feat(learning): extract query backend boundary

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 still does **not** contain separate graphdb/vector adapter modules that would justify claiming foundation re-entry completion.
+  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.
 
 ## 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, but persistence remains file-backed and no separate graphdb/vector adapter boundary has landed | Advanced baseline, foundation lane not re-entered | do not overclaim graphdb/vector readiness |
+| 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 |
 | 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.2)
+## Execution Note (2026-04-20 M8.1-M8.3)
 
 - The smallest executed post-M7 slice is now an evidence bundle, not an adapter claim:
   - `npm run verify:foundation:readiness`
@@ -173,10 +173,13 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
   - `FoundationReadinessReport` / `FoundationReadinessAPI`
   - `GET /api/knowledge/foundation/readiness`
 - The readiness route is required to preserve honest repo-truth even under hermetic runtime/test roots.
+- 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.
 - Current expected outcome on `main` remains:
   - status `in_progress`
   - decision `no-go`
-  - reason: mainline still lacks dedicated graph/vector adapter modules.
+  - reason: mainline still lacks vector adapter independence and still remains file-backed.
 - This closes the earlier planning question about the smallest executable readiness slice:
   - answer: make the anti-overclaim baseline inspectable first, then decide adapter-boundary code with fresher evidence.
 

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.3 Query Backend Boundary Extraction)
+
+- Extracted the live retrieval scoring path into a dedicated module:
+  - `src/learning/queryBackend.ts`
+- Kept the current mainline external behavior stable:
+  - `KnowledgeLearningPlatform.queryKnowledge(...)` still returns the same API shape,
+  - relation-path, temporal-validity, and evidence payload wiring remain in `src/learning/KnowledgeLearningPlatform.ts`.
+- Added direct regression coverage for backend scoring discipline:
+  - `src/learning/queryBackend.test.ts`
+- Kept foundation honesty intact:
+  - dedicated query-backend boundary is now present on `main`,
+  - vector adapter independence is still absent,
+  - readiness therefore remains `in_progress` / `no-go`.
+
 ## Latest Mainline Increment (2026-04-20 M8.2 Foundation Readiness API Surface)
 
 - Added a typed foundation-readiness contract surface on mainline:
@@ -665,7 +679,8 @@ Execution anchor:
 - Kept the scope evidence-first instead of inventing unfinished adapter claims:
   - current result is expected to stay `in_progress` / `no-go` on `main`,
   - file-backed persistence remains the verified baseline,
-  - dedicated `queryBackend` and `vectorAccelerationAdapter` modules are still absent on `main`.
+  - dedicated `queryBackend` is now present on `main`,
+  - dedicated `vectorAccelerationAdapter` 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`
@@ -718,7 +733,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`, but persistence is still file-backed (`src/learning/KnowledgeLearningPlatform.ts`, `src/learning/store.ts`) | M8: foundation re-entry readiness, evidence-first |
+| 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 |
 | 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 |

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

@@ -51,7 +51,7 @@ Bundle note:
 - Current expected result on `main` is:
   - status `In Progress`
   - decision `No-Go`
-  - rationale: file-backed baseline exists, but dedicated graph/vector adapter modules are still absent.
+  - rationale: file-backed baseline exists and query-backend boundary is now present, but vector adapter independence is still absent.
 
 ## 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.3 Query Backend 边界抽取）
+
+- 已把当前主线真实使用的检索打分路径抽到独立模块：
+  - `src/learning/queryBackend.ts`
+- 保持当前主线外部行为稳定：
+  - `KnowledgeLearningPlatform.queryKnowledge(...)` 的 API 形状不变，
+  - relation-path、temporal-validity、evidence 载荷仍由 `src/learning/KnowledgeLearningPlatform.ts` 负责组装。
+- 已补 query backend 直测回归：
+  - `src/learning/queryBackend.test.ts`
+- 仍保持 foundation 诚实状态：
+  - 主线现在已有独立 query-backend 边界，
+  - 但 vector adapter 独立性仍未进入主线，
+  - readiness 仍应保持 `in_progress` / `no-go`。
+
 ## 主线最新增量（2026-04-20 M8.2 Foundation Readiness API 面）
 
 - 已在主线补齐 typed foundation-readiness 合同面：
@@ -668,7 +682,8 @@
 - 当前实现坚持 evidence-first，而不是虚构尚未落地的 adapter 结论：
   - 主线当前预期结果保持 `in_progress` / `no-go`，
   - file-backed persistence 仍是已验证基线，
-  - 主线仍不存在独立 `queryBackend` 与 `vectorAccelerationAdapter` 模块。
+  - 主线现在已有独立 `queryBackend`，
+  - 但 `vectorAccelerationAdapter` 仍未进入主线。
 - 已为运维/文档核对补齐机器可读产物：
   - `build/foundation-readiness/foundation-readiness-latest.json`
   - `build/foundation-readiness/foundation-readiness-latest.md`
@@ -721,7 +736,7 @@
 |---|---|---|---|---|
 | L0 表示层 | 原子/证据提取 + staleness | 稳定 | 稳定 | 无紧急阻塞 |
 | L1 结构层 | 关系 + 时序图语义 | 稳定 | 稳定 | 无紧急阻塞 |
-| L2 检索层 | 可解释混合/向量检索 + 治理 | 分支仍指向 graphdb/vector 扩展 | 主线已经落入 relation-path + temporal-validity 的 explainable retrieval，但 persistence 仍是 file-backed（`src/learning/KnowledgeLearningPlatform.ts`、`src/learning/store.ts`） | M8：foundation re-entry readiness，evidence-first |
+| 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 边界 |
 | 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 |

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

@@ -51,7 +51,7 @@
 - 当前主线的预期结果是：
   - 状态 `In Progress`
   - 决策 `No-Go`
-  - 原因：file-backed 基线已存在，但 dedicated graph/vector adapter 模块仍未进入主线。
+  - 原因：file-backed 基线已存在，且 query-backend 边界已落入主线，但 vector adapter 独立性仍未进入主线。
 
 ## 防超前宣称策略
 

package.json

@@ -86,7 +86,7 @@
     "ops:fixrisk:close": "node scripts/run-fixrisk-ops-closure.js",
     "ops:fixrisk:close:dry": "node scripts/run-fixrisk-ops-closure.js --dry-run",
     "test:mobile:contracts": "jest src/mobile.pipeline.test.ts src/runtime.capabilities.test.ts src/source_manager.loadflow.test.ts src/capacitor.runtime.contract.test.ts src/android.pathmode.contract.test.ts src/android.pathmode.smoke.contract.test.ts src/graph.accessibility.contract.test.ts src/detox.pipeline.contract.test.ts src/privacy.manifest.contract.test.ts --runInBand && npm run verify:detox:pipeline && npm run verify:privacy:manifest",
-    "test:migration": "jest src/core/Graph.test.ts src/core/PathEngine.test.ts src/core/TreeLayout.test.ts src/backend/algorithms/CycleDetection.test.ts src/backend/algorithms/TopologicalSort.test.ts src/backend/algorithms/WasmParityHistory.test.ts src/utils/RuntimePaths.test.ts src/server.migration.test.ts src/pkg.sidecar.contract.test.ts src/pkg.snapshot.safety.contract.test.ts src/godot.sidecar.bootstrap.contract.test.ts src/release.godot.mirror.contract.test.ts src/sidecar.replacement.boundary.contract.test.ts src/sidecar.supply.readiness.contract.test.ts src/foundation.readiness.contract.test.ts src/lfs.asset.policy.contract.test.ts src/tauri.frontend.build.contract.test.ts src/mobile.pipeline.test.ts src/capacitor.device.utils.contract.test.ts src/capacitor.evidence.contract.test.ts src/runtime.capabilities.test.ts src/runtime.heap.policy.contract.test.ts src/runtime.spool.policy.contract.test.ts src/runtime.transport.adapter.contract.test.ts src/storage.provider.contract.test.ts src/storage.provider.capacitor.content.contract.test.ts src/storage.provider.capacitor.worker.contract.test.ts src/wasm.parity.runtime.contract.test.ts src/wasm.parity.runtime.functional.test.ts src/wasm.parity.output.equivalence.contract.test.ts src/wasm.parity.benchmark.contract.test.ts src/wasm.parity.benchmark.guards.contract.test.ts src/wasm.parity.history.gate.contract.test.ts src/wasm.parity.artifact.probe.contract.test.ts src/wasm.parity.artifact.provisioning.contract.test.ts src/source_manager.loadflow.test.ts src/capacitor.runtime.contract.test.ts src/welcome.loadflow.test.ts src/pathmode.history.contract.test.ts src/android.pathmode.contract.test.ts src/android.pathmode.smoke.contract.test.ts src/pathbridge.handshake.contract.test.ts src/pathbridge.strict.policy.contract.test.ts src/graph.accessibility.contract.test.ts src/detox.pipeline.contract.test.ts src/privacy.manifest.contract.test.ts src/server.port.fallback.contract.test.ts src/sidecar.signature.contract.test.ts src/sbom.policy.contract.test.ts src/sbom.attestation.policy.contract.test.ts src/sidecar.relaunch.contract.test.ts src/tauri.test.runner.contract.test.ts --runInBand",
+    "test:migration": "jest src/core/Graph.test.ts src/core/PathEngine.test.ts src/core/TreeLayout.test.ts src/backend/algorithms/CycleDetection.test.ts src/backend/algorithms/TopologicalSort.test.ts src/backend/algorithms/WasmParityHistory.test.ts src/utils/RuntimePaths.test.ts src/server.migration.test.ts src/pkg.sidecar.contract.test.ts src/pkg.snapshot.safety.contract.test.ts src/godot.sidecar.bootstrap.contract.test.ts src/release.godot.mirror.contract.test.ts src/sidecar.replacement.boundary.contract.test.ts src/sidecar.supply.readiness.contract.test.ts src/foundation.readiness.contract.test.ts src/learning/queryBackend.test.ts src/lfs.asset.policy.contract.test.ts src/tauri.frontend.build.contract.test.ts src/mobile.pipeline.test.ts src/capacitor.device.utils.contract.test.ts src/capacitor.evidence.contract.test.ts src/runtime.capabilities.test.ts src/runtime.heap.policy.contract.test.ts src/runtime.spool.policy.contract.test.ts src/runtime.transport.adapter.contract.test.ts src/storage.provider.contract.test.ts src/storage.provider.capacitor.content.contract.test.ts src/storage.provider.capacitor.worker.contract.test.ts src/wasm.parity.runtime.contract.test.ts src/wasm.parity.runtime.functional.test.ts src/wasm.parity.output.equivalence.contract.test.ts src/wasm.parity.benchmark.contract.test.ts src/wasm.parity.benchmark.guards.contract.test.ts src/wasm.parity.history.gate.contract.test.ts src/wasm.parity.artifact.probe.contract.test.ts src/wasm.parity.artifact.provisioning.contract.test.ts src/source_manager.loadflow.test.ts src/capacitor.runtime.contract.test.ts src/welcome.loadflow.test.ts src/pathmode.history.contract.test.ts src/android.pathmode.contract.test.ts src/android.pathmode.smoke.contract.test.ts src/pathbridge.handshake.contract.test.ts src/pathbridge.strict.policy.contract.test.ts src/graph.accessibility.contract.test.ts src/detox.pipeline.contract.test.ts src/privacy.manifest.contract.test.ts src/server.port.fallback.contract.test.ts src/sidecar.signature.contract.test.ts src/sbom.policy.contract.test.ts src/sbom.attestation.policy.contract.test.ts src/sidecar.relaunch.contract.test.ts src/tauri.test.runner.contract.test.ts --runInBand",
     "test:tauri": "node scripts/run-tauri-tests.js",
     "test:agent-workspace:contracts": "jest src/agent_workspace.contract.parity.test.ts src/agent_workspace.frontend.test.ts src/agent_workspace.runtime.integration.test.ts src/agent_workspace.runtime.behavior.test.ts src/agent_workspace.verification.contract.test.ts src/knowledge.api.contract.test.ts --runInBand",
     "test:license:contract": "jest src/license.policy.contract.test.ts --runInBand",

scripts/foundation-readiness-utils.js

@@ -131,10 +131,18 @@ function evaluateFoundationReadiness(options = {}) {
     );
   }
 
-  if (!graphAdapterModulePresent || !vectorAdapterModulePresent) {
+  if (!graphAdapterModulePresent && !vectorAdapterModulePresent) {
     recommendations.push(
       'Do not claim foundation re-entry integrated while dedicated graph/vector adapter modules remain absent on mainline.'
     );
+  } else if (!graphAdapterModulePresent) {
+    recommendations.push(
+      'Keep foundation re-entry at no-go while a dedicated query backend boundary is still absent on mainline.'
+    );
+  } else if (!vectorAdapterModulePresent) {
+    recommendations.push(
+      'Keep foundation re-entry at no-go while vector adapter independence remains absent on mainline.'
+    );
   }
 
   if (!checklistPagesPresent || !dashboardReferencesPresent) {

src/foundation.readiness.contract.test.ts

@@ -105,13 +105,13 @@ describe('foundation readiness contract', () => {
     expect(result.baseline.exists).toBe(true);
     expect(result.baseline.loaded).toBe(true);
     expect(result.baseline.fileBackedStore).toBe(true);
-    expect(result.baseline.graphAdapterModulePresent).toBe(false);
+    expect(result.baseline.graphAdapterModulePresent).toBe(true);
     expect(result.baseline.vectorAdapterModulePresent).toBe(false);
     expect(result.documents.checklistPagesPresent).toBe(true);
     expect(result.documents.dashboardReferencesPresent).toBe(true);
     expect(result.packageScripts.readinessVerifierPresent).toBe(true);
     expect(result.recommendations).toContain(
-      'Do not claim foundation re-entry integrated while dedicated graph/vector adapter modules remain absent on mainline.'
+      'Keep foundation re-entry at no-go while vector adapter independence remains absent on mainline.'
     );
   });