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/storage/cow/RefManager.ts

@@ -433,6 +433,22 @@ export class RefManager {
     await this.setRef(name, newCommitHash, options)
   }
 
+  /**
+   * Update metadata on an existing ref (merge semantics).
+   *
+   * @param name - Reference name
+   * @param metadata - Metadata fields to merge into the ref
+   */
+  async updateRefMetadata(name: string, metadata: Record<string, unknown>): Promise<void> {
+    const fullName = this.normalizeRefName(name)
+    const ref = await this.getRef(fullName)
+    if (!ref) throw new Error(`Ref not found: ${fullName}`)
+    ref.metadata = { ...ref.metadata, ...metadata }
+    ref.updatedAt = Date.now()
+    await this.adapter.put(`ref:${fullName}`, Buffer.from(JSON.stringify(ref)))
+    this.cache.set(fullName, ref)
+  }
+
   /**
    * Get commit hash for reference
    *