feat: tighten graph readiness semantics

Author: Jacobinwwey

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

@@ -198,6 +198,12 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
   - readiness now reports `vectorAdapterSignalKind`
   - current mainline truth is now machine-readable as lexical-prefilter semantics rather than an ambiguous "vector" label
   - overall status still remains `in_progress` / `no-go`, because lexical overlap evidence is still not ANN evidence.
+- The next bounded execution slice after that makes graph-backend semantics explicit and closes a readiness loophole:
+  - readiness now reports `graphBackendStatus`
+  - readiness now reports `graphBackendSignalKind`
+  - readiness now reports `graphBackendIndependent`
+  - integrated readiness now requires independent graph-backend evidence in addition to independent vector evidence
+  - overall status still remains `in_progress` / `no-go`, because current mainline persistence is still file-backed snapshot-only.
 - Current expected outcome on `main` remains:
   - status `in_progress`
   - decision `no-go`

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

@@ -275,6 +275,28 @@ Execution anchor:
   - decision stays `no-go`,
   - no ANN readiness claim is permitted from lexical-prefilter evidence alone.
 
+## Latest Mainline Increment (2026-04-20 M8.10 Foundation Graph-Backend Semantics Evidence)
+
+- Tightened foundation readiness so file-backed snapshot persistence can no longer be mistaken for graph-backend re-entry:
+  - `FoundationReadinessReport.baseline` now includes `graphBackendStatus`,
+  - `FoundationReadinessReport.baseline` now includes `graphBackendSignalKind`,
+  - `FoundationReadinessReport.baseline` now includes `graphBackendIndependent`.
+- Readiness promotion logic is now stricter and matches the actual roadmap gap:
+  - independent vector evidence alone is not enough,
+  - integrated readiness now also requires independent graph-backend evidence.
+- Current mainline truth is now explicit:
+  - `graphBackendStatus = file_snapshot_only`
+  - `graphBackendSignalKind = json_snapshot_file`
+  - `graphBackendIndependent = false`
+- Operator/runtime inspectability stayed aligned:
+  - `scripts/verify-foundation-readiness.js` prints graph-backend semantics,
+  - `src/frontend/agent_workspace_runtime.js` persists the same graph fields in `lastFoundationReadiness`,
+  - toolbar summaries now show graph status and signal kind alongside query/vector semantics.
+- Guardrail remains unchanged on `main`:
+  - status stays `in_progress`,
+  - decision stays `no-go`,
+  - file snapshots still do not qualify as independent graph backend readiness.
+
 ## Latest Mainline Increment (2026-04-16 M7.2 Runtime Evidence Deepening Lane)
 
 - Expanded runtime behavior coverage in `src/agent_workspace.runtime.behavior.test.ts` for pane lifecycle evidence:

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

@@ -55,18 +55,27 @@ Bundle note:
 - Current expected result on `main` is:
   - status `In Progress`
   - decision `No-Go`
-  - 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.
+  - rationale: mainline persistence is still `file_snapshot_only`, query-backend and vector-boundary modules are present, but graph-backend independence is absent and the vector adapter is still only `prefilter_only`, so independent graph/ANN evidence is still absent.
 - The readiness payload now makes that distinction explicit:
+  - `graphBackendStatus`
+  - `graphBackendSignalKind`
+  - `graphBackendIndependent`
   - `queryBackendDefaultMode`
   - `queryBackendScoreSignals`
   - `vectorAdapterLinkedIntoQueryBackend`
   - `vectorAdapterStatus`
   - `vectorAdapterSignalKind`
   - `vectorAdapterIndependent`
+- Current expected graph semantics on `main` are:
+  - `graphBackendStatus = file_snapshot_only`
+  - `graphBackendSignalKind = json_snapshot_file`
+  - `graphBackendIndependent = false`
 - Current expected signal semantics on `main` are:
   - `queryBackendScoreSignals = [keyword_matches, title_match_bonus, vector_prefilter_content_bonus, relation_bonus]`
   - `vectorAdapterSignalKind = lexical_token_overlap`
 - Interpretation rule:
+  - `file_snapshot_only` is evidence of snapshot persistence only.
+  - It is **not** evidence of independent graph-backend semantics.
   - `lexical_token_overlap` is evidence of lexical prefilter scoring only.
   - It is **not** evidence of embedding-backed ANN readiness.
 

docs/diataxis/en/explanation/knowledge-mastery-evolution-roadmap.md

@@ -53,8 +53,8 @@ This requires:
 ## Primary Structural Gaps Still Open
 
 1. Graph persistence depth:
-   - `graphdb` mode currently relies on `FileGraphDbSnapshotAdapter` in `src/learning/store.ts`.
-   - this preserves fallback reliability but does not yet deliver a true local graph database backend.
+   - `src/learning/store.ts` currently exposes file-backed snapshot persistence as the verified mainline baseline.
+   - no independent local graph database backend is integrated on `main` yet.
 2. Vector retrieval independence:
    - retrieval currently uses `local_hybrid` token/semantic heuristics and `keyword_only` fallback in `src/learning/queryBackend.ts`.
    - a standalone vector index backend is not integrated yet.

docs/diataxis/en/reference/release-and-governance.md

@@ -105,7 +105,7 @@ npm run test:migration
   - API contract surface coverage
   - runtime runbook and diagnostics endpoints
 - Needs continued hardening:
-  - graphdb backend depth (current graphdb mode still file-adapter backed)
+  - graph backend depth (current mainline persistence is still file-backed snapshot-only)
   - independent vector retrieval backend integration
   - stricter promotion from trend observations to hard release quality gates
 

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

@@ -275,6 +275,28 @@
   - 决策仍为 `no-go`，
   - 不能把 lexical-prefilter 证据误写成 ANN readiness。
 
+## 主线最新增量（2026-04-20 M8.10 Foundation 图后端语义证据）
+
+- 已加固 foundation readiness，避免把 file-backed snapshot persistence 误读成 graph backend 回归：
+  - `FoundationReadinessReport.baseline` 新增 `graphBackendStatus`，
+  - `FoundationReadinessReport.baseline` 新增 `graphBackendSignalKind`，
+  - `FoundationReadinessReport.baseline` 新增 `graphBackendIndependent`。
+- readiness 升级逻辑现在更严格，也更符合真实路线图缺口：
+  - 只有独立 vector 证据还不够，
+  - 要进入 integrated readiness，还必须同时具备独立 graph backend 证据。
+- 当前主线事实现在已显式化：
+  - `graphBackendStatus = file_snapshot_only`
+  - `graphBackendSignalKind = json_snapshot_file`
+  - `graphBackendIndependent = false`
+- 执行侧/运行时可观测性保持对齐：
+  - `scripts/verify-foundation-readiness.js` 现在输出图后端语义，
+  - `src/frontend/agent_workspace_runtime.js` 会在 `lastFoundationReadiness` 中保留同样字段，
+  - 工具栏摘要现在会同时展示图后端状态与信号类型。
+- `main` 上的护栏结论保持不变：
+  - 状态仍为 `in_progress`，
+  - 决策仍为 `no-go`，
+  - file snapshot 仍不构成独立 graph backend readiness。
+
 ## 主线最新增量（2026-04-16 M7.2 运行时证据加深链路）
 
 - 已在 `src/agent_workspace.runtime.behavior.test.ts` 扩展 pane 生命周期证据覆盖：

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

@@ -55,18 +55,27 @@
 - 当前主线的预期结果是：
   - 状态 `In Progress`
   - 决策 `No-Go`
-  - 原因：file-backed 基线已存在，query-backend 与 vector 边界都已进入主线，但该 vector adapter 仍只是 `prefilter_only`，独立 ANN 证据仍未进入主线。
+  - 原因：主线 persistence 仍是 `file_snapshot_only`，query-backend 与 vector 边界虽已进入主线，但 graph backend 独立性仍缺失，且 vector adapter 仍只是 `prefilter_only`，因此独立 graph/ANN 证据仍未进入主线。
 - readiness 载荷现在也显式区分这层语义：
+  - `graphBackendStatus`
+  - `graphBackendSignalKind`
+  - `graphBackendIndependent`
   - `queryBackendDefaultMode`
   - `queryBackendScoreSignals`
   - `vectorAdapterLinkedIntoQueryBackend`
   - `vectorAdapterStatus`
   - `vectorAdapterSignalKind`
   - `vectorAdapterIndependent`
+- 当前 `main` 的图后端预期语义为：
+  - `graphBackendStatus = file_snapshot_only`
+  - `graphBackendSignalKind = json_snapshot_file`
+  - `graphBackendIndependent = false`
 - 当前 `main` 的预期信号语义为：
   - `queryBackendScoreSignals = [keyword_matches, title_match_bonus, vector_prefilter_content_bonus, relation_bonus]`
   - `vectorAdapterSignalKind = lexical_token_overlap`
 - 解读规则：
+  - `file_snapshot_only` 只表示 snapshot persistence 存在。
+  - 它**不等于**独立 graph backend 语义已成立。
   - `lexical_token_overlap` 只表示词法预过滤打分存在。
   - 它**不等于** embedding/ANN readiness 已经成立。
 

docs/diataxis/zh/explanation/knowledge-mastery-evolution-roadmap.md

@@ -52,8 +52,8 @@
 ## 当前仍需优先补齐的结构缺口
 
 1. 图存储深度不足：
-   - `src/learning/store.ts` 的 `graphdb` 当前仍依赖 `FileGraphDbSnapshotAdapter`。
-   - 具备 fallback 稳定性，但尚未达到“真实本地图数据库后端”目标。
+   - `src/learning/store.ts` 当前在主线仅提供 file-backed snapshot persistence 基线。
+   - `main` 尚未集成独立的本地图数据库图后端。
 2. 向量检索独立性不足：
    - `src/learning/queryBackend.ts` 目前是 `local_hybrid` 与 `keyword_only` 两路。
    - 尚未接入独立向量索引后端。

docs/diataxis/zh/reference/release-and-governance.md

@@ -105,7 +105,7 @@ npm run test:migration
   - API 契约覆盖
   - runtime runbook 与诊断端点
 - 需持续补强：
-  - graphdb 后端深度（当前仍是 file-adapter 模式）
+  - 图后端深度（当前主线仍是 file-backed snapshot-only）
   - 独立向量检索后端接入
   - 将趋势观察进一步升级为硬发布门禁
 

scripts/foundation-readiness-utils.js

@@ -51,6 +51,53 @@ function resolveQueryBackendDefaultMode(queryBackendSource, graphAdapterModulePr
   return 'unknown';
 }
 
+function resolveGraphBackendSignalKind(storeSource, storeModulePresent, fileBackedStore) {
+  if (!storeModulePresent) {
+    return 'absent';
+  }
+
+  if (fileBackedStore) {
+    return 'json_snapshot_file';
+  }
+
+  if (
+    /better-sqlite3/i.test(storeSource)
+    || /\bsqlite\b/i.test(storeSource)
+    || /createSqliteKnowledgeGraphStore/.test(storeSource)
+    || /createLocalGraphDbStore/.test(storeSource)
+  ) {
+    return 'embedded_graphdb';
+  }
+
+  if (
+    /neo4j/i.test(storeSource)
+    || /cypher/i.test(storeSource)
+    || /GraphDbClient/.test(storeSource)
+    || /createExternalGraphDbStore/.test(storeSource)
+  ) {
+    return 'external_graphdb';
+  }
+
+  return 'unknown';
+}
+
+function resolveGraphBackendStatus(storeSource, storeModulePresent, fileBackedStore) {
+  if (!storeModulePresent) {
+    return 'absent';
+  }
+
+  if (fileBackedStore) {
+    return 'file_snapshot_only';
+  }
+
+  const signalKind = resolveGraphBackendSignalKind(storeSource, storeModulePresent, fileBackedStore);
+  if (signalKind === 'embedded_graphdb' || signalKind === 'external_graphdb') {
+    return 'independent';
+  }
+
+  return 'unknown';
+}
+
 function resolveQueryBackendScoreSignals(queryBackendSource, graphAdapterModulePresent) {
   if (!graphAdapterModulePresent) {
     return [];
@@ -153,6 +200,9 @@ function evaluateFoundationReadiness(options = {}) {
   const fileBackedStore =
     storeSource.includes('createFileBackedKnowledgeGraphStore')
     && storeSource.includes("storeType: 'file'");
+  const graphBackendStatus = resolveGraphBackendStatus(storeSource, storeModulePresent, fileBackedStore);
+  const graphBackendSignalKind = resolveGraphBackendSignalKind(storeSource, storeModulePresent, fileBackedStore);
+  const graphBackendIndependent = graphBackendStatus === 'independent';
   const graphAdapterModulePresent = fileExists(graphAdapterPath);
   const queryBackendDefaultMode = resolveQueryBackendDefaultMode(queryBackendSource, graphAdapterModulePresent);
   const queryBackendScoreSignals = resolveQueryBackendScoreSignals(
@@ -177,14 +227,15 @@ function evaluateFoundationReadiness(options = {}) {
   const readinessVerifierPresent =
     scripts['verify:foundation:readiness'] === 'node scripts/verify-foundation-readiness.js';
 
-  const baselineReady = fileBackedStore && checklistPagesPresent && dashboardReferencesPresent;
+  const baselineReady = storeModulePresent && checklistPagesPresent && dashboardReferencesPresent;
 
   let status = 'planned';
   let decision = 'no-go';
 
   if (
     baselineReady
     && readinessVerifierPresent
+    && graphBackendIndependent
     && graphAdapterModulePresent
     && vectorAdapterIndependent
   ) {
@@ -219,9 +270,21 @@ function evaluateFoundationReadiness(options = {}) {
 
   const recommendations = [];
 
-  if (!fileBackedStore) {
+  if (!fileBackedStore && !graphBackendIndependent) {
+    recommendations.push(
+      'Keep foundation re-entry at no-go until store backend evidence is explicit enough to distinguish file snapshots from a real graph backend on mainline.'
+    );
+  }
+
+  if (!storeModulePresent) {
+    recommendations.push(
+      'Restore explicit store backend evidence before advancing foundation readiness claims.'
+    );
+  }
+
+  if (!graphBackendIndependent) {
     recommendations.push(
-      'Restore explicit file-backed store evidence before advancing foundation readiness claims.'
+      'Keep foundation re-entry at no-go while graph persistence remains file-backed snapshot storage without independent graph backend semantics on mainline.'
     );
   }
 
@@ -270,6 +333,9 @@ function evaluateFoundationReadiness(options = {}) {
       exists: storeModulePresent,
       loaded: storeModulePresent && storeSource.includes('loadSnapshot'),
       fileBackedStore,
+      graphBackendStatus,
+      graphBackendSignalKind,
+      graphBackendIndependent,
       graphAdapterModulePresent,
       queryBackendDefaultMode,
       queryBackendScoreSignals,
@@ -305,6 +371,9 @@ function formatFoundationReadinessMarkdown(result, reportPaths) {
     `- Store evidence present: ${result.baseline.exists ? 'yes' : 'no'}`,
     `- Store load capability present: ${result.baseline.loaded ? 'yes' : 'no'}`,
     `- File-backed store evidence: ${result.baseline.fileBackedStore ? 'yes' : 'no'}`,
+    `- Graph backend status: ${result.baseline.graphBackendStatus}`,
+    `- Graph backend signal kind: ${result.baseline.graphBackendSignalKind}`,
+    `- Graph backend independent: ${result.baseline.graphBackendIndependent ? 'yes' : 'no'}`,
     `- Dedicated graph adapter module present: ${result.baseline.graphAdapterModulePresent ? 'yes' : 'no'}`,
     `- Query backend default mode: ${result.baseline.queryBackendDefaultMode}`,
     `- Query backend score signals: ${result.baseline.queryBackendScoreSignals.join(', ') || 'none'}`,