fix(mirror,relations): persist edges into entity markdown frontmatter

Two related bugs that meant relations created via UI/REST/MCP never
made it into the markdown mirror, plus a silent data-loss path on
subsequent entity updates.

1. Mirror was never told about relations
   The phase4 SQLite migration (c8997ee) wired StoreManager to call
   mirrorNoteCreate/Update, mirrorTaskCreate/Update, mirrorSkillCreate/
   Update, mirrorEpicCreate/Update, but hardcoded the `relations`
   parameter as `[]` everywhere, and dropped all calls to the dedicated
   mirrorNoteRelation / mirrorTaskRelation / mirrorSkillRelation /
   mirrorEpicRelation event functions. Those functions stayed in
   file-mirror.ts but became dead code, and their tests were deleted in
   the same commit.

   Effects:
   - Edges created through createEdge() never appeared in the mirror
     file frontmatter — they lived in SQLite only.
   - Every updateNote/updateTask/updateSkill regenerated the snapshot
     with `relations: []`, wiping any frontmatter relations that had
     been put there by an external file edit.
   - If a user then edited the markdown file in their IDE and saved it,
     the reverse-import path (syncEdgesFromFile) would diff the empty
     desired list against current SQLite edges and *delete every edge
     for that entity*. Silent data loss.

   Fix:
   - Add private StoreManager.buildOutgoingForMirror(graph, id, slug)
     that walks findOutgoingEdges + resolveIdToSlug to construct the
     RelationLike[] the file-mirror layer expects. Indexed-graph
     targets (docs/code/files) are skipped because they have no slug.
   - Replace all 9 hardcoded `[]` arguments at the entity create/update/
     move/reorder/bulk call sites with this helper.
   - Add private StoreManager.mirrorRelationEvent(action, edge) that
     dispatches to mirrorNoteRelation / mirrorTaskRelation /
     mirrorSkillRelation / mirrorEpicRelation depending on edge.fromGraph,
     re-uses buildMirrorTaskAttrs and the inline note/skill/epic attr
     builders, and records the mirror write through the existing tracker
     so the watcher does not feedback-loop the change back into SQLite.
   - Wire createEdge() and deleteEdge() to call mirrorRelationEvent
     after the SQLite mutation succeeds.

2. REST DELETE /relations and /links never deleted anything
   The REST handlers for knowledge/tasks/skills delete-edge endpoints
   passed `kind: ''` to deleteEdge() unconditionally. The underlying
   SQL DELETE matches edges by (fromGraph, fromId, toGraph, toId, kind),
   so the empty kind never matched any real row — the SQL affected
   0 rows but the handler returned 204 OK. Pre-existing bug, masked
   until now because the mirror file was empty too, so the UI saw
   "delete worked".

   Fix:
   - .pick() the validation schemas to include `kind` (already required
     by createRelationSchema/createTaskLinkSchema/createSkillLinkSchema).
   - Read kind from req.body and pass it through to deleteEdge.
   - Update the frontend deleteRelation / deleteTaskLink /
     deleteSkillLink type signatures to require kind, and update
     RelationManager.handleDeleteConfirmed to pass rel.kind from the
     original edge.

Tests
   - Restored 3 unit tests in src/tests/file-mirror.test.ts covering
     mirrorNoteRelation / mirrorTaskRelation / mirrorSkillRelation, so
     these dedicated event functions never silently rot again.
   - 8 round-trip tests in src/tests/store/store-manager.test.ts that
     drive StoreManager.createEdge/deleteEdge and assert the markdown
     file frontmatter, including the silent-data-loss case (createEdge
     followed by updateNote must preserve the relation), cross-graph
     edges (graph: tag), and tasks/skills mirror coverage.
   - New "2.3.1 Forward mirror" group in functional test
     02-knowledge.ts that POSTs a relation, PUTs the note body, and
     DELETEs the relation, asserting the mirror file frontmatter at
     each step through the actual REST API + dist build.
   - Updated existing tests in 02-knowledge.ts, 03-tasks.ts,
     13-websocket.ts, 19-coverage-gaps.ts and rest-api-gaps.test.ts to
     pass the now-required `kind` field. Several of those tests had
     been silently exercising the broken code path.

Verified: 1597 jest tests pass, 502 functional sandbox tests pass.

Author: prih

demo-projects/test-sandbox/tests/02-knowledge.ts

@@ -20,6 +20,8 @@ let restNoteId = '';
 let mcpNoteId = '';
 let noteA_Id = '';
 let noteB_Id = '';
+let noteA_Slug = '';
+let noteB_Slug = '';
 let codeSymbolId = '';
 
 // ─── 2.1 CRUD ────────────────────────────────────────────────────
@@ -129,6 +131,8 @@ test('Create note for search tests', async () => {
   });
   assertOk(res);
   noteA_Id = res.data.noteId ?? res.data.id;
+  noteA_Slug = res.data.slug ?? '';
+  assertExists(noteA_Slug, 'noteA slug');
 });
 
 test('REST GET /knowledge/search?q=quantum — finds note', async () => {
@@ -158,6 +162,8 @@ test('Create second note for relations', async () => {
   });
   assertOk(res);
   noteB_Id = res.data.noteId ?? res.data.id;
+  noteB_Slug = res.data.slug ?? '';
+  assertExists(noteB_Slug, 'noteB slug');
 });
 
 test('REST POST /knowledge/relations — create relation', async () => {
@@ -181,6 +187,7 @@ test('REST DELETE /knowledge/relations — remove relation', async () => {
   const res = await del('/knowledge/relations', {
     fromId: noteA_Id,
     toId: noteB_Id,
+    kind: 'related_to',
   });
   assertOk(res);
 });
@@ -210,6 +217,60 @@ test('MCP notes_delete_link — remove relation', async () => {
   assertMcpOk(res);
 });
 
+// ─── 2.3.1 Forward mirror (DB → file relations) ─────────────────
+//
+// Regression for the silent data-loss bug: relations created via REST/MCP
+// were never written to the markdown mirror, and any subsequent entity
+// update wiped existing relations from the file frontmatter.
+
+group('2.3.1 Forward mirror (DB → file relations)');
+
+function readNoteMd(slug: string): string {
+  return readFile(projectPath('.notes', slug, 'note.md'));
+}
+
+test('POST /knowledge/relations writes outgoing relation to note.md', async () => {
+  const res = await post('/knowledge/relations', {
+    fromId: noteA_Id,
+    toId: noteB_Id,
+    kind: 'related_to',
+  });
+  assertOk(res);
+  await wait(200);
+
+  const md = readNoteMd(noteA_Slug);
+  assert(md.includes('relations:'), `note.md should contain relations: frontmatter, got:\n${md.substring(0, 300)}`);
+  assert(md.includes(`to: ${noteB_Slug}`), `note.md should reference target slug ${noteB_Slug}`);
+  assert(md.includes('kind: related_to'), 'note.md should have the relation kind');
+});
+
+test('PUT /knowledge/notes/{id} preserves existing relations', async () => {
+  // The previous test left the noteA → noteB edge in place. Updating the note
+  // body must NOT wipe it from the mirror frontmatter.
+  const res = await put(`/knowledge/notes/${noteA_Id}`, {
+    content: 'Quantum computing uses qubits — updated body.',
+  });
+  assertOk(res);
+  await wait(200);
+
+  const md = readNoteMd(noteA_Slug);
+  assert(md.includes(`to: ${noteB_Slug}`), `relation must survive entity update, got:\n${md.substring(0, 400)}`);
+  assert(md.includes('kind: related_to'), 'kind must survive update');
+});
+
+test('DELETE /knowledge/relations removes the relation from note.md', async () => {
+  const res = await del('/knowledge/relations', {
+    fromId: noteA_Id,
+    toId: noteB_Id,
+    kind: 'related_to',
+  });
+  assertOk(res);
+  await wait(200);
+
+  const md = readNoteMd(noteA_Slug);
+  assert(!md.includes(`to: ${noteB_Slug}`), `relation should be removed, got:\n${md.substring(0, 300)}`);
+});
+
 // ─── 2.4 Cross-graph links ──────────────────────────────────────
 
 group('2.4 Cross-graph links');

demo-projects/test-sandbox/tests/03-tasks.ts

@@ -252,6 +252,7 @@ test('REST DELETE /tasks/links — delete link', async () => {
   const res = await del('/tasks/links', {
     fromId: taskB_Id,
     toId: taskC_Id,
+    kind: 'related_to',
   });
   assertOk(res);
 });

demo-projects/test-sandbox/tests/13-websocket.ts

@@ -234,7 +234,7 @@ test('Create note→note relation → receives note:relation:added', async () =>
   // Delete relation → note:relation:deleted
   clearReceived();
   await restWith(BASE, 'DELETE', '/api/projects/sandbox/knowledge/relations',
-    { fromId: n1.data.id, toId: n2.data.id });
+    { fromId: n1.data.id, toId: n2.data.id, kind: 'related_to' });
   const delEvt = await findEvent('note:relation:deleted');
   assertExists(delEvt, 'note:relation:deleted event');
 
@@ -258,7 +258,7 @@ test('Create task→note relation → receives task:relation:added', async () =>
 
   clearReceived();
   await restWith(BASE, 'DELETE', '/api/projects/sandbox/tasks/links',
-    { fromId: task.data.id, toId: note.data.id, targetGraph: 'knowledge' });
+    { fromId: task.data.id, toId: note.data.id, kind: 'references', targetGraph: 'knowledge' });
   const delEvt = await findEvent('task:relation:deleted');
   assertExists(delEvt, 'task:relation:deleted event');
 
@@ -282,7 +282,7 @@ test('Create skill→skill relation → receives skill:relation:added', async ()
 
   clearReceived();
   await restWith(BASE, 'DELETE', '/api/projects/sandbox/skills/links',
-    { fromId: s1.data.id, toId: s2.data.id });
+    { fromId: s1.data.id, toId: s2.data.id, kind: 'depends_on' });
   const delEvt = await findEvent('skill:relation:deleted');
   assertExists(delEvt, 'skill:relation:deleted event');
 

demo-projects/test-sandbox/tests/19-coverage-gaps.ts

@@ -183,6 +183,7 @@ test('REST DELETE /skills/links — remove link', async () => {
   const res = await del('/skills/links', {
     fromId: skillId,
     toId: skillB_Id,
+    kind: 'depends_on',
   });
   assertOk(res);
 });
@@ -290,6 +291,7 @@ test('REST DELETE /knowledge/relations with targetGraph=code', async () => {
   const res = await del('/knowledge/relations', {
     fromId: noteId,
     toId: skillId,
+    kind: 'references',
     targetGraph: 'code',
   });
   assert(res.status < 500, `should not 500, got ${res.status}`);
@@ -323,6 +325,7 @@ test('REST DELETE /tasks/links with targetGraph=code', async () => {
   const res = await del('/tasks/links', {
     fromId: taskId,
     toId: skillId,
+    kind: 'references',
     targetGraph: 'code',
   });
   assert(res.status < 500, `should not 500, got ${res.status}`);
@@ -669,11 +672,13 @@ test('Cleanup cross-graph file-link fixtures', async () => {
   await del('/knowledge/relations', {
     fromId: linkedNoteId,
     toId: fileNodeId,
+    kind: 'references',
     targetGraph: 'files',
   });
   await del('/tasks/links', {
     fromId: linkedTaskId,
     toId: fileNodeId,
+    kind: 'references',
     targetGraph: 'files',
   });
   await del(`/knowledge/notes/${linkedNoteId}`);

src/api/rest/knowledge.ts

@@ -133,15 +133,17 @@ export function createKnowledgeRouter(_users?: Record<string, UserConfig>): Rout
     } catch (err) { next(err); }
   });
 
-  // Delete edge (relation)
-  router.delete('/relations', requireWriteAccess, validateBody(createRelationSchema.pick({ fromId: true, toId: true, targetGraph: true, projectId: true })), async (req, res, next) => {
+  // Delete edge (relation). `kind` is required because the underlying SQL
+  // delete matches edges by (fromId, toId, fromGraph, toGraph, kind) — without
+  // it we'd silently affect 0 rows.
+  router.delete('/relations', requireWriteAccess, validateBody(createRelationSchema.pick({ fromId: true, toId: true, kind: true, targetGraph: true, projectId: true })), async (req, res, next) => {
     try {
       const { storeManager: mgr, mutationQueue } = getProject(req);
-      const { fromId, toId, targetGraph } = req.body;
+      const { fromId, toId, kind, targetGraph } = req.body;
       const fromGraph: GraphName = 'knowledge';
       const toGraph: GraphName = targetGraph || 'knowledge';
       await mutationQueue.enqueue(async () => {
-        mgr.deleteEdge({ fromGraph, fromId, toGraph, toId, kind: '' });
+        mgr.deleteEdge({ fromGraph, fromId, toGraph, toId, kind });
       });
       res.status(204).end();
     } catch (err) { next(err); }

src/api/rest/skills.ts

@@ -159,17 +159,17 @@ export function createSkillsRouter(_users?: Record<string, UserConfig>): Router
 
   // Delete skill link
   // Must be registered before DELETE /:skillId to avoid 'links' being parsed as a skillId
-  router.delete('/links', requireWriteAccess, validateBody(createSkillLinkSchema.pick({ fromId: true, toId: true, targetGraph: true, projectId: true })), async (req, res, next) => {
+  router.delete('/links', requireWriteAccess, validateBody(createSkillLinkSchema.pick({ fromId: true, toId: true, kind: true, targetGraph: true, projectId: true })), async (req, res, next) => {
     try {
       const p = getProject(req);
-      const { fromId, toId, targetGraph } = req.body;
+      const { fromId, toId, kind, targetGraph } = req.body;
       await p.mutationQueue.enqueue(async () => {
         p.storeManager.deleteEdge({
           fromGraph: 'skills',
           fromId,
           toGraph: targetGraph ?? 'skills',
           toId,
-          kind: '',
+          kind,
         });
       });
       res.status(204).end();

src/api/rest/tasks.ts

@@ -203,16 +203,16 @@ export function createTasksRouter(_users?: Record<string, unknown>): Router {
 
   // Delete edge
   // Must be registered before DELETE /:taskId to avoid 'links' being parsed as a taskId
-  router.delete('/links', requireWriteAccess, validateBody(createTaskLinkSchema.pick({ fromId: true, toId: true, targetGraph: true, projectId: true })), async (req, res, next) => {
+  router.delete('/links', requireWriteAccess, validateBody(createTaskLinkSchema.pick({ fromId: true, toId: true, kind: true, targetGraph: true, projectId: true })), async (req, res, next) => {
     try {
       const p = getProject(req);
-      const { fromId, toId, targetGraph } = req.body;
+      const { fromId, toId, kind, targetGraph } = req.body;
       const edge: Edge = {
         fromGraph: 'tasks' as GraphName,
         fromId,
         toGraph: (targetGraph ?? 'tasks') as GraphName,
         toId,
-        kind: '',  // kind not required for delete lookup
+        kind,
       };
       await p.mutationQueue.enqueue(async () => {
         p.storeManager.deleteEdge(edge);