@temporal-architect/claude-plugin 0.9.0

package/skills/temporal-architect-design/topics/patterns.twf

@@ -0,0 +1,346 @@
+# Source: patterns.md
+# Patterns: process, entity, saga, fan-out/fan-in, pipeline, state machine, polling
+
+# --- Process Workflow ---
+
+workflow OrderFulfillment(order: Order) -> (OrderResult):
+    # Step 1: Validate
+    activity ValidateRetailOrder(order) -> validated
+    if (validated.success == false):
+        close fail(OrderResult{status: "invalid", error: validated.error})
+
+    # Step 2: Reserve
+    activity ReserveInventory(order.items) -> reservation
+
+    # Step 3: Charge
+    activity ProcessPayment(order.payment) -> payment
+
+    # Step 4: Fulfill
+    activity ShipRetailOrder(order, reservation)
+
+    # Step 5: Notify
+    activity SendConfirmation(order.customer)
+
+    close complete(OrderResult{status: "completed", trackingId: reservation.trackingId})
+
+# --- Entity Workflow ---
+
+workflow AccountEntity(accountId: string, account: Account):
+    signal Deposit(amount: decimal):
+        account.balance = account.balance + amount
+
+    signal Withdraw(amount: decimal):
+        if (account.balance >= amount):
+            account.balance = account.balance - amount
+
+    signal Close():
+        closePending = true
+
+    query GetBalance() -> (decimal):
+        return account.balance
+
+    update Transfer(amount: decimal, toAccount: string) -> (TransferResult):
+        if (account.balance < amount):
+            return TransferResult{success: false, error: "insufficient funds"}
+        account.balance = account.balance - amount
+        activity RecordAccountTransaction(accountId, "transfer")
+        return TransferResult{success: true}
+
+    if (account == null):
+        activity LoadAccount(accountId) -> account
+
+    eventCount = 0
+    closePending = false
+
+    for:
+        await one:
+            signal Deposit:
+                activity RecordAccountTransaction(accountId, "deposit")
+            signal Withdraw:
+                activity RecordAccountTransaction(accountId, "withdraw")
+            signal Close:
+                activity CloseAccount(accountId)
+                close complete
+            timer(24h):
+                activity DailyReconciliation(accountId)
+
+        eventCount = eventCount + 1
+        if (eventCount > 1000):
+            close continue_as_new(accountId, account)
+
+# --- Saga Pattern (adapted without try/catch) ---
+
+workflow BookingWorkflow(booking: Booking) -> (BookingResult):
+    # Step 1: Reserve flight
+    activity ReserveFlight(booking.flight) -> flight
+
+    # Step 2: Reserve hotel (compensate flight if this fails)
+    activity ReserveHotel(booking.hotel) -> hotel
+    if (hotel.failed):
+        activity CancelFlight(flight.id)
+        close fail(BookingResult{status: "hotel_failed"})
+
+    # Step 3: Reserve car (compensate flight + hotel if this fails)
+    activity ReserveCar(booking.car) -> car
+    if (car.failed):
+        activity CancelFlight(flight.id)
+        activity CancelHotel(hotel.id)
+        close fail(BookingResult{status: "car_failed"})
+
+    # Step 4: Charge payment (compensate all if this fails)
+    activity ChargeBookingPayment(booking.payment) -> payment
+    if (payment.failed):
+        workflow CompensateBooking(flight.id, hotel.id, car.id)
+        close fail(BookingResult{status: "payment_failed"})
+
+    # All succeeded
+    close complete(BookingResult{status: "confirmed"})
+
+# --- Saga compensation workflow (called on failure) ---
+
+workflow CompensateBooking(flight: string, hotel: string, car: string):
+    # Run compensations
+    activity CancelFlight(flight)
+    activity CancelHotel(hotel)
+    activity CancelCar(car)
+    close complete
+
+# --- Fan-Out/Fan-In ---
+
+workflow BatchProcessor(items: []Item) -> (BatchResult):
+    # Fan-out: start all processing in parallel
+    await all:
+        for (item in items):
+            activity ProcessBatchItem(item)
+
+    # Fan-in: aggregate results (SDK collects results from await all)
+    activity AggregateResults(items) -> aggregated
+    close complete(BatchResult{processed: aggregated.count})
+
+# --- Pipeline ---
+
+workflow DataPipeline(rawData: RawData) -> (ProcessedData):
+    # Stage 1: Ingest
+    activity Ingest(rawData) -> ingested
+
+    # Stage 2: Validate
+    activity Validate(ingested) -> validated
+    if (validated.valid == false):
+        close fail(ProcessedData{status: "invalid", errors: validated.errors})
+
+    # Stage 3: Transform
+    activity Transform(validated.data) -> transformed
+
+    # Stage 4: Enrich
+    activity Enrich(transformed) -> enriched
+
+    # Stage 5: Load
+    activity Load(enriched)
+
+    close complete(ProcessedData{status: "complete", recordCount: enriched.count})
+
+# --- State Machine ---
+
+workflow DocumentApproval(doc: Document) -> (ApprovalResult):
+    signal Submit():
+        phase = "pending_review"
+        activity NotifyReviewers(doc)
+
+    signal Approve():
+        phase = "approved"
+
+    signal Reject():
+        phase = "rejected"
+
+    signal RequestChanges():
+        phase = "changes_requested"
+
+    signal Withdraw():
+        phase = "withdrawn"
+
+    phase = "draft"
+
+    for:
+        switch (phase):
+            case "draft":
+                await one:
+                    signal Submit:
+                    timer(90d):
+                        phase = "expired"
+            case "pending_review":
+                await one:
+                    signal Approve:
+                    signal Reject:
+                    signal RequestChanges:
+                    timer(30d):
+                        phase = "expired"
+            case "changes_requested":
+                await one:
+                    signal Submit:
+                    signal Withdraw:
+                    timer(30d):
+                        phase = "expired"
+            case "approved":
+                activity PublishDocument(doc)
+                close complete(ApprovalResult{status: "approved"})
+            case "rejected":
+                activity ArchiveDocument(doc)
+                close complete(ApprovalResult{status: "rejected"})
+            case "withdrawn":
+                close complete(ApprovalResult{status: "withdrawn"})
+            case "expired":
+                close complete(ApprovalResult{status: "expired"})
+
+# --- Polling ---
+
+workflow AwaitResourceReady(resourceId: string) -> (Resource):
+    backoff = 5s
+    maxBackoff = 60s
+
+    for:
+        activity CheckResourceStatus(resourceId) -> status
+
+        if (status.ready):
+            activity GetResource(resourceId) -> resource
+            close complete(resource)
+
+        if (status.failed):
+            close fail(Resource{error: status.error})
+
+        # Wait with backoff, timeout via await one + timer
+        await one:
+            timer(backoff):
+                backoff = min(backoff * 2, maxBackoff)
+            timer(30m):
+                close fail(Resource{error: "timeout"})
+
+# --- Supporting activities ---
+
+activity ValidateRetailOrder(order: Order) -> (ValidateResult):
+    return validate(order)
+
+activity ReserveInventory(items: []Item) -> (Reservation):
+    return reserve(items)
+
+activity ProcessPayment(payment: Payment) -> (PaymentResult):
+    return charge(payment)
+
+activity ShipRetailOrder(order: Order, reservation: Reservation):
+    ship(order, reservation)
+
+activity SendConfirmation(customer: Customer):
+    notify(customer)
+
+activity LoadAccount(accountId: string) -> (Account):
+    return db.load(accountId)
+
+activity RecordAccountTransaction(accountId: string, txType: string):
+    db.record(accountId, txType)
+
+activity CloseAccount(accountId: string):
+    db.close(accountId)
+
+activity DailyReconciliation(accountId: string):
+    reconcile(accountId)
+
+activity ReserveFlight(flight: FlightSpec) -> (FlightReservation):
+    return reserve(flight)
+
+activity ReserveHotel(hotel: HotelSpec) -> (HotelReservation):
+    return reserve(hotel)
+
+activity ReserveCar(car: CarSpec) -> (CarReservation):
+    return reserve(car)
+
+activity ChargeBookingPayment(payment: Payment) -> (PaymentResult):
+    return charge(payment)
+
+activity CancelFlight(flightId: string):
+    cancel(flightId)
+
+activity CancelHotel(hotelId: string):
+    cancel(hotelId)
+
+activity CancelCar(carId: string):
+    cancel(carId)
+
+activity ProcessBatchItem(item: Item) -> (ItemResult):
+    return process(item)
+
+activity AggregateResults(results: []ItemResult) -> (AggregateResult):
+    return aggregate(results)
+
+activity Ingest(rawData: RawData) -> (IngestedData):
+    return ingest(rawData)
+
+activity Validate(data: IngestedData) -> (ValidationResult):
+    return validate(data)
+
+activity Transform(data: ValidatedData) -> (TransformedData):
+    return transform(data)
+
+activity Enrich(data: TransformedData) -> (EnrichedData):
+    return enrich(data)
+
+activity Load(data: EnrichedData):
+    load(data)
+
+activity NotifyReviewers(doc: Document):
+    notify(doc.reviewers)
+
+activity PublishDocument(doc: Document):
+    publish(doc)
+
+activity ArchiveDocument(doc: Document):
+    archive(doc)
+
+activity CheckResourceStatus(resourceId: string) -> (ResourceStatus):
+    return check(resourceId)
+
+activity GetResource(resourceId: string) -> (Resource):
+    return fetch(resourceId)
+
+# --- Worker and namespace ---
+
+worker patternsWorker:
+    workflow OrderFulfillment
+    workflow AccountEntity
+    workflow BookingWorkflow
+    workflow CompensateBooking
+    workflow BatchProcessor
+    workflow DataPipeline
+    workflow DocumentApproval
+    workflow AwaitResourceReady
+    activity ValidateRetailOrder
+    activity ReserveInventory
+    activity ProcessPayment
+    activity ShipRetailOrder
+    activity SendConfirmation
+    activity LoadAccount
+    activity RecordAccountTransaction
+    activity CloseAccount
+    activity DailyReconciliation
+    activity ReserveFlight
+    activity ReserveHotel
+    activity ReserveCar
+    activity ChargeBookingPayment
+    activity CancelFlight
+    activity CancelHotel
+    activity CancelCar
+    activity ProcessBatchItem
+    activity AggregateResults
+    activity Ingest
+    activity Validate
+    activity Transform
+    activity Enrich
+    activity Load
+    activity NotifyReviewers
+    activity PublishDocument
+    activity ArchiveDocument
+    activity CheckResourceStatus
+    activity GetResource
+
+namespace patterns:
+    worker patternsWorker
+        options:
+            task_queue: "patterns"

package/skills/temporal-architect-design/topics/promises-conditions.md

@@ -0,0 +1,179 @@
+# Promises and Conditions
+
+> **Example:** [`promises-conditions.twf`](./promises-conditions.twf)
+
+Deferred async operations and named boolean awaitables for workflow state.
+
+## Overview
+
+| Primitive | Purpose | Syntax |
+|-----------|---------|--------|
+| **Promise** | Start async operation, await later | `promise p <- activity Foo(x)` |
+| **Condition** | Named boolean awaitable | `condition myCondition` (in `state:` block) |
+| **Set / Unset** | Mutate a condition | `set myCondition` / `unset myCondition` |
+| **State block** | Declare workflow state | `state:` (before handlers) |
+
+---
+
+## Promises
+
+A `promise` wraps any async operation (activity, workflow, timer, signal, update) for non-blocking execution. The `<-` operator visually distinguishes async declaration from sync result binding (`->`).
+
+### Declaration
+
+```twf
+promise p <- activity ProcessItem(input)
+promise report <- workflow BuildReport(data)
+promise timeout <- timer(5m)
+promise approved <- signal Approved
+promise addr <- update ChangeAddress
+promise pay <- nexus BillingEndpoint BillingService.ChargePayment(card)
+```
+
+### Awaiting a Promise
+
+Block until the promise resolves and bind the result:
+
+```twf
+await p -> result
+await timeout
+```
+
+### Promises in `await one` (race)
+
+```twf
+await one:
+    p -> result:
+        close complete(Result{data: result})
+    timeout:
+        close fail("timed out")
+```
+
+> **The promise's operation is not cancelled when it loses.** If `timeout` wins, the operation backing `p` (the activity/workflow/nexus call started by `promise p <- ...`) keeps running until the workflow run ends — racing a promise against a timeout does **not** cancel the promise. If the losing operation must actually stop, add explicit cleanup; the race alone won't release it.
+
+### Start-Now, Wait-Later Pattern
+
+The primary use case for promises is starting operations without blocking, doing other work, then collecting results:
+
+```twf
+workflow ParallelProcessing(items: Items) -> (Result):
+    promise handleA <- activity ProcessA(items.a)
+    promise handleB <- activity ProcessB(items.b)
+
+    activity QuickSetup(items)
+
+    await handleA -> resultA
+    await handleB -> resultB
+
+    close complete(Result{a: resultA, b: resultB})
+```
+
+### Async Duality
+
+Every async operation has two forms:
+
+| Form | Syntax | Behavior |
+|------|--------|----------|
+| **Blocking** | `activity Process(item) -> result` | Start and wait immediately |
+| **Non-blocking** | `promise p <- activity Process(item)` | Start, continue, wait later |
+
+This applies uniformly to: `activity`, `workflow`, `timer`, `signal`, `update`.
+
+---
+
+## Conditions
+
+A `condition` is a named boolean temporal primitive declared in the workflow `state:` block. It can be set, unset, and awaited.
+
+### Declaration (in `state:` block only)
+
+```twf
+workflow Example():
+    state:
+        condition clusterStarted
+        condition thresholdReached
+```
+
+### Mutation
+
+```twf
+set clusterStarted
+unset clusterStarted
+```
+
+### Awaiting a Condition
+
+```twf
+await clusterStarted
+```
+
+### Conditions in `await one` (race)
+
+```twf
+await one:
+    clusterStarted:
+        close complete(ClusterState{started: true})
+    timer(30d):
+        close fail("timeout")
+```
+
+### Update Handler + Condition Pattern
+
+The primary motivator for conditions: update handlers that wait on workflow state. The client blocks until the handler returns, and the handler waits for a condition that the main workflow body sets:
+
+```twf
+workflow ClusterManager(config: Config):
+    state:
+        condition clusterStarted
+
+    update WaitUntilStarted() -> (ClusterState):
+        await clusterStarted
+        return ClusterState{started: true}
+
+    activity ProvisionCluster(config)
+    activity StartCluster(config)
+    set clusterStarted
+
+    await signal Shutdown
+    close complete
+```
+
+---
+
+## State Block
+
+The `state:` block declares workflow state including conditions and variable initializations. It must appear first in a workflow definition, before signal/query/update handlers.
+
+```twf
+workflow Example():
+    state:
+        condition myCondition
+        balance = 0
+        status = "pending"
+
+    signal Deposit(amount: decimal):
+        balance = balance + amount
+        if (balance >= 1000):
+            set myCondition
+
+    await myCondition
+    close complete
+```
+
+### Restrictions
+
+- No temporal primitives inside `state:` block (it is purely declarative)
+- `condition` declarations can only appear inside `state:` blocks
+- `set`/`unset` targets must refer to conditions declared in the `state:` block
+
+---
+
+## Condition Considerations
+
+| Consideration | Guidance |
+|---------------|----------|
+| **Boolean only** | Conditions are simple true/false values |
+| **Declarative** | Must be declared in `state:` block before use |
+| **Signal-driven** | Typically set/unset in signal or update handlers |
+| **Reactive** | `await condition` unblocks when condition becomes true |
+| **No expressions** | Conditions are named booleans, not arbitrary predicates |