feat: surface vector stage in query traces

Author: Jacobinwwey

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

@@ -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.4)
+## Execution Note (2026-04-20 M8.1-M8.5)
 
 - The smallest executed post-M7 slice is now an evidence bundle, not an adapter claim:
   - `npm run verify:foundation:readiness`
@@ -179,6 +179,9 @@ This document re-baselines current mainline truth on 2026-04-19, records what ch
 - 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.
+- The next bounded execution slice after that exposes staged vector metadata through query traces:
+  - query responses now surface vector `mode`, `status`, and `candidateCount`
+  - the agent-workspace query-trace card now renders that metadata directly instead of hiding the prefilter stage.
 - Current expected outcome on `main` remains:
   - status `in_progress`
   - decision `no-go`

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

@@ -639,6 +639,23 @@ Execution anchor:
   - `npm run docs:diataxis:check`
   - `npm run docs:site:build`
 
+## Latest Mainline Increment (2026-04-20 M8.5 Query Trace Vector Visibility)
+
+- Extended public query-trace payloads so the staged vector boundary is inspectable instead of implicit:
+  - `src/learning/types.ts`
+  - `src/learning/KnowledgeLearningPlatform.ts`
+- Query traces now expose bounded vector stage metadata:
+  - `mode`
+  - `status`
+  - `candidateCount`
+- Updated the agent-workspace query-trace card to render that staged vector status directly in chat:
+  - `src/frontend/agent_workspace_runtime.js`
+  - `src/frontend/locales/en.json`
+  - `src/frontend/locales/zh.json`
+- Added focused regression coverage for trace payload and runtime rendering:
+  - `src/learning/KnowledgeLearningPlatform.test.ts`
+  - `src/agent_workspace.runtime.behavior.test.ts`
+
 ## Latest Mainline Increment (2026-04-20 M8.4 Vector Boundary Extraction)
 
 - Added a dedicated vector-acceleration boundary without changing the public query contract:

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

@@ -642,6 +642,23 @@
   - `npm run docs:diataxis:check`
   - `npm run docs:site:build`
 
+## 主线最新增量（2026-04-20 M8.5 Query Trace 向量阶段可见性）
+
+- 已扩展公共 query-trace 载荷，让当前 staged vector 边界可被直接检查，而不是隐含在实现内部：
+  - `src/learning/types.ts`
+  - `src/learning/KnowledgeLearningPlatform.ts`
+- query trace 现在显式暴露有界向量阶段元数据：
+  - `mode`
+  - `status`
+  - `candidateCount`
+- 已更新 agent-workspace 的 query-trace 卡片，使对话面直接显示该向量阶段状态：
+  - `src/frontend/agent_workspace_runtime.js`
+  - `src/frontend/locales/en.json`
+  - `src/frontend/locales/zh.json`
+- 已补 trace 载荷与 runtime 渲染的聚焦回归：
+  - `src/learning/KnowledgeLearningPlatform.test.ts`
+  - `src/agent_workspace.runtime.behavior.test.ts`
+
 ## 主线最新增量（2026-04-20 M8.4 Vector 边界抽取）
 
 - 已新增独立 vector-acceleration 边界，且未改变外部 query 合同：

src/agent_workspace.runtime.behavior.test.ts

@@ -589,6 +589,11 @@ describe('agent workspace runtime behavior', () => {
                         items: [{ atom: { id: 'a1' } }, { atom: { id: 'a2' } }],
                         trace: {
                             retrievalModes: ['keyword', 'graph_traversal'],
+                            vectorAcceleration: {
+                                mode: 'local_prefilter',
+                                status: 'prefilter_only',
+                                candidateCount: 2,
+                            },
                             latencyMs: 17,
                             evidenceCoverageRatio: 0.75,
                         },
@@ -625,6 +630,7 @@ describe('agent workspace runtime behavior', () => {
 
         const messages = document.getElementById('agent-workspace-messages') as HTMLElement;
         expect(messages.textContent || '').toContain('Query trace loaded');
+        expect(messages.textContent || '').toContain('vector local_prefilter/prefilter_only');
     });
 
     test('executes ingest guardrail capability and renders gate summary', async () => {

src/frontend/agent_workspace_runtime.js

@@ -1043,16 +1043,26 @@
                         : {};
                     const itemsCount = Array.isArray(result && result.items) ? result.items.length : 0;
                     const retrievalModes = Array.isArray(trace.retrievalModes) ? trace.retrievalModes.join(', ') : '';
+                    const vectorAcceleration = trace.vectorAcceleration && typeof trace.vectorAcceleration === 'object'
+                        ? trace.vectorAcceleration
+                        : null;
+                    const vectorMode = vectorAcceleration ? trimString(vectorAcceleration.mode) : '';
+                    const vectorStatus = vectorAcceleration ? trimString(vectorAcceleration.status) : '';
+                    const vectorCandidateCount = vectorAcceleration ? Number(vectorAcceleration.candidateCount) : NaN;
+                    const vectorAccelerationSummary = vectorMode && vectorStatus
+                        ? `${vectorMode}/${vectorStatus}${Number.isFinite(vectorCandidateCount) ? `/${vectorCandidateCount}` : ''}`
+                        : 'n/a';
                     const latencyMs = Number(trace.latencyMs);
                     const evidenceCoverageRatio = Number(trace.evidenceCoverageRatio);
                     appendMessage(
                         'assistant',
                         getI18nText(
                             'agentWorkspace.messages.queryTraceLoaded',
-                            `Query trace loaded (${itemsCount} hits, modes ${retrievalModes || 'n/a'}, latency ${Number.isFinite(latencyMs) ? latencyMs : 0} ms, evidence ${Number.isFinite(evidenceCoverageRatio) ? evidenceCoverageRatio.toFixed(2) : '0.00'}).`,
+                            `Query trace loaded (${itemsCount} hits, modes ${retrievalModes || 'n/a'}, vector ${vectorAccelerationSummary}, latency ${Number.isFinite(latencyMs) ? latencyMs : 0} ms, evidence ${Number.isFinite(evidenceCoverageRatio) ? evidenceCoverageRatio.toFixed(2) : '0.00'}).`,
                             {
                                 itemsCount,
                                 retrievalModes: retrievalModes || 'n/a',
+                                vectorAcceleration: vectorAccelerationSummary,
                                 latencyMs: Number.isFinite(latencyMs) ? latencyMs : 0,
                                 evidenceCoverageRatio: Number.isFinite(evidenceCoverageRatio) ? evidenceCoverageRatio.toFixed(2) : '0.00',
                             }

src/frontend/locales/en.json

@@ -271,7 +271,7 @@
       "studySessionBuildFailed": "Study session build failed.",
       "studySessionBuilt": "Study session built ({totalActions} actions, {totalEstimatedMinutes} min).",
       "queryTraceFailed": "Query trace request failed.",
-      "queryTraceLoaded": "Query trace loaded ({itemsCount} hits, modes {retrievalModes}, latency {latencyMs} ms, evidence {evidenceCoverageRatio}).",
+      "queryTraceLoaded": "Query trace loaded ({itemsCount} hits, modes {retrievalModes}, vector {vectorAcceleration}, latency {latencyMs} ms, evidence {evidenceCoverageRatio}).",
       "ingestGuardrailFailed": "Ingest guardrail evaluation failed.",
       "ingestGuardrailLoaded": "Ingest guardrails evaluated ({status}): {failedGates}/{totalGates} gates failed.",
       "sessionHistoryFailed": "Session history request failed.",

src/frontend/locales/zh.json

@@ -271,7 +271,7 @@
       "studySessionBuildFailed": "学习会话构建失败。",
       "studySessionBuilt": "学习会话已构建（动作 {totalActions} 个，预计 {totalEstimatedMinutes} 分钟）。",
       "queryTraceFailed": "检索追踪请求失败。",
-      "queryTraceLoaded": "检索追踪已加载（命中 {itemsCount} 条，模式 {retrievalModes}，延迟 {latencyMs} ms，证据覆盖 {evidenceCoverageRatio}）。",
+      "queryTraceLoaded": "检索追踪已加载（命中 {itemsCount} 条，模式 {retrievalModes}，向量阶段 {vectorAcceleration}，延迟 {latencyMs} ms，证据覆盖 {evidenceCoverageRatio}）。",
       "ingestGuardrailFailed": "摄取护栏评估失败。",
       "ingestGuardrailLoaded": "摄取护栏已评估（{status}）：{failedGates}/{totalGates} 个门禁未通过。",
       "sessionHistoryFailed": "会话历史请求失败。",

src/learning/KnowledgeLearningPlatform.test.ts

@@ -98,6 +98,11 @@ describe('KnowledgeLearningPlatform', () => {
         expect(queryResult.trace.retrievalModes).toContain('temporal_filter');
         expect(queryResult.trace.modeWeights.keyword).toBeGreaterThan(0);
         expect(queryResult.trace.modeWeights.graph).toBeGreaterThan(0);
+        expect(queryResult.trace.vectorAcceleration).toEqual({
+            mode: 'local_prefilter',
+            status: 'prefilter_only',
+            candidateCount: expect.any(Number),
+        });
         expect(queryResult.trace.latencyMs).toBeGreaterThanOrEqual(0);
         expect(queryResult.trace.evidenceCoverageRatio).toBeGreaterThan(0);
     });

src/learning/KnowledgeLearningPlatform.ts

@@ -712,6 +712,7 @@ export class KnowledgeLearningPlatform implements KnowledgeLearningPlatformAPI {
             items,
             trace: {
                 retrievalModes: ['keyword', 'graph_traversal', 'temporal_filter'],
+                vectorAcceleration: queryBackendResponse.vectorAcceleration,
                 asOf,
                 totalActiveAtoms: this.activeAtomIds.size,
                 modeWeights: {

src/learning/queryBackend.test.ts

@@ -38,10 +38,12 @@ describe('queryBackend', () => {
         });
 
         expect(keywordOnly.vectorAcceleration).toEqual({
+            candidateCount: 0,
             mode: 'disabled',
             status: 'inactive',
         });
         expect(localHybrid.vectorAcceleration).toEqual({
+            candidateCount: 2,
             mode: 'local_prefilter',
             status: 'prefilter_only',
         });