Merge branch 'main' into drewhoskins_interceptor

Author: lennessyy

.gitignore

@@ -25,6 +25,7 @@ temp/
 AGENTS.md
 CLAUDE.md
 .claude/*
+.omc
 
 npm-debug.log*
 yarn-debug.log*

docs/cloud/billing-api.mdx

@@ -14,8 +14,7 @@ tags:
 ---
 
 The Temporal Cloud Billing API provides Namespace-level cost attribution through on-demand billing reports. 
-These reports are generated asynchronously and can be accessed with an object endpoint or downloaded in CSV format 
-for analysis by FinOps professionals and Temporal Cloud operators.
+Reports are delivered in CSV format and can be accessed via API or downloaded directly for use in FinOps tooling and cost management platforms.  
 
 This API is part of the [Cloud Operations API](/ops).
 
@@ -29,67 +28,42 @@ The Billing API allows you to:
 
 - Generate billing reports for specified invoice months  
 - Retrieve report status and metadata  
-- Correlate report generation with async operations  
-- Download CSV reports  
-- Integrate billing reports into internal analytics tooling and cloud cost management platforms
+- Download CSV reports that can be fed into internal analytics tooling or cloud cost management platforms
 
-The Billing API contains:
+The Billing Report contains:
 
 - Accurate Namespace-level cost attribution  
-- Down to hourly granularity  
-- Alignment with the [FOCUS schema](https://focus.finops.org/)
+- Hourly granularity  
+- A [FOCUS](https://focus.finops.org/)-friendly data format
 
-For complete request and response schemas, refer to the Protocol Buffer definitions below.
+For complete request and response schemas, refer to the Schema below.
 
 Billing report generation is **asynchronous**. You initiate report creation, then poll for completion.
 
-## Report data granularity
+## Report data limitations
 
-Reports can be generated with hourly granularity only, for the current billing month, and the previous billing month.
+For pre-release, reports can be generated with hourly granularity only, for the current billing month, and the previous billing month.
 
 ## Allowed date ranges
 
 Date ranges must use billing-month boundaries (MM/YYYY). 
 Requests may include the current billing month. 
 The data in finalized reports includes usage up to `current_time` \- 24 hours (rounded up to nearest hour).
 
-:::info Limitiations
-
-Data from the current billing period is not cacheable. Also, recently requested historical date ranges may complete faster due to caching.
-
-:::
-
 ## Rate limits and concurrency
 
-To ensure system stability, rate limits apply to API usage. 
+Rate limits apply to API usage. 
 
 ### Per-account concurrency
 
 Within a single account:
 
-- Only one billing report per account is processed at a time  
+- Only one billing report per account is generated at a time  
 - Additional requests are accepted but queued  
-- Processing occurs serially per account
-
-### Global rate limits
-
-Billing report generation depends on shared infrastructure.
 
-Report generation time varies based on:
+### Report Generation Latency
 
-- Global system load  
-- Date range size  
-- Cache availability
-
-### Caching behavior
-
-If a previously requested date range is requested again:
-
-- Cached precomputed data is reused  
-- Global rate limits are skipped  
-- Generation completes significantly faster
-
-Exception: Data from the current billing period is not cached.
+Report generation time varies and is not guaranteed. Factors that affect it include the size of the requested date range and overall platform load.
 
 ## Best practices
 
@@ -99,8 +73,6 @@ Poll `GetBillingReport` using exponential backoff.
 
 Download reports immediately after generation (URLs expire).
 
-Reuse previously requested date ranges when possible to benefit from caching.
-
 Avoid frequent generation of large overlapping ranges in the current billing period.
 
 ## Billing report schema
@@ -123,7 +95,7 @@ Each row represents a charge record.
 | ChargePeriodStart | Time period start from when this charge took place, correlates to data granularity | 2025-10-01T00:00:00.000Z |
 | ContractedCost | Cost calculated by multiplying ContractedUnitPrice and PricingQuantity | 100.00 |
 | ContractedUnitPrice | The agreed-upon unit price for a single pricing unit of the associated SKU. Inclusive of negotiated discounts | 10.00 |
-| InvoiceID | The ID of the invoice for this billing period | in\_1SPN94JLJETBw2gmYWyQ71xT |
+| InvoiceID | The ID of the invoice for this billing period | in\_XXXXXXXXXXXXXXXXXXXX |
 | InvoiceIssuer | The entity responsible for issuing payable invoices | stripe |
 | PricingQuantity | The volume of a given SKU used or purchased | 10.00 |
 | PricingUnit | The measurement unit used for PricingQuantity | 1 Million Actions |
@@ -137,16 +109,13 @@ Each row represents a charge record.
 | ServiceSubcategory | A secondary classification of the service category for a service based on its core function | Actions |
 | SKUID | A unique identifier that represents a specific SKU | essentials-actions |
 | SKUMeter | The functionality being metered or measured by a particular SKU in a charge | Actions |
-| Tags | Provider and customer defined tags associated with resources | `{"$tmprl\_project":\["project-id"\],"namespace-tag-key":\["namespace-tag-value"\]}` |
+| Tags | Provider and customer defined tags associated with resources | `{"$tmprl_project":["project-id"],"namespace-tag-key":["namespace-tag-value"]}` |
 
 ## Generate a report
 
 To generate a report, follow these steps:
 
-1. Create a billing report using `CreateBillingReport`  
-1. Receive:  
-   - `billing_report_id` (identifies the report artifact)  
-   - `async_operation_id` (identifies the background job)  
+1. Create a billing report using `CreateBillingReport`. The response includes a `billing_report_id` and `async_operation_id`.
 1. Poll `GetBillingReport` using the `billing_report_id`  
 1. When the report state becomes `BILLING_REPORT_STATE_GENERATED`, retrieve the download URL  
 1. Download the report before the URL expires
@@ -155,7 +124,7 @@ To generate a report, follow these steps:
 
 | Identifier | Purpose |
 | ----- | ----- |
-| `billing_report_id` | Identifies the billing report artifact and is used to retrieve metadata and download URLs |
+| `billing_report_id` | Identifies the billing report and is used to retrieve metadata and download URLs |
 | `async_operation_id` | Identifies the background operation responsible for generating the report |
 
 The async operation follows the standard Cloud Operations async model (see [Async Operations](/ops#per-identity-rate-limits)).

docs/develop/dotnet/message-passing.mdx

@@ -37,8 +37,7 @@ Follow these guidelines when writing your message handlers:
 
 - Message handlers are defined as methods on the Workflow class, using one of the three attributes: [`WorkflowQueryAttribute`](https://dotnet.temporal.io/api/Temporalio.Workflows.WorkflowQueryAttribute.html), [`WorkflowSignalAttribute`](https://dotnet.temporal.io/api/Temporalio.Workflows.WorkflowSignalAttribute.html), and [`WorkflowUpdateAttribute`](https://dotnet.temporal.io/api/Temporalio.Workflows.WorkflowUpdateAttribute.html).
 - The parameters and return values of handlers and the main Workflow function must be [serializable](/dataconversion).
-- Prefer data classes to multiple input parameters.
-  Data class parameters allow you to add fields without changing the calling signature.
+- Prefer data classes to multiple input parameters. Data class parameters allow you to add fields without changing the calling signature. Keep in mind that serialization and deserialization can fail with the default data converter if the new field does not have a default value.
 
 ### Query handlers {#queries}
 

docs/develop/go/error-handling.mdx

@@ -5,23 +5,97 @@ sidebar_label: Failure detection
 toc_max_heading_level: 4
 keywords:
   - failure detection
+  - error-handling
 tags:
   - Activities
   - Workflows
   - Failures
   - Errors
   - Go SDK
   - Temporal SDKs
-description: Configure Workflow timeouts, set Retry Policies, and manage Activity timeouts and Heartbeats using Temporal's Go SDK for optimized execution control.
+description: Handle errors, configure Workflow timeouts, set Retry Policies, and manage Activity timeouts and Heartbeats using Temporal's Go SDK.
 ---
 
 This page shows how to do the following:
 
+- [Handle errors](#error-handling)
 - [Set Workflow timeouts](#workflow-timeouts)
 - [Set a Workflow Retry Policy](#workflow-retries)
 - [Set Activity timeouts](#activity-timeouts)
 - [Set a custom Activity Retry Policy](#activity-retries)
 
+## Error handling {#error-handling}
+
+Within a Workflow, an Activity or Child Workflow execution might fail. You can
+handle errors differently based on the error type.
+
+If the Activity returns an error as `errors.New()` or `fmt.Errorf()`, that error is converted into `*temporal.ApplicationError`.
+
+If the Activity returns an error as `temporal.NewNonRetryableApplicationError("error message", details)`, that error is returned as `*temporal.ApplicationError`.
+
+There are other types of errors such as `*temporal.TimeoutError`, `*temporal.CanceledError` and
+`*temporal.PanicError`.
+
+Here's an example of handling Activity errors within Workflow code that differentiates between different error types.
+
+```go
+err := workflow.ExecuteActivity(ctx, YourActivity, ...).Get(ctx, nil)
+if err != nil {
+	var applicationErr *ApplicationError
+	if errors.As(err, &applicationErr) {
+		// retrieve error message
+		workflow.GetLogger(ctx).Info("Application error", "error", applicationErr.Error())
+
+		// handle Activity errors (created via NewApplicationError() API)
+		var detailMsg string // assuming Activity return error by NewApplicationError("message", true, "string details")
+		applicationErr.Details(&detailMsg) // extract strong typed details
+
+		// handle Activity errors (errors created other than using NewApplicationError() API)
+		switch applicationErr.Type() {
+		case "CustomErrTypeA":
+			// handle CustomErrTypeA
+		case CustomErrTypeB:
+			// handle CustomErrTypeB
+		default:
+			// newer version of Activity could return new errors that Workflow was not aware of.
+		}
+	}
+
+	var canceledErr *CanceledError
+	if errors.As(err, &canceledErr) {
+		// handle cancellation
+	}
+
+	var timeoutErr *TimeoutError
+	if errors.As(err, &timeoutErr) {
+		// handle timeout, could check timeout type by timeoutErr.TimeoutType()
+        switch err.TimeoutType() {
+        case commonpb.ScheduleToStart:
+            // Handle ScheduleToStart timeout.
+        case commonpb.StartToClose:
+            // Handle StartToClose timeout.
+        case commonpb.Heartbeat:
+            // Handle heartbeat timeout.
+        default:
+        }
+	}
+
+	var panicErr *PanicError
+	if errors.As(err, &panicErr) {
+		// handle panic, message and call stack are available by panicErr.Error() and panicErr.StackTrace()
+	}
+}
+```
+
+### Panics and deferred functions
+
+In Go, [`defer` schedules cleanup functions and `recover()` catches panics](https://go.dev/blog/defer-panic-and-recover) to prevent them from crashing the program.
+This doesn't work the same way in Temporal Workflow code — you cannot `recover()` from a panic inside a `defer`.
+Deferred functions that try to interact with the Temporal SDK during panic unwinding will re-panic immediately.
+
+Use `defer` only for local cleanup.
+Handle Temporal API cleanup through explicit error checks instead.
+
 ## Workflow timeouts {#workflow-timeouts}
 
 **How to set Workflow timeouts using the Temporal Go SDK**

docs/develop/go/failure-detection.mdx

@@ -42,8 +42,7 @@ Follow these guidelines when writing your message handlers:
 
 - Message handlers are defined as methods on the Workflow class, using one of the three decorators: [`@workflow.query`](https://python.temporal.io/temporalio.workflow.html#query), [`@workflow.signal`](https://python.temporal.io/temporalio.workflow.html#signal), and [`@workflow.update`](https://python.temporal.io/temporalio.workflow.html#update).
 - The parameters and return values of handlers and the main Workflow function must be [serializable](/dataconversion).
-- Prefer [data classes](https://docs.python.org/3/library/dataclasses.html) to multiple input parameters.
-  Data class parameters allow you to add fields without changing the calling signature.
+- Prefer [data classes](https://docs.python.org/3/library/dataclasses.html) to multiple input parameters. Data class parameters allow you to add fields without changing the calling signature. Keep in mind that serialization and deserialization can fail with the default data converter if the new field does not have a default value.
 
 ### Query handlers {#queries}
 

docs/develop/python/message-passing.mdx

@@ -18,11 +18,7 @@ import { CaptionedImage } from '@site/src/components';
 
 :::tip SUPPORT, STABILITY, and DEPENDENCY INFO
 
-Temporal Python SDK support for Nexus is at [Public Preview](/evaluate/development-production-features/release-stages#public-preview).
-
-Features in public preview may undergo further development and testing before they are made Generally Available.
-These features are being refined and are recommended for production usage.
-The APIs may undergo changes; however, Temporal's goal is to maintain backward compatibility.
+Temporal Python SDK support for Nexus is now [Generally Available](/evaluate/development-production-features/release-stages#general-availability).
 
 :::
 

docs/develop/python/temporal-nexus.mdx

@@ -74,7 +74,7 @@ Since Independent Activities aren't part of a Workflow's version, they can run i
 
 - **Current Worker Deployment Version**: The version where Workflows are routed to unless they were previously pinned on a different version. Other versions can continue polling to allow pinned Workflows to finish executing or in case you need to roll back. If no current version is specified, the default is unversioned.
 - **Ramping Worker Deployment Version**: The version where a configurable percentage of Workflows are routed to unless they were previously pinned on a different version. The ramp percentage can be in the range [0, 100]. Workflows that don't go to the Ramping Version will go to the Current Version. If no Ramping Version is specified, 100% of new Workflows and Auto-Upgrade Workflows will go to the Current Version.
-- **Target Worker Deployment Version**: The version your Workflow will move to next. This could be the Deployment's Current Version or the Ramping Version. For example, if an Auto-Upgrade Workflow was running on Version A, the Current Version is B, and there is a 5% ramp to C, there is a 95% chance that its Target Version is B and 5% that it's C.
+- **Target Worker Deployment Version**: The version your Workflow will upgrade to next. This could be the Deployment's Current Version or the Ramping Version. For example, if an Auto-Upgrade Workflow was running on Version A, the Current Version is B, and there is a 5% ramp to C, there is a 95% chance that its Target Version is B and 5% that it's C. Workflow ID determines whether the workflow falls into the 95% group or the 5% group.
 
 ## Versioning Statuses {#versioning-statuses}