feat(runtime): define versioned error envelope

[daryllimyt]

Summary

• define the strict tracecat.error.v1 envelope with independent owner, namespaced kind, safe message, retry_disposition, and diagnostic-only cause_type
• make kind the single stable taxonomy identity and mirror it into Temporal ApplicationError.type
• extend action error details with a discriminated classified variant while preserving the legacy payload shape
• add Temporal adapters for carrying, extracting, and wrapping envelopes with retryability derived from the typed contract

Why

ENG-1407 needs a narrow runtime-error contract before execution paths begin producing or consuming classifications. A fine-grained namespaced kind is sufficient for product grouping and operator diagnosis, so this contract does not add a second operation dimension or retain a separate compatibility error type.

Keeping this layer contract-only makes the compatibility, retry, and history-safety properties reviewable independently from runtime integration.

Impact

This PR does not classify live failures, change workflow routing, add Sentry capture, or alter completion behavior. Existing unclassified action and Temporal error details keep their established shape and semantics. cause_type remains diagnostic metadata and must not control attribution or retry behavior.

Validation

• focused runtime, Temporal transport, and scheduler unit coverage
• uv run ruff check and uv run ruff format --check
• targeted uv run basedpyright
• repository commit hooks, including generated-client verification and secret scanning

LOC breakdown

Category	+	-
Logic	373	4
Tests	462	1

---

Summary by cubic

Defines a versioned runtime error envelope and Temporal adapters; adopts namespaced error kinds and adds executor backend initialization classification. This standardizes error attribution and retry behavior without changing workflow routing or delivery (ENG-1407).

• Introduces the tracecat.error.v1 envelope with owner, kind (namespaced), message, retry_disposition, and cause_type; strict parsing requires the explicit schema discriminator and forbids extra fields.
• Adds Temporal transport helpers: build ApplicationError from an envelope (type = kind, retryability derived), reject next_retry_delay for non-retryable envelopes, and reliably wrap/extract envelopes through temporalio failure serialization and exception chains.
• Extends DSL action error details with ClassifiedActionErrorInfo and a strict ActionErrorInfoAdapter union; updates the scheduler to parse via the adapter and preserve classification while keeping legacy payload shape.
• Expands the runtime taxonomy (namespaced kinds) and adds executor.backend.initialization_failed.
• No migrations or user actions.

^{Written for commit d610c36. Summary will update on new commits.}

[zeropath-ai]

✅ No security or compliance issues detected. Reviewed everything up to d610c36.

Security Overview

• 🔎 Scanned files: 8 changed file(s)
• 🔗 Scan Link: https://zeropath.com/app/repositories/00dffd6c-8834-4dc9-b6d8-b44cd1622986?scanId=08f2b3a6-33e3-4dfd-b78f-812c53266735&codeScanTypes=PrScan&tab=issues

Detected Code Changes

Change Type	Relevant files
Enhancement	► tests/unit/test_dsl_scheduler_concurrency.py     Preserve classified action errors in scheduler ► tracecat/dsl/scheduler.py     Use ActionErrorInfoAdapter for parsing action errors in error path
Enhancement	► tests/unit/test_runtime_errors.py     Add runtime error envelope tests including serialization/deserialization and platform/user handling
Enhancement	► tests/unit/test_temporal_errors.py     Add extensive Temporal error handling and envelope integration tests
Enhancement	► tracecat/dsl/types.py     Introduce ClassifiedActionErrorInfo and ActionErrorInfoAdapter; update imports
Enhancement	► tracecat/runtime/init.py     Add runtime package marker
Enhancement	► tracecat/runtime/errors.py     Add runtime error envelope model and utilities (ErrorEnvelope, TracecatRuntimeError, parse_error_envelope, etc.)
Enhancement	► tracecat/temporal/errors.py     Add Temporal transport layer with application_error_from_envelope, wrap/extract helpers, and envelope parsing

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6d501eddbe

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve standalone envelopes in scheduler errors

When wrap_application_error() or application_error_from_envelope() transports an error without an ActionErrorInfo, its sole detail is the new TemporalErrorDetails mapping. This branch treats that mapping as a child-workflow map and validates its first value (the schema string) as an action error, then falls back to an unclassified ActionErrorInfo; consequently the envelope is absent from task_exceptions and the final workflow/error-handler payload. Recognize TemporalErrorDetails here and synthesize a ClassifiedActionErrorInfo so the non-action transport path retains its classification.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d610c3608b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve classifications inside aggregate action errors

When a classified action fails inside a scatter/gather, this variant is only used by the top-level adapter: FinalizeGatherActivityResult.errors and ActionErrorInfo.children remain typed as ActionErrorInfo. Pydantic therefore serializes those values as the base dataclass and drops the subclass's envelope at the activity or aggregate boundary, so gather RAISE/partition paths lose the new owner, kind, and retry metadata. Use the variant (or an equivalent classification-preserving serializer) for aggregate error fields as well.

Useful? React with 👍 / 👎.