@temporal-architect/claude-plugin 0.9.0

package/skills/temporal-architect-design/topics/long-running.md

@@ -0,0 +1,230 @@
+# Long-Running Workflows
+
+> **Example:** [`long-running.twf`](./long-running.twf)
+
+Patterns for workflows that run for extended periods: continue-as-new, history management, and entity workflows.
+
+## The History Problem
+
+Temporal replays the full event history to reconstruct workflow state after any restart. This is the **primary constraint** on long-running workflows — history size directly determines replay cost, and Temporal enforces a hard limit (~50MB / ~50K events).
+
+| Issue | Impact |
+|-------|--------|
+| Replay cost | **Entire history replayed on every recovery** — this is the main bottleneck |
+| Hard limit | ~50MB event history / ~50K events — workflow terminates if exceeded |
+| Memory | Full history loaded into worker memory during replay |
+| Latency | Longer history = slower recovery after worker restart |
+
+**Solution:** Reset history periodically with `continue_as_new`.
+
+> **A bound is not a free pass.** "Only infinite loops need `continue_as_new`" is wrong. A *bounded* loop still grows history linearly with its bound, and if per-iteration history is chunky (a large activity result plus several tool calls each iteration) it can hit the limit well before the bound. The rule is: **loops whose accumulated history is large need `continue_as_new` — the bound alone is not sufficient.**
+>
+> **State the strategy explicitly.** Even though *where* to continue-as-new is partly an implementation concern, the design should **say** what it is — "bounded at N, per-iteration history small, no `continue_as_new`," "resets every K iterations," or "defer to author-go" — rather than leaving it silent. A silent design is one nobody decided.
+
+---
+
+## Continue-As-New
+
+Atomically complete current workflow and start a new execution with fresh history, preserving logical continuity.
+
+### Basic Pattern
+
+```twf
+workflow LongRunningProcessor(processor: Processor):
+    eventCount = 0
+    
+    for:
+        await signal NewEvent -> (event)
+        activity ProcessEvent(event)
+        processor.processed += 1
+        eventCount += 1
+        
+        # Reset history before it gets too large
+        if eventCount >= 1000:
+            close continue_as_new(processor)  # Fresh history, same logical workflow
+```
+
+### Continue-As-New Semantics
+
+| Aspect | Behavior |
+|--------|----------|
+| Workflow ID | Same (logical continuity) |
+| Run ID | New (fresh execution) |
+| History | Reset to zero |
+| Pending signals | Carried over (configurable) |
+| State | Passed as input to new execution |
+
+### When to Continue-As-New
+
+| Trigger | Example |
+|---------|---------|
+| Event count | After processing N events |
+| Time-based | Every 24 hours |
+| History size | Approaching limit |
+| Periodic reset | End of billing cycle |
+
+### SDK Intrinsics for History Tracking
+
+These deterministic SDK functions are available in workflow code (not activities) for deciding when to continue-as-new:
+
+| Function | Returns | Use |
+|----------|---------|-----|
+| `workflow.history_length()` | Event count | Compare against threshold (e.g., `>= 1000`) |
+| `workflow.history_size()` | Bytes | Compare against limit (e.g., `> 40_000_000`) |
+
+These appear in TWF as raw expressions since they're SDK-level calls, not TWF keywords.
+
+### Data Serialization
+
+```twf
+workflow EntityWorkflow(entity: Entity, data: EntityData):
+    for:
+        await signal Command -> (command)
+        data = applyCommand(data, command)
+        
+        # Periodic continuation with current data
+        if should_continue():
+            close continue_as_new(entity, data)
+```
+
+> Note: Data structs are defined at the SDK level, not in TWF notation.
+
+```pseudo
+# Data must be serializable!
+struct EntityData:
+    balance: decimal
+    lastUpdated: timestamp
+    pendingOperations: []Operation
+```
+
+---
+
+## Entity Workflow Pattern
+
+Long-lived workflow representing a business entity (user, order, account, subscription).
+
+### Structure
+
+```twf
+workflow UserEntity(userId: string, user: User):
+    # Initialize user if new
+    if user == null:
+        activity LoadUser(userId) -> (user)
+
+    query GetUser() -> (User):
+        return user
+
+    update UpdateSettings(settings: Settings) -> (Result):
+        user.settings = settings
+        return Result{success: true}
+
+    for:
+        # Wait for commands or periodic triggers
+        await one:
+            signal UpdateProfile:
+                user.profile = signal.data
+
+            signal AddCredits:
+                user.credits += signal.amount
+
+            signal Deactivate:
+                user.active = false
+                close complete  # End entity lifecycle
+
+            timer(24h):
+                # Periodic maintenance
+
+        # Persist after any change
+        activity PersistUser(user)
+
+        # Continue-as-new periodically
+        if eventCount > 500:
+            close continue_as_new(userId, user)
+```
+
+### Entity Lifecycle
+
+> Note: Entity lifecycle management uses SDK-level API calls, not TWF notation.
+
+```pseudo
+# Create entity (start workflow)
+temporal.start_workflow(
+    workflow: UserEntity,
+    id: "user-{userId}",
+    input: {userId: userId, user: null}
+)
+
+# Interact with entity (signals, queries, updates)
+temporal.signal("user-{userId}", UpdateProfile, {name: "Alice"})
+user = temporal.query("user-{userId}", GetUser)
+result = temporal.update("user-{userId}", AddCredits, {amount: 100})
+
+# Entity continues until explicit termination
+temporal.signal("user-{userId}", Deactivate, {})
+```
+
+### Entity vs Process Workflows
+
+| Entity Workflow | Process Workflow |
+|-----------------|------------------|
+| Long-lived (days, months, years) | Short-lived (minutes, hours) |
+| Represents a thing | Represents a process |
+| Reacts to external events | Drives toward completion |
+| No natural end state | Has completion state |
+| Examples: User, Account, Subscription | Examples: Order, Deployment, Migration |
+
+---
+
+## Continue-As-New Anti-Patterns
+
+### Losing Data on Continue
+
+```twf
+# BAD: Data not passed to continuation
+workflow Processor(data: ProcessorData):
+    modifiedData = transform(data)
+    close continue_as_new()  # Lost modifiedData!
+
+# GOOD: Pass current data
+workflow Processor(data: ProcessorData):
+    modifiedData = transform(data)
+    close continue_as_new(modifiedData)
+```
+
+### Continue-As-New in Wrong Place
+
+```twf
+# BAD: Continue in middle of operation
+workflow Processor(data: ProcessorData):
+    activity Step1()
+    if shouldContinue:
+        close continue_as_new(data)  # Step2 never runs!
+    activity Step2()
+
+# GOOD: Continue at natural boundary
+workflow Processor(data: ProcessorData):
+    activity Step1()
+    activity Step2()
+    if shouldContinue:
+        close continue_as_new(data)
+```
+
+### Too Frequent Continuation
+
+```twf
+# BAD: Continue every event
+workflow Processor(data: ProcessorData):
+    event = await signal Event
+    process(event)
+    close continue_as_new(data)  # Unnecessary overhead!
+
+# GOOD: Batch before continuing
+workflow Processor(data: ProcessorData):
+    count = 0
+    for:
+        event = await signal Event
+        process(event)
+        count += 1
+        if count >= 1000:
+            close continue_as_new(data)
+```

package/skills/temporal-architect-design/topics/long-running.twf

@@ -0,0 +1,100 @@
+# Source: long-running.md
+# Patterns: continue_as_new, entity workflow, signal/query/update
+
+# --- Basic continue-as-new pattern ---
+
+workflow LongRunningProcessor(processor: Processor):
+    signal NewEvent(data: EventData):
+        processor.lastEvent = data
+
+    eventCount = 0
+
+    for:
+        await one:
+            signal NewEvent:
+                activity ProcessEvent(processor) -> result
+                processor.processed = processor.processed + 1
+                eventCount = eventCount + 1
+            timer(24h):
+                activity PeriodicCheck(processor)
+
+        # Reset history before it gets too large
+        if (eventCount >= 1000):
+            close continue_as_new(processor)
+
+# --- Entity workflow pattern ---
+
+workflow UserEntity(userId: string, user: User):
+    signal UpdateProfile(data: ProfileData):
+        user.profile = data
+
+    signal AddCredits(amount: decimal):
+        user.credits = user.credits + amount
+
+    signal Deactivate():
+        user.active = false
+
+    query GetUser() -> (User):
+        return user
+
+    update UpdateSettings(settings: Settings) -> (Result):
+        user.settings = settings
+        activity PersistUser(user)
+        return Result{success: true}
+
+    # Initialize user if new
+    if (user == null):
+        activity LoadUser(userId) -> user
+
+    eventCount = 0
+
+    for:
+        await one:
+            signal UpdateProfile:
+                activity PersistUser(user)
+            signal AddCredits:
+                activity PersistUser(user)
+            signal Deactivate:
+                activity PersistUser(user)
+                close complete
+            timer(24h):
+                activity DailyMaintenance(user)
+
+        eventCount = eventCount + 1
+
+        # Continue-as-new periodically
+        if (eventCount > 500):
+            close continue_as_new(userId, user)
+
+# --- Supporting activities ---
+
+activity ProcessEvent(processor: Processor) -> (EventResult):
+    return process(processor)
+
+activity LoadUser(userId: string) -> (User):
+    return db.load(userId)
+
+activity PersistUser(user: User):
+    db.save(user.id, user)
+
+activity DailyMaintenance(user: User):
+    run_maintenance(user.id, user)
+
+activity PeriodicCheck(processor: Processor):
+    check(processor)
+
+# --- Worker and namespace ---
+
+worker longRunningWorker:
+    workflow LongRunningProcessor
+    workflow UserEntity
+    activity ProcessEvent
+    activity LoadUser
+    activity PersistUser
+    activity DailyMaintenance
+    activity PeriodicCheck
+
+namespace longRunning:
+    worker longRunningWorker
+        options:
+            task_queue: "long-running"

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

@@ -0,0 +1,248 @@
+# Nexus: Cross-Namespace Communication
+
+> **Example:** [`nexus.twf`](./nexus.twf)
+
+Nexus enables workflows in one Temporal namespace to call operations in another namespace, with proper authorization and abstraction.
+
+## When to Use Nexus
+
+| Use Nexus | Use Child Workflow Instead |
+|-----------|---------------------------|
+| Cross-namespace calls | Same namespace |
+| Cross-team boundaries | Same team |
+| Different security contexts | Same security context |
+| Service abstraction needed | Direct coupling acceptable |
+| Multi-tenant architectures | Single-tenant |
+
+> **Deciding how many namespaces?** See [namespaces.md](../reference/namespaces.md) — the default is **one**. Nexus is the mechanism for the *one* case that legitimately spans namespaces (a cross-team / different-security-context service contract); it is not a reason to multiply namespaces. Same-namespace calls should be child workflows, not Nexus.
+
+---
+
+## Nexus Concepts
+
+### Architecture
+
+```text
+orders Namespace (Caller)
+  OrderCheckout Workflow
+    nexus PaymentsEndpoint PaymentsService.ProcessPayment(args) -> result
+      |
+      v  (cross-namespace)
+payments Namespace (Target)
+  PaymentsEndpoint (task_queue: "payments")
+    PaymentsService
+      async ProcessPayment -> starts ProcessPaymentWorkflow
+
+orders Namespace (Caller)
+  OrderCheckout Workflow
+    detach nexus NotificationsEndpoint NotificationsService.SendConfirmation(args)
+      |
+      v  (cross-namespace)
+notifications Namespace (Target)
+  NotificationsEndpoint (task_queue: "notifications")
+    NotificationsService
+      async SendConfirmation -> starts SendConfirmationWorkflow
+```
+
+### Components
+
+| Component | TWF Construct | Description |
+|-----------|--------------|-------------|
+| **Nexus Service** | `nexus service Name:` | Top-level definition with operations |
+| **Async Operation** | `async OpName workflow WorkflowName` | Delegates to a named workflow |
+| **Sync Operation** | `sync OpName(params) -> (Type):` | Runs inline with a body |
+| **Nexus Endpoint** | `nexus endpoint Name` (in namespace) | Deployment routing with `task_queue` |
+| **Service Reference** | `nexus service Name` (in worker) | Links service to worker |
+| **Nexus Call** | `nexus Endpoint Service.Op(args)` | Invokes an operation |
+
+---
+
+## Nexus Service Definition
+
+Define a nexus service with typed operations:
+
+```twf
+nexus service PaymentsService:
+    async ProcessPayment workflow ProcessPaymentWorkflow
+    sync GetPaymentStatus(paymentId: string) -> (PaymentStatus):
+        activity LookupPayment(paymentId) -> status
+        close complete(status)
+```
+
+- **Async operations** delegate to a named workflow (one-liner, no body)
+- **Sync operations** have a body using the workflow statement set
+
+### Deployment
+
+Each Nexus service lives in its own namespace. The endpoint is defined alongside the worker that serves it, in the target namespace. The caller namespace only hosts the workflows that invoke the endpoints.
+
+```twf
+worker paymentProcessingWorker:
+    workflow ProcessPaymentWorkflow
+    activity LookupPayment
+    nexus service PaymentsService
+
+# Target namespace: owns the service and exposes the endpoint
+namespace payments:
+    worker paymentProcessingWorker
+        options:
+            task_queue: "payments"
+    nexus endpoint PaymentsEndpoint
+        options:
+            task_queue: "payments"
+
+# Caller namespace: only has the workflows that call into payments
+namespace orders:
+    worker checkoutWorker
+        options:
+            task_queue: "checkout"
+```
+
+---
+
+## Nexus Call Syntax
+
+### Basic Call
+
+```twf
+nexus PaymentsEndpoint PaymentsService.ProcessPayment(order.payment) -> result
+```
+
+Three identifiers: `Endpoint Service.Operation(args)` — endpoint name, then service and operation separated by a dot.
+
+### With Options
+
+```twf
+nexus PaymentsEndpoint PaymentsService.ProcessPayment(payment) -> result
+    options:
+        schedule_to_close_timeout: 5m
+```
+
+Options: `schedule_to_close_timeout`, `retry_policy`, `priority`.
+
+---
+
+## Execution Modes
+
+Nexus calls support the same three execution modes as child workflows:
+
+| Mode | Syntax | Behavior |
+|------|--------|----------|
+| **Synchronous** | `nexus Ep Svc.Op(args) -> result` | Caller blocks until operation completes |
+| **Async (promise)** | `promise p <- nexus Ep Svc.Op(args)` | Caller continues, awaits promise later |
+| **Fire-and-forget** | `detach nexus Ep Svc.Op(args)` | Caller continues, never waits |
+
+### Synchronous (Default)
+
+```twf
+workflow Caller(order: Order) -> (Result):
+    nexus PaymentsEndpoint PaymentsService.ProcessPayment(order.payment) -> result
+    close complete(Result{paymentId: result.id})
+```
+
+### Asynchronous (Promise)
+
+```twf
+workflow Caller(data: Data) -> (Result):
+    promise handle <- nexus PaymentsEndpoint PaymentsService.ProcessPayment(data.payment)
+    activity DoOtherWork(data) -> localResult
+    await handle -> paymentResult
+    close complete(Result{localResult, paymentResult})
+```
+
+### Fire-and-Forget (Detach)
+
+```twf
+workflow Caller(order: Order) -> (Result):
+    detach nexus NotificationsEndpoint NotificationsService.SendConfirmation(order.customer)
+    close complete(Result{status: "initiated"})
+```
+
+---
+
+## Await Patterns
+
+### Await Nexus
+
+```twf
+await nexus PaymentsEndpoint PaymentsService.GetStatus(id) -> status
+```
+
+### Await One with Nexus
+
+Race a nexus call against a timeout:
+
+```twf
+workflow Caller(data: Data) -> (Result):
+    await one:
+        nexus PaymentsEndpoint PaymentsService.ProcessPayment(data) -> result:
+            close complete(Result{success: true, data: result})
+        timer(5m):
+            activity AlertTimeout(data)
+            close fail(Result{success: false, error: "timeout"})
+```
+
+> **The nexus operation continues if the timer wins.** Losing an `await one` race does **not** cancel the nexus call — the operation (and the workflow it runs in the *target* namespace) keeps running until this workflow run ends. Since the target is an independent service, you usually can't cancel it implicitly; if the payment must be voided on timeout, model that explicitly (a compensating nexus op or activity), not by relying on the race.
+
+---
+
+## Resolution
+
+The resolver validates all nexus references:
+
+### Errors
+
+| Condition | Error |
+|-----------|-------|
+| Duplicate `nexus service` name | `duplicate nexus service definition: X` |
+| Duplicate endpoint name across namespaces | `duplicate nexus endpoint name "X"` |
+| Endpoint not found (endpoints exist) | `undefined nexus endpoint: X` |
+| Service not found (services exist) | `undefined nexus service: X` |
+| Operation not found on service | `nexus service X has no operation Y` |
+| `detach nexus ... -> result` | `detach nexus call cannot have a result` |
+| Async op references missing workflow | `async operation Y references undefined workflow: Z` |
+| Worker refs missing service | `worker W references undefined nexus service: X` |
+| Endpoint missing `task_queue` | `nexus endpoint X missing required task_queue option` |
+| Endpoint task queue has no worker with service | `no worker on that queue has service S` |
+
+### Warnings
+
+| Condition | Warning |
+|-----------|---------|
+| Service not on any worker (namespaces exist) | `nexus service X is not referenced by any worker` |
+| Endpoint not found (no endpoints defined) | `unresolved nexus endpoint: X (may be external)` |
+| Service not found (no services defined) | `unresolved nexus service: X (may be external)` |
+
+---
+
+## Anti-Patterns
+
+### Nexus for Same-Namespace Calls
+
+Nexus adds routing and authorization overhead that is only justified across namespace boundaries. Calling a service in the same namespace should use a child workflow instead.
+
+```twf
+# BAD: Nexus overhead for a call that stays inside the orders namespace
+workflow OrderCheckout(order: Order) -> (OrderResult):
+    nexus LocalEndpoint LocalService.Validate(order) -> result
+
+# GOOD: Child workflow — same namespace, same team, no boundary to cross
+workflow OrderCheckout(order: Order) -> (OrderResult):
+    workflow ValidateOrder(order) -> result
+```
+
+### Missing Timeout
+
+```twf
+# BAD: No deadline
+workflow A():
+    nexus Endpoint Svc.SlowOperation(data) -> result
+
+# GOOD: Explicit deadline via await one
+workflow A():
+    await one:
+        nexus Endpoint Svc.SlowOperation(data) -> result:
+            close complete(Result{result})
+        timer(5m):
+            close fail(Result{error: "timeout"})
+```