@thincoder/core 0.10.5 → 0.10.7

package/browser/snapshot.mjs

@@ -0,0 +1,270 @@
+/**
+ * browser/snapshot.mjs — 页面侧快照脚本 ∥ 几何 ∥ 点 / 聚焦表达式 ∥ 结果归一 ∥ 引用表 ∥ 紧凑渲染 ∥ 页摘
+ * （BROWSER-TOOL.md §2.3 ∥ §2.7）。
+ *
+ * 页面侧脚本一律经 `Runtime.evaluate` **一次性执行、不驻留**（§3.3）；每条表达式带一个块注释标识
+ * 前缀（`thincoder-browser:<种类>`）——回执/调试可辨出处，单元测试假传输按此前缀派发。
+ * 引用表：`key = tag + "|" + selector`，跨快照复用原号（KD-1 / F-BT4「微变不全失效」）。
+ * 几何（F-BT14）：每条记录携 `geo`（视口 CSS 像素）与 `inViewport`；`[outside]` 仅标视口外行（KD-15）。
+ */
+export const DEFAULT_MAX = 100
+export const MAX_ELEMENTS = 200
+export const MAX_SNAPSHOT_CHARS = 20_000
+export const COMPACT_ROWS = 30 // 失败回执的紧凑清单行数
+
+const mark = (kind) => `/*thincoder-browser:${kind}*/`
+
+/**
+ * 页面侧快照函数源串（`(opts) => 记录集`）。
+ * 走交互元素（§2.3）：`a[href]` / `button` / `input`（非 hidden） / `select` / `textarea` /
+ * `[role=button]` / `[onclick]` / `[tabindex]`；`selector` = 稳定寻址链（`#id` → `[data-testid]`
+ * → `[name]` → `[href]` → 结构路径）；password 输入**不取 value**（N-BT4）。
+ * 几何随记录（§2.7）：`geo = {x,y,w,h}` 取整 + `inViewport`（非零面积 ∩ 视口）。
+ */
+export const SNAPSHOT_EXPR = String.raw`function (opts) {
+  var SEL = 'a[href],button,input:not([type=hidden]),select,textarea,[role=button],[onclick],[tabindex]'
+  var norm = function (s) { return String(s == null ? '' : s).replace(/\s+/g, ' ').trim().slice(0, 60) }
+  var esc = function (s) {
+    try { return (globalThis.CSS && CSS.escape) ? CSS.escape(String(s)) : String(s).replace(/[^a-zA-Z0-9_-]/g, function (c) { return '\\' + c }) }
+    catch (e) { return String(s) }
+  }
+  var unique = function (sel) { try { return document.querySelectorAll(sel).length === 1 } catch (e) { return false } }
+  var pathOf = function (el) {
+    var parts = []
+    var cur = el
+    while (cur && cur.nodeType === 1 && cur !== document.documentElement) {
+      if (cur.id && unique('#' + esc(cur.id))) { parts.unshift('#' + esc(cur.id)); break }
+      var tag = cur.tagName.toLowerCase()
+      var parent = cur.parentElement
+      if (!parent) { parts.unshift(tag); break }
+      var same = Array.prototype.filter.call(parent.children, function (c) { return c.tagName === cur.tagName })
+      parts.unshift(same.length > 1 ? tag + ':nth-of-type(' + (same.indexOf(cur) + 1) + ')' : tag)
+      cur = parent
+    }
+    return parts.join(' > ')
+  }
+  var selectorOf = function (el) {
+    if (el.id && unique('#' + esc(el.id))) return '#' + esc(el.id)
+    var testid = el.getAttribute('data-testid')
+    if (testid && unique('[data-testid="' + testid + '"]')) return '[data-testid="' + testid + '"]'
+    var name = el.getAttribute('name')
+    if (name && unique('[name="' + name + '"]')) return '[name="' + name + '"]'
+    var href = el.getAttribute('href')
+    if (href && el.tagName === 'A' && unique('[href="' + href + '"]')) return '[href="' + href + '"]'
+    return pathOf(el)
+  }
+  var roleOf = function (el, tag) {
+    var t = String(el.getAttribute('type') || '').toLowerCase()
+    if (tag === 'a') return 'link'
+    if (tag === 'select') return 'select'
+    if (tag === 'textarea') return 'textbox'
+    if (tag === 'button') return 'button'
+    if (tag === 'input') {
+      if (t === 'password') return 'password'
+      if (t === 'checkbox') return 'checkbox'
+      if (t === 'radio') return 'radio'
+      if (t === 'submit' || t === 'button' || t === 'reset' || t === 'image') return 'button'
+      return 'textbox'
+    }
+    if (el.getAttribute('role') === 'button' || el.hasAttribute('onclick')) return 'button'
+    return 'other'
+  }
+  var nameOf = function (el) {
+    // 可及名取序照 §2.3：aria-label ∥ 文本 ∥ placeholder ∥ title
+    return norm(el.getAttribute('aria-label') || el.innerText || el.textContent || el.getAttribute('placeholder') || el.getAttribute('title') || '')
+  }
+  var rectOf = function (el) {
+    var r = el.getBoundingClientRect()
+    return { x: Math.round(r.left), y: Math.round(r.top), w: Math.round(r.width), h: Math.round(r.height) }
+  }
+  var inViewportOf = function (g) {
+    return g.w > 0 && g.h > 0 && g.x < innerWidth && g.y < innerHeight && g.x + g.w > 0 && g.y + g.h > 0
+  }
+  var root = (opts && opts.selector) ? document.querySelector(opts.selector) : document
+  if (!root) return { missing: true, url: location.href, title: document.title, elements: [], total: 0 }
+  var nodes = []
+  if (root.nodeType === 1 && root.matches && root.matches(SEL)) nodes.push(root)
+  var found = root.querySelectorAll ? root.querySelectorAll(SEL) : []
+  for (var i = 0; i < found.length; i++) nodes.push(found[i])
+  var max = Math.max(1, (opts && opts.max) ? opts.max : 100)
+  var elements = []
+  for (var j = 0; j < nodes.length && elements.length < max; j++) {
+    var el = nodes[j]
+    var tag = el.tagName.toLowerCase()
+    var role = roleOf(el, tag)
+    var geo = rectOf(el)
+    var rec = {
+      tag: tag,
+      role: role,
+      name: nameOf(el),
+      selector: selectorOf(el),
+      disabled: Boolean(el.disabled) || el.getAttribute('aria-disabled') === 'true',
+      geo: geo,
+      inViewport: inViewportOf(geo),
+    }
+    if (role === 'textbox' || role === 'select') rec.value = norm(el.value)
+    elements.push(rec)
+  }
+  return { url: location.href, title: document.title, total: nodes.length, elements: elements }
+}`
+
+/** 快照表达式（页面侧一次执行）。 */
+export function snapshotExpression({ selector = null, max = DEFAULT_MAX } = {}) {
+  return `${mark("snapshot")}(${SNAPSHOT_EXPR})(${JSON.stringify({ selector, max })})`
+}
+
+/** 当前页信息表达式（URL ∥ title ∥ readyState）。 */
+export function pageInfoExpression() {
+  return `${mark("pageinfo")}(function () { return { url: location.href, title: document.title, readyState: document.readyState } })()`
+}
+
+/** 点击表达式（寻址 + tag 一致校验 + disabled 判；返回 `{found, disabled, tag?}`）。 */
+export function clickExpression(selector, tag) {
+  return `${mark("click")}(function () {
+  var el = document.querySelector(${JSON.stringify(selector)})
+  if (!el) return { found: false }
+  var tag = el.tagName.toLowerCase()
+  if (tag !== ${JSON.stringify(tag)}) return { found: false, tag: tag }
+  if (el.disabled) return { found: true, disabled: true }
+  el.scrollIntoView({ block: 'center' })
+  el.click()
+  return { found: true, disabled: false }
+})()`
+}
+
+/** 输入表达式（原生 value setter + input/change 事件；回执判据 = `password` 标记）。 */
+export function typeExpression(selector, tag, text, clear) {
+  return `${mark("type")}(function () {
+  var el = document.querySelector(${JSON.stringify(selector)})
+  if (!el) return { found: false }
+  var tag = el.tagName.toLowerCase()
+  if (tag !== ${JSON.stringify(tag)}) return { found: false, tag: tag }
+  if (tag !== 'input' && tag !== 'textarea') return { found: true, disabled: false, password: false, fillable: false }
+  var password = tag === 'input' && String(el.getAttribute('type') || '').toLowerCase() === 'password'
+  if (el.disabled) return { found: true, disabled: true, password: password }
+  var proto = tag === 'textarea' ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype
+  var desc = Object.getOwnPropertyDescriptor(proto, 'value')
+  var next = ${clear ? "true" : "false"} ? ${JSON.stringify(text)} : String(el.value == null ? '' : el.value) + ${JSON.stringify(text)}
+  if (desc && desc.set) desc.set.call(el, next); else el.value = next
+  el.dispatchEvent(new Event('input', { bubbles: true }))
+  el.dispatchEvent(new Event('change', { bubbles: true }))
+  return { found: true, disabled: false, password: password }
+})()`
+}
+
+/** 点表达式（ref → 真点——§2.7）：`scrollIntoView({block:'center'})` → 重测 → 返回中心点与 `{found, tag?}`。 */
+export function pointExpression(selector, tag) {
+  return `${mark("point")}(function () {
+  var el = document.querySelector(${JSON.stringify(selector)})
+  if (!el) return { found: false }
+  var tag = el.tagName.toLowerCase()
+  if (tag !== ${JSON.stringify(tag)}) return { found: false, tag: tag }
+  el.scrollIntoView({ block: 'center' })
+  var r = el.getBoundingClientRect()
+  return { found: true, x: r.left + r.width / 2, y: r.top + r.height / 2 }
+})()`
+}
+
+/** 聚焦表达式（§2.7）：`scrollIntoView` + `focus()` → `{found, tag?, focused}`；不可聚焦 ⇒ `focused:false`。 */
+export function focusExpression(selector, tag) {
+  return `${mark("focus")}(function () {
+  var el = document.querySelector(${JSON.stringify(selector)})
+  if (!el) return { found: false }
+  var tag = el.tagName.toLowerCase()
+  if (tag !== ${JSON.stringify(tag)}) return { found: false, tag: tag }
+  el.scrollIntoView({ block: 'center' })
+  try { el.focus() } catch (e) { /* 不可聚焦元素（div 等）——focused 读回自证 */ }
+  return { found: true, focused: document.activeElement === el }
+})()`
+}
+
+/** 等待谓词表达式（selector ∥ text ∥ url——networkIdle 走核侧事件计数）。 */
+export function waitExpression(kind, value) {
+  const expr = kind === "selector" ? `!!document.querySelector(${JSON.stringify(value)})`
+    : kind === "text" ? `String((document.body && document.body.innerText) || '').includes(${JSON.stringify(value)})`
+      : `location.href.includes(${JSON.stringify(value)})`
+  return `${mark("wait")}(function () { return ${expr} })()`
+}
+
+/** 页面侧结果 → 形状归一的记录集（不可信输入：缺字段/异型一律归一，不抛）。 */
+export function normalizeSnapshot(raw) {
+  const r = raw && typeof raw === "object" ? raw : {}
+  const num = (v) => (Number.isFinite(Number(v)) ? Math.round(Number(v)) : 0)
+  const elements = (Array.isArray(r.elements) ? r.elements : [])
+    .filter((e) => e && typeof e === "object" && e.selector)
+    .map((e) => {
+      const rec = {
+        tag: String(e.tag ?? "").toLowerCase(),
+        role: String(e.role ?? "other"),
+        name: String(e.name ?? ""),
+        selector: String(e.selector),
+        disabled: e.disabled === true,
+      }
+      if (e.value !== undefined && e.value !== null && String(e.value) !== "") rec.value = String(e.value)
+      if (e.geo && typeof e.geo === "object") {
+        rec.geo = { x: num(e.geo.x), y: num(e.geo.y), w: num(e.geo.w), h: num(e.geo.h) }
+      }
+      if (e.inViewport === false) rec.inViewport = false // 仅视口外落标记（在屏行文法零动——KD-15）
+      return rec
+    })
+  return {
+    url: String(r.url ?? ""),
+    title: String(r.title ?? ""),
+    elements,
+    total: Number.isInteger(r.total) ? Math.max(r.total, elements.length) : elements.length,
+    missing: r.missing === true,
+  }
+}
+
+/** 核侧引用表（会话级——`byRef` 反查、`byKey` 复用、`counter` 会话内单调）。 */
+export function createRefTable() {
+  return { byRef: new Map(), byKey: new Map(), counter: 1 }
+}
+
+/** 记录集 → 引用行（key 已在表 ⇒ 复用原号；未见 ⇒ 新号 + `isNew`）。 */
+export function assignRefs(table, elements) {
+  const rows = []
+  for (const el of elements) {
+    const key = `${el.tag}|${el.selector}`
+    let entry = table.byKey.get(key)
+    const isNew = !entry
+    if (isNew) {
+      entry = { ref: `e${table.counter++}`, key, selector: el.selector, tag: el.tag, name: el.name }
+      table.byKey.set(key, entry)
+      table.byRef.set(entry.ref, entry)
+    } else {
+      entry.name = el.name // 名随页面更新；号不变（F-BT4）
+    }
+    rows.push({ ...el, ref: entry.ref, isNew })
+  }
+  return rows
+}
+
+/** 结果行文法：`<ref> <role> "<name>"` + `[value=…]`（password 除外）+ `[new]` + `[disabled]` + `[outside]`。 */
+export function rowLine(row) {
+  const marks = []
+  if (row.role !== "password" && row.value !== undefined && String(row.value) !== "") marks.push(`[value="${row.value}"]`)
+  if (row.isNew) marks.push("[new]")
+  if (row.disabled) marks.push("[disabled]")
+  if (row.inViewport === false) marks.push("[outside]")
+  return `${row.ref} ${row.role} "${row.name}"${marks.length ? ` ${marks.join(" ")}` : ""}`
+}
+
+/** 页摘行（内容与出处同行——N-BT2 来源标注）。 */
+export function pageDigest(url, title) {
+  return `[page] ${url} — "${title}"`
+}
+
+/** 紧凑渲染：页摘 ∥ 计数行 ∥ 元素行 ∥ 截断标记；总文本 ≤ 20,000 字符（N-BT3）。 */
+export function renderSnapshot({ url, title, rows = [], total = rows.length }) {
+  const lines = [pageDigest(url, title), `[${total} interactive elements (${rows.filter((r) => r.isNew).length} new)]`]
+  for (const row of rows) lines.push(rowLine(row))
+  if (total > rows.length) lines.push(`[truncated: showing ${rows.length} of ${total} — pass selector to narrow]`)
+  return truncateText(lines.join("\n"), MAX_SNAPSHOT_CHARS, "pass selector to narrow")
+}
+
+/** 截断（`truncate` 同款标记形态——`tools/shared.mjs:190-193`）。 */
+export function truncateText(text, max, note = "narrow the request") {
+  if (text.length <= max) return text
+  return `${text.slice(0, max)}\n[... truncated: ${text.length - max} chars omitted — ${note}]`
+}

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)