Files

tegwick 6f9132314f 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>

2026-03-04 22:45:40 +01:00

2.5 KiB

Raw Blame History

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:

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.

2.5 KiB Raw Blame History