feat(knowledge): expose foundation readiness api

Author: Jacobinwwey

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

@@ -162,13 +162,17 @@ 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)
+## Execution Note (2026-04-20 M8.1-M8.2)
 
 - The smallest executed post-M7 slice is now an evidence bundle, not an adapter claim:
   - `npm run verify:foundation:readiness`
 - The bundle writes machine-readable baseline reports:
   - `build/foundation-readiness/foundation-readiness-latest.json`
   - `build/foundation-readiness/foundation-readiness-latest.md`
+- The next bounded execution slice exposes the same baseline through typed runtime/API surfaces:
+  - `FoundationReadinessReport` / `FoundationReadinessAPI`
+  - `GET /api/knowledge/foundation/readiness`
+- The readiness route is required to preserve honest repo-truth even under hermetic runtime/test roots.
 - Current expected outcome on `main` remains:
   - status `in_progress`
   - decision `no-go`

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

@@ -639,6 +639,25 @@ Execution anchor:
   - `npm run docs:diataxis:check`
   - `npm run docs:site:build`
 
+## Latest Mainline Increment (2026-04-20 M8.2 Foundation Readiness API Surface)
+
+- Added a typed foundation-readiness contract surface on mainline:
+  - `FoundationReadinessReport` in `src/learning/types.ts`
+  - `FoundationReadinessAPI` in `src/learning/api.ts`
+  - `getFoundationReadiness()` in `src/learning/KnowledgeLearningPlatform.ts`
+- Added operator/frontend-readable route wiring:
+  - `GET /api/knowledge/foundation/readiness` in `src/server.ts`
+- Kept the scope evidence-first:
+  - the route exposes current `in_progress` / `no-go` readiness state,
+  - it does not claim graph/vector adapter integration that is still absent on `main`.
+- Hardened repo-root resolution so readiness truth remains correct in hermetic runtime/test project roots:
+  - explicit runtime roots are accepted when valid,
+  - fallback resolution still locates the real repo evidence bundle when temp runtime roots do not contain docs/package metadata.
+- Expanded regression coverage for the new API surface:
+  - `src/knowledge.api.contract.test.ts`
+  - `src/learning/KnowledgeLearningPlatform.test.ts`
+  - `src/server.migration.test.ts`
+
 ## Latest Mainline Increment (2026-04-20 M8.1 Foundation Readiness Evidence Bundle)
 
 - Added a dedicated readiness verifier for the post-M7 foundation lane:

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

@@ -46,6 +46,8 @@ Bundle note:
 - It packages current mainline truth into:
   - `build/foundation-readiness/foundation-readiness-latest.json`
   - `build/foundation-readiness/foundation-readiness-latest.md`
+- The same bounded readiness payload is also exposed through:
+  - `GET /api/knowledge/foundation/readiness`
 - Current expected result on `main` is:
   - status `In Progress`
   - decision `No-Go`

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

@@ -642,6 +642,25 @@
   - `npm run docs:diataxis:check`
   - `npm run docs:site:build`
 
+## 主线最新增量（2026-04-20 M8.2 Foundation Readiness API 面）
+
+- 已在主线补齐 typed foundation-readiness 合同面：
+  - `src/learning/types.ts` 中新增 `FoundationReadinessReport`
+  - `src/learning/api.ts` 中新增 `FoundationReadinessAPI`
+  - `src/learning/KnowledgeLearningPlatform.ts` 中新增 `getFoundationReadiness()`
+- 已增加可供运维/前端读取的路由接线：
+  - `src/server.ts` 中新增 `GET /api/knowledge/foundation/readiness`
+- 仍保持 evidence-first 边界：
+  - 该路由暴露当前 `in_progress` / `no-go` 状态，
+  - 不会把主线尚不存在的 graph/vector adapter 说成已集成。
+- 已加固 repo-root 解析，避免 hermetic runtime/test project root 造成 readiness 误判：
+  - 显式 runtime root 合法时优先使用，
+  - temp runtime root 不含 docs/package 元数据时，会回退到真实仓库证据根。
+- 已补新 API 面的回归覆盖：
+  - `src/knowledge.api.contract.test.ts`
+  - `src/learning/KnowledgeLearningPlatform.test.ts`
+  - `src/server.migration.test.ts`
+
 ## 主线最新增量（2026-04-20 M8.1 Foundation Readiness 证据打包）
 
 - 已为 post-M7 foundation lane 增加独立就绪性验证命令：

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

@@ -46,6 +46,8 @@
 - 它会把当前主线事实写入：
   - `build/foundation-readiness/foundation-readiness-latest.json`
   - `build/foundation-readiness/foundation-readiness-latest.md`
+- 同一份受限 readiness 载荷现在也通过下列路由暴露：
+  - `GET /api/knowledge/foundation/readiness`
 - 当前主线的预期结果是：
   - 状态 `In Progress`
   - 决策 `No-Go`

scripts/foundation-readiness-utils.js

@@ -69,6 +69,7 @@ function evaluateFoundationReadiness(options = {}) {
   const storeSource = readTextIfExists(storePath);
   const enDashboard = readTextIfExists(enDashboardPath);
   const zhDashboard = readTextIfExists(zhDashboardPath);
+  const storeModulePresent = fileExists(storePath);
 
   const fileBackedStore =
     storeSource.includes('createFileBackedKnowledgeGraphStore')
@@ -159,6 +160,9 @@ function evaluateFoundationReadiness(options = {}) {
     status,
     decision,
     baseline: {
+      storeType: fileBackedStore ? 'file' : 'none',
+      exists: storeModulePresent,
+      loaded: storeModulePresent && storeSource.includes('loadSnapshot'),
       fileBackedStore,
       graphAdapterModulePresent,
       vectorAdapterModulePresent,
@@ -185,6 +189,9 @@ function formatFoundationReadinessMarkdown(result, reportPaths) {
     '',
     '## Baseline',
     '',
+    `- Store type: ${result.baseline.storeType}`,
+    `- 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'}`,
     `- Dedicated graph adapter module present: ${result.baseline.graphAdapterModulePresent ? 'yes' : 'no'}`,
     `- Dedicated vector adapter module present: ${result.baseline.vectorAdapterModulePresent ? 'yes' : 'no'}`,

scripts/verify-foundation-readiness.js

@@ -11,6 +11,9 @@ const DEFAULT_MARKDOWN_REPORT_NAME = 'foundation-readiness-latest.md';
 function printHumanReport(result, reportPaths) {
   console.log(`[Foundation Readiness] Status: ${result.status}`);
   console.log(`[Foundation Readiness] Decision: ${result.decision}`);
+  console.log(`[Foundation Readiness] Store type: ${result.baseline.storeType}`);
+  console.log(`[Foundation Readiness] Store evidence present: ${result.baseline.exists ? 'yes' : 'no'}`);
+  console.log(`[Foundation Readiness] Store load capability present: ${result.baseline.loaded ? 'yes' : 'no'}`);
   console.log(
     `[Foundation Readiness] File-backed store evidence: ${result.baseline.fileBackedStore ? 'yes' : 'no'}`
   );

src/foundation.readiness.contract.test.ts

@@ -10,6 +10,9 @@ type FoundationReadinessResult = {
   status: 'planned' | 'in_progress' | 'integrated';
   decision: 'go' | 'no-go';
   baseline: {
+    storeType: 'none' | 'file';
+    exists: boolean;
+    loaded: boolean;
     fileBackedStore: boolean;
     graphAdapterModulePresent: boolean;
     vectorAdapterModulePresent: boolean;
@@ -98,6 +101,9 @@ describe('foundation readiness contract', () => {
 
     expect(result.status).toBe('in_progress');
     expect(result.decision).toBe('no-go');
+    expect(result.baseline.storeType).toBe('file');
+    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.vectorAdapterModulePresent).toBe(false);
@@ -148,6 +154,9 @@ describe('foundation readiness contract', () => {
 
     expect(result.status).toBe('integrated');
     expect(result.decision).toBe('go');
+    expect(result.baseline.storeType).toBe('file');
+    expect(result.baseline.exists).toBe(true);
+    expect(result.baseline.loaded).toBe(false);
     expect(result.baseline.fileBackedStore).toBe(true);
     expect(result.baseline.graphAdapterModulePresent).toBe(true);
     expect(result.baseline.vectorAdapterModulePresent).toBe(true);

src/knowledge.api.contract.test.ts

@@ -9,6 +9,7 @@ describe('Knowledge mastery API contract wiring', () => {
         const endpoints = [
             '/api/knowledge/state',
             '/api/knowledge/store-diagnostics',
+            '/api/knowledge/foundation/readiness',
             '/api/knowledge/operator/agent-workspace-diagnostics/index',
             '/api/knowledge/operator/agent-workspace-diagnostics/latest',
             '/api/knowledge/operator/agent-workspace-diagnostics/triage',
@@ -81,6 +82,7 @@ describe('Knowledge mastery API contract wiring', () => {
             'interface KnowledgeIngestAPI',
             'interface KnowledgeQueryAPI',
             'interface AgentConversationAPI',
+            'interface FoundationReadinessAPI',
             'interface MasteryDiagnosticsAPI',
             'interface MasteryMisconceptionAPI',
             'interface LearningPathAPI',

src/learning/KnowledgeLearningPlatform.test.ts

@@ -1,4 +1,8 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
 import { KnowledgeLearningPlatform } from './KnowledgeLearningPlatform';
+import { createFileBackedKnowledgeGraphStore } from './store';
 
 describe('KnowledgeLearningPlatform', () => {
     let nowIso: string;
@@ -1048,6 +1052,119 @@ describe('KnowledgeLearningPlatform', () => {
         expect(state.sessionActionTelemetry.executionCount).toBeGreaterThanOrEqual(0);
     });
 
+    test('foundation readiness resolves explicit repo roots without overclaiming missing adapters', async () => {
+        const tempRoot = fs.mkdtempSync(
+            path.join(fs.realpathSync(os.tmpdir()), 'noteconnection-foundation-platform-')
+        );
+
+        try {
+            const fakeRepoRoot = path.join(tempRoot, 'repo');
+            fs.mkdirSync(path.join(fakeRepoRoot, 'src', 'learning'), { recursive: true });
+            fs.mkdirSync(path.join(fakeRepoRoot, 'docs', 'diataxis', 'en', 'explanation'), { recursive: true });
+            fs.mkdirSync(path.join(fakeRepoRoot, 'docs', 'diataxis', 'zh', 'explanation'), { recursive: true });
+
+            fs.writeFileSync(
+                path.join(fakeRepoRoot, 'package.json'),
+                JSON.stringify(
+                    {
+                        scripts: {
+                            'verify:foundation:readiness': 'node scripts/verify-foundation-readiness.js',
+                        },
+                    },
+                    null,
+                    2
+                ),
+                'utf8'
+            );
+            fs.writeFileSync(
+                path.join(fakeRepoRoot, 'src', 'learning', 'store.ts'),
+                "export async function loadSnapshot() {}\nexport function createFileBackedKnowledgeGraphStore() {}\nexport const diagnostics = { storeType: 'file' };\n",
+                'utf8'
+            );
+            fs.writeFileSync(
+                path.join(
+                    fakeRepoRoot,
+                    'docs',
+                    'diataxis',
+                    'en',
+                    'explanation',
+                    'foundation-reentry-readiness-checklist.md'
+                ),
+                'foundation checklist\n',
+                'utf8'
+            );
+            fs.writeFileSync(
+                path.join(
+                    fakeRepoRoot,
+                    'docs',
+                    'diataxis',
+                    'zh',
+                    'explanation',
+                    'foundation-reentry-readiness-checklist.md'
+                ),
+                'foundation checklist\n',
+                'utf8'
+            );
+            fs.writeFileSync(
+                path.join(
+                    fakeRepoRoot,
+                    'docs',
+                    'diataxis',
+                    'en',
+                    'explanation',
+                    'development-progress-dashboard.md'
+                ),
+                'foundation-reentry-readiness-checklist\n',
+                'utf8'
+            );
+            fs.writeFileSync(
+                path.join(
+                    fakeRepoRoot,
+                    'docs',
+                    'diataxis',
+                    'zh',
+                    'explanation',
+                    'development-progress-dashboard.md'
+                ),
+                'foundation-reentry-readiness-checklist\n',
+                'utf8'
+            );
+
+            const readinessPlatform = new KnowledgeLearningPlatform({
+                nowProvider: () => new Date(nowIso),
+                projectRoot: fakeRepoRoot,
+                store: createFileBackedKnowledgeGraphStore({
+                    filePath: path.join(tempRoot, 'runtime_data', 'knowledge_graph_store.v1.json'),
+                }),
+            });
+
+            const readiness = await readinessPlatform.getFoundationReadiness();
+
+            expect(readiness.status).toBe('in_progress');
+            expect(readiness.decision).toBe('no-go');
+            expect(readiness.baseline.storeType).toBe('file');
+            expect(readiness.baseline.exists).toBe(false);
+            expect(readiness.baseline.loaded).toBe(false);
+            expect(readiness.baseline.fileBackedStore).toBe(true);
+            expect(readiness.baseline.graphAdapterModulePresent).toBe(false);
+            expect(readiness.baseline.vectorAdapterModulePresent).toBe(false);
+            expect(readiness.documents.checklistPagesPresent).toBe(true);
+            expect(readiness.documents.dashboardReferencesPresent).toBe(true);
+            expect(readiness.packageScripts.readinessVerifierPresent).toBe(true);
+            expect(readiness.mandatoryChecks.map((entry) => entry.gateId)).toEqual(
+                expect.arrayContaining([
+                    'contract',
+                    'core_behavior',
+                    'persistence_safety',
+                    'interaction_non_regression',
+                    'documentation',
+                ])
+            );
+        } finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    });
+
     test('tutor action uses misconception context for targeted guidance', async () => {
         const ingest = await platform.ingestKnowledge({
             incremental: true,