feat: extract vector boundary without overclaiming readiness

Author: Jacobinwwey

docs/brainstorms/2026-04-19-mainline-progress-reconciliation-and-post-m7-direction-requirements.md

@@ -41,7 +41,7 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
   - learning-path dock coexistence and fullscreen lifecycle coverage.
 - `src/markdown/MarkdownGateway.ts` exists on mainline, but markdown-reader governance is still a bounded backlog lane rather than the current active mainline delivery lane.
 - `src/learning/store.ts` remains file-backed on mainline.
-  Mainline now contains a dedicated `src/learning/queryBackend.ts` boundary, but still does **not** contain the full graphdb/vector adapter set that would justify claiming foundation re-entry completion.
+  Mainline now contains dedicated `src/learning/queryBackend.ts` and `src/learning/vectorAccelerationAdapter.ts` boundaries, but the vector path is still only a local prefilter stage and therefore does **not** justify claiming foundation re-entry completion.
 
 ## Deep Comparison: Prior Requirements vs Current Code
 
@@ -59,7 +59,7 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
 |---|---|---|---|
 | L0 Representation | atom/evidence extraction and staleness semantics are stable | Stable | no urgent blocker |
 | L1 Structure | relation and temporal graph semantics are present in current learning core | Stable | no urgent blocker |
-| L2 Retrieval foundation | explainable retrieval is already integrated, query scoring now has a dedicated boundary, but persistence remains file-backed and vector adapter independence has not landed | Advanced baseline, foundation lane not re-entered | do not overclaim graphdb/vector readiness |
+| L2 Retrieval foundation | explainable retrieval is already integrated, query and vector-prefilter scoring now have dedicated boundaries, but persistence remains file-backed and vector adapter independence has not landed | Advanced baseline, foundation lane not re-entered | do not overclaim graphdb/vector readiness |
 | L3 Learning loop | misconception/path/session/memory flows are integrated and persistence-tested | Advanced baseline | avoid describing this as merely partial without qualifier |
 | L4 Interaction | conversation shell, typed operation routing, focus-mode, learning-path dock coexistence, and runtime verification are integrated | Integrated baseline | broaden only through typed contract discipline |
 | L5 Governance | operator diagnostics and notification-threshold governance expanded deeply through `M7.28` | Deep integrated lane | further route fragmentation now has diminishing returns |
@@ -162,7 +162,7 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
   - `npm test -- src/learning/KnowledgeLearningPlatform.persistence.test.ts --runInBand`
 - The current working branch remains a reference source for future lanes, not a justification for direct wide merge.
 
-## Execution Note (2026-04-20 M8.1-M8.3)
+## Execution Note (2026-04-20 M8.1-M8.4)
 
 - The smallest executed post-M7 slice is now an evidence bundle, not an adapter claim:
   - `npm run verify:foundation:readiness`
@@ -176,6 +176,9 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
 - The next bounded execution slice after that extracts current query scoring into:
   - `src/learning/queryBackend.ts`
   - without changing the external `queryKnowledge(...)` contract or claiming vector closure.
+- The next bounded execution slice after that extracts local vector-prefilter scoring into:
+  - `src/learning/vectorAccelerationAdapter.ts`
+  - while keeping the adapter explicitly staged as `prefilter_only` so readiness cannot flip to `go` from file existence alone.
 - Current expected outcome on `main` remains:
   - status `in_progress`
   - decision `no-go`
@@ -187,7 +190,7 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
 
 ### Deferred to Planning
 - [Resolved in execution][Technical] `M7.29` kept the route bounded and accepted combined `status + appliedMode` filtering on the existing history surface, so no separate planning branch is needed for that question.
-- [Resolved in execution][Technical] The smallest executable `M8 foundation re-entry readiness` slice was an evidence bundle (`verify:foundation:readiness`) that reports current mainline baseline and preserves `no-go` honesty while adapter modules remain absent.
+- [Resolved in execution][Technical] The smallest executable `M8 foundation re-entry readiness` slices were the evidence bundle (`verify:foundation:readiness`), the typed readiness route, and then query/vector boundary extraction while preserving `no-go` honesty because the vector path is still only `prefilter_only`.
 - [Affects R11][Needs research] Does markdown-reader governance now have a stronger near-term product case than foundation re-entry once the post-M7 checkpoint happens?
 
 ## Next Steps

docs/diataxis/en/explanation/development-progress-dashboard.md

@@ -639,6 +639,20 @@ Execution anchor:
   - `npm run docs:diataxis:check`
   - `npm run docs:site:build`
 
+## Latest Mainline Increment (2026-04-20 M8.4 Vector Boundary Extraction)
+
+- Added a dedicated vector-acceleration boundary without changing the public query contract:
+  - `src/learning/vectorAccelerationAdapter.ts`
+- Wired the live query backend through the new boundary instead of inline lexical content scoring:
+  - `src/learning/queryBackend.ts`
+- Added direct regression coverage for the new boundary and its honest staging semantics:
+  - `src/learning/vectorAccelerationAdapter.test.ts`
+  - `src/learning/queryBackend.test.ts`
+- Tightened readiness truth so module existence alone cannot flip foundation status to integrated:
+  - readiness now reports the vector boundary as `prefilter_only`,
+  - `vectorAdapterIndependent` remains `false`,
+  - current repo result therefore stays `in_progress` / `no-go`.
+
 ## Latest Mainline Increment (2026-04-20 M8.3 Query Backend Boundary Extraction)
 
 - Extracted the live retrieval scoring path into a dedicated module:
@@ -680,7 +694,8 @@ Execution anchor:
   - current result is expected to stay `in_progress` / `no-go` on `main`,
   - file-backed persistence remains the verified baseline,
   - dedicated `queryBackend` is now present on `main`,
-  - dedicated `vectorAccelerationAdapter` is still absent on `main`.
+  - dedicated `vectorAccelerationAdapter` is now present on `main` only as a `prefilter_only` boundary,
+  - independent ANN evidence is still absent on `main`.
 - Added machine-readable readiness outputs for operator review:
   - `build/foundation-readiness/foundation-readiness-latest.json`
   - `build/foundation-readiness/foundation-readiness-latest.md`
@@ -733,7 +748,7 @@ This dashboard aligns against the following requirement chain:
 |---|---|---|---|---|
 | L0 Representation | atom/evidence extraction and staleness | Stable | Stable | No immediate blocker |
 | L1 Structure | relation + temporal graph semantics | Stable | Stable | No immediate blocker |
-| L2 Retrieval | explainable hybrid/vector retrieval + governance | Branch still frames graphdb/vector expansion | Explainable retrieval with relation-path + temporal-validity evidence is integrated on `main`; dedicated query scoring now lives in `src/learning/queryBackend.ts`, but persistence is still file-backed and vector independence is still absent (`src/learning/KnowledgeLearningPlatform.ts`, `src/learning/store.ts`) | M8: keep readiness honest, then close vector boundary |
+| L2 Retrieval | explainable hybrid/vector retrieval + governance | Branch still frames graphdb/vector expansion | Explainable retrieval with relation-path + temporal-validity evidence is integrated on `main`; dedicated query scoring now lives in `src/learning/queryBackend.ts`, vector prefilter scoring now lives in `src/learning/vectorAccelerationAdapter.ts`, but persistence is still file-backed and independent ANN evidence is still absent (`src/learning/KnowledgeLearningPlatform.ts`, `src/learning/store.ts`) | M8: keep readiness honest until independent vector evidence exists |
 | L3 Learning | mastery diagnostics + path/session loop | Expanded in branch | Path/session/misconception/memory flows are already integrated and persistence-tested on `main` | Preserve baseline and avoid underclaiming |
 | L4 Interaction | agent conversation + focus/path pane runtime | Implemented in branch | Typed contract routing, conversation shell, focus-mode, and path-dock coexistence are integrated on `main` | Expand only through typed contract discipline |
 | L5 Governance | runbook, diagnostics, replay/autonomy controls | Expanded in branch | Operator diagnostics persistence/triage/history/threshold governance + runbook automation/audit + adaptive simulation/remediation + remediation backtest/approval-gate + approval-policy hardening/regression-alarms + approval-policy drift/escalation + escalation acknowledgement lifecycle/audit + escalation SLA/reminder baseline + notification digest/suppression baseline + delivery-log observability + stale-cleanup health auditing + anomaly/retention governance + notification SLO governance + notification-threshold override/audit governance + rollback preview/drift-diff governance + rollback apply guardrails + latest apply-outcome reconciliation + bounded apply-outcome history + supersession summary + combined status/applied-mode filtered history integrated | Stop lane after M7.29; pivot to M8 foundation readiness |
@@ -775,7 +790,7 @@ Note: do not list foundation-lane gates as baseline until the corresponding modu
 ## Next Direction (Current Priority)
 
 1. Treat notification-threshold governance as closed after `M7.29`; do not plan `M7.30+` unless a materially new operator requirement appears.
-2. Keep `M8 foundation re-entry readiness execution` on the current path: first evidence bundle and anti-overclaim guardrails, then adapter-boundary code only after those reports stay honest.
+2. Keep `M8 foundation re-entry readiness execution` on the current path: evidence bundle and anti-overclaim guardrails landed first, vector/query boundaries now exist, but no document or route should claim independent ANN readiness until stronger evidence lands.
 3. Preserve CI and contract fail-fast guarantees for every lane change by keeping docs, agent-workspace, and learning-core gates green.
 4. Re-baseline progress docs before every major lane switch so stale branch-gap language does not leak into mainline status claims.
 5. Keep markdown reader governance bounded and secondary until the post-M7 lane switch is explicitly planned.

docs/diataxis/en/explanation/foundation-reentry-readiness-checklist.md

@@ -51,7 +51,10 @@ Bundle note:
 - Current expected result on `main` is:
   - status `In Progress`
   - decision `No-Go`
-  - rationale: file-backed baseline exists and query-backend boundary is now present, but vector adapter independence is still absent.
+  - rationale: file-backed baseline exists, query-backend and vector-boundary modules are now present, but the vector adapter is still only `prefilter_only`, so independent ANN evidence is still absent.
+- The readiness payload now makes that distinction explicit:
+  - `vectorAdapterStatus`
+  - `vectorAdapterIndependent`
 
 ## Non-overclaim Policy
 

docs/diataxis/zh/explanation/development-progress-dashboard.md

@@ -642,6 +642,20 @@
   - `npm run docs:diataxis:check`
   - `npm run docs:site:build`
 
+## 主线最新增量（2026-04-20 M8.4 Vector 边界抽取）
+
+- 已新增独立 vector-acceleration 边界，且未改变外部 query 合同：
+  - `src/learning/vectorAccelerationAdapter.ts`
+- 已把主线真实 query backend 接到该边界，而不是继续在模块内内联 lexical content 打分：
+  - `src/learning/queryBackend.ts`
+- 已补该边界与诚实 staging 语义的直测回归：
+  - `src/learning/vectorAccelerationAdapter.test.ts`
+  - `src/learning/queryBackend.test.ts`
+- 已加固 readiness 真实语义，避免“文件存在”直接把 foundation 状态翻成 integrated：
+  - readiness 现在把该 vector 边界标记为 `prefilter_only`，
+  - `vectorAdapterIndependent` 仍为 `false`，
+  - 当前仓库结果因此仍保持 `in_progress` / `no-go`。
+
 ## 主线最新增量（2026-04-20 M8.3 Query Backend 边界抽取）
 
 - 已把当前主线真实使用的检索打分路径抽到独立模块：
@@ -683,7 +697,8 @@
   - 主线当前预期结果保持 `in_progress` / `no-go`，
   - file-backed persistence 仍是已验证基线，
   - 主线现在已有独立 `queryBackend`，
-  - 但 `vectorAccelerationAdapter` 仍未进入主线。
+  - `vectorAccelerationAdapter` 已进入主线，但当前只属于 `prefilter_only` 边界，
+  - 独立 ANN 证据仍未进入主线。
 - 已为运维/文档核对补齐机器可读产物：
   - `build/foundation-readiness/foundation-readiness-latest.json`
   - `build/foundation-readiness/foundation-readiness-latest.md`
@@ -736,7 +751,7 @@
 |---|---|---|---|---|
 | L0 表示层 | 原子/证据提取 + staleness | 稳定 | 稳定 | 无紧急阻塞 |
 | L1 结构层 | 关系 + 时序图语义 | 稳定 | 稳定 | 无紧急阻塞 |
-| L2 检索层 | 可解释混合/向量检索 + 治理 | 分支仍指向 graphdb/vector 扩展 | 主线已经落入 relation-path + temporal-validity 的 explainable retrieval；独立 query scoring 已抽到 `src/learning/queryBackend.ts`，但 persistence 仍是 file-backed，且 vector 独立性仍缺失（`src/learning/KnowledgeLearningPlatform.ts`、`src/learning/store.ts`） | M8：保持 readiness 诚实，再补 vector 边界 |
+| L2 检索层 | 可解释混合/向量检索 + 治理 | 分支仍指向 graphdb/vector 扩展 | 主线已经落入 relation-path + temporal-validity 的 explainable retrieval；独立 query scoring 已抽到 `src/learning/queryBackend.ts`，vector 预筛选打分已抽到 `src/learning/vectorAccelerationAdapter.ts`，但 persistence 仍是 file-backed，且独立 ANN 证据仍缺失（`src/learning/KnowledgeLearningPlatform.ts`、`src/learning/store.ts`） | M8：保持 readiness 诚实，直到独立向量证据落地 |
 | L3 学习层 | 掌握诊断 + 路径/会话闭环 | 分支增强中 | 主线已经集成 path/session/misconception/memory 流并有 persistence 测试 | 保持基线，不再低估 |
 | L4 交互层 | agent 对话 + focus/path pane 运行时 | 分支已实现 | 主线已经集成 typed contract routing、conversation shell、focus mode 与 path dock coexistence | 仅通过 typed contract 扩展 |
 | L5 治理层 | runbook/诊断/回放与自动化 | 分支增强中 | 主线已集成运维诊断持久化/分级/趋势历史/阈值治理 + runbook 自动化/阈值审计 + 自适应模拟/自动修复 + 回测/批准门禁 + 批准策略硬化/回归告警 + 批准策略漂移/升级 + 升级确认生命周期/审计 + 升级 SLA/提醒基线 + 通知摘要/抑制基线 + 交付日志可观测性 + 陈旧通知健康审计 + 异常/retention 治理 + 通知 SLO 治理 + 通知阈值覆盖/审计治理 + 回滚预览/drift-diff 治理 + 回滚 apply guardrails + latest apply-outcome reconciliation + bounded apply-outcome history + supersession summary + 组合 status/appliedMode 过滤历史 | M7.29 后停止此 lane，转向 M8 foundation readiness |
@@ -778,7 +793,7 @@ npm test -- src/learning/KnowledgeLearningPlatform.persistence.test.ts --runInBa
 ## 后续方向（当前优先级）
 
 1. 将 notification-threshold 治理链路视为在 `M7.29` 后已收口；没有新的强运维需求前，不再规划 `M7.30+`。
-2. 继续按 `M8 foundation re-entry readiness execution` 推进：先固化证据打包与防超前宣称护栏，再推进 adapter-boundary 代码，不要反过来。
+2. 继续按 `M8 foundation re-entry readiness execution` 推进：证据打包与防超前宣称护栏已先落地，query/vector 边界也已补齐，但在更强证据进入主线前，不能把当前 prefilter-only 路径说成独立 ANN 就绪。
 3. 每次 lane 切换都保持 docs、agent-workspace 与 learning-core 门禁为绿色，确保事实与门禁同步。
 4. 每次主线方向切换前先重算文档事实，避免过时 branch-gap 语言继续污染状态结论。
 5. Markdown 阅读器治理继续保持受限且次优先级，直到 post-M7 主线切换被明确规划。

docs/diataxis/zh/explanation/foundation-reentry-readiness-checklist.md

@@ -51,7 +51,10 @@
 - 当前主线的预期结果是：
   - 状态 `In Progress`
   - 决策 `No-Go`
-  - 原因：file-backed 基线已存在，且 query-backend 边界已落入主线，但 vector adapter 独立性仍未进入主线。
+  - 原因：file-backed 基线已存在，query-backend 与 vector 边界都已进入主线，但该 vector adapter 仍只是 `prefilter_only`，独立 ANN 证据仍未进入主线。
+- readiness 载荷现在也显式区分这层语义：
+  - `vectorAdapterStatus`
+  - `vectorAdapterIndependent`
 
 ## 防超前宣称策略
 

scripts/foundation-readiness-utils.js

@@ -25,6 +25,19 @@ function fileExists(filePath) {
   }
 }
 
+function resolveVectorAdapterStatus(vectorAdapterSource, vectorAdapterModulePresent) {
+  if (!vectorAdapterModulePresent) {
+    return 'absent';
+  }
+
+  const statusMatch = vectorAdapterSource.match(/VECTOR_ACCELERATION_ADAPTER_STATUS\s*=\s*['"]([^'"]+)['"]/);
+  if (statusMatch && statusMatch[1] === 'independent') {
+    return 'independent';
+  }
+
+  return 'prefilter_only';
+}
+
 function evaluateFoundationReadiness(options = {}) {
   const repoRoot = options.repoRoot || path.resolve(__dirname, '..');
   const packageJson = readJsonIfExists(path.join(repoRoot, 'package.json'));
@@ -67,6 +80,7 @@ function evaluateFoundationReadiness(options = {}) {
   );
 
   const storeSource = readTextIfExists(storePath);
+  const vectorAdapterSource = readTextIfExists(vectorAdapterPath);
   const enDashboard = readTextIfExists(enDashboardPath);
   const zhDashboard = readTextIfExists(zhDashboardPath);
   const storeModulePresent = fileExists(storePath);
@@ -76,6 +90,8 @@ function evaluateFoundationReadiness(options = {}) {
     && storeSource.includes("storeType: 'file'");
   const graphAdapterModulePresent = fileExists(graphAdapterPath);
   const vectorAdapterModulePresent = fileExists(vectorAdapterPath);
+  const vectorAdapterStatus = resolveVectorAdapterStatus(vectorAdapterSource, vectorAdapterModulePresent);
+  const vectorAdapterIndependent = vectorAdapterStatus === 'independent';
   const checklistPagesPresent = fileExists(enChecklistPath) && fileExists(zhChecklistPath);
   const dashboardReferencesPresent =
     enDashboard.includes('foundation-reentry-readiness-checklist')
@@ -92,7 +108,7 @@ function evaluateFoundationReadiness(options = {}) {
     baselineReady
     && readinessVerifierPresent
     && graphAdapterModulePresent
-    && vectorAdapterModulePresent
+    && vectorAdapterIndependent
   ) {
     status = 'integrated';
     decision = 'go';
@@ -143,6 +159,10 @@ function evaluateFoundationReadiness(options = {}) {
     recommendations.push(
       'Keep foundation re-entry at no-go while vector adapter independence remains absent on mainline.'
     );
+  } else if (!vectorAdapterIndependent) {
+    recommendations.push(
+      'Keep foundation re-entry at no-go while the vector adapter remains a local prefilter boundary without independent ANN evidence on mainline.'
+    );
   }
 
   if (!checklistPagesPresent || !dashboardReferencesPresent) {
@@ -174,6 +194,8 @@ function evaluateFoundationReadiness(options = {}) {
       fileBackedStore,
       graphAdapterModulePresent,
       vectorAdapterModulePresent,
+      vectorAdapterStatus,
+      vectorAdapterIndependent,
     },
     documents: {
       checklistPagesPresent,
@@ -203,6 +225,8 @@ function formatFoundationReadinessMarkdown(result, reportPaths) {
     `- File-backed store evidence: ${result.baseline.fileBackedStore ? 'yes' : 'no'}`,
     `- Dedicated graph adapter module present: ${result.baseline.graphAdapterModulePresent ? 'yes' : 'no'}`,
     `- Dedicated vector adapter module present: ${result.baseline.vectorAdapterModulePresent ? 'yes' : 'no'}`,
+    `- Vector adapter status: ${result.baseline.vectorAdapterStatus}`,
+    `- Vector adapter independent: ${result.baseline.vectorAdapterIndependent ? 'yes' : 'no'}`,
     '',
     '## Documentation',
     '',