@velvetmonkey/vault-core 2.0.140 → 2.0.142

package/dist/entities.js

@@ -249,13 +249,53 @@ function mapFrontmatterType(type) {
  * 7. Projects - multi-word (fallback)
  * 8. Other - single word default
  */
-function categorizeEntity(name, techKeywords, frontmatterType) {
+// Folder names that imply entity categories
+const FOLDER_CATEGORY_MAP = {
+    'people': 'people',
+    'person': 'people',
+    'contacts': 'people',
+    'team': 'people',
+    'members': 'people',
+    'projects': 'projects',
+    'project': 'projects',
+    'locations': 'locations',
+    'places': 'locations',
+    'companies': 'organizations',
+    'organizations': 'organizations',
+    'orgs': 'organizations',
+    'concepts': 'concepts',
+    'topics': 'concepts',
+    'tools': 'technologies',
+    'software': 'technologies',
+    'media': 'media',
+    'books': 'media',
+    'films': 'media',
+    'movies': 'media',
+    'music': 'media',
+    'vehicles': 'vehicles',
+    'equipment': 'technologies',
+    'food': 'food',
+    'recipes': 'food',
+    'health': 'health',
+    'finance': 'finance',
+    'hobbies': 'hobbies',
+};
+function categorizeEntity(name, techKeywords, frontmatterType, notePath) {
     // 0. Frontmatter type takes priority
     if (frontmatterType) {
         const mapped = mapFrontmatterType(frontmatterType);
         if (mapped)
             return mapped;
     }
+    // 0.5. Folder-based inference (e.g., people/Andrew.md → person)
+    if (notePath) {
+        const segments = notePath.toLowerCase().split('/');
+        for (const segment of segments) {
+            const mapped = FOLDER_CATEGORY_MAP[segment];
+            if (mapped)
+                return mapped;
+        }
+    }
     const nameLower = name.toLowerCase();
     const words = name.split(/\s+/);
     // 1. Technology check (keyword match)
@@ -438,7 +478,7 @@ export async function scanVaultEntities(vaultPath, options = {}) {
         },
     };
     for (const entity of uniqueEntities) {
-        const category = categorizeEntity(entity.name, techKeywords, entity.frontmatterType);
+        const category = categorizeEntity(entity.name, techKeywords, entity.frontmatterType, entity.relativePath);
         // Store as EntityWithAliases object
         const entityObj = {
             name: entity.name,

package/dist/migrations.d.ts

@@ -2,9 +2,13 @@
  * SQLite Schema Migrations
  *
  * Database path resolution, schema initialization, migration logic,
- * and database file management utilities.
+ * database file management, backup rotation, integrity checks, and
+ * feedback salvage utilities.
  */
 import Database from 'better-sqlite3';
+export declare const BACKUP_ROTATION_COUNT = 3;
+/** High-value tables whose data should survive a corruption recovery. */
+export declare const SALVAGE_TABLES: readonly ["wikilink_feedback", "wikilink_applications", "suggestion_events", "wikilink_suppressions", "note_links", "note_link_history", "memories", "session_summaries", "corrections"];
 /**
  * Get the database path for a vault
  */
@@ -18,4 +22,35 @@ export declare function deleteStateDbFiles(dbPath: string): void;
 export declare function backupStateDb(dbPath: string): void;
 /** Preserve a corrupted database for inspection before deleting. */
 export declare function preserveCorruptedDb(dbPath: string): void;
+/**
+ * Rotate existing backup files: .backup → .backup.1 → .backup.2 → .backup.3
+ * Drops the oldest if rotation count exceeded. Does NOT create a new backup.
+ */
+export declare function rotateBackupFiles(dbPath: string): void;
+/**
+ * Create a WAL-safe backup using SQLite's backup API.
+ * Rotates existing backups first, then writes a new .backup file.
+ */
+export declare function safeBackupAsync(db: Database.Database, dbPath: string): Promise<boolean>;
+/**
+ * Run PRAGMA quick_check on the database.
+ * Returns { ok: true } or { ok: false, detail: string }.
+ */
+export declare function checkDbIntegrity(db: Database.Database): {
+    ok: boolean;
+    detail?: string;
+};
+/**
+ * Attempt to copy high-value feedback tables from a source DB into the target.
+ * Opens source read-only; copies rows with INSERT OR IGNORE.
+ * Handles missing tables and column mismatches gracefully.
+ */
+export declare function salvageFeedbackTables(targetDb: Database.Database, sourceDbPath: string): Record<string, number>;
+/**
+ * After corruption forces a fresh DB, attempt to recover feedback data
+ * from all available backup files (newest first) and the corrupt file.
+ * Merges across all sources — INSERT OR IGNORE deduplicates, so each
+ * successive source only adds rows the previous ones didn't cover.
+ */
+export declare function attemptSalvage(targetDb: Database.Database, dbPath: string): void;
 //# sourceMappingURL=migrations.d.ts.map

package/dist/migrations.js

@@ -2,12 +2,30 @@
  * SQLite Schema Migrations
  *
  * Database path resolution, schema initialization, migration logic,
- * and database file management utilities.
+ * database file management, backup rotation, integrity checks, and
+ * feedback salvage utilities.
  */
+import Database from 'better-sqlite3';
 import * as fs from 'fs';
 import * as path from 'path';
 import { SCHEMA_VERSION, SCHEMA_SQL, STATE_DB_FILENAME, FLYWHEEL_DIR } from './schema.js';
 // =============================================================================
+// Backup & Recovery Constants
+// =============================================================================
+export const BACKUP_ROTATION_COUNT = 3;
+/** High-value tables whose data should survive a corruption recovery. */
+export const SALVAGE_TABLES = [
+    'wikilink_feedback',
+    'wikilink_applications',
+    'suggestion_events',
+    'wikilink_suppressions',
+    'note_links',
+    'note_link_history',
+    'memories',
+    'session_summaries',
+    'corrections',
+];
+// =============================================================================
 // Database Path Resolution
 // =============================================================================
 /**
@@ -317,4 +335,166 @@ export function preserveCorruptedDb(dbPath) {
         // Best effort — don't block recovery
     }
 }
+// =============================================================================
+// Backup Rotation & Safe Backup
+// =============================================================================
+/**
+ * Rotate existing backup files: .backup → .backup.1 → .backup.2 → .backup.3
+ * Drops the oldest if rotation count exceeded. Does NOT create a new backup.
+ */
+export function rotateBackupFiles(dbPath) {
+    try {
+        // Shift numbered backups down (3→drop, 2→3, 1→2)
+        for (let i = BACKUP_ROTATION_COUNT; i >= 1; i--) {
+            const src = i === 1
+                ? `${dbPath}.backup`
+                : `${dbPath}.backup.${i - 1}`;
+            const dst = `${dbPath}.backup.${i}`;
+            if (fs.existsSync(src)) {
+                if (i === BACKUP_ROTATION_COUNT && fs.existsSync(dst)) {
+                    fs.unlinkSync(dst);
+                }
+                fs.renameSync(src, dst);
+            }
+        }
+    }
+    catch (err) {
+        console.error(`[vault-core] Failed to rotate backups: ${err instanceof Error ? err.message : err}`);
+    }
+}
+/**
+ * Create a WAL-safe backup using SQLite's backup API.
+ * Rotates existing backups first, then writes a new .backup file.
+ */
+export async function safeBackupAsync(db, dbPath) {
+    try {
+        rotateBackupFiles(dbPath);
+        const backupPath = `${dbPath}.backup`;
+        await db.backup(backupPath);
+        console.error(`[vault-core] Safe backup created: ${path.basename(backupPath)}`);
+        return true;
+    }
+    catch (err) {
+        console.error(`[vault-core] Safe backup failed: ${err instanceof Error ? err.message : err}`);
+        return false;
+    }
+}
+// =============================================================================
+// Integrity Checks
+// =============================================================================
+/**
+ * Run PRAGMA quick_check on the database.
+ * Returns { ok: true } or { ok: false, detail: string }.
+ */
+export function checkDbIntegrity(db) {
+    try {
+        const result = db.pragma('quick_check');
+        const firstValue = result.length > 0 ? Object.values(result[0])[0] : 'no result';
+        if (result.length === 1 && firstValue === 'ok') {
+            return { ok: true };
+        }
+        return { ok: false, detail: firstValue ?? 'unknown' };
+    }
+    catch (err) {
+        return { ok: false, detail: err instanceof Error ? err.message : String(err) };
+    }
+}
+// =============================================================================
+// Feedback Salvage
+// =============================================================================
+/**
+ * Attempt to copy high-value feedback tables from a source DB into the target.
+ * Opens source read-only; copies rows with INSERT OR IGNORE.
+ * Handles missing tables and column mismatches gracefully.
+ */
+export function salvageFeedbackTables(targetDb, sourceDbPath) {
+    const results = {};
+    if (!fs.existsSync(sourceDbPath))
+        return results;
+    let sourceDb = null;
+    try {
+        sourceDb = new Database(sourceDbPath, { readonly: true, fileMustExist: true });
+        for (const table of SALVAGE_TABLES) {
+            try {
+                // Check table exists in both source and target
+                const srcExists = sourceDb.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name=?`).get(table);
+                if (!srcExists)
+                    continue;
+                const tgtExists = targetDb.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name=?`).get(table);
+                if (!tgtExists)
+                    continue;
+                // Find columns common to both (handles schema version mismatches)
+                const targetCols = targetDb.pragma(`table_info('${table}')`)
+                    .map(c => c.name);
+                const sourceCols = sourceDb.pragma(`table_info('${table}')`)
+                    .map(c => c.name);
+                const commonCols = targetCols.filter(c => sourceCols.includes(c));
+                if (commonCols.length === 0)
+                    continue;
+                const colList = commonCols.join(', ');
+                const placeholders = commonCols.map(() => '?').join(', ');
+                const rows = sourceDb.prepare(`SELECT ${colList} FROM ${table}`).all();
+                if (rows.length === 0)
+                    continue;
+                const insert = targetDb.prepare(`INSERT OR IGNORE INTO ${table} (${colList}) VALUES (${placeholders})`);
+                const insertMany = targetDb.transaction((data) => {
+                    let count = 0;
+                    for (const row of data) {
+                        insert.run(...commonCols.map(c => row[c]));
+                        count++;
+                    }
+                    return count;
+                });
+                const count = insertMany(rows);
+                if (count > 0)
+                    results[table] = count;
+            }
+            catch (tableErr) {
+                console.error(`[vault-core] Salvage ${table}: ${tableErr instanceof Error ? tableErr.message : tableErr}`);
+            }
+        }
+    }
+    catch (err) {
+        console.error(`[vault-core] Cannot open ${path.basename(sourceDbPath)} for salvage: ${err instanceof Error ? err.message : err}`);
+    }
+    finally {
+        try {
+            sourceDb?.close();
+        }
+        catch { /* ignore */ }
+    }
+    return results;
+}
+/**
+ * After corruption forces a fresh DB, attempt to recover feedback data
+ * from all available backup files (newest first) and the corrupt file.
+ * Merges across all sources — INSERT OR IGNORE deduplicates, so each
+ * successive source only adds rows the previous ones didn't cover.
+ */
+export function attemptSalvage(targetDb, dbPath) {
+    const sources = [
+        `${dbPath}.backup`,
+        ...Array.from({ length: BACKUP_ROTATION_COUNT }, (_, i) => `${dbPath}.backup.${i + 1}`),
+        `${dbPath}.corrupt`,
+    ];
+    let totalSalvaged = 0;
+    for (const source of sources) {
+        if (!fs.existsSync(source))
+            continue;
+        console.error(`[vault-core] Attempting feedback salvage from ${path.basename(source)}...`);
+        const results = salvageFeedbackTables(targetDb, source);
+        const sourceRows = Object.values(results).reduce((a, b) => a + b, 0);
+        if (sourceRows > 0) {
+            const detail = Object.entries(results).map(([t, n]) => `${t}: ${n}`).join(', ');
+            console.error(`[vault-core] Salvaged ${sourceRows} rows from ${path.basename(source)}: ${detail}`);
+            totalSalvaged += sourceRows;
+        }
+    }
+    if (totalSalvaged > 0) {
+        console.error(`[vault-core] Total salvaged: ${totalSalvaged} rows across all sources`);
+    }
+    else {
+        console.error('[vault-core] No salvageable backup found — starting fresh');
+    }
+}
 //# sourceMappingURL=migrations.js.map

package/dist/sqlite.d.ts

@@ -14,6 +14,7 @@ import type { Statement, Transaction } from 'better-sqlite3';
 import type { EntityCategory, EntityWithAliases, EntityIndex } from './types.js';
 export { SCHEMA_VERSION, STATE_DB_FILENAME, FLYWHEEL_DIR, SCHEMA_SQL } from './schema.js';
 export { getStateDbPath, initSchema, deleteStateDbFiles, backupStateDb, preserveCorruptedDb } from './migrations.js';
+export { BACKUP_ROTATION_COUNT, SALVAGE_TABLES, rotateBackupFiles, safeBackupAsync, checkDbIntegrity, salvageFeedbackTables, attemptSalvage, } from './migrations.js';
 export { searchEntities, searchEntitiesPrefix, getEntityByName, getAllEntitiesFromDb, getEntityIndexFromDb, getEntitiesByAlias, recordEntityMention, getEntityRecency, getAllRecency, setWriteState, getWriteState, deleteWriteState, setFlywheelConfig, getFlywheelConfig, getAllFlywheelConfig, deleteFlywheelConfig, saveFlywheelConfigToDb, loadFlywheelConfigFromDb, recordMergeDismissal, getDismissedMergePairs, getStateDbMetadata, isEntityDataStale, escapeFts5Query, rebuildEntitiesFts, stateDbExists, deleteStateDb, saveVaultIndexCache, loadVaultIndexCache, getVaultIndexCacheInfo, clearVaultIndexCache, isVaultIndexCacheValid, loadContentHashes, saveContentHashBatch, renameContentHash, } from './queries.js';
 export type { FlywheelConfigRow, VaultIndexCacheData, VaultIndexCacheInfo } from './queries.js';
 /** Search result from FTS5 entity search */

package/dist/sqlite.js

@@ -15,10 +15,12 @@ import * as fs from 'fs';
 export { SCHEMA_VERSION, STATE_DB_FILENAME, FLYWHEEL_DIR, SCHEMA_SQL } from './schema.js';
 // Re-export migrations
 export { getStateDbPath, initSchema, deleteStateDbFiles, backupStateDb, preserveCorruptedDb } from './migrations.js';
+// Re-export backup & recovery
+export { BACKUP_ROTATION_COUNT, SALVAGE_TABLES, rotateBackupFiles, safeBackupAsync, checkDbIntegrity, salvageFeedbackTables, attemptSalvage, } from './migrations.js';
 // Re-export all query functions
 export { searchEntities, searchEntitiesPrefix, getEntityByName, getAllEntitiesFromDb, getEntityIndexFromDb, getEntitiesByAlias, recordEntityMention, getEntityRecency, getAllRecency, setWriteState, getWriteState, deleteWriteState, setFlywheelConfig, getFlywheelConfig, getAllFlywheelConfig, deleteFlywheelConfig, saveFlywheelConfigToDb, loadFlywheelConfigFromDb, recordMergeDismissal, getDismissedMergePairs, getStateDbMetadata, isEntityDataStale, escapeFts5Query, rebuildEntitiesFts, stateDbExists, deleteStateDb, saveVaultIndexCache, loadVaultIndexCache, getVaultIndexCacheInfo, clearVaultIndexCache, isVaultIndexCacheValid, loadContentHashes, saveContentHashBatch, renameContentHash, } from './queries.js';
 // Import for use in openStateDb
-import { getStateDbPath, initSchema, deleteStateDbFiles, backupStateDb, preserveCorruptedDb } from './migrations.js';
+import { getStateDbPath, initSchema, deleteStateDbFiles, preserveCorruptedDb, attemptSalvage } from './migrations.js';
 // =============================================================================
 // Factory
 // =============================================================================
@@ -30,8 +32,9 @@ import { getStateDbPath, initSchema, deleteStateDbFiles, backupStateDb, preserve
  */
 export function openStateDb(vaultPath) {
     const dbPath = getStateDbPath(vaultPath);
-    // Back up existing database before any mutations
-    backupStateDb(dbPath);
+    // Note: safe backup with rotation is done AFTER open + integrity check
+    // by the caller (initializeVault), not here. This avoids overwriting
+    // good backups with a corrupt DB before we've verified it.
     // Guard: Delete corrupted 0-byte database files
     // This can happen when better-sqlite3 fails to compile (e.g., Node 24)
     // and creates an empty file instead of a valid SQLite database
@@ -42,10 +45,15 @@ export function openStateDb(vaultPath) {
             deleteStateDbFiles(dbPath);
         }
     }
+    const isNewDb = !fs.existsSync(dbPath);
     let db;
     try {
         db = new Database(dbPath);
         initSchema(db);
+        // If we just created a fresh DB but backup files exist, salvage from them
+        if (isNewDb) {
+            attemptSalvage(db, dbPath);
+        }
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
@@ -61,6 +69,8 @@ export function openStateDb(vaultPath) {
             deleteStateDbFiles(dbPath);
             db = new Database(dbPath);
             initSchema(db);
+            // Try to recover feedback data from backups or the corrupt file
+            attemptSalvage(db, dbPath);
         }
         else {
             // Recoverable error (constraint violation, migration issue, etc.) — don't destroy the DB

package/dist/wikilinks.js

@@ -1083,6 +1083,9 @@ export function detectImplicitEntities(content, config = {}) {
         // Length check
         if (text.length < minEntityLength)
             return true;
+        // Must contain at least one letter — pure punctuation/symbols are never entities
+        if (!/[a-zA-Z]/.test(text))
+            return true;
         // Common words
         if (IMPLICIT_EXCLUDE_WORDS.has(text.toLowerCase()))
             return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velvetmonkey/vault-core",
-  "version": "2.0.140",
+  "version": "2.0.142",
   "description": "Shared vault utilities for Flywheel ecosystem (entity scanning, wikilinks, protected zones)",
   "type": "module",
   "main": "dist/index.js",