activity-core/docs/conventions.md

# 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`) |

**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}`
- 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)`

The activity-core process registers one `Worker` on `orchestrator-tq`. Execution
ownership belongs to downstream consumers and approved execution services.

---

## 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.