Authored by Claude Opus 4.7 (Claude Code). Session 4a038347-e042-49e6-89fc-908a7708df0d.

Resolves #10871

Closes the AC-B half of the backup/restore parity ticket (AC-A shipped via PR #10876). Adds the canonical npm run ai:restore -- <bundle> orchestrator that inverts npm run ai:backup through the SDK boundary, wires the destructive-operation guard (#10845) into MC's previously-TODO replace-mode path, extends KB's DatabaseService with peer-symmetric import + truncate actions, and retires the importBackupToSQLite.mjs legacy one-off that bypassed both the SDK boundary and the substrate guard.

Evidence: L2 (mocked-SDK + real fs writes for the restore orchestrator's flat-file paths; mocked Chroma collections for the KB import + truncate paths via Playwright unit tests) → L3 required (full-flow restore against real KB+MC ChromaDB collections, validation that operator-confirmation token gates production-target replace mode end-to-end). Residual: Section 9 of learn/agentos/MemoryCore.md runbook + AC-B replace-mode integration coverage [#10871] — operator-side L3 verification deferred since this worktree's ChromaDB is shared substrate and live operations would contend with peer worktrees.

What ships

Slot Rationale (substrate-mutation gate)

Substrate-mutation gate fires for the learn/agentos/MemoryCore.md addition.

• Added section: H2 "Backup and Restore from Atomic Bundle" inserted between "Internals: Text Embeddings & ChromaDB" and "Configuration".
  • Disposition: keep (not compress-to-trigger) — operator runbook content; readers consult linearly when invoking the orchestrator. Trigger-frequency × failure-severity × enforceability: high × severe × disciplinary.
  • Decay-mitigation rationale: Stale runbook inducement risk is bounded by AC-B's same-PR coupling — the runbook lands with the orchestrator that documents it. Future evolution (e.g., --mode dry-run or per-subsystem partial restore) extends the runbook as a co-modification, not a separate doc-only PR.

Architectural guarantees

• Pre-flight integrity validation BEFORE any write. The bundle is fully validated (5 required subdirs, JSONL parseable, bundle-meta.json parsed if present) before any service write fires. A torn / partial bundle aborts with zero side effects on the live substrate.
• Topology compatibility check. bundle-meta.topology.chromaUnified vs current mcConfig.chromaUnified divergence is refused unless --force-topology-mismatch. Legacy bundles without metadata skip with a console warning (warn-and-degrade).
• Two-mode contract:
  • --mode merge (default): idempotent. Embedded substrates upsert (KB chunks, MC memories+summaries+graph). Flat substrates skip-if-target-non-empty (preserves operator additions). No --force required.
  • --mode replace: destructive. Each embedded subsystem fires assertDestructiveTargetAllowed() (#10845) before truncating + restoring. Flat substrates fire the guard against the target file/dir before overwriting. Refuses if any target is non-empty without --force.
• Canonical SDK boundary only. restore.mjs never reaches into SQLiteVectorManager, ChromaManager, or any other manager directly. All embedded-substrate writes go through KB_DatabaseService.manageDatabaseBackup and Memory_DatabaseService.manageDatabaseBackup so the destructive-operation guard fires uniformly per the AC-B "no SQLiteVectorManager direct" mandate.

Acceptance Criteria

AC-B (new restore) — full coverage:

• npm run ai:restore -- <bundle> registered in package.json
• buildScripts/ai/restore.mjs invokes canonical SDK methods exclusively (no SQLiteVectorManager direct)
• Pre-flight integrity validation: 5 required subdirs, JSONL parseable, bundle-meta.json parsed if present
• Topology mismatch warning + refusal-without---force-topology-mismatch
• Default --mode merge works idempotently (test: happy-path merge)
• --mode replace calls assertDestructiveTargetAllowed(...) from #10845 guard (test: replace mode with --force fires guard for flat substrates)
• Refuse non-empty target without --force (test: replace mode without --force refuses non-empty target)
• importBackupToSQLite.mjs retired (deleted)
• Restore-runbook documented in learn/agentos/MemoryCore.md (new "Backup and Restore from Atomic Bundle" section)
• Playwright unit tests: happy-path merge, integrity-failure refusal, topology-mismatch refusal + bypass, force-flag bypass, replace-mode guard call, merge-preserve-existing, legacy-bundle path, malformed JSONL, parseArgs edge cases, validateBundle reuse — 11 tests, all pass at the new spec location.

Deltas from ticket (extension)

• MC importDatabase replace-mode wire-up. The ticket flagged this as --mode replace should fire the guard, but the existing MC code had a TODO that just logged a message. Wired it to call truncateDatabase({include}) over only the subsystems whose files appear in the import scan — so a memory-only restore doesn't accidentally wipe graph, and vice versa. Restore.mjs's mode-replace SDK calls now correctly trigger the guard per subsystem. Strictly improves AC-B's "guard fires" guarantee.
• KB manageDatabaseBackup({action: 'truncate'}) dispatcher entry. The AC-B prescription only required 'import'. Adding 'truncate' peer-symmetrically with MC's surface keeps the dispatcher contract uniform across KB and MC and lets future operator tooling truncate KB without re-implementing the guard wiring.
• Spec relocated to right-hemisphere unit-test root. Per operator architectural guidance during Cycle 1 review: the new restore.spec.mjs lives at test/playwright/unit/ai/buildScripts/restore.spec.mjs (right-hemisphere pillar), not test/playwright/unit/buildScripts/ai/restore.spec.mjs (source-mirror). Path depth is identical (4 levels under test/), so relative imports are unchanged. Sibling-spec symmetric relocation (backup.spec.mjs, peer-architecture.spec.mjs, runSandman.spec.mjs) tracked as #10889 to keep this PR scoped to AC-B.

Test Evidence

npm run test-unit -- test/playwright/unit/ai/buildScripts/restore.spec.mjs
  11 passed (731ms)

npm run test-unit -- \
    test/playwright/unit/ai/mcp/server/knowledge-base/services/DatabaseService.backup.spec.mjs \
    test/playwright/unit/ai/mcp/server/memory-core/services/DatabaseService.backupPath.spec.mjs \
    test/playwright/unit/buildScripts/ai/backup.spec.mjs
  11 passed (911ms)

Total: 22 related tests pass. Zero regressions on adjacent KB+MC backup tests after the substrate extension. The KB backup test's "rejects 'import'" assertion was updated to assert against 'frobnicate' (clearly-unsupported action) since 'import' is now a valid dispatcher entry.

Post-Merge Validation

• L3 verification: run npm run ai:backup, then npm run ai:restore -- <bundle> against a real local Chroma + SQLite stack with a populated MC; confirm row counts match across bundle-meta.integrity and the restored collections.
• Production-bypass exercise: confirm --mode replace against .neo-ai-data/ paths is rejected by the destructive-op guard without NEO_ALLOW_PRODUCTION_DESTRUCTIVE_AI_SUBSTRATE=true AND the explicit confirmation token.
• Topology-mismatch exercise: take a bundle on a federated topology, switch to unified, attempt restore — verify the refusal fires AND --force-topology-mismatch lets it proceed with a warning.

Commits (multi-commit)

• 7e1896651 — feat(ai/mcp): add KB import/truncate + wire MC replace-mode guard (#10871)
• 44d422b35 — feat(ai/restore): bundle-aware restore orchestrator + npm run ai:restore (#10871)
• d08296fe4 — chore(ai): retire importBackupToSQLite legacy one-off (#10871)
• 28625d0de — docs(agentos): add Backup-and-Restore runbook to MemoryCore guide (#10871)
• 6cd013997 — refactor(test): relocate restore spec to right-hemisphere unit-test root (#10871)

Cross-family review routing

Per pull-request-workflow §6.2 round-robin: previous review of one of mine was @neo-gpt on PR #10879 (env-var fixture follow-up). Routing this PR to @neo-gemini-pro as primary reviewer.