feat: add migration system with error handling, validation, and enterprise hardening

- MigrationRunner: per-entity error tracking (non-fatal), maxErrors bail-out,
  static validateMigrations() called in constructor, branch error propagation
- RefManager: updateRefMetadata() method for clean metadata updates
- brainy.ts: eliminate as-any casts in migration methods, use updateRefMetadata,
  forward maxErrors through full chain including branch migrations
- Types: MigrationError interface, errors field on MigrationResult, maxErrors on MigrateOptions
- Package exports: MigrationError type, migrate() on BrainyInterface, autoMigrate config
- 31 integration tests covering error handling, validation, branch error propagation
- Documentation: docs/guides/schema-migrations.md

src/types/brainy.types.ts

@@ -837,6 +837,11 @@ export interface BrainyConfig {
   // - false/undefined: Disable integrations (default)
   // - IntegrationsConfig: Custom configuration
   integrations?: boolean | IntegrationsConfig
+
+  // Migration configuration
+  // - false/undefined (default): Log warning if pending migrations exist, but don't auto-run
+  // - true: Automatically run pending migrations during init() for small datasets (<10K entities)
+  autoMigrate?: boolean
 }
 
 // ============= Neural API Types =============

src/types/brainyInterface.ts

@@ -10,6 +10,7 @@
 import { Vector } from '../coreTypes.js'
 import { AddParams, RelateParams, Result, Entity, FindParams, SimilarParams } from './brainy.types.js'
 import { NounType, VerbType } from './graphTypes.js'
+import type { MigrationPreview, MigrationResult, MigrateOptions } from '../migration/types.js'
 
 export interface BrainyInterface<T = unknown> {
   /**
@@ -159,4 +160,23 @@ export interface BrainyInterface<T = unknown> {
     entities: Entity<any>[]
     centroid?: number[]
   }>>
+
+  /**
+   * Run pending data migrations, or preview what would change.
+   *
+   * @param options - Pass { dryRun: true } to preview without writing
+   * @returns Migration result or preview depending on options
+   *
+   * @example
+   * ```typescript
+   * // Preview
+   * const preview = await brain.migrate({ dryRun: true })
+   * console.log(preview.affectedEntities)
+   *
+   * // Apply
+   * const result = await brain.migrate()
+   * console.log(result.backupBranch) // 'pre-migration-7.17.0'
+   * ```
+   */
+  migrate(options?: MigrateOptions): Promise<MigrationResult | MigrationPreview>
 }