@xingular/harness 0.0.0-stage → 0.1.0

package/src/memory/facts.ts

@@ -0,0 +1,248 @@
+// Facts: short, typed things to carry between runs (a preference, a decision). Each is a file,
+// `wiki/facts/<id>.md`, with frontmatter and a few lines of body, has sources and revisions like
+// a page, and changes only through the user or a validated proposal.
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { noteChange } from '../core/changes'
+import { HarnessError, invalid, notFound } from '../core/errors'
+import * as frontmatter from '../core/frontmatter'
+import { atomicWrite, now, safeId } from '../core/fs'
+import { comparePaths } from '../core/text'
+import { looksSecret } from './secrets'
+import * as store from './store'
+import { LIBRARY_NAMESPACE, ROOT_NAMESPACE, type WikiLink } from './store'
+
+/** A procedure is a skill, not a fact. */
+export const MEMORY_KINDS = ['preference', 'fact', 'decision', 'feedback'] as const
+/** A volatile fact older than this loses rank in search and is reported by Health. */
+export const STALE_DAYS = 30
+export const CONFIDENCE = ['high', 'medium', 'low'] as const
+export const STATUSES = ['active', 'superseded', 'archived'] as const
+/** A fact is short, not a document. Measured in bytes. */
+export const MAX_BODY = 2000
+
+export interface MemoryFront {
+  id: string
+  title: string
+  kind: string
+  /** `/` for everything, or a project namespace such as `/projects/agent-x`. */
+  namespace: string
+  sourceIds: string[]
+  confidence: string
+  status: string
+  supersedes: string | null
+  links: WikiLink[]
+  createdAt: string
+  updatedAt: string
+  /** When the fact was observed to be true. */
+  observedAt: string
+  /** Current state that will change. Never put in a compiled prompt; loses rank as it ages. */
+  volatile: boolean
+}
+
+export interface ParsedMemory {
+  front: MemoryFront
+  body: string
+  path: string
+}
+
+/** Days since the fact was observed (or last updated), when that can be read. */
+export function ageDays(front: MemoryFront): number | null {
+  const at = Date.parse(front.observedAt || front.updatedAt)
+  return Number.isNaN(at) ? null : Math.trunc((Date.now() - at) / 86_400_000)
+}
+
+export function isStale(front: MemoryFront): boolean {
+  const days = ageDays(front)
+  return front.volatile && front.status === 'active' && days !== null && days >= STALE_DAYS
+}
+
+export function memoryDir(wiki: string): string {
+  return join(wiki, 'facts')
+}
+
+/** The reason a fact is not valid, or `null`. */
+export function validate(front: MemoryFront, body: string): string | null {
+  try {
+    safeId(front.id)
+  } catch {
+    return 'The fact id must be letters, numbers, - or _.'
+  }
+  if (!front.title.trim() || !body.trim()) return 'A fact needs a title and a body.'
+  if (Buffer.byteLength(body) > MAX_BODY) return `A memory is a short fact; keep the body under ${MAX_BODY} characters and put longer material in a Wiki page.`
+  if (!(MEMORY_KINDS as readonly string[]).includes(front.kind)) return `A fact must be one of ${MEMORY_KINDS.join(', ')}.`
+  if (!(CONFIDENCE as readonly string[]).includes(front.confidence) || !(STATUSES as readonly string[]).includes(front.status)) return 'Unknown confidence or status.'
+  if (front.namespace !== ROOT_NAMESPACE && store.projectNamespaceOf(front.namespace) !== front.namespace && front.namespace !== LIBRARY_NAMESPACE) {
+    return "A memory's namespace is / or a project namespace (/projects/<slug>)."
+  }
+  return null
+}
+
+const optionalText = (value: unknown, fallback: string): string | null => (value === undefined ? fallback : typeof value === 'string' ? value : null)
+
+export function parse(text: string, path: string): ParsedMemory | null {
+  const parsed = frontmatter.parse(text)
+  if (!parsed) return null
+  const { id, title, kind, supersedes, volatile } = parsed.front
+  if (typeof id !== 'string' || typeof title !== 'string' || typeof kind !== 'string') return null
+  const namespace = optionalText(parsed.front.namespace, ROOT_NAMESPACE)
+  const confidence = optionalText(parsed.front.confidence, 'medium')
+  const status = optionalText(parsed.front.status, 'active')
+  const createdAt = optionalText(parsed.front.createdAt, '')
+  const updatedAt = optionalText(parsed.front.updatedAt, '')
+  const observedAt = optionalText(parsed.front.observedAt, '')
+  const sourceIds = store.stringList(parsed.front.sourceIds)
+  const links = store.linkList(parsed.front.links, id)
+  if (namespace === null || confidence === null || status === null || createdAt === null || updatedAt === null || observedAt === null || !sourceIds || !links) return null
+  if (supersedes !== undefined && supersedes !== null && typeof supersedes !== 'string') return null
+  if (volatile !== undefined && typeof volatile !== 'boolean') return null
+  return {
+    front: {
+      id,
+      title,
+      // Historical procedures read as facts without rewriting files or creating registry skills.
+      kind: kind === 'procedure' ? 'fact' : kind,
+      namespace,
+      sourceIds,
+      confidence,
+      status,
+      supersedes: supersedes ?? null,
+      links,
+      createdAt,
+      updatedAt,
+      observedAt,
+      volatile: volatile ?? false
+    },
+    body: parsed.body,
+    path
+  }
+}
+
+export function loadMemories(wiki: string): ParsedMemory[] {
+  const files: string[] = []
+  store.markdownFiles(memoryDir(wiki), files)
+  const memories: ParsedMemory[] = []
+  for (const path of files.sort(comparePaths)) {
+    try {
+      const memory = parse(readFileSync(path, 'utf8'), path)
+      if (memory) memories.push(memory)
+    } catch {
+      // An unreadable file is not a fact.
+    }
+  }
+  return memories
+}
+
+export function findMemory(wiki: string, id: string): ParsedMemory {
+  const memory = loadMemories(wiki).find((entry) => entry.front.id === id)
+  if (!memory) throw notFound('Memory')
+  return memory
+}
+
+export function serialize(front: MemoryFront, body: string): string {
+  return frontmatter.serialize(
+    {
+      id: front.id,
+      title: front.title,
+      kind: front.kind,
+      namespace: front.namespace,
+      sourceIds: front.sourceIds,
+      confidence: front.confidence,
+      status: front.status,
+      ...(front.supersedes === null ? {} : { supersedes: front.supersedes }),
+      links: front.links,
+      createdAt: front.createdAt,
+      updatedAt: front.updatedAt,
+      observedAt: front.observedAt,
+      ...(front.volatile ? { volatile: true } : {})
+    },
+    body
+  )
+}
+
+export function pathFor(wiki: string, id: string): string {
+  return join(memoryDir(wiki), `${safeId(id)}.md`)
+}
+
+/**
+ * Facts that apply in a project namespace (or everywhere): active ones in `/`, `/library`,
+ * or that namespace. Others stay retrievable by search.
+ */
+export function appliesTo(front: MemoryFront, projectNamespace: string | null): boolean {
+  return front.status === 'active' && (front.namespace === ROOT_NAMESPACE || front.namespace === LIBRARY_NAMESPACE || front.namespace === projectNamespace)
+}
+
+export type WikiMemory = Omit<MemoryFront, 'supersedes' | 'volatile'> & { supersedes?: string; volatile?: true; body: string; path: string; revisionId: string | null }
+
+export function response(wiki: string, memory: ParsedMemory): WikiMemory {
+  const { supersedes, volatile, ...front } = memory.front
+  return {
+    ...front,
+    ...(supersedes === null ? {} : { supersedes }),
+    ...(volatile ? { volatile: true as const } : {}),
+    body: memory.body,
+    path: memory.path,
+    revisionId: store.currentRevision(wiki, memory.front.id)
+  }
+}
+
+export interface MemoryInput {
+  id?: string | null
+  title: string
+  kind: string
+  namespace?: string
+  body: string
+  confidence?: string
+  status?: string
+  supersedes?: string | null
+  volatile?: boolean
+}
+
+/** A user's create or edit. Writes a revision before and after, like every other change. */
+export function saveAsUser(wiki: string, input: MemoryInput): WikiMemory {
+  const id = input.id ?? store.slug(input.title)
+  let existing: ParsedMemory | null = null
+  try {
+    existing = findMemory(wiki, id)
+  } catch {
+    existing = null
+  }
+  const sourceIds = existing ? [...existing.front.sourceIds] : []
+  if (!sourceIds.length) sourceIds.push('user')
+  const front: MemoryFront = {
+    id,
+    title: input.title.trim(),
+    kind: input.kind,
+    namespace: (input.namespace ?? ROOT_NAMESPACE).trim(),
+    sourceIds,
+    confidence: input.confidence ?? 'medium',
+    status: input.status ?? 'active',
+    supersedes: input.supersedes || null,
+    links: existing ? existing.front.links : [],
+    createdAt: existing?.front.createdAt || now(),
+    updatedAt: now(),
+    // Saving a fact again says it is still true now.
+    observedAt: now(),
+    volatile: input.volatile ?? false
+  }
+  const problem = validate(front, input.body)
+  if (problem) throw invalid(problem)
+  if (looksSecret(input.body)) throw invalid('The fact contains text that looks like a credential.')
+  const path = existing?.path ?? pathFor(wiki, id)
+  if (existing) {
+    let before: string
+    try {
+      before = readFileSync(existing.path, 'utf8')
+    } catch (error) {
+      throw new HarnessError('io_error', error instanceof Error ? error.message : String(error))
+    }
+    store.snapshot(wiki, id, before, 'user', 'Before edit')
+  }
+  const text = serialize(front, input.body)
+  atomicWrite(path, text)
+  store.snapshot(wiki, id, text, 'user', existing ? 'Edited' : 'Created')
+  noteChange({ wiki, id, path, text, actor: 'user', reason: existing ? 'Edited' : 'Created' })
+  store.log(wiki, `- ${now()} · user · memory · \`${id}\` ${existing ? 'edited' : 'created'}`)
+  return response(wiki, findMemory(wiki, id))
+}

package/src/memory/graph.ts

@@ -0,0 +1,103 @@
+// One graph of the Wiki: pages, facts, memory blocks, registry skills/prompts/rules, and sources
+// as nodes; frontmatter links, citations, and namespace membership as edges.
+import type { HarnessEnv } from '../core/env'
+import { charCount } from '../core/text'
+import * as registry from '../skills/registry'
+import * as blocks from './blocks'
+import * as facts from './facts'
+import * as store from './store'
+import { registryEntryKind } from './wiki'
+
+export interface GraphNode {
+  id: string
+  label: string
+  type: 'project' | 'page' | 'memory' | 'skill' | 'prompt' | 'rule' | 'block' | 'source'
+  pageType: string | null
+  namespace: string
+  summary: string
+  status: 'unresolved' | 'established' | 'stale'
+  provenance: string
+}
+
+export interface GraphEdge {
+  id: string
+  source: string
+  target: string
+  type: string
+  evidence: string | null
+}
+
+export interface GraphResponse {
+  nodes: GraphNode[]
+  edges: GraphEdge[]
+}
+
+const statusOf = (sourceIds: readonly string[]): 'unresolved' | 'established' => (sourceIds.length ? 'established' : 'unresolved')
+
+export function build(env: HarnessEnv): GraphResponse {
+  const wiki = store.wikiDir(env.root)
+  const pages = store.loadPages(wiki)
+  const memories = facts.loadMemories(wiki)
+  const nodes: GraphNode[] = pages.map((page) => ({
+    id: page.frontmatter.id,
+    label: page.frontmatter.title,
+    type: page.frontmatter.type === 'project' ? 'project' : 'page',
+    pageType: page.frontmatter.type,
+    namespace: page.location.namespace,
+    summary: store.firstParagraph(page.body),
+    status: statusOf(page.frontmatter.sourceIds),
+    provenance: `Wiki page ${page.location.path} · ${page.frontmatter.sourceIds.length} source(s)`
+  }))
+  for (const memory of memories) {
+    nodes.push({
+      id: memory.front.id,
+      label: memory.front.title,
+      type: 'memory',
+      pageType: memory.front.kind,
+      namespace: memory.front.namespace,
+      summary: store.firstParagraph(memory.body),
+      status: memory.front.status !== 'active' ? 'stale' : statusOf(memory.front.sourceIds),
+      provenance: `Memory · ${memory.front.confidence} confidence · ${memory.front.sourceIds.length} source(s)`
+    })
+  }
+  for (const item of registry.list(env.root)) {
+    const type = registryEntryKind(item.kind)
+    if (type) nodes.push({ id: item.id, label: item.name, type, pageType: null, namespace: store.ROOT_NAMESPACE, summary: item.description, status: 'established', provenance: `Registry item ${item.id}` })
+  }
+  for (const block of blocks.loadAll(wiki)) {
+    nodes.push({
+      id: block.id,
+      label: block.scope === 'agent' && block.owner ? `${env.directory.agentName(block.owner) ?? 'Removed agent'} · ${block.front.label}` : block.front.label,
+      type: 'block',
+      pageType: block.scope,
+      namespace: block.scope === 'project' && block.owner ? `/projects/${block.owner}` : store.ROOT_NAMESPACE,
+      summary: block.body.trim() ? store.firstParagraph(block.body) : block.front.description,
+      status: 'established',
+      provenance: `Memory block · ${charCount(block.body)} of ${block.front.limit} characters`
+    })
+  }
+  for (const source of store.listSources(wiki)) {
+    nodes.push({ id: source.id, label: source.name, type: 'source', pageType: null, namespace: store.ROOT_NAMESPACE, summary: `Imported source, version ${source.version}`, status: 'established', provenance: `Imported ${source.importedAt}` })
+  }
+
+  const ids = new Set(nodes.map((node) => node.id))
+  const edges: GraphEdge[] = []
+  const pushLinks = (from: string, links: readonly store.WikiLink[], sourceIds: readonly string[]): void => {
+    for (const link of links) if (ids.has(link.toId)) edges.push({ id: `${from}->${link.toId}:${link.type}`, source: from, target: link.toId, type: link.type, evidence: null })
+    for (const sourceId of sourceIds) if (ids.has(sourceId)) edges.push({ id: `${from}->${sourceId}:cites`, source: from, target: sourceId, type: 'references', evidence: sourceId })
+  }
+  for (const page of pages) pushLinks(page.frontmatter.id, page.frontmatter.links, page.frontmatter.sourceIds)
+  for (const memory of memories) pushLinks(memory.front.id, memory.front.links, memory.front.sourceIds)
+  // Namespace membership: entries in a project namespace attach to that project's overview page.
+  const projectPages = pages.filter((page) => page.frontmatter.type === 'project' && page.location.namespace.startsWith('/projects/')).map((page) => ({ namespace: page.location.namespace, id: page.frontmatter.id }))
+  const members = [
+    ...pages.map((page) => ({ id: page.frontmatter.id, namespace: page.location.namespace })),
+    ...memories.map((memory) => ({ id: memory.front.id, namespace: memory.front.namespace })),
+    ...nodes.filter((node) => node.type === 'block').map((node) => ({ id: node.id, namespace: node.namespace }))
+  ]
+  for (const member of members) {
+    const project = projectPages.find((entry) => entry.namespace === member.namespace && entry.id !== member.id)
+    if (project) edges.push({ id: `${member.id}->${project.id}:part_of`, source: member.id, target: project.id, type: 'part_of', evidence: null })
+  }
+  return { nodes, edges }
+}

package/src/memory/health.test.ts

@@ -0,0 +1,130 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, test } from 'vitest'
+
+import { dataRoot, writeFile } from '../../tests/helpers'
+import { createEnv } from '../core/env'
+import { now, readJson, writeJson } from '../core/fs'
+import * as blocks from './blocks'
+import { loadMemories } from './facts'
+import { build } from './graph'
+import { check } from './health'
+import { run, version, WIKI_VERSION } from './migrate'
+import { ensureProjectNamespace, isDir, isFile, loadPages, wikiDir } from './store'
+
+test('reports problems across the wiki', () => {
+  const root = dataRoot()
+  const wiki = wikiDir(root)
+  writeFileSync(join(wiki, 'library/tauri.md'), '---\nid: tauri\ntitle: Use Tauri\ntype: decision\nsourceIds: []\nlinks:\n  - toId: xingular-agent\n    type: references\n  - toId: electron\n    type: contradicts\n---\n\nWe use Tauri 2.\n')
+  writeFile(join(wiki, 'projects/xingular-agent/xingular-agent.md'), '---\nid: xingular-agent\ntitle: Xingular Agent\ntype: concept\n---\n\nThe app.\n')
+  writeFileSync(join(wiki, 'library/lonely.md'), '---\nid: lonely\ntitle: Lonely\ntype: concept\nsourceIds: [run:r1]\n---\n\nAlone.\n')
+  writeFileSync(join(wiki, 'facts/m.md'), '---\nid: m\ntitle: M\nkind: fact\nsourceIds: [src-missing]\n---\n\nFact.\n')
+  const report = check(root)
+  expect(report.brokenLinks).toHaveLength(1)
+  expect(report.contradictions).toHaveLength(1)
+  expect(report.orphanPages).toEqual(['lonely'])
+  expect([...report.missingEvidence].sort()).toEqual(['m', 'tauri', 'xingular-agent'])
+  expect([report.staleFacts, report.similarTitles, report.fullBlocks]).toEqual([[], [], []])
+})
+
+test('reports stale facts, near-duplicate titles and full blocks', () => {
+  const root = dataRoot()
+  ensureProjectNamespace(root, 'app', 'App')
+  const wiki = wikiDir(root)
+  for (const [file, title] of [['a', 'Linear MCP availability observed in run a3695ebe'], ['b', 'Linear MCP availability observed in run c54c128a'], ['c', 'Release plan']]) {
+    writeFileSync(join(wiki, `library/${file}.md`), `---\nid: ${file}\ntitle: ${title}\ntype: reference\nsourceIds: [user]\n---\n\nText.\n`)
+  }
+  writeFileSync(join(wiki, 'facts/old.md'), '---\nid: old\ntitle: Open issues\nkind: fact\nvolatile: true\nobservedAt: 2020-01-01T00:00:00Z\nsourceIds: [user]\n---\n\nThree open.\n')
+  writeFileSync(join(wiki, 'facts/new.md'), `---\nid: new\ntitle: On call\nkind: fact\nvolatile: true\nobservedAt: ${now()}\nsourceIds: [user]\n---\n\nNora.\n`)
+  const user = blocks.ensureUser(wiki)
+  writeFileSync(user.path, blocks.serializeBlock({ ...user.front, limit: 20 }, 'Nineteen characters'))
+  const report = check(root)
+  expect(report.staleFacts).toEqual(['old'])
+  expect(report.similarTitles).toEqual([['a', 'b']])
+  expect(report.fullBlocks).toEqual(['blocks/shared/user'])
+  // A project's skeleton pages start empty and unlinked without being reported.
+  expect(report.orphanPages).toEqual(['a', 'b', 'c'])
+  expect(report.missingEvidence).toEqual([])
+})
+
+test('graph spans namespaces, memories and registry', () => {
+  const root = dataRoot()
+  ensureProjectNamespace(root, 'app', 'App')
+  const wiki = wikiDir(root)
+  writeFileSync(join(wiki, 'projects/app/arch.md'), '---\nid: arch\ntitle: Arch\ntype: concept\nlinks:\n  - toId: skills/review\n    type: uses\n---\n\nBody.\n')
+  writeFileSync(join(wiki, 'facts/m.md'), '---\nid: m\ntitle: M\nkind: fact\nnamespace: /projects/app\n---\n\nFact.\n')
+  writeFile(join(root, 'registry/skills/review.md'), 'Review code.\n')
+  const graph = build(createEnv(root))
+  const types = new Set(graph.nodes.map((node) => node.type))
+  for (const type of ['project', 'memory', 'skill'] as const) expect(types.has(type)).toBe(true)
+  expect(graph.edges.some((edge) => edge.source === 'arch' && edge.target === 'skills/review')).toBe(true)
+  expect(graph.edges.some((edge) => edge.source === 'm' && edge.target === 'project-app' && edge.type === 'part_of')).toBe(true)
+})
+
+function v2Layout(): string {
+  const root = mkdtempSync(join(tmpdir(), 'harness-migrate-'))
+  writeJson(join(root, 'projects.json'), [{ id: 'p1', name: 'Xingular Agent', slug: 'xingular-agent', rootPath: '/tmp/x', autoMaintenance: true, createdAt: '2026-01-01T00:00:00Z' }])
+  writeFile(join(root, 'config/storage.json'), '{"wikiVersion":2}')
+  writeFile(join(root, 'wiki/docs/observed.md'), '---\nid: observed\ntitle: Observed in run\ntype: reference\n---\n\nA run.\n')
+  writeFile(join(root, 'wiki/memory/pnpm.md'), '---\nid: pnpm\ntitle: Use pnpm\nkind: preference\n---\n\nUse pnpm.\n')
+  writeFile(join(root, 'wiki/log.md'), '# Maintenance log\n\n- t · user · ingest\n')
+  writeFile(join(root, 'registry/rules/style.md'), 'Use spaces.\n')
+  return root
+}
+
+test('version 3 starts clean and keeps the old wiki as a backup', () => {
+  const root = v2Layout()
+  expect(version(root)).toBe(2)
+  expect(run(createEnv(root), ['a1'])).toBe(true)
+  const wiki = wikiDir(root)
+  expect(loadPages(wiki).every((page) => page.frontmatter.id !== 'observed')).toBe(true)
+  expect(loadMemories(wiki)).toEqual([])
+  for (const relative of ['blocks/shared/user.md', 'blocks/agents/a1/persona.md', 'blocks/agents/a1/notes.md', 'blocks/projects/xingular-agent/brief.md', 'projects/xingular-agent/overview.md']) expect(isFile(join(wiki, relative))).toBe(true)
+  expect(isDir(join(wiki, 'library')) && isDir(join(wiki, 'facts'))).toBe(true)
+  expect(isFile(join(root, 'wiki.pre-v3/docs/observed.md')) && isFile(join(root, 'wiki.pre-v3/memory/pnpm.md'))).toBe(true)
+  expect(readFileSync(join(root, 'registry/rules/style.md'), 'utf8')).toBe('Use spaces.\n')
+  expect(isDir(join(root, 'wiki.migrating'))).toBe(false)
+  expect(version(root)).toBe(WIKI_VERSION)
+  expect(run(createEnv(root))).toBe(false)
+})
+
+test('a version 2 wiki without a marker is still migrated', () => {
+  const root = v2Layout()
+  rmSync(join(root, 'config/storage.json'))
+  expect(version(root)).toBe(2)
+  expect(run(createEnv(root))).toBe(true)
+  expect(isFile(join(root, 'wiki.pre-v3/docs/observed.md'))).toBe(true)
+})
+
+test('version 1 knowledge is kept as a backup and personal items become global', () => {
+  const root = mkdtempSync(join(tmpdir(), 'harness-migrate-'))
+  writeJson(join(root, 'projects.json'), [{ id: 'p1', name: 'Xingular Agent', rootPath: '/tmp/x', autoMaintenance: true, createdAt: '2026-01-01T00:00:00Z' }])
+  writeFile(join(root, 'knowledge/personal/wiki/overview.md'), '---\nid: overview\ntitle: Mine\ntype: summary\n---\n\nMine.\n')
+  writeFile(join(root, 'config/registry-enabled.json'), '{"personal":["skills/a"],"p1":["rules/b"]}')
+  expect(version(root)).toBe(1)
+  expect(run(createEnv(root))).toBe(true)
+  expect(isDir(join(root, 'knowledge'))).toBe(false)
+  expect(isFile(join(root, 'knowledge.pre-v2/personal/wiki/overview.md'))).toBe(true)
+  expect(isFile(join(wikiDir(root), 'blocks/projects/xingular-agent/brief.md'))).toBe(true)
+  const enablement = readJson<Record<string, string[]>>(join(root, 'config/registry-enabled.json'))!
+  expect(enablement.global[0]).toBe('skills/a')
+  expect('personal' in enablement).toBe(false)
+})
+
+test('a failed migration leaves the wiki untouched', () => {
+  const root = v2Layout()
+  // An unreadable project registry makes staging fail.
+  writeFileSync(join(root, 'projects.json'), 'not json')
+  expect(() => run(createEnv(root))).toThrow()
+  expect(isFile(join(root, 'wiki/docs/observed.md'))).toBe(true)
+  expect(isDir(join(root, 'wiki.migrating')) || isDir(join(root, 'wiki.pre-v3'))).toBe(false)
+  expect(version(root)).toBe(2)
+})
+
+test('fresh data roots need no migration', () => {
+  const root = mkdtempSync(join(tmpdir(), 'harness-migrate-'))
+  mkdirSync(root, { recursive: true })
+  expect(version(root)).toBe(WIKI_VERSION)
+  expect(run(createEnv(root))).toBe(false)
+})

package/src/memory/health.ts

@@ -0,0 +1,74 @@
+// Health checks over the whole Wiki. They report problems with a route to the affected
+// entries and never delete anything.
+import { charCount } from '../core/text'
+import * as registry from '../skills/registry'
+import * as blocks from './blocks'
+import * as facts from './facts'
+import { lastOperationAt } from './operations'
+import * as store from './store'
+
+export interface HealthReport {
+  brokenLinks: { pageId: string; targetId: string }[]
+  orphanPages: string[]
+  missingEvidence: string[]
+  contradictions: { fromId: string; toId: string }[]
+  duplicateIds: string[]
+  /** Volatile facts that have not been observed for a while and may no longer be true. */
+  staleFacts: string[]
+  /** Groups of pages whose titles differ only by a run id, a number, or punctuation. */
+  similarTitles: string[][]
+  /** Memory blocks at 90% of their limit or more. */
+  fullBlocks: string[]
+  lastMaintenanceAt: string | null
+}
+
+const IGNORED_WORDS = new Set(['the', 'a', 'an', 'in', 'of', 'run'])
+
+/** A title without the parts that make near-duplicates look different: case, punctuation, numbers, and id-like words. */
+function titleKey(title: string): string {
+  return title.toLowerCase().split(/[^\p{Alphabetic}\p{N}]+/u).filter((word) => word && !/[0-9]/.test(word) && !IGNORED_WORDS.has(word)).join(' ')
+}
+
+export function check(root: string): HealthReport {
+  const wiki = store.wikiDir(root)
+  const pages = store.loadPages(wiki)
+  const memories = facts.loadMemories(wiki)
+  const sourceIds = new Set(store.listSources(wiki).map((source) => source.id))
+  const registryIds = registry.list(root).map((item) => item.id)
+
+  // Every page and fact; `standalone` ones need neither links nor sources.
+  const entries = [
+    ...pages.map((page) => ({ id: page.frontmatter.id, links: page.frontmatter.links, sources: page.frontmatter.sourceIds, standalone: page.frontmatter.id === 'home' || page.frontmatter.type === 'project' || store.isSkeleton(page.location) })),
+    ...memories.map((memory) => ({ id: memory.front.id, links: memory.front.links, sources: memory.front.sourceIds, standalone: true }))
+  ]
+  const seen = new Set<string>()
+  const duplicateIds = entries.filter((entry) => seen.size === seen.add(entry.id).size).map((entry) => entry.id)
+  const known = new Set([...entries.map((entry) => entry.id), ...sourceIds, ...registryIds])
+  const linked = new Set(entries.flatMap((entry) => entry.links.map((link) => link.toId)))
+  const validEvidence = (id: string): boolean => sourceIds.has(id) || store.isExternalEvidence(id)
+
+  // Pages in one namespace whose titles reduce to the same key, in namespace then key order.
+  const groups = new Map<string, { namespace: string; key: string; ids: string[] }>()
+  for (const page of pages) {
+    if (store.isSkeleton(page.location) || page.frontmatter.type === 'project') continue
+    const key = titleKey(page.frontmatter.title)
+    if (!key) continue
+    const name = `${page.location.namespace}\u0000${key}`
+    if (!groups.has(name)) groups.set(name, { namespace: page.location.namespace, key, ids: [] })
+    groups.get(name)!.ids.push(page.frontmatter.id)
+  }
+  const ordered = [...groups.values()].sort((left, right) => (left.namespace === right.namespace ? (left.key < right.key ? -1 : left.key > right.key ? 1 : 0) : left.namespace < right.namespace ? -1 : 1))
+
+  return {
+    brokenLinks: entries.flatMap((entry) => entry.links.filter((link) => !known.has(link.toId)).map((link) => ({ pageId: entry.id, targetId: link.toId }))),
+    // Home, project overviews, and facts stand on their own; other pages should be linked.
+    orphanPages: entries.filter((entry) => !entry.standalone && !entry.links.length && !linked.has(entry.id)).map((entry) => entry.id),
+    missingEvidence: entries.filter((entry) => (!entry.standalone && !entry.sources.length) || entry.sources.some((id) => !validEvidence(id))).map((entry) => entry.id),
+    contradictions: entries.flatMap((entry) => entry.links.filter((link) => link.type === 'contradicts').map((link) => ({ fromId: entry.id, toId: link.toId }))),
+    duplicateIds,
+    staleFacts: memories.filter((memory) => facts.isStale(memory.front)).map((memory) => memory.front.id),
+    similarTitles: ordered.filter((group) => group.ids.length > 1).map((group) => group.ids),
+    fullBlocks: blocks.loadAll(wiki).filter((block) => block.front.limit > 0 && charCount(block.body) * 100 >= block.front.limit * 90).map((block) => block.id),
+    lastMaintenanceAt: lastOperationAt(wiki)
+  }
+}