durable-workflow.github.io: update v2 changes

Author: durable-workflow-ops

docs/configuration/microservices.md

@@ -283,9 +283,9 @@ POST /webhooks/activity-attempts/{attemptId}/complete
 POST /webhooks/activity-attempts/{attemptId}/fail
 ```
 
-The poll route accepts optional `connection`, `queue`, `limit` (1–100, default 10), and `compatibility` query parameters. It returns the same task summary list as the PHP `poll()` method, wrapped in a `{"tasks": [...]}` envelope. A standalone server uses this route to discover ready activity tasks before claiming them by id.
+The poll route accepts optional `connection`, `queue`, `limit` (1–100, default 10), `compatibility`, and `namespace` query parameters. It returns the same task summary list as the PHP `poll()` method, wrapped in a `{"tasks": [...]}` envelope. A standalone server uses this route to discover ready activity tasks before claiming them by id.
 
-That HTTP surface is still the same first bridge, not a complete hosted cross-language worker service. It does not yet provide long-poll claim loops, namespaces, or service-level routing. External workers should integrate through durable task ids, execution ids, attempt ids, codec-tagged payloads, heartbeats, completion or failure records, and late-result handling. They should not depend on mirroring placeholder PHP classes or sharing queue-serialized PHP payloads as the protocol boundary.
+That HTTP surface is still the same first bridge, not a complete hosted cross-language worker service. It does not yet provide long-poll claim loops or service-level routing. Namespace scoping is supported at the package level through `poll()` and visibility filters; the HTTP poll routes accept a `namespace` query parameter. External workers should integrate through durable task ids, execution ids, attempt ids, codec-tagged payloads, heartbeats, completion or failure records, and late-result handling. They should not depend on mirroring placeholder PHP classes or sharing queue-serialized PHP payloads as the protocol boundary.
 
 ## Workflow Task Boundary
 
@@ -463,7 +463,7 @@ Serialized values (`result`, `arguments`) should match the run's `payload_codec`
 
 The default implementation is `Workflow\V2\Support\DefaultWorkflowTaskBridge`. Apps that need custom claim, lease, or execution behavior can bind their own implementation of `Workflow\V2\Contracts\WorkflowTaskBridge` in the container.
 
-The workflow task bridge uses the same backend/compatibility checks, task lease semantics, and summary projection as the default `RunWorkflowTask` queue job. It does not yet provide long-poll discovery or namespace routing.
+The workflow task bridge uses the same backend/compatibility checks, task lease semantics, and summary projection as the default `RunWorkflowTask` queue job. It supports namespace filtering through the `namespace` parameter on `poll()`. It does not yet provide long-poll discovery.
 
 ### HTTP routes
 
@@ -479,7 +479,7 @@ POST /webhooks/workflow-tasks/{taskId}/fail
 POST /webhooks/workflow-tasks/{taskId}/heartbeat
 ```
 
-**Poll** discovers ready workflow tasks. Accepts optional `connection`, `queue`, `limit` (1–100, default 10), and `compatibility` query parameters. Returns `{"tasks": [...]}` with the same task summary shape as the PHP `poll()` method.
+**Poll** discovers ready workflow tasks. Accepts optional `connection`, `queue`, `limit` (1–100, default 10), `compatibility`, and `namespace` query parameters. Returns `{"tasks": [...]}` with the same task summary shape as the PHP `poll()` method.
 
 **Claim** creates a lease on a ready workflow task. Pass an optional `lease_owner` string in the request body. Returns the claim payload on success or a rejection reason on failure:
 
@@ -564,6 +564,7 @@ Options:
 - `arguments` — codec-tagged serialized arguments (string)
 - `connection` — queue connection override
 - `queue` — queue name override
+- `namespace` — execution namespace for multi-namespace isolation (falls back to `WORKFLOW_V2_NAMESPACE` config)
 - `business_key` — caller-supplied business key
 - `labels` — visibility labels for fleet search
 - `memo` — non-indexed metadata
@@ -668,6 +669,7 @@ if ($result['found']) {
     // Instance metadata
     $result['workflow_instance_id'];  // 'order-12345'
     $result['workflow_type'];         // 'order-processing'
+    $result['namespace'];             // 'production' or null
     $result['business_key'];          // 'order-12345'
     $result['run_count'];             // 1
 

docs/configuration/options.md

@@ -71,6 +71,56 @@ The `$timeout` setting is used to control the maximum number of seconds an activ
 
 The `backoff` method returns an array of integers corresponding to the current attempt. The default `backoff` method decays exponentially to 2 minutes. This can be overridden by implementing the `backoff` method on the activity class.
 
+## Namespace
+
+Workflows can be scoped to a namespace for multi-namespace isolation. When a namespace is configured, it is persisted on every workflow instance, run, task, and run-summary projection created through the control plane. Task bridge polling and Waterline visibility filters can then restrict results to a single namespace.
+
+Set the default namespace via environment variable:
+
+```env
+WORKFLOW_V2_NAMESPACE=production
+```
+
+Or in `config/workflows.php`:
+
+```php
+'v2' => [
+    'namespace' => env('WORKFLOW_V2_NAMESPACE'),
+    // ...
+],
+```
+
+The control plane also accepts a per-call namespace override in the `start()` options:
+
+```php
+$controlPlane->start('order-processing', 'order-12345', [
+    'namespace' => 'staging',
+    // ...
+]);
+```
+
+When no namespace is configured and none is passed explicitly, instances have a `null` namespace and are visible to all consumers.
+
+### Waterline namespace scoping
+
+When Waterline is deployed against a shared database with multiple namespaces, set `WATERLINE_NAMESPACE` to restrict all list views to one namespace:
+
+```env
+WATERLINE_NAMESPACE=production
+```
+
+This injects a namespace filter into every visibility query so Waterline only shows workflows belonging to the configured namespace.
+
+### Task bridge namespace filtering
+
+Both the workflow and activity task bridges accept an optional `namespace` parameter on `poll()`:
+
+```php
+$tasks = $bridge->poll('redis', 'default', limit: 10, namespace: 'production');
+```
+
+When omitted, `poll()` returns tasks from all namespaces (backward-compatible with pre-namespace installations).
+
 ## Durable Type Aliases
 
 Durable type keys for workflows and activities are stored when you register them under `workflows.v2.types`. Failure payloads can use the same pattern for exception classes: