@polderlabs/bizar 4.5.0 → 4.5.2

package/bizar-dash/tests/headroom-settings.test.mjs

@@ -0,0 +1,126 @@
+/**
+ * tests/headroom-settings.test.mjs
+ *
+ * Tests for DEFAULT_SETTINGS.headroom and mergeSettings() headroom merging.
+ */
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+
+// We need to import the actual module — we test the _shared.mjs exports
+
+test('DEFAULT_SETTINGS has headroom key', async () => {
+  const { DEFAULT_SETTINGS } = await import('../src/server/routes/_shared.mjs');
+  assert.ok('headroom' in DEFAULT_SETTINGS, 'headroom key exists in DEFAULT_SETTINGS');
+});
+
+test('DEFAULT_SETTINGS.headroom has all required fields', async () => {
+  const { DEFAULT_SETTINGS } = await import('../src/server/routes/_shared.mjs');
+  const h = DEFAULT_SETTINGS.headroom;
+
+  assert.strictEqual(typeof h.enabled, 'boolean', 'enabled is boolean');
+  assert.strictEqual(typeof h.autoInstall, 'boolean', 'autoInstall is boolean');
+  assert.strictEqual(typeof h.port, 'number', 'port is number');
+  assert.strictEqual(typeof h.host, 'string', 'host is string');
+  assert.strictEqual(typeof h.outputShaper, 'boolean', 'outputShaper is boolean');
+  assert.strictEqual(typeof h.telemetry, 'boolean', 'telemetry is boolean');
+  assert.strictEqual(typeof h.budget, 'number', 'budget is number');
+  assert.strictEqual(typeof h.backend, 'string', 'backend is string');
+  assert.strictEqual(typeof h.autoStart, 'boolean', 'autoStart is boolean');
+  assert.strictEqual(typeof h.autoWrap, 'boolean', 'autoWrap is boolean');
+  assert.strictEqual(typeof h.routeAllProviders, 'boolean', 'routeAllProviders is boolean');
+});
+
+test('DEFAULT_SETTINGS.headroom has correct defaults', async () => {
+  const { DEFAULT_SETTINGS } = await import('../src/server/routes/_shared.mjs');
+  const h = DEFAULT_SETTINGS.headroom;
+
+  assert.strictEqual(h.enabled, true, 'enabled defaults to true');
+  assert.strictEqual(h.autoInstall, true, 'autoInstall defaults to true');
+  assert.strictEqual(h.port, 8787, 'port defaults to 8787');
+  assert.strictEqual(h.host, '127.0.0.1', 'host defaults to 127.0.0.1');
+  assert.strictEqual(h.outputShaper, false, 'outputShaper defaults to false');
+  assert.strictEqual(h.telemetry, false, 'telemetry defaults to false');
+  assert.strictEqual(h.budget, 0, 'budget defaults to 0 (unlimited)');
+  assert.strictEqual(h.backend, 'anthropic', 'backend defaults to anthropic');
+  assert.strictEqual(h.autoStart, true, 'autoStart defaults to true');
+  assert.strictEqual(h.autoWrap, true, 'autoWrap defaults to true');
+  assert.strictEqual(h.routeAllProviders, true, 'routeAllProviders defaults to true');
+});
+
+test('mergeSettings preserves headroom sub-object', async () => {
+  const { mergeSettings, DEFAULT_SETTINGS } = await import('../src/server/routes/_shared.mjs');
+
+  const existing = {
+    theme: { mode: 'light' },
+    headroom: { port: 9999, enabled: false },
+  };
+
+  const merged = mergeSettings(existing);
+
+  assert.ok('headroom' in merged, 'headroom preserved in merged');
+  assert.strictEqual(merged.headroom.port, 9999, 'headroom.port is overridden');
+  assert.strictEqual(merged.headroom.enabled, false, 'headroom.enabled is overridden');
+  // Non-overridden fields should fall back to defaults
+  assert.strictEqual(merged.headroom.host, DEFAULT_SETTINGS.headroom.host, 'headroom.host falls back to default');
+  assert.strictEqual(merged.headroom.autoInstall, DEFAULT_SETTINGS.headroom.autoInstall, 'headroom.autoInstall falls back to default');
+});
+
+test('mergeSettings handles missing headroom in existing', async () => {
+  const { mergeSettings, DEFAULT_SETTINGS } = await import('../src/server/routes/_shared.mjs');
+
+  const existing = { theme: { mode: 'light' } };
+  const merged = mergeSettings(existing);
+
+  assert.ok('headroom' in merged, 'headroom present in merged');
+  assert.deepStrictEqual(merged.headroom, DEFAULT_SETTINGS.headroom, 'headroom matches default when not in existing');
+});
+
+test('mergeSettings handles null existing', async () => {
+  const { mergeSettings, DEFAULT_SETTINGS } = await import('../src/server/routes/_shared.mjs');
+
+  const merged = mergeSettings(null);
+
+  assert.ok('headroom' in merged, 'headroom present in merged');
+  assert.deepStrictEqual(merged.headroom, DEFAULT_SETTINGS.headroom, 'headroom matches default when existing is null');
+});
+
+test('mergeSettings handles undefined existing', async () => {
+  const { mergeSettings, DEFAULT_SETTINGS } = await import('../src/server/routes/_shared.mjs');
+
+  const merged = mergeSettings(undefined);
+
+  assert.ok('headroom' in merged, 'headroom present in merged');
+  assert.deepStrictEqual(merged.headroom, DEFAULT_SETTINGS.headroom, 'headroom matches default when existing is undefined');
+});
+
+// ── HeadroomSettings TypeScript type validation ────────────────────────────────
+// This is validated by `tsc --noEmit`. We just verify the JS shape here.
+
+test('HeadroomSettings type shape matches DEFAULT_SETTINGS.headroom', async () => {
+  const { DEFAULT_SETTINGS } = await import('../src/server/routes/_shared.mjs');
+  const h = DEFAULT_SETTINGS.headroom;
+
+  // All fields must be present
+  const requiredKeys = [
+    'enabled', 'autoInstall', 'port', 'host', 'outputShaper',
+    'telemetry', 'budget', 'backend', 'autoStart', 'autoWrap', 'routeAllProviders',
+  ];
+
+  for (const key of requiredKeys) {
+    assert.ok(key in h, `headroom.${key} is present`);
+  }
+
+  // All values must be the correct type
+  assert.strictEqual(typeof h.enabled, 'boolean');
+  assert.strictEqual(typeof h.autoInstall, 'boolean');
+  assert.strictEqual(typeof h.port, 'number');
+  assert.strictEqual(typeof h.host, 'string');
+  assert.strictEqual(typeof h.outputShaper, 'boolean');
+  assert.strictEqual(typeof h.telemetry, 'boolean');
+  assert.strictEqual(typeof h.budget, 'number');
+  assert.strictEqual(typeof h.backend, 'string');
+  assert.strictEqual(typeof h.autoStart, 'boolean');
+  assert.strictEqual(typeof h.autoWrap, 'boolean');
+  assert.strictEqual(typeof h.routeAllProviders, 'boolean');
+});

package/bizar-dash/tests/headroom-status.test.mjs

@@ -0,0 +1,117 @@
+/**
+ * tests/headroom-status.test.mjs
+ *
+ * Tests for getHeadroomStatus() and the /api/headroom/status endpoint.
+ * Uses real headroom binary when available, mocked when not.
+ */
+
+import { test, describe, beforeEach, afterEach, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, rmSync, writeFileSync, existsSync, unlinkSync } from 'node:fs';
+import http from 'node:http';
+
+const HEADROOM_PORT_FILE = join(tmpdir(), `headroom-port-test-${Date.now()}.txt`);
+
+// ── HTTP helpers ─────────────────────────────────────────────────────────────
+
+const httpGet = (port, path) =>
+  new Promise((resolve, reject) => {
+    const req = http.request({ hostname: 'localhost', port, path, method: 'GET' }, (res) => {
+      let body = '';
+      res.on('data', (c) => (body += c));
+      res.on('end', () => {
+        try { resolve({ status: res.statusCode, body: JSON.parse(body || '{}') }); }
+        catch { resolve({ status: res.statusCode, body }); }
+      });
+    });
+    req.on('error', reject);
+    req.end();
+  });
+
+// ── Status shape validation ──────────────────────────────────────────────────
+
+test('getHeadroomStatus returns correct shape', async () => {
+  const { getHeadroomStatus } = await import('../src/server/headroom.mjs');
+  const status = await getHeadroomStatus();
+
+  assert.ok(typeof status.installed === 'boolean', 'installed is boolean');
+  assert.ok(typeof status.version === 'string' || status.version === null, 'version is string|null');
+  assert.ok(typeof status.proxyRunning === 'boolean', 'proxyRunning is boolean');
+  assert.ok(typeof status.proxyPort === 'number' || status.proxyPort === null, 'proxyPort is number|null');
+  assert.ok(typeof status.proxyPid === 'number' || status.proxyPid === null, 'proxyPid is number|null');
+  assert.ok(typeof status.wrapped === 'boolean', 'wrapped is boolean');
+  assert.ok(typeof status.configPath === 'string' || status.configPath === null, 'configPath is string|null');
+  assert.ok(['ok', 'warn', 'fail'].includes(status.healthy), 'healthy is ok|warn|fail');
+  assert.ok(Array.isArray(status.messages), 'messages is array');
+});
+
+test('getHeadroomStatus.healthy is warn when not installed', async () => {
+  const { getHeadroomStatus } = await import('../src/server/headroom.mjs');
+  const status = await getHeadroomStatus();
+
+  if (!status.installed) {
+    assert.strictEqual(status.healthy, 'warn', 'healthy should be warn when not installed');
+  }
+});
+
+test('getHeadroomStatus.healthy is warn when not wrapped but installed', async () => {
+  const { getHeadroomStatus } = await import('../src/server/headroom.mjs');
+  const status = await getHeadroomStatus();
+
+  if (status.installed && !status.wrapped) {
+    assert.strictEqual(status.healthy, 'warn', 'healthy should be warn when not wrapped but installed');
+  }
+});
+
+// ── /api/headroom/status endpoint ───────────────────────────────────────────
+
+async function buildApp() {
+  const { createHeadroomRouter } = await import('../src/server/routes/headroom.mjs');
+  const express = (await import('express')).default;
+  const app = express();
+  app.use(express.json());
+  // Mount at /api/headroom so routes like /status become /api/headroom/status
+  app.use('/api/headroom', await createHeadroomRouter());
+  return app;
+}
+
+test('GET /api/headroom/status returns status object', async () => {
+  const app = await buildApp();
+  const server = app.listen(0);
+  const { port } = server.address();
+
+  try {
+    const res = await httpGet(port, '/api/headroom/status');
+    assert.strictEqual(res.status, 200, 'status should be 200');
+    assert.ok(typeof res.body.installed === 'boolean', 'installed is boolean');
+    assert.ok(['ok', 'warn', 'fail'].includes(res.body.healthy), 'healthy is ok|warn|fail');
+    assert.ok(Array.isArray(res.body.messages), 'messages is array');
+  } finally {
+    server.close();
+  }
+});
+
+test('GET /api/headroom/status includes version when installed', async () => {
+  const { getHeadroomStatus } = await import('../src/server/headroom.mjs');
+  const status = await getHeadroomStatus();
+
+  if (status.installed && status.version) {
+    assert.ok(status.version.length > 0, 'version is non-empty string');
+  }
+});
+
+test('GET /api/headroom/status includes proxyPort from cached file', async () => {
+  // Write a fake port file
+  writeFileSync(HEADROOM_PORT_FILE, '9999', 'utf8');
+
+  // Override the module's port file path temporarily by mocking the fs access
+  const { getHeadroomStatus } = await import('../src/server/headroom.mjs');
+  // Note: in a real scenario you'd override via the import.meta trick or env var
+  // Here we just verify the status structure is correct
+  const status = await getHeadroomStatus();
+  assert.ok(typeof status.proxyPort === 'number' || status.proxyPort === null, 'proxyPort is number|null');
+
+  try { unlinkSync(HEADROOM_PORT_FILE); } catch { /* ignore */ }
+});

package/bizar-dash/tests/memory-lightrag-extended.test.mjs

@@ -0,0 +1,162 @@
+/**
+ * tests/memory-lightrag-extended.test.mjs
+ *
+ * v4.7.0 — Tests for the new LightRAG stats / rebuild-graph / recordQuery
+ * helpers added for the Memory tab.
+ *
+ * These helpers do NOT require a live lightrag-server — they exercise the
+ * pure helpers against an isolated tmp project root.
+ */
+
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, writeFileSync, rmSync, existsSync, readFileSync } from 'node:fs';
+
+const {
+  resolveLightRAGConfig,
+  stats,
+  recordQuery,
+  rebuildGraph,
+} = await import('../src/server/memory-lightrag.mjs');
+
+let tmpRoot;
+
+beforeEach(() => {
+  tmpRoot = join(tmpdir(), `bizar-memlight-ext-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpRoot, '.bizar', 'memory-cache'), { recursive: true });
+});
+
+afterEach(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe('resolveLightRAGConfig', () => {
+  test('returns sensible defaults for empty project', () => {
+    const cfg = resolveLightRAGConfig(tmpRoot);
+    assert.equal(cfg.enabled, true);
+    assert.equal(cfg.host, '127.0.0.1');
+    assert.equal(cfg.port, 9621);
+    assert.ok(cfg.workingDir.includes('.bizar/lightrag'));
+  });
+});
+
+describe('stats', () => {
+  test('returns the documented shape for a fresh project', async () => {
+    const s = await stats(tmpRoot);
+    assert.equal(typeof s.running, 'boolean');
+    assert.equal(s.pid, null); // no server running in tests
+    assert.equal(s.host, '127.0.0.1');
+    assert.equal(s.port, 9621);
+    assert.equal(typeof s.workingDir, 'string');
+    assert.equal(s.lastReindexAt, null);
+    assert.equal(s.lastReindexOk, null);
+    assert.equal(s.lastReindexInserted, null);
+    assert.equal(s.lastReindexFailed, null);
+    assert.equal(typeof s.noteCount, 'number');
+    assert.equal(typeof s.indexedApprox, 'number');
+    assert.equal(typeof s.queryCountLast24h, 'number');
+    assert.ok(s.avgResponseMs === null || typeof s.avgResponseMs === 'number');
+  });
+
+  test('reflects noteCount from the vault', async () => {
+    // Set up a memory.json in managed mode + a vault with 2 notes.
+    mkdirSync(join(tmpRoot, '.bizar', 'memory', 'projects', 'extproj'), { recursive: true });
+    writeFileSync(join(tmpRoot, '.bizar', 'memory.json'), JSON.stringify({
+      projectId: 'extproj',
+      memoryRepo: {
+        mode: 'managed',
+        path: join(tmpRoot, '.bizar', 'memory'),
+        remote: null,
+        branch: 'main',
+      },
+    }));
+    writeFileSync(
+      join(tmpRoot, '.bizar', 'memory', 'projects', 'extproj', 'a.md'),
+      '---\ntitle: A\n---\n\nBody A.',
+    );
+    writeFileSync(
+      join(tmpRoot, '.bizar', 'memory', 'projects', 'extproj', 'b.md'),
+      '---\ntitle: B\n---\n\nBody B.',
+    );
+    const s = await stats(tmpRoot);
+    assert.equal(s.noteCount, 2);
+  });
+
+  test('indexedApprox sums kv_store_doc_status + kv_store_full_docs', async () => {
+    const cfg = resolveLightRAGConfig(tmpRoot);
+    mkdirSync(cfg.workingDir, { recursive: true });
+    writeFileSync(
+      join(cfg.workingDir, 'kv_store_doc_status.json'),
+      JSON.stringify({ a: 1, b: 2, c: 3 }),
+    );
+    writeFileSync(
+      join(cfg.workingDir, 'kv_store_full_docs.json'),
+      JSON.stringify({ x: 1, y: 2 }),
+    );
+    const s = await stats(tmpRoot);
+    assert.equal(s.indexedApprox, 5);
+  });
+});
+
+describe('recordQuery', () => {
+  test('writes to lightrag-query-log.jsonl and stats picks it up', async () => {
+    recordQuery(tmpRoot, 42);
+    recordQuery(tmpRoot, 84);
+    recordQuery(tmpRoot, 1000);
+    const logPath = join(tmpRoot, '.bizar', 'memory-cache', 'lightrag-query-log.jsonl');
+    assert.ok(existsSync(logPath), 'log file should exist');
+    const content = readFileSync(logPath, 'utf8').trim().split('\n');
+    assert.equal(content.length, 3);
+    for (const line of content) {
+      const rec = JSON.parse(line);
+      assert.equal(typeof rec.ts, 'number');
+      assert.equal(typeof rec.ms, 'number');
+    }
+    const s = await stats(tmpRoot);
+    assert.equal(s.queryCountLast24h, 3);
+    assert.equal(s.avgResponseMs, Math.round((42 + 84 + 1000) / 3));
+  });
+
+  test('ignores queries older than 24h', async () => {
+    const logPath = join(tmpRoot, '.bizar', 'memory-cache', 'lightrag-query-log.jsonl');
+    mkdirSync(join(tmpRoot, '.bizar', 'memory-cache'), { recursive: true });
+    const old = { ts: Date.now() - 48 * 60 * 60 * 1000, ms: 99 };
+    const fresh = { ts: Date.now() - 60 * 1000, ms: 50 };
+    writeFileSync(logPath, JSON.stringify(old) + '\n' + JSON.stringify(fresh) + '\n');
+    const s = await stats(tmpRoot);
+    assert.equal(s.queryCountLast24h, 1);
+    assert.equal(s.avgResponseMs, 50);
+  });
+
+  test('handles missing log file gracefully', async () => {
+    const s = await stats(tmpRoot);
+    assert.equal(s.queryCountLast24h, 0);
+    assert.equal(s.avgResponseMs, null);
+  });
+});
+
+describe('rebuildGraph', () => {
+  test('is idempotent when called against a non-running server', async () => {
+    // We don't have a live lightrag-server in tests, so rebuildGraph will
+    // ultimately return ok=false with error="lightrag disabled in .bizar/memory.json"
+    // OR ok=false with error about not running. Either way, it must NOT throw
+    // and must return a structured result.
+    mkdirSync(join(tmpRoot, '.bizar'), { recursive: true });
+    writeFileSync(join(tmpRoot, '.bizar', 'memory.json'), JSON.stringify({
+      projectId: 'rbproj',
+      memoryRepo: { mode: 'local-only', path: join(tmpRoot, '.obsidian') },
+      lightrag: { enabled: false },
+    }));
+    let result;
+    try {
+      result = await rebuildGraph(tmpRoot, {});
+    } catch (err) {
+      assert.fail(`rebuildGraph threw: ${err.message}`);
+    }
+    assert.ok(result);
+    assert.equal(typeof result.ok, 'boolean');
+    // workingDir should have been wiped and re-created (or attempted).
+  });
+});

package/bizar-dash/tests/memory-obsidian.test.mjs

@@ -0,0 +1,269 @@
+/**
+ * tests/memory-obsidian.test.mjs
+ *
+ * v4.7.0 — Tests for the memory-obsidian façade: CRUD re-exports + the
+ * higher-level helpers (tree, listBacklinks, linkGraph, diffVault) used by
+ * the Memory tab Obsidian panel.
+ *
+ * Uses an isolated tmp projectRoot per describe so the rest of the repo's
+ * memory config is untouched.
+ */
+
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { mkdirSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+
+const obsidian = await import('../src/server/memory-obsidian.mjs');
+const memoryStore = await import('../src/server/memory-store.mjs');
+
+let tmpRoot;
+
+beforeEach(() => {
+  tmpRoot = join(tmpdir(), `bizar-memobs-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  mkdirSync(join(tmpRoot, '.bizar'), { recursive: true });
+  memoryStore.saveConfig(tmpRoot, {
+    version: 1,
+    backend: 'bizar-local',
+    projectId: 'memobs-test',
+    memoryRepo: {
+      mode: 'local-only',
+      path: join(tmpRoot, '.obsidian'),
+      remote: null,
+      branch: 'main',
+      namespace: 'projects/memobs-test',
+    },
+    namespaces: {
+      project: 'projects/memobs-test',
+      global: 'global/bizar',
+      user: 'users/local',
+    },
+    lightrag: { enabled: false, host: '127.0.0.1', port: 9621 },
+    git: {
+      autoPullOnSessionStart: false,
+      autoCommitOnMemoryWrite: false,
+      autoPushOnSessionEnd: false,
+      commitAuthor: 'Test <test@local>',
+      commitMessageTemplate: 'memory(test): {summary}',
+    },
+  });
+  memoryStore.initVault(tmpRoot);
+});
+
+afterEach(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+// ── Re-exports sanity ─────────────────────────────────────────────────────
+
+describe('memory-obsidian façade', () => {
+  test('re-exports the canonical CRUD surface', () => {
+    assert.equal(typeof obsidian.listNotes, 'function');
+    assert.equal(typeof obsidian.readNote, 'function');
+    assert.equal(typeof obsidian.writeNote, 'function');
+    assert.equal(typeof obsidian.deleteNote, 'function');
+    assert.equal(typeof obsidian.searchVault, 'function');
+    assert.equal(typeof obsidian.vaultStats, 'function');
+    assert.equal(typeof obsidian.resolveVault, 'function');
+  });
+
+  test('exposes the Memory-tab specific helpers', () => {
+    assert.equal(typeof obsidian.tree, 'function');
+    assert.equal(typeof obsidian.listBacklinks, 'function');
+    assert.equal(typeof obsidian.linkGraph, 'function');
+    assert.equal(typeof obsidian.diffVault, 'function');
+  });
+});
+
+// ── tree ──────────────────────────────────────────────────────────────────
+
+describe('tree', () => {
+  test('returns null when vault does not exist', () => {
+    rmSync(join(tmpRoot, '.obsidian'), { recursive: true, force: true });
+    const result = obsidian.tree(tmpRoot);
+    assert.equal(result, null);
+  });
+
+  test('returns a folder node containing nested notes', () => {
+    memoryStore.writeNote(tmpRoot, 'daily/2026-07-04.md', {
+      frontmatter: fullFM({ title: 'Day 1' }),
+      body: 'first day',
+    });
+    memoryStore.writeNote(tmpRoot, 'daily/2026-07-05.md', {
+      frontmatter: fullFM({ title: 'Day 2' }),
+      body: 'second day',
+    });
+    memoryStore.writeNote(tmpRoot, 'patterns/auth.md', {
+      frontmatter: fullFM({ title: 'Auth pattern' }),
+      body: 'use bcrypt',
+    });
+    const root = obsidian.tree(tmpRoot);
+    assert.ok(root);
+    assert.equal(root.type, 'folder');
+    assert.ok(Array.isArray(root.children));
+    const folders = root.children.filter((c) => c.type === 'folder').map((c) => c.name);
+    assert.ok(folders.includes('daily'));
+    assert.ok(folders.includes('patterns'));
+  });
+});
+
+// ── listBacklinks ─────────────────────────────────────────────────────────
+
+describe('listBacklinks', () => {
+  test('returns empty for a note with no incoming links', () => {
+    memoryStore.writeNote(tmpRoot, 'target.md', {
+      frontmatter: fullFM({ title: 'Target' }),
+      body: 'no one links here',
+    });
+    const links = obsidian.listBacklinks(tmpRoot, 'target.md');
+    assert.deepEqual(links, []);
+  });
+
+  test('finds incoming wikilinks by basename', () => {
+    memoryStore.writeNote(tmpRoot, 'projects/api.md', {
+      frontmatter: fullFM({ title: 'API' }),
+      body: 'API details.',
+    });
+    memoryStore.writeNote(tmpRoot, 'daily/today.md', {
+      frontmatter: fullFM({ title: 'Today' }),
+      body: 'Working on [[api]] and [[projects/api]].',
+    });
+    const links = obsidian.listBacklinks(tmpRoot, 'projects/api.md');
+    assert.ok(links.length >= 1, 'expected at least one backlink');
+    const src = links.find((l) => l.fromRelPath === 'daily/today.md');
+    assert.ok(src);
+    assert.match(src.snippet, /\[\[api\]\]/);
+  });
+
+  test('handles wikilinks with aliases and headings', () => {
+    memoryStore.writeNote(tmpRoot, 'a.md', { frontmatter: fullFM({ title: 'A' }), body: 'a body' });
+    memoryStore.writeNote(tmpRoot, 'b.md', {
+      frontmatter: fullFM({ title: 'B' }),
+      body: 'See [[a|the A note]] for context.',
+    });
+    const links = obsidian.listBacklinks(tmpRoot, 'a.md');
+    assert.equal(links.length, 1);
+    assert.match(links[0].snippet, /\[\[a\|the A note\]\]/);
+  });
+
+  test('does not include the target itself', () => {
+    memoryStore.writeNote(tmpRoot, 'self.md', {
+      frontmatter: fullFM({ title: 'Self' }),
+      body: 'See [[self]] for context.',
+    });
+    const links = obsidian.listBacklinks(tmpRoot, 'self.md');
+    assert.deepEqual(links, []);
+  });
+});
+
+// ── linkGraph ─────────────────────────────────────────────────────────────
+
+describe('linkGraph', () => {
+  test('returns nodes for each note + edges for each wikilink', () => {
+    memoryStore.writeNote(tmpRoot, 'a.md', { frontmatter: fullFM({ title: 'A' }), body: 'links to [[b]]' });
+    memoryStore.writeNote(tmpRoot, 'b.md', { frontmatter: fullFM({ title: 'B' }), body: 'links to [[c]]' });
+    memoryStore.writeNote(tmpRoot, 'c.md', { frontmatter: fullFM({ title: 'C' }), body: 'no links' });
+    const g = obsidian.linkGraph(tmpRoot);
+    assert.ok(g.nodes.length >= 3);
+    assert.ok(g.edges.length >= 2);
+    for (const e of g.edges) {
+      assert.equal(typeof e.from, 'string');
+      assert.equal(typeof e.to, 'string');
+      assert.equal(typeof e.dangling, 'boolean');
+    }
+  });
+
+  test('marks non-existent targets as dangling', () => {
+    memoryStore.writeNote(tmpRoot, 'a.md', { frontmatter: fullFM({ title: 'A' }), body: 'links to [[ghost-note]]' });
+    const g = obsidian.linkGraph(tmpRoot);
+    const edge = g.edges.find((e) => e.raw === 'ghost-note');
+    assert.ok(edge, 'expected edge for ghost-note');
+    assert.equal(edge.dangling, true);
+  });
+});
+
+// ── diffVault ─────────────────────────────────────────────────────────────
+
+describe('diffVault', () => {
+  test('returns empty diff when notes are identical', () => {
+    memoryStore.writeNote(tmpRoot, 'a.md', { frontmatter: fullFM({ title: 'A' }), body: 'same body' });
+    memoryStore.writeNote(tmpRoot, 'b.md', { frontmatter: fullFM({ title: 'B' }), body: 'same body' });
+    const d = obsidian.diffVault(tmpRoot, 'a.md', 'b.md');
+    assert.ok(d.lines.length > 0);
+    for (const line of d.lines) {
+      assert.notEqual(line.kind, 'add');
+      assert.notEqual(line.kind, 'del');
+    }
+  });
+
+  test('returns add + del entries for differing notes', () => {
+    memoryStore.writeNote(tmpRoot, 'old.md', { frontmatter: fullFM({ title: 'Old' }), body: 'line1\nline2\nline3' });
+    memoryStore.writeNote(tmpRoot, 'new.md', { frontmatter: fullFM({ title: 'New' }), body: 'line1\nline4\nline5' });
+    const d = obsidian.diffVault(tmpRoot, 'old.md', 'new.md');
+    const adds = d.lines.filter((l) => l.kind === 'add').map((l) => l.text);
+    const dels = d.lines.filter((l) => l.kind === 'del').map((l) => l.text);
+    assert.ok(adds.includes('line4'), 'expected line4 added');
+    assert.ok(adds.includes('line5'), 'expected line5 added');
+    assert.ok(dels.includes('line2'), 'expected line2 deleted');
+    assert.ok(dels.includes('line3'), 'expected line3 deleted');
+  });
+
+  test('handles null fromPath gracefully', () => {
+    memoryStore.writeNote(tmpRoot, 'new.md', { frontmatter: fullFM({ title: 'New' }), body: 'fresh content' });
+    const d = obsidian.diffVault(tmpRoot, '', 'new.md');
+    assert.ok(d.lines.length > 0);
+    for (const line of d.lines) {
+      assert.ok(['add', 'same'].includes(line.kind));
+    }
+  });
+});
+
+// ── CRUD via the façade ───────────────────────────────────────────────────
+
+describe('CRUD via memory-obsidian façade', () => {
+  test('writeNote + readNote + deleteNote round-trip', () => {
+    const created = obsidian.writeNote(tmpRoot, 'foo/bar.md', {
+      frontmatter: fullFM({ title: 'Foo' }),
+      body: 'hello world',
+    });
+    assert.equal(created.relPath, 'foo/bar.md');
+    const read = obsidian.readNote(tmpRoot, 'foo/bar.md');
+    assert.ok(read);
+    assert.equal(read.frontmatter.title, 'Foo');
+    assert.equal(read.body, 'hello world');
+    const ok = obsidian.deleteNote(tmpRoot, 'foo/bar.md');
+    assert.equal(ok, true);
+    const after = obsidian.readNote(tmpRoot, 'foo/bar.md');
+    assert.equal(after, null);
+  });
+
+  test('searchVault finds notes by content', () => {
+    obsidian.writeNote(tmpRoot, 'search/a.md', { frontmatter: fullFM({ title: 'A' }), body: 'contains the magic word auth' });
+    obsidian.writeNote(tmpRoot, 'search/b.md', { frontmatter: fullFM({ title: 'B' }), body: 'no match here' });
+    const r = obsidian.searchVault(tmpRoot, 'auth', { limit: 5 });
+    assert.ok(r.length >= 1);
+    assert.ok(r[0].relPath.startsWith('search/'));
+  });
+});
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+/**
+ * Build a schema-valid frontmatter object with overrides for the test note.
+ * The memory-store schema requires memory_id, project_id, type, status,
+ * confidence, created, updated, tags.
+ */
+function fullFM(overrides = {}) {
+  return {
+    memory_id: `mem-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    project_id: 'memobs-test',
+    type: 'session_summary',
+    status: 'draft',
+    confidence: 'inferred',
+    created: '2026-07-05',
+    updated: '2026-07-05',
+    tags: ['test'],
+    ...overrides,
+  };
+}