feat(agent-workspace): add ingest guardrail capability lane

Jacobinwwey · Jacobinwwey · commit 47b0910a0c2e · 2026-04-14T09:33:13.000-05:00
diff --git a/docs/brainstorms/2026-04-14-mainline-reality-reconciliation-and-next-direction-requirements.md b/docs/brainstorms/2026-04-14-mainline-reality-reconciliation-and-next-direction-requirements.md
@@ -243,6 +243,18 @@ npm run verify:agent-workspace:tauri
   - frontend payload-builder query endpoint/body assertions,
   - runtime endpoint/payload/message assertions for query-trace execution.
 
+#### M6.10 Progress Note (2026-04-14)
+
+- [Done] typed conversation capability surface expanded with `inspect_ingest_guardrails` action, `evaluate_ingest_guardrails` operation, and `ingest_guardrail_card` presentation.
+- [Done] conversation capability emission now includes ingest-governance guardrail evaluation execution through `/api/knowledge/ingest/guardrails/evaluate`.
+- [Done] contract/runtime planners preserve diagnostics payload shaping:
+  - explicit endpoint binding,
+  - side-effect-free empty payload.
+- [Done] regression coverage expanded for:
+  - ingest-guardrail capability wiring in conversation output,
+  - frontend payload-builder ingest-guardrail endpoint/body assertions,
+  - runtime endpoint/payload/message assertions for ingest-guardrail execution.
+
 ### M7 (Future): Foundation Lane Re-entry (Evidence-First)
 
 Entry criteria:
diff --git a/docs/diataxis/en/explanation/development-progress-dashboard.md b/docs/diataxis/en/explanation/development-progress-dashboard.md
@@ -218,6 +218,21 @@ Execution anchor:
   - frontend query payload-builder endpoint/body assertions,
   - runtime endpoint/payload/message assertions for query-trace execution and rendering.
 
+## Latest Mainline Increment (2026-04-14 M6.10 Ingest Guardrail Capability Lane)
+
+- Added `inspect_ingest_guardrails` to the typed conversation action union on mainline.
+- Extended capability operation/result unions with:
+  - `evaluate_ingest_guardrails`,
+  - `ingest_guardrail_card`.
+- Extended `runAgentConversation(...)` capability emission to include ingest-guardrail evaluation through `/api/knowledge/ingest/guardrails/evaluate`.
+- Kept contract/runtime planner behavior aligned for diagnostics execution:
+  - explicit guardrail endpoint binding,
+  - side-effect-free empty payload.
+- Expanded regression coverage for:
+  - ingest-guardrail capability wiring in conversation output,
+  - frontend ingest-guardrail payload-builder endpoint/body assertions,
+  - runtime endpoint/payload/message assertions for ingest-guardrail execution and rendering.
+
 ## Mainline vs Working-Branch Snapshot (2026-04-14)
 
 | Capability Slice | Working Branch (`feat/learning-multi-tutor-adapter`) | Mainline (`origin/main`) | Integration Status |
diff --git a/docs/diataxis/zh/explanation/development-progress-dashboard.md b/docs/diataxis/zh/explanation/development-progress-dashboard.md
@@ -218,6 +218,21 @@
   - 前端 query payload-builder 的 endpoint/body 断言，
   - runtime query-trace 路径 endpoint/payload/消息断言。
 
+## 主线最新增量（2026-04-14 M6.10 摄取护栏能力链路）
+
+- 主线 typed conversation action union 新增 `inspect_ingest_guardrails`。
+- capability operation/result union 同步扩展：
+  - `evaluate_ingest_guardrails`，
+  - `ingest_guardrail_card`。
+- `runAgentConversation(...)` capability 输出新增摄取护栏评估动作，执行路径对接 `/api/knowledge/ingest/guardrails/evaluate`。
+- contract/runtime payload 规划保持对齐：
+  - endpoint 明确绑定，
+  - 空 payload 无副作用执行。
+- 回归覆盖同步扩展：
+  - conversation 输出中的 ingest-guardrail capability 连线断言，
+  - 前端 ingest-guardrail payload-builder 的 endpoint/body 断言，
+  - runtime ingest-guardrail 路径 endpoint/payload/消息断言。
+
 ## 主线 vs 工作分支快照（2026-04-14）
 
 | 能力切片 | 工作分支（`feat/learning-multi-tutor-adapter`） | 主线（`origin/main`） | 集成状态 |
diff --git a/src/agent_workspace.contract.parity.test.ts b/src/agent_workspace.contract.parity.test.ts
@@ -14,6 +14,7 @@ describe('agent_workspace contract parity', () => {
             'execute_tutor_action',
             'build_study_session',
             'query_knowledge',
+            'evaluate_ingest_guardrails',
             'query_session_history',
             'query_mastery_misconceptions',
             'capture_learning_quality_snapshot',
@@ -31,6 +32,7 @@ describe('agent_workspace contract parity', () => {
             'tutor_action_card',
             'study_session_card',
             'query_trace_card',
+            'ingest_guardrail_card',
             'session_history_card',
             'mastery_misconceptions_card',
             'learning_quality_snapshot_card',
diff --git a/src/agent_workspace.frontend.test.ts b/src/agent_workspace.frontend.test.ts
@@ -212,6 +212,26 @@ describe('agent_workspace frontend operation contract', () => {
         });
     });
 
+    test('evaluate_ingest_guardrails builds diagnostics payload', () => {
+        const requestPlan = buildKnowledgeOperationRequestPayload({
+            request: {
+                userId: 'learner-a',
+                atomId: 'atom-2',
+            },
+            execution: {
+                operationId: 'evaluate_ingest_guardrails',
+            },
+        });
+
+        expect(requestPlan).toEqual({
+            operationId: 'evaluate_ingest_guardrails',
+            endpoint: '/api/knowledge/ingest/guardrails/evaluate',
+            method: 'POST',
+            resultPresentation: 'ingest_guardrail_card',
+            body: {},
+        });
+    });
+
     test('query_session_history builds bounded history payload', () => {
         const requestPlan = buildKnowledgeOperationRequestPayload({
             request: {
@@ -395,6 +415,7 @@ describe('agent_workspace frontend operation contract', () => {
             execute_tutor_action: 'assistant_message',
             build_study_session: 'study_session_card',
             query_knowledge: 'query_trace_card',
+            evaluate_ingest_guardrails: 'ingest_guardrail_card',
             query_session_history: 'session_history_card',
             query_mastery_misconceptions: 'mastery_misconceptions_card',
             capture_learning_quality_snapshot: 'learning_quality_snapshot_card',
@@ -409,6 +430,9 @@ describe('agent_workspace frontend operation contract', () => {
         expect(diagnostics.operationAllowedResultPresentations.query_knowledge).toEqual(
             expect.arrayContaining(['query_trace_card'])
         );
+        expect(diagnostics.operationAllowedResultPresentations.evaluate_ingest_guardrails).toEqual(
+            expect.arrayContaining(['ingest_guardrail_card'])
+        );
         expect(diagnostics.operationAllowedResultPresentations.query_session_history).toEqual(
             expect.arrayContaining(['session_history_card'])
         );
diff --git a/src/agent_workspace.runtime.behavior.test.ts b/src/agent_workspace.runtime.behavior.test.ts
@@ -84,6 +84,8 @@ describe('agent workspace runtime behavior', () => {
                         ? '/api/knowledge/session/plan'
                         : operationId === 'query_knowledge'
                             ? '/api/knowledge/query'
+                            : operationId === 'evaluate_ingest_guardrails'
+                                ? '/api/knowledge/ingest/guardrails/evaluate'
                         : operationId === 'query_session_history'
                             ? '/api/knowledge/session/history'
                             : operationId === 'query_mastery_misconceptions'
@@ -125,6 +127,15 @@ describe('agent workspace runtime behavior', () => {
                         },
                     };
                 }
+                if (operationId === 'evaluate_ingest_guardrails') {
+                    return {
+                        operationId,
+                        endpoint,
+                        method: 'POST',
+                        resultPresentation: capability.execution.resultPresentation,
+                        body: {},
+                    };
+                }
                 if (operationId === 'query_mastery_misconceptions') {
                     return {
                         operationId,
@@ -473,6 +484,85 @@ describe('agent workspace runtime behavior', () => {
         expect(messages.textContent || '').toContain('Query trace loaded');
     });
 
+    test('executes ingest guardrail capability and renders gate summary', async () => {
+        const fetchMock = jest
+            .fn()
+            .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    success: true,
+                    result: {
+                        userId: 'agent_user_default',
+                        message: 'Found 1 local knowledge point(s).',
+                        knowledgePoints: [
+                            {
+                                atomId: 'atom-guardrail-1',
+                                title: 'Guardrail Candidate',
+                                snippet: 'Inspect ingest governance budget.',
+                                score: 0.71,
+                                capabilities: [
+                                    {
+                                        actionId: 'inspect_ingest_guardrails',
+                                        label: 'Ingest Guardrails',
+                                        request: {
+                                            userId: 'agent_user_default',
+                                            atomId: 'atom-guardrail-1',
+                                        },
+                                        execution: {
+                                            kind: 'knowledge_operation',
+                                            operationId: 'evaluate_ingest_guardrails',
+                                            resultPresentation: 'ingest_guardrail_card',
+                                        },
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                }),
+            })
+            .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    success: true,
+                    result: {
+                        overallPassed: false,
+                        gates: [
+                            { gateId: 'changed_documents', passed: true },
+                            { gateId: 'ingest_p95', passed: false },
+                        ],
+                    },
+                }),
+            });
+        (global as unknown as Record<string, unknown>).fetch = fetchMock;
+
+        const runtime = runtimeModule.createAgentWorkspaceRuntime({ defaultUserId: 'agent_user_default' });
+        runtime.init();
+
+        const input = document.getElementById('agent-workspace-input') as HTMLTextAreaElement;
+        const form = document.getElementById('agent-workspace-form') as HTMLFormElement;
+        input.value = 'inspect ingest guardrails';
+        form.dispatchEvent(new dom!.window.Event('submit', { bubbles: true, cancelable: true }));
+        await flushAsync();
+
+        const actionButton = document.querySelector('.agent-workspace-action-button') as HTMLButtonElement;
+        expect(actionButton).not.toBeNull();
+        actionButton.click();
+        await flushAsync();
+
+        expect(fetchMock).toHaveBeenNthCalledWith(
+            2,
+            '/api/knowledge/ingest/guardrails/evaluate',
+            expect.objectContaining({ method: 'POST' })
+        );
+        const payload = JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body || '{}')) as Record<string, unknown>;
+        expect(payload).toEqual({});
+
+        const messages = document.getElementById('agent-workspace-messages') as HTMLElement;
+        expect(messages.textContent || '').toContain('Ingest guardrails evaluated');
+    });
+
     test('executes mastery misconceptions capability and renders summary message', async () => {
         const fetchMock = jest
             .fn()
diff --git a/src/agent_workspace.runtime.integration.test.ts b/src/agent_workspace.runtime.integration.test.ts
@@ -26,6 +26,7 @@ describe('agent workspace runtime integration baseline', () => {
         expect(runtimeSource).toContain('/api/knowledge/conversation');
         expect(runtimeSource).toContain('/api/knowledge/session/plan');
         expect(runtimeSource).toContain('/api/knowledge/query');
+        expect(runtimeSource).toContain('/api/knowledge/ingest/guardrails/evaluate');
         expect(runtimeSource).toContain('/api/knowledge/session/history');
         expect(runtimeSource).toContain('/api/knowledge/mastery/misconceptions');
         expect(runtimeSource).toContain('/api/knowledge/quality/snapshot');
diff --git a/src/frontend/agent_workspace.js b/src/frontend/agent_workspace.js
@@ -38,6 +38,12 @@
                 defaultResultPresentation: 'query_trace_card',
                 allowedResultPresentations: Object.freeze(['query_trace_card']),
             }),
+            evaluate_ingest_guardrails: Object.freeze({
+                endpoint: '/api/knowledge/ingest/guardrails/evaluate',
+                method: 'POST',
+                defaultResultPresentation: 'ingest_guardrail_card',
+                allowedResultPresentations: Object.freeze(['ingest_guardrail_card']),
+            }),
             query_session_history: Object.freeze({
                 endpoint: '/api/knowledge/session/history',
                 method: 'POST',
@@ -289,6 +295,16 @@
                 };
             }
 
+            if (operationId === 'evaluate_ingest_guardrails') {
+                return {
+                    operationId,
+                    endpoint: config.endpoint,
+                    method: config.method,
+                    resultPresentation,
+                    body: {},
+                };
+            }
+
             if (operationId === 'query_session_history') {
                 const userId = String(request.userId || '').trim();
                 if (!userId) {
diff --git a/src/frontend/agent_workspace_runtime.js b/src/frontend/agent_workspace_runtime.js
@@ -235,6 +235,15 @@
                     },
                 };
             }
+            if (operationId === 'evaluate_ingest_guardrails') {
+                return {
+                    operationId,
+                    endpoint: '/api/knowledge/ingest/guardrails/evaluate',
+                    method: 'POST',
+                    resultPresentation: trimString(execution.resultPresentation) || 'ingest_guardrail_card',
+                    body: {},
+                };
+            }
             if (operationId === 'query_session_history') {
                 return {
                     operationId,
@@ -634,6 +643,26 @@
                     return;
                 }
 
+                if (presentation === 'ingest_guardrail_card') {
+                    const gates = Array.isArray(result && result.gates) ? result.gates : [];
+                    const totalGates = gates.length;
+                    const failedGates = gates.filter((gate) => gate && gate.passed === false).length;
+                    const overallPassed = Boolean(result && result.overallPassed);
+                    appendMessage(
+                        'assistant',
+                        getI18nText(
+                            'agentWorkspace.messages.ingestGuardrailLoaded',
+                            `Ingest guardrails evaluated (${overallPassed ? 'pass' : 'fail'}): ${failedGates}/${totalGates} gates failed.`,
+                            {
+                                status: overallPassed ? 'pass' : 'fail',
+                                failedGates,
+                                totalGates,
+                            }
+                        )
+                    );
+                    return;
+                }
+
                 if (presentation === 'session_history_card') {
                     const summary = result && result.summary && typeof result.summary === 'object'
                         ? result.summary
diff --git a/src/frontend/locales/en.json b/src/frontend/locales/en.json
@@ -241,6 +241,7 @@
       "generateCounterexample": "Generate Counterexample",
       "buildStudySession": "Build Session",
       "inspectQueryTrace": "Query Trace",
+      "inspectIngestGuardrails": "Ingest Guardrails",
       "inspectSessionHistory": "Session History",
       "inspectMasteryMisconceptions": "Mastery Misconceptions",
       "inspectLearningQualitySnapshot": "Learning Quality",
@@ -270,6 +271,8 @@
       "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}).",
+      "ingestGuardrailFailed": "Ingest guardrail evaluation failed.",
+      "ingestGuardrailLoaded": "Ingest guardrails evaluated ({status}): {failedGates}/{totalGates} gates failed.",
       "sessionHistoryFailed": "Session history request failed.",
       "sessionHistoryLoaded": "Session history loaded ({totalRecords} sessions, {totalExecutedActions} actions).",
       "masteryMisconceptionsFailed": "Mastery misconceptions request failed.",
diff --git a/src/frontend/locales/zh.json b/src/frontend/locales/zh.json
@@ -241,6 +241,7 @@
       "generateCounterexample": "生成反例",
       "buildStudySession": "构建学习会话",
       "inspectQueryTrace": "检索追踪",
+      "inspectIngestGuardrails": "摄取护栏",
       "inspectSessionHistory": "会话历史",
       "inspectMasteryMisconceptions": "误解洞察",
       "inspectLearningQualitySnapshot": "学习质量",
@@ -270,6 +271,8 @@
       "studySessionBuilt": "学习会话已构建（动作 {totalActions} 个，预计 {totalEstimatedMinutes} 分钟）。",
       "queryTraceFailed": "检索追踪请求失败。",
       "queryTraceLoaded": "检索追踪已加载（命中 {itemsCount} 条，模式 {retrievalModes}，延迟 {latencyMs} ms，证据覆盖 {evidenceCoverageRatio}）。",
+      "ingestGuardrailFailed": "摄取护栏评估失败。",
+      "ingestGuardrailLoaded": "摄取护栏已评估（{status}）：{failedGates}/{totalGates} 个门禁未通过。",
       "sessionHistoryFailed": "会话历史请求失败。",
       "sessionHistoryLoaded": "会话历史已加载（会话 {totalRecords} 条，动作 {totalExecutedActions} 个）。",
       "masteryMisconceptionsFailed": "误解洞察请求失败。",
diff --git a/src/learning/KnowledgeLearningPlatform.test.ts b/src/learning/KnowledgeLearningPlatform.test.ts
@@ -131,7 +131,7 @@ describe('KnowledgeLearningPlatform', () => {
         expect(result.trace.retrievalModes).toContain('keyword');
 
         const firstPoint = result.knowledgePoints[0];
-        expect(firstPoint.capabilities.length).toBeGreaterThanOrEqual(16);
+        expect(firstPoint.capabilities.length).toBeGreaterThanOrEqual(17);
         const actionIds = firstPoint.capabilities.map((capability) => capability.actionId);
         expect(actionIds).toEqual(
             expect.arrayContaining([
@@ -145,6 +145,7 @@ describe('KnowledgeLearningPlatform', () => {
                 'generate_counterexample',
                 'build_study_session',
                 'inspect_query_trace',
+                'inspect_ingest_guardrails',
                 'inspect_session_history',
                 'inspect_mastery_misconceptions',
                 'inspect_learning_quality_snapshot',
@@ -168,6 +169,9 @@ describe('KnowledgeLearningPlatform', () => {
         expect(queryTraceCapability?.execution.resultPresentation).toBe('query_trace_card');
         expect(typeof queryTraceCapability?.request.query).toBe('string');
         expect(queryTraceCapability?.request.topK).toBe(4);
+        const ingestGuardrailCapability = firstPoint.capabilities.find((capability) => capability.actionId === 'inspect_ingest_guardrails');
+        expect(ingestGuardrailCapability?.execution.operationId).toBe('evaluate_ingest_guardrails');
+        expect(ingestGuardrailCapability?.execution.resultPresentation).toBe('ingest_guardrail_card');
         const historyCapability = firstPoint.capabilities.find((capability) => capability.actionId === 'inspect_session_history');
         expect(historyCapability?.execution.operationId).toBe('query_session_history');
         expect(historyCapability?.execution.resultPresentation).toBe('session_history_card');
diff --git a/src/learning/KnowledgeLearningPlatform.ts b/src/learning/KnowledgeLearningPlatform.ts
diff --git a/src/learning/types.ts b/src/learning/types.ts
