feat: port MCP retrieval and write hardening

- align os MCP/runtime/docs with ra-h contract
- add safe direct node lookup and context-optional flows
- gate edge and context writes behind confirmation

app/api/edges/[id]/route.ts

@@ -1,5 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { edgeService } from '@/services/database';
+import { validateEdgeExplanation } from '@/services/database/quality';
 
 export const runtime = 'nodejs';
 
@@ -66,7 +67,60 @@ export async function PUT(
       }, { status: 400 });
     }
 
-    const edge = await edgeService.updateEdge(edgeId, body);
+    const explanation =
+      typeof body.explanation === 'string'
+        ? body.explanation.trim()
+        : typeof body.context?.explanation === 'string'
+          ? body.context.explanation.trim()
+          : '';
+
+    const createdVia = (() => {
+      const raw =
+        typeof body.created_via === 'string'
+          ? body.created_via
+          : typeof body.context?.created_via === 'string'
+            ? body.context.created_via
+            : '';
+      if (['ui', 'agent', 'mcp', 'workflow', 'quicklink'].includes(raw)) return raw as any;
+      return 'ui' as const;
+    })();
+
+    if ((createdVia === 'agent' || createdVia === 'mcp' || createdVia === 'workflow') && body.confirmed_by_user !== true) {
+      return NextResponse.json({
+        success: false,
+        error: 'Agent-driven edge updates require explicit user confirmation before writing to the graph.'
+      }, { status: 400 });
+    }
+
+    if (!explanation && createdVia !== 'ui' && createdVia !== 'quicklink') {
+      return NextResponse.json({
+        success: false,
+        error: 'Agent-driven edge updates require an explicit explanation.'
+      }, { status: 400 });
+    }
+
+    if (explanation) {
+      const explanationError = validateEdgeExplanation(explanation);
+      if (explanationError) {
+        return NextResponse.json({
+          success: false,
+          error: explanationError
+        }, { status: 400 });
+      }
+    }
+
+    const updatePayload = { ...body };
+    delete updatePayload.confirmed_by_user;
+
+    if (typeof updatePayload.created_via === 'string') {
+      updatePayload.context = {
+        ...(updatePayload.context && typeof updatePayload.context === 'object' ? updatePayload.context : {}),
+        created_via: updatePayload.created_via,
+      };
+      delete updatePayload.created_via;
+    }
+
+    const edge = await edgeService.updateEdge(edgeId, updatePayload);
 
     return NextResponse.json({
       success: true,
@@ -112,4 +166,4 @@ export async function DELETE(
       error: error instanceof Error ? error.message : 'Failed to delete edge'
     }, { status: 500 });
   }
-}
+}

app/api/edges/route.ts

@@ -59,6 +59,26 @@ export async function POST(request: NextRequest) {
     const fromId = parseInt(body.from_node_id);
     const toId = parseInt(body.to_node_id);
     const explanation = String(body.explanation || '').trim();
+    const createdVia = (() => {
+      const raw = typeof body.created_via === 'string' ? body.created_via : '';
+      if (['ui', 'agent', 'mcp', 'workflow', 'quicklink'].includes(raw)) return raw as any;
+      return 'ui' as const;
+    })();
+
+    if (!explanation && createdVia !== 'ui' && createdVia !== 'quicklink') {
+      return NextResponse.json({
+        success: false,
+        error: 'Agent-driven edge creation requires an explicit explanation. Propose likely edges first and only create them after the user confirms.'
+      }, { status: 400 });
+    }
+
+    if ((createdVia === 'agent' || createdVia === 'mcp' || createdVia === 'workflow') && body.confirmed_by_user !== true) {
+      return NextResponse.json({
+        success: false,
+        error: 'Agent-driven edge creation requires explicit user confirmation before writing to the graph.'
+      }, { status: 400 });
+    }
+
     if (explanation) {
       const explanationError = validateEdgeExplanation(explanation);
       if (explanationError) {
@@ -68,13 +88,7 @@ export async function POST(request: NextRequest) {
         }, { status: 400 });
       }
     }
-
     const skipInference = Boolean(body.skip_inference);
-    const createdVia = (() => {
-      const raw = typeof body.created_via === 'string' ? body.created_via : '';
-      if (['ui', 'agent', 'mcp', 'workflow', 'quicklink'].includes(raw)) return raw as any;
-      return 'ui' as const;
-    })();
 
     // Idempotency: prevent duplicate edges between same pair
     try {