v2: add static facade methods to Workflow authoring class (#171 phase 1)

Mirror the helpers under Workflow\V2\functions.php as static methods on
the Workflow abstract base class so v2 authors can write:

    use Workflow\V2\Workflow;

    final class MyWorkflow extends Workflow
    {
        public function handle(): mixed
        {
            $result = Workflow::activity(SendEmail::class, $input);
            Workflow::timer('5 seconds');
            Workflow::upsertMemo(['stage' => 'done']);

            return $result;
        }
    }

Each static is a thin delegate to the equivalent namespaced helper
(activity, child, async, all, parallel, await, awaitWithTimeout,
awaitSignal, timer, sideEffect, continueAsNew, getVersion, upsertMemo,
upsertSearchAttributes, seconds/minutes/hours/days/weeks/months/years,
plus executeActivity and executeChildWorkflow aliases). The namespaced
helpers remain in place as the functional-style alternative.

The existing instance convenience `$this->child()` — which returns the
most recently spawned ChildWorkflowHandle — conflicted with the new
static `Workflow::child(...)` spawn API. Renamed the instance method to
`$this->lastChild()` and updated the four V2 test fixtures that used
it. No v1 back-compat shim is needed because v2 is unpublished.

Also update the v2 scaffolding stub to show Workflow:: usage in a
commented example so new workflows ship with the facade-idiomatic form.

docs/api-stability.md now documents the authoring facade as part of the
v2 public API surface alongside the Contracts\* interfaces and the
server-facing Support\* stability list.

Deferred from #171 to a follow-up: `Workflow::now()` (needs new
deterministic workflow-time machinery), and the `startActivity` /
`startChild` fire-and-forget variants (not yet represented in the
runtime primitives).

Refs #294 (blocker), #171.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: durable-workflow-ops

docs/api-stability.md

@@ -71,6 +71,34 @@ Additive changes — new public methods, new optional parameters with
 defaults, new constants — are minor-version changes and do not require a
 major bump.
 
+## `Workflow\V2\Workflow` authoring facade
+
+The abstract base class `Workflow\V2\Workflow` is the canonical authoring
+API for v2 workflows. It exposes two surfaces, both covered by the
+semver guarantee:
+
+- **Instance members** applications rely on inside an `execute()` /
+  `handle()` method: `workflowId()`, `runId()`, `lastChild()`,
+  `children()`, `historyLength()`, `historySize()`, `shouldContinueAsNew()`,
+  `addCompensation()`, `setParallelCompensation()`,
+  `setContinueWithError()`, `compensate()`, and the public properties
+  `$run`, `$connection`, `$queue`.
+- **Static method facade** mirroring the helpers in
+  `Workflow\V2\functions.php`: `activity`, `executeActivity`, `child`,
+  `executeChildWorkflow`, `async`, `all`, `parallel`, `await`,
+  `awaitWithTimeout`, `awaitSignal`, `timer`, `sideEffect`,
+  `continueAsNew`, `getVersion`, `upsertMemo`, `upsertSearchAttributes`,
+  and the timer sugar `seconds`/`minutes`/`hours`/`days`/`weeks`/
+  `months`/`years`.
+
+The namespaced helper functions under `Workflow\V2\*` remain the
+equivalent functional-style surface and are equally stable. Choosing
+between the static facade and the namespaced helpers is a style
+preference; both produce identical `Support\*` Call value objects.
+
+Adding new static methods to the facade is an additive (non-breaking)
+change. Removing or renaming a documented method is a major change.
+
 ## Pre-existing `Contracts\*` interfaces
 
 Interfaces under `Workflow\V2\Contracts\*` are the preferred extension

src/Commands/stubs/workflow.v2.stub

@@ -12,6 +12,13 @@ class {{ class }} extends Workflow
 {
     public function handle(): mixed
     {
+        // Example:
+        //
+        //     $result = Workflow::activity(MyActivity::class, $input);
+        //     Workflow::timer('5 seconds');
+        //     Workflow::upsertMemo(['stage' => 'done']);
+        //
+        //     return $result;
         return null;
     }
 }

src/V2/Workflow.php

@@ -4,12 +4,41 @@
 
 namespace Workflow\V2;
 
+use Carbon\CarbonInterval;
 use Throwable;
 use Workflow\Traits\ResolvesMethodDependencies;
 use Workflow\V2\Models\WorkflowRun;
 use Workflow\V2\Support\ChildWorkflowHandles;
 use Workflow\V2\Support\HistoryBudget;
 
+/**
+ * Base class for v2 workflows.
+ *
+ * Application workflows extend this class and implement an `execute` (or
+ * `handle`) entry method. The class also exposes the v2 authoring API as
+ * a static facade so workflow code can read like:
+ *
+ *     use Workflow\V2\Workflow;
+ *
+ *     class MyWorkflow extends Workflow
+ *     {
+ *         public function execute(): mixed
+ *         {
+ *             $result = Workflow::activity(MyActivity::class, 'arg');
+ *             Workflow::timer('5 seconds');
+ *             Workflow::upsertMemo(['stage' => 'finalizing']);
+ *
+ *             return $result;
+ *         }
+ *     }
+ *
+ * Each static method is a thin delegate to the equivalent namespaced
+ * helper under `Workflow\V2\*` — authors can pick either style.
+ *
+ * @api Stable v2 authoring API. Adding new static methods is an additive
+ *      (non-breaking) change; removing or renaming a documented method
+ *      requires a major version bump. See docs/api-stability.md.
+ */
 abstract class Workflow
 {
     use ResolvesMethodDependencies;
@@ -44,7 +73,16 @@ public function runId(): string
         return $this->run->id;
     }
 
-    public function child(): ?ChildWorkflowHandle
+    /**
+     * The handle for the most recently spawned child workflow, or null if
+     * this workflow has not spawned any children yet.
+     *
+     * Renamed from `child()` in v2 so the `Workflow::child(...)` static
+     * facade can spawn child workflows. Use `lastChild()` for the handle
+     * lookup and `Workflow::child(...)` / `Workflow::executeChildWorkflow(...)`
+     * to spawn a new child.
+     */
+    public function lastChild(): ?ChildWorkflowHandle
     {
         $children = $this->children();
 
@@ -141,4 +179,220 @@ public function setCommandDispatchEnabled(bool $enabled): void
     {
         $this->commandDispatchEnabled = $enabled;
     }
+
+    // ── Static authoring facade ─────────────────────────────────────────────
+    //
+    // The static methods below delegate to the namespaced helpers under
+    // `Workflow\V2\*` (see src/V2/functions.php). They exist so workflow
+    // authors can use the more conventional `Workflow::timer(...)` form
+    // without an extra import. See the class docblock for example usage.
+    //
+    // These are pure delegates. Behaviour, determinism guarantees, and
+    // operand/return types come from the underlying helper functions.
+
+    /**
+     * Invoke an activity and wait for its result.
+     *
+     * @see activity()
+     */
+    public static function activity(string $activity, mixed ...$arguments): mixed
+    {
+        return activity($activity, ...$arguments);
+    }
+
+    /**
+     * Alias for {@see activity()} matching Temporal's `executeActivity` name.
+     */
+    public static function executeActivity(string $activity, mixed ...$arguments): mixed
+    {
+        return activity($activity, ...$arguments);
+    }
+
+    /**
+     * Invoke a child workflow and wait for its result.
+     *
+     * @see child()
+     */
+    public static function child(string $workflow, mixed ...$arguments): mixed
+    {
+        return child($workflow, ...$arguments);
+    }
+
+    /**
+     * Alias for {@see child()} matching Temporal's `executeChildWorkflow` name.
+     */
+    public static function executeChildWorkflow(string $workflow, mixed ...$arguments): mixed
+    {
+        return child($workflow, ...$arguments);
+    }
+
+    /**
+     * Run a callable as an auto-generated child workflow.
+     *
+     * @see async()
+     */
+    public static function async(callable $callback): mixed
+    {
+        return async($callback);
+    }
+
+    /**
+     * Await a list of concurrent calls and return their resolved results in
+     * iteration order.
+     *
+     * @see all()
+     */
+    public static function all(iterable $calls): mixed
+    {
+        return all($calls);
+    }
+
+    /**
+     * Alias for {@see all()} matching the "run these in parallel" intent.
+     */
+    public static function parallel(iterable $calls): mixed
+    {
+        return all($calls);
+    }
+
+    /**
+     * Wait for a condition closure to become truthy, for a signal by name,
+     * or for either plus a timeout.
+     *
+     * @see await()
+     */
+    public static function await(
+        callable|string $condition,
+        int|string|CarbonInterval|null $timeout = null,
+        ?string $conditionKey = null,
+    ): mixed {
+        return await($condition, $timeout, $conditionKey);
+    }
+
+    /**
+     * Wait for a condition or signal with an explicit timeout, failing the
+     * await when the timeout elapses.
+     */
+    public static function awaitWithTimeout(
+        int|string|CarbonInterval $timeout,
+        callable|string $condition,
+        ?string $conditionKey = null,
+    ): mixed {
+        return await($condition, $timeout, $conditionKey);
+    }
+
+    /**
+     * Wait for a named signal. Equivalent to `await(<signal name>)`.
+     */
+    public static function awaitSignal(string $name): mixed
+    {
+        return await($name);
+    }
+
+    /**
+     * Suspend until a timer fires.
+     *
+     * @see timer()
+     */
+    public static function timer(int|string|CarbonInterval $duration): mixed
+    {
+        return timer($duration);
+    }
+
+    /**
+     * Capture the result of a side-effect closure in history so replay
+     * returns the same value on subsequent attempts.
+     *
+     * @see sideEffect()
+     */
+    public static function sideEffect(callable $callback): mixed
+    {
+        return sideEffect($callback);
+    }
+
+    /**
+     * Terminate the current run by starting a new one with the provided
+     * arguments, preserving workflow instance identity.
+     *
+     * @see continueAsNew()
+     */
+    public static function continueAsNew(mixed ...$arguments): mixed
+    {
+        return continueAsNew(...$arguments);
+    }
+
+    /**
+     * Declare a workflow-code versioning change and receive the negotiated
+     * version for the current run.
+     *
+     * @see getVersion()
+     */
+    public static function getVersion(
+        string $changeId,
+        int $minSupported = WorkflowStub::DEFAULT_VERSION,
+        int $maxSupported = 1,
+    ): mixed {
+        return getVersion($changeId, $minSupported, $maxSupported);
+    }
+
+    /**
+     * Upsert non-indexed memo metadata on the current workflow run.
+     *
+     * @param array<string, mixed> $entries
+     *
+     * @see upsertMemo()
+     */
+    public static function upsertMemo(array $entries): void
+    {
+        upsertMemo($entries);
+    }
+
+    /**
+     * Upsert indexed search attributes on the current workflow run.
+     *
+     * @param array<string, scalar|null> $attributes
+     *
+     * @see upsertSearchAttributes()
+     */
+    public static function upsertSearchAttributes(array $attributes): void
+    {
+        upsertSearchAttributes($attributes);
+    }
+
+    // Timer sugar --------------------------------------------------------
+
+    public static function seconds(int $seconds): mixed
+    {
+        return seconds($seconds);
+    }
+
+    public static function minutes(int $minutes): mixed
+    {
+        return minutes($minutes);
+    }
+
+    public static function hours(int $hours): mixed
+    {
+        return hours($hours);
+    }
+
+    public static function days(int $days): mixed
+    {
+        return days($days);
+    }
+
+    public static function weeks(int $weeks): mixed
+    {
+        return weeks($weeks);
+    }
+
+    public static function months(int $months): mixed
+    {
+        return months($months);
+    }
+
+    public static function years(int $years): mixed
+    {
+        return years($years);
+    }
 }

tests/Fixtures/V2/TestChildHandleParentWorkflow.php

@@ -27,7 +27,7 @@ public function handle(): array
     #[QueryMethod('current-child-handle')]
     public function currentChildHandle(): ?array
     {
-        $handle = $this->child();
+        $handle = $this->lastChild();
 
         if ($handle === null) {
             return null;
@@ -43,6 +43,6 @@ public function currentChildHandle(): ?array
     #[UpdateMethod('approve-child')]
     public function approveChild(string $approvedBy): void
     {
-        $this->child()?->signal('approved-by', $approvedBy);
+        $this->lastChild()?->signal('approved-by', $approvedBy);
     }
 }

tests/Fixtures/V2/TestParallelChildHandlesWorkflow.php

@@ -38,7 +38,7 @@ public function childHandles(): array
     #[QueryMethod('latest-child-handle')]
     public function latestChildHandle(): ?array
     {
-        $handle = $this->child();
+        $handle = $this->lastChild();
 
         if ($handle === null) {
             return null;

tests/Fixtures/V2/TestParentWaitingOnContinuingChildWorkflow.php

@@ -26,7 +26,7 @@ public function handle(int $count = 0, int $max = 1): array
     #[QueryMethod('current-child-handle')]
     public function currentChildHandle(): ?array
     {
-        $handle = $this->child();
+        $handle = $this->lastChild();
 
         if ($handle === null) {
             return null;

tests/Fixtures/V2/TestQueryChildResolutionAuthorityWorkflow.php

@@ -31,7 +31,7 @@ public function handle(int $seconds): array
     #[QueryMethod('current-state')]
     public function currentState(): array
     {
-        $handle = $this->child();
+        $handle = $this->lastChild();
 
         return [
             'stage' => $this->stage,