fix(schema): migrate v4 — await_mechanism column for upgraded installs

Task 7 added await_mechanism to the canonical long_processes schema and
ProcessRepository writes it unconditionally, but DDD_SCHEMA_VERSION stayed
at 3. ddd_maybe_migrate()'s fast path bails for any consumer already at
v3, so dbDelta never re-runs and the column never lands — every process
insert/update then silently fails (return value ignored) and sagas never
persist. Fresh installs were unaffected (dbDelta covers the full schema
on install), which is why existing tests passed.

Bump DDD_SCHEMA_VERSION to 4 and add the v4 explicit migration entry
using the existing v2/v3 idiom (ddd_add_column_if_missing), so consumers
parked at v3 get healed on their next admin_init. Verified against the
shared ddev DB: all real consumers were recorded at v3 with the column
genuinely missing — this is not a theoretical gap.

Author: titustangible

ddd-wordpress/migrations.php

@@ -32,8 +32,9 @@
  *  - 1: original 6 tables
  *  - 2: command_audit gains causation_id + causation_type (+ idx_causation)
  *  - 3: behaviour_workflows gains correlation_id (+ idx_correlation)
+ *  - 4: long_processes gains await_mechanism
  */
-const DDD_SCHEMA_VERSION = 3;
+const DDD_SCHEMA_VERSION = 4;
 
 /**
  * Per-prefix option holding the installed schema version.
@@ -83,6 +84,15 @@ function ddd_explicit_migrations(): array {
       ddd_add_column_if_missing($table, 'correlation_id', 'CHAR(36) NULL', 'is_failed');
       ddd_add_index_if_missing($table, 'idx_correlation', '`correlation_id`');
     },
+
+    // v4 — await_mechanism on long_processes. Additive; dbDelta covers fresh
+    // installs; explicit entry guarantees the column for consumers already at
+    // v3, whose fast-path in ddd_maybe_migrate() would otherwise never
+    // re-run dbDelta and leave ProcessRepository writing to a missing column.
+    4 => static function (IDDDConfig $config): void {
+      $table = $config->table('long_processes');
+      ddd_add_column_if_missing($table, 'await_mechanism', 'JSON NULL', 'match_criteria');
+    },
   ];
 }
 

tests/Unit/WordPress/MigrationsTest.php

@@ -3,9 +3,13 @@
 namespace TangibleDDD\Tests\Unit\WordPress;
 
 use PHPUnit\Framework\TestCase;
+use TangibleDDD\Tests\Fakes\FakeDDDConfig;
 
+use function TangibleDDD\WordPress\ddd_explicit_migrations;
 use function TangibleDDD\WordPress\ddd_pending_migrations;
 
+use const TangibleDDD\WordPress\DDD_SCHEMA_VERSION;
+
 // migrations.php is a procedural ddd-wordpress file; load it directly for the
 // pure-logic test (no WP/DB needed for ddd_pending_migrations).
 if (!function_exists('TangibleDDD\\WordPress\\ddd_pending_migrations')) {
@@ -39,4 +43,36 @@ public function test_installed_ahead_never_runs_backward(): void {
     // Downgrade / weird state must not produce negative or backward work.
     $this->assertSame([], ddd_pending_migrations(3, 2));
   }
+
+  public function test_current_schema_version_is_4(): void {
+    // Regression guard for the v3-fast-path bug: a consumer already recorded
+    // as v3 must NOT be treated as up to date once await_mechanism ships.
+    $this->assertSame(4, DDD_SCHEMA_VERSION);
+  }
+
+  public function test_v4_migration_adds_await_mechanism_after_match_criteria_on_long_processes(): void {
+    $migrations = ddd_explicit_migrations();
+    $this->assertArrayHasKey(4, $migrations, 'ddd_explicit_migrations() must define a v4 entry so consumers already at v3 actually get the column.');
+
+    // Spy wpdb: report the column as absent (get_var => 0) so the guarded
+    // helper proceeds to the ALTER, and capture the SQL it issues.
+    $spy = new class extends \wpdb {
+      public array $queries = [];
+      public function get_var(?string $query = null, int $x = 0, int $y = 0) {
+        return 0;
+      }
+      public function query(string $query) {
+        $this->queries[] = $query;
+        return true;
+      }
+    };
+    $GLOBALS['wpdb'] = $spy;
+
+    $migrations[4](new FakeDDDConfig());
+
+    $this->assertCount(1, $spy->queries);
+    $this->assertStringContainsString('wp_test_long_processes', $spy->queries[0]);
+    $this->assertStringContainsString('ADD COLUMN `await_mechanism` JSON NULL', $spy->queries[0]);
+    $this->assertStringContainsString('AFTER `match_criteria`', $spy->queries[0]);
+  }
 }