generated from coulomb/repo-seed
Add project scaffold: contracts, schemas, docker-compose, workplans
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>
This commit is contained in:
93
docs/conventions.md
Normal file
93
docs/conventions.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user