diff --git a/gitnexus/test/unit/basicblock-callee-ids-schema.test.ts b/gitnexus/test/unit/basicblock-callee-ids-schema.test.ts
index b91a7e469..22b170958 100644
--- a/gitnexus/test/unit/basicblock-callee-ids-schema.test.ts
+++ b/gitnexus/test/unit/basicblock-callee-ids-schema.test.ts
@@ -177,6 +177,8 @@ const makeConfigMock = () => {
     resolveNativeSafeStorageDir: (p: string) => p,
     WAL_RECOVERY_SUGGESTION: 'run analyze --force',
     waitForWindowsHandleRelease: vi.fn(async () => true),
+    isStorageVersionMismatchError: vi.fn(() => false),
+    STORAGE_VERSION_MISMATCH_SUGGESTION: '',
   };
   return { mock, queries };
 };
diff --git a/gitnexus/test/unit/convex-metadata-persistence-contract.test.ts b/gitnexus/test/unit/convex-metadata-persistence-contract.test.ts
index 8fd89e820..ed215eedb 100644
--- a/gitnexus/test/unit/convex-metadata-persistence-contract.test.ts
+++ b/gitnexus/test/unit/convex-metadata-persistence-contract.test.ts
@@ -32,6 +32,8 @@ function makeConfigMock() {
       resolveNativeSafeStorageDir: (value: string) => value,
       WAL_RECOVERY_SUGGESTION: 'run analyze --force',
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     },
   };
 }
diff --git a/gitnexus/test/unit/lbug-adapter-wal-schema.test.ts b/gitnexus/test/unit/lbug-adapter-wal-schema.test.ts
index 5822728a8..dde36271f 100644
--- a/gitnexus/test/unit/lbug-adapter-wal-schema.test.ts
+++ b/gitnexus/test/unit/lbug-adapter-wal-schema.test.ts
@@ -147,6 +147,8 @@ describe('doInitLbug WAL corruption guard — behavioural', () => {
       WAL_RECOVERY_SUGGESTION:
         'WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.',
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -199,6 +201,8 @@ describe('doInitLbug WAL corruption guard — behavioural', () => {
       WAL_RECOVERY_SUGGESTION:
         'WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.',
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -260,6 +264,8 @@ describe('doInitLbug WAL corruption guard — behavioural', () => {
       WAL_RECOVERY_SUGGESTION:
         'WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.',
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -312,6 +318,8 @@ describe('doInitLbug WAL corruption guard — behavioural', () => {
       WAL_RECOVERY_SUGGESTION:
         'WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.',
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -389,6 +397,8 @@ describe('doInitLbug WAL corruption guard — behavioural', () => {
       WAL_RECOVERY_SUGGESTION:
         'WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.',
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -470,6 +480,8 @@ describe('doInitLbug WAL corruption guard — behavioural', () => {
       WAL_RECOVERY_SUGGESTION:
         'WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.',
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -524,6 +536,8 @@ describe('doInitLbug WAL corruption guard — behavioural', () => {
       WAL_RECOVERY_SUGGESTION:
         'WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.',
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -646,6 +660,8 @@ describe('Symmetric WAL-size gate during missing-shadow recovery (PR #1747 D2)',
       WAL_RECOVERY_SUGGESTION:
         'WAL corruption detected. Run `gitnexus analyze --force` to rebuild the index.',
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
diff --git a/gitnexus/test/unit/lbug-checkpoint-lifecycle.test.ts b/gitnexus/test/unit/lbug-checkpoint-lifecycle.test.ts
index e06e7445c..63acae912 100644
--- a/gitnexus/test/unit/lbug-checkpoint-lifecycle.test.ts
+++ b/gitnexus/test/unit/lbug-checkpoint-lifecycle.test.ts
@@ -95,6 +95,8 @@ describe('lbug adapter CHECKPOINT lifecycle', () => {
       isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')),
       isOpenRetryExhausted: vi.fn(() => false),
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -167,6 +169,8 @@ describe('lbug adapter CHECKPOINT lifecycle', () => {
       isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')),
       isOpenRetryExhausted: vi.fn(() => false),
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -232,6 +236,8 @@ describe('lbug adapter CHECKPOINT lifecycle', () => {
       isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')),
       isOpenRetryExhausted: vi.fn(() => false),
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -300,6 +306,8 @@ describe('lbug adapter CHECKPOINT lifecycle', () => {
       isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')),
       isOpenRetryExhausted: vi.fn(() => false),
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -359,6 +367,8 @@ describe('lbug adapter CHECKPOINT lifecycle', () => {
       isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')),
       isOpenRetryExhausted: vi.fn(() => false),
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -431,6 +441,8 @@ describe('lbug adapter CHECKPOINT lifecycle', () => {
       isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')),
       isOpenRetryExhausted: vi.fn(() => false),
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -506,6 +518,8 @@ describe('lbug adapter CHECKPOINT lifecycle', () => {
       isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')),
       isOpenRetryExhausted: vi.fn(() => false),
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -565,6 +579,8 @@ describe('lbug adapter CHECKPOINT lifecycle', () => {
       isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')),
       isOpenRetryExhausted: vi.fn(() => false),
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -617,6 +633,8 @@ describe('lbug adapter CHECKPOINT lifecycle', () => {
       isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')),
       isOpenRetryExhausted: vi.fn(() => false),
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -680,6 +698,8 @@ describe('lbug adapter CHECKPOINT lifecycle', () => {
       isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')),
       isOpenRetryExhausted: vi.fn(() => false),
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -758,6 +778,8 @@ describe('lbug adapter CHECKPOINT lifecycle', () => {
       isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')),
       isOpenRetryExhausted: vi.fn(() => false),
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {
@@ -836,6 +858,8 @@ describe('lbug adapter CHECKPOINT lifecycle', () => {
       isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')),
       isOpenRetryExhausted: vi.fn(() => false),
       waitForWindowsHandleRelease: vi.fn(async () => true),
+      isStorageVersionMismatchError: vi.fn(() => false),
+      STORAGE_VERSION_MISMATCH_SUGGESTION: '',
     }));
     vi.doMock('../../src/core/lbug/extension-loader.js', () => ({
       extensionManager: {