@aperdomoll90/ledger-ai 1.4.0 → 1.4.2

package/dist/commands/restore.js

@@ -1,71 +1,71 @@
 import { readFileSync, existsSync } from 'fs';
 import { resolve } from 'path';
 import { confirm } from '../lib/prompt.js';
+import { createDocument } from '../lib/documents/operations.js';
 export async function restore(config, filePath) {
     const absPath = resolve(filePath);
     if (!existsSync(absPath)) {
         console.error(`File not found: ${absPath}`);
         process.exit(1);
     }
-    let notes;
+    let documents;
     try {
-        notes = JSON.parse(readFileSync(absPath, 'utf-8'));
+        documents = JSON.parse(readFileSync(absPath, 'utf-8'));
     }
     catch {
         console.error('Invalid JSON file.');
         process.exit(1);
     }
-    console.error(`Found ${notes.length} notes in backup.`);
+    console.error(`Found ${documents.length} documents in backup.`);
     // Check current database
     const { count } = await config.supabase
-        .from('notes')
+        .from('documents')
         .select('*', { count: 'exact', head: true });
     if (count && count > 0) {
-        console.error(`Database already has ${count} notes.`);
-        const proceed = await confirm('Restore will add notes (not replace). Continue?');
+        console.error(`Database already has ${count} documents.`);
+        const proceed = await confirm('Restore will add documents (not replace). Continue?');
         if (!proceed) {
             console.error('Cancelled.');
             return;
         }
     }
     console.error('Restoring...\n');
+    const clients = {
+        supabase: config.supabase,
+        openai: config.openai,
+    };
     let restored = 0;
     let skipped = 0;
-    for (const note of notes) {
-        // Check for existing note with same upsert_key
-        const upsertKey = note.metadata.upsert_key;
-        if (upsertKey) {
-            const { data: existing } = await config.supabase
-                .from('notes')
-                .select('id')
-                .eq('metadata->>upsert_key', upsertKey)
-                .limit(1)
-                .single();
-            if (existing) {
-                console.error(`  skip "${upsertKey}" (already exists)`);
-                skipped++;
-                continue;
-            }
+    for (const document of documents) {
+        // Check for existing document with same name (UNIQUE in v2)
+        const { data: existing } = await config.supabase
+            .from('documents')
+            .select('id')
+            .eq('name', document.name)
+            .limit(1)
+            .single();
+        if (existing) {
+            console.error(`  skip "${document.name}" (already exists)`);
+            skipped++;
+            continue;
+        }
+        try {
+            await createDocument(clients, {
+                name: document.name,
+                domain: document.domain,
+                document_type: document.document_type,
+                project: document.project ?? undefined,
+                protection: document.protection,
+                content: document.content,
+                description: document.description ?? undefined,
+                status: document.status ?? undefined,
+            });
         }
-        // Generate embedding
-        const embeddingResponse = await config.openai.embeddings.create({
-            model: 'text-embedding-3-small',
-            input: note.content,
-        });
-        const embedding = embeddingResponse.data[0].embedding;
-        const { error } = await config.supabase
-            .from('notes')
-            .insert({
-            content: note.content,
-            metadata: note.metadata,
-            embedding,
-        });
-        if (error) {
-            console.error(`  error restoring note ${note.id}: ${error.message}`);
+        catch (error) {
+            console.error(`  error restoring "${document.name}": ${error.message}`);
             continue;
         }
-        const label = upsertKey || `note-${note.id}`;
-        console.error(`  restored "${label}"`);
+        console.error(`  restored "${document.name}"`);
         restored++;
     }
     console.error(`\nRestore complete: ${restored} restored, ${skipped} skipped (already exist)`);

package/dist/commands/show.js

@@ -1,29 +1,26 @@
 import { writeFileSync, mkdirSync } from 'fs';
 import { resolve } from 'path';
 import { execFileSync } from 'child_process';
-import { searchNotes } from '../lib/notes.js';
+import { searchHybrid } from '../lib/search/ai-search.js';
 import { fatal, ExitCode } from '../lib/errors.js';
 const VIEW_DIR = '/tmp/ledger-view';
 export async function show(config, query, options = {}) {
-    // Fetch more if filtering
-    const fetchLimit = (options.type || options.project) ? 10 : 1;
-    let results = await searchNotes(config.supabase, config.openai, query, 0.3, fetchLimit);
-    if (options.type) {
-        results = results.filter(n => n.metadata.type === options.type);
-    }
-    if (options.project) {
-        results = results.filter(n => n.metadata.project === options.project);
-    }
+    const results = await searchHybrid({ supabase: config.supabase, openai: config.openai }, {
+        query,
+        limit: (options.type || options.project) ? 10 : 1,
+        document_type: options.type,
+        project: options.project,
+    });
     if (results.length === 0) {
-        fatal('No matching notes found.', ExitCode.NOTE_NOT_FOUND);
+        fatal('No matching documents found.', ExitCode.DOCUMENT_NOT_FOUND);
     }
-    const note = results[0];
-    const upsertKey = note.metadata.upsert_key || `note-${note.id}`;
-    const filename = `${upsertKey}.md`;
+    const document = results[0];
+    const filename = `${document.name}.md`;
     mkdirSync(VIEW_DIR, { recursive: true });
     const filePath = resolve(VIEW_DIR, filename);
-    writeFileSync(filePath, note.content + '\n', 'utf-8');
-    console.log(`Match: "${upsertKey}" (similarity: ${note.similarity.toFixed(3)})`);
+    writeFileSync(filePath, document.content + '\n', 'utf-8');
+    const score = document.score?.toFixed(3) ?? document.similarity?.toFixed(3) ?? 'n/a';
+    console.log(`Match: "${document.name}" (score: ${score})`);
     console.log(filePath);
     try {
         execFileSync('code', [filePath], { stdio: 'ignore' });

package/dist/commands/sync.js

@@ -1,13 +1,14 @@
 import { writeFileSync, readFileSync, mkdirSync, existsSync, unlinkSync, readdirSync } from 'fs';
 import { resolve } from 'path';
 import { loadConfigFile, saveConfigFile } from '../lib/config.js';
-import { fetchPersonaNotes, updateNoteContent, updateNoteHash, opAddNote } from '../lib/notes.js';
+import { fetchSyncableNotes, updateNoteContent, updateNoteHash, opAddNote } from '../lib/notes.js';
 import { contentHash } from '../lib/hash.js';
 import { generateClaudeMd, generateMemoryMd } from '../lib/generators.js';
 import { confirm } from '../lib/prompt.js';
+import { writeNoteFile } from '../lib/file-writer.js';
 export async function sync(config, options) {
     const { quiet, force, dryRun } = options;
-    const notes = await fetchPersonaNotes(config.supabase);
+    const notes = await fetchSyncableNotes(config.supabase);
     const result = {
         downloaded: [],
         uploaded: [],
@@ -25,15 +26,17 @@ export async function sync(config, options) {
     await syncTypeRegistryPull(config, quiet, force, dryRun);
     const notesByFile = new Map();
     for (const note of notes) {
-        const localFile = note.metadata.local_file;
-        if (localFile)
-            notesByFile.set(localFile, note);
+        const filePath = note.metadata.file_path;
+        const fileKey = filePath ? filePath.split('/').pop() : undefined;
+        if (fileKey)
+            notesByFile.set(fileKey, note);
     }
     // --- Phase 1: Process each persona note ---
     for (const note of notes) {
-        const localFile = note.metadata.local_file;
-        if (!localFile)
+        const noteFilePath = note.metadata.file_path;
+        if (!noteFilePath)
             continue;
+        const localFile = noteFilePath.split('/').pop();
         const filePath = resolve(config.memoryDir, localFile);
         const ledgerContent = note.content;
         const ledgerHash = contentHash(ledgerContent);
@@ -173,26 +176,62 @@ export async function sync(config, options) {
                 console.error(`  ${file} — removed (no longer in Ledger)`);
         }
     }
+    // --- Phase 2.5: Write file_path notes to disk (hooks, skills, configs) ---
+    const filePathNotes = notes.filter(n => {
+        const fp = n.metadata.file_path;
+        return fp && fp.startsWith('/') && !fp.includes('/memory/');
+    });
+    for (const note of filePathNotes) {
+        const fp = note.metadata.file_path;
+        const perms = note.metadata.file_permissions ?? null;
+        if (dryRun) {
+            if (!quiet)
+                console.error(`  ${fp} — would write (file_path note)`);
+            continue;
+        }
+        const writeResult = writeNoteFile(note.content, fp, perms);
+        if (writeResult.status === 'written') {
+            if (!quiet)
+                console.error(`  ${fp} — written`);
+        }
+    }
     // --- Phase 3: Regenerate MEMORY.md and CLAUDE.md ---
     if (!dryRun) {
-        const allLocalFiles = [...result.downloaded, ...result.uploaded, ...result.skipped, ...result.conflicts];
+        const autoLoadFiles = notes
+            .filter(n => n.metadata.auto_load === true && n.metadata.file_path)
+            .map(n => {
+            const fp = n.metadata.file_path;
+            return fp.includes('/') ? fp.split('/').pop() : fp;
+        });
+        const allLocalFiles = [...new Set([...autoLoadFiles, ...result.downloaded, ...result.uploaded, ...result.skipped])];
         const memoryPath = resolve(config.memoryDir, 'MEMORY.md');
         writeFileSync(memoryPath, generateMemoryMd(allLocalFiles), 'utf-8');
-        const feedbackNotes = notes.filter(n => n.metadata.type === 'feedback');
-        const newClaudeMd = generateClaudeMd(feedbackNotes);
-        if (existsSync(config.claudeMdPath)) {
-            const existing = readFileSync(config.claudeMdPath, 'utf-8');
-            if (existing.startsWith('# Global Rules') || force) {
+        // CLAUDE.md: prefer claude-md note, fall back to legacy generation
+        const claudeMdNote = notes.find(n => n.metadata.type === 'claude-md' ||
+            n.metadata.upsert_key === 'claude-md-backup');
+        if (claudeMdNote) {
+            writeFileSync(config.claudeMdPath, claudeMdNote.content, 'utf-8');
+            if (!quiet)
+                console.error('  wrote ~/CLAUDE.md (from claude-md note)');
+        }
+        else {
+            // Legacy fallback
+            const feedbackNotes = notes.filter(n => n.metadata.type === 'feedback');
+            const newClaudeMd = generateClaudeMd(feedbackNotes);
+            if (existsSync(config.claudeMdPath)) {
+                const existing = readFileSync(config.claudeMdPath, 'utf-8');
+                if (existing.startsWith('# Global Rules') || force) {
+                    writeFileSync(config.claudeMdPath, newClaudeMd, 'utf-8');
+                    if (!quiet)
+                        console.error('  wrote ~/CLAUDE.md');
+                }
+            }
+            else {
                 writeFileSync(config.claudeMdPath, newClaudeMd, 'utf-8');
                 if (!quiet)
                     console.error('  wrote ~/CLAUDE.md');
             }
         }
-        else {
-            writeFileSync(config.claudeMdPath, newClaudeMd, 'utf-8');
-            if (!quiet)
-                console.error('  wrote ~/CLAUDE.md');
-        }
     }
     // --- Phase 3.5: Push type registry ---
     await syncTypeRegistryPush(config, quiet, dryRun);
@@ -225,7 +264,7 @@ export async function syncTypeRegistryPush(config, quiet, dryRun) {
     await opAddNote(clients, content, 'system-rule', 'ledger-sync', {
         upsert_key: 'system-rule-type-registry',
         description: 'User-defined type registry overrides. Managed by ledger sync.',
-        delivery: 'persona',
+        domain: 'system',
         scope: 'system',
         interactive_skip: true,
     }, true); // force: true to skip duplicate guard

package/dist/commands/tag.js

@@ -1,20 +1,26 @@
-import { opUpdateMetadata } from '../lib/notes.js';
+import { getDocumentById } from '../lib/documents/fetching.js';
+import { updateDocumentFields } from '../lib/documents/operations.js';
 export async function tag(config, id, options) {
-    const metadata = {};
-    if (options.description)
-        metadata.description = options.description;
-    if (options.project)
-        metadata.project = options.project;
-    if (options.scope)
-        metadata.scope = options.scope;
-    if (Object.keys(metadata).length === 0) {
-        console.error('No metadata fields provided. Use --description, --project, or --scope.');
+    if (!options.description && !options.project && !options.domain && !options.status) {
+        console.error('No fields provided. Use --description, --project, --domain, or --status.');
         process.exit(1);
     }
-    const result = await opUpdateMetadata({ supabase: config.supabase, openai: config.openai }, id, metadata);
-    if (result.status === 'error') {
-        console.error(result.message);
+    const document = await getDocumentById(config.supabase, id);
+    if (!document) {
+        console.error(`Document ${id} not found.`);
         process.exit(1);
     }
-    console.error(result.message);
+    if (document.protection === 'immutable') {
+        console.error(`Document "${document.name}" (id: ${id}) is immutable and cannot be updated.`);
+        process.exit(1);
+    }
+    await updateDocumentFields({ supabase: config.supabase, openai: config.openai }, {
+        id,
+        description: options.description,
+        project: options.project,
+        domain: options.domain,
+        status: options.status,
+        agent: 'cli',
+    });
+    console.error(`Document ${id} fields updated.`);
 }

package/dist/commands/update.js

@@ -1,22 +1,54 @@
-import { opUpdateNote } from '../lib/notes.js';
+import { resolve } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { getDocumentById } from '../lib/documents/fetching.js';
+import { updateDocumentFromFile, VerifyMismatchError } from '../lib/documents/operations.js';
 import { confirm } from '../lib/prompt.js';
-export async function update(config, id, content, options) {
-    const clients = { supabase: config.supabase, openai: config.openai };
-    // First call: show confirmation
-    const preview = await opUpdateNote(clients, id, content, options.metadata, false);
-    if (preview.status === 'error') {
-        console.error(preview.message);
-        process.exit(1);
+import { fatal, ExitCode } from '../lib/errors.js';
+/**
+ * Update an existing document by reading new content from a file on disk.
+ * Auto-verified after push: the doc is pulled back and byte-compared against
+ * the file we sent. VerifyMismatchError on round-trip drift.
+ *
+ * Bytes flow file -> updateDocumentFromFile() -> Postgres without retyping.
+ * The composed-string path (`-c`) was removed in Phase 4 of the
+ * file-based-write-api rollout to close the drift class of bug.
+ */
+export async function updateFromFile(config, id, filePath, options = {}) {
+    const absPath = resolve(filePath);
+    if (!existsSync(absPath)) {
+        fatal(`File not found: ${absPath}`, ExitCode.FILE_NOT_FOUND);
     }
-    console.error(preview.message);
-    const proceed = await confirm('\nProceed with update?');
-    if (!proceed) {
-        console.error('Cancelled.');
-        return;
+    const document = await getDocumentById(config.supabase, id);
+    if (!document) {
+        fatal(`Document ${id} not found.`, ExitCode.DOCUMENT_NOT_FOUND);
+    }
+    if (document.protection === 'immutable') {
+        fatal(`Document "${document.name}" (id: ${id}) is immutable and cannot be updated.`, ExitCode.PROTECTED);
+    }
+    const newContent = readFileSync(absPath, 'utf8');
+    process.stderr.write(`Document: "${document.name}" (id: ${id})\n`);
+    process.stderr.write(`Current content preview: ${document.content.slice(0, 200)}${document.content.length > 200 ? '...' : ''}\n`);
+    process.stderr.write(`\nNew content preview: ${newContent.slice(0, 200)}${newContent.length > 200 ? '...' : ''}\n`);
+    process.stderr.write(`Source file: ${absPath} (${newContent.length} bytes)\n`);
+    if (!options.yes) {
+        const proceed = await confirm('\nProceed with update?');
+        if (!proceed) {
+            process.stderr.write('Cancelled.\n');
+            return;
+        }
+    }
+    try {
+        const result = await updateDocumentFromFile({ supabase: config.supabase, openai: config.openai }, { id, filePath: absPath, agent: 'cli' });
+        process.stderr.write(`Document ${id} updated successfully (${result.bytes} bytes, verified).\n`);
+    }
+    catch (error) {
+        if (error instanceof VerifyMismatchError) {
+            process.stderr.write(`\nVerify failed on document ${error.id}.\n`);
+            process.stderr.write(`Pushed ${error.expectedLength} bytes, pulled ${error.actualLength} bytes.\n`);
+            process.stderr.write(`${error.diffPreview}\n`);
+            process.stderr.write(`The push completed but the round-trip diff caught drift. Re-pull and re-edit.\n`);
+            process.exit(ExitCode.VERIFY_MISMATCH);
+        }
+        throw error;
     }
-    // Second call: execute
-    const result = await opUpdateNote(clients, id, content, options.metadata, true);
-    console.error(result.message);
-    if (result.status === 'error')
-        process.exit(1);
 }

package/dist/commands/wizard.js

@@ -107,7 +107,7 @@ export async function wizard() {
     // Step 7: Migrate local files
     const unknownFiles = getMemoryFiles(config);
     const personaNotes = await fetchPersonaNotes(config.supabase);
-    const knownFiles = new Set(personaNotes.map(n => n.metadata.local_file).filter(Boolean));
+    const knownFiles = new Set(personaNotes.map(n => n.metadata.file_path).filter(Boolean));
     const unknowns = unknownFiles.filter(f => !knownFiles.has(f));
     if (unknowns.length === 0) {
         console.error('Step 7: Migration: no unknown files\n');
@@ -177,7 +177,7 @@ async function showAlreadySetUp(checks) {
         const { data: personaData } = await supabase
             .from('notes')
             .select('id')
-            .eq('metadata->>delivery', 'persona')
+            .eq('metadata->>domain', 'persona')
             .limit(1);
         const hasPersona = personaData !== null && personaData.length > 0;
         // Check platforms
@@ -318,7 +318,7 @@ async function stepDeviceAlias(config) {
             content,
             metadata: {
                 type: 'reference',
-                delivery: 'knowledge',
+                domain: 'workspace',
                 agent: 'ledger-wizard',
                 scope: 'user',
                 upsert_key: 'user-devices',

package/dist/lib/ai-search.js

@@ -0,0 +1,163 @@
+// ai-search.ts
+// AI-powered search — vector (meaning), keyword (exact words), hybrid (both combined).
+// Each function calls a Postgres RPC function that does the actual search.
+// TypeScript's job: generate the query embedding, then call the right function.
+import { getOrCacheQueryEmbedding, toVectorString } from './embeddings.js';
+// =============================================================================
+// Search evaluation logging
+// =============================================================================
+/**
+ * Log a search to the search_evaluations table.
+ * Called after every search — silently records what was searched,
+ * what came back, and how long it took. This is the raw data
+ * that powers all evaluation, quality tracking, and improvement.
+ *
+ * Fire-and-forget: we don't await this. If logging fails,
+ * the search still returns results. The user never waits for logging.
+ */
+function logSearchEvaluation(supabase, params) {
+    // Extract unique document_types and source_types from results
+    // These tell us which types of documents search finds well vs poorly
+    const documentTypes = [...new Set(params.results.map(result => result.document_type))];
+    // Build the results JSONB array — just IDs and scores, not full content
+    const resultsSummary = params.results.map(result => ({
+        id: result.id,
+        score: result.similarity ?? result.rank ?? result.score ?? null,
+        document_type: result.document_type,
+    }));
+    // Fire and forget — don't await, don't block the search response
+    supabase
+        .from('search_evaluations')
+        .insert({
+        query_text: params.query,
+        search_mode: params.searchMode,
+        result_count: params.results.length,
+        results: resultsSummary,
+        document_types: documentTypes,
+        response_time_ms: params.responseTimeMs,
+    })
+        .then(() => { })
+        .catch(() => {
+        // Silently ignore logging failures — search results matter more
+    });
+}
+// =============================================================================
+// Search functions
+// =============================================================================
+/**
+ * Search by meaning — "how does auth work?" finds documents about OAuth.
+ *
+ * Flow:
+ * 1. Convert query text to an embedding (array of 1,536 numbers) via OpenAI
+ * 2. Check the query_cache first to avoid repeat API calls
+ * 3. Call match_documents RPC — Postgres compares the query embedding
+ *    against every chunk's embedding using cosine similarity
+ * 4. Return matching documents sorted by similarity
+ */
+export async function searchByVector(clients, props) {
+    const startTime = Date.now();
+    const queryEmbedding = await getOrCacheQueryEmbedding(clients, props.query);
+    const { data, error } = await clients.supabase.rpc('match_documents', {
+        q_emb: toVectorString(queryEmbedding),
+        p_threshold: props.threshold ?? 0.25,
+        p_max_results: props.limit ?? 10,
+        p_domain: props.domain ?? null,
+        p_document_type: props.document_type ?? null,
+        p_project: props.project ?? null,
+    });
+    if (error)
+        throw new Error(`Vector search failed: ${error.message}`);
+    const results = (data ?? []);
+    logSearchEvaluation(clients.supabase, {
+        query: props.query,
+        searchMode: 'vector',
+        results,
+        responseTimeMs: Date.now() - startTime,
+    });
+    return results;
+}
+/**
+ * Search by exact words — "pgvector HNSW" finds documents containing those words.
+ *
+ * No embedding needed — Postgres uses the search_vector column (GIN index)
+ * to match words directly. Good for code identifiers, proper nouns, error messages.
+ */
+export async function searchByKeyword(supabase, props) {
+    const startTime = Date.now();
+    const { data, error } = await supabase.rpc('match_documents_keyword', {
+        p_query: props.query,
+        p_max_results: props.limit ?? 10,
+        p_domain: props.domain ?? null,
+        p_document_type: props.document_type ?? null,
+        p_project: props.project ?? null,
+    });
+    if (error)
+        throw new Error(`Keyword search failed: ${error.message}`);
+    const results = (data ?? []);
+    logSearchEvaluation(supabase, {
+        query: props.query,
+        searchMode: 'keyword',
+        results,
+        responseTimeMs: Date.now() - startTime,
+    });
+    return results;
+}
+/**
+ * Combined search — runs both vector AND keyword, merges results with RRF fusion.
+ *
+ * Documents found by both methods rank highest. This is the default search mode
+ * because it handles both meaning-based queries ("how does auth work?") and
+ * exact-term queries ("pgvector HNSW") well.
+ *
+ * RRF (Reciprocal Rank Fusion) formula:
+ *   score = 1/(k + vector_rank) + 1/(k + keyword_rank)
+ *   k=60 is a smoothing constant that prevents the #1 result from dominating.
+ */
+export async function searchHybrid(clients, props) {
+    const startTime = Date.now();
+    const queryEmbedding = await getOrCacheQueryEmbedding(clients, props.query);
+    const { data, error } = await clients.supabase.rpc('match_documents_hybrid', {
+        q_emb: toVectorString(queryEmbedding),
+        q_text: props.query,
+        p_threshold: props.threshold ?? 0.25,
+        p_max_results: props.limit ?? 10,
+        p_domain: props.domain ?? null,
+        p_document_type: props.document_type ?? null,
+        p_project: props.project ?? null,
+        p_rrf_k: props.rrf_k ?? 60,
+    });
+    if (error)
+        throw new Error(`Hybrid search failed: ${error.message}`);
+    const results = (data ?? []);
+    logSearchEvaluation(clients.supabase, {
+        query: props.query,
+        searchMode: 'hybrid',
+        results,
+        responseTimeMs: Date.now() - startTime,
+    });
+    return results;
+}
+/**
+ * Smart retrieval — decide how much content to send to the LLM.
+ *
+ * After search finds a matching document, this decides:
+ * - Small document (under context_window chars) → return full content
+ * - Large document → return only the matched chunk + neighbors
+ *
+ * Why: sending a 50,000-char document to the LLM when only one section
+ * is relevant wastes tokens and money. But sending only a 500-char chunk
+ * might miss context. This finds the balance.
+ */
+export async function retrieveContext(supabase, props) {
+    const { data, error } = await supabase.rpc('retrieve_context', {
+        p_document_id: props.document_id,
+        p_matched_chunk_index: props.matched_chunk_index,
+        p_context_window: props.context_window ?? 4000,
+        p_neighbor_count: props.neighbor_count ?? 1,
+    });
+    if (error)
+        throw new Error(`Context retrieval failed: ${error.message}`);
+    if (!data || (Array.isArray(data) && data.length === 0))
+        return null;
+    return (Array.isArray(data) ? data[0] : data);
+}

package/dist/lib/audit.js

@@ -0,0 +1,19 @@
+/**
+ * Log a note operation to the audit_log table.
+ * Extracts domain + agent from metadata automatically.
+ * Silently fails if the audit_log table doesn't exist yet (pre-migration).
+ */
+export async function audit(clients, noteId, metadata, operation, diff) {
+    const { error } = await clients.supabase
+        .from('audit_log')
+        .insert({
+        note_id: noteId,
+        domain: metadata.domain ?? null,
+        operation,
+        agent: metadata.agent ?? 'unknown',
+        diff,
+    });
+    if (error) {
+        console.error(`[audit] Warning: failed to write audit entry: ${error.message}`);
+    }
+}

package/dist/lib/backfill.js

@@ -0,0 +1,60 @@
+import { homedir } from 'os';
+import { resolve } from 'path';
+import { TYPE_MIGRATION, inferDomain, getProtectionDefault, getAutoLoadDefault, isV2Type, } from './domains.js';
+const HOME_PROJECT_DIR = homedir().replace(/\//g, '-');
+const MEMORY_DIR = resolve(homedir(), `.claude/projects/${HOME_PROJECT_DIR}/memory`);
+/**
+ * Backfill v1 note metadata to v2 format.
+ * Pure function — no DB calls. Idempotent: skips notes that already have `domain`.
+ */
+export function backfillMetadata(metadata) {
+    // Idempotent: if already has domain + schema_version, skip
+    if (metadata.domain && metadata.schema_version) {
+        return metadata;
+    }
+    const result = { ...metadata };
+    const oldType = metadata.type;
+    // --- Step 1: Migrate type + infer domain ---
+    let newType = oldType ?? 'knowledge';
+    let domain;
+    const migration = oldType ? TYPE_MIGRATION[oldType] : undefined;
+    const hasProject = !!metadata.project;
+    if (migration) {
+        newType = migration.type;
+        domain = migration.domain;
+        // knowledge-guide maps to general by default, but promote to project if note has a project tag
+        if (migration.domain === 'general' && hasProject) {
+            domain = 'project';
+        }
+    }
+    else if (oldType === 'general') {
+        newType = 'general';
+        domain = 'general';
+    }
+    else if (oldType && isV2Type(oldType)) {
+        domain = inferDomain(oldType);
+    }
+    else {
+        newType = 'general';
+        domain = 'general';
+    }
+    result.type = newType;
+    result.domain = domain;
+    // --- Step 2: Set protection and auto_load from defaults ---
+    result.protection = getProtectionDefault(newType);
+    result.auto_load = getAutoLoadDefault(domain, newType);
+    // --- Step 3: Ownership (single user for now) ---
+    result.owner_type = 'user';
+    result.owner_id = null;
+    // --- Step 4: Schema + embedding tracking ---
+    result.schema_version = 1;
+    result.embedding_model = 'openai/text-embedding-3-small';
+    result.embedding_dimensions = 1536;
+    // --- Step 5: Derive file_path from local_file for persona notes ---
+    const localFile = metadata.local_file;
+    if (localFile && domain === 'persona' && !result.file_path) {
+        result.file_path = resolve(MEMORY_DIR, localFile);
+        result.file_permissions = '644';
+    }
+    return result;
+}