@ilaomianyang/dsh-memory-graph 0.10.0

package/test/graphdata.mjs

@@ -0,0 +1,295 @@
+/**
+ * Session-view data checks.
+ *
+ * The panel in the Conversation row is only as honest as this payload: the
+ * filter that decides which episodes belong to the Session, the edges that claim
+ * a connection, and the caps that keep the drawing readable. None of that is
+ * visible from the browser side, so it is asserted here against a real vault in
+ * a temp directory.
+ *
+ *   node test/graphdata.mjs
+ */
+import assert from 'node:assert/strict'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import { resolveConfig } from '../src/config.js'
+import { createRedactor } from '../src/privacy.js'
+import { createVault } from '../src/vault.js'
+import {
+  GRAPH_PATH,
+  buildSessionGraph,
+  createGraphHandler,
+  dominantProject,
+  layoutNodes,
+  recallQuery,
+} from '../src/graphdata.js'
+
+const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'memgraph-graphdata-'))
+const results = []
+function check(name, fn) {
+  try {
+    fn()
+    results.push(`  ok   ${name}`)
+  } catch (error) {
+    results.push(`  FAIL ${name}: ${error.message}`)
+    process.exitCode = 1
+  }
+}
+async function checkAsync(name, fn) {
+  try {
+    await fn()
+    results.push(`  ok   ${name}`)
+  } catch (error) {
+    results.push(`  FAIL ${name}: ${error.message}`)
+    process.exitCode = 1
+  }
+}
+
+/* ---------------------------------------------------------------- the vault */
+
+const cfg = resolveConfig({ vaultDir: dir, defaultProject: 'proj-a' })
+const vault = createVault(cfg, createRedactor(cfg.privacy))
+await vault.ensure()
+
+const LEAK = 'ASSISTANT-TEXT-MUST-NOT-LEAK'
+await vault.appendEpisode({
+  t: '2026-11-02T10:00:00+08:00',
+  project: 'proj-a',
+  session: 'sess-1',
+  turn: 1,
+  user: '记忆库要用纯文本存。',
+  assistant: LEAK,
+})
+await vault.appendEpisode({
+  t: '2026-11-02T10:05:00+08:00',
+  project: 'proj-a',
+  session: 'sess-1',
+  turn: 2,
+  user: '实体页怎么把两个项目连起来？',
+  assistant: 'ok',
+})
+await vault.appendEpisode({
+  t: '2026-11-02T11:00:00+08:00',
+  project: 'proj-b',
+  session: 'sess-2',
+  turn: 1,
+  user: '别的会话在聊发布流程。',
+  assistant: 'ok',
+})
+
+const cardA = await vault.saveCard({
+  title: '记忆库用纯文本存储',
+  body: '每个记忆一个文件，可以 diff。',
+  kind: 'decision',
+  project: 'proj-a',
+  entities: ['memory-vault', 'markdown'],
+})
+const cardB = await vault.saveCard({
+  title: '实体页把项目串起来',
+  body: '实体是跨项目的连接点。',
+  kind: 'fact',
+  project: 'proj-a',
+  entities: ['entity-page'],
+})
+const cardC = await vault.saveCard({
+  title: '纯文本也能 grep',
+  body: '不需要索引也能查。',
+  kind: 'note',
+  project: 'proj-b',
+  entities: ['memory-vault'],
+})
+
+/* ------------------------------------------------------------- pure helpers */
+
+check('the route path is an exact /api path that Connection accepts', () => {
+  assert.equal(GRAPH_PATH, '/api/memory-graph.graph')
+  assert.equal(GRAPH_PATH.startsWith('/api/'), true)
+  assert.ok(GRAPH_PATH.length > '/api/'.length, 'connection rejects a bare channel path')
+})
+
+check('the project is the majority of the episodes and null when none name one', () => {
+  assert.equal(dominantProject([{ project: 'a' }, { project: 'b' }, { project: 'b' }]), 'b')
+  assert.equal(dominantProject([{ project: '' }, {}, { project: 'x' }]), 'x')
+  assert.equal(dominantProject([]), null)
+})
+
+check('the recall query is the newest turns, capped', () => {
+  const episodes = [{ user: 'one' }, { user: 'two' }, { user: 'three' }, { user: 'four' }]
+  assert.equal(recallQuery(episodes, { turns: 2 }), 'four\nthree', 'newest last')
+  assert.equal(recallQuery([{ user: '' }, { user: 'x' }]), 'x', 'empty turns are skipped')
+  const long = recallQuery([{ user: 'y'.repeat(4000) }], { maxChars: 120 })
+  assert.equal(long.length, 120)
+})
+
+check('the layout is deterministic and stays inside the box', () => {
+  const nodes = [
+    { key: 'a', k: 'session', r: 12 },
+    { key: 'b', k: 'episode', r: 5 },
+    { key: 'c', k: 'card', r: 7 },
+    { key: 'd', k: 'entity', r: 6 },
+  ]
+  const links = [
+    { s: 'a', t: 'b', k: 'said' },
+    { s: 'a', t: 'c', k: 'recall' },
+    { s: 'c', t: 'd', k: 'mentions' },
+  ]
+  layoutNodes(nodes, links)
+  const first = nodes.map((node) => [node.x, node.y])
+  for (const node of nodes) {
+    assert.equal(Number.isFinite(node.x) && Number.isFinite(node.y), true, `${node.key} has a position`)
+    assert.ok(node.x >= 0 && node.x <= 1080, `${node.key} x in the box`)
+    assert.ok(node.y >= 0 && node.y <= 640, `${node.key} y in the box`)
+  }
+  const again = nodes.map((node) => ({ ...node }))
+  layoutNodes(again, links)
+  assert.deepEqual(
+    again.map((node) => [node.x, node.y]),
+    first,
+    'same input, same picture: no Math.random',
+  )
+})
+
+/* -------------------------------------------------------------- the payload */
+
+let sessOne = null
+await checkAsync('a session sees only its own episodes', async () => {
+  sessOne = await buildSessionGraph({ vault, session: 'sess-1' })
+  assert.equal(sessOne.ok, true)
+  assert.equal(sessOne.project, 'proj-a')
+  assert.equal(sessOne.counts.episodes, 2)
+  assert.equal(sessOne.empty, false)
+  const episodes = sessOne.nodes.filter((node) => node.k === 'episode')
+  assert.equal(episodes.length, 2)
+  assert.deepEqual(
+    episodes.map((node) => node.label),
+    ['T1', 'T2'],
+  )
+  assert.equal(
+    sessOne.links.filter((link) => link.k === 'said').length,
+    2,
+    'the session said both episodes',
+  )
+})
+
+await checkAsync('the payload never carries the assistant side', () => {
+  assert.equal(JSON.stringify(sessOne).includes(LEAK), false)
+})
+
+await checkAsync('recalled cards are marked, their entities are drawn, links are wired', async () => {
+  const cards = sessOne.nodes.filter((node) => node.k === 'card' && !node.foreign)
+  assert.ok(cards.length >= 2, 'both project cards are on the graph')
+  assert.ok(sessOne.recall.length >= 1, 'the session text retrieves something')
+  const hot = sessOne.nodes.filter((node) => node.k === 'card' && node.hot === true)
+  assert.ok(hot.length >= 1, 'at least one card is marked as recalled')
+  assert.equal(
+    sessOne.links.filter((link) => link.k === 'recall').length,
+    sessOne.recall.length,
+    'one recall edge per recalled card',
+  )
+  const entities = sessOne.nodes.filter((node) => node.k === 'entity')
+  assert.ok(entities.length >= 2, 'the cards mention entities')
+  assert.ok(
+    sessOne.links.some((link) => link.k === 'mentions'),
+    'a card is joined to the entity it mentions',
+  )
+  const hotNode = hot[0]
+  assert.equal(typeof hotNode.body, 'string', 'the panel can show the body on click')
+  assert.equal(typeof hotNode.title, 'string')
+})
+
+await checkAsync('a card in another project is drawn dim when it shares an entity', async () => {
+  const foreign = sessOne.nodes.filter((node) => node.foreign === true)
+  assert.equal(foreign.length, 1, 'exactly the cross-project bridge')
+  assert.equal(foreign[0].id, cardC.card.id)
+  assert.equal(foreign[0].project, 'proj-b')
+  assert.ok(
+    sessOne.links.some((link) => link.s === `c:${cardC.card.id}` && link.k === 'mentions'),
+    'the bridge hangs off the shared entity',
+  )
+  assert.equal(sessOne.counts.foreign, 1)
+})
+
+await checkAsync('every link points at a node that exists', () => {
+  const keys = new Set(sessOne.nodes.map((node) => node.key))
+  for (const link of sessOne.links) {
+    assert.equal(keys.has(link.s), true, `missing source ${link.s}`)
+    assert.equal(keys.has(link.t), true, `missing target ${link.t}`)
+  }
+  assert.equal(new Set(sessOne.nodes.map((node) => node.key)).size, sessOne.nodes.length, 'keys are unique')
+})
+
+await checkAsync('a second session resolves to its own project', async () => {
+  const other = await buildSessionGraph({ vault, session: 'sess-2' })
+  assert.equal(other.project, 'proj-b')
+  assert.equal(other.counts.episodes, 1)
+  assert.ok(
+    other.nodes.some((node) => node.k === 'card' && node.id === cardC.card.id && !node.foreign),
+    'its own card is local here',
+  )
+})
+
+await checkAsync('an unknown session is an empty answer, not a failure', async () => {
+  const none = await buildSessionGraph({ vault, session: 'never-seen' })
+  assert.equal(none.ok, true)
+  assert.equal(none.empty, true)
+  assert.equal(none.counts.episodes, 0)
+  assert.equal(none.nodes.filter((node) => node.k === 'episode').length, 0)
+  assert.ok(
+    none.nodes.some((node) => node.k === 'session'),
+    'the session node still anchors the (empty) drawing',
+  )
+})
+
+await checkAsync('the caps hold and say they held', async () => {
+  const capped = await buildSessionGraph({ vault, session: 'sess-1', limits: { episodes: 1 } })
+  assert.equal(capped.nodes.filter((node) => node.k === 'episode').length, 1)
+  assert.equal(capped.truncated.episodes, true)
+  assert.equal(capped.counts.episodes, 2, 'the count still reports the real total')
+})
+
+/* ---------------------------------------------------------------- the route */
+
+const request = (session) =>
+  new Request(`http://127.0.0.1:12180${GRAPH_PATH}?session=${encodeURIComponent(session)}`)
+
+await checkAsync('the route answers JSON for a session', async () => {
+  const handler = createGraphHandler({ getVault: () => vault, getConfig: () => cfg })
+  const response = await handler(request('sess-1'))
+  assert.equal(response.status, 200)
+  assert.equal(response.headers.get('content-type').startsWith('application/json'), true)
+  assert.equal(response.headers.get('cache-control'), 'no-store')
+  const body = await response.json()
+  assert.equal(body.ok, true)
+  assert.equal(body.counts.episodes, 2)
+})
+
+await checkAsync('a request without a session is refused, not guessed', async () => {
+  const handler = createGraphHandler({ getVault: () => vault, getConfig: () => cfg })
+  const response = await handler(new Request(`http://127.0.0.1:12180${GRAPH_PATH}`))
+  assert.equal(response.status, 400)
+  assert.equal((await response.json()).reason, 'missing-session')
+})
+
+await checkAsync('a broken vault answers with something the panel can print', async () => {
+  const handler = createGraphHandler({
+    getVault: () => ({
+      readEpisodes: async () => {
+        throw new Error('vault is a directory of permission errors')
+      },
+    }),
+    getConfig: () => cfg,
+  })
+  const response = await handler(request('sess-1'))
+  assert.equal(response.status, 500)
+  const body = await response.json()
+  assert.equal(body.ok, false)
+  assert.equal(body.reason, 'unavailable')
+  assert.match(body.message, /permission/)
+})
+
+await fsp.rm(dir, { recursive: true, force: true })
+
+console.log(results.join('\n'))
+console.log(`\n${results.filter((line) => line.includes(' ok ')).length}/${results.length} checks passed`)

package/test/live-supersede.mjs

@@ -0,0 +1,78 @@
+/**
+ * Does a later correction actually retire the earlier memory? This is the one
+ * behaviour that cannot be checked offline, because it depends on the model
+ * filling `supersedes` with a real id.
+ *
+ *   node test/live-supersede.mjs [--keep]
+ *
+ * Round one distills a claim. Round two adds the user correcting it and distills
+ * again. The check passes when the old card ends up `superseded` and the new card
+ * points at it, which is the whole point of temporal validity.
+ */
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { resolveConfig } from '../src/config.js'
+import { createRedactor } from '../src/privacy.js'
+import { createVault } from '../src/vault.js'
+import { distill } from '../src/extract.js'
+
+const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'mem-supersede-'))
+const cfg = resolveConfig({
+  vaultDir: dir,
+  extractor: {
+    enabled: true,
+    // Direct endpoint on purpose: a bare `node` process has no harness llm service.
+    transport: 'http',
+    apiKeyEnv: process.env.LIVE_KEY_ENV || 'DEEPSEEK_API_KEY',
+    baseUrl: process.env.LIVE_BASE_URL || 'https://api.deepseek.com/v1',
+    model: process.env.LIVE_MODEL || 'deepseek-chat',
+  },
+})
+const redactor = createRedactor(cfg.privacy)
+const vault = createVault(cfg, redactor)
+const project = 'memory-graph'
+
+await vault.appendEpisode({
+  project,
+  t: '2026-11-01T09:00:00+08:00',
+  user: '记忆库在本地文件夹生成，方便上传到 GitHub 上共享。',
+  assistant: '纯文本文件就可以直接进 git，diff 和合并都没问题。',
+})
+const first = await distill({ cfg, vault, redactor })
+if (!first.ok || first.cards.length === 0) {
+  console.error('round one produced no cards', first)
+  process.exit(1)
+}
+const oldCards = await vault.listCards({ includeRetracted: true })
+console.log(`round 1: ${first.cards.map((card) => `${card.id} ${card.title}`).join(' | ')}`)
+
+await vault.appendEpisode({
+  project,
+  t: '2026-11-02T10:00:00+08:00',
+  user: '更正一下：共享出去的是插件这个项目，不是记忆本身。记忆是私有的，不应该上传。纯文本只是为了可读、可移植、无锁。',
+  assistant: '明白，记忆库当私有数据对待，共享的是插件包。',
+})
+const second = await distill({ cfg, vault, redactor })
+if (!second.ok) {
+  console.error('round two failed', second)
+  process.exit(1)
+}
+console.log(`round 2: ${second.cards.map((card) => `${card.id} ${card.title} supersedes=${JSON.stringify(card.supersedes ?? [])}`).join(' | ')}`)
+
+const after = await vault.listCards({ includeRetracted: true })
+const backwards = (card) => card.supersededBy ?? card.superseded_by ?? null
+const retired = after.filter((card) => card.status === 'superseded')
+const linking = after.filter((card) => (card.supersedes ?? []).length > 0)
+
+console.log('')
+console.log(`superseded cards: ${retired.map((card) => `${card.id} -> ${backwards(card)}`).join(', ') || 'none'}`)
+console.log(`cards that point at another: ${linking.map((card) => `${card.id} -> ${card.supersedes.join(',')}`).join(', ') || 'none'}`)
+
+const chained = retired.some((card) => backwards(card) && linking.some((newer) => newer.id === backwards(card) && newer.supersedes.includes(card.id)))
+const ok = retired.length > 0 && linking.length > 0 && chained
+console.log(ok ? '\nPASS: the correction retired the earlier memory, both directions linked' : '\nFAIL: the correction did not retire the earlier memory')
+
+if (process.argv.includes('--keep')) console.log(`kept: ${dir}`)
+else await fsp.rm(dir, { recursive: true, force: true })
+process.exit(ok ? 0 : 1)

package/test/live.mjs

@@ -0,0 +1,156 @@
+/**
+ * End-to-end check against a real model. Not part of `npm test`: it needs
+ * network access and spends tokens.
+ *
+ *   node test/live.mjs                      # seeded episodes, Chinese + English
+ *   node test/live.mjs --log <session.jsonl> # replay a real session log instead
+ *   node test/live.mjs --backlog 12          # 12 seeded episodes, to watch it batch
+ *   node test/live.mjs --tokens 900          # a small output budget, to watch it split
+ *   node test/live.mjs --dry                # show what the model proposes, write nothing
+ *   node test/live.mjs --keep               # leave the temp vault on disk to look at
+ *
+ * The key is resolved exactly the way the plugin resolves it: env var named by
+ * `extractor.apiKeyEnv`, then the harness credential store. Override the endpoint
+ * with LIVE_BASE_URL / LIVE_MODEL / LIVE_KEY_ENV.
+ */
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { resolveConfig } from '../src/config.js'
+import { createRedactor } from '../src/privacy.js'
+import { createVault } from '../src/vault.js'
+import { distill } from '../src/extract.js'
+import { searchCards } from '../src/search.js'
+import { registerCapture } from '../src/capture.js'
+
+const argv = process.argv.slice(2)
+const flag = (name) => argv.includes(`--${name}`)
+const value = (name) => {
+  const at = argv.indexOf(`--${name}`)
+  return at >= 0 ? argv[at + 1] : undefined
+}
+
+const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'mem-live-'))
+const cfg = resolveConfig({
+  vaultDir: dir,
+  extractor: {
+    enabled: true,
+    // This script talks to an endpoint directly; the plugin's default transport
+    // borrows Settings instead, which a bare `node` process cannot do.
+    transport: 'http',
+    apiKeyEnv: process.env.LIVE_KEY_ENV || 'DEEPSEEK_API_KEY',
+    baseUrl: process.env.LIVE_BASE_URL || 'https://api.deepseek.com/v1',
+    model: process.env.LIVE_MODEL || 'deepseek-chat',
+    ...(value('tokens') ? { maxOutputTokens: Number(value('tokens')) } : {}),
+  },
+})
+const redactor = createRedactor(cfg.privacy)
+const vault = createVault(cfg, redactor)
+
+const SEED = [
+  {
+    project: 'memory-graph',
+    t: '2026-10-28T10:12:00+08:00',
+    user: '我打算把长期记忆做成纯文本的库：episodes 存原始对话，cards 存蒸馏出来的记忆，entities 存实体索引。你觉得这样分层有问题吗？',
+    assistant:
+      '分层本身没问题，但要防止 cards 变成 episodes 的摘要备份。关键是 cards 必须有类型和有效期，否则过时的决策会一直毒害检索。建议每条卡片带 kind、valid_from/valid_to、supersedes，并且蒸馏只在离线显式触发，不挂在对话主路径上。',
+    tools: 0,
+  },
+  {
+    project: 'memory-graph',
+    t: '2026-10-28T10:41:00+08:00',
+    user: '那就定下来：蒸馏用一个单独的模型接口，key 从环境变量读，不写进配置文件。另外记忆只在模型主动查的时候给，不做自动注入。',
+    assistant:
+      '同意。自动注入会把记忆塞进每一个轮次，token 成本和污染风险都不划算；工具化按需查询可控得多。apiKeyEnv 默认 MEMORY_LLM_API_KEY，配置文件里永远只出现变量名。',
+    tools: 3,
+  },
+  {
+    project: 'blog-engine',
+    t: '2026-10-30T09:05:00+08:00',
+    user: 'The blog generator keeps rewriting my markdown footnotes. I want the pipeline to treat the markdown body as opaque: only rewrite frontmatter, never touch the rendered content.',
+    assistant:
+      'Then the transformer has to parse frontmatter and stop at the closing delimiter, passing the rest through byte-for-byte. Any markdown-aware step breaks that promise, so drop the remark/rehype pass from the publish path and run validation as a separate read-only check.',
+    tools: 1,
+  },
+]
+
+if (value('log')) {
+  const lines = fs.readFileSync(value('log'), 'utf8').split('\n').filter(Boolean)
+  const handlers = new Map()
+  const ctx = {
+    on(name, fn) {
+      if (!handlers.has(name)) handlers.set(name, [])
+      handlers.get(name).push(fn)
+      return () => {}
+    },
+    logger: { info() {}, warn() {} },
+  }
+  registerCapture(ctx, { cfg, vault, redactor })
+  const session = { id: 'live-replay', header: { cwd: process.cwd() } }
+  let seen = 0
+  for (const line of lines) {
+    let event
+    try {
+      event = JSON.parse(line)
+    } catch {
+      continue
+    }
+    if (!['user/message', 'assistant/message', 'tool/result', 'turn/end'].includes(event.type)) continue
+    seen += 1
+    for (const fn of handlers.get('session/event') ?? []) fn(session, event)
+  }
+  await new Promise((resolve) => setTimeout(resolve, 400))
+  console.log(`replayed ${seen} events from ${value('log')}`)
+} else {
+  const want = Number(value('backlog') ?? 0)
+  let i = 0
+  do {
+    const template = SEED[i % SEED.length]
+    const round = Math.floor(i / SEED.length)
+    await vault.appendEpisode({
+      ...template,
+      // Same content, different turn: a backlog has to look like a real session
+      // continuing rather than the same episode copied verbatim.
+      t: new Date(Date.parse(template.t) + round * 3600_000).toISOString(),
+      user: round === 0 ? template.user : `${template.user}（第 ${round + 1} 次讨论）`,
+    })
+    i += 1
+  } while (i < Math.max(SEED.length, want))
+  console.log(`seeded ${i} episodes`)
+}
+
+const stats = await vault.stats()
+console.log(`vault ${dir}\nepisodes: ${stats.episodes.records} · cards: ${stats.cards.total} · projects: ${stats.projects.join(', ') || '-'}`)
+if (stats.episodes.records === 0) {
+  console.error('no episodes to distill — nothing to check')
+  process.exit(1)
+}
+
+const started = Date.now()
+const report = await distill({ cfg, vault, redactor, dryRun: flag('dry') })
+const batching = report.batches ? ` · ${report.batches.done}/${report.batches.planned} batch(es) of ${report.batches.size}` : ''
+console.log(`\ndistill ${report.ok ? 'ok' : 'FAILED'} in ${Date.now() - started}ms · key=${report.keySource ?? '?'} · ${report.episodes} episode(s)${batching}`)
+
+if (!report.ok) {
+  console.error(report.reason)
+  process.exit(1)
+}
+if (report.dryRun) {
+  for (const card of report.proposed) console.log(`  [${card.kind}] ${card.title} · ${card.entities.join(', ')}`)
+  console.log(`\nskipped: ${report.skipped ?? '-'}`)
+} else {
+  for (const card of report.cards) console.log(`  ${card.id} [${card.kind}] ${card.title}${card.deduped ? ' (dup)' : ''}`)
+  const fresh = report.cards.filter((card) => !card.deduped).length
+  console.log(`written: ${fresh} new · ${report.cards.length - fresh} re-confirmed · usage: ${JSON.stringify(report.usage)}`)
+  console.log(`skipped: ${report.skipped ?? '-'}`)
+
+  // The loop only closes if what was written can be found again.
+  const probe = report.cards[0]?.title ?? 'memory'
+  const hits = searchCards(await vault.listCards(), probe, { limit: 3 })
+  console.log(`\nsearch "${probe.slice(0, 40)}" -> ${hits.length} hit(s)`)
+  for (const hit of hits) console.log(`  ${hit.score.toFixed(2)} ${hit.card.id} ${hit.card.title}`)
+}
+
+if (flag('keep')) console.log(`\nkept: ${dir}`)
+else await fsp.rm(dir, { recursive: true, force: true })

package/test/page.mjs

@@ -0,0 +1,116 @@
+/**
+ * The whole-vault graph page.
+ *
+ * This route is what makes the graph viewable inside the app: the sidebar panel
+ * embeds it, so the page has to be real HTML, has to be the *same* renderer the
+ * vault writes to disk, and has to say something printable when the vault is
+ * unreadable instead of handing the panel a blank frame.
+ *
+ *   node test/page.mjs
+ */
+import assert from 'node:assert/strict'
+import fsp from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import { PAGE_PATH, createPageHandler } from '../src/pageapi.js'
+import { resolveConfig } from '../src/config.js'
+import { createRedactor } from '../src/privacy.js'
+import { createVault } from '../src/vault.js'
+
+const results = []
+function check(name, fn) {
+  return Promise.resolve()
+    .then(fn)
+    .then(
+      () => results.push(`  ok   ${name}`),
+      (error) => {
+        results.push(`  FAIL ${name}: ${error.message}`)
+        process.exitCode = 1
+      },
+    )
+}
+
+const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'memgraph-page-'))
+const cfg = resolveConfig({ vaultDir: dir })
+const redactor = createRedactor(cfg.privacy)
+const vault = createVault(cfg, redactor)
+
+await check('the route sits on the authenticated /api channel like the other two', () => {
+  assert.ok(PAGE_PATH.startsWith('/api/'))
+  assert.ok(PAGE_PATH.includes('page'), 'it is the page door, not the graph door')
+  assert.ok(!PAGE_PATH.includes('?'), 'a query string would make the exact route never match')
+})
+
+await check('an empty vault still answers with a page, not an error', async () => {
+  const handler = createPageHandler({ getVault: () => vault })
+  const response = await handler()
+  assert.equal(response.status, 200)
+  assert.match(response.headers.get('content-type'), /text\/html/)
+  const body = await response.text()
+  assert.ok(body.toLowerCase().includes('<!doctype html'), body.slice(0, 80))
+})
+
+await check('it is the same renderer the vault writes to disk', async () => {
+  await vault.writeCard({
+    kind: 'decision',
+    project: '测试',
+    title: '整库图与应用里的面板是同一份渲染',
+    body: '因为第二份实现迟早会和库里的东西对不上。',
+    sources: [],
+  })
+  await vault.regenerateGraph()
+  const onDisk = await fsp.readFile(path.join(dir, 'graph.html'), 'utf8')
+  const handler = createPageHandler({ getVault: () => vault })
+  const served = await (await handler()).text()
+  // The timestamp differs between the two renders; everything structural must not.
+  // It carries the host's offset (`…T13:21:53+08:00`), not `Z`, so the normalizer
+  // has to accept both — matching only `Z` made this check pass or fail depending
+  // on whether the two renders landed in the same second.
+  const skeleton = (html) =>
+    html.replace(/<!--[^]*?-->/g, '').replace(/\d{4}-\d{2}-\d{2}T[\d:.]+(?:Z|[+-]\d{2}:\d{2})/g, 'T')
+  assert.equal(skeleton(served), skeleton(onDisk))
+})
+
+await check('the page is frameable by its own origin and nothing else', async () => {
+  const handler = createPageHandler({ getVault: () => vault })
+  const response = await handler()
+  assert.equal(response.headers.get('x-frame-options'), 'SAMEORIGIN')
+  assert.equal(response.headers.get('cache-control'), 'no-store', 'a stale graph would be a lie')
+})
+
+await check('a broken vault prints the reason instead of a blank frame', async () => {
+  const broken = {
+    graphPage: async () => {
+      throw new Error('EACCES: 读不了 <vault>/cards')
+    },
+  }
+  const handler = createPageHandler({ getVault: () => broken })
+  const response = await handler()
+  assert.equal(response.status, 500)
+  const body = await response.text()
+  assert.ok(body.includes('EACCES'), 'the reason is on the page')
+  assert.ok(body.includes('&lt;vault&gt;'), 'and it is escaped, not injected as markup')
+})
+
+await check('no vault at all is a 500 with a reason, not a crash', async () => {
+  const handler = createPageHandler({ getVault: () => null })
+  const response = await handler()
+  assert.equal(response.status, 500)
+  assert.ok((await response.text()).includes('vault unavailable'))
+})
+
+await check('the vault never reaches the browser as a path', async () => {
+  const handler = createPageHandler({ getVault: () => vault })
+  const body = await (await handler()).text()
+  assert.equal(body.includes(dir), false, 'the served page carries no vault path')
+  assert.equal(body.includes('episodes/'), false, 'and no vault-relative file names')
+})
+
+console.log(results.join('\n'))
+if (process.exitCode) {
+  console.log('\nSOME CHECKS FAILED')
+} else {
+  console.log(`\nall ${results.length} checks passed`)
+  await fsp.rm(dir, { recursive: true, force: true })
+}