refactor(migration): 回填 Migration Phase Strategy 體系（PR-D）

A v3.0.1 把 orchestrator 的 11 個 phase 抽成可注入的 Phase 物件，B 仍是
1107 行單體、以 'phase_' . $current 字串魔法分派、completed 甚至 inline
在 tick() 裡。本 commit 對齊：

新增 13 檔
- includes/migration/interface-migration-phase.php
- includes/migration/class-tmdo-migration-phase-base.php（log/get_managed_keys/
  execute_bulk_pivot/values_loose_equal 等共用 helper）
- includes/migration/phases/ 11 個 phase 類別

orchestrator 1107 → 640 行
- tick() 改 make_phase() 工廠 + $phase->execute($job)
- 移除 final、self::ENTITY_TYPE → static::（A v3.3.0 late static binding）
- 保留 B 原有的 '✓ %s (%.2fs)' 耗時 log（改為 tick 自行量測，A 版已簡化掉）
- 公開介面（preflight/start/tick/get_status/cancel/resume/needs_attention/
  cron_tick）經 diff 確認與 A 完全一致，呼叫端零影響

連帶
- Schema_Manager 補 table_exists 的 request-scoped cache 與
  flush_table_exists_cache()（A v3.1.6 + v3.4.6），Phase 測試需要它
- back-compat 補 12 個 Phase 類別的 WPDO_ alias
- 移植 MigrationPhaseTest + MigrationPhaseRemainingTest（527 行）

測試隔離差異（B 的 unit bootstrap 會載入 Member_Fields / Post_Fields，
A 的不會）：MigrationPhaseRemainingTest 的 setUp 需額外清空 Entity_Registry
與 wpdo_register_entity_fields listener，否則 install_schema 會真的走進
dbDelta。MigrationPhaseTest 的 interface 斷言改用 TMDO_ 正式名稱
（PHP 無法 class_alias 介面，且該契約是核心內部擴充點）。

unit 451 / integration 398 GREEN

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TbG1keQQ7XBa7qMQY16KCY

2meet-data-optimizer.php

@@ -236,6 +236,19 @@ require_once TMDO_PATH . 'includes/engine/class-tmdo-schema-manager.php';
 require_once TMDO_PATH . 'includes/engine/class-tmdo-entity-registry.php';
 require_once TMDO_PATH . 'includes/engine/class-tmdo-entity-migration-engine.php';
 require_once TMDO_PATH . 'includes/engine/class-tmdo-entity-health.php';
+require_once TMDO_PATH . 'includes/migration/interface-migration-phase.php';
+require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-phase-base.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-diagnose.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backup.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-demote.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-install-schema.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-bulk.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-unserialize.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-shadow.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-verify-sample.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-aeav.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-cleanup.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-completed.php';
 require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-orchestrator.php';
 require_once TMDO_PATH . 'includes/migration/class-tmdo-post-migration.php';
 add_action( TMDO_Migration_Orchestrator::CRON_HOOK, array( 'TMDO_Migration_Orchestrator', 'cron_tick' ) );

includes/class-tmdo-back-compat.php

@@ -113,6 +113,18 @@ $tmdo_class_aliases = array(
 	'TMDO_Zone_Cold'                  => 'WPDO_Zone_Cold',
 	'TMDO_Zone_Router'                => 'WPDO_Zone_Router',
 	'TMDO_Routing_Predicate'          => 'WPDO_Routing_Predicate',
+	'TMDO_Migration_Phase_Base'       => 'WPDO_Migration_Phase_Base',
+	'TMDO_Phase_Diagnose'             => 'WPDO_Phase_Diagnose',
+	'TMDO_Phase_Backup'               => 'WPDO_Phase_Backup',
+	'TMDO_Phase_Demote'               => 'WPDO_Phase_Demote',
+	'TMDO_Phase_Install_Schema'       => 'WPDO_Phase_Install_Schema',
+	'TMDO_Phase_Backfill_Bulk'        => 'WPDO_Phase_Backfill_Bulk',
+	'TMDO_Phase_Backfill_Unserialize' => 'WPDO_Phase_Backfill_Unserialize',
+	'TMDO_Phase_Promote_Shadow'       => 'WPDO_Phase_Promote_Shadow',
+	'TMDO_Phase_Verify_Sample'        => 'WPDO_Phase_Verify_Sample',
+	'TMDO_Phase_Promote_Aeav'         => 'WPDO_Phase_Promote_Aeav',
+	'TMDO_Phase_Cleanup'              => 'WPDO_Phase_Cleanup',
+	'TMDO_Phase_Completed'            => 'WPDO_Phase_Completed',
 	'TMDO_Zone_Archive'               => 'WPDO_Zone_Archive',
 	'TMDO_Interceptor_Base'           => 'WPDO_Interceptor_Base',
 	'TMDO_Query_Interceptor_Base'     => 'WPDO_Query_Interceptor_Base',

includes/engine/class-tmdo-schema-manager.php

@@ -18,6 +18,9 @@ defined( 'ABSPATH' ) || exit;
 
 final class TMDO_Schema_Manager {
 
+	/** Request-scoped cache for table_exists() — prevents repeated SHOW TABLES per request. */
+	private static array $table_exists_cache = array();
+
 	/**
 	 * WordPress 邏輯型別 → MySQL 實體型別映射
 	 */
@@ -145,6 +148,9 @@ final class TMDO_Schema_Manager {
 		// dbDelta 自動處理建表／ALTER TABLE
 		$dbdelta_result = dbDelta( $sql );
 
+		// Bust the request-scoped table_exists cache so subsequent calls see the new table.
+		self::$table_exists_cache[ $table ] = true;
+
 		// 記錄 Schema 版本與定義
 		self::store_schema_metadata( $entity_type, $group_name, $schema_hash, $field_definitions );
 
@@ -284,8 +290,25 @@ final class TMDO_Schema_Manager {
 	 */
 	public static function table_exists( string $table_name ): bool {
 		global $wpdb;
+		if ( isset( self::$table_exists_cache[ $table_name ] ) ) {
+			return self::$table_exists_cache[ $table_name ];
+		}
+
 		$result                                  = $wpdb->get_var( $wpdb->prepare( 'SHOW TABLES LIKE %s', $table_name ) );
-		return $result === $table_name;
+		self::$table_exists_cache[ $table_name ] = $result === $table_name;
+		return self::$table_exists_cache[ $table_name ];
+	}
+
+	/**
+	 * Clear the request-scoped table-exists cache.
+	 *
+	 * Mirrors TMDO_Routing_Predicate::flush_cache(): call in test setUp to isolate
+	 * cases. In production the cache is correct for a request lifetime; tests that
+	 * create then drop flat tables across classes must reset it so a stale `true`
+	 * does not survive after a table is dropped.
+	 */
+	public static function flush_table_exists_cache(): void {
+		self::$table_exists_cache = array();
 	}
 
 	/**

includes/migration/class-tmdo-migration-orchestrator.php

@@ -1,5 +1,4 @@
 <?php
-// phpcs:ignore WPDO.AntiEAV -- platform migration tool: WPDO v1->v2 legacy meta orchestration
 /**
  * One-click User Entity Migration Orchestrator.
  *
@@ -11,15 +10,17 @@
  * is 10-50× faster than per-row PHP loops. Per-row safe_unserialize fallback
  * applies only to groups containing `json` fields (currently only `hp_user`).
  *
- * @package WP_Data_Optimizer
+ * @package TMDO
  * @since 2.8.0
  */
 
+// phpcs:ignore WPDO.AntiEAV -- platform migration tool: WPDO v1->v2 legacy meta orchestration
+
 if ( ! defined( 'ABSPATH' ) ) {
 	exit;
 }
 
-// phpcs:disable Squiz.Commenting.FunctionComment,Squiz.Commenting.VariableComment,Squiz.Commenting.ClassComment,WordPress.DB.PreparedSQL.NotPrepared,WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.Security.EscapeOutput.ExceptionNotEscaped,WordPress.PHP.YodaConditions,Squiz.Commenting.InlineComment.InvalidEndChar -- Internal state-machine helpers and Throwable messages — not user output. SQL composed with sanitize_column_name() + $wpdb->prepare() values.
+// phpcs:disable Squiz.Commenting.FunctionComment,Squiz.Commenting.VariableComment,Squiz.Commenting.ClassComment,WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.Security.EscapeOutput.ExceptionNotEscaped,WordPress.PHP.YodaConditions,Squiz.Commenting.InlineComment.InvalidEndChar -- Internal state-machine helpers and Throwable messages — not user output. SQL composed with sanitize_column_name() + $wpdb->prepare() values.
 
 /**
  * One-click User Migration Orchestrator — drives the demote → backfill →
@@ -27,7 +28,7 @@ if ( ! defined( 'ABSPATH' ) ) {
  *
  * @since 2.8.0
  */
-final class TMDO_Migration_Orchestrator {
+class TMDO_Migration_Orchestrator {
 
 	const OPT_JOB             = 'wpdo_migration_job';
 	const OPT_LOCK            = 'wpdo_migration_lock';
@@ -78,14 +79,14 @@ final class TMDO_Migration_Orchestrator {
 		$eav_rows     = self::count_eav_residue( $managed_keys );
 		$users        = (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$wpdb->users}" );
 		$usermeta     = (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$wpdb->usermeta}" );
-		$mode         = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
+		$mode         = TMDO_Mode_Manager::get( static::ENTITY_TYPE );
 
 		$groups = array();
-		foreach ( TMDO_Entity_Registry::get_groups_for_type( self::ENTITY_TYPE ) as $group ) {
+		foreach ( TMDO_Entity_Registry::get_groups_for_type( static::ENTITY_TYPE ) as $group ) {
-			$keys             = TMDO_Entity_Registry::get_group_keys( self::ENTITY_TYPE, $group );
+			$keys             = TMDO_Entity_Registry::get_group_keys( static::ENTITY_TYPE, $group );
 			$has_json         = self::group_has_json_field( $group );
 			$residue          = $keys ? self::count_eav_residue( $keys ) : 0;
-			$flat_table       = TMDO_Schema_Manager::get_table_name( self::ENTITY_TYPE, $group );
+			$flat_table       = TMDO_Schema_Manager::get_table_name( static::ENTITY_TYPE, $group );
 			$flat_rows        = TMDO_Schema_Manager::table_exists( $flat_table )
 				? (int) $wpdb->get_var( "SELECT COUNT(*) FROM `{$flat_table}`" )
 				: 0;
@@ -145,8 +146,8 @@ final class TMDO_Migration_Orchestrator {
 		$eav_rows     = self::count_eav_residue( $managed_keys );
 
 		$groups_with_residue = 0;
-		foreach ( TMDO_Entity_Registry::get_groups_for_type( self::ENTITY_TYPE ) as $group ) {
+		foreach ( TMDO_Entity_Registry::get_groups_for_type( static::ENTITY_TYPE ) as $group ) {
-			$keys = TMDO_Entity_Registry::get_group_keys( self::ENTITY_TYPE, $group );
+			$keys = TMDO_Entity_Registry::get_group_keys( static::ENTITY_TYPE, $group );
 			if ( $keys && self::count_eav_residue( $keys ) > 0 ) {
 				++$groups_with_residue;
 			}
@@ -154,7 +155,7 @@ final class TMDO_Migration_Orchestrator {
 
 		$users    = (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$wpdb->users}" );
 		$usermeta = (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$wpdb->usermeta}" );
-		$mode     = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
+		$mode     = TMDO_Mode_Manager::get( static::ENTITY_TYPE );
 
 		$job_state = 'idle';
 		$job       = get_option( self::OPT_JOB );
@@ -299,14 +300,11 @@ final class TMDO_Migration_Orchestrator {
 		}
 
 		$current = $job['phase'];
-		$method  = 'phase_' . $current;
 
 		try {
-			if ( ! method_exists( __CLASS__, $method ) ) {
+			$phase_started = microtime( true );
-				throw new \RuntimeException( "Unknown phase: {$current}" );
+			$phase         = self::make_phase( $current );
-			}
+			$result        = $phase->execute( $job );
-
-			$result = self::{$method}( $job );
 
 			if ( 'in_progress' === ( $result['status'] ?? '' ) ) {
 				self::persist_job( $job );
@@ -324,7 +322,7 @@ final class TMDO_Migration_Orchestrator {
 			}
 
 			$next = self::next_phase( $current );
-			self::log( $job, sprintf( '✓ %s (%.2fs)', $current, microtime( true ) - ( $result['_started_at'] ?? microtime( true ) ) ) );
+			self::log( $job, sprintf( '✓ %s (%.2fs)', $current, microtime( true ) - $phase_started ) );
 			$job['phase']            = $next;
 			$job['phase_index']      = array_search( $next, self::PHASES, true );
 			$job['phase_progress']   = 0;
@@ -332,18 +330,7 @@ final class TMDO_Migration_Orchestrator {
 			$job['updated_at']       = time();
 
 			if ( 'completed' === $next ) {
-				$job['state']            = 'completed';
+				self::make_phase( 'completed' )->execute( $job );
-				$job['completed_at']     = time();
-				$job['overall_progress'] = 100;
-				self::log(
-					$job,
-					sprintf(
-						'✅ Migration complete — ratio %s → %s (-%.0f%%)',
-						$job['metrics']['ratio_start'],
-						$job['metrics']['ratio_now'],
-						( $job['metrics']['ratio_start'] - $job['metrics']['ratio_now'] ) / max( $job['metrics']['ratio_start'], 0.01 ) * 100
-					)
-				);
 				self::persist_job( $job );
 				self::release_lock();
 				self::bust_attention_cache();
@@ -396,12 +383,12 @@ final class TMDO_Migration_Orchestrator {
 		}
 		// Auto-rollback to safe state (dual_write) before clearing.
 		try {
-			$current_mode = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
+			$current_mode = TMDO_Mode_Manager::get( static::ENTITY_TYPE );
 			if ( TMDO_Mode_Manager::MODE_AEAV_ONLY === $current_mode ) {
-				TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_SHADOW_READ );
+				TMDO_Mode_Manager::set( static::ENTITY_TYPE, TMDO_Mode_Manager::MODE_SHADOW_READ );
-				TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_DUAL_WRITE );
+				TMDO_Mode_Manager::set( static::ENTITY_TYPE, TMDO_Mode_Manager::MODE_DUAL_WRITE );
 			} elseif ( TMDO_Mode_Manager::MODE_SHADOW_READ === $current_mode ) {
-				TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_DUAL_WRITE );
+				TMDO_Mode_Manager::set( static::ENTITY_TYPE, TMDO_Mode_Manager::MODE_DUAL_WRITE );
 			}
 		} catch ( \Throwable $e ) {
 			// Logged but non-fatal.
@@ -480,405 +467,28 @@ final class TMDO_Migration_Orchestrator {
 	// Phases — each returns ['status' => 'ok'|'in_progress'|'error', 'message' => string]
 	// ─────────────────────────────────────────────────────────────────────
 
-	private static function phase_diagnose( array &$job ): array {
+	// ── Phase factory ─────────────────────────────────────────────────────────
-		$preflight                      = self::preflight();
-		$job['metrics']['eav_rows_now'] = $preflight['eav_rows'];
-		$job['metrics']['ratio_now']    = $preflight['ratio'];
 
-		self::log(
+	private static function make_phase( string $name ): TMDO_Migration_Phase_Interface {
-			$job,
+		$map = array(
-			sprintf(
+			'diagnose'             => TMDO_Phase_Diagnose::class,
-				'Diagnose: %d EAV residue rows, %d users, ratio %s, mode %s',
+			'backup'               => TMDO_Phase_Backup::class,
-				$preflight['eav_rows'],
+			'demote'               => TMDO_Phase_Demote::class,
-				$preflight['users'],
+			'install_schema'       => TMDO_Phase_Install_Schema::class,
-				(string) $preflight['ratio'],
+			'backfill_bulk'        => TMDO_Phase_Backfill_Bulk::class,
-				$preflight['mode']
+			'backfill_unserialize' => TMDO_Phase_Backfill_Unserialize::class,
-			)
+			'promote_shadow'       => TMDO_Phase_Promote_Shadow::class,
-		);
+			'verify_sample'        => TMDO_Phase_Verify_Sample::class,
-
+			'promote_aeav'         => TMDO_Phase_Promote_Aeav::class,
-		return array(
+			'cleanup'              => TMDO_Phase_Cleanup::class,
-			'status'  => 'ok',
+			'completed'            => TMDO_Phase_Completed::class,
-			'message' => 'Diagnose complete',
 		);
+		if ( ! isset( $map[ $name ] ) ) {
+			throw new \RuntimeException( "Unknown phase: {$name}" );
+		}
+		return new $map[ $name ]( static::ENTITY_TYPE );
 	}
 
-	private static function phase_backup( array &$job ): array {
-		if ( empty( $job['options']['auto_backup'] ) ) {
-			self::log( $job, '↪ Backup skipped (auto_backup=false)' );
-			return array( 'status' => 'ok' );
-		}
-
-		$upload_dir = wp_upload_dir();
-		$backup_dir = trailingslashit( $upload_dir['basedir'] ) . self::BACKUP_DIR_REL;
-
-		if ( ! wp_mkdir_p( $backup_dir ) ) {
-			throw new \RuntimeException( "Cannot create backup directory: {$backup_dir}" );
-		}
-
-		// HTTP-level deny for Apache/IIS. Note: nginx silently ignores .htaccess —
-		// operators on nginx must add a `location ~ /wp-content/uploads/wpdo-backups/
-		// { deny all; }` block (logged in admin notice).
-		$htaccess = $backup_dir . '/.htaccess';
-		if ( ! file_exists( $htaccess ) ) {
-			file_put_contents( $htaccess, "Require all denied\n" );
-			@chmod( $htaccess, 0644 );
-		}
-		$webconfig = $backup_dir . '/web.config';
-		if ( ! file_exists( $webconfig ) ) {
-			file_put_contents(
-				$webconfig,
-				"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<configuration><system.webServer><authorization><deny users=\"*\"/></authorization></system.webServer></configuration>\n"
-			);
-			@chmod( $webconfig, 0644 );
-		}
-		$index = $backup_dir . '/index.php';
-		if ( ! file_exists( $index ) ) {
-			file_put_contents( $index, "<?php // Silence is golden.\n" );
-			@chmod( $index, 0644 );
-		}
-
-		$filename    = sprintf(
-			'wp_usermeta_%s_%s.sql',
-			gmdate( 'Ymd_His' ),
-			$job['job_id']
-		);
-		$backup_path = $backup_dir . '/' . $filename;
-
-		global $wpdb;
-		$rows = $wpdb->get_results(
-			"SELECT umeta_id, user_id, meta_key, meta_value FROM {$wpdb->usermeta} ORDER BY umeta_id ASC",
-			ARRAY_A
-		);
-
-		$fp = fopen( $backup_path, 'wb' );
-		if ( ! $fp ) {
-			throw new \RuntimeException( "Cannot open backup file for writing: {$backup_path}" );
-		}
-		// Owner-only read/write — backup contains user PII (emails, billing
-		// addresses, OAuth tokens, session blobs). Default umask leaks to
-		// other system users on shared hosts.
-		@chmod( $backup_path, 0600 );
-
-		fwrite( $fp, "-- WPDO migration backup of {$wpdb->usermeta}\n" );
-		fwrite( $fp, '-- Job: ' . $job['job_id'] . "\n" );
-		fwrite( $fp, '-- Generated: ' . gmdate( 'c' ) . "\n" );
-		fwrite( $fp, "-- Restore: mysql ... < this_file.sql\n\n" );
-		fwrite( $fp, "/*!40101 SET NAMES utf8mb4 */;\n" );
-		fwrite( $fp, "/*!40101 SET @OLD_SQL_MODE=@@SQL_MODE, SQL_MODE='NO_AUTO_VALUE_ON_ZERO' */;\n" );
-		fwrite( $fp, "SET FOREIGN_KEY_CHECKS=0;\n" );
-		fwrite( $fp, "LOCK TABLES `{$wpdb->usermeta}` WRITE;\n" );
-
-		$batch = array();
-		$count = 0;
-		foreach ( $rows as $row ) {
-			// UNHEX-encode meta_value: avoids ALL escape edge cases (binary,
-			// embedded NULs, non-UTF8, sql_mode mismatches at restore time).
-			// meta_key is %-bound through esc_sql which is sufficient for an
-			// ASCII-only key universe.
-			$batch[] = sprintf(
-				"(%d,%d,'%s',UNHEX('%s'))",
-				(int) $row['umeta_id'],
-				(int) $row['user_id'],
-				esc_sql( (string) $row['meta_key'] ),
-				bin2hex( (string) ( $row['meta_value'] ?? '' ) )
-			);
-			++$count;
-			if ( count( $batch ) >= 500 ) {
-				fwrite( $fp, "INSERT INTO `{$wpdb->usermeta}` (umeta_id,user_id,meta_key,meta_value) VALUES\n" . implode( ",\n", $batch ) . ";\n" );
-				$batch = array();
-			}
-		}
-		if ( $batch ) {
-			fwrite( $fp, "INSERT INTO `{$wpdb->usermeta}` (umeta_id,user_id,meta_key,meta_value) VALUES\n" . implode( ",\n", $batch ) . ";\n" );
-		}
-		fwrite( $fp, "UNLOCK TABLES;\n" );
-		fwrite( $fp, "SET FOREIGN_KEY_CHECKS=1;\n" );
-		fwrite( $fp, "/*!40101 SET SQL_MODE=@OLD_SQL_MODE */;\n" );
-		fclose( $fp );
-
-		$job['backup_path'] = $backup_path;
-		self::log(
-			$job,
-			sprintf(
-				'Backup written: %s (%d rows, %s, chmod 0600)',
-				$filename,
-				$count,
-				size_format( filesize( $backup_path ) )
-			)
-		);
-
-		// Best-effort web-server detection — log nginx warning so operator
-		// can add the manual location block (htaccess/web.config don't apply).
-		$server = isset( $_SERVER['SERVER_SOFTWARE'] ) ? strtolower( sanitize_text_field( wp_unslash( (string) $_SERVER['SERVER_SOFTWARE'] ) ) ) : '';
-		if ( str_contains( $server, 'nginx' ) ) {
-			self::log( $job, '⚠ nginx detected: add `location ~ /wp-content/uploads/wpdo-backups/ { deny all; }` to your nginx config — .htaccess does not apply.' );
-		}
-
-		return array( 'status' => 'ok' );
-	}
-
-	private static function phase_demote( array &$job ): array {
-		$current = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
-		if ( TMDO_Mode_Manager::MODE_AEAV_ONLY !== $current ) {
-			self::log( $job, "↪ Demote skipped (mode is {$current}, not aeav_only)" );
-			return array( 'status' => 'ok' );
-		}
-
-		// Two-step demotion: aeav_only → shadow_read → dual_write.
-		// (Safe transition: demotion always allowed.)
-		$r = TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_SHADOW_READ );
-		if ( is_wp_error( $r ) ) {
-			throw new \RuntimeException( 'Demote step 1 failed: ' . $r->get_error_message() );
-		}
-		$r = TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_DUAL_WRITE );
-		if ( is_wp_error( $r ) ) {
-			throw new \RuntimeException( 'Demote step 2 failed: ' . $r->get_error_message() );
-		}
-
-		self::log( $job, 'Mode: aeav_only → dual_write (reads now go to EAV)' );
-		return array( 'status' => 'ok' );
-	}
-
-	private static function phase_install_schema( array &$job ): array {
-		do_action( 'wpdo_register_entity_fields', TMDO_Entity_Registry::class );
-		TMDO_Schema_Manager::process_pending_migrations();
-
-		// Verify all 9 expected tables exist.
-		$missing = array();
-		foreach ( TMDO_Entity_Registry::get_groups_for_type( self::ENTITY_TYPE ) as $group ) {
-			$table = TMDO_Schema_Manager::get_table_name( self::ENTITY_TYPE, $group );
-			if ( ! TMDO_Schema_Manager::table_exists( $table ) ) {
-				$missing[] = $group;
-			}
-		}
-		if ( $missing ) {
-			throw new \RuntimeException( 'Schema migration failed; missing tables: ' . implode( ',', $missing ) );
-		}
-
-		$count = count( TMDO_Entity_Registry::get_groups_for_type( self::ENTITY_TYPE ) );
-		self::log( $job, "Schema migration ok ({$count} flat tables verified)" );
-		return array( 'status' => 'ok' );
-	}
-
-	private static function phase_backfill_bulk( array &$job ): array {
-		if ( ! empty( $job['options']['dry_run'] ) ) {
-			self::log( $job, '↪ Backfill bulk skipped (dry_run)' );
-			return array( 'status' => 'ok' );
-		}
-
-		$total_groups = 0;
-		$total_rows   = 0;
-		foreach ( TMDO_Entity_Registry::get_groups_for_type( self::ENTITY_TYPE ) as $group ) {
-			if ( self::group_has_json_field( $group ) ) {
-				continue; // handled in phase_backfill_unserialize
-			}
-			$rows        = self::execute_bulk_pivot( $group );
-			$total_rows += $rows;
-			++$total_groups;
-			self::log( $job, sprintf( '  • bulk pivot %s: %d row(s)', $group, $rows ) );
-		}
-		self::log( $job, sprintf( 'Bulk backfill: %d groups, %d rows total', $total_groups, $total_rows ) );
-
-		// Update live ratio.
-		$preflight                      = self::preflight();
-		$job['metrics']['eav_rows_now'] = $preflight['eav_rows'];
-		$job['metrics']['ratio_now']    = $preflight['ratio'];
-
-		return array( 'status' => 'ok' );
-	}
-
-	private static function phase_backfill_unserialize( array &$job ): array {
-		if ( ! empty( $job['options']['dry_run'] ) ) {
-			self::log( $job, '↪ Backfill unserialize skipped (dry_run)' );
-			return array( 'status' => 'ok' );
-		}
-
-		$total_rows = 0;
-		foreach ( TMDO_Entity_Registry::get_groups_for_type( self::ENTITY_TYPE ) as $group ) {
-			if ( ! self::group_has_json_field( $group ) ) {
-				continue;
-			}
-			$result = TMDO_Entity_Migration_Engine::migrate_group(
-				self::ENTITY_TYPE,
-				$group,
-				array( 'sleep_ms' => 0 )
-			);
-			if ( ! empty( $result['error'] ) ) {
-				throw new \RuntimeException( "Row-by-row backfill {$group} failed: " . $result['error'] );
-			}
-			if ( ( $result['errors'] ?? 0 ) > 0 && 0 === ( $result['migrated'] ?? 0 ) ) {
-				throw new \RuntimeException( "All rows failed during {$group} backfill — see error_log" );
-			}
-			$total_rows += (int) ( $result['migrated'] ?? 0 );
-			self::log( $job, sprintf( '  • row-by-row %s: %d row(s)', $group, $result['migrated'] ?? 0 ) );
-		}
-		self::log( $job, sprintf( 'Row-by-row backfill: %d rows total', $total_rows ) );
-		return array( 'status' => 'ok' );
-	}
-
-	private static function phase_promote_shadow( array &$job ): array {
-		$current = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
-		if ( TMDO_Mode_Manager::MODE_DUAL_WRITE === $current ) {
-			$r = TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_SHADOW_READ );
-			if ( is_wp_error( $r ) ) {
-				throw new \RuntimeException( 'Promote to shadow_read failed: ' . $r->get_error_message() );
-			}
-			self::log( $job, 'Mode: dual_write → shadow_read (verifying flat reads)' );
-		} else {
-			self::log( $job, "↪ Already at {$current}; skip promote_shadow" );
-		}
-		return array( 'status' => 'ok' );
-	}
-
-	private static function phase_verify_sample( array &$job ): array {
-		global $wpdb;
-
-		if ( ! empty( $job['options']['verify_24h'] ) ) {
-			// Operator opted into the 24-hour shadow-read window — pause here.
-			$elapsed = time() - ( $job['phase_started_at'] ?? time() );
-			if ( ! isset( $job['phase_started_at'] ) ) {
-				$job['phase_started_at'] = time();
-				self::log( $job, '⏸ 24h shadow_read window started — wizard will resume after window elapses.' );
-				return array( 'status' => 'in_progress' );
-			}
-			if ( $elapsed < DAY_IN_SECONDS ) {
-				return array( 'status' => 'in_progress' );
-			}
-			self::log( $job, '⏳ 24h shadow_read window complete; running sample compare' );
-		}
-
-		$strict      = ! empty( $job['options']['verify_strict'] );
-		$users_total = (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$wpdb->users}" );
-		$sample_size = $strict
-			? (int) max( self::VERIFY_SAMPLE_MIN, ceil( $users_total * self::VERIFY_SAMPLE_RATIO ) )
-			: 100;
-		$sample_size = min( $sample_size, $users_total );
-		$sample_ids  = $wpdb->get_col(
-			$wpdb->prepare(
-				"SELECT ID FROM {$wpdb->users} ORDER BY RAND() LIMIT %d",
-				$sample_size
-			)
-		);
-
-		$diffs        = 0;
-		$compared     = 0;
-		$managed_keys = self::get_managed_keys();
-
-		foreach ( $sample_ids as $uid ) {
-			foreach ( $managed_keys as $key ) {
-				$eav = $wpdb->get_var(
-					$wpdb->prepare(
-						"SELECT meta_value FROM {$wpdb->usermeta} WHERE user_id = %d AND meta_key = %s LIMIT 1",
-						$uid,
-						$key
-					)
-				);
-
-				// Skip: no EAV source-of-truth to verify against (key already cleaned
-				// or never existed). The wizard's invariant only flags as DIFF the
-				// case where EAV has data but flat doesn't match it — that is the
-				// only real "backfill error".
-				if ( null === $eav || '' === $eav ) {
-					continue;
-				}
-
-				++$compared;
-				$flat = TMDO_Hook_Bus::direct_read( self::ENTITY_TYPE, (int) $uid, $key );
-
-				if ( ! self::values_loose_equal( $flat, $eav ) ) {
-					++$diffs;
-					if ( $diffs <= 3 ) {
-						self::log(
-							$job,
-							sprintf(
-								'  ! diff uid=%d key=%s flat=%s eav=%s',
-								$uid,
-								$key,
-								is_scalar( $flat ) ? (string) $flat : gettype( $flat ),
-								is_scalar( $eav ) ? (string) $eav : gettype( $eav )
-							)
-						);
-					}
-				}
-			}
-		}
-
-		self::log(
-			$job,
-			sprintf(
-				'Verify: sampled %d users × %d keys = %d compares, %d diff(s)',
-				count( $sample_ids ),
-				count( $managed_keys ),
-				$compared,
-				$diffs
-			)
-		);
-
-		if ( $diffs > 0 ) {
-			throw new \RuntimeException(
-				sprintf(
-					'Verification found %d divergence(s) across %d compares — aborting before destructive cleanup.',
-					$diffs,
-					$compared
-				)
-			);
-		}
-
-		return array( 'status' => 'ok' );
-	}
-
-	private static function phase_promote_aeav( array &$job ): array {
-		$current = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
-		if ( TMDO_Mode_Manager::MODE_AEAV_ONLY === $current ) {
-			self::log( $job, '↪ Already aeav_only' );
-			return array( 'status' => 'ok' );
-		}
-		$r = TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_AEAV_ONLY );
-		if ( is_wp_error( $r ) ) {
-			throw new \RuntimeException( 'Promote to aeav_only failed: ' . $r->get_error_message() );
-		}
-		self::log( $job, 'Mode: shadow_read → aeav_only (cutover complete)' );
-		return array( 'status' => 'ok' );
-	}
-
-	private static function phase_cleanup( array &$job ): array {
-		if ( ! empty( $job['options']['dry_run'] ) ) {
-			self::log( $job, '↪ Cleanup skipped (dry_run)' );
-			return array( 'status' => 'ok' );
-		}
-
-		// Hard guard: must be in aeav_only AND backup must exist (if requested).
-		$mode = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
-		if ( TMDO_Mode_Manager::MODE_AEAV_ONLY !== $mode ) {
-			throw new \RuntimeException( "Refusing cleanup — mode is {$mode}, must be aeav_only" );
-		}
-		if ( ! empty( $job['options']['auto_backup'] ) && empty( $job['backup_path'] ) ) {
-			throw new \RuntimeException( 'Refusing cleanup — auto_backup requested but no backup_path on record' );
-		}
-
-		global $wpdb;
-		$keys = self::get_managed_keys();
-		if ( empty( $keys ) ) {
-			self::log( $job, '↪ No managed keys to clean' );
-			return array( 'status' => 'ok' );
-		}
-
-		$placeholders = implode( ',', array_fill( 0, count( $keys ), '%s' ) );
-		$deleted      = (int) $wpdb->query(
-			$wpdb->prepare(
-				"DELETE FROM {$wpdb->usermeta} WHERE meta_key IN ({$placeholders})",
-				...$keys
-			)
-		);
-
-		// Refresh metrics.
-		$preflight                      = self::preflight();
-		$job['metrics']['eav_rows_now'] = $preflight['eav_rows'];
-		$job['metrics']['ratio_now']    = $preflight['ratio'];
-
-		self::log( $job, sprintf( 'Cleanup: deleted %d EAV row(s); ratio now %s', $deleted, (string) $preflight['ratio'] ) );
-		return array( 'status' => 'ok' );
-	}
 
 	// ─────────────────────────────────────────────────────────────────────
 	// Helpers
@@ -887,14 +497,14 @@ final class TMDO_Migration_Orchestrator {
 	/** Returns all meta_keys registered as entity fields for `user`. */
 	private static function get_managed_keys(): array {
 		$keys = array();
-		foreach ( TMDO_Entity_Registry::get_groups_for_type( self::ENTITY_TYPE ) as $group ) {
+		foreach ( TMDO_Entity_Registry::get_groups_for_type( static::ENTITY_TYPE ) as $group ) {
-			$keys = array_merge( $keys, TMDO_Entity_Registry::get_group_keys( self::ENTITY_TYPE, $group ) );
+			$keys = array_merge( $keys, TMDO_Entity_Registry::get_group_keys( static::ENTITY_TYPE, $group ) );
 		}
 		return array_values( array_unique( $keys ) );
 	}
 
 	private static function group_has_json_field( string $group ): bool {
-		foreach ( TMDO_Entity_Registry::get_group_fields( self::ENTITY_TYPE, $group ) as $field ) {
+		foreach ( TMDO_Entity_Registry::get_group_fields( static::ENTITY_TYPE, $group ) as $field ) {
 			if ( 'json' === ( $field['type'] ?? '' ) ) {
 				return true;
 			}
@@ -919,82 +529,6 @@ final class TMDO_Migration_Orchestrator {
 		);
 	}
 
-	/**
-	 * Single-statement bulk pivot for a text-only group.
-	 *
-	 * @param string $group Entity group name.
-	 * @return int Affected rows.
-	 * @throws \RuntimeException If $wpdb->query() fails.
-	 */
-	private static function execute_bulk_pivot( string $group ): int {
-		global $wpdb;
-
-		$fields = TMDO_Entity_Registry::get_group_fields( self::ENTITY_TYPE, $group );
-		if ( empty( $fields ) ) {
-			return 0;
-		}
-
-		$adapter = TMDO_Entity_Registry::get_adapter( self::ENTITY_TYPE );
-		$id_col  = $adapter->get_entity_id_column();
-		$table   = TMDO_Schema_Manager::get_table_name( self::ENTITY_TYPE, $group );
-
-		$select_cases = array();
-		$update_cols  = array();
-		$col_names    = array();
-		$keys         = array();
-		foreach ( $fields as $f ) {
-			$key         = $f['key'];
-			$col         = TMDO_Schema_Manager::sanitize_column_name( $key );
-			$keys[]      = $key;
-			$col_names[] = "`{$col}`";
-			// MAX(CASE WHEN meta_key='...' THEN meta_value END)
-			$select_cases[] = $wpdb->prepare(
-				"MAX(CASE WHEN um.meta_key = %s THEN um.meta_value END) AS `{$col}`",
-				$key
-			);
-			$update_cols[]  = "`{$col}` = COALESCE(VALUES(`{$col}`), `{$col}`)";
-		}
-
-		$placeholders = implode( ',', array_fill( 0, count( $keys ), '%s' ) );
-
-		$sql = sprintf(
-			'INSERT INTO `%s` (`%s`, %s)
-			 SELECT um.user_id, %s
-			 FROM `%s` um
-			 WHERE um.meta_key IN (%s)
-			 GROUP BY um.user_id
-			 ON DUPLICATE KEY UPDATE %s',
-			$table,
-			$id_col,
-			implode( ', ', $col_names ),
-			implode( ', ', $select_cases ),
-			$wpdb->usermeta,
-			$placeholders,
-			implode( ', ', $update_cols )
-		);
-
-		// phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared,WordPress.DB.PreparedSQL.InterpolatedNotPrepared -- pivot SQL composed from registry-validated identifiers + prepared values inside CASE/IN.
-		$result = $wpdb->query( $wpdb->prepare( $sql, ...$keys ) );
-
-		if ( false === $result ) {
-			throw new \RuntimeException( "Bulk pivot failed for group {$group}: " . $wpdb->last_error );
-		}
-		return (int) $result;
-	}
-
-	private static function values_loose_equal( $a, $b ): bool {
-		if ( null === $a && null === $b ) {
-			return true;
-		}
-		if ( null === $a || null === $b ) {
-			$other = null === $a ? $b : $a;
-			return '' === $other || array() === $other || 0 === $other || '0' === $other;
-		}
-		if ( is_array( $a ) || is_array( $b ) ) {
-			return wp_json_encode( $a ) === wp_json_encode( $b );
-		}
-		return (string) $a === (string) $b;
-	}
 
 	private static function next_phase( string $current ): string {
 		$idx = array_search( $current, self::PHASES, true );
@@ -1072,12 +606,12 @@ final class TMDO_Migration_Orchestrator {
 
 		// Auto-rollback: only if mode is currently aeav_only AND we haven't reached cleanup yet.
 		try {
-			$current     = TMDO_Mode_Manager::get( self::ENTITY_TYPE );
+			$current     = TMDO_Mode_Manager::get( static::ENTITY_TYPE );
 			$phase       = $job['phase'] ?? '';
 			$pre_cleanup = ! in_array( $phase, array( 'cleanup', 'completed' ), true );
 			if ( $pre_cleanup && TMDO_Mode_Manager::MODE_AEAV_ONLY === $current ) {
-				TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_SHADOW_READ );
+				TMDO_Mode_Manager::set( static::ENTITY_TYPE, TMDO_Mode_Manager::MODE_SHADOW_READ );
-				TMDO_Mode_Manager::set( self::ENTITY_TYPE, TMDO_Mode_Manager::MODE_DUAL_WRITE );
+				TMDO_Mode_Manager::set( static::ENTITY_TYPE, TMDO_Mode_Manager::MODE_DUAL_WRITE );
 				self::log( $job, '↩ Auto-rolled back to dual_write (reads safe)' );
 			}
 		} catch ( \Throwable $inner ) {

includes/migration/class-tmdo-migration-phase-base.php

@@ -0,0 +1,166 @@
+<?php
+/**
+ * Shared helpers for all migration phase Strategy objects.
+ *
+ * @package TMDO
+ * @since 3.0.1
+ */
+
+// phpcs:disable Squiz.Commenting.FunctionComment,WordPress.DB.PreparedSQL.NotPrepared,WordPress.DB.PreparedSQL.InterpolatedNotPrepared,WordPress.PHP.YodaConditions,WordPress.Security.EscapeOutput.OutputNotEscaped -- Internal helpers; SQL composed from registry-validated identifiers; exception messages not echoed.
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Shared helpers for all migration phase Strategy objects.
+ *
+ * Concrete phases extend this class, receive the entity type at construction,
+ * and implement execute().  All database helpers delegate to
+ * TMDO_Entity_Registry / TMDO_Schema_Manager so the entity type is the only
+ * injection point needed for unit tests.
+ */
+abstract class TMDO_Migration_Phase_Base implements TMDO_Migration_Phase_Interface {
+
+	const MAX_LOG_LINES = 50;
+
+	/**
+	 * Entity type this phase operates on (e.g. 'user', 'post').
+	 *
+	 * @var string
+	 */
+	protected string $entity_type;
+
+	public function __construct( string $entity_type ) {
+		$this->entity_type = $entity_type;
+	}
+
+	// ── Logging ───────────────────────────────────────────────────────────────
+
+	protected function log( array &$job, string $message ): void {
+		$line         = '[' . gmdate( 'H:i:s' ) . '] ' . $message;
+		$job['log'][] = $line;
+		if ( count( $job['log'] ) > self::MAX_LOG_LINES ) {
+			$job['log'] = array_slice( $job['log'], -self::MAX_LOG_LINES );
+		}
+		$job['updated_at'] = time();
+	}
+
+	// ── Registry helpers ──────────────────────────────────────────────────────
+
+	protected function get_managed_keys(): array {
+		$keys = array();
+		foreach ( TMDO_Entity_Registry::get_groups_for_type( $this->entity_type ) as $group ) {
+			$keys = array_merge( $keys, TMDO_Entity_Registry::get_group_keys( $this->entity_type, $group ) );
+		}
+		return array_values( array_unique( $keys ) );
+	}
+
+	protected function group_has_json_field( string $group ): bool {
+		foreach ( TMDO_Entity_Registry::get_group_fields( $this->entity_type, $group ) as $field ) {
+			if ( 'json' === ( $field['type'] ?? '' ) ) {
+				return true;
+			}
+		}
+		return false;
+	}
+
+	// ── DB helpers ────────────────────────────────────────────────────────────
+
+	/** Count EAV rows for the given meta keys (or all managed keys if empty). */
+	protected function count_eav_residue( array $keys = array() ): int {
+		global $wpdb;
+		if ( empty( $keys ) ) {
+			$keys = $this->get_managed_keys();
+		}
+		if ( empty( $keys ) ) {
+			return 0;
+		}
+		$adapter      = TMDO_Entity_Registry::get_adapter( $this->entity_type );
+		$meta_table   = $adapter->get_native_meta_table();
+		$placeholders = implode( ',', array_fill( 0, count( $keys ), '%s' ) );
+		return (int) $wpdb->get_var(
+			$wpdb->prepare( "SELECT COUNT(*) FROM `{$meta_table}` WHERE meta_key IN ({$placeholders})", ...$keys )
+		);
+	}
+
+	/**
+	 * Bulk pivot for a text-only group via INSERT … SELECT … GROUP BY …
+	 * ON DUPLICATE KEY UPDATE.
+	 *
+	 * @param string $group Entity group to pivot.
+	 * @return int Number of rows affected.
+	 * @throws \RuntimeException On DB failure.
+	 */
+	protected function execute_bulk_pivot( string $group ): int {
+		global $wpdb;
+
+		$fields = TMDO_Entity_Registry::get_group_fields( $this->entity_type, $group );
+		if ( empty( $fields ) ) {
+			return 0;
+		}
+
+		$adapter    = TMDO_Entity_Registry::get_adapter( $this->entity_type );
+		$id_col     = $adapter->get_entity_id_column();
+		$meta_table = $adapter->get_native_meta_table();
+		$table      = TMDO_Schema_Manager::get_table_name( $this->entity_type, $group );
+
+		$select_cases = array();
+		$update_cols  = array();
+		$col_names    = array();
+		$keys         = array();
+
+		foreach ( $fields as $f ) {
+			$key            = $f['key'];
+			$col            = TMDO_Schema_Manager::sanitize_column_name( $key );
+			$keys[]         = $key;
+			$col_names[]    = "`{$col}`";
+			$select_cases[] = $wpdb->prepare(
+				"MAX(CASE WHEN um.meta_key = %s THEN um.meta_value END) AS `{$col}`",
+				$key
+			);
+			$update_cols[]  = "`{$col}` = COALESCE(VALUES(`{$col}`), `{$col}`)";
+		}
+
+		$placeholders = implode( ',', array_fill( 0, count( $keys ), '%s' ) );
+
+		$sql = sprintf(
+			'INSERT INTO `%s` (`%s`, %s)
+			 SELECT um.user_id, %s
+			 FROM `%s` um
+			 WHERE um.meta_key IN (%s)
+			 GROUP BY um.user_id
+			 ON DUPLICATE KEY UPDATE %s',
+			$table,
+			$id_col,
+			implode( ', ', $col_names ),
+			implode( ', ', $select_cases ),
+			$meta_table,
+			$placeholders,
+			implode( ', ', $update_cols )
+		);
+
+		$result = $wpdb->query( $wpdb->prepare( $sql, ...$keys ) );
+
+		if ( false === $result ) {
+			// phpcs:ignore WordPress.Security.EscapeOutput -- Exception message not echoed to browser.
+			throw new \RuntimeException( 'Bulk pivot failed for group ' . $group . ': ' . $wpdb->last_error );
+		}
+		return (int) $result;
+	}
+
+	/** Loose equality check for EAV vs flat value comparison (null/empty/scalar). */
+	protected function values_loose_equal( $a, $b ): bool {
+		if ( null === $a && null === $b ) {
+			return true;
+		}
+		if ( null === $a || null === $b ) {
+			$other = null === $a ? $b : $a;
+			return '' === $other || array() === $other || 0 === $other || '0' === $other;
+		}
+		if ( is_array( $a ) || is_array( $b ) ) {
+			return wp_json_encode( $a ) === wp_json_encode( $b );
+		}
+		return (string) $a === (string) $b;
+	}
+}

includes/migration/interface-migration-phase.php

@@ -0,0 +1,37 @@
+<?php
+/**
+ * Contract for a single migration phase (Strategy pattern).
+ *
+ * @package TMDO
+ * @since 3.0.1
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Contract for a single migration phase (Strategy pattern).
+ *
+ * Each phase is idempotent — re-entering returns ok if the desired state is
+ * already achieved.  The orchestrator never calls execute() on a phase that
+ * has already returned 'ok'; it only re-enters on 'in_progress'.
+ */
+interface TMDO_Migration_Phase_Interface {
+
+	/** Short slug matching the PHASES constant entry (e.g. 'backfill_bulk'). */
+	public function name(): string;
+
+	/**
+	 * Run the phase.
+	 *
+	 * @param  array $job Job array passed by reference — phase may append log
+	 *                    lines and update metrics fields.
+	 * @return array{status: 'ok'|'in_progress'|'done', message?: string}
+	 *              'ok'          — phase finished, advance to next.
+	 *              'in_progress' — phase needs another tick (e.g. 24h window).
+	 *              'done'        — terminal phase completed (completed phase only).
+	 * @throws \RuntimeException On unrecoverable failure; orchestrator catches.
+	 */
+	public function execute( array &$job ): array;
+}

includes/migration/phases/class-tmdo-phase-backfill-bulk.php

@@ -0,0 +1,62 @@
+<?php
+/**
+ * Migration phase: bulk pivot text-only meta groups via INSERT … SELECT.
+ *
+ * @package TMDO
+ * @since 3.0.1
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Iterates all registered groups for the entity type and pivots each
+ * text-only group in a single INSERT … SELECT … ON DUPLICATE KEY UPDATE.
+ */
+class TMDO_Phase_Backfill_Bulk extends TMDO_Migration_Phase_Base {
+
+	/**
+	 * Returns the phase slug.
+	 *
+	 * @return string
+	 */
+	public function name(): string {
+		return 'backfill_bulk';
+	}
+
+	/**
+	 * Executes the phase.
+	 *
+	 * @param array $job Job array (by reference).
+	 * @return array{status: string}
+	 * @throws \RuntimeException On DB pivot failure.
+	 */
+	public function execute( array &$job ): array {
+		if ( ! empty( $job['options']['dry_run'] ) ) {
+			$this->log( $job, '↪ Backfill bulk skipped (dry_run)' );
+			return array( 'status' => 'ok' );
+		}
+
+		$total_groups = 0;
+		$total_rows   = 0;
+
+		foreach ( TMDO_Entity_Registry::get_groups_for_type( $this->entity_type ) as $group ) {
+			if ( $this->group_has_json_field( $group ) ) {
+				continue; // Handled in backfill_unserialize.
+			}
+			$rows        = $this->execute_bulk_pivot( $group );
+			$total_rows += $rows;
+			++$total_groups;
+			$this->log( $job, sprintf( '  • bulk pivot %s: %d row(s)', $group, $rows ) );
+		}
+
+		$this->log( $job, sprintf( 'Bulk backfill: %d groups, %d rows total', $total_groups, $total_rows ) );
+
+		$preflight                      = TMDO_Migration_Orchestrator::preflight();
+		$job['metrics']['eav_rows_now'] = $preflight['eav_rows'];
+		$job['metrics']['ratio_now']    = $preflight['ratio'];
+
+		return array( 'status' => 'ok' );
+	}
+}

includes/migration/phases/class-tmdo-phase-backfill-unserialize.php

@@ -0,0 +1,69 @@
+<?php
+/**
+ * Migration phase: row-by-row backfill for groups with JSON/serialized fields.
+ *
+ * @package TMDO
+ * @since 3.0.1
+ */
+
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Uses TMDO_Entity_Migration_Engine for groups whose fields contain JSON type,
+ * which cannot be bulk-pivoted via INSERT … SELECT.
+ */
+class TMDO_Phase_Backfill_Unserialize extends TMDO_Migration_Phase_Base {
+
+	/**
+	 * Returns the phase slug.
+	 *
+	 * @return string
+	 */
+	public function name(): string {
+		return 'backfill_unserialize';
+	}
+
+	/**
+	 * Executes the phase.
+	 *
+	 * @param array $job Job array (by reference).
+	 * @return array{status: string}
+	 * @throws \RuntimeException On migration engine failure.
+	 */
+	public function execute( array &$job ): array {
+		if ( ! empty( $job['options']['dry_run'] ) ) {
+			$this->log( $job, '↪ Backfill unserialize skipped (dry_run)' );
+			return array( 'status' => 'ok' );
+		}
+
+		$total_rows = 0;
+
+		foreach ( TMDO_Entity_Registry::get_groups_for_type( $this->entity_type ) as $group ) {
+			if ( ! $this->group_has_json_field( $group ) ) {
+				continue; // Handled in backfill_bulk.
+			}
+
+			$result = TMDO_Entity_Migration_Engine::migrate_group(
+				$this->entity_type,
+				$group,
+				array( 'sleep_ms' => 0 )
+			);
+
+			if ( ! empty( $result['error'] ) ) {
+				throw new \RuntimeException( "Row-by-row backfill {$group} failed: " . $result['error'] );
+			}
+			if ( ( $result['errors'] ?? 0 ) > 0 && 0 === ( $result['migrated'] ?? 0 ) ) {
+				throw new \RuntimeException( "All rows failed during {$group} backfill — see error_log" );
+			}
+
+			$total_rows += (int) ( $result['migrated'] ?? 0 );
+			$this->log( $job, sprintf( '  • row-by-row %s: %d row(s)', $group, $result['migrated'] ?? 0 ) );
+		}
+
+		$this->log( $job, sprintf( 'Row-by-row backfill: %d rows total', $total_rows ) );
+		return array( 'status' => 'ok' );
+	}
+}

includes/migration/phases/class-tmdo-phase-backup.php

@@ -0,0 +1,158 @@
+<?php
+/**
+ * Migration phase: back up the native meta table before destructive cleanup.
+ *
+ * @package TMDO
+ * @since 3.0.1
+ */
+
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Writes a mysqldump-style SQL file of the usermeta table to wp-content/uploads/wpdo-backups/.
+ */
+class TMDO_Phase_Backup extends TMDO_Migration_Phase_Base {
+
+	/**
+	 * Relative path under wp-content/uploads/ for backup files.
+	 *
+	 * @var string
+	 */
+	const BACKUP_DIR_REL = 'wpdo-backups';
+
+	/**
+	 * Returns the phase slug.
+	 *
+	 * @return string
+	 */
+	public function name(): string {
+		return 'backup';
+	}
+
+	/**
+	 * Executes the phase.
+	 *
+	 * @param array $job Job array (by reference).
+	 * @return array{status: string}
+	 * @throws \RuntimeException If backup directory or file cannot be created.
+	 */
+	public function execute( array &$job ): array {
+		if ( empty( $job['options']['auto_backup'] ) ) {
+			$this->log( $job, '↪ Backup skipped (auto_backup=false)' );
+			return array( 'status' => 'ok' );
+		}
+
+		$upload_dir = wp_upload_dir();
+		$backup_dir = trailingslashit( $upload_dir['basedir'] ) . self::BACKUP_DIR_REL;
+
+		if ( ! wp_mkdir_p( $backup_dir ) ) {
+			throw new \RuntimeException( "Cannot create backup directory: {$backup_dir}" );
+		}
+
+		$this->write_web_deny_files( $backup_dir );
+
+		$filename    = sprintf( 'wp_usermeta_%s_%s.sql', gmdate( 'Ymd_His' ), $job['job_id'] );
+		$backup_path = $backup_dir . '/' . $filename;
+
+		global $wpdb;
+		$rows = $wpdb->get_results(
+			"SELECT umeta_id, user_id, meta_key, meta_value FROM {$wpdb->usermeta} ORDER BY umeta_id ASC", // phpcs:ignore WPDO.AntiEAV.no-direct-usermeta-select -- migration backup: must read raw usermeta to create full SQL dump before schema change
+			ARRAY_A
+		);
+
+		$fp = fopen( $backup_path, 'wb' );
+		if ( ! $fp ) {
+			throw new \RuntimeException( "Cannot open backup file for writing: {$backup_path}" );
+		}
+		// Owner-only read/write — backup contains user PII (emails, billing
+		// addresses, OAuth tokens, session blobs).
+		@chmod( $backup_path, 0600 );
+
+		fwrite( $fp, "-- WPDO migration backup of {$wpdb->usermeta}\n" );
+		fwrite( $fp, '-- Job: ' . $job['job_id'] . "\n" );
+		fwrite( $fp, '-- Generated: ' . gmdate( 'c' ) . "\n" );
+		fwrite( $fp, "-- Restore: mysql ... < this_file.sql\n\n" );
+		fwrite( $fp, "/*!40101 SET NAMES utf8mb4 */;\n" );
+		fwrite( $fp, "/*!40101 SET @OLD_SQL_MODE=@@SQL_MODE, SQL_MODE='NO_AUTO_VALUE_ON_ZERO' */;\n" );
+		fwrite( $fp, "SET FOREIGN_KEY_CHECKS=0;\n" );
+		fwrite( $fp, "LOCK TABLES `{$wpdb->usermeta}` WRITE;\n" );
+
+		$batch = array();
+		$count = 0;
+		foreach ( (array) $rows as $row ) {
+			// UNHEX-encode meta_value: avoids escape edge cases (binary, embedded
+			// NULs, non-UTF8, sql_mode mismatches at restore time).
+			$batch[] = sprintf(
+				"(%d,%d,'%s',UNHEX('%s'))",
+				(int) $row['umeta_id'],
+				(int) $row['user_id'],
+				esc_sql( (string) $row['meta_key'] ),
+				bin2hex( (string) ( $row['meta_value'] ?? '' ) )
+			);
+			++$count;
+			if ( count( $batch ) >= 500 ) {
+				fwrite( $fp, "INSERT INTO `{$wpdb->usermeta}` (umeta_id,user_id,meta_key,meta_value) VALUES\n" . implode( ",\n", $batch ) . ";\n" );
+				$batch = array();
+			}
+		}
+		if ( $batch ) {
+			fwrite( $fp, "INSERT INTO `{$wpdb->usermeta}` (umeta_id,user_id,meta_key,meta_value) VALUES\n" . implode( ",\n", $batch ) . ";\n" );
+		}
+		fwrite( $fp, "UNLOCK TABLES;\n" );
+		fwrite( $fp, "SET FOREIGN_KEY_CHECKS=1;\n" );
+		fwrite( $fp, "/*!40101 SET SQL_MODE=@OLD_SQL_MODE */;\n" );
+		fclose( $fp );
+
+		$job['backup_path'] = $backup_path;
+		$this->log(
+			$job,
+			sprintf(
+				'Backup written: %s (%d rows, %s, chmod 0600)',
+				$filename,
+				$count,
+				size_format( filesize( $backup_path ) )
+			)
+		);
+
+		$server = isset( $_SERVER['SERVER_SOFTWARE'] )
+			? strtolower( sanitize_text_field( wp_unslash( (string) $_SERVER['SERVER_SOFTWARE'] ) ) )
+			: '';
+		if ( str_contains( $server, 'nginx' ) ) {
+			$this->log( $job, '⚠ nginx detected: add `location ~ /wp-content/uploads/wpdo-backups/ { deny all; }` to your nginx config — .htaccess does not apply.' );
+		}
+
+		return array( 'status' => 'ok' );
+	}
+
+	/**
+	 * Writes .htaccess, web.config, and index.php deny files into the backup directory.
+	 *
+	 * @param string $backup_dir Absolute path to the backup directory.
+	 * @return void
+	 */
+	private function write_web_deny_files( string $backup_dir ): void {
+		$htaccess = $backup_dir . '/.htaccess';
+		if ( ! file_exists( $htaccess ) ) {
+			file_put_contents( $htaccess, "Require all denied\n" );
+			@chmod( $htaccess, 0644 );
+		}
+
+		$webconfig = $backup_dir . '/web.config';
+		if ( ! file_exists( $webconfig ) ) {
+			file_put_contents(
+				$webconfig,
+				"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<configuration><system.webServer><authorization><deny users=\"*\"/></authorization></system.webServer></configuration>\n"
+			);
+			@chmod( $webconfig, 0644 );
+		}
+
+		$index = $backup_dir . '/index.php';
+		if ( ! file_exists( $index ) ) {
+			file_put_contents( $index, "<?php // Silence is golden.\n" );
+			@chmod( $index, 0644 );
+		}
+	}
+}

includes/migration/phases/class-tmdo-phase-cleanup.php

@@ -0,0 +1,71 @@
+<?php
+/**
+ * Migration phase: remove managed keys from the native meta table.
+ *
+ * @package TMDO
+ * @since 3.0.1
+ */
+
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Deletes all managed meta keys from the EAV table after verifying aeav_only mode.
+ */
+class TMDO_Phase_Cleanup extends TMDO_Migration_Phase_Base {
+
+	/**
+	 * Returns the phase slug.
+	 *
+	 * @return string
+	 */
+	public function name(): string {
+		return 'cleanup';
+	}
+
+	/**
+	 * Executes the phase.
+	 *
+	 * @param array $job Job array (by reference).
+	 * @return array{status: string}
+	 * @throws \RuntimeException If mode is not aeav_only or backup is missing.
+	 */
+	public function execute( array &$job ): array {
+		global $wpdb;
+
+		if ( ! empty( $job['options']['dry_run'] ) ) {
+			$this->log( $job, '↪ Cleanup skipped (dry_run)' );
+			return array( 'status' => 'ok' );
+		}
+
+		$mode = TMDO_Mode_Manager::get( $this->entity_type );
+		if ( TMDO_Mode_Manager::MODE_AEAV_ONLY !== $mode ) {
+			throw new \RuntimeException( "Refusing cleanup — mode is {$mode}, must be aeav_only" );
+		}
+		if ( ! empty( $job['options']['auto_backup'] ) && empty( $job['backup_path'] ) ) {
+			throw new \RuntimeException( 'Refusing cleanup — auto_backup requested but no backup_path on record' );
+		}
+
+		$keys = $this->get_managed_keys();
+		if ( empty( $keys ) ) {
+			$this->log( $job, '↪ No managed keys to clean' );
+			return array( 'status' => 'ok' );
+		}
+
+		$adapter      = TMDO_Entity_Registry::get_adapter( $this->entity_type );
+		$meta_table   = $adapter->get_native_meta_table();
+		$placeholders = implode( ',', array_fill( 0, count( $keys ), '%s' ) );
+		$deleted      = (int) $wpdb->query(
+			$wpdb->prepare( "DELETE FROM `{$meta_table}` WHERE meta_key IN ({$placeholders})", ...$keys )
+		);
+
+		$preflight                      = TMDO_Migration_Orchestrator::preflight();
+		$job['metrics']['eav_rows_now'] = $preflight['eav_rows'];
+		$job['metrics']['ratio_now']    = $preflight['ratio'];
+
+		$this->log( $job, sprintf( 'Cleanup: deleted %d EAV row(s); ratio now %s', $deleted, (string) $preflight['ratio'] ) );
+		return array( 'status' => 'ok' );
+	}
+}

includes/migration/phases/class-tmdo-phase-completed.php

@@ -0,0 +1,53 @@
+<?php
+/**
+ * Migration phase: terminal phase marking the job as successfully completed.
+ *
+ * @package TMDO
+ * @since 3.0.1
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Terminal phase — marks the job as successfully completed.
+ *
+ * Returns 'done' (instead of 'ok') so tick() knows to release the lock and
+ * flush the attention cache without scheduling another tick.
+ */
+class TMDO_Phase_Completed extends TMDO_Migration_Phase_Base {
+
+	/**
+	 * Returns the phase slug.
+	 *
+	 * @return string
+	 */
+	public function name(): string {
+		return 'completed';
+	}
+
+	/**
+	 * Executes the phase.
+	 *
+	 * @param array $job Job array (by reference).
+	 * @return array{status: 'done'}
+	 */
+	public function execute( array &$job ): array {
+		$job['state']            = 'completed';
+		$job['completed_at']     = time();
+		$job['overall_progress'] = 100;
+
+		$this->log(
+			$job,
+			sprintf(
+				'✅ Migration complete — ratio %s → %s (-%.0f%%)',
+				$job['metrics']['ratio_start'],
+				$job['metrics']['ratio_now'],
+				( $job['metrics']['ratio_start'] - $job['metrics']['ratio_now'] ) / max( $job['metrics']['ratio_start'], 0.01 ) * 100
+			)
+		);
+
+		return array( 'status' => 'done' );
+	}
+}

includes/migration/phases/class-tmdo-phase-demote.php

@@ -0,0 +1,57 @@
+<?php
+/**
+ * Migration phase: demote entity mode from aeav_only back to dual_write.
+ *
+ * @package TMDO
+ * @since 3.0.1
+ */
+
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Two-step mode demotion: aeav_only → shadow_read → dual_write.
+ */
+class TMDO_Phase_Demote extends TMDO_Migration_Phase_Base {
+
+	/**
+	 * Returns the phase slug.
+	 *
+	 * @return string
+	 */
+	public function name(): string {
+		return 'demote';
+	}
+
+	/**
+	 * Executes the phase.
+	 *
+	 * @param array $job Job array (by reference).
+	 * @return array{status: string}
+	 * @throws \RuntimeException If mode transition fails.
+	 */
+	public function execute( array &$job ): array {
+		$current = TMDO_Mode_Manager::get( $this->entity_type );
+
+		if ( TMDO_Mode_Manager::MODE_AEAV_ONLY !== $current ) {
+			$this->log( $job, "↪ Demote skipped (mode is {$current}, not aeav_only)" );
+			return array( 'status' => 'ok' );
+		}
+
+		// Two-step demotion: aeav_only → shadow_read → dual_write.
+		$r = TMDO_Mode_Manager::set( $this->entity_type, TMDO_Mode_Manager::MODE_SHADOW_READ );
+		if ( is_wp_error( $r ) ) {
+			throw new \RuntimeException( 'Demote step 1 failed: ' . $r->get_error_message() );
+		}
+
+		$r = TMDO_Mode_Manager::set( $this->entity_type, TMDO_Mode_Manager::MODE_DUAL_WRITE );
+		if ( is_wp_error( $r ) ) {
+			throw new \RuntimeException( 'Demote step 2 failed: ' . $r->get_error_message() );
+		}
+
+		$this->log( $job, 'Mode: aeav_only → dual_write (reads now go to EAV)' );
+		return array( 'status' => 'ok' );
+	}
+}

includes/migration/phases/class-tmdo-phase-diagnose.php

@@ -0,0 +1,54 @@
+<?php
+/**
+ * Migration phase: diagnose current entity state.
+ *
+ * @package TMDO
+ * @since 3.0.1
+ */
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Reads preflight metrics and records them in the job array.
+ */
+class TMDO_Phase_Diagnose extends TMDO_Migration_Phase_Base {
+
+	/**
+	 * Returns the phase slug.
+	 *
+	 * @return string
+	 */
+	public function name(): string {
+		return 'diagnose';
+	}
+
+	/**
+	 * Executes the phase.
+	 *
+	 * @param array $job Job array (by reference).
+	 * @return array{status: string, message?: string}
+	 */
+	public function execute( array &$job ): array {
+		$preflight                      = TMDO_Migration_Orchestrator::preflight();
+		$job['metrics']['eav_rows_now'] = $preflight['eav_rows'];
+		$job['metrics']['ratio_now']    = $preflight['ratio'];
+
+		$this->log(
+			$job,
+			sprintf(
+				'Diagnose: %d EAV residue rows, %d users, ratio %s, mode %s',
+				$preflight['eav_rows'],
+				$preflight['users'],
+				(string) $preflight['ratio'],
+				$preflight['mode']
+			)
+		);
+
+		return array(
+			'status'  => 'ok',
+			'message' => 'Diagnose complete',
+		);
+	}
+}

includes/migration/phases/class-tmdo-phase-install-schema.php

@@ -0,0 +1,55 @@
+<?php
+/**
+ * Migration phase: install flat schema tables for the entity type.
+ *
+ * @package TMDO
+ * @since 3.0.1
+ */
+
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Fires wpdo_register_entity_fields, runs schema migrations, verifies all tables exist.
+ */
+class TMDO_Phase_Install_Schema extends TMDO_Migration_Phase_Base {
+
+	/**
+	 * Returns the phase slug.
+	 *
+	 * @return string
+	 */
+	public function name(): string {
+		return 'install_schema';
+	}
+
+	/**
+	 * Executes the phase.
+	 *
+	 * @param array $job Job array (by reference).
+	 * @return array{status: string}
+	 * @throws \RuntimeException If any required tables are missing after migration.
+	 */
+	public function execute( array &$job ): array {
+		do_action( 'wpdo_register_entity_fields', TMDO_Entity_Registry::class );
+		TMDO_Schema_Manager::process_pending_migrations();
+
+		$missing = array();
+		foreach ( TMDO_Entity_Registry::get_groups_for_type( $this->entity_type ) as $group ) {
+			$table = TMDO_Schema_Manager::get_table_name( $this->entity_type, $group );
+			if ( ! TMDO_Schema_Manager::table_exists( $table ) ) {
+				$missing[] = $group;
+			}
+		}
+
+		if ( $missing ) {
+			throw new \RuntimeException( 'Schema migration failed; missing tables: ' . implode( ',', $missing ) );
+		}
+
+		$count = count( TMDO_Entity_Registry::get_groups_for_type( $this->entity_type ) );
+		$this->log( $job, "Schema migration ok ({$count} flat tables verified)" );
+		return array( 'status' => 'ok' );
+	}
+}

includes/migration/phases/class-tmdo-phase-promote-aeav.php

@@ -0,0 +1,51 @@
+<?php
+/**
+ * Migration phase: promote entity mode to aeav_only (cutover complete).
+ *
+ * @package TMDO
+ * @since 3.0.1
+ */
+
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Transitions mode from shadow_read → aeav_only.
+ */
+class TMDO_Phase_Promote_Aeav extends TMDO_Migration_Phase_Base {
+
+	/**
+	 * Returns the phase slug.
+	 *
+	 * @return string
+	 */
+	public function name(): string {
+		return 'promote_aeav';
+	}
+
+	/**
+	 * Executes the phase.
+	 *
+	 * @param array $job Job array (by reference).
+	 * @return array{status: string}
+	 * @throws \RuntimeException If mode transition fails.
+	 */
+	public function execute( array &$job ): array {
+		$current = TMDO_Mode_Manager::get( $this->entity_type );
+
+		if ( TMDO_Mode_Manager::MODE_AEAV_ONLY === $current ) {
+			$this->log( $job, '↪ Already aeav_only' );
+			return array( 'status' => 'ok' );
+		}
+
+		$r = TMDO_Mode_Manager::set( $this->entity_type, TMDO_Mode_Manager::MODE_AEAV_ONLY );
+		if ( is_wp_error( $r ) ) {
+			throw new \RuntimeException( 'Promote to aeav_only failed: ' . $r->get_error_message() );
+		}
+
+		$this->log( $job, 'Mode: shadow_read → aeav_only (cutover complete)' );
+		return array( 'status' => 'ok' );
+	}
+}

includes/migration/phases/class-tmdo-phase-promote-shadow.php

@@ -0,0 +1,50 @@
+<?php
+/**
+ * Migration phase: promote entity mode to shadow_read.
+ *
+ * @package TMDO
+ * @since 3.0.1
+ */
+
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Transitions mode from dual_write → shadow_read (flat table serves reads).
+ */
+class TMDO_Phase_Promote_Shadow extends TMDO_Migration_Phase_Base {
+
+	/**
+	 * Returns the phase slug.
+	 *
+	 * @return string
+	 */
+	public function name(): string {
+		return 'promote_shadow';
+	}
+
+	/**
+	 * Executes the phase.
+	 *
+	 * @param array $job Job array (by reference).
+	 * @return array{status: string}
+	 * @throws \RuntimeException If mode transition fails.
+	 */
+	public function execute( array &$job ): array {
+		$current = TMDO_Mode_Manager::get( $this->entity_type );
+
+		if ( TMDO_Mode_Manager::MODE_DUAL_WRITE === $current ) {
+			$r = TMDO_Mode_Manager::set( $this->entity_type, TMDO_Mode_Manager::MODE_SHADOW_READ );
+			if ( is_wp_error( $r ) ) {
+				throw new \RuntimeException( 'Promote to shadow_read failed: ' . $r->get_error_message() );
+			}
+			$this->log( $job, 'Mode: dual_write → shadow_read (verifying flat reads)' );
+		} else {
+			$this->log( $job, "↪ Already at {$current}; skip promote_shadow" );
+		}
+
+		return array( 'status' => 'ok' );
+	}
+}

includes/migration/phases/class-tmdo-phase-verify-sample.php

@@ -0,0 +1,140 @@
+<?php
+/**
+ * Migration phase: sample-verify flat table vs EAV for data integrity.
+ *
+ * @package TMDO
+ * @since 3.0.1
+ */
+
+
+if ( ! defined( 'ABSPATH' ) ) {
+	exit;
+}
+
+/**
+ * Samples a subset of entities and compares flat vs EAV values.
+ * Aborts with RuntimeException if any divergences are found.
+ */
+class TMDO_Phase_Verify_Sample extends TMDO_Migration_Phase_Base {
+
+	/**
+	 * Minimum sample size regardless of total entity count.
+	 *
+	 * @var int
+	 */
+	const VERIFY_SAMPLE_MIN = 500;
+
+	/**
+	 * Fraction of total entities to sample in strict mode.
+	 *
+	 * @var float
+	 */
+	const VERIFY_SAMPLE_RATIO = 0.10;
+
+	/**
+	 * Returns the phase slug.
+	 *
+	 * @return string
+	 */
+	public function name(): string {
+		return 'verify_sample';
+	}
+
+	/**
+	 * Executes the phase.
+	 *
+	 * @param array $job Job array (by reference).
+	 * @return array{status: string}
+	 * @throws \RuntimeException If verification divergences are found.
+	 */
+	public function execute( array &$job ): array {
+		global $wpdb;
+
+		if ( ! empty( $job['options']['verify_24h'] ) ) {
+			$elapsed = time() - ( $job['phase_started_at'] ?? time() );
+			if ( ! isset( $job['phase_started_at'] ) ) {
+				$job['phase_started_at'] = time();
+				$this->log( $job, '⏸ 24h shadow_read window started — wizard will resume after window elapses.' );
+				return array( 'status' => 'in_progress' );
+			}
+			if ( $elapsed < DAY_IN_SECONDS ) {
+				return array( 'status' => 'in_progress' );
+			}
+			$this->log( $job, '⏳ 24h shadow_read window complete; running sample compare' );
+		}
+
+		$strict      = ! empty( $job['options']['verify_strict'] );
+		$users_total = (int) $wpdb->get_var( "SELECT COUNT(*) FROM {$wpdb->users}" );
+		$sample_size = $strict
+			? (int) max( self::VERIFY_SAMPLE_MIN, ceil( $users_total * self::VERIFY_SAMPLE_RATIO ) )
+			: 100;
+		$sample_size = min( $sample_size, $users_total );
+		$sample_ids  = $wpdb->get_col(
+			$wpdb->prepare( "SELECT ID FROM {$wpdb->users} ORDER BY RAND() LIMIT %d", $sample_size )
+		);
+
+		$diffs        = 0;
+		$compared     = 0;
+		$managed_keys = $this->get_managed_keys();
+
+		foreach ( $sample_ids as $uid ) {
+			foreach ( $managed_keys as $key ) {
+				$eav = $wpdb->get_var(
+					$wpdb->prepare(
+						"SELECT meta_value FROM {$wpdb->usermeta} WHERE user_id = %d AND meta_key = %s LIMIT 1", // phpcs:ignore WPDO.AntiEAV.no-direct-usermeta-select -- verify phase: must compare EAV source against flat table to confirm migration correctness
+						$uid,
+						$key
+					)
+				);
+
+				// Skip keys with no EAV source-of-truth — only flag when EAV has data
+				// but flat doesn't match (real backfill error).
+				if ( null === $eav || '' === $eav ) {
+					continue;
+				}
+
+				++$compared;
+				$flat = TMDO_Hook_Bus::direct_read( $this->entity_type, (int) $uid, $key );
+
+				if ( ! $this->values_loose_equal( $flat, $eav ) ) {
+					++$diffs;
+					if ( $diffs <= 3 ) {
+						$this->log(
+							$job,
+							sprintf(
+								'  ! diff uid=%d key=%s flat=%s eav=%s',
+								$uid,
+								$key,
+								is_scalar( $flat ) ? (string) $flat : gettype( $flat ),
+								is_scalar( $eav ) ? (string) $eav : gettype( $eav )
+							)
+						);
+					}
+				}
+			}
+		}
+
+		$this->log(
+			$job,
+			sprintf(
+				'Verify: sampled %d users × %d keys = %d compares, %d diff(s)',
+				count( $sample_ids ),
+				count( $managed_keys ),
+				$compared,
+				$diffs
+			)
+		);
+
+		if ( $diffs > 0 ) {
+			throw new \RuntimeException(
+				sprintf(
+					'Verification found %d divergence(s) across %d compares — aborting before destructive cleanup.',
+					$diffs,
+					$compared
+				)
+			);
+		}
+
+		return array( 'status' => 'ok' );
+	}
+}

tests/bootstrap.php

@@ -600,6 +600,19 @@ require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-term.php';
 require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-comment.php';
 
 // Migration Orchestrator (needs Entity_Registry).
+require_once TMDO_PATH . 'includes/migration/interface-migration-phase.php';
+require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-phase-base.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-diagnose.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backup.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-demote.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-install-schema.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-bulk.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-unserialize.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-shadow.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-verify-sample.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-aeav.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-cleanup.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-completed.php';
 require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-orchestrator.php';
 require_once TMDO_PATH . 'includes/migration/class-tmdo-post-migration.php';
 

tests/integration/bootstrap.php

@@ -569,6 +569,19 @@ require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-post.php';
 require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-user.php';
 require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-term.php';
 require_once TMDO_PATH . 'includes/adapters/class-tmdo-adapter-comment.php';
+require_once TMDO_PATH . 'includes/migration/interface-migration-phase.php';
+require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-phase-base.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-diagnose.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backup.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-demote.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-install-schema.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-bulk.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-backfill-unserialize.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-shadow.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-verify-sample.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-promote-aeav.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-cleanup.php';
+require_once TMDO_PATH . 'includes/migration/phases/class-tmdo-phase-completed.php';
 require_once TMDO_PATH . 'includes/migration/class-tmdo-migration-orchestrator.php';
 require_once TMDO_PATH . 'includes/migration/class-tmdo-post-migration.php';
 require_once TMDO_PATH . 'modules/options/class-tmdo-options-manager.php';

tests/unit/MigrationPhaseRemainingTest.php

@@ -0,0 +1,282 @@
+<?php
+declare(strict_types=1);
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Unit tests for the 5 migration phases not covered in MigrationPhaseTest.php
+ * (P1-11): Diagnose, Install_Schema, Backfill_Bulk, Backfill_Unserialize,
+ * Verify_Sample.
+ *
+ * All engine dependencies (WPDO_Schema_Manager, WPDO_Migration_Orchestrator,
+ * WPDO_Entity_Migration_Engine, WPDO_Hook_Bus) use the real classes loaded via
+ * composer autoload. The $wpdb stub returns null/[] for all DB calls, giving
+ * zero-row results sufficient to exercise the logic paths under test.
+ */
+class MigrationPhaseRemainingTest extends TestCase {
+
+	/** @var object Original $wpdb saved for restoration. */
+	private object $original_wpdb;
+
+	protected function setUp(): void {
+		global $wpdb;
+		$this->original_wpdb    = $wpdb;
+		$GLOBALS['_wp_options'] = array();
+		WPDO_Mode_Manager::reset_cache();
+
+		// Provide a fresh $wpdb with all methods the phases under test require,
+		// regardless of which prior test may have left a broken stub.
+		$wpdb = new class {
+			public string $prefix     = 'wp_';
+			public string $users      = 'wp_users';
+			public string $usermeta   = 'wp_usermeta';
+			public string $postmeta   = 'wp_postmeta';
+			public string $options    = 'wp_options';
+			public string $last_error = '';
+			public array  $queries    = [];
+			public function prepare( string $sql, ...$args ): string {
+				$i = 0;
+				return preg_replace_callback( '/%[sd]/', function () use ( &$i, $args ) {
+					return (string) ( $args[ $i++ ] ?? '?' );
+				}, $sql );
+			}
+			public function get_var( string $sql ): ?string { return null; }
+			public function get_col( string $sql ): array { return []; }
+			public function get_results( string $sql, $output = null ): array { return []; }
+			public function query( string $sql ): int|bool { $this->queries[] = $sql; return 1; }
+			public function insert( string $t, array $d, $f = null ): int|false { return 1; }
+			public function get_charset_collate(): string { return ''; }
+		};
+
+		// Reset Schema_Manager request-scoped cache so table_exists() hits $wpdb each test.
+		$ref  = new ReflectionClass( WPDO_Schema_Manager::class );
+		$prop = $ref->getProperty( 'table_exists_cache' );
+		$prop->setAccessible( true );
+		$prop->setValue( null, array() );
+
+		// The unit bootstrap loads Member_Fields / Post_Fields, which register entity
+		// groups at include time. These phases assert "no groups registered" behaviour,
+		// so clear the registry to isolate them from that ambient state.
+		$reg = new ReflectionClass( WPDO_Entity_Registry::class );
+		foreach ( array( 'groups', 'field_index' ) as $name ) {
+			$p = $reg->getProperty( $name );
+			$p->setAccessible( true );
+			$p->setValue( null, array() );
+		}
+
+		// Install_Schema re-fires wpdo_register_entity_fields, which would re-populate
+		// the registry from those same listeners — drop them for the duration.
+		$this->saved_field_listeners                            = $GLOBALS['_wp_filter_callbacks']['wpdo_register_entity_fields'] ?? array();
+		$GLOBALS['_wp_filter_callbacks']['wpdo_register_entity_fields'] = array();
+		WPDO_Entity_Registry::clear_pending_schemas();
+	}
+
+	/**
+	 * Listeners removed in setUp() and restored in tearDown().
+	 *
+	 * @var array
+	 */
+	private array $saved_field_listeners = array();
+
+	protected function tearDown(): void {
+		global $wpdb;
+		$wpdb = $this->original_wpdb;
+
+		$GLOBALS['_wp_filter_callbacks']['wpdo_register_entity_fields'] = $this->saved_field_listeners;
+	}
+
+	private function make_job(): array {
+		return array(
+			'job_id'           => 'test-job',
+			'log'              => array(),
+			'state'            => 'running',
+			'overall_progress' => 0,
+			'metrics'          => array(
+				'ratio_start' => 1.5,
+				'ratio_now'   => 1.5,
+			),
+			'options'          => array(),
+		);
+	}
+
+	// ── WPDO_Phase_Diagnose ───────────────────────────────────────────────────
+
+	public function test_diagnose_name(): void {
+		$phase = new WPDO_Phase_Diagnose( 'user' );
+		$this->assertSame( 'diagnose', $phase->name() );
+	}
+
+	public function test_diagnose_returns_ok(): void {
+		$phase  = new WPDO_Phase_Diagnose( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+	}
+
+	public function test_diagnose_records_eav_rows_in_metrics(): void {
+		// With $wpdb returning null, count_eav_residue() → 0. Key must exist.
+		$phase = new WPDO_Phase_Diagnose( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+		$this->assertArrayHasKey( 'eav_rows_now', $job['metrics'] );
+		$this->assertIsInt( $job['metrics']['eav_rows_now'] );
+	}
+
+	public function test_diagnose_records_ratio_in_metrics(): void {
+		// 0 users → ratio = 0. Key must exist.
+		$phase = new WPDO_Phase_Diagnose( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+		$this->assertArrayHasKey( 'ratio_now', $job['metrics'] );
+	}
+
+	public function test_diagnose_appends_log_entry(): void {
+		$phase = new WPDO_Phase_Diagnose( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+		$this->assertNotEmpty( $job['log'] );
+		$this->assertStringContainsString( 'Diagnose', $job['log'][0] );
+	}
+
+	// ── WPDO_Phase_Install_Schema ─────────────────────────────────────────────
+
+	public function test_install_schema_name(): void {
+		$phase = new WPDO_Phase_Install_Schema( 'user' );
+		$this->assertSame( 'install_schema', $phase->name() );
+	}
+
+	public function test_install_schema_succeeds_when_no_groups_registered(): void {
+		// No groups registered for 'user' in unit-test bootstrap → $missing stays empty.
+		$phase  = new WPDO_Phase_Install_Schema( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+	}
+
+	public function test_install_schema_appends_log_entry(): void {
+		$phase = new WPDO_Phase_Install_Schema( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+		$this->assertNotEmpty( $job['log'] );
+		$this->assertStringContainsString( 'Schema migration ok', $job['log'][0] );
+	}
+
+	// ── WPDO_Phase_Backfill_Bulk ──────────────────────────────────────────────
+
+	public function test_backfill_bulk_name(): void {
+		$phase = new WPDO_Phase_Backfill_Bulk( 'user' );
+		$this->assertSame( 'backfill_bulk', $phase->name() );
+	}
+
+	public function test_backfill_bulk_skips_on_dry_run(): void {
+		$phase  = new WPDO_Phase_Backfill_Bulk( 'user' );
+		$job    = array_merge( $this->make_job(), array( 'options' => array( 'dry_run' => true ) ) );
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertStringContainsString( 'dry_run', $job['log'][0] ?? '' );
+	}
+
+	public function test_backfill_bulk_returns_ok_with_no_groups(): void {
+		// No groups → loop body never executes → 0 groups, 0 rows.
+		$phase  = new WPDO_Phase_Backfill_Bulk( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+		$found_summary = false;
+		foreach ( $job['log'] as $line ) {
+			if ( str_contains( $line, 'Bulk backfill' ) ) {
+				$found_summary = true;
+				$this->assertStringContainsString( '0 groups', $line );
+				break;
+			}
+		}
+		$this->assertTrue( $found_summary, 'Log must contain Bulk backfill summary.' );
+	}
+
+	// ── WPDO_Phase_Backfill_Unserialize ───────────────────────────────────────
+
+	public function test_backfill_unserialize_name(): void {
+		$phase = new WPDO_Phase_Backfill_Unserialize( 'user' );
+		$this->assertSame( 'backfill_unserialize', $phase->name() );
+	}
+
+	public function test_backfill_unserialize_skips_on_dry_run(): void {
+		$phase  = new WPDO_Phase_Backfill_Unserialize( 'user' );
+		$job    = array_merge( $this->make_job(), array( 'options' => array( 'dry_run' => true ) ) );
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertStringContainsString( 'dry_run', $job['log'][0] ?? '' );
+	}
+
+	public function test_backfill_unserialize_returns_ok_with_no_json_groups(): void {
+		// No groups with JSON fields → loop body never executes.
+		$phase  = new WPDO_Phase_Backfill_Unserialize( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+	}
+
+	public function test_backfill_unserialize_appends_total_log_entry(): void {
+		$phase = new WPDO_Phase_Backfill_Unserialize( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+		$this->assertNotEmpty( $job['log'] );
+		$last = end( $job['log'] );
+		$this->assertStringContainsString( 'Row-by-row backfill', $last );
+	}
+
+	// ── WPDO_Phase_Verify_Sample ──────────────────────────────────────────────
+
+	public function test_verify_sample_name(): void {
+		$phase = new WPDO_Phase_Verify_Sample( 'user' );
+		$this->assertSame( 'verify_sample', $phase->name() );
+	}
+
+	public function test_verify_sample_24h_starts_window_when_no_started_at(): void {
+		$phase  = new WPDO_Phase_Verify_Sample( 'user' );
+		$job    = array_merge( $this->make_job(), array( 'options' => array( 'verify_24h' => true ) ) );
+		$result = $phase->execute( $job );
+		$this->assertSame( 'in_progress', $result['status'] );
+		$this->assertArrayHasKey( 'phase_started_at', $job );
+	}
+
+	public function test_verify_sample_24h_stays_in_progress_during_window(): void {
+		$phase = new WPDO_Phase_Verify_Sample( 'user' );
+		$job   = array_merge(
+			$this->make_job(),
+			array(
+				'options'          => array( 'verify_24h' => true ),
+				'phase_started_at' => time() - 3600, // 1 hour ago — still within 24h window
+			)
+		);
+		$result = $phase->execute( $job );
+		$this->assertSame( 'in_progress', $result['status'] );
+	}
+
+	public function test_verify_sample_succeeds_with_zero_users(): void {
+		// $wpdb->get_var() returns null → 0 users → 0 samples → 0 diffs → ok.
+		$phase  = new WPDO_Phase_Verify_Sample( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+	}
+
+	public function test_verify_sample_log_contains_compare_summary(): void {
+		$phase = new WPDO_Phase_Verify_Sample( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+		$found = false;
+		foreach ( $job['log'] as $line ) {
+			if ( str_contains( $line, 'Verify' ) ) {
+				$found = true;
+				break;
+			}
+		}
+		$this->assertTrue( $found, 'Log must contain Verify summary.' );
+	}
+
+	public function test_verify_sample_constants(): void {
+		$this->assertSame( 500, WPDO_Phase_Verify_Sample::VERIFY_SAMPLE_MIN );
+		$this->assertEqualsWithDelta( 0.10, WPDO_Phase_Verify_Sample::VERIFY_SAMPLE_RATIO, 0.0001 );
+	}
+}

tests/unit/MigrationPhaseTest.php

@@ -0,0 +1,272 @@
+<?php
+declare(strict_types=1);
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Unit tests for WPDO_Migration_Phase_Base and WPDO_Phase_Completed.
+ *
+ * WPDO_Phase_Completed is the simplest phase — no external class calls — so it
+ * exercises the full interface contract without mocking infrastructure.
+ */
+class MigrationPhaseTest extends TestCase {
+
+	private function make_job( float $ratio_start = 1.5, float $ratio_now = 0.8 ): array {
+		return array(
+			'job_id'           => 'test-job',
+			'log'              => array(),
+			'state'            => 'running',
+			'overall_progress' => 0,
+			'metrics'          => array(
+				'ratio_start' => $ratio_start,
+				'ratio_now'   => $ratio_now,
+			),
+		);
+	}
+
+	// ── WPDO_Phase_Completed ──────────────────────────────────────────────────
+
+	public function test_completed_returns_done_status(): void {
+		$phase  = new WPDO_Phase_Completed( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+
+		$this->assertSame( 'done', $result['status'] );
+	}
+
+	public function test_completed_sets_state_to_completed(): void {
+		$phase = new WPDO_Phase_Completed( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+
+		$this->assertSame( 'completed', $job['state'] );
+	}
+
+	public function test_completed_sets_overall_progress_to_100(): void {
+		$phase = new WPDO_Phase_Completed( 'user' );
+		$job   = $this->make_job();
+		$phase->execute( $job );
+
+		$this->assertSame( 100, $job['overall_progress'] );
+	}
+
+	public function test_completed_sets_completed_at_timestamp(): void {
+		$before = time();
+		$phase  = new WPDO_Phase_Completed( 'user' );
+		$job    = $this->make_job();
+		$phase->execute( $job );
+
+		$this->assertGreaterThanOrEqual( $before, $job['completed_at'] );
+		$this->assertLessThanOrEqual( time(), $job['completed_at'] );
+	}
+
+	public function test_completed_appends_log_entry(): void {
+		$phase = new WPDO_Phase_Completed( 'user' );
+		$job   = $this->make_job( 1.5, 0.75 );
+		$phase->execute( $job );
+
+		$this->assertNotEmpty( $job['log'] );
+		$last_line = end( $job['log'] );
+		$this->assertStringContainsString( 'Migration complete', $last_line );
+	}
+
+	public function test_completed_name_is_completed(): void {
+		$phase = new WPDO_Phase_Completed( 'user' );
+		$this->assertSame( 'completed', $phase->name() );
+	}
+
+	// ── WPDO_Migration_Phase_Base log truncation ──────────────────────────────
+
+	public function test_log_truncates_at_max_log_lines(): void {
+		$phase = new WPDO_Phase_Completed( 'user' );
+		$job   = $this->make_job();
+
+		// Each execute() appends exactly one log entry — call it MAX+5 times.
+		$max = WPDO_Migration_Phase_Base::MAX_LOG_LINES;
+		for ( $i = 0; $i < $max + 5; $i++ ) {
+			$phase->execute( $job );
+		}
+
+		$this->assertCount( $max, $job['log'] );
+	}
+
+	public function test_log_keeps_most_recent_lines_when_truncating(): void {
+		$phase = new WPDO_Phase_Completed( 'user' );
+		$job   = $this->make_job();
+
+		$max = WPDO_Migration_Phase_Base::MAX_LOG_LINES;
+		for ( $i = 0; $i < $max + 10; $i++ ) {
+			$phase->execute( $job );
+		}
+
+		// Log contains exactly MAX lines with truncation keeping the most recent.
+		$this->assertCount( $max, $job['log'] );
+		// First kept line was written after at least 10 entries were discarded.
+		$first_line = $job['log'][0];
+		$this->assertStringContainsString( 'Migration complete', $first_line );
+	}
+
+	// ── Phase interface contract ───────────────────────────────────────────────
+
+	public function test_phase_implements_interface(): void {
+		$phase = new WPDO_Phase_Completed( 'user' );
+		// Interfaces cannot be class_alias()'d; the phase contract is core-internal
+		// (only the 11 built-in phases implement it), so assert the canonical name.
+		$this->assertInstanceOf( TMDO_Migration_Phase_Interface::class, $phase );
+	}
+
+	public function test_phase_entity_type_injectable(): void {
+		$phase_user = new WPDO_Phase_Completed( 'user' );
+		$phase_term = new WPDO_Phase_Completed( 'term' );
+
+		// Both are independent instances — no shared state.
+		$job_a = $this->make_job();
+		$job_b = $this->make_job();
+		$phase_user->execute( $job_a );
+		$phase_term->execute( $job_b );
+
+		$this->assertSame( 'completed', $job_a['state'] );
+		$this->assertSame( 'completed', $job_b['state'] );
+	}
+
+	// ── Phase_Cleanup — RuntimeException guards (P1-11, highest priority) ────────
+
+	protected function setUp(): void {
+		$GLOBALS['_wp_options'] = [];
+		WPDO_Mode_Manager::reset_cache();
+	}
+
+	private function make_mode_option( string $entity_type, string $mode ): void {
+		$GLOBALS['_wp_options']['wpdo_bridge_modes'] = array( $entity_type => $mode );
+		WPDO_Mode_Manager::reset_cache();
+	}
+
+	public function test_cleanup_throws_when_mode_not_aeav_only(): void {
+		$this->make_mode_option( 'user', 'dual_write' );
+		$phase = new WPDO_Phase_Cleanup( 'user' );
+		$job   = $this->make_job();
+
+		$this->expectException( \RuntimeException::class );
+		$this->expectExceptionMessageMatches( '/must be aeav_only/' );
+		$phase->execute( $job );
+	}
+
+	public function test_cleanup_throws_when_auto_backup_requested_but_no_path(): void {
+		$this->make_mode_option( 'user', 'aeav_only' );
+		$phase = new WPDO_Phase_Cleanup( 'user' );
+		$job   = array_merge(
+			$this->make_job(),
+			array(
+				'options'     => array( 'auto_backup' => true ),
+				'backup_path' => '', // empty — simulates backup that never ran
+			)
+		);
+
+		$this->expectException( \RuntimeException::class );
+		$this->expectExceptionMessageMatches( '/no backup_path on record/' );
+		$phase->execute( $job );
+	}
+
+	public function test_cleanup_skips_when_dry_run(): void {
+		$this->make_mode_option( 'user', 'dual_write' ); // wrong mode, but dry_run should short-circuit first
+		$phase = new WPDO_Phase_Cleanup( 'user' );
+		$job   = array_merge( $this->make_job(), array( 'options' => array( 'dry_run' => true ) ) );
+
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertStringContainsString( 'dry_run', $job['log'][0] ?? '' );
+	}
+
+	// ── Phase_Demote ──────────────────────────────────────────────────────────────
+
+	public function test_demote_skips_when_not_aeav_only(): void {
+		$this->make_mode_option( 'user', 'shadow_read' );
+		$phase  = new WPDO_Phase_Demote( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertStringContainsString( 'skipped', $job['log'][0] ?? '' );
+	}
+
+	public function test_demote_transitions_aeav_only_to_dual_write(): void {
+		$this->make_mode_option( 'user', 'aeav_only' );
+		$phase  = new WPDO_Phase_Demote( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertSame( 'dual_write', WPDO_Mode_Manager::get( 'user' ) );
+	}
+
+	// ── Phase_Backup — skip when auto_backup=false ────────────────────────────────
+
+	public function test_backup_skips_when_auto_backup_false(): void {
+		$phase = new WPDO_Phase_Backup( 'user' );
+		$job   = array_merge( $this->make_job(), array( 'options' => array( 'auto_backup' => false ) ) );
+
+		$result = $phase->execute( $job );
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertStringContainsString( 'skipped', $job['log'][0] ?? '' );
+	}
+
+	// ── Phase_Promote_Aeav ────────────────────────────────────────────────────────
+
+	public function test_promote_aeav_skips_when_already_aeav_only(): void {
+		$this->make_mode_option( 'user', 'aeav_only' );
+		$phase  = new WPDO_Phase_Promote_Aeav( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertStringContainsString( 'Already', $job['log'][0] ?? '' );
+	}
+
+	public function test_promote_aeav_transitions_from_shadow_read(): void {
+		$this->make_mode_option( 'user', 'shadow_read' );
+		$phase  = new WPDO_Phase_Promote_Aeav( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertSame( 'aeav_only', WPDO_Mode_Manager::get( 'user' ) );
+	}
+
+	// ── Phase_Promote_Shadow ──────────────────────────────────────────────────────
+
+	public function test_promote_shadow_transitions_from_dual_write(): void {
+		$this->make_mode_option( 'user', 'dual_write' );
+		$phase  = new WPDO_Phase_Promote_Shadow( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+
+		$this->assertSame( 'ok', $result['status'] );
+		$this->assertSame( 'shadow_read', WPDO_Mode_Manager::get( 'user' ) );
+	}
+
+	public function test_promote_shadow_skips_when_already_at_shadow_or_higher(): void {
+		$this->make_mode_option( 'user', 'aeav_only' );
+		$phase  = new WPDO_Phase_Promote_Shadow( 'user' );
+		$job    = $this->make_job();
+		$result = $phase->execute( $job );
+
+		$this->assertSame( 'ok', $result['status'] );
+		// Mode should be unchanged (already past shadow_read).
+		$this->assertSame( 'aeav_only', WPDO_Mode_Manager::get( 'user' ) );
+	}
+
+	// ── Phase name() contract ─────────────────────────────────────────────────────
+
+	public function test_all_phases_return_expected_names(): void {
+		$cases = array(
+			array( new WPDO_Phase_Backup( 'user' ), 'backup' ),
+			array( new WPDO_Phase_Cleanup( 'user' ), 'cleanup' ),
+			array( new WPDO_Phase_Demote( 'user' ), 'demote' ),
+			array( new WPDO_Phase_Promote_Aeav( 'user' ), 'promote_aeav' ),
+			array( new WPDO_Phase_Promote_Shadow( 'user' ), 'promote_shadow' ),
+		);
+		foreach ( $cases as [ $phase, $expected ] ) {
+			$this->assertSame( $expected, $phase->name() );
+		}
+	}
+}