@thincoder/core 0.10.6 → 0.10.7

package/CHANGELOG.md

@@ -3,6 +3,15 @@
 All notable changes to the core package are documented here.
 Format: Keep a Changelog · 中文 · 号在发布时定（CalVer——见 `docs/RELEASE.md` §4）。
 
+## [0.10.7] — 2026-10-14
+
+> 0.10.6 → 0.10.7（月内 +1——发布时定号）
+
+### Added
+
+- **批次档不入文档索引（#1366）**：`docs/batches/**` 无条件默认排除（用户 19:03「不管 manifest 里配置没配置排除路径，都把批次档目录排除掉」）；读面准入过滤同拍。
+- **索引范围声明化（#1367）**：只索引 manifest 声明目录 ∪ 一级子目录（用户 19:25「只索引 manifest 指定的目录……还要考虑一级子目录下的 manifest」）；结构门替换开放式排除；manifest 写 ⇒ 范围缓存失效。
+
 ## [0.10.6] — 2026-10-13
 
 > 0.10.5 → 0.10.6（月内 +1——发布时定号；P0 热修）

package/agent-tools/manifest.mjs

@@ -27,11 +27,16 @@
  *
  * 报告面随动（KD-M1-40）：本工具**不写** `agent.manifest`（第二值源否——工具目标可为非锚项目）——
  * 写盘 = 盘面变化，情境行经既有 ③b mtime 门控于下回合采纳（`agent/setup-reminders.mjs`）。
+ *
+ * 缓存失效（#1367 面⑦）：写档成功（init ∥ write——全部成功路径）⇒ `clearDeclarationCache()`——
+ * 「补档即回归」进程内即时（声明 ∥ 范围缓存同清）；失败路径不清（盘零变 ⇒ 缓存照旧）；
+ * 手工改档 ⇒ 重启生效（零文件侦听）。
  */
 import { existsSync } from "node:fs"
 import { join, resolve } from "node:path"
 import { MANIFEST_REL, MANIFEST_SCHEMA, initManifest, projectRootView, projectView, readManifest, writeManifest } from "../manifest.mjs"
 import { DESC } from "../tools/shared.mjs"
+import { clearDeclarationCache } from "../conventions.mjs" // #1367 面⑦：写档成功 ⇒ 缓存失效（fix 轮接线）
 
 /** 拒面统一前缀（设计 §2.10：`manifest <action>: refused — …`）——盘零变类拒绝一律经此抛错。 */
 function refuse(action, reason) {
@@ -150,6 +155,7 @@ export const manifestTool = {
       } catch (e) {
         throw refuse("init", `could not write the default manifest at ${file} — ${e?.message ?? String(e)}`)
       }
+      clearDeclarationCache() // 写成功：补档 ⇒ 范围即回归（进程内——失败路径不清）
       return `manifest init: created default manifest (DEFAULT_MANIFEST)\npath=${file}`
     }
 
@@ -188,6 +194,7 @@ export const manifestTool = {
     } catch (e) {
       throw refuse("write", `the edited manifest fails the pre-write validation (disk unchanged) — ${e?.message ?? String(e)}`)
     }
+    clearDeclarationCache() // 写成功：声明 ∥ 范围逐字随动（进程内——失败路径不清）
     return `manifest write: set ${key} = ${JSON.stringify(value)}\npath=${file}`
   },
 }

package/conventions.mjs

@@ -189,4 +189,4 @@ export function isStatePath(p, conv) {
 // 迁出面（2026-10-01 拆分批 · #755 ∥ #786）：声明装载面外提 `declaration.mjs`——本档经
 // 转口保名（消费面 / 单元测试档 import 面零改；`DEFAULT_DECLARATION` 另供本档分类裁判缺省取用）。
 // ─────────────────────────────────────────────────────────────────────────────
-export { loadProjectDeclaration, declarationForTarget, DEFAULT_DECLARATION, isExcludedRelPath, declaredPublicRoots, clearDeclarationCache } from "./declaration.mjs"
+export { loadProjectDeclaration, declarationForTarget, DEFAULT_DECLARATION, isExcludedRelPath, declaredIndexScope, isInDeclaredScope, declaredPublicRoots, clearDeclarationCache } from "./declaration.mjs"

package/declaration.mjs

@@ -5,9 +5,10 @@
  * name / shape / defaults = schema 面 `docs/core/design/MANIFEST.md` §2.2）。迁出块逐字；
  * 原档 `conventions.mjs` 经 `export { … } from` 转口保名（消费面 / 单元测试档 import 面零改）。
  */
-import { existsSync, statSync } from "node:fs"
+import { existsSync, readdirSync, statSync } from "node:fs"
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path"
-import { DEFAULT_MANIFEST, manifestFilePath, owningProject, readManifest } from "./manifest.mjs"
+import { DEFAULT_MANIFEST, MANIFEST_REL, docRootPaths, manifestFilePath, owningProject, readManifest } from "./manifest.mjs"
+import { isSkippedRelPath } from "./memory/file-walk.mjs" // 面⑦ 子目录扫描的跳过段谓词单源（零环：file-walk 不引本档）
 import { logEvent } from "./log.mjs"
 
 /** Retired declaration carrier (project-root relative). Its EXISTENCE is checked, its
@@ -78,6 +79,7 @@ function buildDeclaration(m, root = null) {
   const docExtensions = normalizeExtensions(m?.index?.docExtensions)
   const excludePaths = normalizePathList(m?.index?.excludePaths)
   const publicRepos = normalizePathList(m?.index?.publicRepos)
+  const batchRecords = batchSegments(m?.docRoot?.batches) // §6.14 面⑥ 声明值投影（`declared` 旗不涉——docRoot 族现状零改）
   const docMap = normalizeString(m?.advisor?.docMap)
   const standardsDoc = normalizeString(m?.advisor?.standardsDoc)
   const defaults = normalizeCodePaths(DEFAULT_MANIFEST.codePaths) ?? []
@@ -86,6 +88,7 @@ function buildDeclaration(m, root = null) {
   return Object.freeze({
     declared,
     codePaths: Object.freeze(codePaths),
+    batchRecords: Object.freeze(batchRecords.map((s) => Object.freeze(s))),
     index: Object.freeze({
       codeExtensions: Object.freeze(codeExtensions),
       docExtensions: Object.freeze(docExtensions),
@@ -101,25 +104,158 @@ function buildDeclaration(m, root = null) {
  *  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（零行为变化）。
+/** 段序列归一（面⑥ 目标集）：值（串 ∥ 串数组——元素层归一同 `normalizePathList`）⇒ 实义段序列
+ *  （空 ∥ `.` ∥ `..` 段剔除——空序列另剔，防恒真；去重保序）。 */
+function batchSegments(v) {
+  const out = []
+  for (const e of normalizePathList(Array.isArray(v) ? v : v == null ? [] : [v])) {
+    const segs = e.split("/").filter((s) => s && s !== "." && s !== "..")
+    if (segs.length && !out.some((q) => q.length === segs.length && q.every((s, i) => s === segs[i]))) out.push(segs)
+  }
+  return out
+}
+
+/** 约定段（面⑥——`DEFAULT_MANIFEST.docRoot.batches` 单源派生；默认值改名/迁移两处同动）。 */
+const DEFAULT_BATCH_SEGMENTS = batchSegments(DEFAULT_MANIFEST.docRoot.batches)
+
+/** 排除谓词（单源——§6.14 面① 前缀 ∥ 面⑥ 批次档段序列；两族同一谓词全判，非第二判定面）：
+ *  面⑥（2026-10-13 · 台账 #1366 · **无条件**——不看 `index.excludePaths` 是否配置）：`rel` 命中
+ *  约定段 ∪ 声明值段序列（`decl.batchRecords`——`docRoot.batches` 投影）于**路径任意深度**
+ *  （段边界 = 整段一致——`docs/batchesx` ∥ `doc/batches` 判假）⇒ true；`docRoot.batches: null`
+ *  ⇒ 约定段恒在（无逃生口）；`decl` 缺 ⇒ 约定段照判。
+ *  面①（前缀语义）：`rel`（**`base` 相对**——缺省视为根相对）命中声明前缀（恰等 ∨ 后随 `/`——
+ *  `openclaw` 不吞 `openclaw-fork`）⇒ true；缺省 `[]` ⇒ 恒 false（零行为变化）。
  *  `base`（调用面 cwd/origin·#700）= `rel` 的相对基：`resolve` + `relative` 换算至 `decl.root` 根面
- *  再比前缀（cwd = 项目根时与既有行为逐字等义）；换算越出根面（`..` 头 ∥ 根外绝对形）⇒ **不命中**
- *  （保守不排除——沉默洞方向收窄，与 D17 aux 面「indeterminate ⇒ 不匹配」同向）；`decl.root` 缺
- *  ⇒ `rel` 原样（根起步调用面等义）。 */
+ *  再判（cwd = 项目根时与既有行为逐字等义）；换算越出根面（`..` 头 ∥ 根外绝对形）⇒ 面① **不命中**
+ *  （保守不排除——沉默洞方向收窄，与 D17 aux 面「indeterminate ⇒ 不匹配」同向）∥ 面⑥ 按入参
+ *  **原样 `rel`** 判（段序列面不回退——面① 不命中口径逐字零改）；`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
+  let inRoot = true
   if (base != null && root) {
     const converted = relative(root, resolve(base, s)).replace(/\\/g, "/")
-    if (converted === ".." || converted.startsWith("../") || isAbsolute(converted)) return false
-    s = converted
+    if (converted === ".." || converted.startsWith("../") || isAbsolute(converted)) inRoot = false
+    else s = converted
   }
+  // 面⑥ 段序列（约定段 ∪ 声明值——任意深度连续命中）；越根（`inRoot=false`）⇒ `s` 即原样 rel
+  const segs = s.split("/").filter(Boolean)
+  if ([...DEFAULT_BATCH_SEGMENTS, ...(decl?.batchRecords ?? [])].some((seq) => segs.some((_, i) => seq.every((q, j) => segs[i + j] === q)))) return true
+  // 面① 前缀（既有口径逐字零改：缺省 `[]` ∥ 越根 ⇒ 不命中）
+  const list = decl?.index?.excludePaths
+  if (!Array.isArray(list) || list.length === 0 || !inRoot) return false
   return list.some((p) => p && (s === p || s.startsWith(`${p}/`)))
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// §6.14 面⑦ 索引范围声明化（结构门——2026-10-13 · 台账 #1367）：范围 = 锚的**管辖 manifest**
+// 声明目录 ∪ **一级子目录**（带档者）声明目录——「未声明 ⇒ 不进」；条目集空 ⇒ 零索引
+// （不回落全树）。键面 = `docRoot.*`（五子键合并）∪ `codePaths`——两键各按自身既有语义
+// （本规 = 新增消费点，键值语义零改）。写面（收录）∥ 读面（存量行准入）共用本谓词族。
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** 文档面前缀集合（条目根相对——`docRoot.*` 五子键合并展开；解析单源 = `docRootPaths`，F7）：
+ *  值 = 根相对字面前缀（恰等 ∨ 后随 `/`——路径及子树；文件值如 `docs/RELEASE.md` ⇒ 恰该文件）；
+ *  `"."` = 该条目根自身（整根面）；越根值（`../` 形）剔除——条目子树内的文件永不可命中它。
+ *  去重保序。 */
+function entryDocPaths(docRoot, root) {
+  const out = []
+  if (docRoot === null || typeof docRoot !== "object" || Array.isArray(docRoot)) return out
+  for (const key of Object.keys(DEFAULT_MANIFEST.docRoot)) {
+    for (const abs of docRootPaths(docRoot[key], root)) {
+      const rel = relative(root, abs).replace(/\\/g, "/")
+      if (rel === "" || rel === ".") { if (!out.includes(".")) out.push("."); continue }
+      if (rel === ".." || rel.startsWith("../") || isAbsolute(rel)) continue
+      if (!out.includes(rel)) out.push(rel)
+    }
+  }
+  return out
+}
+
+/** 段序列任意深度连续命中（面⑦ 代码面——大小写不敏感 = 既有键语义口径，同 `conventions.mjs`
+ *  `hasSequenceIn`）；`face` = 已小写化的根相对段表。 */
+function hasSegmentRun(face, seq) {
+  const want = String(seq).replace(/\\/g, "/").split("/").filter(Boolean).map((s) => s.toLowerCase())
+  if (want.length === 0) return false
+  for (let i = 0; i + want.length <= face.length; i++) {
+    if (want.every((w, j) => face[i + j] === w)) return true
+  }
+  return false
+}
+
+/** 面⑦ 一条目（`root` = 仓根绝对路径；档在场 = 调用面已判）：`docPaths` = 根相对字面前缀 ∥
+ *  `codePaths` = 段名数组（既有归一单源 = `loadProjectDeclaration`——`[]` = 无段面）。档**非法**
+ *  （坏 JSON ∥ 形态错）⇒ 两族按默认值参与 + 既有可见告警（声明链 KD-M1-32——`loadProjectDeclaration`
+ *  的降级告警单源，本档零第二实现）——不静默成零。 */
+function scopeEntryOf(root) {
+  const decl = loadProjectDeclaration(root)
+  const r = readManifest(root)
+  const docRoot = r.ok ? r.manifest.docRoot : DEFAULT_MANIFEST.docRoot // 档在场才补默认（无档 = 无条目，不走本函数）
+  return Object.freeze({
+    root,
+    docPaths: Object.freeze(entryDocPaths(docRoot, root)),
+    codePaths: Object.freeze([...decl.codePaths]),
+  })
+}
+
+/**
+ * §6.14 面⑦ 范围求并（结构门——单源）：① `dir` 的**管辖 manifest**（`manifestFilePath(dir)` 同一根
+ * 解析——最近祖先带档 ∥ 发现兜底；**可高于 `dir`** ⇒ 深 cwd 等义）在场 ⇒ 锚条目（`root` = 档所在
+ * 目录）；② `dir` 的**直接子目录**（非跳过段——点段 ∥ 内建名单，防 `.thincoder/tmp` 类伪档）根下带档
+ *  者 ⇒ 各一条目（`root` = 该子目录）。**一层、纯向下、绝不向上**（发现纪律在案）。
+ *  冻结条目数组（按根去重保序）；条目集空 ⇒ 范围空 ⇒ **零索引**（不回落全树）。
+ *  缓存按 `dir` 归一绝对路径（`clearDeclarationCache()` 同清——测试缝单点）。
+ * @param {string} [dir] 会话锚 ∕ 同步根（项目内子目录 ⇒ 管辖 manifest 生效）
+ * @returns {ReadonlyArray<{root: string, docPaths: readonly string[], codePaths: readonly string[]}>}
+ */
+export function declaredIndexScope(dir) {
+  const key = resolve(dir ?? ".")
+  const hit = _scopeCache.get(key)
+  if (hit) return hit
+  const roots = []
+  const anchorFile = manifestFilePath(key) // 数据档路径单源（KD-M1-18）
+  if (existsSync(anchorFile)) roots.push(dirname(anchorFile))
+  let names = []
+  try { names = readdirSync(key, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort() } catch { /* 不可读 ⇒ 零子条目（不抛——同发现梯内核） */ }
+  for (const name of names) {
+    if (isSkippedRelPath(name)) continue
+    const child = join(key, name)
+    if (!existsSync(join(child, MANIFEST_REL)) || roots.includes(child)) continue // 发现兜底命中的子目录 = 锚条目同根 ⇒ 去重
+    roots.push(child)
+  }
+  const scope = Object.freeze(roots.map(scopeEntryOf))
+  _scopeCache.set(key, scope)
+  return scope
+}
+
+/**
+ * §6.14 面⑦ 范围谓词（纯谓词——单一实现，写面 ∥ 读面共用）：`rel`（`base` 相对；缺省按进程 cwd
+ * 解析）经 `resolve` 绝对化 ⇒ 逐条目判归属（`abs` ∈ `root` 子树；无归属条目 = **未声明**）⇒ 两面试
+ * 任一命中即入范围（两层锚条目间 = 并集）：
+ *   · **文档面** = 条目根相对面**字面前缀**（恰等 ∨ 后随 `/`；`"."` = 整根）；
+ *   · **代码面** = 段序列**任意深度**命中（大小写不敏感）。
+ * 不在任何条目子树内（越根）⇒ 不命中。`scope` 空 ∥ 缺 ⇒ false（零索引面——未声明 ⇒ 不进）。
+ * @param {string} rel 路径（`base` 相对）
+ * @param {ReadonlyArray<object>} scope `declaredIndexScope()` 回执
+ * @param {string|null} [base] `rel` 的相对基（目录绝对路径；缺省 = 进程 cwd）
+ * @returns {boolean}
+ */
+export function isInDeclaredScope(rel, scope, base = null) {
+  if (!Array.isArray(scope) || scope.length === 0) return false
+  const abs = resolve(base ?? ".", String(rel ?? "").replace(/\\/g, "/"))
+  for (const entry of scope) {
+    const relFromRoot = relative(entry.root, abs).replace(/\\/g, "/")
+    if (relFromRoot === "" || relFromRoot === ".." || relFromRoot.startsWith("../") || isAbsolute(relFromRoot)) continue
+    if (entry.docPaths.some((p) => p === "." || relFromRoot === p || relFromRoot.startsWith(`${p}/`))) return true
+    if (entry.codePaths.length > 0) {
+      const face = relFromRoot.split("/").filter(Boolean).map((s) => s.toLowerCase())
+      if (entry.codePaths.some((seq) => hasSegmentRun(face, seq))) return true
+    }
+  }
+  return false
+}
+
 /**
  * 声明公共仓**绝对根集**（§6.15 解析层——检索同步 ∥ 读面 origin 集 ∥ 引用解析三消费面共用的单一定义，
  * 不得二写）：值形层逐项 `resolve(decl.root, p)` ⇒ 绝对根集（去重保序）；存在性判归消费面（本层不判）。
@@ -165,10 +301,14 @@ export function resolveDeclaredRef(base, part) {
 const isFile = (p) => { try { return statSync(p).isFile() } catch { return false } }
 
 const _cache = new Map()
+/** 面⑦ 范围缓存（按 `dir` 归一绝对路径——子目录档 ∥ 声明变更后经本缝同清）。 */
+const _scopeCache = new Map()
 
-/** Drop the per-data-file-path cache (test seam — declarations are read once per path). */
+/** Drop the per-data-file-path cache (test seam — declarations are read once per path).
+ *  #1367：面⑦ 范围缓存同清（「声明 ∥ 一级子目录档」变更后同一条测试缝）。 */
 export function clearDeclarationCache() {
   _cache.clear()
+  _scopeCache.clear()
 }
 
 /** Retired-carrier warning (existence check only — zero content parsing, zero fallback). */
@@ -188,7 +328,7 @@ function warnRetiredCarrier(root) {
  * 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[],
+ * @returns {Readonly<{declared: boolean, codePaths: readonly string[], batchRecords: readonly (readonly string[])[],
  *   index: {codeExtensions: string[], docExtensions: string[], excludePaths: string[], publicRepos: string[]},
  *   advisor: {docMap: string, standardsDoc: string}, root: string|null}>}
  */

package/memory/code-search.mjs

@@ -8,7 +8,7 @@
 import { embed, embedTolerant, cosine, toBlob, fromBlob } from "../embedding.mjs"
 import { scanVectors, createTopK } from "./scan.mjs"
 import { normalizeOrigin } from "./origin.mjs"
-import { declaredPublicRoots } from "../conventions.mjs"
+import { declaredPublicRoots, loadProjectDeclaration, isExcludedRelPath, declaredIndexScope, isInDeclaredScope } from "../conventions.mjs"
 import { buildFtsQuery, ensureEmbeddings, EMBED_TEXT_MAX_LEN } from "./core.mjs"
 import { safeSliceUTF16 } from "../text-budget.mjs"
 import { DESC } from "../tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/code_search.md
@@ -35,13 +35,28 @@ export async function codeSearch(memory, query, { limit = 5 } = {}) {
   const origins = searchOrigins(memory)
   const ftsOriginFilter = origins.length === 1 ? `AND c.origin = ?` : origins.length > 1 ? `AND c.origin IN (${origins.map(() => "?").join(", ")})` : ""
   const originParams = origins
+  // §6.14 读面准入过滤（FTS 列表建成后 ∥ 向量 top-K push 前；两判据并列互不吞）：排除谓词（面①∪面⑥，
+  // 行 origin 为 `base`）∪ 声明范围门（面⑦——`isInDeclaredScope(path, declaredIndexScope(origin), origin)`，
+  // 逐 origin 预载一次）⇒「批次档 ∥ 范围外路径从未入索引」等价检索；存量行不删（收尾保护位）；窗口欠额接受。
+  const declCache = new Map()
+  const scopeCache = new Map()
+  const rowHidden = (origin, path) => {
+    const d = declCache.get(origin) ?? loadProjectDeclaration(origin)
+    declCache.set(origin, d)
+    if (isExcludedRelPath(path, d, origin)) return true
+    let scope = scopeCache.get(origin)
+    if (scope === undefined) { scope = declaredIndexScope(origin); scopeCache.set(origin, scope) }
+    return !isInDeclaredScope(path, scope, origin)
+  }
+  const ftsNeedOrigin = origins.length !== 1 // 单 origin 形 SQL 零改；多 origin ∥ 无过滤形补 `origin` 列（行 origin 随行可得）
 
   const ftsList = ftsQuery ? memory.db.prepare(`
-    SELECT c.rowid, c.path, c.language, c.symbol_name, c.content, c.line_start, c.line_end, bm25(code_chunks_fts) AS rank
+    SELECT c.rowid, c.path, c.language, c.symbol_name, c.content, c.line_start, c.line_end, bm25(code_chunks_fts) AS rank${ftsNeedOrigin ? ", c.origin" : ""}
     FROM code_chunks_fts JOIN code_chunks c ON c.rowid = code_chunks_fts.rowid
     WHERE code_chunks_fts MATCH ? ${ftsOriginFilter}
     ORDER BY rank LIMIT ?
-  `).all(ftsQuery, ...originParams, Math.max(limit * 4, 20)) : []
+  `).all(ftsQuery, ...originParams, Math.max(limit * 4, 20))
+    .filter((r) => !rowHidden(origins.length === 1 ? origins[0] : r.origin, r.path)) : []
 
   if (!memory.embedder) return ftsList.slice(0, limit)
 
@@ -70,7 +85,9 @@ export async function codeSearch(memory, query, { limit = 5 } = {}) {
   for (const origin of origins.length ? origins : [null]) {
     await scanVectors(memory.db, vecSql, origin ? [origin] : [], {
       cursorKey,
-      onRow: (r) => top.push({ id: r.rowid, rowid: r.rowid, score: cosine(qvec, fromBlob(r.embedding)) }),
+      onRow: (r) => { // §6.14 面⑥∪面⑦ 准入（top-K push 前；无过滤形行 origin = 游标键 `origin` 列）
+        if (!rowHidden(origin ?? r.origin, r.path)) top.push({ id: r.rowid, rowid: r.rowid, score: cosine(qvec, fromBlob(r.embedding)) })
+      },
     })
   }
   const vecList = top.list().map((c) => ({ rowid: c.id, score: c.score }))

package/memory/code-sync.mjs

@@ -11,7 +11,7 @@ import { ensureEmbeddings, invalidateStaleEmbeddings } from "./core.mjs"
 import { detectLanguage, _upsertCodeFile, _upsertDocFile, yieldTick } from "./code-index.mjs"
 import { isSkippedRelPath, extensionOf } from "./file-walk.mjs"
 import { createRowBudget, rowCountOfPath, sweepStaleRows } from "./sync-tail.mjs"
-import { loadProjectDeclaration, isExcludedRelPath, declaredPublicRoots } from "../conventions.mjs"
+import { loadProjectDeclaration, isExcludedRelPath, declaredPublicRoots, declaredIndexScope, isInDeclaredScope } from "../conventions.mjs"
 import { logEvent } from "../log.mjs"
 import { indexExtensions, listProjectFiles } from "./file-list.mjs"
 
@@ -53,6 +53,7 @@ export async function gitSync(memory, dir, opts = {}) {
 async function gitSyncDir(memory, dir, { onProgress } = {}) {
   const origin = normalizeOrigin(dir) // §6.11 写缝归一（git / 文件 I/O 用原样 dir；库面 origin 一律归一值）
   const decl = loadProjectDeclaration(dir)
+  const scope = declaredIndexScope(dir) // §6.14 面⑦ 范围门（diff 缝逐行判——见下）
   const { execFile: _execFile } = await import("node:child_process")
   const { code: codeExts, doc: docExts } = indexExtensions(dir)
   const gitRun = (args) => new Promise((resolve, reject) => {
@@ -95,7 +96,8 @@ async function gitSyncDir(memory, dir, { onProgress } = {}) {
     const abs = join(dir, rel)
     const ext = extensionOf(rel)
 
-    if (isSkippedRelPath(rel) || isExcludedRelPath(rel, decl, dir)) continue
+    // §6.14 准入三族同判（面④ 跳过段 ∥ 面①∪面⑥ 排除谓词 ∥ 面⑦ 声明范围）：范围外 = 不收录
+    if (isSkippedRelPath(rel) || isExcludedRelPath(rel, decl, dir) || !isInDeclaredScope(rel, scope, dir)) continue
 
     if (!codeExts.has(ext) && !docExts.has(ext)) { skipped++; continue }
 
@@ -210,8 +212,8 @@ async function codeSyncDir(memory, dir, { onProgress, yieldFn = yieldTick, nowFn
     }
   }
 
-  // §6.14 B6 ∕ M3：收尾 stale 循环（同款让出 + 面① 收尾保护位）——机制单源 = `sync-tail.mjs`
-  removed = await sweepStaleRows(memory, { table: "code_chunks", origin, indexed, seen, decl, base: dir, yieldFn, nowFn, yieldMs })
+  // §6.14 B6 ∕ M3：收尾 stale 循环（同款让出 + 收尾保护位：面①∪面⑥ 排除 ∪ 面⑦ 范围）——机制单源 = `sync-tail.mjs`
+  removed = await sweepStaleRows(memory, { table: "code_chunks", origin, indexed, seen, decl, base: dir, scope: declaredIndexScope(dir), yieldFn, nowFn, yieldMs })
 
   onProgress?.({ phase: "done", total: files.length, updated, removed, skipped, failed, overSizeSkipped, budgetSkipped: budgetSkipped.length })
   // §6.14 B7 维护口：模型键失配的失效**执行**（读面只判定降级——执行住同步尾；覆盖 /reindex ∕ 桌面 ∕ VSC 构建）
@@ -248,6 +250,7 @@ export async function reindexFile(memory, cwd, absPath) {
   if (rel === ".." || rel.startsWith("../")) return
   if (isSkippedRelPath(rel)) return
   if (isExcludedRelPath(rel, loadProjectDeclaration(cwd), cwd)) return // §6.14 面① 第三起效点（单文件缝零写）
+  if (!isInDeclaredScope(rel, declaredIndexScope(cwd), cwd)) return // §6.14 面⑦ 同址第三起效点（范围外单文件零写）
   // Declared extensions count for the single-file path too (union with built-ins).
   const { code: codeExts, doc: docExts } = indexExtensions(cwd)
 

package/memory/docs.mjs

@@ -12,7 +12,7 @@ import { _upsertDocFile, yieldTick } from "./code-index.mjs"
 import { markIndexedCommit, listProjectFiles, indexExtensions, declaredRootEntries } from "./code-sync.mjs"
 import { searchOrigins } from "./code-search.mjs"
 import { createRowBudget, rowCountOfPath, sweepStaleRows } from "./sync-tail.mjs"
-import { loadProjectDeclaration } from "../conventions.mjs" // 排除谓词本档不直调（经 `decl` 传 `sweepStaleRows`）
+import { loadProjectDeclaration, isExcludedRelPath, declaredIndexScope, isInDeclaredScope } from "../conventions.mjs" // 面① 谓词经 `decl` 传 `sweepStaleRows`；面⑥∪面⑦ 读面准入本档直调
 import { logEvent } from "../log.mjs"
 import { safeSliceUTF16 } from "../text-budget.mjs"
 import { DESC } from "../tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/*.md（DESC 单解析面，缺档抛错语义不变）
@@ -88,8 +88,8 @@ export async function syncDocRoot(memory, dir, { onProgress, yieldFn = yieldTick
     }
   }
 
-  // §6.14 B6 ∕ M3：收尾 stale 循环（同款让出 + 面① 收尾保护位）——机制单源 = `sync-tail.mjs`
-  removed = await sweepStaleRows(memory, { table: "doc_chunks", origin, indexed, seen, decl, base: dir, yieldFn, nowFn, yieldMs })
+  // §6.14 B6 ∕ M3：收尾 stale 循环（同款让出 + 收尾保护位：面①∪面⑥ 排除 ∪ 面⑦ 范围）——机制单源 = `sync-tail.mjs`
+  removed = await sweepStaleRows(memory, { table: "doc_chunks", origin, indexed, seen, decl, base: dir, scope: declaredIndexScope(dir), yieldFn, nowFn, yieldMs })
 
   onProgress?.({ phase: "done", total: files.length, updated, removed, skipped, failed, overSizeSkipped, budgetSkipped: budgetSkipped.length })
   // §6.14 B7 维护口：模型键失配的失效**执行**（读面只判定降级——执行住同步尾）
@@ -117,13 +117,28 @@ export async function docSearch(memory, query, { limit = 5, origins: originsOver
   const origins = originsOverride ?? searchOrigins(memory)
   const ftsOriginFilter = origins.length === 1 ? `AND d.origin = ?` : origins.length > 1 ? `AND d.origin IN (${origins.map(() => "?").join(", ")})` : ""
   const originParams = origins
+  // §6.14 读面准入过滤（FTS 列表建成后 ∥ 向量 top-K push 前；两判据并列互不吞）：排除谓词（面①∪面⑥，
+  // 行 origin 为 `base`）∪ 声明范围门（面⑦——`isInDeclaredScope(path, declaredIndexScope(origin), origin)`，
+  // 逐 origin 预载一次）⇒「批次档 ∥ 范围外路径从未入索引」等价检索；存量行不删（收尾保护位）；窗口欠额接受。
+  const declCache = new Map()
+  const scopeCache = new Map()
+  const rowHidden = (origin, path) => {
+    const d = declCache.get(origin) ?? loadProjectDeclaration(origin)
+    declCache.set(origin, d)
+    if (isExcludedRelPath(path, d, origin)) return true
+    let scope = scopeCache.get(origin)
+    if (scope === undefined) { scope = declaredIndexScope(origin); scopeCache.set(origin, scope) }
+    return !isInDeclaredScope(path, scope, origin)
+  }
+  const ftsNeedOrigin = origins.length !== 1 // 单 origin 形 SQL 零改；多 origin ∥ 无过滤形补 `origin` 列（行 origin 随行可得）
 
   const ftsList = ftsQuery ? memory.db.prepare(`
-    SELECT d.rowid, d.path, d.language, d.heading, d.content, d.line_start, d.line_end, bm25(doc_chunks_fts) AS rank
+    SELECT d.rowid, d.path, d.language, d.heading, d.content, d.line_start, d.line_end, bm25(doc_chunks_fts) AS rank${ftsNeedOrigin ? ", d.origin" : ""}
     FROM doc_chunks_fts JOIN doc_chunks d ON d.rowid = doc_chunks_fts.rowid
     WHERE doc_chunks_fts MATCH ? ${ftsOriginFilter}
     ORDER BY rank LIMIT ?
-  `).all(ftsQuery, ...originParams, Math.max(limit * 4, 20)) : []
+  `).all(ftsQuery, ...originParams, Math.max(limit * 4, 20))
+    .filter((r) => !rowHidden(origins.length === 1 ? origins[0] : r.origin, r.path)) : []
 
   if (!memory.embedder) return ftsList.slice(0, limit)
 
@@ -152,7 +167,9 @@ export async function docSearch(memory, query, { limit = 5, origins: originsOver
   for (const origin of origins.length ? origins : [null]) {
     await scanVectors(memory.db, vecSql, origin ? [origin] : [], {
       cursorKey,
-      onRow: (r) => top.push({ id: r.rowid, rowid: r.rowid, score: cosine(qvec, fromBlob(r.embedding)) }),
+      onRow: (r) => { // §6.14 面⑥∪面⑦ 准入（top-K push 前；无过滤形行 origin = 游标键 `origin` 列）
+        if (!rowHidden(origin ?? r.origin, r.path)) top.push({ id: r.rowid, rowid: r.rowid, score: cosine(qvec, fromBlob(r.embedding)) })
+      },
     })
   }
   const vecList = top.list().map((c) => ({ rowid: c.id, score: c.score }))

package/memory/file-list.mjs

@@ -1,12 +1,13 @@
 /**
  * memory/file-list.mjs — 项目文件清单面（自 `memory/code-sync.mjs` 迁出 · 2026-10-01 core 拆分批 #755 ∥ #786）。
  * 内容 = `indexExtensions`（内置扩展名表 ∪ 项目声明并集）∥ `listProjectFiles`（git 列面 + 非 git walk
- * 回退 + unlisted 计数；`index.excludePaths` §6.14 面① 双径过滤：git 列面筛行 ∥ walk 剪枝）——迁出块逐字。
+ * 回退 + unlisted 计数；准入 = 排除（§6.14 面①∪面⑥——git 列面筛行 ∥ walk 剪枝）+ 声明范围门
+ * （§6.14 面⑦——双径逐文件判 ∥ walk 不剪枝））——迁出块逐字。
  * 原档 `memory/code-sync.mjs` 经 `export { … } from` 转口保名（消费面 / 单元测试档 import 面零改）。
  */
 import { CODE_EXTS, DOC_EXTS } from "./schema.mjs"
 import { walkProjectFiles, isSkippedRelPath, extensionOf, createUnlistedTally, MAX_WALK_FILES } from "./file-walk.mjs"
-import { loadProjectDeclaration, isExcludedRelPath } from "../conventions.mjs"
+import { loadProjectDeclaration, isExcludedRelPath, declaredIndexScope, isInDeclaredScope } from "../conventions.mjs"
 import { logEvent } from "../log.mjs"
 
 /**
@@ -33,10 +34,13 @@ export function indexExtensions(dir) {
  * Returns { entries, unlisted }: `entries` = { abs, rel } pairs (rel relative to
  * dir); `unlisted` = files whose extension is in NO index list (count + sample),
  * the visible signal behind "my .xyz files are not searchable" (PORTABILITY PO-9).
- * Declared `index.excludePaths` (§6.14 面①) filters BOTH paths — git listing filters the
- * line set; the walk prunes excluded subtrees during traversal (no expansion, no budget).
+ * Both admission facets filter BOTH paths: the exclusion predicate (§6.14 面① declared
+ * `index.excludePaths` ∪ 面⑥ batch-record segments) — git listing filters the line set,
+ * the walk prunes excluded subtrees during traversal (no expansion, no budget); and the
+ * declared-scope gate (§6.14 面⑦ — un-declared ⇒ not indexed) — per-file on both paths,
+ * no pruning on the walk (a segment-sequence face may match at any depth).
  * `truncated` = the non-git walk hit its file cap (capped trees are logged, never
- * silently indexed-partial). opts.maxFiles = the walk cap (test seam).
+ * silently indexed-partial; out-of-scope files spend no budget). opts.maxFiles = the walk cap (test seam).
  */
 export async function listProjectFiles(dir, exts, { maxFiles } = {}) {
   const { execFile: _execFile } = await import("node:child_process")
@@ -44,6 +48,8 @@ export async function listProjectFiles(dir, exts, { maxFiles } = {}) {
   const { code, doc } = indexExtensions(dir)
   const decl = loadProjectDeclaration(dir)
   const excluded = (rel) => isExcludedRelPath(rel, decl, dir)
+  const scope = declaredIndexScope(dir) // §6.14 面⑦ 范围门（单源谓词；本根一份——条目集空 ⇒ 零索引）
+  const inScope = (rel) => isInDeclaredScope(rel, scope, dir)
   const tally = createUnlistedTally(new Set([...code, ...doc]))
 
   const files = []
@@ -58,7 +64,7 @@ export async function listProjectFiles(dir, exts, { maxFiles } = {}) {
     })).replace(/\\/g, "/")
   } catch {
     // Not a git repo → filesystem walk (FR15: the index must still be usable).
-    const walked = await walkProjectFiles(dir, exts, { knownExts: new Set([...code, ...doc]), isExcluded: excluded, ...(maxFiles !== undefined ? { maxFiles } : {}) })
+    const walked = await walkProjectFiles(dir, exts, { knownExts: new Set([...code, ...doc]), isExcluded: excluded, isInScope: inScope, ...(maxFiles !== undefined ? { maxFiles } : {}) })
     files.push(...walked.files)
     // The walk's cap must stay visible end-to-end (file-walk.mjs: "never silently
     // dropped") — a capped listing says so in the log, not only in a discarded flag.
@@ -78,7 +84,7 @@ export async function listProjectFiles(dir, exts, { maxFiles } = {}) {
       const p = line.trim()
       if (!p) continue
       const rel = p.replace(/\\/g, "/")
-      if (isSkippedRelPath(rel) || excluded(rel)) continue
+      if (isSkippedRelPath(rel) || excluded(rel) || !inScope(rel)) continue
       const ext = extensionOf(rel)
       if (!ext || !exts.has(ext)) { tally.note(rel); continue }
       files.push({ abs: joinPath(dir, rel), rel })

package/memory/file-walk.mjs

@@ -80,14 +80,18 @@ export function createUnlistedTally(knownExts) {
  * silently dropped.
  * @param {string} dir — project root
  * @param {Set<string>} exts — extensions to keep (lower-case, leading dot)
- * @param {{maxFiles?: number, knownExts?: Set<string>|null, isExcluded?: ((rel: string) => boolean)|null}} [opts]
+ * @param {{maxFiles?: number, knownExts?: Set<string>|null, isExcluded?: ((rel: string) => boolean)|null,
+ *   isInScope?: ((rel: string) => boolean)|null}} [opts]
  *   knownExts → also tally files whose extension is in NO index list
- *   isExcluded → caller-injected exclusion predicate (§6.14 面① 剪枝形): a hit prunes the
+ *   isExcluded → caller-injected exclusion predicate (§6.14 面① ∪ 面⑥ 剪枝形): a hit prunes the
  *   subtree (never expanded — zero readdir, no MAX_WALK_FILES budget spent) or drops the file
+ *   isInScope → caller-injected declared-scope predicate (§6.14 面⑦): a hit drops the FILE only —
+ *   never prunes (the code face matches a segment sequence at any depth, so an upper directory
+ *   carries no pruning judgement); an out-of-scope file spends no MAX_WALK_FILES budget
  * @returns {Promise<{files: {abs: string, rel: string}[], truncated: boolean,
  *   unlisted: {count: number, exts: {ext: string, count: number}[]}}>}
  */
-export async function walkProjectFiles(dir, exts, { maxFiles = MAX_WALK_FILES, knownExts = null, isExcluded = null } = {}) {
+export async function walkProjectFiles(dir, exts, { maxFiles = MAX_WALK_FILES, knownExts = null, isExcluded = null, isInScope = null } = {}) {
   const files = []
   const tally = knownExts ? createUnlistedTally(knownExts) : null
   let truncated = false
@@ -106,7 +110,8 @@ export async function walkProjectFiles(dir, exts, { maxFiles = MAX_WALK_FILES, k
         if (!isSkippedRelPath(rel) && !isExcluded?.(rel)) stack.push({ abs: join(cur.abs, ent.name), rel })
         continue
       }
-      if (!ent.isFile() || isSkippedRelPath(rel) || isExcluded?.(rel)) continue
+      // 面⑦ 范围门：只丢文件、不剪枝（段序列可命中任意深度 ⇒ 上层目录无剪枝判据）
+      if (!ent.isFile() || isSkippedRelPath(rel) || isExcluded?.(rel) || (isInScope !== null && !isInScope(rel))) continue
       const ext = extensionOf(ent.name)
       if (!ext || !exts.has(ext)) {
         tally?.note(rel)

package/memory/sync-tail.mjs

@@ -8,14 +8,15 @@
  *     一行；真实行数——F-S14 ①）＋ `logEvent`；过 `INDEX_ORIGIN_ROW_CAP` 由调用方跳过列序后缀
  *     （**只停新增**——存量行不失效；跳过 = 不落行 ∕ 不记 mtime ⇒ 下趟重试）。
  *   · **stale 收尾循环**（`sweepStaleRows`）：同款时间片让出（§6.10 A2 口径——每 `SCAN_YIELD_CHECK_ROWS`
- *     行读钟，累计 ≥ `yieldMs` 即让出）＋ 面① **收尾保护位**（`isExcludedRelPath` 命中路径短路——
- *     被排除但存在的路径存量行不因声明删除，收敛仅经 `sweep --path`；缺省 `[]` ⇒ 恒不命中）。
+ *     行读钟，累计 ≥ `yieldMs` 即让出）＋ **收尾保护位**（两族并列：面①∪面⑥ `isExcludedRelPath` ∪
+ *     面⑦ `isInDeclaredScope` 命中路径短路——被排除 ∥ 范围外而文件仍在盘的路径，存量行不因声明
+ *     删除；收尾只删「不在盘 ∥ 不再列」的行，收敛仅经 `sweep --path`）。
  *
  * 零环：只引 `log.mjs` ∕ `conventions.mjs`（谓词）∕ `schema.mjs`（常量）∕ `scan.mjs`（预算常量）∕
  * `code-index.mjs`（`yieldTick`）——不引 `code-sync.mjs` ∕ `docs.mjs`。作业皆经传入句柄，档内零状态。
  */
 import { logEvent } from "../log.mjs"
-import { isExcludedRelPath } from "../conventions.mjs"
+import { isExcludedRelPath, isInDeclaredScope } from "../conventions.mjs"
 import { INDEX_ORIGIN_ROW_WARN, INDEX_ORIGIN_ROW_CAP } from "./schema.mjs"
 import { SCAN_YIELD_CHECK_ROWS, SCAN_YIELD_MS } from "./scan.mjs"
 import { yieldTick } from "./code-index.mjs"
@@ -65,16 +66,19 @@ export function createRowBudget(memory, origin, kind, dir, { baseOffset } = {})
  * §6.14 B6 ∕ M3：收尾 stale 删除循环（同款让出 + 收尾保护位）。返回删除行数（文件级）。
  * @param {object} memory 句柄
  * @param {{table: string, origin: string, indexed: Map<string, number>, seen: Set<string>, decl: object,
- *   base?: string|null, yieldFn?: Function, nowFn?: Function, yieldMs?: number}} opts
+ *   base?: string|null, scope?: readonly object[]|null, yieldFn?: Function, nowFn?: Function, yieldMs?: number}} opts
  *   `indexed` = 库内 path→mtime（开趟读）；`seen` = 本趟列文件；`decl` = `loadProjectDeclaration()` 回执；
- *   `base` = `indexed`/`seen` 里 `rel` 的相对基（调用面 dir——#700 等价换算；缺省 = 根相对）
+ *   `base` = `indexed`/`seen` 里 `rel` 的相对基（调用面 dir——#700 等价换算；缺省 = 根相对）；
+ *   `scope` = `declaredIndexScope(base)` 回执（面⑦ 保护位——缺省 `null` ⇒ **范围面不判**（仅面①∪面⑥ 保护，
+ *   既有调用方语义零改）；在场（含空数组 = 零条目）⇒ 范围外短路（存量行不删））
  */
-export async function sweepStaleRows(memory, { table, origin, indexed, seen, decl, base = null, yieldFn = yieldTick, nowFn = Date.now, yieldMs = SCAN_YIELD_MS }) {
+export async function sweepStaleRows(memory, { table, origin, indexed, seen, decl, base = null, scope = null, yieldFn = yieldTick, nowFn = Date.now, yieldMs = SCAN_YIELD_MS }) {
   let removed = 0
   let checked = 0
   let lastYieldAt = nowFn()
   for (const stale of indexed.keys()) {
-    if (!seen.has(stale) && !isExcludedRelPath(stale, decl, base)) {
+    // 面⑦ 保护位：`scope` 在场 ⇒「声明面内才删」（范围外短路）；缺省 ⇒ 范围面不判（既有调用方语义零改）
+    if (!seen.has(stale) && !isExcludedRelPath(stale, decl, base) && (scope === null || isInDeclaredScope(stale, scope, base))) {
       memory.db.prepare(`DELETE FROM ${table} WHERE origin = ? AND path = ?`).run(origin, stale)
       removed++
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thincoder/core",
-  "version": "0.10.6",
+  "version": "0.10.7",
   "description": "ThinCoder shared core — shared mechanism modules + shared prompt content (CLI ↔ VS Code extension).",
   "keywords": [
     "ai",