docs(jsdoc): Phase 5 — Annotate Workflow client and runtime classes

[WhitWaldo]

Summary

Add comprehensive JSDoc annotations to the Workflow subsystem — both the client (for managing workflow instances) and the runtime (for defining workflows and activities).

Scope

Workflow Client (src/workflow/client/)

File	Purpose
DaprWorkflowClient.ts	Start, query, pause, resume, terminate, purge workflows
WorkflowState.ts	Represents the current state of a workflow instance
WorkflowFailureDetails.ts	Error details when a workflow fails

Workflow Runtime (src/workflow/runtime/)

File	Purpose
WorkflowRuntime.ts	Registers workflows and activities, starts the task worker
WorkflowContext.ts	Context available inside workflow orchestrator functions
WorkflowActivityContext.ts	Context available inside activity functions
WorkflowRuntimeStatus.ts	Enum of workflow lifecycle states

Workflow Types (src/types/workflow/)

• Activity.type.ts — Activity function signature
• Workflow.type.ts — Workflow orchestrator function signature
• WorkflowClientOption.ts — Client constructor options
• WorkflowGetResponse.type.ts — Response from get operations
• WorkflowRaiseOptions.type.ts — Options for raising events
• WorkflowRuntimeStatus.type.ts — Status enum type
• WorkflowStartOptions.type.ts — Options for starting workflows
• InputOutput.type.ts — Generic I/O type helpers

Requirements

• DaprWorkflowClient: Document every method (start, get, pause, resume, terminate, purge, raise, wait)
• WorkflowRuntime: Document registerWorkflow, registerActivity, start, shutdown
• WorkflowContext: Document all orchestration primitives:
  • callActivity — scheduling activities
  • callChildWorkflow — sub-orchestrations
  • createTimer — durable timers
  • waitForExternalEvent — external event correlation
  • continueAsNew — eternal workflows
  • whenAll / whenAny — fan-out/fan-in patterns
• WorkflowActivityContext: Document what's available inside activities
• WorkflowState: Document all properties (instanceId, name, runtimeStatus, input, output, createdAt, lastUpdatedAt)
• All option types: Document every property with defaults and constraints
• Add @example blocks showing common patterns (start → wait → get result)

Example

/**
 * Schedules an activity for execution and returns a task representing
 * the pending result.
 *
 * Activities are the basic unit of work in a workflow — they execute
 * exactly once (with at-least-once delivery) and can perform I/O,
 * call external services, and interact with Dapr building blocks.
 *
 * @param activity - The activity function or its registered name
 * @param input - Input data passed to the activity; must be JSON-serializable
 * @returns A task that resolves with the activity's return value
 *
 * @example
 * ```ts
 * function* myWorkflow(ctx: WorkflowContext) {
 *   const result = yield ctx.callActivity(processPayment, { orderId: "123", amount: 49.99 });
 *   return result;
 * }
 * ```
 */
callActivity<TInput, TOutput>(activity: Activity<TInput, TOutput>, input?: TInput): Task<TOutput>;

Acceptance Criteria

• All workflow client and runtime classes fully annotated
• Orchestration context primitives documented with usage examples
• Workflow types and options documented
• No logic changes — documentation only
• Builds cleanly (npm run build)