fix(testing): harden foundation runtime verification commands

Jacobinwwey · Jacobinwwey · commit 7572ee4950fd · 2026-05-18T16:01:44.000+08:00
diff --git a/docs/en/task.md b/docs/en/task.md
@@ -34,3 +34,18 @@
 3. The live query comparison, staleness, learning-quality, and session-plan-quality diagnostics are calibrated on top of a release-grade graphdb/ANN baseline.
 4. Tutor routing advances from local-first adapter execution into a production-proven multi-provider policy while keeping explicit fallback behavior.
 5. Tauri desktop + Android path remains documented, verified, and cleanly separated from historical Electron context.
+
+### Core Real-Machine Test Commands
+
+- `npm run verify:foundation:sqlite-runtime:matrix`
+  - Highest-value host/runtime proof for the embedded sqlite graph backend across `smoke` / `medium` / `heavy` workloads.
+- `npm run verify:foundation:ann-runtime:matrix`
+  - Highest-value host/runtime proof for the `external_http` ANN connector across `smoke` / `medium` / `heavy` workloads.
+- `npm run verify:agent-workspace:browser`
+  - Real browser smoke for agent workspace, runbook cards, query/quality/session surfaces, and focus/path flows.
+- `npm run verify:agent-workspace:tauri`
+  - Real desktop-shell smoke for the current Tauri app path.
+- `npm run tauri:dev:mini:gpu`
+  - Primary desktop real-machine interactive command when you want to manually drive the app in the mini GPU-enabled shell.
+- `npm run tauri:android:dev`
+  - Primary Android real-device interactive command when you want to push the current app to a connected device.
diff --git a/docs/zh/task.md b/docs/zh/task.md
@@ -31,6 +31,21 @@
 4. tutor routing 从 local-first adapter 执行推进到生产级多 provider 策略，同时保留明确的 fallback。
 5. Tauri 桌面与 Android 路径继续保持可验证、可文档化，并与历史 Electron 上下文清晰分层。
 
+### 核心实机测试命令
+
+- `npm run verify:foundation:sqlite-runtime:matrix`
+  - 当前 embedded sqlite 图后端最有价值的主机/runtime 证明，覆盖 `smoke` / `medium` / `heavy` 三档 workload。
+- `npm run verify:foundation:ann-runtime:matrix`
+  - 当前 `external_http` ANN connector 最有价值的主机/runtime 证明，覆盖 `smoke` / `medium` / `heavy` 三档 workload。
+- `npm run verify:agent-workspace:browser`
+  - 真实浏览器 smoke，覆盖 agent workspace、runbook 卡片、query/quality/session 面板和 focus/path 流程。
+- `npm run verify:agent-workspace:tauri`
+  - 当前 Tauri 桌面壳层路径的真实 smoke。
+- `npm run tauri:dev:mini:gpu`
+  - 你要做桌面端手动实机交互测试时，优先使用的 mini GPU 壳层命令。
+- `npm run tauri:android:dev`
+  - 你要把当前应用推到已连接 Android 实机上做交互测试时，优先使用的命令。
+
 ---
 
 # Task: Refining Path Mode Visualization
diff --git a/package.json b/package.json
@@ -92,11 +92,11 @@
     "test:conversation-turn-cache:durability": "jest src/notemd.server.integration.test.ts --runInBand --testNamePattern=\"turn-cache alert trend restart durability\"",
     "test:license:contract": "jest src/license.policy.contract.test.ts --runInBand",
     "verify:agent-workspace:runtime": "node scripts/verify-agent-workspace-runtime.js",
-    "verify:foundation:ann-runtime": "node scripts/verify-foundation-ann-runtime.js",
-    "verify:foundation:ann-runtime:matrix": "node scripts/verify-foundation-ann-runtime.js --matrix",
-    "verify:foundation:sqlite-runtime": "node scripts/verify-foundation-sqlite-runtime.js",
-    "verify:foundation:sqlite-runtime:heavy": "node scripts/verify-foundation-sqlite-runtime.js --heavy",
-    "verify:foundation:sqlite-runtime:matrix": "node scripts/verify-foundation-sqlite-runtime.js --matrix",
+    "verify:foundation:ann-runtime": "npm run build && node scripts/ensure-sidecar-ready.js && node scripts/verify-foundation-ann-runtime.js",
+    "verify:foundation:ann-runtime:matrix": "npm run build && node scripts/ensure-sidecar-ready.js && node scripts/verify-foundation-ann-runtime.js --matrix",
+    "verify:foundation:sqlite-runtime": "npm run build && node scripts/ensure-sidecar-ready.js && node scripts/verify-foundation-sqlite-runtime.js",
+    "verify:foundation:sqlite-runtime:heavy": "npm run build && node scripts/ensure-sidecar-ready.js && node scripts/verify-foundation-sqlite-runtime.js --heavy",
+    "verify:foundation:sqlite-runtime:matrix": "npm run build && node scripts/ensure-sidecar-ready.js && node scripts/verify-foundation-sqlite-runtime.js --matrix",
     "verify:agent-workspace:browser": "node scripts/verify-agent-workspace-browser.js",
     "verify:agent-workspace:tauri": "node scripts/verify-agent-workspace-tauri.js",
     "verify:agent-workspace:tauri:window-evidence": "node scripts/verify-agent-workspace-tauri-window-evidence.js",
diff --git a/scripts/verify-foundation-ann-runtime.js b/scripts/verify-foundation-ann-runtime.js
@@ -12,6 +12,9 @@ const DIST_FRONTEND_DIR = path.join(REPO_ROOT, 'dist', 'src', 'frontend');
 const LOOPBACK_HOST = '127.0.0.1';
 const STARTUP_TIMEOUT_MS = 30000;
 const SHUTDOWN_TIMEOUT_MS = 8000;
+const REQUEST_TIMEOUT_SCALE = Number.isFinite(Number(process.env.NOTE_CONNECTION_FOUNDATION_ANN_TIMEOUT_SCALE))
+    ? Math.max(0.5, Number(process.env.NOTE_CONNECTION_FOUNDATION_ANN_TIMEOUT_SCALE))
+    : 1;
 const WORKLOAD_PROFILES = {
     smoke: {
         profileId: 'smoke',
@@ -158,7 +161,29 @@ function getFreePort() {
     });
 }
 
-function requestJson(port, method, requestPath, body) {
+function computeRequestTimeoutMs(context = {}) {
+    const requestPath = String(context.requestPath || '').trim();
+    const workloadProfile = context.workloadProfile || { documentCount: 1 };
+    const documentCount = Math.max(1, Math.floor(Number(workloadProfile.documentCount || 1)));
+    const mode = String(context.mode || '').trim();
+    let timeoutMs = 6000;
+
+    if (requestPath === '/api/knowledge/ingest') {
+        timeoutMs = Math.max(20000, documentCount * 450);
+    } else if (requestPath === '/api/knowledge/query') {
+        timeoutMs = Math.max(8000, documentCount * 60);
+    } else if (requestPath === '/api/knowledge/query-backend-diagnostics') {
+        timeoutMs = Math.max(6000, documentCount * 30);
+    }
+
+    if (mode === 'packaged_sidecar') {
+        timeoutMs = Math.round(timeoutMs * 2);
+    }
+
+    return Math.max(2000, Math.round(timeoutMs * REQUEST_TIMEOUT_SCALE));
+}
+
+function requestJson(port, method, requestPath, body, timeoutMs = 6000) {
     return new Promise((resolve, reject) => {
         const payload = typeof body === 'undefined'
             ? null
@@ -199,7 +224,7 @@ function requestJson(port, method, requestPath, body) {
             }
         );
 
-        req.setTimeout(2000, () => {
+        req.setTimeout(timeoutMs, () => {
             req.destroy(new Error(`Timed out requesting ${requestPath}`));
         });
         req.once('error', reject);
@@ -354,12 +379,21 @@ async function startReferenceAnnService(port, state) {
     return server;
 }
 
-async function waitForServer(port, timeoutMs) {
+async function waitForServer(port, timeoutMs, context = {}) {
     const startedAt = Date.now();
     let lastError = null;
     while ((Date.now() - startedAt) < timeoutMs) {
         try {
-            const response = await requestJson(port, 'GET', '/api/knowledge/query-backend-diagnostics');
+            const response = await requestJson(
+                port,
+                'GET',
+                '/api/knowledge/query-backend-diagnostics',
+                undefined,
+                computeRequestTimeoutMs({
+                    ...context,
+                    requestPath: '/api/knowledge/query-backend-diagnostics',
+                })
+            );
             if (response.status >= 200 && response.status < 500) {
                 return;
             }
@@ -667,10 +701,20 @@ function assertAnnState(state, mode, phase, workloadProfile, minSelectCount) {
     };
 }
 
-async function runQueries(port, mode, phase, workloadQueries) {
+async function runQueries(port, mode, phase, workloadProfile, workloadQueries) {
     const queryResults = [];
     for (const queryPlan of workloadQueries) {
-        const queryResponse = await requestJson(port, 'POST', '/api/knowledge/query', queryPlan.request);
+        const queryResponse = await requestJson(
+            port,
+            'POST',
+            '/api/knowledge/query',
+            queryPlan.request,
+            computeRequestTimeoutMs({
+                requestPath: '/api/knowledge/query',
+                workloadProfile,
+                mode,
+            })
+        );
         queryResults.push({
             phaseId: queryPlan.phaseId,
             ...assertQueryResponse(queryResponse, mode, `${phase}:${queryPlan.phaseId}`, {
@@ -707,14 +751,34 @@ async function runScenario(mode, workloadProfile) {
 
     try {
         runtime = spawnRuntime(mode, { port, bridgePort, connectorPort, fixture });
-        await waitForServer(port, STARTUP_TIMEOUT_MS);
-
-        const ingestResponse = await requestJson(port, 'POST', '/api/knowledge/ingest', ingestPayload);
+        await waitForServer(port, STARTUP_TIMEOUT_MS, { workloadProfile, mode });
+
+        const ingestResponse = await requestJson(
+            port,
+            'POST',
+            '/api/knowledge/ingest',
+            ingestPayload,
+            computeRequestTimeoutMs({
+                requestPath: '/api/knowledge/ingest',
+                workloadProfile,
+                mode,
+            })
+        );
         assertCondition(ingestResponse.status === 200, `[${mode}] ingest status=${ingestResponse.status}`);
         assertCondition(ingestResponse.body && ingestResponse.body.success === true, `[${mode}] ingest success!=true`);
 
-        const firstQueries = await runQueries(port, mode, 'first_pass', workloadQueries);
-        const firstDiagnosticsResponse = await requestJson(port, 'GET', '/api/knowledge/query-backend-diagnostics');
+        const firstQueries = await runQueries(port, mode, 'first_pass', workloadProfile, workloadQueries);
+        const firstDiagnosticsResponse = await requestJson(
+            port,
+            'GET',
+            '/api/knowledge/query-backend-diagnostics',
+            undefined,
+            computeRequestTimeoutMs({
+                requestPath: '/api/knowledge/query-backend-diagnostics',
+                workloadProfile,
+                mode,
+            })
+        );
         const firstDiagnostics = assertDiagnostics(
             firstDiagnosticsResponse,
             mode,
@@ -737,10 +801,20 @@ async function runScenario(mode, workloadProfile) {
         port = await getFreePort();
         bridgePort = await getFreePort();
         runtime = spawnRuntime(mode, { port, bridgePort, connectorPort, fixture });
-        await waitForServer(port, STARTUP_TIMEOUT_MS);
-
-        const restartQueries = await runQueries(port, mode, 'restart_pass', workloadQueries);
-        const restartDiagnosticsResponse = await requestJson(port, 'GET', '/api/knowledge/query-backend-diagnostics');
+        await waitForServer(port, STARTUP_TIMEOUT_MS, { workloadProfile, mode });
+
+        const restartQueries = await runQueries(port, mode, 'restart_pass', workloadProfile, workloadQueries);
+        const restartDiagnosticsResponse = await requestJson(
+            port,
+            'GET',
+            '/api/knowledge/query-backend-diagnostics',
+            undefined,
+            computeRequestTimeoutMs({
+                requestPath: '/api/knowledge/query-backend-diagnostics',
+                workloadProfile,
+                mode,
+            })
+        );
         const restartDiagnostics = assertDiagnostics(
             restartDiagnosticsResponse,
             mode,
diff --git a/src/foundation.ann.runtime.contract.test.ts b/src/foundation.ann.runtime.contract.test.ts
@@ -18,10 +18,10 @@ describe('foundation ann runtime verification contract', () => {
   test('keeps the host-level ann runtime verifier wired in package scripts', () => {
     const packageJson = readJson<PackageJson>(packageJsonPath);
     expect(packageJson.scripts?.['verify:foundation:ann-runtime']).toBe(
-      'node scripts/verify-foundation-ann-runtime.js'
+      'npm run build && node scripts/ensure-sidecar-ready.js && node scripts/verify-foundation-ann-runtime.js'
     );
     expect(packageJson.scripts?.['verify:foundation:ann-runtime:matrix']).toBe(
-      'node scripts/verify-foundation-ann-runtime.js --matrix'
+      'npm run build && node scripts/ensure-sidecar-ready.js && node scripts/verify-foundation-ann-runtime.js --matrix'
     );
   });
 
diff --git a/src/foundation.sqlite.runtime.contract.test.ts b/src/foundation.sqlite.runtime.contract.test.ts
@@ -18,13 +18,13 @@ describe('foundation sqlite runtime verification contract', () => {
   test('keeps the host-level sqlite runtime verifier wired in package scripts', () => {
     const packageJson = readJson<PackageJson>(packageJsonPath);
     expect(packageJson.scripts?.['verify:foundation:sqlite-runtime']).toBe(
-      'node scripts/verify-foundation-sqlite-runtime.js'
+      'npm run build && node scripts/ensure-sidecar-ready.js && node scripts/verify-foundation-sqlite-runtime.js'
     );
     expect(packageJson.scripts?.['verify:foundation:sqlite-runtime:heavy']).toBe(
-      'node scripts/verify-foundation-sqlite-runtime.js --heavy'
+      'npm run build && node scripts/ensure-sidecar-ready.js && node scripts/verify-foundation-sqlite-runtime.js --heavy'
     );
     expect(packageJson.scripts?.['verify:foundation:sqlite-runtime:matrix']).toBe(
-      'node scripts/verify-foundation-sqlite-runtime.js --matrix'
+      'npm run build && node scripts/ensure-sidecar-ready.js && node scripts/verify-foundation-sqlite-runtime.js --matrix'
     );
   });
 
