@xingular/harness 0.1.7 → 1.0.0

package/src/memory/curation.ts

@@ -1,64 +0,0 @@
-import { readdirSync } from 'node:fs'
-import { join } from 'node:path'
-import { createHash } from 'node:crypto'
-
-import { invalid, notFound } from '../core/errors'
-import { newId, now, readJson, safeId, writeJson } from '../core/fs'
-import type { CallerContext } from './caller'
-import type { Job } from './maintenance'
-import type { MaintenanceRequest } from './maintainer'
-import { captureHashes, parseProposalSet, type ProposalSet, type RegistryProposal, type Evidence, type Trigger } from './proposals'
-import { looksSecret } from './secrets'
-import * as store from './store'
-
-export type CurationInput = Job
-  | { kind: 'proposal'; namespace: string; proposals: ProposalSet; caller: CallerContext }
-  | { kind: 'registry'; proposal: RegistryProposal; caller: CallerContext }
-  | { kind: 'plugin'; proposal: unknown; caller: CallerContext }
-export interface CurationJob {
-  id: string
-  key: string
-  input: CurationInput
-  status: 'queued' | 'running' | 'completed' | 'failed' | 'rejected' | 'needs_user'
-  createdAt: string
-  updatedAt: string
-  runId: string | null
-  reason: string
-  hashes: [string, string][]
-  prepared?: { request: MaintenanceRequest; evidence: Evidence; namespace: string; trigger: Trigger }
-  receipt: { operationId: string | null; notes: string[]; parked: number; flagged: number } | null
-}
-
-const directory = (root: string): string => join(store.wikiDir(root), 'maintenance-jobs')
-export function listCuration(root: string): CurationJob[] {
-  let names: string[] = []
-  try { names = readdirSync(directory(root)) } catch { return [] }
-  return names.filter((name) => name.endsWith('.json')).flatMap((name) => {
-    const job = readJson<CurationJob>(join(directory(root), name))
-    return job && typeof job.id === 'string' && job.input && typeof job.input.kind === 'string' ? [job] : []
-  }).sort((a, b) => a.createdAt.localeCompare(b.createdAt))
-}
-export function curationJob(root: string, id: string): CurationJob {
-  const job = readJson<CurationJob>(join(directory(root), `${safeId(id)}.json`))
-  if (!job) throw notFound('Maintenance job')
-  return job
-}
-export function saveCuration(root: string, job: CurationJob): CurationJob {
-  writeJson(join(directory(root), `${safeId(job.id)}.json`), { ...job, updatedAt: now() })
-  return job
-}
-export function enqueueCuration(root: string, input: CurationInput): CurationJob {
-  if (input.kind === 'proposal') input = { ...input, proposals: parseProposalSet(input.proposals) }
-  if (Buffer.byteLength(JSON.stringify(input)) > 256 * 1024) throw invalid('The proposal is larger than 256 KiB.')
-  if (looksSecret(JSON.stringify(input))) throw invalid('The proposal contains text that looks like a credential.')
-  const captured = captureHashes(store.wikiDir(root))
-  const revisions = input.kind === 'consolidate' ? input.blockIds.map(id => [id, captured.get(id)]) : undefined
-  const key = createHash('sha256').update(JSON.stringify({ input, revisions })).digest('hex')
-  const existing = listCuration(root).find((job) => job.key === key)
-  if (existing) return existing
-  const timestamp = now()
-  return saveCuration(root, { id: newId(), key, input, status: 'queued', createdAt: timestamp, updatedAt: timestamp, runId: null, reason: '', hashes: [...captured], receipt: null })
-}
-export function requireCurator(context: CallerContext): void {
-  if (context.vaultAccess !== 'curator' || !context.runId) throw invalid('This operation needs a curator capability issued by the host for this run.')
-}

package/src/memory/dispatch.ts

@@ -1,59 +0,0 @@
-// One entry point for every memory, recall, and Wiki call a session makes, whichever way it
-// reaches the harness (a Pi tool, the `xagent-wiki` command, the bundled MCP server).
-import type { Bus } from '../core/bus'
-import type { HarnessEnv } from '../core/env'
-import { HarnessError } from '../core/errors'
-import { launchText, load, render } from '../prompt/compile'
-import * as api from './api'
-import type { CallerContext } from './caller'
-import * as recall from './recall'
-import { reindexQuietly } from './wikiIndex'
-
-export type DispatchEnv = HarnessEnv & { bus?: Bus }
-
-/** Runs one call and returns its reply as text for a model. */
-export function dispatch(env: DispatchEnv, context: CallerContext, call: string, params: api.Params, contributions?: readonly string[]): string {
-  switch (call) {
-    case 'wiki.entrypoint': {
-      const recorded = context.runId ? safely(() => load(env.root, context.runId!)) : null
-      return recorded ? render(env, recorded) : launchText(env, context)
-    }
-    case 'recall.search':
-      return recall.searchTool(env, context, params)
-    case 'recall.read':
-      return recall.readTool(env, context, params)
-    case 'memory.append':
-    case 'memory.replace':
-    case 'memory.rethink': {
-      const text = api.memoryEdit(env, context, call, params)
-      env.bus?.emit({ type: 'wiki.changed' })
-      return text
-    }
-    case 'wiki.search':
-      return api.search(env, context, params)
-    case 'wiki.read':
-      return api.read(env, context, params)
-    case 'wiki.list':
-      return api.list(env, params)
-    case 'wiki.skill':
-      return api.skill(env, context, params, contributions)
-    case 'wiki.memory':
-      return api.memories(env, context, params)
-    case 'wiki.propose': {
-      const text = api.propose(env, context, params)
-      reindexQuietly(env.root)
-      env.bus?.emit({ type: 'wiki.changed' })
-      return text
-    }
-    default:
-      throw new HarnessError('unknown_method', call.startsWith('memory.') ? `Unknown memory call ${call}.` : `Unknown Wiki call ${call}.`)
-  }
-}
-
-function safely<T>(read: () => T): T | null {
-  try {
-    return read()
-  } catch {
-    return null
-  }
-}

package/src/memory/facts.test.ts

@@ -1,41 +0,0 @@
-import { expect, test } from 'vitest'
-
-import { dataRoot } from '../../tests/helpers'
-import { now } from '../core/fs'
-import { appliesTo, isStale, loadMemories, parse, response, saveAsUser, type MemoryFront, type MemoryInput } from './facts'
-import { readManifest, wikiDir } from './store'
-
-test('reads legacy procedures as facts without changing their content', () => {
-  const parsed = parse('---\nid: legacy\ntitle: Legacy procedure\nkind: procedure\n---\n\nFollow these steps.\n', '/tmp/legacy.md')!
-  expect(parsed.front.kind).toBe('fact')
-  expect(parsed.body).toBe('Follow these steps.\n')
-  const value = response(dataRoot(), parsed)
-  expect(value.kind).toBe('fact')
-  expect(value.body).toBe('Follow these steps.\n')
-})
-
-const input = (title: string, kind: string): MemoryInput => ({ title, kind, namespace: '/', body: 'Use pnpm, not npm.', confidence: 'high', status: 'active' })
-
-test('saves, validates and revisions memories', () => {
-  const wiki = wikiDir(dataRoot())
-  const saved = saveAsUser(wiki, input('Package manager', 'preference'))
-  expect(saved.id).toBe('package-manager')
-  expect(saved.sourceIds).toEqual(['user'])
-  saveAsUser(wiki, { ...input('Package manager', 'preference'), id: 'package-manager', body: 'Use pnpm everywhere.' })
-  expect(readManifest(wiki, 'package-manager')).toHaveLength(3)
-  expect(() => saveAsUser(wiki, input('Bad', 'opinion'))).toThrow()
-  expect(() => saveAsUser(wiki, input('Steps', 'procedure'))).toThrow()
-  expect(() => saveAsUser(wiki, { ...input('Scoped', 'fact'), namespace: '/elsewhere' })).toThrow()
-  expect(loadMemories(wiki)).toHaveLength(1)
-})
-
-test('applies by namespace and status', () => {
-  const front: MemoryFront = { id: 'm', title: 'M', kind: 'fact', namespace: '/projects/a', sourceIds: [], confidence: 'high', status: 'active', supersedes: null, links: [], createdAt: '', updatedAt: '', observedAt: '', volatile: false }
-  expect(isStale(front)).toBe(false)
-  expect(isStale({ ...front, volatile: true, observedAt: '2020-01-01T00:00:00Z' })).toBe(true)
-  expect(isStale({ ...front, volatile: true, observedAt: now() })).toBe(false)
-  expect(appliesTo(front, '/projects/a')).toBe(true)
-  expect(appliesTo(front, '/projects/b')).toBe(false)
-  expect(appliesTo({ ...front, namespace: '/' }, null)).toBe(true)
-  expect(appliesTo({ ...front, namespace: '/', status: 'archived' }, null)).toBe(false)
-})

package/src/memory/facts.ts

@@ -1,248 +0,0 @@
-// 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/xagent`. */
-  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

@@ -1,103 +0,0 @@
-// 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

@@ -1,130 +0,0 @@
-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)
-})