generated from coulomb/repo-seed
tegwick
6f9132314f
Phase 0 contracts (event envelope, ActivityDefinition, idempotency doc, naming conventions) and Phase 1 Temporal cluster setup (docker-compose.dev.yml, Temporal dynamic config) are complete. Includes Pydantic models, JSON schemas, wiki architecture docs, and ADR-001 workplan files for both workstreams. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
94 lines
2.5 KiB
Markdown
94 lines
2.5 KiB
Markdown
# Temporal Conventions
|
|
|
|
## Namespace
|
|
|
|
| Environment | Namespace |
|
|
|---|---|
|
|
| Dev (Docker Compose) | `default` |
|
|
| Production | `activity-core-prod` |
|
|
|
|
Use the `default` namespace for all dev and test work. The production namespace is
|
|
created via the Temporal admin API as part of the Kubernetes deployment (EP-custodian,
|
|
extension point `af654abb`).
|
|
|
|
---
|
|
|
|
## Task Queues
|
|
|
|
| Queue name | Registered workers |
|
|
|---|---|
|
|
| `orchestrator-tq` | `RunActivityWorkflow` and all its activities (`load_activity_definition`, `resolve_context`, `log_run`) |
|
|
| `task-execution-tq` | `TaskExecutorWorkflow` and all concrete task type workflows |
|
|
|
|
**Rule:** a workflow and its activities must be registered on the same task queue.
|
|
Cross-queue activity calls require an explicit `task_queue` argument on
|
|
`workflow.execute_activity()`.
|
|
|
|
---
|
|
|
|
## Workflow ID conventions
|
|
|
|
See `docs/idempotency.md` for the full workflow ID strategy.
|
|
|
|
Summary:
|
|
- `RunActivityWorkflow`: `activity-{activity_id}:{trigger_key}`
|
|
- `TaskExecutorWorkflow`: `task-{run_id}:{task_type}:{index}`
|
|
- Temporal Schedules: `activity-schedule-{activity_id}`
|
|
|
|
---
|
|
|
|
## Schedule ID conventions
|
|
|
|
Temporal Schedules are identified by `schedule_id`. The convention:
|
|
|
|
```
|
|
activity-schedule-{activity_definition.id}
|
|
```
|
|
|
|
This makes it trivial to look up the schedule for a given ActivityDefinition
|
|
without a separate mapping table.
|
|
|
|
---
|
|
|
|
## Worker registration
|
|
|
|
Each worker process registers:
|
|
- **Workflows**: `worker.register_workflow(WorkflowClass)`
|
|
- **Activities**: `worker.register_activity(activity_function)`
|
|
|
|
A single process may run workers for multiple task queues, but each `Worker`
|
|
instance is bound to one task queue. Use separate `Worker` instances for
|
|
`orchestrator-tq` and `task-execution-tq`.
|
|
|
|
---
|
|
|
|
## Search attributes
|
|
|
|
`RunActivityWorkflow` sets the following search attributes (requires Elasticsearch
|
|
visibility, enabled in the dev docker-compose):
|
|
|
|
| Attribute | Type | Value |
|
|
|---|---|---|
|
|
| `ActivityId` | `Keyword` | The `ActivityDefinition.id` UUID |
|
|
| `ActivityName` | `Keyword` | The `ActivityDefinition.name` |
|
|
|
|
These allow filtering workflow runs by activity in the Temporal UI.
|
|
|
|
---
|
|
|
|
## Retry policy defaults
|
|
|
|
Unless overridden, all activities use:
|
|
|
|
```python
|
|
RetryPolicy(
|
|
initial_interval=timedelta(seconds=1),
|
|
backoff_coefficient=2.0,
|
|
maximum_interval=timedelta(minutes=5),
|
|
maximum_attempts=10,
|
|
)
|
|
```
|
|
|
|
Long-running context-resolution activities that call external services should set
|
|
`heartbeat_timeout` to detect stalls.
|