Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

21.0 KB
Raw Blame
import { mkdtempSync, rmSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, beforeEach, expect, it } from 'vitest'
import { CodingMemoryStore } from './store.js'
import type { MemoryDraft, MemoryRecord, MemoryScope, SourceEvent } from './types.js'
import type { MemoryCorrection } from './library.js'

let directory: string, store: CodingMemoryStore
beforeEach(() => {
  directory = mkdtempSync(join(tmpdir(), 'memory-library-'))
  const opened = CodingMemoryStore.open({ directory, profileId: 'owner', now: () => 1000 })
  if (!opened.ok) throw new Error(opened.reason)
  store = opened.store
  store.setControls({ learn: true, recall: true })
})
afterEach(() => { store.close(); rmSync(directory, { recursive: true, force: true }) })

function learn(id: string, scope: MemoryScope = { profileId: 'owner', projectId: 'project' }): MemoryRecord {
  if (scope.projectId) store.registerProject(scope.projectId)
  const claim = `For coding task ${id}, I prefer a small reproducer.`
  const source: SourceEvent = { id, profileId: 'owner', projectId: scope.projectId ?? null, taskId: scope.taskId, branchId: scope.branchId,
    role: 'user', engine: 'claude', sessionId: id, nativeEventId: id, rootIds: [id], eligibility: 'coding', observedAt: 900,
    text: `${claim}\nUnrelated private conversation must never appear in the library detail.` }
  store.ingest(source)
  const draft: MemoryDraft = { kind: 'working_preference', facet: 'debugging', assertionType: 'stated_preference', scope, claim,
    rationale: null, futureAction: 'Begin with a reproducer.', applicability: {}, exceptions: [], retrievalCues: ['reproducer'],
    conflictKey: id, evidenceClass: 'user_stated', evidence: [{ sourceEventId: id, quote: claim, paths: ['/claim', '/futureAction', '/applicability'] }],
    validity: { validFrom: null, validUntil: null, recheckWhen: [] } }
  return store.propose(draft, { profileId: 'owner', projectIds: scope.projectId ? [scope.projectId] : [], includeProfile: true,
    taskId: scope.taskId, branchId: scope.branchId }).record
}
function fields(record: MemoryRecord): MemoryCorrection {
  const { claim, rationale, futureAction, applicability, exceptions, retrievalCues, validity } = record
  return { claim, rationale, futureAction, applicability, exceptions, retrievalCues, validity }
}

it('paginates all owner scopes without granting that access to ordinary agents', () => {
  const personal = learn('personal', { profileId: 'owner' })
  const task = learn('task', { profileId: 'owner', projectId: 'project', taskId: 'task' })
  const branch = learn('branch', { profileId: 'owner', projectId: 'second', branchId: 'branch' })
  const page = store.libraryPage('owner', { limit: 2 })
  expect(page.items.map(item => item.id)).toEqual([branch.id, task.id])
  expect(page.items[0]).not.toHaveProperty('evidence')
  expect(store.libraryPage('owner', { limit: 2, cursor: page.nextCursor! }).items.map(item => item.id)).toEqual([personal.id])
  expect(store.libraryPage('owner', { scope: 'personal' }).items.map(item => item.id)).toEqual([personal.id])
  expect(store.libraryPage('owner', { projectId: 'project' }).items.map(item => item.id)).toEqual([task.id])
  expect(store.list({ profileId: 'owner', projectIds: ['project'], includeProfile: false })).toEqual([])
  expect(() => store.libraryPage('other')).toThrow('scope_denied')
  expect(() => store.libraryDetail('other', task.id)).toThrow('scope_denied')
})

it('applies privacy before page limits and returns only retained evidence spans', () => {
  const record = learn('visible')
  learn('hidden')
  store.setSessionIncluded('claude', 'hidden', false)
  expect(store.libraryPage('owner', { limit: 1 }).items.map(item => item.id)).toEqual([record.id])
  const detail = store.libraryDetail('owner', record.id)!
  expect(detail.sources).toEqual([{ id: 'visible', engine: 'claude', sessionId: 'visible', role: 'user', observedAt: 900 }])
  expect(JSON.stringify(detail)).not.toContain('Unrelated private')
  store.setProjectIncluded('project', false)
  expect(store.libraryPage('owner').items).toEqual([])
  expect(store.libraryDetail('owner', record.id)).toBeNull()
  // Privacy must not prevent the owner from deleting a known record.
  const preview = store.libraryPreview('owner', { kind: 'forget', id: record.id, revision: 1 })
  expect(store.libraryApply('owner', preview.command, preview.version, false).deletedIds).toContain(record.id)
})

it('rejects stale, malformed, foreign-owner and differently filtered cursors', () => {
  const first = learn('first'); learn('second')
  const page = store.libraryPage('owner', { limit: 1 })
  expect(() => store.libraryPage('owner', { cursor: 'garbage' })).toThrow('invalid_cursor')
  expect(() => store.libraryPage('owner', { cursor: page.nextCursor!, scope: 'personal' })).toThrow('invalid_cursor')
  const cursor = JSON.parse(Buffer.from(page.nextCursor!, 'base64url').toString())
  expect(() => store.libraryPage('owner', { cursor: Buffer.from(JSON.stringify({ ...cursor, owner: 'other' })).toString('base64url') })).toThrow('invalid_cursor')
  store.libraryCorrect('owner', first.id, 1, { ...fields(first), claim: 'I prefer a minimal failing test.' })
  expect(() => store.libraryPage('owner', { cursor: page.nextCursor! })).toThrow('page_changed')
})

it('validates a concrete correction without saving a revision or invented user event', () => {
  const record = learn('one', { profileId: 'owner', projectId: 'project', taskId: 'task', branchId: 'branch' })
  const version = store.libraryPage('owner').version
  const command = { kind: 'correct' as const, id: record.id, revision: 1, fields: { ...fields(record), claim: 'I prefer a focused regression test.' } }
  const preview = store.libraryPreview('owner', command)
  expect(preview.effects.record).toMatchObject({ claim: command.fields.claim, revision: 2, scope: record.scope })
  expect(store.libraryDetail('owner', record.id)!.record).toEqual(record)
  expect(store.libraryPage('owner').version).toEqual(version)
  store.setControls({ learn: false, recall: false })
  const current = store.libraryPreview('owner', command)
  expect(store.libraryApply('owner', command, current.version, false).record).toMatchObject({ revision: 2, evidenceClass: 'user_stated' })
  const detail = store.libraryDetail('owner', record.id)!
  expect(detail.sources).toMatchObject([{ engine: 'harness_viewer', role: 'user' }])
  expect(() => store.libraryApply('owner', command, current.version, false)).toThrow('preview_changed')
  expect(() => store.libraryCorrect('owner', record.id, 1, command.fields)).toThrow('revision_conflict')
})

it('refuses payload authority changes and secret-bearing corrections without changing the record', () => {
  const record = learn('one')
  expect(() => store.libraryCorrect('owner', record.id, 1, { ...fields(record), scope: { profileId: 'owner' } } as MemoryCorrection)).toThrow('invalid_input')
  expect(() => store.libraryPreview('owner', { kind: 'correct', id: record.id, revision: 1,
    fields: { ...fields(record), claim: 'Save this API key sk-ant-api03-abcdefghijklmnopqrstuvwxyz0123456789' } })).toThrow()
  expect(store.libraryDetail('owner', record.id)!.record).toEqual(record)
})

it('narrows a personal memory to one known project without changing its meaning or adding confirmation', () => {
  const record = learn('personal', { profileId: 'owner' })
  const { schemaVersion: _schema, id: _id, revision: _revision, state: _state, createdAt: _created, updatedAt: _updated, ...draft } = record
  store.ingest({ id: 'corroboration', profileId: 'owner', projectId: null, role: 'user', engine: 'codex', sessionId: 'another_session',
    nativeEventId: 'corroboration', rootIds: ['corroboration'], eligibility: 'coding', observedAt: 950, text: record.claim })
  store.propose({ ...draft, evidence: [{ ...draft.evidence[0], sourceEventId: 'corroboration' }] },
    { profileId: 'owner', projectIds: [], includeProfile: true })
  store.registerProject('chosen_project')
  store.registerProject('other_project')
  const originalSupport = store.libraryDetail('owner', record.id)!.support
  expect(originalSupport?.independentUserStatements).toBe(2)
  const command = { kind: 'narrow' as const, id: record.id, revision: 1, projectId: 'chosen_project' }
  const preview = store.libraryPreview('owner', command)
  expect(preview.effects.record).toMatchObject({ id: record.id, revision: 2, scope: { profileId: 'owner', projectId: 'chosen_project' } })
  expect(store.libraryDetail('owner', record.id)!.record).toEqual(record)
  store.libraryApply('owner', command, preview.version, true)
  const detail = store.libraryDetail('owner', record.id)!
  expect(detail.record).toMatchObject({ claim: record.claim, rationale: record.rationale, evidence: record.evidence,
    evidenceClass: record.evidenceClass, applicability: record.applicability, revision: 2 })
  expect(detail.support).toEqual(originalSupport)
  expect(detail.scopeChanges).toEqual([{ revision: 2, from: { profileId: 'owner' },
    to: { profileId: 'owner', projectId: 'chosen_project' }, changedAt: 1000, actor: 'owner' }])
  expect(store.recall({ query: 'reproducer' }, { profileId: 'owner', projectIds: ['chosen_project'], includeProfile: true }).items).toHaveLength(1)
  expect(store.recall({ query: 'reproducer' }, { profileId: 'owner', projectIds: ['other_project'], includeProfile: true }).items).toEqual([])
  expect(() => store.libraryApply('owner', command, preview.version, true)).toThrow('preview_changed')
})

it('refuses unknown or excluded destinations and moving a memory from one project to another', () => {
  const personal = learn('personal', { profileId: 'owner' }), scoped = learn('scoped')
  store.registerProject('excluded'); store.setProjectIncluded('excluded', false)
  for (const projectId of ['missing', 'excluded']) expect(() => store.libraryPreview('owner',
    { kind: 'narrow', id: personal.id, revision: 1, projectId })).toThrow('project_unavailable')
  expect(() => store.libraryPreview('owner', { kind: 'narrow', id: scoped.id, revision: 1, projectId: 'project' }))
    .toThrow('scope_narrowing_only')
  expect(store.libraryDetail('owner', personal.id)!.record).toEqual(personal)
  expect(() => store.libraryPreview('other', { kind: 'narrow', id: personal.id, revision: 1, projectId: 'project' })).toThrow('scope_denied')
})

it('keeps inferred knowledge tentative when its applicability is narrowed', () => {
  const original = learn('statement', { profileId: 'owner' })
  const { schemaVersion: _schema, id: _id, revision: _revision, state: _state, createdAt: _created, updatedAt: _updated, ...draft } = original
  const record = store.propose({ ...draft, assertionType: 'observed_usage', evidenceClass: 'inferred', conflictKey: 'inferred' },
    { profileId: 'owner', projectIds: [], includeProfile: true }).record
  store.registerProject('project')
  const preview = store.libraryPreview('owner', { kind: 'narrow', id: record.id, revision: 1, projectId: 'project' })
  store.libraryApply('owner', preview.command, preview.version, true)
  const detail = store.libraryDetail('owner', record.id)!
  expect(detail.record).toMatchObject({ state: 'tentative', evidenceClass: 'inferred', evidence: record.evidence })
  expect(detail.support?.independentUserStatements).toBe(0)
})

it('preserves an unresolved conflict while allowing an owner to narrow with learning and recall off', () => {
  const original = learn('original', { profileId: 'owner' }), opposing = learn('opposing', { profileId: 'owner' })
  const { schemaVersion: _schema, id: _id, revision: _revision, state: _state, createdAt: _created, updatedAt: _updated, ...draft } = opposing
  store.propose({ ...draft, conflictKey: original.conflictKey }, { profileId: 'owner', projectIds: [], includeProfile: true })
  const conflicted = store.libraryDetail('owner', original.id)!.record
  expect(conflicted.state).toBe('needs_verification')
  store.registerProject('project')
  store.setControls({ learn: false, recall: false })
  const preview = store.libraryPreview('owner', { kind: 'narrow', id: original.id, revision: conflicted.revision, projectId: 'project' })
  store.libraryApply('owner', preview.command, preview.version, false)
  expect(store.libraryDetail('owner', original.id)!.record).toMatchObject({ state: 'needs_verification', evidence: original.evidence })
  expect(store.controls()).toMatchObject({ learn: false, recall: false })
})

it('previews conflicting project knowledge and atomically withholds both claims after narrowing', () => {
  const personal = learn('personal', { profileId: 'owner' }), existing = learn('project')
  const { schemaVersion: _schema, id: _id, revision: _revision, state: _state, createdAt: _created, updatedAt: _updated, ...draft } = existing
  const opposing = store.propose({ ...draft, conflictKey: personal.conflictKey },
    { profileId: 'owner', projectIds: ['project'], includeProfile: true }).record
  const preview = store.libraryPreview('owner', { kind: 'narrow', id: personal.id, revision: 1, projectId: 'project' })
  expect(preview.effects.record?.state).toBe('needs_verification')
  expect(preview.effects.conflicts).toMatchObject([{ id: opposing.id, revision: 2, claim: opposing.claim, state: 'needs_verification' }])
  expect(store.libraryDetail('owner', opposing.id)!.record.state).toBe('active')
  expect(store.libraryDetail('owner', personal.id)!.record.scope.projectId).toBeUndefined()
  store.libraryApply('owner', preview.command, preview.version, true)
  expect(store.libraryDetail('owner', opposing.id)!.record.state).toBe('needs_verification')
  expect(store.libraryDetail('owner', personal.id)!.record.state).toBe('needs_verification')
})

it('persists scope audit across restart and removes it with the forgotten memory', () => {
  const record = learn('personal', { profileId: 'owner' })
  const projectId = store.projectForLocator({ kind: 'directory', path: '/synthetic/project-label-only' })
  const access = { profileId: 'owner', projectIds: [projectId], includeProfile: true }
  store.putTopic({ id: 'topic', scope: record.scope, title: 'Debugging', statements: [{ text: record.claim,
    supports: [{ memoryId: record.id, revision: 1, paths: ['/claim'] }] }] }, access)
  const preview = store.libraryPreview('owner', { kind: 'narrow', id: record.id, revision: 1, projectId })
  store.libraryApply('owner', preview.command, preview.version, true)
  expect(store.topic('topic', access)).toBeNull()
  expect(JSON.stringify({ list: store.list(access), recall: store.recall({ query: 'reproducer' }, access) }))
    .not.toContain('project-label-only')
  store.close()
  const reopened = CodingMemoryStore.open({ directory, profileId: 'owner', now: () => 1000 })
  if (!reopened.ok) throw new Error(reopened.reason)
  store = reopened.store
  expect(store.libraryDetail('owner', record.id)!.scopeChanges).toHaveLength(1)
  expect(store.libraryDetail('owner', record.id)!.project?.location).toBe('/synthetic/project-label-only')
  store.libraryForget('owner', record.id, 2)
  expect(store.libraryDetail('owner', record.id)).toBeNull()
  expect(store.libraryPage('owner').items).toEqual([])
})

it('withdraws the broader revision from other conversations and invalidates a stale target preview', () => {
  const record = learn('personal', { profileId: 'owner' })
  store.registerProject('project'); store.registerProject('other_project')
  const access = { profileId: 'owner', projectIds: ['other_project'], includeProfile: true }
  const binding = { engine: 'claude' as const, sessionId: 'receiving', projectId: 'other_project', route: 'prompt_hook' as const }
  store.prepareRecall({ query: 'reproducer' }, binding, access)
  const command = { kind: 'narrow' as const, id: record.id, revision: 1, projectId: 'project' }
  const preview = store.libraryPreview('owner', command)
  store.setProjectIncluded('project', false)
  expect(() => store.libraryApply('owner', command, preview.version, true)).toThrow('preview_changed')
  store.setProjectIncluded('project', true)
  const current = store.libraryPreview('owner', command)
  store.libraryApply('owner', command, current.version, true)
  const next = store.prepareRecall({ query: 'reproducer' }, binding, access)
  expect(next.packet.items).toEqual([])
  expect(JSON.parse(next.packet.text).withdrawn.references).toEqual([{ id: record.id, revision: 1 }])
  store.libraryForget('owner', record.id, 2)
  expect(store.libraryDetail('owner', record.id)).toBeNull()
})

it('lists known project names and literal path matches with privacy applied before pagination', () => {
  const first = store.projectForLocator({ kind: 'git_common_directory', path: '/synthetic/work/editor/.git' })
  const second = store.projectForLocator({ kind: 'directory', path: '/synthetic/research/editor' })
  const hidden = store.projectForLocator({ kind: 'directory', path: '/synthetic/private-hidden' })
  store.setProjectIncluded(hidden, false)
  const page = store.libraryProjects('owner', { search: 'editor', limit: 1 })
  expect(page.items).toEqual([{ id: second, name: 'editor', location: '/synthetic/research/editor' }])
  expect(store.libraryProjects('owner', { search: 'editor', before: page.nextBefore!, limit: 1 }).items)
    .toEqual([{ id: first, name: 'editor', location: '/synthetic/work/editor' }])
  expect(store.libraryProjects('owner', { search: 'research/editor' }).items.map(project => project.id)).toEqual([second])
  expect(store.libraryProjects('owner', { search: '%' }).items).toEqual([])
  expect(store.libraryProjects('owner').items.map(project => project.id)).not.toContain(hidden)
  expect(() => store.libraryProjects('other')).toThrow('scope_denied')
  expect(() => store.libraryProjects('owner', { limit: 1000 })).toThrow('invalid_input')
})

it('previews forgetting without erasing evidence and refuses a changed dependency snapshot', () => {
  const record = learn('one')
  const preview = store.libraryPreview('owner', { kind: 'forget', id: record.id, revision: 1 })
  expect(preview.effects).toEqual({ deletedIds: [record.id], deletedTopicIds: [], alreadyDeliveredContent: 'not_erased' })
  expect(store.libraryDetail('owner', record.id)!.record).toEqual(record)
  learn('new_knowledge')
  expect(() => store.libraryApply('owner', preview.command, preview.version, true)).toThrow('preview_changed')
  const current = store.libraryPreview('owner', preview.command)
  store.libraryApply('owner', current.command, current.version, true)
  expect(store.libraryDetail('owner', record.id)).toBeNull()
})

it('invalidates a forget preview when a new notebook page depends on the record', () => {
  const record = learn('one')
  const preview = store.libraryPreview('owner', { kind: 'forget', id: record.id, revision: 1 })
  store.putTopic({ id: 'new_topic', scope: record.scope, title: 'Debugging', statements: [{ text: record.claim,
    supports: [{ memoryId: record.id, revision: 1, paths: ['/claim'] }] }] }, { profileId: 'owner', projectIds: ['project'], includeProfile: true })
  expect(() => store.libraryApply('owner', preview.command, preview.version, true)).toThrow('preview_changed')
  expect(store.libraryPreview('owner', preview.command).effects.deletedTopicIds).toEqual(['new_topic'])
})

it('invalidates a forget preview when new corroborating evidence connects existing memories', () => {
  const one = learn('one'), two = learn('two')
  const preview = store.libraryPreview('owner', { kind: 'forget', id: one.id, revision: 1 })
  const text = `${one.claim} ${two.claim}`
  store.ingest({ id: 'bridge', profileId: 'owner', projectId: 'project', role: 'user', engine: 'codex', sessionId: 'bridge',
    nativeEventId: 'bridge', rootIds: ['bridge'], eligibility: 'coding', observedAt: 950, text })
  for (const record of [one, two]) {
    const { schemaVersion: _schema, id: _id, revision: _revision, state: _state, createdAt: _created, updatedAt: _updated, ...draft } = record
    const input = { ...draft, evidence: [{ sourceEventId: 'bridge', quote: text, paths: ['/claim', '/futureAction', '/applicability'] }] }
    const access = { profileId: 'owner', projectIds: ['project'], includeProfile: true }
    expect(store.propose(input, access).disposition).toBe('duplicate')
    const version = store.libraryPage('owner').version
    store.propose(input, access) // Replaying the same root changes neither evidence nor the snapshot.
    expect(store.libraryPage('owner').version).toEqual(version)
  }
  expect(store.libraryDetail('owner', one.id)!.record.revision).toBe(1)
  expect(() => store.libraryApply('owner', preview.command, preview.version, true)).toThrow('preview_changed')
  expect(store.libraryPreview('owner', preview.command).effects.deletedIds).toEqual(expect.arrayContaining([one.id, two.id]))
})

it('keeps effective controls off when changing preferences without watching consent', () => {
  store.setControls({ learn: false, recall: false })
  const preview = store.libraryPreview('owner', { kind: 'configure', preferences: { learn: false, recall: true }, expected: { learn: true, recall: true } })
  expect(store.preferences()).toEqual({ learn: true, recall: true })
  expect(store.controls()).toMatchObject({ learn: false, recall: false })
  store.libraryApply('owner', preview.command, preview.version, false)
  expect(store.preferences()).toEqual({ learn: false, recall: true })
  expect(store.controls()).toMatchObject({ learn: false, recall: false })
  expect(() => store.changePreferences({ learn: true, recall: true }, { learn: true, recall: true })).toThrow('revision_conflict')
})