feat(pi-hermes-memory): 导入上游 v0.9.10 源码快照

从官方 Git 仓库导入 chandra447/pi-hermes-memory 在 tag v0.9.10 （df624056a2e8c68bc89ba0a81e1c120856ec9665，2026-10-02）的源码快照。本次仅导入源码，尚未接入组合包：package.json、加载顺序、依赖与权限策略均未改动。 - 原样导入 src/、tests/、docs/、scripts/、README、CHANGELOG、PLAN、 AGENTS 与 LICENSE；该快照共 156 个上游文件。 - 剔除嵌套 .git、上游 .github 工作流、.ralph/、.claude/、node_modules、覆盖率与构建产物。 - 新增中文 UPSTREAM.md，记录来源，以及启用前必须完成的待决事项：在 pi-compaction 之前注册加载顺序、better-sqlite3 版本与根 allowScripts 对齐、strip-ansi 解析确认。 - 说明选择 tag 而非 main 的原因：导入时上游 main 已领先至 24fcd8ad26fc27badb8d7dbaf8034645de07b893（2026-10-11），选 tag 是为对应一个已发布、可复现的版本。尚未接线。启用前还需反转 tests/extension-load.test.ts 中"不得加载 Hermes"的断言，并同步 pi-tool-search 分组、权限策略与文档。验证：快照 156 个上游文件全部导入，目录内仅多出 UPSTREAM.md 一份；已确认与上游 main 内容存在差异，证明取的是 tag 而非 main。
2026-10-26 10:45:22 +00:00 · 2026-10-13 23:19:35 -07:00
parent 879fc5d37f
commit 312bb2ba5a
157 changed files with 52287 additions and 0 deletions
@@ -0,0 +1,112 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { DatabaseManager } from '../../src/store/db.js';
+import { isFts5QueryError } from '../../src/store/fts-query.js';
+import { reconcileMarkdownMemoryScope } from '../../src/store/sqlite-memory-store.js';
+
+/**
+ * Behavior change under test (PR #184): reconcileMarkdownMemoryScope now
+ * runs its persistence inside DatabaseManager.withCorruptionRecovery().
+ * Before this change, corruption errors ("database disk image is malformed",
+ * SQLITE_CORRUPT, SQLITE_NOTADB) thrown during markdown reconciliation
+ * surfaced as raw failures on every memory write — corruption recovery was
+ * only wired into the session-indexing paths, so a corrupt sessions.db kept
+ * failing markdown syncs until repaired by hand. Now the markdown reconcile
+ * path participates in the same recovery: the corrupt database is
+ * quarantined, rebuilt, and the reconcile is retried on a fresh handle, so
+ * the memory entry is persisted instead of lost.
+ *
+ * The FTS5 soft fallback stays narrow: only genuine FTS query/index errors
+ * (isFts5QueryError) degrade to a warned, repair-guided result. Corruption
+ * signals never match that classifier, so they can never be swallowed into a
+ * zero-count success here.
+ */
+describe('Corruption recovery during markdown sync', () => {
+  it('keeps corruption signals out of the FTS5 fallback classifier', () => {
+    // Corruption/recovery signals must propagate so DatabaseManager can
+    // quarantine + rebuild, not be swallowed by the search-index fallback.
+    assert.equal(isFts5QueryError(new Error('database disk image is malformed')), false);
+    assert.equal(isFts5QueryError(new Error('SQL logic error')), false);
+    assert.equal(isFts5QueryError(new Error('file is not a database')), false);
+    // Genuine FTS5 query/index errors remain recoverable search-path failures.
+    assert.equal(isFts5QueryError(new Error('fts5: syntax error near "AND"')), true);
+    assert.equal(isFts5QueryError(new Error('fts5: unterminated string')), true);
+  });
+
+  it('withCorruptionRecovery quarantines a corrupt DB, rebuilds, and persists the entry', async () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-corruption-'));
+    const dbManager = new DatabaseManager(tmpDir);
+    const dbFile = path.join(tmpDir, 'sessions.db');
+
+    try {
+      // 1. Prime a healthy database with one memory.
+      const first = reconcileMarkdownMemoryScope(dbManager, ['first healthy entry'], 'memory', null);
+      assert.equal(first.inserted, 1);
+      await dbManager.waitForStartupIntegrityScan();
+
+      // 2. Close the handle and corrupt the DB file on disk.
+      dbManager.close();
+      fs.writeFileSync(dbFile, 'GARBAGE-NOT-A-SQLITE-DB'.repeat(32), 'utf-8');
+      assert.equal(isFts5QueryError(new Error('file is not a database')), false);
+
+      // 3. Reconcile a second entry. The corrupt file must be detected,
+      // quarantined, and a fresh database rebuilt — and the entry persisted
+      // on the healthy database instead of being swallowed as a zero-count
+      // "successful" reconcile.
+      const second = reconcileMarkdownMemoryScope(dbManager, ['second entry after corruption'], 'memory', null);
+
+      // 4. Recovery must have run (not a no-op reuse of the corrupt file).
+      const recovery = dbManager.getLastRecovery();
+      assert.ok(recovery, 'expected a corruption recovery to be recorded');
+      assert.notEqual(recovery.strategy, 'reused', 'the corrupt file must not have been reused');
+      assert.ok(recovery.backupPaths.length >= 1, 'the corrupt file must have been quarantined to a backup');
+      for (const backup of recovery.backupPaths) {
+        assert.ok(fs.existsSync(backup), `quarantined backup missing: ${backup}`);
+      }
+
+      // 5. The entry must actually be persisted in the rebuilt database —
+      // a swallowed zero-count success would leave the memory in markdown only.
+      // The rebuild strips copied markdown-scope fingerprints (copyRecoverableRows),
+      // so the retry on the new handle re-mirrors instead of trusting them.
+      assert.ok(second.inserted >= 1, `expected the entry to persist after recovery, got ${JSON.stringify(second)}`);
+      const rows = dbManager.getDb()
+        .prepare('SELECT content FROM memories WHERE target = ? ORDER BY id ASC')
+        .all('memory') as Array<{ content: string }>;
+      assert.ok(
+        rows.some((row) => row.content.includes('second entry after corruption')),
+        'the second entry must be present in the rebuilt database',
+      );
+
+      // 6. The original path must now hold a fresh, healthy database.
+      const header = fs.readFileSync(dbFile).subarray(0, 16).toString('utf-8');
+      assert.equal(header, 'SQLite format 3\x00', 'a fresh SQLite database must exist at the original path');
+
+      // 7. Fingerprint on the rebuilt handle must skip a third identical reconcile.
+      const recoveredDb = dbManager.getDb() as { prepare: (sql: string) => unknown };
+      const originalPrepare = recoveredDb.prepare.bind(recoveredDb);
+      recoveredDb.prepare = (sql: string) => {
+        const normalized = sql.replace(/\s+/g, ' ').trim();
+        if (/^INSERT(?: OR REPLACE)? INTO memories\b/i.test(normalized) || /^UPDATE memories\b/i.test(normalized)) {
+          throw new Error(`unexpected memories write after recovery skip: ${normalized}`);
+        }
+        return originalPrepare(sql);
+      };
+      try {
+        const third = reconcileMarkdownMemoryScope(dbManager, ['second entry after corruption'], 'memory', null);
+        assert.equal(third.inserted, 0);
+        assert.equal(third.existing, 1);
+        assert.equal(third.removed, 0);
+      } finally {
+        recoveredDb.prepare = originalPrepare;
+      }
+    } finally {
+      try { dbManager.close(); } catch { /* best effort */ }
+      // Best-effort: on Windows the shared AtomicLockCoordinator keeps
+      // .pi-hermes-locks.sqlite open, so the directory may not be removable.
+      try { fs.rmSync(tmpDir, { recursive: true, force: true }); } catch { /* OS cleans temp eventually */ }
+    }
+  });
+});