@temporal-architect/claude-plugin 0.9.0

package/skills/temporal-architect-design/topics/timers-scheduling.md

@@ -0,0 +1,131 @@
+# Timers and Scheduling
+
+> **Example:** [`timers-scheduling.twf`](./timers-scheduling.twf)
+
+Durable timing primitives for delays, deadlines, and recurring execution.
+
+## Timers
+
+Durable sleep that survives worker restarts, deployments, and failures.
+
+### Basic Timer
+
+```twf
+workflow DelayedNotification(userId: string, delay: duration):
+    # Durable sleep - workflow pauses but state is preserved
+    await timer(delay)
+
+    activity SendNotification(userId)
+```
+
+### Timer Considerations
+
+| Aspect | Guidance |
+|--------|----------|
+| **Durability** | Timer survives worker restarts; workflow resumes when timer fires |
+| **Precision** | Not precise to the millisecond; expect seconds of variance |
+| **History** | Each timer adds to workflow history; avoid very frequent short timers |
+| **Cancellation** | Timers can be cancelled if workflow is cancelled |
+
+---
+
+## Deadlines and Timeouts
+
+### Workflow-Level Deadline
+
+```twf
+workflow OrderFulfillment(order: Order) -> (OrderResult):
+    # Entire workflow must complete within deadline (SDK-level config)
+    # workflow_timeout: 7d
+
+    activity ValidateRetailOrder(order)
+    await signal PaymentReceived
+    activity ShipRetailOrder(order)
+    close complete(OrderResult{status: "completed"})
+```
+
+### Operation Deadline Pattern
+
+```twf
+workflow ProcessWithDeadline(data: Data) -> (Result):
+    # Race between operation and deadline
+    await one:
+        activity LongOperation(data) -> result:
+            close complete(Result{success: true, data: result})
+        timer(1h):
+            activity Cleanup(data)
+            close fail(Result{success: false, error: "deadline exceeded"})
+```
+
+> **`await one` does not cancel the loser.** If the timer wins, `LongOperation` is **not** cancelled — it keeps running in the background until the workflow run ends. `await one` is "first to complete wins," not "winner cancels the rest." If the losing operation must actually stop (release a lock, stop billing), you need an explicit cancellation/cleanup activity — the race alone won't do it.
+
+### Timeout on Signal Wait
+
+```twf
+workflow ApprovalWorkflow(request: Request) -> (Decision):
+    activity NotifyApprovers(request)
+
+    await one:
+        signal Approved:
+            close complete(Decision{status: "approved"})
+        signal Rejected:
+            close complete(Decision{status: "rejected"})
+        timer(7d):
+            activity NotifyExpired(request)
+            close complete(Decision{status: "expired"})
+```
+
+---
+
+## Scheduling Patterns
+
+### Periodic Execution Within Workflow
+
+```twf
+workflow Heartbeat(resourceId: string):
+    for:
+        activity CheckHealth(resourceId)
+        await timer(5m)
+```
+
+### Polling with Backoff
+
+```twf
+workflow WaitForResource(resourceId: string) -> (Resource):
+    backoff = 1s
+    max_backoff = 5m
+
+    for:
+        activity CheckResource(resourceId) -> resource
+        if resource.ready:
+            close complete(resource)
+
+        await timer(backoff)
+        backoff = min(backoff * 2, max_backoff)
+```
+
+### Deadline with Periodic Check
+
+```twf
+workflow WaitForCompletion(jobId: string) -> (JobResult):
+    for:
+        activity GetJobStatus(jobId) -> status
+        if status.complete:
+            close complete(JobResult{status: "complete", data: status.data})
+
+        await one:
+            timer(30s):
+                # Continue polling
+            timer(2h):
+                close fail(JobResult{status: "timeout"})
+```
+
+---
+
+## Schedules (Cron Workflows)
+
+Temporal Schedules execute workflows on a recurring basis (cron expressions, intervals, calendars). Schedules are **platform configuration**, not workflow design — they define *when* to start a workflow, not *how* it runs.
+
+Schedule configuration (specs, overlap policies, catchup windows, timezones) is managed through the Temporal CLI or SDK, not TWF notation. See [Temporal Schedules documentation](https://docs.temporal.io/workflows#schedule) for details.
+
+**Design implication:** A scheduled workflow should be designed like any other workflow — idempotent, with continue-as-new if long-running. The schedule itself is an external trigger, not part of the workflow's logic.

package/skills/temporal-architect-design/topics/timers-scheduling.twf

@@ -0,0 +1,129 @@
+# Source: timers-scheduling.md
+# Patterns: timer delay, deadline, polling with backoff, periodic
+
+# --- Basic timer: delayed notification ---
+
+workflow DelayedNotification(userId: string, delay: duration):
+    # Durable sleep - workflow pauses but state is preserved
+    await timer(delay)
+    activity SendNotification(userId)
+
+# --- Deadline pattern: race between operation and timer ---
+
+workflow ProcessWithDeadline(data: Data) -> (Result):
+    await one:
+        activity LongOperation(data) -> result:
+            close complete(Result{success: true, data: result})
+        timer(1h):
+            activity Cleanup(data)
+            close fail(Result{success: false, error: "deadline exceeded"})
+
+# --- Periodic execution within workflow ---
+
+workflow HealthMonitor(resourceId: string):
+    count = 0
+
+    for:
+        activity CheckHealth(resourceId)
+        await timer(5m)
+        count = count + 1
+        if (count > 1000):
+            close continue_as_new(resourceId)
+
+# --- Polling with backoff ---
+
+workflow WaitForResource(resourceId: string) -> (Resource):
+    backoff = 1s
+    maxBackoff = 60s
+
+    for:
+        activity CheckResource(resourceId) -> resource
+        if (resource.ready):
+            close complete(resource)
+
+        await one:
+            timer(backoff):
+                backoff = min(backoff * 2, maxBackoff)
+            timer(30m):
+                close fail(Resource{error: "timeout"})
+
+# --- Deadline with periodic check ---
+
+workflow WaitForCompletion(jobId: string) -> (JobResult):
+    checks = 0
+
+    for:
+        activity GetJobStatus(jobId) -> status
+        if (status.complete):
+            close complete(JobResult{status: "complete", data: status.data})
+
+        checks = checks + 1
+        if (checks > 100):
+            close complete(JobResult{status: "timeout"})
+
+        await timer(30s)
+
+# --- Polling with continue-as-new for history management ---
+
+workflow LongPoller(resourceId: string, iteration: int) -> (Resource):
+    count = 0
+
+    for:
+        activity PollResource(resourceId) -> status
+        if (status.ready):
+            activity FetchResource(resourceId) -> resource
+            close complete(resource)
+
+        await timer(5s)
+        count = count + 1
+        if (count >= 500):
+            close continue_as_new(resourceId, iteration + 1)
+
+# --- Supporting activities ---
+
+activity SendNotification(userId: string):
+    send(userId)
+
+activity LongOperation(data: Data) -> (OperationResult):
+    return process(data)
+
+activity Cleanup(data: Data):
+    cleanup(data)
+
+activity CheckHealth(resourceId: string) -> (HealthStatus):
+    return check(resourceId)
+
+activity CheckResource(resourceId: string) -> (Resource):
+    return check(resourceId)
+
+activity GetJobStatus(jobId: string) -> (JobStatus):
+    return get_status(jobId)
+
+activity PollResource(resourceId: string) -> (ResourceStatus):
+    return poll(resourceId)
+
+activity FetchResource(resourceId: string) -> (Resource):
+    return fetch(resourceId)
+
+# --- Worker and namespace ---
+
+worker schedulingWorker:
+    workflow DelayedNotification
+    workflow ProcessWithDeadline
+    workflow HealthMonitor
+    workflow WaitForResource
+    workflow WaitForCompletion
+    workflow LongPoller
+    activity SendNotification
+    activity LongOperation
+    activity Cleanup
+    activity CheckHealth
+    activity CheckResource
+    activity GetJobStatus
+    activity PollResource
+    activity FetchResource
+
+namespace scheduling:
+    worker schedulingWorker
+        options:
+            task_queue: "scheduling"

package/skills/temporal-architect-design/topics/versioning.md

@@ -0,0 +1,434 @@
+# Workflow Versioning and Evolution
+
+> **Example:** [`versioning.twf`](./versioning.twf)
+
+Safe strategies for evolving workflows without breaking running executions.
+
+## The Versioning Challenge
+
+Running workflows may execute for hours, days, or months. When you deploy new code:
+
+```text
+Problem:
+1. Workflow V1 starts, runs step A, B
+2. You deploy V2 (changes step B to B')
+3. Worker restarts, replays V1 workflow
+4. Replay expects B but code has B'
+5. Non-determinism error!
+```
+
+**Solution:** Version-aware code that handles both old and new execution paths.
+
+---
+
+## Temporal's Versioning Approaches
+
+| Approach | Use Case | Complexity |
+|----------|----------|------------|
+| **Patching API** | Incremental changes to existing workflows | Low |
+| **Worker Versioning** | Major workflow changes, complete rewrites | Medium |
+| **Workflow Type Versioning** | Breaking changes, parallel versions | Higher |
+
+---
+
+## Patching API
+
+Add conditional logic to handle old vs new code paths during replay.
+
+> **TWF vs SDK:** The `.twf` file ([`versioning.twf`](./versioning.twf)) uses boolean flag parameters for version gating — this is the DSL-level representation. The examples below use `patched("...")` which is the SDK-level API (Go: `workflow.GetVersion()`, Python: `patched()`). Both represent the same concept: branching on whether a workflow execution predates a code change.
+
+### Basic Pattern
+
+```pseudo
+workflow UnderwritingAddFraudCheck(policy: Policy) -> (PolicyResult):
+    activity ValidatePolicy(policy)
+
+    # Version gate: new code only runs for new executions
+    if patched("add-fraud-check"):
+        activity FraudCheck(policy)  # New step, only for new workflows
+    
+    activity BindPolicy(policy)
+    close complete(PolicyResult{status: "complete"})
+```
+
+### How Patching Works
+
+```text
+New Execution:
+1. patched("add-fraud-check") → true (marks in history)
+2. FraudCheck runs
+3. History: [Validate, Patch:add-fraud-check, FraudCheck, Payment]
+
+Replay of Old Execution (started before patch):
+1. History has no patch marker
+2. patched("add-fraud-check") → false
+3. FraudCheck skipped
+4. Replay matches original history
+
+Replay of New Execution (started after patch):
+1. History has patch marker
+2. patched("add-fraud-check") → true
+3. FraudCheck runs
+4. Replay matches history
+```
+
+### Patching Examples
+
+**Adding a Step:**
+```pseudo
+workflow Process(data: Data) -> (Result):
+    activity Step1(data)
+
+    if patched("v2-add-validation"):
+        activity NewValidation(data)  # Added in V2
+    
+    activity Step2(data)
+    close complete(Result{})
+```
+
+**Removing a Step:**
+```pseudo
+workflow Process(data: Data) -> (Result):
+    activity Step1(data)
+
+    if not patched("v3-remove-legacy"):
+        activity LegacyStep(data)  # Removed in V3, but runs for old workflows
+
+    activity Step2(data)
+    close complete(Result{})
+```
+
+**Changing a Step:**
+```pseudo
+workflow Process(data: Data) -> (Result):
+    activity Step1(data)
+
+    if patched("v4-improved-processing"):
+        activity ImprovedProcessing(data)
+    else:
+        activity OldProcessing(data)
+
+    activity Step3(data)
+    close complete(Result{})
+```
+
+### Deprecating Patches
+
+After all old workflows complete, remove patch:
+
+> Note: Patch lifecycle management uses SDK-specific APIs. The concept is shown as pseudo-code.
+
+```pseudo
+# Phase 1: Add patch (both paths exist)
+if patched("add-feature"):
+    activity NewFeature()
+
+# Phase 2: After all old workflows done, simplify
+# (Run deprecate_patch to verify no old workflows)
+if deprecated_patch("add-feature"):
+    pass  # Old path, will error if any old workflows still running
+activity NewFeature()
+
+# Phase 3: Remove patch code entirely
+activity NewFeature()
+```
+
+---
+
+## Worker Versioning (Build IDs)
+
+Route workflows to workers running compatible code versions.
+
+### Declaring the strategy in `.twf`
+
+> **TWF vs SDK:** A worker instantiation declares *which* versioning strategy a worker pool uses via the `versioning` option — the design-altitude decision. The build-id registration, ramping, and routing mechanics below stay SDK/CLI-level (code-scale).
+
+```twf
+namespace orders:
+    worker orderTypes
+        options:
+            task_queue: "orderProcessing"
+            versioning: build_id      # none | build_id | deployment
+```
+
+`versioning` expresses *intent* — the strategy a worker pool follows — not concrete Build IDs or deployment names (those are deploy-time inputs, never `.twf` content):
+
+| Value | Meaning |
+|-------|---------|
+| `none` | Unversioned workers (default) |
+| `build_id` | Build ID–based worker versioning |
+| `deployment` | Worker Deployment–based versioning |
+
+Enum values are bare idents — `build_id`, not `build-id` or `"build_id"`.
+
+### Concept
+
+```text
+┌─────────────────────────────────────────────────────┐
+│                   Task Queue                         │
+├─────────────────────────────────────────────────────┤
+│  Build ID: 1.0  │  Build ID: 2.0  │  Build ID: 3.0 │
+│    (default)    │   (compatible)  │    (latest)    │
+└────────┬────────┴────────┬────────┴────────┬───────┘
+         │                 │                  │
+     ┌───▼───┐        ┌────▼────┐       ┌────▼────┐
+     │Worker │        │ Worker  │       │ Worker  │
+     │  1.0  │        │   2.0   │       │   3.0   │
+     └───────┘        └─────────┘       └─────────┘
+```
+
+### Configuration
+
+```bash
+# Register build ID with task queue
+temporal task-queue update-build-ids add-new-default \
+    --task-queue main-queue \
+    --build-id "v2.0"
+```
+
+> Note: Worker configuration is SDK-level code.
+
+```pseudo
+# Worker identifies its build ID
+worker = Worker(
+    task_queue: "main-queue",
+    build_id: "v2.0",
+    workflows: [UnderwritingAddFraudCheck],
+    activities: [ValidatePolicy, FraudCheck, BindPolicy]
+)
+```
+
+### Version Sets
+
+```bash
+# Create version set: v1.0 and v1.1 are compatible
+temporal task-queue update-build-ids add-new-compatible \
+    --task-queue main-queue \
+    --build-id "v1.1" \
+    --existing-compatible-build-id "v1.0"
+
+# New version set: v2.0 is NOT compatible with v1.x
+temporal task-queue update-build-ids add-new-default \
+    --task-queue main-queue \
+    --build-id "v2.0"
+```
+
+### Routing Behavior
+
+| Workflow State | Routed To |
+|----------------|-----------|
+| New workflow | Latest default build ID |
+| Running workflow | Same build ID (or compatible) |
+| Workflow started on v1.0 | v1.0 or v1.1 worker |
+
+---
+
+## Workflow Type Versioning
+
+Create a new workflow type for breaking changes.
+
+### Pattern
+
+```twf
+# Version 1
+workflow PolicyV1(policy: PolicyV1Input) -> (PolicyV1Result):
+    # Original implementation
+    ...
+
+# Version 2 (breaking changes)
+workflow PolicyV2(policy: PolicyV2Input) -> (PolicyV2Result):
+    # New implementation with different structure
+    ...
+```
+
+### Migration Strategy
+
+> Note: API routing logic is application-level code, not TWF notation.
+
+```pseudo
+# API layer routes to appropriate version
+function startPolicyWorkflow(policy):
+    if policy.version == 1:
+        return client.start(PolicyV1, convertToV1(policy))
+    else:
+        return client.start(PolicyV2, convertToV2(policy))
+```
+
+### When to Use Workflow Type Versioning
+
+| Scenario | Approach |
+|----------|----------|
+| Adding optional step | Patching |
+| Changing activity order | Patching |
+| Complete workflow rewrite | New workflow type |
+| Input/output schema breaking change | New workflow type |
+| Different business logic | New workflow type |
+
+---
+
+## Versioning Best Practices
+
+### 1. Plan for Evolution
+
+```pseudo
+# Good: Named constants for versions (SDK-level code)
+PATCH_ADD_FRAUD_CHECK = "2024-01-add-fraud-check"
+PATCH_IMPROVE_VALIDATION = "2024-02-improve-validation"
+
+workflow Process(data: Data):
+    if patched(PATCH_ADD_FRAUD_CHECK):
+        ...
+```
+
+### 2. Test Both Paths
+
+```pseudo
+test "workflow handles both old and new path":
+    # Test new execution path
+    env = TestEnvironment()
+    result = env.execute(Workflow, input)
+    assert result.includesFraudCheck
+    
+    # Test replay of old execution
+    old_history = load("workflow_v1.history")
+    replay_result = env.replay(Workflow, old_history)
+    assert replay_result.success  # No non-determinism
+```
+
+### 3. Document Versions
+
+```text
+# Workflow: UnderwritingAddFraudCheck
+# 
+# Version History:
+# - 2024-01: Added fraud check (patch: add-fraud-check)
+# - 2024-02: Improved validation (patch: improve-validation)
+# - 2024-03: Deprecated old validation (patch: remove-legacy-validation)
+#
+# Active patches: add-fraud-check, improve-validation
+# Deprecated patches: remove-legacy-validation (safe to remove after 2024-04)
+```
+
+### 4. Monitor Old Workflows
+
+```bash
+# Query for workflows started before patch
+temporal workflow list \
+    --query "StartTime < '2024-01-15' AND ExecutionStatus = 'Running'"
+```
+
+---
+
+## Common Versioning Scenarios
+
+### Adding Activity
+
+```pseudo
+workflow Process(data: Data):
+    activity Existing1(data)
+
+    if patched("add-new-activity"):
+        activity NewActivity(data)  # Safe to add
+    
+    activity Existing2(data)
+```
+
+### Removing Activity
+
+```pseudo
+workflow Process(data: Data):
+    activity Existing1(data)
+
+    if not patched("remove-deprecated"):
+        activity DeprecatedActivity(data)  # Removed for new, kept for old
+    
+    activity Existing2(data)
+```
+
+### Reordering Activities
+
+```pseudo
+# Original order: A, B, C
+# New order: A, C, B
+
+workflow Process(data: Data):
+    activity A(data)
+
+    if patched("reorder-bc"):
+        activity C(data)
+        activity B(data)
+    else:
+        activity B(data)
+        activity C(data)
+```
+
+### Changing Activity Parameters
+
+```pseudo
+workflow Process(data: Data):
+    if patched("new-activity-params"):
+        activity Enhanced(data, extraParam: true)
+    else:
+        activity Enhanced(data)  # Old signature
+```
+
+---
+
+## Anti-Patterns
+
+### Unguarded Changes
+
+```pseudo
+# BAD: Breaking change without version guard
+workflow Process(data: Data):
+    activity Step1(data)
+    # Removed Step2 without patch - breaks replay!
+    activity Step3(data)
+
+# GOOD: Version-guarded removal
+workflow Process(data: Data):
+    activity Step1(data)
+    if not patched("remove-step2"):
+        activity Step2(data)
+    activity Step3(data)
+```
+
+### Too Many Active Patches
+
+```pseudo
+# BAD: Accumulated complexity
+workflow Process(data: Data):
+    if patched("v1"):
+        if patched("v2"):
+            if patched("v3"):
+                ...
+
+# GOOD: Consolidate when safe, or use worker versioning
+```
+
+### Forgetting to Deprecate
+
+```pseudo
+# BAD: Old patch code lives forever
+if patched("feature-from-2020"):  # All workflows with this are done!
+    ...
+
+# GOOD: Clean up after old workflows complete
+# 1. Verify no running workflows need old path
+# 2. Replace with deprecated_patch
+# 3. Remove patch code after verification
+```
+
+---
+
+## Version Migration Checklist
+
+- [ ] Identify all changes from current version
+- [ ] Classify each change (additive, removal, modification)
+- [ ] Add appropriate patches for each change
+- [ ] Write replay tests against old histories
+- [ ] Deploy with both code paths active
+- [ ] Monitor for non-determinism errors
+- [ ] Wait for old workflows to complete
+- [ ] Remove deprecated patch code
+- [ ] Update documentation