@xingular/harness 2.1.1 → 3.0.0

package/src/memory/curation.test.ts

@@ -1,206 +0,0 @@
-import { existsSync, mkdtempSync } from 'node:fs'
-import { join } from 'node:path'
-import { tmpdir } from 'node:os'
-import { afterEach, expect, test } from 'vitest'
-
-import { createHarness, type Harness } from '../harness'
-import { memorySecretStore } from '../accounts/secrets'
-import type { PiSessionLike } from '../sessions/runner'
-import { registryTools } from '../tools/registryWrite'
-import type { ToolSession } from '../tools/types'
-import * as blocks from './blocks'
-import { memoryEdit, propose } from './api'
-import { enqueueCuration } from './curation'
-import { findMemory, saveAsUser } from './facts'
-import * as registry from '../skills/registry'
-import * as attachments from '../plugins/attachments'
-import { listInbox } from './operations'
-import { wikiDir } from './store'
-
-const opened: Harness[] = []
-afterEach(async () => { for (const harness of opened.splice(0)) await harness.close() })
-const self = { agentId: 'nora', agentName: 'Nora', actor: 'Chat', vaultAccess: 'self' as const, runId: 'origin' }
-const curator = { agentId: 'curator', agentName: 'Curator', actor: 'Chat', vaultAccess: 'curator' as const, runId: 'review' }
-
-function setup(): Harness {
-  let emit: (event: unknown) => void = () => undefined
-  const session: PiSessionLike = { sessionId: 'test-session', subscribe: listener => { emit = listener as never; return () => undefined }, prompt: async () => { emit({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text: 'Prefer pnpm for all builds.' }] } }) }, sendCustomMessage: async () => undefined, abort: async () => undefined, dispose: () => undefined }
-  const harness = createHarness({ dataRoot: mkdtempSync(join(tmpdir(), 'curation-data-')), stateDir: mkdtempSync(join(tmpdir(), 'curation-state-')), externalMaintenance: true, secrets: memorySecretStore(), sessionFactory: async () => session, maintainerFactory: async () => { throw new Error('Hidden maintenance must not run') } })
-  opened.push(harness)
-  harness.accounts.create('Main', 'apiKey')
-  blocks.ensureAgent(wikiDir(harness.env.root), 'nora')
-  return harness
-}
-async function origin(harness: Harness): Promise<void> {
-  await harness.sessions.run({ run: { id: 'origin', sessionId: 'nora' }, cwd: harness.env.root, sessionDir: join(harness.env.root, 'history'), text: 'Prefer pnpm for all builds.', caller: self, tools: { allow: [] } })
-  await new Promise(resolve => setTimeout(resolve, 30))
-}
-
-test('normal callers directly write only their own persona and notes; standalone callers retain their prior scope', () => {
-  const h = setup()
-  expect(memoryEdit(h.env, self, 'memory.append', { block: 'notes', text: 'Working on release notes.' })).toContain('Updated')
-  expect(() => memoryEdit(h.env, self, 'memory.append', { block: 'user', text: 'A shared preference.' })).toThrow('outside your writable memory')
-  blocks.ensureAgent(wikiDir(h.env.root), 'other')
-  expect(() => memoryEdit(h.env, self, 'memory.append', { block: 'blocks/agents/other/notes', text: 'Not mine.' })).toThrow()
-  expect(memoryEdit(h.env, { ...self, vaultAccess: undefined }, 'memory.append', { block: 'user', text: 'Standalone scope.' })).toContain('Updated')
-})
-
-test('a shared fact is proposed without writing, then validated against its original run and applied once', async () => {
-  const h = setup(); await origin(h)
-  const submitted = propose(h.env, self, { kind: 'fact', title: 'Build tool', body: 'Use pnpm for builds.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current', excerpt: 'Prefer pnpm for all builds.' }] })
-  const job = h.maintenance.jobs().find(job => job.input.kind === 'proposal')!
-  expect(submitted).toContain(job.id)
-  expect(() => findMemory(wikiDir(h.env.root), 'build-tool')).toThrow()
-  expect(() => h.maintenance.readJob(self, job.id)).toThrow('curator capability')
-  const receipt = h.maintenance.applyJob(curator, job.id, undefined, 'Preserve the stated build preference.')
-  expect(receipt.status).toBe('completed')
-  expect(findMemory(wikiDir(h.env.root), 'build-tool').front.sourceIds).toContain('run:origin')
-  expect(h.maintenance.applyJob(curator, job.id, undefined, 'Retry receipt').receipt).toEqual(receipt.receipt)
-})
-
-test('an assigned proposal batch is read together and committed as one reconciled Wiki operation', async () => {
-  const h = setup(); await origin(h)
-  propose(h.env, self, { kind: 'fact', title: 'Build package', body: 'Prefer pnpm for builds.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current', excerpt: 'Prefer pnpm for all builds.' }] })
-  propose(h.env, self, { kind: 'fact', title: 'Build tool', body: 'Use pnpm for builds.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current', excerpt: 'Prefer pnpm for all builds.' }] })
-  const ids = h.maintenance.jobs().filter(job => job.input.kind === 'proposal').map(job => job.id)
-  const batchCurator = { ...curator, maintenanceJobIds: ids }
-  expect(h.maintenance.readBatch(batchCurator).jobs).toHaveLength(2)
-
-  const applied = h.maintenance.applyBatch(batchCurator, ids.map(id => ({ id, decision: 'apply' as const, reason: 'Merge duplicate statements into one evidence-backed fact.' })), {
-    pages: [],
-    memories: [{ title: 'Build tool', kind: 'preference', body: 'Prefer pnpm for builds.', namespace: '/', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'origin', excerpt: 'Prefer pnpm for all builds.' }], links: [] }],
-    blocks: [],
-    flags: []
-  })
-
-  expect(applied.operationId).toMatch(/^batch-/)
-  expect(applied.jobs.map(job => job.status)).toEqual(['completed', 'completed'])
-  expect(applied.jobs.filter(job => job.receipt?.operationId === applied.operationId)).toHaveLength(1)
-  expect(findMemory(wikiDir(h.env.root), 'build-tool').body.trim()).toBe('Prefer pnpm for builds.')
-  expect(listInbox(wikiDir(h.env.root)).filter(item => item.operationId === applied.operationId)).toHaveLength(1)
-})
-
-test('a batch parks updates whose captured Wiki target changed before review', async () => {
-  const h = setup(); await origin(h)
-  const wiki = wikiDir(h.env.root)
-  saveAsUser(wiki, { id: 'build-tool', title: 'Build tool', kind: 'preference', namespace: '/', body: 'Use pnpm for builds.' })
-  propose(h.env, self, { kind: 'fact', id: 'build-tool', title: 'Build tool', body: 'Prefer pnpm for all builds.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current', excerpt: 'Prefer pnpm for all builds.' }] })
-  const id = h.maintenance.jobs().find(job => job.input.kind === 'proposal')!.id
-  saveAsUser(wiki, { id: 'build-tool', title: 'Build tool', kind: 'preference', namespace: '/', body: 'The user changed this preference.' })
-
-  const result = h.maintenance.applyBatch({ ...curator, maintenanceJobIds: [id] }, [{ id, decision: 'apply', reason: 'Review the proposed update against its evidence.' }], {
-    pages: [],
-    memories: [{ id: 'build-tool', title: 'Build tool', kind: 'preference', body: 'Prefer pnpm for all builds.', namespace: '/', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'origin', excerpt: 'Prefer pnpm for all builds.' }], links: [] }],
-    blocks: [],
-    flags: []
-  })
-
-  expect(result.jobs[0].status).toBe('needs_user')
-  expect(result.operationId).toBeNull()
-  expect(findMemory(wiki, 'build-tool').body.trim()).toBe('The user changed this preference.')
-})
-
-test('invented evidence is parked and a read-only memory block is not rewritten', async () => {
-  const h = setup(); await origin(h)
-  propose(h.env, self, { kind: 'fact', title: 'Invented', body: 'Use another tool.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current', excerpt: 'This was never said anywhere.' }] })
-  const job = h.maintenance.jobs().find(job => job.input.kind === 'proposal')!
-  expect(h.maintenance.applyJob(curator, job.id, undefined, 'Review the claimed evidence').status).toBe('needs_user')
-  expect(() => findMemory(wikiDir(h.env.root), 'invented')).toThrow()
-  const block = blocks.find(wikiDir(h.env.root), 'blocks/agents/nora/notes')
-  blocks.saveAsUser(wikiDir(h.env.root), { id: block.id, body: '', description: block.front.description, limit: 2000, readOnly: true })
-  expect(() => propose(h.env, self, { kind: 'block', id: block.id, title: 'Notes', body: 'Changed.' })).toThrow('user-only')
-})
-
-test('text resources remain inactive until curated; undo restores attachments and preserves subsequent user edits', async () => {
-  const h = setup()
-  const tool = (await registryTools({ harness: h })({ caller: self } as ToolSession)).find(tool => tool.name === 'registry_write')!
-  await tool.execute({ kind: 'skill', name: 'release-notes', description: 'Write release notes', body: 'Summarize verified changes.', reason: 'Repeated release work.' })
-  const job = h.maintenance.jobs().find(job => job.input.kind === 'registry')!
-  expect(registry.list(h.env.root).some(item => item.id === 'skills/release-notes')).toBe(false)
-  const receipt = h.maintenance.applyJob(curator, job.id, undefined, 'Reuse the repeated release procedure.')
-  expect(attachments.attached(attachments.load(h.env.root), ['skills/release-notes'], { agentId: 'nora' }, false)).toBe(true)
-  h.maintenance.undoOperation(receipt.receipt!.operationId!)
-  expect(registry.list(h.env.root).some(item => item.id === 'skills/release-notes')).toBe(false)
-  const next = enqueueCuration(h.env.root, { kind: 'registry', caller: self, proposal: { kind: 'skill', name: 'other-notes', description: 'Notes', body: 'Write verified notes.', reason: 'Workflow improvement.' } })
-  const applied = h.maintenance.applyJob(curator, next.id, undefined, 'Apply text-only improvement.')
-  registry.writeItem(h.env.root, 'skill', 'other-notes', 'Notes', 'The user changed this.', 'User edit')
-  expect(() => h.maintenance.undoOperation(applied.receipt!.operationId!)).toThrow('changed after')
-})
-
-test('changed target versions are escalated instead of overwritten', () => {
-  const h = setup()
-  registry.writeItem(h.env.root, 'skill', 'notes', 'Notes', 'Original notes.', 'Initial')
-  const job = enqueueCuration(h.env.root, { kind: 'registry', caller: self, proposal: { kind: 'skill', name: 'notes', description: 'Notes', body: 'Proposed notes.', reason: 'Improve' } })
-  registry.writeItem(h.env.root, 'skill', 'notes', 'Notes', 'User edits win.', 'User edit')
-  expect(h.maintenance.applyJob(curator, job.id, undefined, 'Review update').status).toBe('needs_user')
-  expect(registry.list(h.env.root).find(item => item.id === 'skills/notes')).toBeDefined()
-})
-
-test('executable plugins are submitted without saving, activation or trust', async () => {
-  const h = setup()
-  const tool = (await registryTools({ harness: h })({ caller: self } as ToolSession)).find(tool => tool.name === 'plugin_write')!
-  await tool.execute({ name: 'code-change', description: 'A code plugin', files: [{ path: 'extensions/index.ts', content: 'export default () => {}' }] })
-  const job = h.maintenance.jobs().find(job => job.input.kind === 'plugin')!
-  expect(h.maintenance.applyJob(curator, job.id, undefined, 'Code needs trust').status).toBe('needs_user')
-  expect(existsSync(join(h.env.root, 'plugins/code-change'))).toBe(false)
-})
-
-test('external jobs persist and repeated schedule occurrences are distinct; no hidden provider runs', async () => {
-  const h = setup()
-  const source = h.maintenance.ingest('source.txt', Buffer.from('Prefer pnpm for all builds.'))
-  expect(h.maintenance.jobs().some(job => job.input.kind === 'ingest' && job.input.sourceId === source.id)).toBe(true)
-  h.maintenance.enqueue({ kind: 'review', requestId: 'day-one' })
-  h.maintenance.enqueue({ kind: 'review', requestId: 'day-one' })
-  h.maintenance.enqueue({ kind: 'review', requestId: 'day-two' })
-  expect(h.maintenance.jobs().filter(job => job.input.kind === 'review')).toHaveLength(2)
-  await h.maintenance.settled()
-})
-
-test('a curator run never enqueues another completed-run maintenance job', async () => {
-  const h = setup()
-  await h.sessions.run({ run: { id: 'curator-run', sessionId: 'curator' }, cwd: h.env.root, sessionDir: join(h.env.root, 'curator-history'), text: 'Review maintenance.', caller: curator, tools: { allow: [] } })
-  await new Promise(resolve => setTimeout(resolve, 30))
-  expect(h.maintenance.jobs().some(job => job.input.kind === 'run' && job.input.runId === 'curator-run')).toBe(false)
-})
-
-test('curator prose cannot become its own evidence; original source runs can support a review', async () => {
-  const h = setup(); await origin(h)
-  await h.sessions.run({ run: { id: 'review', sessionId: 'curator' }, cwd: h.env.root, sessionDir: join(h.env.root, 'curator-history'), text: 'Prefer pnpm for all builds.', caller: curator, tools: { allow: [] } })
-  await new Promise(resolve => setTimeout(resolve, 30))
-  propose(h.env, curator, { kind: 'fact', title: 'Curator claim', body: 'A claim from the review.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'current', excerpt: 'Prefer pnpm for all builds.' }] })
-  const own = h.maintenance.jobs().find(job => job.input.kind === 'proposal')!
-  expect(h.maintenance.applyJob(curator, own.id, undefined, 'Check the original evidence.').status).toBe('needs_user')
-  expect(() => findMemory(wikiDir(h.env.root), 'curator-claim')).toThrow()
-  const review = enqueueCuration(h.env.root, { kind: 'review', requestId: 'grounded-review' })
-  const applied = h.maintenance.applyJob(curator, review.id, { memories: [{ title: 'Original preference', kind: 'preference', body: 'Prefer pnpm.', confidence: 'high', sourceRefs: [{ kind: 'run', ref: 'origin', excerpt: 'Prefer pnpm for all builds.' }] }] }, 'Retain the original recorded preference.')
-  expect(applied.status).toBe('completed')
-  expect(findMemory(wikiDir(h.env.root), 'original-preference').front.sourceIds).toContain('run:origin')
-})
-
-
-test('a failed evidence preparation remains attributed and can be rejected without rereading invalid input', () => {
-  const h = setup()
-  const job = enqueueCuration(h.env.root, { kind: 'consolidate', blockIds: ['missing-block'] })
-  expect(() => h.maintenance.readJob(curator, job.id)).toThrow('No writable blocks')
-  expect(h.maintenance.jobs().find(item => item.id === job.id)).toMatchObject({ status: 'failed', runId: 'review' })
-  expect(h.maintenance.decide(curator, job.id, 'reject', 'The target no longer exists.').status).toBe('rejected')
-})
-
-test('a propose-only caller writes no memory directly, not even its own persona and notes', () => {
-  const h = setup()
-  const proposer = { ...self, vaultAccess: 'propose' as const }
-  expect(() => memoryEdit(h.env, proposer, 'memory.append', { block: 'notes', text: 'Working on release notes.' })).toThrow('Memory changes are proposals')
-  expect(() => memoryEdit(h.env, proposer, 'memory.append', { block: 'persona', text: 'I am terse.' })).toThrow('Memory changes are proposals')
-  expect(propose(h.env, proposer, { kind: 'block', id: 'blocks/agents/nora/notes', title: 'Notes', body: 'Working on release notes.' })).toContain('Submitted proposal')
-})
-
-test('with the run trigger off, a settled run queues no consolidation of its own', async () => {
-  let emit: (event: unknown) => void = () => undefined
-  const session: PiSessionLike = { sessionId: 'quiet', subscribe: listener => { emit = listener as never; return () => undefined }, prompt: async () => { emit({ type: 'message_end', message: { role: 'assistant', content: [{ type: 'text', text: 'Prefer pnpm for all builds.' }] } }) }, sendCustomMessage: async () => undefined, abort: async () => undefined, dispose: () => undefined }
-  const h = createHarness({ dataRoot: mkdtempSync(join(tmpdir(), 'curation-data-')), stateDir: mkdtempSync(join(tmpdir(), 'curation-state-')), externalMaintenance: true, maintenanceRunTrigger: false, secrets: memorySecretStore(), sessionFactory: async () => session })
-  opened.push(h)
-  h.accounts.create('Main', 'apiKey')
-  await h.sessions.run({ run: { id: 'quiet-run', sessionId: 'nora' }, cwd: h.env.root, sessionDir: join(h.env.root, 'history'), text: 'Prefer pnpm.', caller: self, tools: { allow: [] } })
-  await new Promise(resolve => setTimeout(resolve, 30))
-  expect(h.maintenance.jobs().filter(job => job.input.kind === 'run')).toEqual([])
-})

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,64 +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 * as trajectory from './trajectory'
-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 'trajectory.search':
-      return trajectory.searchTool(env, context, params)
-    case 'trajectory.read':
-      return trajectory.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))
-}