feat(wordpress): fold process discovery into register_hooks (0.2.2) (#12)

boot() now truly is the whole ceremony: register_hooks() reads the
ddd.long_process container tag (guarded by findTaggedServiceIds, same
style as the handler sweep) and registers every tagged LongProcess —
plus resume hooks for its #[Awaits] events — with the ProcessRunner.

Previously discovery was a separate manual call consumers had to
remember: datastream made it, cred declared a privately-named tag
(tgbl.long_process) that nothing ever scanned. The scaffolder now emits
the _instanceof rule so fresh consumers are saga-ready, and the wiring
guide documents the tag-name and manual-call anti-patterns.

Double registration stays safe: ProcessRunner::register_event is
idempotent per event class on the shared runner instance.

Co-authored-by: Titus TC <titus@teamtangible.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: 3 people

ddd-wordpress/cli/class-ddd-command.php

@@ -554,6 +554,13 @@ private function template_services_yaml( string $prefix, string $namespace, stri
     autoconfigure: true
     public: true
 
+  # Every LongProcess subclass is auto-tagged; boot() discovers the tag at
+  # init:2 and registers each process (plus the resume hooks for its
+  # #[Awaits] events) with the ProcessRunner. No per-saga wiring needed.
+  _instanceof:
+    TangibleDDD\\Application\\Process\\LongProcess:
+      tags: ['ddd.long_process']
+
   # Config
   # Version is wired via the {$prefix}.version container parameter set in di/index.php
   # (sourced from the {$version_const} PHP constant when defined).

ddd-wordpress/hooks.php

@@ -54,6 +54,19 @@ function register_hooks(IDDDConfig $config, callable $di_getter): void {
   ConsumerRegistry::add($config, $di_getter);
   register_event_handlers($di_getter);
   register_process_hooks($config, $di_getter);
+
+  // Process discovery: register ddd.long_process-tagged classes (and the
+  // resume hooks for their #[Awaits] events) with the ProcessRunner. Needs
+  // findTaggedServiceIds — a ContainerBuilder API — so containers that don't
+  // expose it (dumped/opaque) skip discovery, same guard style as
+  // register_event_handlers' getServiceIds probe above.
+  if (processes_enabled($config)) {
+    $container = $di_getter();
+    if (method_exists($container, 'findTaggedServiceIds')) {
+      register_processes_from_container($config, $container);
+    }
+  }
+
   register_outbox_hooks($config, $di_getter);
   register_migration_hooks($config);
 }

docs/wiring-a-consumer.md

@@ -198,15 +198,38 @@ regardless of which features it uses today:
 | `register_event_handlers` | async handlers + `IntegrationListener`s never `add_action` (Symfony DI is lazy) — AS fails with "no callbacks registered" |
 | `register_outbox_hooks` | **outbox never drains** — integration events written, never delivered (this exact bug shipped twice) |
 | `register_process_hooks` | sagas never resume after the AS hop |
+| process discovery | saga classes never registered with the `ProcessRunner` — awaited integration events fire but wake nothing (see below) |
 | `register_migration_hooks` | framework schema migrations never run — fresh installs never get their tables (the lane runs on `init` + `admin_init`; it replaces the activation hook entirely), upgraded installs drift |
 
+**Process discovery** (0.2.2): `register_hooks()` reads the
+`ddd.long_process` container tag and registers every tagged class — plus
+the resume hooks for its `#[Awaits(Event::class)]` events — with the
+`ProcessRunner`. The consumer's only job is the `_instanceof` rule the
+scaffolder already emits:
+
+```yaml
+_instanceof:
+  TangibleDDD\Application\Process\LongProcess:
+    tags: ['ddd.long_process']
+```
+
+Discovery needs `findTaggedServiceIds()` (a `ContainerBuilder` API) — with a
+dumped/opaque container it is skipped silently, same guard as the handler
+sweep. Declare awaited events with the `#[Awaits]` class attribute, not tag
+parameters.
+
 Anti-patterns seen in the wild:
 
 - **À-la-carte calls** (`register_process_hooks` + `register_outbox_hooks`
   only) — silently skips migrations and eager handler boot.
 - **Homegrown eager-boot registrars** duplicating `register_event_handlers`
   by iterating service ids. Delete them; the framework function covers
   `\Application\EventHandlers\` and `\Application\IntegrationListeners\`.
+- **Manual `register_processes_from_container()` calls** in consumer
+  bootstrap — redundant since 0.2.2 (idempotent, but delete on next touch).
+- **Consumer-prefixed process tags** (`acme.long_process`) — the framework
+  scans `ddd.long_process` only; a private tag name means your sagas are
+  never discovered.
 
 ## 7. Events — 0.2.0 taxonomy in four rules
 

tangible-ddd.php

@@ -3,7 +3,7 @@
  * Plugin Name: Tangible DDD
  * Plugin URI: https://tangible.one
  * Description: Domain-Driven Design framework for WordPress plugins
- * Version: 0.2.1
+ * Version: 0.2.2
  * Author: Tangible
  * Author URI: https://tangible.one
  * License: MIT
@@ -38,7 +38,7 @@
 // Guarded: the first copy to load wins the constant (oldest-loads-first is fine;
 // the registry, not the constant, determines the winner).
 if (!defined('TANGIBLE_DDD_VERSION')) {
-    define('TANGIBLE_DDD_VERSION', '0.2.1');
+    define('TANGIBLE_DDD_VERSION', '0.2.2');
 }
 
 // ─── Tangible_DDD_Versions registry (defined once, first copy wins the class) ─
@@ -87,7 +87,7 @@ public static function instance(): self
         /**
          * Register a copy of tangible-ddd.
          *
-         * @param string      $version      SemVer string (e.g. '0.2.1').
+         * @param string      $version      SemVer string (e.g. '0.2.2').
          * @param string      $path         Absolute path to the ddd plugin root.
          * @param callable    $initialize   Callback that boots THIS copy: receives $path.
          * @param string|null $min_required Minimum ddd version this consumer needs.
@@ -223,42 +223,42 @@ public function is_initialized(): bool
 } // if (!class_exists('Tangible_DDD_Versions'))
 
 // ─── Version-named register function (guarded — safe in N copies) ────────────
-// Slug: 0.2.1 → 0_2_1  (dots and hyphens → underscores)
-if (!function_exists('tangible_ddd_register_0_2_1')) {
+// Slug: 0.2.2 → 0_2_2  (dots and hyphens → underscores)
+if (!function_exists('tangible_ddd_register_0_2_2')) {
 
     /**
-     * Register this copy (0.2.1) into Tangible_DDD_Versions.
+     * Register this copy (0.2.2) into Tangible_DDD_Versions.
      * Hooked at plugins_loaded priority 0 so all copies register before pri-1 wins.
      */
-    function tangible_ddd_register_0_2_1(): void
+    function tangible_ddd_register_0_2_2(): void
     {
         // Pass a closure so the callable type check passes even when this register
-        // function is invoked before tangible_ddd_initialize_0_2_1() is defined
+        // function is invoked before tangible_ddd_initialize_0_2_2() is defined
         // (which can happen in unit-test context where add_action is absent and we
         // self-register immediately at file-include time).
         Tangible_DDD_Versions::instance()->register(
-            '0.2.1',
+            '0.2.2',
             __DIR__,
             static function (string $path): void {
-                tangible_ddd_initialize_0_2_1($path);
+                tangible_ddd_initialize_0_2_2($path);
             }
         );
     }
 
     if (function_exists('add_action')) {
-        add_action('plugins_loaded', 'tangible_ddd_register_0_2_1', 0, 0);
+        add_action('plugins_loaded', 'tangible_ddd_register_0_2_2', 0, 0);
     } else {
         // Outside WP (unit tests / direct require with no hook system):
         // self-register immediately.  initialize_latest() is NOT called here
         // so that N copies included during tests can each register first;
         // test code can call Tangible_DDD_Versions::instance()->initialize_latest()
         // explicitly, or the bootstrap triggers it below.
-        tangible_ddd_register_0_2_1();
+        tangible_ddd_register_0_2_2();
     }
 }
 
 // ─── Version-named initializer (guarded — the winner calls this) ──────────────
-if (!function_exists('tangible_ddd_initialize_0_2_1')) {
+if (!function_exists('tangible_ddd_initialize_0_2_2')) {
 
     /**
      * Boot this copy of tangible-ddd as the site winner.
@@ -269,7 +269,7 @@ static function (string $path): void {
      *
      * @param string $path Absolute path to the winning ddd plugin root.
      */
-    function tangible_ddd_initialize_0_2_1(string $path): void
+    function tangible_ddd_initialize_0_2_2(string $path): void
     {
         // (a) Prepend autoloader — winner's classes beat consumer psr-4 maps.
         spl_autoload_register(
@@ -386,6 +386,6 @@ function_exists('did_action')   && did_action('plugins_loaded')
     && function_exists('doing_action') && !doing_action('plugins_loaded')
     && !Tangible_DDD_Versions::instance()->is_initialized()
 ) {
-    tangible_ddd_register_0_2_1();
+    tangible_ddd_register_0_2_2();
     Tangible_DDD_Versions::instance()->initialize_latest();
 }

tests/Unit/WordPress/BootTest.php

@@ -3,7 +3,12 @@
 namespace TangibleDDD\Tests\Unit\WordPress;
 
 use PHPUnit\Framework\TestCase;
+use TangibleDDD\Application\Process\ProcessRunner;
+use TangibleDDD\Infra\IDDDConfig;
 use TangibleDDD\Tests\Fakes\FakeDDDConfig;
+use TangibleDDD\Tests\Fakes\FakeGatherProcess;
+use TangibleDDD\Tests\Fakes\FakeProcessRepository;
+use TangibleDDD\Tests\Fakes\FakeResolvedEvent;
 use TangibleDDD\WordPress\ConsumerRegistry;
 
 use function TangibleDDD\WordPress\boot;
@@ -107,4 +112,49 @@ public function test_consumers_pass_through_the_filter(): void {
 
     $this->assertSame([], consumers());
   }
+
+  public function test_register_hooks_discovers_tagged_long_processes(): void {
+    global $_test_actions;
+
+    // Unique prefix so processes_enabled()'s static cache (keyed by prefix,
+    // poisoned to false by the other tests' stub wpdb) probes fresh.
+    $config = new class implements IDDDConfig {
+      public function prefix(): string { return 'proc'; }
+      public function table(string $name): string { return 'wp_proc_' . $name; }
+      public function hook(string $name): string { return 'proc_' . $name; }
+      public function as_group(string $name): string { return 'proc-' . $name; }
+      public function option(string $name): string { return 'proc_' . $name; }
+      public function domain_action(string $event_name): string { return 'proc_domain_' . $event_name; }
+      public function integration_action(string $event_name): string { return 'proc_integration_' . $event_name; }
+      public function version(): string { return 'proc'; }
+    };
+
+    // Answer every SHOW TABLES probe with the long_processes table name:
+    // the process gate opens, the outbox gate (comparing against its own
+    // table name) stays closed.
+    $GLOBALS['wpdb'] = new class extends \wpdb {
+      public function get_var(?string $query = null, int $x = 0, int $y = 0) {
+        return 'wp_proc_long_processes';
+      }
+    };
+
+    $runner = new ProcessRunner($config, new FakeProcessRepository());
+    $container = new class($runner) {
+      public function __construct(private readonly ProcessRunner $runner) {}
+      public function getServiceIds(): array { return []; }
+      public function findTaggedServiceIds(string $tag): array {
+        return 'ddd.long_process' === $tag
+          ? [FakeGatherProcess::class => [[]]]
+          : [];
+      }
+      public function get(string $id): ProcessRunner { return $this->runner; }
+    };
+
+    \TangibleDDD\WordPress\register_hooks($config, static fn () => $container);
+
+    $this->assertNotEmpty(
+      $_test_actions[FakeResolvedEvent::integration_action()] ?? [],
+      'register_hooks must wire resume hooks for the #[Awaits] events of ddd.long_process-tagged classes',
+    );
+  }
 }