@thincoder/core 0.10.5 → 0.10.7

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.5",
+  "version": "0.10.7",
   "description": "ThinCoder shared core — shared mechanism modules + shared prompt content (CLI ↔ VS Code extension).",
   "keywords": [
     "ai",
@@ -40,6 +40,7 @@
     "advisor/",
     "agent/",
     "agent-tools/",
+    "browser/",
     "git/",
     "mcp/",
     "memory/",