@vaur94/agz-memory 0.4.0 → 0.4.1

package/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # AGZ Memory Architecture
 
-This document describes the `0.4.0` runtime and SQLite schema v10.
+This document describes the `0.4.1` runtime and SQLite schema v10.
 
 ## System Boundaries
 
@@ -20,7 +20,7 @@ OpenCode V2 beta-18743
 
 SQLite outbox
   -> optional derived retrieval backend
-     -> disabled in 0.4.0; backend = none
+     -> disabled in 0.4.1; backend = none
 ```
 
 The MCP adapter owns tool schemas, annotations, and result envelopes. The core
@@ -128,7 +128,7 @@ original OpenCode context unchanged.
 
 Semantic providers implement an optional backend contract: project-filtered
 query, idempotent upsert, deterministic delete, full project purge, and health.
-No provider is enabled in `0.4.0`. The SQLite lexical/graph path remains fully
+No provider is enabled in `0.4.1`. The SQLite lexical/graph path remains fully
 functional without one.
 
 ## Derived Index Outbox

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to AGZ Memory are recorded here. The project follows
 [Semantic Versioning](https://semver.org/).
 
+## [0.4.1] - 2026-09-01
+
+### Fixed
+
+- Re-read the SQLite schema after acquiring the migration lock so concurrent
+  MCP processes do not act on a stale pre-lock version.
+- Skip backup and migration work when another process already completed the
+  target schema, preventing redundant backups whose manifest version could
+  differ from the copied database.
+- Retry migration-lock handoff when the previous owner releases the lock
+  between a competing process's create attempt and ownership check.
+- Reopen the canonical SQLite file after taking the migration lock so a waiter
+  cannot continue on a database file replaced during automatic recovery.
+- Verify versioned backup manifests against the schema stored in their SQLite
+  database instead of trusting the caller-provided source label.
+- Added a six-process regression test that requires exactly one v9 backup, a
+  v9 backup database, and one healthy v10 canonical database.
+
 ## [0.4.0] - 2026-09-01
 
 ### Added
@@ -56,5 +74,6 @@ All notable changes to AGZ Memory are recorded here. The project follows
 - Preserved the nine-tool MCP interface and project-isolation guarantees while
   establishing the AGZ Memory public packages and repository.
 
+[0.4.1]: https://github.com/ugur-murat-alt/agz-memory/releases/tag/v0.4.1
 [0.4.0]: https://github.com/ugur-murat-alt/agz-memory/releases/tag/v0.4.0
 [0.4.0-beta.1]: https://github.com/ugur-murat-alt/agz-memory/releases/tag/v0.4.0-beta.1

package/README.md

@@ -32,8 +32,8 @@ binding and rollout mode are configured.
 
 | Component | Supported version |
 |---|---|
-| Core and MCP | `0.4.0` |
-| OpenCode plugin | `0.4.0` |
+| Core and MCP | `0.4.1` |
+| OpenCode plugin | `0.4.1` |
 | OpenCode V2 | `0.0.0-beta-18743` |
 | `@opencode-ai/plugin` | `0.0.0-beta-18743` |
 | Bun | `>=1.3.14` |
@@ -47,7 +47,7 @@ itself unless the running OpenCode version exactly matches the supported beta.
 Run the server directly:
 
 ```sh
-bunx @vaur94/agz-memory@0.4.0
+bunx @vaur94/agz-memory@0.4.1
 ```
 
 Or register it in OpenCode V2 under `mcp.servers`:
@@ -58,7 +58,7 @@ Or register it in OpenCode V2 under `mcp.servers`:
     "servers": {
       "agz-memory": {
         "type": "local",
-        "command": ["bunx", "@vaur94/agz-memory@0.4.0"],
+        "command": ["bunx", "@vaur94/agz-memory@0.4.1"],
         "environment": {
           "OPENCODE_MEMORY_DATABASE_PATH": "{env:OPENCODE_MEMORY_DATABASE_PATH}"
         },
@@ -113,7 +113,7 @@ options:
 {
   "plugins": [
     {
-      "package": "@vaur94/agz-memory-plugin@0.4.0",
+      "package": "@vaur94/agz-memory-plugin@0.4.1",
       "options": {
         "mode": "off",
         "autoCreateProjects": false,
@@ -186,11 +186,11 @@ quality, and latency gates.
 The admin CLI reads the same `OPENCODE_MEMORY_DATABASE_PATH`:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin doctor
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin backup
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin upgrade --to 10
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin capture status
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin outbox status
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin upgrade --to 10
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin capture status
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin outbox status
 ```
 
 Upgrades take an exclusive migration lock and create a verified backup before
@@ -199,7 +199,7 @@ restore. Restore and backup deletion use dry-run output plus explicit
 confirmation values; never guess them.
 
 Use [the backup and restore runbook](docs/backup-restore-runbook.md) for a full
-rehearsal. Final `0.4.0` backup manifests use `agz-memory-backup/1`; prerelease
+rehearsal. Final `0.4.1` backup manifests use `agz-memory-backup/1`; prerelease
 manifests must be handled by the prerelease that created them.
 
 ## Security Model

package/README.tr.md

@@ -32,8 +32,8 @@ bağlam eklemez.
 
 | Bileşen | Desteklenen sürüm |
 |---|---|
-| Çekirdek ve MCP | `0.4.0` |
-| OpenCode eklentisi | `0.4.0` |
+| Çekirdek ve MCP | `0.4.1` |
+| OpenCode eklentisi | `0.4.1` |
 | OpenCode V2 | `0.0.0-beta-18743` |
 | `@opencode-ai/plugin` | `0.0.0-beta-18743` |
 | Bun | `>=1.3.14` |
@@ -47,7 +47,7 @@ MCP sunucusu bir OpenCode beta sürümüne bağlı değildir. İsteğe bağlı e
 Sunucuyu doğrudan çalıştırın:
 
 ```sh
-bunx @vaur94/agz-memory@0.4.0
+bunx @vaur94/agz-memory@0.4.1
 ```
 
 Ya da OpenCode V2 içinde `mcp.servers` altına kaydedin:
@@ -58,7 +58,7 @@ Ya da OpenCode V2 içinde `mcp.servers` altına kaydedin:
     "servers": {
       "agz-memory": {
         "type": "local",
-        "command": ["bunx", "@vaur94/agz-memory@0.4.0"],
+        "command": ["bunx", "@vaur94/agz-memory@0.4.1"],
         "environment": {
           "OPENCODE_MEMORY_DATABASE_PATH": "{env:OPENCODE_MEMORY_DATABASE_PATH}"
         },
@@ -114,7 +114,7 @@ ayarlarla ekleyin:
 {
   "plugins": [
     {
-      "package": "@vaur94/agz-memory-plugin@0.4.0",
+      "package": "@vaur94/agz-memory-plugin@0.4.1",
       "options": {
         "mode": "off",
         "autoCreateProjects": false,
@@ -187,11 +187,11 @@ kapılarından geçene kadar `semanticBackend` değeri `none` olmalıdır.
 Yönetim aracı aynı `OPENCODE_MEMORY_DATABASE_PATH` değerini okur:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin doctor
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin backup
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin upgrade --to 10
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin capture status
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin outbox status
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin upgrade --to 10
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin capture status
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin outbox status
 ```
 
 Yükseltmeler özel bir geçiş kilidi alır ve veritabanını değiştirmeden önce
@@ -200,7 +200,7 @@ dener. Geri yükleme ve yedek silme işlemleri önce deneme çıktısı, sonra a
 onay değerleri ister; bu değerleri tahmin etmeyin.
 
 Tam prova için [yedekleme ve geri yükleme runbook'unu](docs/backup-restore-runbook.tr.md)
-kullanın. Final `0.4.0` yedek manifestleri `agz-memory-backup/1` kullanır;
+kullanın. Final `0.4.1` yedek manifestleri `agz-memory-backup/1` kullanır;
 ön sürüm manifestleri onları oluşturan ön sürümle işlenmelidir.
 
 ## Güvenlik Modeli

package/dist/admin.js

@@ -107,6 +107,9 @@ function hasTable(db, table) {
 var BACKUP_FORMAT = "agz-memory-backup/1";
 function createVerifiedBackup(db, databasePath, sourceSchema, targetSchema, productVersion) {
   const sourceHealth = assertHealthyDatabase(db);
+  if (sourceHealth.schemaVersion !== undefined && sourceHealth.schemaVersion !== sourceSchema) {
+    throw new Error(`backup source schema v${sourceSchema} does not match database schema v${sourceHealth.schemaVersion}`);
+  }
   const checkpoint = db.query("PRAGMA wal_checkpoint(TRUNCATE)").get();
   if (checkpoint.busy !== 0)
     throw new Error("database WAL checkpoint is busy");
@@ -134,6 +137,9 @@ function createVerifiedBackup(db, databasePath, sourceSchema, targetSchema, prod
     if (JSON.stringify(backupHealth.counts) !== JSON.stringify(sourceHealth.counts)) {
       throw new Error("backup row counts differ from source database");
     }
+    if (backupHealth.schemaVersion !== undefined && backupHealth.schemaVersion !== sourceSchema) {
+      throw new Error("backup schema does not match source schema");
+    }
     const bytes = readFileSync(temporaryDatabasePath);
     const manifest = {
       format: BACKUP_FORMAT,
@@ -206,6 +212,9 @@ function verifyBackupManifest(manifestPath) {
     if (JSON.stringify(health.counts) !== JSON.stringify(manifest.counts)) {
       throw new Error("backup manifest row counts do not match");
     }
+    if (health.schemaVersion !== undefined && health.schemaVersion !== manifest.sourceSchema) {
+      throw new Error("backup manifest source schema does not match database");
+    }
   } finally {
     db.close();
   }
@@ -391,7 +400,7 @@ function acquireMigrationLock(databasePath, targetSchema, timeoutMs = 30000) {
           rmSync2(path, { recursive: true, force: true });
           throw error;
         }
-        if (!existsSync2(path))
+        if (!isAlreadyExistsError(error))
           throw error;
         if (Date.now() >= deadline) {
           const current = readMigrationLockOwner(path);
@@ -464,6 +473,9 @@ function processIsAlive(pid) {
     return false;
   }
 }
+function isAlreadyExistsError(error) {
+  return Boolean(error && typeof error === "object" && "code" in error && String(error.code) === "EEXIST");
+}
 
 // src/db/migrations/v009.ts
 import { createHash as createHash3, randomUUID as randomUUID3 } from "crypto";
@@ -866,7 +878,7 @@ function migrateV9ToV10(db) {
 }
 
 // src/version.ts
-var PRODUCT_VERSION = "0.4.0";
+var PRODUCT_VERSION = "0.4.1";
 
 // src/db.ts
 var DDL = `
@@ -909,13 +921,11 @@ CREATE INDEX IF NOT EXISTS note_edges_target_idx ON note_edges(project_id, targe
 CREATE TABLE IF NOT EXISTS schema_state (version INTEGER PRIMARY KEY);
 `;
 function openMemoryDatabase(path) {
-  const db = new Database2(path, { create: true });
-  chmodSync2(path, 384);
+  let db = openDatabase(path);
+  let dbOpen = true;
   let lock;
   let backup;
   try {
-    db.exec("PRAGMA busy_timeout=5000");
-    db.exec("PRAGMA journal_mode=WAL");
     const existingVersion = getSchemaVersion(db);
     if (existingVersion && existingVersion.version > SCHEMA_VERSION) {
       throw new Error(`database schema v${existingVersion.version} is newer than supported v${SCHEMA_VERSION}`);
@@ -928,14 +938,31 @@ function openMemoryDatabase(path) {
       return { db, close: () => db.close() };
     }
     if ((existingVersion?.version ?? 0) < SCHEMA_VERSION) {
+      db.close();
+      dbOpen = false;
       lock = acquireMigrationLock(path, SCHEMA_VERSION);
-      backup = createVerifiedBackup(db, path, existingVersion?.version ?? 2, SCHEMA_VERSION, PRODUCT_VERSION);
+      db = openDatabase(path);
+      dbOpen = true;
+      const migrationVersion = getSchemaVersion(db);
+      if (migrationVersion && migrationVersion.version > SCHEMA_VERSION) {
+        throw new Error(`database schema v${migrationVersion.version} is newer than supported v${SCHEMA_VERSION}`);
+      }
+      if ((migrationVersion?.version ?? 0) === SCHEMA_VERSION) {
+        lock.release();
+        lock = undefined;
+        db.exec("PRAGMA foreign_keys=ON");
+        db.exec(SCHEMA_TABLES);
+        db.exec(FTS_V9);
+        assertHealthyDatabase(db);
+        return { db, close: () => db.close() };
+      }
+      backup = createVerifiedBackup(db, path, migrationVersion?.version ?? 2, SCHEMA_VERSION, PRODUCT_VERSION);
       db.exec("PRAGMA foreign_keys=OFF");
-      if (!existingVersion && hasLegacyV2(db)) {
+      if (!migrationVersion && hasLegacyV2(db)) {
         db.exec(DDL);
         db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(id UNINDEXED, title, summary, content, tokenize='unicode61')");
         migrateFromV2(db, path);
-      } else if (!existingVersion) {
+      } else if (!migrationVersion) {
         db.exec(DDL);
         db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(id UNINDEXED, title, summary, content, tokenize='unicode61')");
         db.transaction(() => {
@@ -943,7 +970,7 @@ function openMemoryDatabase(path) {
           db.query("DELETE FROM schema_state").run();
           db.query("INSERT INTO schema_state (version) VALUES (8)").run();
         })();
-      } else if (existingVersion.version < 8) {
+      } else if (migrationVersion.version < 8) {
         db.exec(DDL);
         db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(id UNINDEXED, title, summary, content, tokenize='unicode61')");
         migrateToV8(db);
@@ -972,7 +999,8 @@ function openMemoryDatabase(path) {
     db.exec("PRAGMA foreign_keys=ON");
     return { db, close: () => db.close() };
   } catch (error) {
-    db.close();
+    if (dbOpen)
+      db.close();
     if (backup) {
       try {
         restoreVerifiedBackup(backup.manifestPath, path, "RESTORE_DATABASE_FROM_VERIFIED_BACKUP");
@@ -985,6 +1013,18 @@ function openMemoryDatabase(path) {
     lock?.release();
   }
 }
+function openDatabase(path) {
+  const db = new Database2(path, { create: true });
+  try {
+    chmodSync2(path, 384);
+    db.exec("PRAGMA busy_timeout=5000");
+    db.exec("PRAGMA journal_mode=WAL");
+    return db;
+  } catch (error) {
+    db.close();
+    throw error;
+  }
+}
 function getSchemaVersion(db) {
   if (!hasTable2(db, "schema_state"))
     return;

package/dist/core.js

@@ -95,6 +95,9 @@ function hasTable(db, table) {
 var BACKUP_FORMAT = "agz-memory-backup/1";
 function createVerifiedBackup(db, databasePath, sourceSchema, targetSchema, productVersion) {
   const sourceHealth = assertHealthyDatabase(db);
+  if (sourceHealth.schemaVersion !== undefined && sourceHealth.schemaVersion !== sourceSchema) {
+    throw new Error(`backup source schema v${sourceSchema} does not match database schema v${sourceHealth.schemaVersion}`);
+  }
   const checkpoint = db.query("PRAGMA wal_checkpoint(TRUNCATE)").get();
   if (checkpoint.busy !== 0)
     throw new Error("database WAL checkpoint is busy");
@@ -122,6 +125,9 @@ function createVerifiedBackup(db, databasePath, sourceSchema, targetSchema, prod
     if (JSON.stringify(backupHealth.counts) !== JSON.stringify(sourceHealth.counts)) {
       throw new Error("backup row counts differ from source database");
     }
+    if (backupHealth.schemaVersion !== undefined && backupHealth.schemaVersion !== sourceSchema) {
+      throw new Error("backup schema does not match source schema");
+    }
     const bytes = readFileSync(temporaryDatabasePath);
     const manifest = {
       format: BACKUP_FORMAT,
@@ -194,6 +200,9 @@ function verifyBackupManifest(manifestPath) {
     if (JSON.stringify(health.counts) !== JSON.stringify(manifest.counts)) {
       throw new Error("backup manifest row counts do not match");
     }
+    if (health.schemaVersion !== undefined && health.schemaVersion !== manifest.sourceSchema) {
+      throw new Error("backup manifest source schema does not match database");
+    }
   } finally {
     db.close();
   }
@@ -379,7 +388,7 @@ function acquireMigrationLock(databasePath, targetSchema, timeoutMs = 30000) {
           rmSync2(path, { recursive: true, force: true });
           throw error;
         }
-        if (!existsSync2(path))
+        if (!isAlreadyExistsError(error))
           throw error;
         if (Date.now() >= deadline) {
           const current = readMigrationLockOwner(path);
@@ -422,6 +431,9 @@ function processStartMarker(pid) {
     return;
   }
 }
+function isAlreadyExistsError(error) {
+  return Boolean(error && typeof error === "object" && "code" in error && String(error.code) === "EEXIST");
+}
 
 // src/db/migrations/v009.ts
 import { createHash as createHash3, randomUUID as randomUUID3 } from "crypto";
@@ -824,7 +836,7 @@ function migrateV9ToV10(db) {
 }
 
 // src/version.ts
-var PRODUCT_VERSION = "0.4.0";
+var PRODUCT_VERSION = "0.4.1";
 
 // src/db.ts
 var DDL = `
@@ -867,13 +879,11 @@ CREATE INDEX IF NOT EXISTS note_edges_target_idx ON note_edges(project_id, targe
 CREATE TABLE IF NOT EXISTS schema_state (version INTEGER PRIMARY KEY);
 `;
 function openMemoryDatabase(path) {
-  const db = new Database2(path, { create: true });
-  chmodSync2(path, 384);
+  let db = openDatabase(path);
+  let dbOpen = true;
   let lock;
   let backup;
   try {
-    db.exec("PRAGMA busy_timeout=5000");
-    db.exec("PRAGMA journal_mode=WAL");
     const existingVersion = getSchemaVersion(db);
     if (existingVersion && existingVersion.version > SCHEMA_VERSION) {
       throw new Error(`database schema v${existingVersion.version} is newer than supported v${SCHEMA_VERSION}`);
@@ -886,14 +896,31 @@ function openMemoryDatabase(path) {
       return { db, close: () => db.close() };
     }
     if ((existingVersion?.version ?? 0) < SCHEMA_VERSION) {
+      db.close();
+      dbOpen = false;
       lock = acquireMigrationLock(path, SCHEMA_VERSION);
-      backup = createVerifiedBackup(db, path, existingVersion?.version ?? 2, SCHEMA_VERSION, PRODUCT_VERSION);
+      db = openDatabase(path);
+      dbOpen = true;
+      const migrationVersion = getSchemaVersion(db);
+      if (migrationVersion && migrationVersion.version > SCHEMA_VERSION) {
+        throw new Error(`database schema v${migrationVersion.version} is newer than supported v${SCHEMA_VERSION}`);
+      }
+      if ((migrationVersion?.version ?? 0) === SCHEMA_VERSION) {
+        lock.release();
+        lock = undefined;
+        db.exec("PRAGMA foreign_keys=ON");
+        db.exec(SCHEMA_TABLES);
+        db.exec(FTS_V9);
+        assertHealthyDatabase(db);
+        return { db, close: () => db.close() };
+      }
+      backup = createVerifiedBackup(db, path, migrationVersion?.version ?? 2, SCHEMA_VERSION, PRODUCT_VERSION);
       db.exec("PRAGMA foreign_keys=OFF");
-      if (!existingVersion && hasLegacyV2(db)) {
+      if (!migrationVersion && hasLegacyV2(db)) {
         db.exec(DDL);
         db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(id UNINDEXED, title, summary, content, tokenize='unicode61')");
         migrateFromV2(db, path);
-      } else if (!existingVersion) {
+      } else if (!migrationVersion) {
         db.exec(DDL);
         db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(id UNINDEXED, title, summary, content, tokenize='unicode61')");
         db.transaction(() => {
@@ -901,7 +928,7 @@ function openMemoryDatabase(path) {
           db.query("DELETE FROM schema_state").run();
           db.query("INSERT INTO schema_state (version) VALUES (8)").run();
         })();
-      } else if (existingVersion.version < 8) {
+      } else if (migrationVersion.version < 8) {
         db.exec(DDL);
         db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(id UNINDEXED, title, summary, content, tokenize='unicode61')");
         migrateToV8(db);
@@ -930,7 +957,8 @@ function openMemoryDatabase(path) {
     db.exec("PRAGMA foreign_keys=ON");
     return { db, close: () => db.close() };
   } catch (error) {
-    db.close();
+    if (dbOpen)
+      db.close();
     if (backup) {
       try {
         restoreVerifiedBackup(backup.manifestPath, path, "RESTORE_DATABASE_FROM_VERIFIED_BACKUP");
@@ -943,6 +971,18 @@ function openMemoryDatabase(path) {
     lock?.release();
   }
 }
+function openDatabase(path) {
+  const db = new Database2(path, { create: true });
+  try {
+    chmodSync2(path, 384);
+    db.exec("PRAGMA busy_timeout=5000");
+    db.exec("PRAGMA journal_mode=WAL");
+    return db;
+  } catch (error) {
+    db.close();
+    throw error;
+  }
+}
 function getSchemaVersion(db) {
   if (!hasTable2(db, "schema_state"))
     return;

package/dist/server.js

@@ -110,6 +110,9 @@ function hasTable(db, table) {
 var BACKUP_FORMAT = "agz-memory-backup/1";
 function createVerifiedBackup(db, databasePath, sourceSchema, targetSchema, productVersion) {
   const sourceHealth = assertHealthyDatabase(db);
+  if (sourceHealth.schemaVersion !== undefined && sourceHealth.schemaVersion !== sourceSchema) {
+    throw new Error(`backup source schema v${sourceSchema} does not match database schema v${sourceHealth.schemaVersion}`);
+  }
   const checkpoint = db.query("PRAGMA wal_checkpoint(TRUNCATE)").get();
   if (checkpoint.busy !== 0)
     throw new Error("database WAL checkpoint is busy");
@@ -137,6 +140,9 @@ function createVerifiedBackup(db, databasePath, sourceSchema, targetSchema, prod
     if (JSON.stringify(backupHealth.counts) !== JSON.stringify(sourceHealth.counts)) {
       throw new Error("backup row counts differ from source database");
     }
+    if (backupHealth.schemaVersion !== undefined && backupHealth.schemaVersion !== sourceSchema) {
+      throw new Error("backup schema does not match source schema");
+    }
     const bytes = readFileSync(temporaryDatabasePath);
     const manifest = {
       format: BACKUP_FORMAT,
@@ -209,6 +215,9 @@ function verifyBackupManifest(manifestPath) {
     if (JSON.stringify(health.counts) !== JSON.stringify(manifest.counts)) {
       throw new Error("backup manifest row counts do not match");
     }
+    if (health.schemaVersion !== undefined && health.schemaVersion !== manifest.sourceSchema) {
+      throw new Error("backup manifest source schema does not match database");
+    }
   } finally {
     db.close();
   }
@@ -394,7 +403,7 @@ function acquireMigrationLock(databasePath, targetSchema, timeoutMs = 30000) {
           rmSync2(path, { recursive: true, force: true });
           throw error;
         }
-        if (!existsSync2(path))
+        if (!isAlreadyExistsError(error))
           throw error;
         if (Date.now() >= deadline) {
           const current = readMigrationLockOwner(path);
@@ -437,6 +446,9 @@ function processStartMarker(pid) {
     return;
   }
 }
+function isAlreadyExistsError(error) {
+  return Boolean(error && typeof error === "object" && "code" in error && String(error.code) === "EEXIST");
+}
 
 // src/db/migrations/v009.ts
 import { createHash as createHash3, randomUUID as randomUUID3 } from "crypto";
@@ -839,7 +851,7 @@ function migrateV9ToV10(db) {
 }
 
 // src/version.ts
-var PRODUCT_VERSION = "0.4.0";
+var PRODUCT_VERSION = "0.4.1";
 
 // src/db.ts
 var DDL = `
@@ -882,13 +894,11 @@ CREATE INDEX IF NOT EXISTS note_edges_target_idx ON note_edges(project_id, targe
 CREATE TABLE IF NOT EXISTS schema_state (version INTEGER PRIMARY KEY);
 `;
 function openMemoryDatabase(path) {
-  const db = new Database2(path, { create: true });
-  chmodSync2(path, 384);
+  let db = openDatabase(path);
+  let dbOpen = true;
   let lock;
   let backup;
   try {
-    db.exec("PRAGMA busy_timeout=5000");
-    db.exec("PRAGMA journal_mode=WAL");
     const existingVersion = getSchemaVersion(db);
     if (existingVersion && existingVersion.version > SCHEMA_VERSION) {
       throw new Error(`database schema v${existingVersion.version} is newer than supported v${SCHEMA_VERSION}`);
@@ -901,14 +911,31 @@ function openMemoryDatabase(path) {
       return { db, close: () => db.close() };
     }
     if ((existingVersion?.version ?? 0) < SCHEMA_VERSION) {
+      db.close();
+      dbOpen = false;
       lock = acquireMigrationLock(path, SCHEMA_VERSION);
-      backup = createVerifiedBackup(db, path, existingVersion?.version ?? 2, SCHEMA_VERSION, PRODUCT_VERSION);
+      db = openDatabase(path);
+      dbOpen = true;
+      const migrationVersion = getSchemaVersion(db);
+      if (migrationVersion && migrationVersion.version > SCHEMA_VERSION) {
+        throw new Error(`database schema v${migrationVersion.version} is newer than supported v${SCHEMA_VERSION}`);
+      }
+      if ((migrationVersion?.version ?? 0) === SCHEMA_VERSION) {
+        lock.release();
+        lock = undefined;
+        db.exec("PRAGMA foreign_keys=ON");
+        db.exec(SCHEMA_TABLES);
+        db.exec(FTS_V9);
+        assertHealthyDatabase(db);
+        return { db, close: () => db.close() };
+      }
+      backup = createVerifiedBackup(db, path, migrationVersion?.version ?? 2, SCHEMA_VERSION, PRODUCT_VERSION);
       db.exec("PRAGMA foreign_keys=OFF");
-      if (!existingVersion && hasLegacyV2(db)) {
+      if (!migrationVersion && hasLegacyV2(db)) {
         db.exec(DDL);
         db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(id UNINDEXED, title, summary, content, tokenize='unicode61')");
         migrateFromV2(db, path);
-      } else if (!existingVersion) {
+      } else if (!migrationVersion) {
         db.exec(DDL);
         db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(id UNINDEXED, title, summary, content, tokenize='unicode61')");
         db.transaction(() => {
@@ -916,7 +943,7 @@ function openMemoryDatabase(path) {
           db.query("DELETE FROM schema_state").run();
           db.query("INSERT INTO schema_state (version) VALUES (8)").run();
         })();
-      } else if (existingVersion.version < 8) {
+      } else if (migrationVersion.version < 8) {
         db.exec(DDL);
         db.exec("CREATE VIRTUAL TABLE IF NOT EXISTS notes_fts USING fts5(id UNINDEXED, title, summary, content, tokenize='unicode61')");
         migrateToV8(db);
@@ -945,7 +972,8 @@ function openMemoryDatabase(path) {
     db.exec("PRAGMA foreign_keys=ON");
     return { db, close: () => db.close() };
   } catch (error) {
-    db.close();
+    if (dbOpen)
+      db.close();
     if (backup) {
       try {
         restoreVerifiedBackup(backup.manifestPath, path, "RESTORE_DATABASE_FROM_VERIFIED_BACKUP");
@@ -958,6 +986,18 @@ function openMemoryDatabase(path) {
     lock?.release();
   }
 }
+function openDatabase(path) {
+  const db = new Database2(path, { create: true });
+  try {
+    chmodSync2(path, 384);
+    db.exec("PRAGMA busy_timeout=5000");
+    db.exec("PRAGMA journal_mode=WAL");
+    return db;
+  } catch (error) {
+    db.close();
+    throw error;
+  }
+}
 function getSchemaVersion(db) {
   if (!hasTable2(db, "schema_state"))
     return;

package/dist/types/server.d.ts

@@ -1,5 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/server";
 import type { MemoryStore } from "./store";
 export declare const SERVER_NAME = "agz-memory";
-export declare const SERVER_VERSION: "0.4.0";
+export declare const SERVER_VERSION: "0.4.1";
 export declare function createMemoryServer(store: MemoryStore): McpServer;

package/dist/types/version.d.ts

@@ -1 +1 @@
-export declare const PRODUCT_VERSION: "0.4.0";
+export declare const PRODUCT_VERSION: "0.4.1";

package/docs/backup-restore-runbook.md

@@ -2,7 +2,7 @@
 
 English | [Türkçe](backup-restore-runbook.tr.md)
 
-This runbook applies to `@vaur94/agz-memory@0.4.0` and SQLite schema v10.
+This runbook applies to `@vaur94/agz-memory@0.4.1` and SQLite schema v10.
 
 ## Preconditions
 
@@ -25,16 +25,16 @@ Do not proceed with a guessed or empty path.
 Run a read-only health report first:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
 ```
 
 `ok` must be `true`. Record `schemaVersion`, row counts, and invariant counts.
 Then create a standalone verified backup and upgrade:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin backup
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin upgrade --to 10
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin upgrade --to 10
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
 ```
 
 The upgrade itself creates another verified pre-migration backup when the
@@ -54,16 +54,16 @@ The manifest format is `agz-memory-backup/1`. `agz-memory-admin restore` verifie
 that the manifest and database are regular files in the same backup directory,
 then checks size, SHA-256, SQLite integrity, foreign keys, and row counts.
 
-Final `0.4.0` does not accept prerelease manifest formats. Use the originating
+Final `0.4.1` does not accept prerelease manifest formats. Use the originating
 prerelease to restore such a backup, run its doctor check, and only then upgrade
-that restored database with `0.4.0`.
+that restored database with `0.4.1`.
 
 ## Restore Rehearsal
 
 Keep all writers stopped. First request a dry run by omitting confirmation:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin restore \
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin restore \
   "$OPENCODE_MEMORY_DATABASE_PATH.backup/<backup>.manifest.json"
 ```
 
@@ -71,7 +71,7 @@ Compare `targetPath`, `sourceSchema`, `targetSchema`, row counts, size, and
 SHA-256 with the recorded backup. Then use the exact manifest hash:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin restore \
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin restore \
   "$OPENCODE_MEMORY_DATABASE_PATH.backup/<backup>.manifest.json" \
   --sha256 <manifest-database-sha256> \
   --confirm RESTORE_DATABASE_FROM_VERIFIED_BACKUP
@@ -84,9 +84,9 @@ database passes all checks.
 ## Post-Restore Validation
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin doctor
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin capture status
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin outbox status
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin capture status
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin outbox status
 ```
 
 Start only the MCP server and perform read-only `project_list`, `memory_recall`,
@@ -104,7 +104,7 @@ style error first if uncertain. Break only a proven stale lock with the exact
 owner ID and confirmation:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin unlock \
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin unlock \
   --owner <owner-id> \
   --confirm BREAK_STALE_MIGRATION_LOCK
 ```
@@ -118,13 +118,13 @@ The first command is non-destructive and returns a digest over the exact backup
 set:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin backup prune
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup prune
 ```
 
 Review every listed manifest/database pair. Delete only that unchanged set:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin backup prune \
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup prune \
   --digest <dry-run-digest> \
   --confirm DELETE_VERIFIED_BACKUPS
 ```

package/docs/backup-restore-runbook.tr.md

@@ -2,7 +2,7 @@
 
 [English](backup-restore-runbook.md) | Türkçe
 
-Bu runbook `@vaur94/agz-memory@0.4.0` ve SQLite schema v10 için geçerlidir.
+Bu runbook `@vaur94/agz-memory@0.4.1` ve SQLite schema v10 için geçerlidir.
 
 ## Ön Koşullar
 
@@ -25,16 +25,16 @@ Tahmin edilmiş veya boş bir yolla devam etmeyin.
 Önce salt-okunur sağlık raporu alın:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
 ```
 
 `ok` değeri `true` olmalıdır. `schemaVersion`, satır sayıları ve değişmez kural
 sayılarını kaydedin. Sonra bağımsız doğrulanmış yedek oluşturup yükseltin:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin backup
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin upgrade --to 10
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin upgrade --to 10
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
 ```
 
 Veritabanı v10'dan eskiyse yükseltme ayrıca değişiklikten önce doğrulanmış yedek
@@ -54,16 +54,16 @@ Manifest formatı `agz-memory-backup/1` olur. `agz-memory-admin restore`, manife
 ile veritabanının aynı yedek dizinindeki normal dosyalar olduğunu doğrular;
 ardından boyut, SHA-256, SQLite bütünlüğü, foreign key ve satır sayılarını denetler.
 
-Final `0.4.0` ön sürüm manifest formatlarını kabul etmez. Böyle bir yedeği onu
+Final `0.4.1` ön sürüm manifest formatlarını kabul etmez. Böyle bir yedeği onu
 oluşturan ön sürümle geri yükleyin, o sürümün doctor kontrolünü çalıştırın ve
-yalnız bundan sonra geri yüklenen veritabanını `0.4.0` ile yükseltin.
+yalnız bundan sonra geri yüklenen veritabanını `0.4.1` ile yükseltin.
 
 ## Geri Yükleme Provası
 
 Tüm yazıcıları kapalı tutun. Önce onay vermeden deneme yapın:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin restore \
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin restore \
   "$OPENCODE_MEMORY_DATABASE_PATH.backup/<backup>.manifest.json"
 ```
 
@@ -71,7 +71,7 @@ bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin restore \
 değerlerini kaydedilen yedekle karşılaştırın. Sonra tam manifest özetini kullanın:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin restore \
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin restore \
   "$OPENCODE_MEMORY_DATABASE_PATH.backup/<backup>.manifest.json" \
   --sha256 <manifest-database-sha256> \
   --confirm RESTORE_DATABASE_FROM_VERIFIED_BACKUP
@@ -84,9 +84,9 @@ veritabanı tüm kontrollerden geçmeden bunu silmeyin.
 ## Geri Yükleme Sonrası Doğrulama
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin doctor
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin capture status
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin outbox status
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin capture status
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin outbox status
 ```
 
 Yalnız MCP sunucusunu başlatın ve salt-okunur `project_list`, `memory_recall` ve
@@ -103,7 +103,7 @@ Sahip dosyasındaki PID, makine ve başlangıç zamanını doğrulayın. Yalnız
 kanıtlanan kilidi tam sahip ID'si ve onayla kırın:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin unlock \
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin unlock \
   --owner <owner-id> \
   --confirm BREAK_STALE_MIGRATION_LOCK
 ```
@@ -116,14 +116,14 @@ kanıtıdır; veritabanı doğrulamasını atlama izni değildir.
 İlk komut silme yapmaz ve tam yedek kümesinin özetini döndürür:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin backup prune
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup prune
 ```
 
 Listelenen her manifest/veritabanı çiftini inceleyin. Yalnız değişmemiş kümeyi
 silin:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.0 agz-memory-admin backup prune \
+bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup prune \
   --digest <dry-run-digest> \
   --confirm DELETE_VERIFIED_BACKUPS
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaur94/agz-memory",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Project-scoped persistent linked memory MCP server for OpenCode V2",
   "type": "module",
   "main": "./dist/server.js",