thincoder 0.12.62 → 0.12.64

package/src/context.mjs

@@ -1,392 +0,0 @@
-/**
- * context.mjs — Context management and compaction
- * When no measured token count is available, use estimation as fallback (ASCII/4 + non-ASCII/1, no tokenizer dependency).
- * When a measured value exists (response usage.prompt_tokens), trust it — estimation underestimates CJK by 3-4x and relying solely on it may never trigger compaction.
- * Compaction strategy: summarize everything before the tail into one LLM note, keep the latest N messages verbatim.
- * NOTE: no dedicated head is kept (KEEP_HEAD = 0) — in multi-task sessions the earliest messages are
- * typically a COMPLETED earlier task; preserving them verbatim anchored the model's attention on stale
- * work after compaction. The earliest messages now go into the summary (which distinguishes completed
- * vs in-progress work), so the post-compaction context anchors on the current task (recent tail) only.
- */
-
-import { chat } from "./provider/index.mjs"
-import { estimateText } from "./provider/rate.mjs"
-import { providerSpec } from "./config.mjs"
-
-const IMAGE_TOKEN_ESTIMATE = 2000 // rough estimate for image content tokens (CLI legacy 256 underestimated real image costs, delaying compaction)
-
-/** Rough token count for a list of messages (body + reasoning + tool_calls params) */
-export function estimateTokens(messages) {
-  let tokens = 0
-  for (const m of messages) {
-    if (typeof m.content === "string") tokens += estimateText(m.content)
-    else if (Array.isArray(m.content)) {
-      for (const part of m.content) {
-        if (part.type === "text") tokens += estimateText(part.text)
-        else if (part.type === "image_url") tokens += IMAGE_TOKEN_ESTIMATE
-      }
-    }
-    if (typeof m.reasoning_content === "string") tokens += estimateText(m.reasoning_content)
-    for (const tc of m.tool_calls ?? []) {
-      tokens += estimateText(tc.function?.name ?? "") + estimateText(tc.function?.arguments ?? "")
-    }
-  }
-  return tokens
-}
-
-const KEEP_HEAD = 0 // No dedicated head: earliest messages may be a COMPLETED earlier task in multi-task
-// sessions — keeping them verbatim anchored attention on stale work. Everything before the tail is
-// summarized (the summary itself distinguishes completed vs in-progress work; see SUMMARIZE_PROMPT).
-// Tail count formula (D4): window-adaptive (~30 msgs per 100K — old fixed 10 too thin on 1M), capped
-// at 40% of history; §9 D-T1/D-T2 make the count only a CANDIDATE — a token budget (TAIL_BUDGET_FRACTION
-// × window − SUMMARY_TOKEN_ESTIMATE ≈1K, §8) tightens it over pair-safe boundaries when compaction runs,
-// never below TAIL_FLOOR_MESSAGES; ordinary sessions never reach it (D-T4: trigger 0.6 untouched).
-const TAIL_BUDGET_FRACTION = 0.15
-const SUMMARY_TOKEN_ESTIMATE = 1000 // §8: summary output target ~1K tokens — reserved from the 15%
-const TAIL_FLOOR_MESSAGES = 10 // §9 D-T2: the tail keeps ≥10 verbatim messages — floor beats budget
-function keepTailSize(provider, historyLen) {
-  // provider is guaranteed at every call site (runAgent always builds one); providerSpec
-  // degrades to DEFAULT_SPEC (128K) only if provider is somehow absent — acceptable
-  // because the 40% history cap still bounds the tail. providers[].context override
-  // (K units) is honored here (PROVIDER.md §15 T-C2: tail formula follows the window).
-  const ctxWindow = providerSpec(provider).context
-  return Math.min(Math.max(10, Math.floor((ctxWindow / 100_000) * 30)), Math.floor(historyLen * 0.4))
-}
-// §9 D-T1 tail token budget: window×15% − summary ~1K — the compressed history segment (summary + placeholder + tail) lands ≈ 15% (B 口径 §9.5).
-function tailBudgetTokens(provider) {
-  return Math.max(0, Math.floor(providerSpec(provider).context * TAIL_BUDGET_FRACTION) - SUMMARY_TOKEN_ESTIMATE)
-}
-
-export const SUMMARIZE_PROMPT = `You are a conversation compressor. Summarize the following agent work log into a compact summary for use as context in the ongoing conversation.
-Requirements:
-- Write in first person, present tense — these are "my" handover notes, continuing my own train of thought
-- Most important: preserve design decisions and their reasons — architecture choices, API contracts, naming conventions, trade-off rationale. These are the anchors the subsequent code must not deviate from
-- Distinguish COMPLETED vs IN-PROGRESS work: completed tasks get a ONE-LINE recap each (what was done, key outcome); spend the detail budget on unresolved issues, next steps, and the CURRENT task
-- The user's most recent request defines the current task — anchor on it. Earlier requests are likely already completed and only need the one-line recap; do NOT preserve them at full fidelity
-- Explicitly list FILES CHANGED: every modified file path plus a one-line "why" — so post-compaction work can re-locate what was edited and where
-- Explicitly list UNRESOLVED ISSUES / TODOs: anything still open plus the next steps — so post-compaction recovery knows where to resume
-- Drop: pleasantries, repetition, fine-grained tool output details
-- Honestly mark uncertain items: anything not actually verified must say "unverified"; do not present guesses as facts
-- Use bullet-point output. Stay under ~1K tokens (≈1000 Chinese chars / 4000 ASCII chars) — a hard target. An oversized summary wastes window and dilutes the tail; the old unbounded-length guidance is deprecated. When over budget, trim in this order: completed recaps to one line; FILES CHANGED why-notes to bare paths; in-progress prose tightened. NEVER cut design anchors or UNRESOLVED ISSUES/TODOs — recovery depends on them.
-
-Work log:
-`
-
-/** Context prefix after compaction, informing the agent what happened */
-const COMPACTION_PREFIX =
-  "[Context was automatically compacted. Below is a summary of earlier work. " +
-  "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"
-
-/** 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
-
-/** Task re-injection reminder prefix (after compaction, clear old versions from history first for a single source of truth) */
-const TASK_REINJECT_PREFIX = "[System reminder: your current task list after compaction:"
-
-/** Truncation fallback note (used when the summary LLM fails repeatedly; no LLM call) */
-const FALLBACK_NOTE =
-  "[Context was truncated after repeated summarization failures. " +
-  "The middle portion of earlier work was dropped WITHOUT a summary. " +
-  "Re-verify any state you need with tools before relying on it.]\n\n"
-
-/**
- * Split history into head / middle (to be summarized) / tail; return null if no middle to compress.
- * head is normally empty (KEEP_HEAD = 0 — earliest messages go into the summary); the tool_calls-extension logic below is defensive for future KEEP_HEAD > 0.
- * The tail boundary must include any assistant whose tool results are in the tail — if the assistant is in the middle, the summary swallows it, leaving orphan tool results → protocol 400.
- * `budgetTokens` (optional, §9 D-T1): when the candidate's estimate exceeds it, the boundary moves
- * forward until the tail fits — never below the D-T2 floor (10 msgs, or the candidate itself when
- * the 40% cap made it < 10 — short history).
- */
-function splitHistory(history, keepTail, budgetTokens = null) {
-  if (history.length <= KEEP_HEAD + keepTail + 1) return null
-  let headEnd = KEEP_HEAD
-  // head must not end with dangling tool_calls: when assistant declares tool_calls, all its tool results must stay in head.
-  // Parallel calls: one assistant followed by multiple tool messages — accepting only one still causes 400, must collect all
-  if (history[headEnd - 1]?.role === "assistant" && history[headEnd - 1].tool_calls?.length) {
-    while (headEnd < history.length && history[headEnd].role === "tool") headEnd++
-  }
-  const candidate = repairedTailStart(history, headEnd, history.length - keepTail)
-  if (candidate <= headEnd) return null
-  let tailStart = candidate
-  // §9 D-T1: tighten only above the floor — a candidate ≤ 10 IS the floor (short history under the 40% cap must not tighten further, review #5); the floor is D5-repaired too.
-  if (budgetTokens > 0 && keepTail > TAIL_FLOOR_MESSAGES) {
-    const floor = repairedTailStart(history, headEnd, history.length - TAIL_FLOOR_MESSAGES)
-    if (floor > candidate) tailStart = tightenTailByBudget(history, candidate, floor, budgetTokens)
-  }
-  return { headEnd, tailStart }
-}
-
-/**
- * D5 tail-side pairing repair for a raw cut at history.length − tailCount: pull into the tail any
- * assistant whose tool results are in the tail (the summary swallowing the owner leaves orphan tool
- * results → protocol 400), then skip orphan tool messages at the new boundary. Single-assistant
- * assumption (nearest owner only — a tail spans at most one assistant→tools cycle); bounds-guarded.
- */
-function repairedTailStart(history, headEnd, tailStart) {
-  const tailToolIds = new Set()
-  for (let i = tailStart; i < history.length; i++) {
-    if (history[i].role === "tool") tailToolIds.add(history[i].tool_call_id)
-  }
-  for (let i = tailStart - 1; i > headEnd; i--) {
-    const m = history[i]
-    if (m.role === "assistant" && m.tool_calls?.some((tc) => tailToolIds.has(tc.id))) {
-      tailStart = i
-      break
-    }
-  }
-  while (tailStart < history.length && tailStart > headEnd && history[tailStart].role === "tool") {
-    tailStart++
-  }
-  return tailStart
-}
-
-/**
- * §9 D-T1 budget tightening (pair-safe, review #2): walk the boundary FORWARD (fewer tail messages —
- * the rest joins the summary) while the tail's estimated tokens exceed the budget. Only pair-safe
- * positions may stop the walk: a boundary ON a tool message would orphan its owner assistant into the
- * middle (D5); pairing is contiguous in the machine line (§6 note) — every non-tool boundary is safe.
- * No fit before the floor → keep the floor, accept the overrun.
- */
-function tightenTailByBudget(history, start, floorStart, budgetTokens) {
-  const suffixTokens = new Array(history.length + 1)
-  suffixTokens[history.length] = 0
-  for (let i = history.length - 1; i >= 0; i--) suffixTokens[i] = suffixTokens[i + 1] + estimateTokens([history[i]])
-  if (suffixTokens[start] <= budgetTokens) return start // already fits — ordinary sessions stay untouched (D-T2)
-  for (let p = start + 1; p <= floorStart; p++) { // first fit keeps the most recent verbatim context
-    if (history[p].role !== "tool" && suffixTokens[p] <= budgetTokens) return p
-  }
-  return floorStart
-}
-
-/**
- * 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 §9 D-S1): 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 §14.3.5）——人读线内存有界 + 磁盘为准：
- *   ① `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)
-}
-
-/** 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),
-  // so compaction only shrinks the machine line — nothing to preserve here.
-  // head is normally empty (KEEP_HEAD = 0) — the summary note becomes the first message,
-  // which is exactly the intent: post-compaction context anchors on the current task, not on
-  // possibly-completed earlier requests.
-  const head = agent.history.slice(0, headEnd)
-  const tail = agent.history.slice(tailStart)
-  // SESSION.md §9 D-S1: compaction-injected messages (note + "Understood") carry a ts —
-  // Date.now() at the compaction moment. They are machine-only (never in _fullHistory),
-  // but the machine-line timeline stays consistent for any audit use.
-  const now = Date.now()
-  agent.history = [
-    ...head,
-    { role: "user", content: note, ts: now },
-    { role: "assistant", content: "Understood. I'll continue from these notes, re-verifying anything transient.", ts: now },
-    ...tail,
-  ]
-  // Compaction REBUILDS the machine line (head + note + "Understood" + tail), so the pre-compaction
-  // _runStartHistoryLen index is stale — a longer array shrank beneath it, and end-of-run exploration
-  // distillation would then silently skip or slice from the wrong offset. Reset the boundary to the
-  // verbatim tail start (head.length + 2: the note and the "Understood" placeholder sit between head
-  // and tail). Exploration before the tail was already covered by the compaction summary, so only the
-  // still-raw tail needs distilling. `head` is empty today (KEEP_HEAD = 0) — the formula stays
-  // correct if KEEP_HEAD ever grows. (shrinkOversized only truncates message bodies in place and
-  // leaves the array length unchanged, so this boundary stays valid there — no reset needed.)
-  agent._runStartHistoryLen = head.length + 2
-  // Measured token baseline is invalidated along with old history (prompt_tokens were for pre-compaction context), fall back to estimation until next response
-  agent._lastPromptTokens = null
-  agent._usageAtLen = null
-
-  // After compaction, re-inject the task list (the agent needs to know what it was doing).
-  // Single source of truth: first remove any stale re-injections from the tail, then inject the latest version —
-  // no longer embedded in the summary body (would duplicate and grow stale)
-  agent.history = agent.history.filter(
-    (m) => !(m.role === "user" && typeof m.content === "string" && m.content.startsWith(TASK_REINJECT_PREFIX))
-  )
-  if (agent.tasks.length > 0) {
-    const taskSummary = agent.tasks.map((t) => `- [${t.status}] ${t.title}`).join("\n")
-    agent.history.push({
-      role: "user",
-      content: `${TASK_REINJECT_PREFIX}\n${taskSummary}\nContinue from where you left off.]`,
-    })
-  }
-
-  // Plan mode compaction: re-inject plan mode guidance
-  if (agent.planMode) {
-    agent.history.push({
-      role: "user",
-      content: "[System reminder: plan mode is active. Explore the codebase read-only, design your solution, then call plan with action='exit' to present it for user approval.]",
-    })
-  }
-}
-
-/**
- * If history exceeds threshold, compact it. Returns whether compaction happened.
- * Only called at safe points in the loop (history ends with user or tool message — a complete exchange boundary).
- * Automatically re-injects task list state after compaction.
- * @param {object} agent
- * @param {number} threshold - compaction threshold in tokens
- * @param {object} callbacks - { onToken, onReasoning, onCompress, onCompressStart } — summary
- *   generation is SILENT (never forwards onToken/onReasoning: the compaction process is an
- *   internal mechanism, not a model reply); onCompressStart fires right before the summary call
- *   (§7 D-C1, compression lifecycle visibility — panel start state)
- * @param {object} extras - { systemPrompt?, tools? } — estimated overhead for the pure-estimation
- *   path (no measured baseline); the measured path already includes system+tools in prompt_tokens.
- */
-export async function compressIfNeeded(agent, threshold, callbacks, extras = {}, signal) {
-  const history = agent.history
-  // Prefer the real baseline: the last response's prompt_tokens is the measured value for the full context (system+tools+history).
-  // Subsequent appended messages use estimation as increment; when no measured value exists (first turn / after restore / right after compaction), fall back to pure estimation
-  const overhead =
-    (extras.systemPrompt ? estimateText(extras.systemPrompt) : 0) +
-    (extras.tools ? estimateText(JSON.stringify(extras.tools)) : 0)
-  const tokens =
-    agent._lastPromptTokens != null
-      ? agent._lastPromptTokens + estimateTokens(history.slice(agent._usageAtLen ?? history.length))
-      : estimateTokens(history) + overhead
-  if (tokens <= threshold) return false
-
-  const keepTail = keepTailSize(agent.provider, history.length)
-  const split = splitHistory(history, keepTail, tailBudgetTokens(agent.provider))
-  if (!split) {
-    // History is too short (≤KEEP_HEAD+keepTail+1 messages) to find a middle section, but tokens exceed threshold — typically a single giant message
-    // (large paste / huge injection). When summarization has no room, degrade to deterministic shrinking to ensure context always reduces
-    return shrinkOversized(agent)
-  }
-
-  const middle = history.slice(split.headEnd, split.tailStart)
-  const serialized = middle
-    .map((m) => {
-      const toolNote = m.tool_calls ? ` [called tools: ${m.tool_calls.map((t) => t.function?.name).join(", ")}]` : ""
-      // user messages get a wider cap (8000): cutting off a long user-pasted requirement loses original intent; tool/assistant capped at 2000 is enough
-      const cap = m.role === "user" ? 8000 : 2000
-      // Multimodal messages (array content): extract the TEXT parts — the image itself can't be
-      // summarized, but any accompanying text (e.g. "看这张图" + image) must not be silently lost
-      let text = ""
-      if (typeof m.content === "string") text = m.content
-      else if (Array.isArray(m.content)) text = m.content.filter((p) => p?.type === "text").map((p) => p.text ?? "").join(" ")
-      return `[${m.role}]${toolNote} ${text.slice(0, cap)}`
-    })
-    .join("\n")
-
-  // The summary is a plain-text task, no reasoning needed — passing thinking to the compaction provider wastes tokens.
-  // Silent by design (D11): no onToken/onReasoning — the compaction process must not stream to the frontend.
-  // signal propagates user cancellation (Ctrl+C) to the in-flight summary call.
-  // Compression visibility (CONTEXT-COMPACTION.md §7 D-C1/D-C2): the frontend learns the compression
-  // STARTED right before the summary LLM call ("Compressing context… / summarizing N messages" panel) — only
-  // the lifecycle is surfaced, never the summary body. N = the number of history messages being summarized.
-  callbacks?.onCompressStart?.({ messages: middle.length })
-  const startedAt = performance.now()
-  const summary = await chat({ ...agent.provider, thinking: null, reasoningEffort: null }, {
-    messages: [{ role: "user", content: SUMMARIZE_PROMPT + serialized }],
-    signal,
-    // §18.6 D-TR4：轨迹元数据增补——kind=compress（上下文构建面——agent 元数据透出；
-    // depth 经 extras.traceDepth——agent.mjs 主作用域传入——compress 调用点补齐）
-    logCtx: {
-      stage: "compress", child: agent._logId, kind: "compress",
-      role: agent._role ?? null, depth: extras?.traceDepth ?? null,
-      session: agent._sessionStart ?? null, cwd: agent.cwd,
-      traces: agent.config?.traces?.enabled !== false,
-    },
-  })
-
-  applyCompression(agent, split.headEnd, split.tailStart, COMPACTION_PREFIX + summary.content)
-
-  // Completion info for the compression panel (D-C2): tokens freed = the pre-compression prompt
-  // estimate (`tokens` — the value that tripped the threshold, incl. system/tools overhead on the
-  // pure-estimation path) minus the post-compression estimate on the same basis. Elapsed = the
-  // summary call + splice duration. agent.mjs forwards this to onCompress unchanged.
-  agent._lastCompressInfo = {
-    mode: "summary",
-    tokensFreed: Math.max(0, Math.round(tokens - (estimateTokens(agent.history) + overhead))),
-    elapsedMs: performance.now() - startedAt,
-  }
-  return true
-}
-
-/**
- * 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.
- */
-export function compressFallback(agent) {
-  const keepTail = keepTailSize(agent.provider, agent.history.length)
-  const split = splitHistory(agent.history, keepTail, tailBudgetTokens(agent.provider))
-  if (!split) return false
-  const tailMessages = agent.history.length - split.tailStart
-  applyCompression(agent, split.headEnd, split.tailStart, FALLBACK_NOTE)
-  // Fallback completion info (D-C2): mode marks the deterministic-truncation path — the panel
-  // shows the degradation note ("truncated to N messages") ONLY after 3 consecutive failures.
-  agent._lastCompressInfo = { mode: "fallback", tailMessages }
-  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.
- * 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
-}
-
-// ─── 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））───────────────────────
-
-export { summarizeRunExplorations, EXPLORE_TOOLS, EXPLORE_SUMMARY_PROMPT } from "./explore-distill.mjs"

package/src/conventions.mjs

@@ -1,223 +0,0 @@
-/**
- * conventions.mjs — the single authority for code / doc / temp path classification,
- * plus the project convention declaration surface (`.thincoder/conventions.json`).
- *
- * Why one module: engineering-mode 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.
- *
- * 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).
- *
- * 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.
- */
-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"]
-
-/** Project declaration file, relative to the project root. */
-export const CONVENTIONS_REL_PATH = ".thincoder/conventions.json"
-
-/** 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
-
-/** Temp/scratch predicate (moved here verbatim from advisor/repos.mjs). */
-const TEMP_FILE = /(?:^|[/\\])tmp-[^/\\]+$|\.(?:tmp|temp)$/i
-
-/** True when a path is a throwaway temp file (tmp-* name or .tmp/.temp extension). */
-export function isTempPath(p) {
-  return TEMP_FILE.test(p ?? "")
-}
-
-/** Path → segments (both separators accepted; absolute and relative alike). */
-function segmentsOf(p) {
-  return String(p ?? "").replace(/\\/g, "/").split("/").filter(Boolean)
-}
-
-/**
- * True when the path contains a declared code segment sequence 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.
- */
-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())
-    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
-    }
-  }
-  return false
-}
-
-/** "code" | "doc" | "temp" — 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). */
-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"
-  return "code"
-}
-
-/** True when the path is product code (see classifyPath for the precedence). */
-export function isCodePath(p, conv) {
-  return classifyPath(p, conv) === "code"
-}
-
-/** True when the path is a documentation file — a doc extension that does NOT
- *  live inside a declared code segment (src/prompts/*.md is product code). */
-export function isDocPath(p, conv) {
-  const s = String(p ?? "")
-  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
-}
-
-/** 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
-}