feat(agent-workspace): add unit memory snapshot capability lane

Jacobinwwey · Jacobinwwey · commit 909f2e5a9eeb · 2026-04-14T09:39:45.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
@@ -255,6 +255,16 @@ npm run verify:agent-workspace:tauri
   - frontend payload-builder ingest-guardrail endpoint/body assertions,
   - runtime endpoint/payload/message assertions for ingest-guardrail execution.
 
+#### M6.11 Progress Note (2026-04-14)
+
+- [Done] typed conversation capability surface expanded with `inspect_unit_memory_snapshot` action.
+- [Done] conversation capability emission now includes readonly unit-layer memory snapshot execution (`memoryLayer: unit`, `memoryOperation: snapshot`) through `apply_memory_policy`.
+- [Done] contract/runtime planners preserve memory-layer passthrough for unit snapshot diagnostics.
+- [Done] regression coverage expanded for:
+  - unit-memory capability wiring in conversation output,
+  - frontend payload-builder unit memory-layer assertions,
+  - runtime endpoint/payload/message assertions for unit memory snapshot 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
@@ -233,6 +233,18 @@ Execution anchor:
   - frontend ingest-guardrail payload-builder endpoint/body assertions,
   - runtime endpoint/payload/message assertions for ingest-guardrail execution and rendering.
 
+## Latest Mainline Increment (2026-04-14 M6.11 Unit Memory Snapshot Capability Lane)
+
+- Added `inspect_unit_memory_snapshot` to the typed conversation action union on mainline.
+- Extended `runAgentConversation(...)` capability emission to include readonly unit-layer memory snapshot execution (`memoryLayer: unit`, `memoryOperation: snapshot`) via `apply_memory_policy`.
+- Kept contract/runtime planner behavior aligned for unit memory diagnostics payload shaping:
+  - preserved layer passthrough (`unit`),
+  - readonly snapshot operation guardrails unchanged.
+- Expanded regression coverage for:
+  - unit-memory capability wiring in conversation output,
+  - frontend unit memory payload-builder assertions,
+  - runtime endpoint/payload/message assertions for unit memory snapshot execution.
+
 ## 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
@@ -233,6 +233,18 @@
   - 前端 ingest-guardrail payload-builder 的 endpoint/body 断言，
   - runtime ingest-guardrail 路径 endpoint/payload/消息断言。
 
+## 主线最新增量（2026-04-14 M6.11 单元记忆快照能力链路）
+
+- 主线 typed conversation action union 新增 `inspect_unit_memory_snapshot`。
+- `runAgentConversation(...)` capability 输出新增只读单元层记忆快照动作（`memoryLayer: unit`、`memoryOperation: snapshot`，经 `apply_memory_policy` 执行）。
+- contract/runtime payload 规划保持对齐：
+  - `unit` 层透传保持一致，
+  - 只读 snapshot 护栏保持不变。
+- 回归覆盖同步扩展：
+  - conversation 输出中的 unit-memory capability 连线断言，
+  - 前端 unit memory payload-builder 断言，
+  - runtime unit memory 路径 endpoint/payload/消息断言。
+
 ## 主线 vs 工作分支快照（2026-04-14）
 
 | 能力切片 | 工作分支（`feat/learning-multi-tutor-adapter`） | 主线（`origin/main`） | 集成状态 |
diff --git a/src/agent_workspace.frontend.test.ts b/src/agent_workspace.frontend.test.ts
@@ -328,6 +328,32 @@ describe('agent_workspace frontend operation contract', () => {
         });
     });
 
+    test('apply_memory_policy builds readonly unit memory snapshot payload', () => {
+        const requestPlan = buildKnowledgeOperationRequestPayload({
+            request: {
+                userId: 'learner-a',
+                atomId: 'atom-2',
+                memoryLayer: 'unit',
+                memoryOperation: 'snapshot',
+            },
+            execution: {
+                operationId: 'apply_memory_policy',
+            },
+        });
+
+        expect(requestPlan).toEqual({
+            operationId: 'apply_memory_policy',
+            endpoint: '/api/knowledge/memory/policy',
+            method: 'POST',
+            resultPresentation: 'memory_policy_card',
+            body: {
+                userId: 'learner-a',
+                layer: 'unit',
+                operation: 'snapshot',
+            },
+        });
+    });
+
     test('apply_memory_policy rejects mutating memory operations from capability lane', () => {
         expect(() =>
             buildKnowledgeOperationRequestPayload({
diff --git a/src/agent_workspace.runtime.behavior.test.ts b/src/agent_workspace.runtime.behavior.test.ts
@@ -978,6 +978,98 @@ describe('agent workspace runtime behavior', () => {
         expect(messages.textContent || '').toContain('Memory snapshot loaded');
     });
 
+    test('executes unit memory snapshot capability and forwards unit layer', 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-memory-unit-1',
+                                title: 'Unit Memory Candidate',
+                                snippet: 'Inspect unit memory snapshot.',
+                                score: 0.71,
+                                capabilities: [
+                                    {
+                                        actionId: 'inspect_unit_memory_snapshot',
+                                        label: 'Unit Memory Snapshot',
+                                        request: {
+                                            userId: 'agent_user_default',
+                                            atomId: 'atom-memory-unit-1',
+                                            memoryLayer: 'unit',
+                                            memoryOperation: 'snapshot',
+                                            memoryLimit: 10,
+                                        },
+                                        execution: {
+                                            kind: 'knowledge_operation',
+                                            operationId: 'apply_memory_policy',
+                                            resultPresentation: 'memory_policy_card',
+                                        },
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                }),
+            })
+            .mockResolvedValueOnce({
+                ok: true,
+                status: 200,
+                json: async () => ({
+                    success: true,
+                    result: {
+                        layer: 'unit',
+                        operation: 'snapshot',
+                        entries: [
+                            { key: 'u1', value: 'unit memory 1' },
+                        ],
+                        evictedCount: 0,
+                        stats: {
+                            session: 3,
+                            unit: 4,
+                            longTerm: 2,
+                        },
+                    },
+                }),
+            });
+        (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 = 'show unit memory snapshot';
+        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/memory/policy',
+            expect.objectContaining({ method: 'POST' })
+        );
+        const payload = JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body || '{}')) as {
+            layer?: string;
+            operation?: string;
+        };
+        expect(payload.layer).toBe('unit');
+        expect(payload.operation).toBe('snapshot');
+
+        const messages = document.getElementById('agent-workspace-messages') as HTMLElement;
+        expect(messages.textContent || '').toContain('unit/snapshot');
+    });
+
     test('executes memory retrain-plan capability and preserves readonly operation', async () => {
         const fetchMock = jest
             .fn()
diff --git a/src/frontend/locales/en.json b/src/frontend/locales/en.json
@@ -246,6 +246,7 @@
       "inspectMasteryMisconceptions": "Mastery Misconceptions",
       "inspectLearningQualitySnapshot": "Learning Quality",
       "inspectMemorySnapshot": "Memory Snapshot",
+      "inspectUnitMemorySnapshot": "Unit Memory Snapshot",
       "inspectMemoryRetrainPlan": "Memory Retrain Plan",
       "inspectMemoryRead": "Memory Read",
       "closeLearningPath": "Close Path",
diff --git a/src/frontend/locales/zh.json b/src/frontend/locales/zh.json
@@ -246,6 +246,7 @@
       "inspectMasteryMisconceptions": "误解洞察",
       "inspectLearningQualitySnapshot": "学习质量",
       "inspectMemorySnapshot": "记忆快照",
+      "inspectUnitMemorySnapshot": "单元记忆快照",
       "inspectMemoryRetrainPlan": "记忆复训计划",
       "inspectMemoryRead": "记忆读取",
       "closeLearningPath": "关闭路径",
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(17);
+        expect(firstPoint.capabilities.length).toBeGreaterThanOrEqual(18);
         const actionIds = firstPoint.capabilities.map((capability) => capability.actionId);
         expect(actionIds).toEqual(
             expect.arrayContaining([
@@ -150,6 +150,7 @@ describe('KnowledgeLearningPlatform', () => {
                 'inspect_mastery_misconceptions',
                 'inspect_learning_quality_snapshot',
                 'inspect_memory_snapshot',
+                'inspect_unit_memory_snapshot',
                 'inspect_memory_retrain_plan',
                 'inspect_memory_read',
             ])
@@ -187,6 +188,11 @@ describe('KnowledgeLearningPlatform', () => {
         expect(memoryCapability?.request.memoryOperation).toBe('snapshot');
         expect(memoryCapability?.execution.operationId).toBe('apply_memory_policy');
         expect(memoryCapability?.execution.resultPresentation).toBe('memory_policy_card');
+        const unitMemoryCapability = firstPoint.capabilities.find((capability) => capability.actionId === 'inspect_unit_memory_snapshot');
+        expect(unitMemoryCapability?.request.memoryLayer).toBe('unit');
+        expect(unitMemoryCapability?.request.memoryOperation).toBe('snapshot');
+        expect(unitMemoryCapability?.execution.operationId).toBe('apply_memory_policy');
+        expect(unitMemoryCapability?.execution.resultPresentation).toBe('memory_policy_card');
         const retrainMemoryCapability = firstPoint.capabilities.find((capability) => capability.actionId === 'inspect_memory_retrain_plan');
         expect(retrainMemoryCapability?.request.memoryLayer).toBe('session');
         expect(retrainMemoryCapability?.request.memoryOperation).toBe('retrain_plan');
diff --git a/src/learning/KnowledgeLearningPlatform.ts b/src/learning/KnowledgeLearningPlatform.ts
@@ -989,6 +989,27 @@ export class KnowledgeLearningPlatform implements KnowledgeLearningPlatformAPI {
                         resultPresentation: 'memory_policy_card',
                     },
                 },
+                {
+                    capabilityId: `cap_unit_memory_snapshot_${item.atom.id}`,
+                    actionId: 'inspect_unit_memory_snapshot',
+                    label: 'Unit Memory Snapshot',
+                    labelKey: 'agentWorkspace.actions.inspectUnitMemorySnapshot',
+                    request: {
+                        ...focusRequest,
+                        memoryLayer: 'unit',
+                        memoryOperation: 'snapshot',
+                        memoryLimit: 10,
+                    },
+                    failure: {
+                        messageKey: 'agentWorkspace.messages.memoryPolicyFailed',
+                        fallbackMessage: 'Unable to inspect unit memory snapshot for "{title}".',
+                    },
+                    execution: {
+                        kind: 'knowledge_operation',
+                        operationId: 'apply_memory_policy',
+                        resultPresentation: 'memory_policy_card',
+                    },
+                },
                 {
                     capabilityId: `cap_memory_retrain_plan_${item.atom.id}`,
                     actionId: 'inspect_memory_retrain_plan',
diff --git a/src/learning/types.ts b/src/learning/types.ts
@@ -558,6 +558,7 @@ export type AgentConversationActionId =
     | 'inspect_mastery_misconceptions'
     | 'inspect_learning_quality_snapshot'
     | 'inspect_memory_snapshot'
+    | 'inspect_unit_memory_snapshot'
     | 'inspect_memory_retrain_plan'
     | 'inspect_memory_read';
 
