fix(ai): flag empty-parity backups as not a healthy pass (#14048) (#14049)

* fix(ai): flag empty-parity backups as not a healthy pass (#14048)

verifyBundleIntegrity reported status:'pass' whenever bundleCount === sourceCount,
including when both are zero. A backup of a gutted store — the #13999 signature, where
the source was already emptied so the export returns 0 and the bundle is 0 — therefore
passed as healthy, indistinguishable from a real backup. An all-empty 'passing' backup
is a false recovery source, the exact trust gap the backup substrate must close.

Distinguish status:'empty' (source === bundle === 0) from a healthy 'pass' (N === N,
N > 0). runBackup surfaces empty subsystems with a loud, non-fatal warning (a fresh
environment legitimately backs up empty subsystems) and the 'empty' status is carried in
bundle-meta.integrity so a downstream canary/alert can escalate.

(block-alignment --fix also corrected pre-existing import over-padding in the touched file.)

* fix(ai): document empty integrity status + prove runBackup propagation (#14048)

Addresses the #14049 review:
- Contract doc: verifyBundleIntegrity's JSDoc (body + @returns) now documents the
  'empty' status (zero-zero parity, non-fatal, not a usable recovery source)
  alongside pass/fail/skipped — the previously-stale return contract.
- Propagation proof: a new test drives runBackup with an empty MC subsystem and
  asserts status:'empty' is persisted into bundle-meta.integrity AND a non-fatal
  warning fires — proving the canary/alert handoff, not just the helper branch.

Contract impact verified: no current consumer switches on bundle-meta.integrity[].status
(restore.mjs runs its own validation + reads topology/version; HealthService reads only
completedAt/timestamp). 'empty' is additive; the intended consumer is the future canary.

Author: neo-opus-vega

ai/scripts/maintenance/backup.mjs

@@ -1,19 +1,19 @@
-import {execFile}       from 'child_process';
-import fs               from 'fs-extra';
-import path             from 'path';
-import {promisify}      from 'util';
-import {fileURLToPath}  from 'url';
+import {execFile}      from 'child_process';
+import fs              from 'fs-extra';
+import path            from 'path';
+import {promisify}     from 'util';
+import {fileURLToPath} from 'url';
 
 // Neo namespace bootstrap (entry-point invariant) for the operator-runnable backup driver.
 // `Neo` + `core/_export` populate
 // `globalThis.Neo`; `InstanceManager` binds Neo.find/findFirst/get aliases +
 // consumes pre-singleton `Neo.idMap`.
-import Neo              from '../../../src/Neo.mjs';
-import * as core        from '../../../src/core/_export.mjs';
-import InstanceManager  from '../../../src/manager/Instance.mjs';
-import AiConfig         from '../../config.mjs';
-import kbConfig         from '../../mcp/server/knowledge-base/config.mjs';
-import mcConfig         from '../../mcp/server/memory-core/config.mjs';
+import Neo             from '../../../src/Neo.mjs';
+import * as core       from '../../../src/core/_export.mjs';
+import InstanceManager from '../../../src/manager/Instance.mjs';
+import AiConfig        from '../../config.mjs';
+import kbConfig        from '../../mcp/server/knowledge-base/config.mjs';
+import mcConfig        from '../../mcp/server/memory-core/config.mjs';
 
 import {
     KB_DatabaseService,
@@ -157,7 +157,7 @@ export async function runBackup({
     sentToCullSourceFile   = DEFAULT_SENT_TO_CULL_FILE,
     logger                 = console
 } = {}) {
-    const timestamp    = new Date().toISOString().replace(/:/g, '-');
+    const timestamp = new Date().toISOString().replace(/:/g, '-');
     const resolvedRoot = bundleRoot ?? path.join(DEFAULT_BACKUP_ROOT, `backup-${timestamp}`);
 
     const layout = {
@@ -214,7 +214,7 @@ export async function runBackup({
     await cleanOldBackups(DEFAULT_BACKUP_ROOT, logger, resolveBackupRetention());
 
     logger.log('Verifying bundle integrity (row-count parity)...');
-    const integrity = await verifyBundleIntegrity(layout, subsystems);
+    const integrity    = await verifyBundleIntegrity(layout, subsystems);
     const failedChecks = integrity.filter(check => check.status === 'fail');
     if (failedChecks.length > 0) {
         throw new Error(
@@ -223,10 +223,23 @@ export async function runBackup({
         );
     }
 
+    const emptyChecks = integrity.filter(check => check.status === 'empty');
+    if (emptyChecks.length > 0) {
+        // Non-fatal (a fresh environment legitimately backs up empty subsystems), but loud: a zero-row
+        // export from a normally-populated deployment is the gutted-store signature, and a backup of an
+        // empty store is a false recovery source. The 'empty' status is carried in bundle-meta.integrity
+        // for a downstream canary/alert to escalate on.
+        logger.warn?.(
+            `[Backup] ${emptyChecks.length} subsystem(s) exported ZERO rows — empty backup is not a usable ` +
+            `recovery source: ${emptyChecks.map(c => c.subsystem).join(', ')}. Legitimate for a fresh ` +
+            `environment; corruption-suspicious for a populated deployment.`
+        );
+    }
+
     const completedAt = new Date().toISOString();
     const topology    = buildTopologyDescriptor();
     const versionInfo = await buildVersionDescriptor(PROJECT_ROOT, logger);
-    const meta = {
+    const meta        = {
         bundleVersion: 1,
         timestamp,
         completedAt,
@@ -246,15 +259,19 @@ export async function runBackup({
  * bundle. For subsystems whose `manageDatabaseBackup({action: 'export'})` SDK call returns a
  * numeric count (KB, MC memories+summaries, MC graph), this function counts non-empty lines
  * in the bundle's JSONL files and compares — mismatch indicates a partial/torn write that the
- * caller treats as a fail-the-bundle condition.
+ * caller treats as a fail-the-bundle condition. Zero-zero parity (source and bundle both empty) is
+ * reported as `empty`, not `pass`: a backup of an empty/gutted store is surfaced non-fatally because
+ * it is not a usable recovery source (a fresh environment is legitimately empty; a populated
+ * deployment reporting zero rows is the gutted-store signature). `runBackup` warns on `empty`
+ * subsystems and persists the status into `bundle-meta.integrity` for a downstream canary/alert.
  *
  * For file-copy subsystems (concepts, trajectories, mailbox) the source side has no
  * authoritative count to compare against — `copyJsonlSource`'s reported `copied` field
  * already covers the file-presence check, so these are skipped with `status: 'skipped'`.
  *
  * @param {Object} layout     The bundle's per-subsystem destination directory map.
  * @param {Object} subsystems The runBackup `subsystems` map of SDK return values.
- * @returns {Promise<Array<{subsystem: String, status: String, sourceCount: Number, bundleCount: Number, reason: String}>>} `status` is `pass` / `fail` / `skipped`; count + reason fields present per status.
+ * @returns {Promise<Array<{subsystem: String, status: String, sourceCount: Number, bundleCount: Number, reason: String}>>} `status` is `pass` (positive row-count parity) / `empty` (source and bundle both zero — non-fatal, not a usable recovery source) / `fail` (row-count mismatch) / `skipped` (non-numeric source count); count + reason fields present per status.
  */
 export async function verifyBundleIntegrity(layout, subsystems) {
     const verifiable = ['kb', 'mc', 'graph'];
@@ -276,16 +293,29 @@ export async function verifyBundleIntegrity(layout, subsystems) {
             continue;
         }
 
-        const files = (await fs.readdir(dir)).filter(f => f.endsWith('.jsonl'));
-        let bundleCount = 0;
+        const files       = (await fs.readdir(dir)).filter(f => f.endsWith('.jsonl'));
+        let   bundleCount = 0;
 
         for (const file of files) {
             const content = await fs.readFile(path.join(dir, file), 'utf8');
             bundleCount += content.split('\n').filter(line => line.trim()).length;
         }
 
         if (bundleCount === sourceCount) {
-            checks.push({subsystem, status: 'pass', sourceCount, bundleCount});
+            // Empty-parity is NOT a healthy pass: a backup whose source AND bundle are both empty is
+            // not a usable recovery source. Legitimate for a fresh environment, but for a normally-
+            // populated deployment a zero-row export is the gutted-store signature (the corruption a
+            // backup is supposed to survive) — surface it as 'empty' (visible, non-fatal) rather than
+            // a silent 'pass' so a downstream canary/alert can act on bundle-meta.integrity.
+            const status = sourceCount === 0 ? 'empty' : 'pass';
+            const entry  = {subsystem, status, sourceCount, bundleCount};
+
+            if (status === 'empty') {
+                entry.reason = 'source and bundle both report zero rows — empty backup is not a usable ' +
+                    'recovery source (fresh-env legitimate; populated-deployment corruption-suspicious)';
+            }
+
+            checks.push(entry);
         } else {
             checks.push({
                 subsystem,
@@ -314,7 +344,7 @@ export async function verifyBundleIntegrity(layout, subsystems) {
 function buildTopologyDescriptor() {
     return {
         shared_topology: true,
-        kbChromaCoords: {
+        kbChromaCoords : {
             host: kbConfig.host    ?? null,
             port: kbConfig.port    ?? null,
             path: kbConfig.path    ?? null
@@ -396,9 +426,9 @@ export async function cleanOldBackups(backupRoot, logger, retention = {}) {
         const tsMatch = entry.name.match(/^backup-(.+)$/);
         if (!tsMatch) continue;
 
-        const rawTs = tsMatch[1];
+        const rawTs   = tsMatch[1];
         const isoTime = rawTs.replace(/T(\d{2})-(\d{2})-(\d{2})/, 'T$1:$2:$3');
-        const date = new Date(isoTime);
+        const date    = new Date(isoTime);
 
         if (!isNaN(date.getTime())) {
             backups.push({
@@ -412,16 +442,16 @@ export async function cleanOldBackups(backupRoot, logger, retention = {}) {
 
     backups.sort((a, b) => b.time - a.time);
 
-    const K = keepMinimum;
-    const N_DAYS = maxDays;
-    const now = Date.now();
+    const K           = keepMinimum;
+    const N_DAYS      = maxDays;
+    const now         = Date.now();
     const thresholdMs = N_DAYS * 24 * 60 * 60 * 1000;
 
     let deletedCount = 0;
 
     for (let i = K; i < backups.length; i++) {
         const backup = backups[i];
-        const ageMs = now - backup.time;
+        const ageMs  = now - backup.time;
         if (ageMs > thresholdMs) {
             try {
                 logger.log(`[Retention] Deleting old backup: ${backup.name} (age: ${Math.round(ageMs / 86400000)} days)`);

test/playwright/unit/ai/scripts/maintenance/backup.spec.mjs

@@ -144,7 +144,7 @@ test.describe('backup.mjs orchestrator — atomic bundle assembly (#10129 Phase
     });
 
     test('reports missing concept/trajectory sources as non-fatal notes', async () => {
-        const silentLogger = {log: () => {}, error: () => {}};
+        const silentLogger  = {log: () => {}, error: () => {}};
         const altBundleRoot = path.join(workRoot, 'bundle-no-optional-sources');
 
         const result = await runBackup({
@@ -275,4 +275,58 @@ test.describe('backup.mjs orchestrator — atomic bundle assembly (#10129 Phase
         expect(mc.status).toBe('skipped');
         expect(mc.reason).toMatch(/no numeric source count/);
     });
+
+    test('verifyBundleIntegrity: empty (not a silent pass) when source and bundle are both zero (#14030)', async () => {
+        const tempRoot = path.join(workRoot, 'integrity-empty');
+        const kbDir    = path.join(tempRoot, 'kb');
+
+        fs.mkdirSync(kbDir, {recursive: true});
+        // The gutted-store signature: a populated deployment whose export came back empty. Both
+        // sides agree at zero, so the old `bundleCount === sourceCount` branch reported 'pass' —
+        // a false recovery source. It must surface as 'empty', never 'pass'.
+        fs.writeFileSync(path.join(kbDir, 'kb-data.jsonl'), '');
+
+        const checks = await verifyBundleIntegrity(
+            {kb: kbDir, mc: path.join(tempRoot, 'mc-missing'), graph: path.join(tempRoot, 'graph-missing')},
+            {kb: 0}
+        );
+
+        const kb = checks.find(c => c.subsystem === 'kb');
+        expect(kb.status).toBe('empty');
+        expect(kb.status).not.toBe('pass');
+        expect(kb.sourceCount).toBe(0);
+        expect(kb.bundleCount).toBe(0);
+        expect(kb.reason).toMatch(/not a usable recovery source/);
+    });
+
+    test('runBackup propagates an empty subsystem to bundle-meta.integrity "empty" + a non-fatal warning (#14048)', async () => {
+        // Close-target proof: the helper status alone is not enough — runBackup must keep an empty
+        // subsystem non-fatal, WARN, and persist `empty` into bundle-meta.integrity (the canary/alert
+        // handoff). Force MC (memories + summaries) to export zero rows.
+        const warnings      = [];
+        const captureLogger = {log: () => {}, error: () => {}, warn: msg => warnings.push(msg)};
+        const savedMem      = Memory_StorageRouter.getMemoryCollection;
+        const savedSum      = Memory_StorageRouter.getSummaryCollection;
+
+        try {
+            Memory_StorageRouter.getMemoryCollection  = async () => fakeCollection([], 'empty-mem');
+            Memory_StorageRouter.getSummaryCollection = async () => fakeCollection([], 'empty-sum');
+
+            const result = await runBackup({
+                bundleRoot: path.join(workRoot, 'bundle-empty-subsystem'),
+                conceptsSourceDir,
+                trajectoriesSourceFile,
+                logger    : captureLogger
+            });
+
+            const mcIntegrity = result.meta.integrity.find(check => check.subsystem === 'mc');
+            expect(mcIntegrity.status).toBe('empty');           // persisted into bundle-meta.integrity
+            expect(mcIntegrity.sourceCount).toBe(0);
+            expect(mcIntegrity.bundleCount).toBe(0);
+            expect(warnings.some(w => /ZERO rows|empty backup/i.test(w))).toBe(true);  // runBackup warned, non-fatally
+        } finally {
+            Memory_StorageRouter.getMemoryCollection  = savedMem;
+            Memory_StorageRouter.getSummaryCollection = savedSum;
+        }
+    });
 });