Temporal IDs & Naming — what changed, and why each choice

A walk-through of the redesign on feature/Temporal-ids. We rebuilt Pipelex's Temporal identity layer around the principle: Pipelex already mints the right IDs — thread them straight through Temporal's primitives, don't invent new ones. Phases 1–6 are shipped; this note explains the shape so you can navigate the diff without reading every plan file.

1. The two problems we were fixing

2. The Temporal identity primitives, distilled

Temporal makes a hard distinction between IDs (per-instance, unique, runtime) and Types (per-class, registered, static). Get those mixed up and the design will be wrong before it starts.

3. The mapping we picked

One sheet, one decision per row. No information is lost on the way down, no information is invented on the way up.

4. Workflow ID shape

Top-level

Child workflows — slash-nested path

// Top-level                ut-3f9c…b3c
// Fixed-role child         ut-3f9c…b3c/pipe-router
// Dynamic sub-pipe child   ut-3f9c…b3c/pipe-router/translate_doc-7c1e2f8a
// Nested router            ut-3f9c…b3c/pipe-router/translate_doc-7c1e2f8a/extract_text-4d9b1c83

The construction site, in code

// pipelex/temporal/temporal_manager.py — make_top_workflow_id
- def make_top_workflow_id(self, base_id: str) -> str:
-     # Truncated session + random shortuuid + caller class name
-     return f"{prefix}{self.session_id[:5]}-{random_short_uuid()}-{base_id}"
+ def make_top_workflow_id(self, pipeline_run_id: str) -> str:
+     prefix: str
+     match runtime_manager.run_mode:
+         case RunMode.UNIT_TEST:      prefix = "ut-"
+         case RunMode.NORMAL:         prefix = ""
+         case RunMode.CI_TEST:        prefix = "ci-"
+         case RunMode.CODEX_CLOUD:    prefix = "cc-"
+         case RunMode.CODEX_CLOUD_TEST: prefix = "cct-"
+     return f"{prefix}{pipeline_run_id}"

// pipelex/temporal/tprl_pipe/temporal_pipe_router.py — child branch
  if is_in_temporal_workflow():
      parent_workflow_id = workflow.info().workflow_id
+     # Replay-safe: workflow.uuid4() is deterministic by design.
+     child_workflow_id = f"{parent_workflow_id}/{pipe_job.pipe.code}-{str(workflow.uuid4())[:8]}"
+     pipe_output = await workflow.execute_child_workflow(
+         WfPipeRouter.run,
+         arg=pipe_job,
+         id=child_workflow_id,
+         search_attributes=build_search_attributes(pipe_job),
+         static_summary=build_static_summary(pipe_job.pipe),
+         static_details=build_static_details(pipe_job),
+     )

5. Activity ID — let the SDK do its job

Pipelex no longer passes activity_id= anywhere. The Python SDK auto-assigns sequential integers ("1", "2", …) per workflow run. They are:

• ✓ Unique per (workflow_id, run_id) by construction.
• ✓ Deterministic across replay (assigned by history position).
• ✓ Visible in Event History next to the Activity Type and per-activity summary.

Per-call meaning lives in summary=. Every make_* method in ContentGeneratorInWorkflow looks like this:

async def make_llm_text(self, job_metadata, llm_setting_main, llm_prompt_for_text) -> str:
    dispatch_kwargs = worker_config.resolve_dispatch(
        activity_name=act_llm_gen_text.__name__,
        routing_key=llm_assignment.llm_handle,
        queue_options_by_queue=get_config().temporal.queue_options,
        is_traced=get_config().temporal.temporal_config.temporal_log_config.is_dispatch_resolution_traced,
    ).to_execute_kwargs()
    return await workflow.execute_activity(
        act_llm_gen_text,
        arg=llm_assignment,
        summary=build_activity_summary("LLM text", job_metadata,
                                       extras={"model": llm_assignment.llm_handle}),
        **dispatch_kwargs,                # task_queue + timeouts + retry, see queues-and-options.html
    )

Pipe authors never think about Temporal IDs: identity flows entirely through JobMetadata.pipeline_run_id, the SDK assigns the activity ID, the per-call summary carries the call-specific meaning.

6. Observability — three primitives, zero new fields

We weren't using any of Temporal's display primitives. Now we use all the relevant ones, in three layers.

Static summary (workflow list view)

Set once at workflow start. 200-byte single-line Markdown.

{pipe_code} — {description}
// e.g. "translate_doc — Translate a document from English to French"

Static details (workflow detail view)

Set once at workflow start. 20 KB Markdown table.

| Field         | Value                                          |
|---------------|------------------------------------------------|
| Pipe          | `translate_doc`                                |
| Domain        | `documents`                                    |
| Pipeline run  | `3f9c8b2a-1e4d-4f5b-9c7a-2d8e1f0a6b3c`         |
| User          | `acme-corp`                                    |
| Session       | `EdgdJ7Yk4Q3HF2pXyZv9w8`                       |
| Library crate | `documents@2.1.4`                              |
| Input         | `source_text`, `target_language`               |

Per-activity summary (Event History)

Set per workflow.execute_activity(...) call. 200 bytes. Where the call-specific meaning lives.

Formatting is centralized in one place — pipelex/temporal/tprl/observability.py — so call sites stay thin:

build_search_attributes(pipe_job)         # 5 typed keys → TypedSearchAttributes
build_static_summary(pipe)                # "{code} — {description}", 200B clamp
build_static_details(pipe_job)            # markdown table, 20KB clamp
build_activity_summary(label, metadata,   # "{label} · pipe={code} · {extras…}"
                       extras={...})

7. Search attributes — the filterable layer

Five custom Keyword attributes, registered once per namespace, set on every workflow start:

Hard-fail at worker boot (Phase 6)

A real Temporal cluster rejects every StartWorkflowExecution RPC that references an unregistered attribute. We used to soft-warn at worker boot; now we hard-fail with the exact registration command embedded in the exception:

$ pipelex worker
SearchAttributeRegistrationError: namespace "default" is missing required attributes:
  PipeCode, PipelineRunId, SessionId, UserId, DomainCode

Register via Pipelex CLI:
  pipelex setup-temporal-namespace

Or via the Temporal CLI:
  temporal operator search-attribute create \
    --namespace default \
    --name PipeCode --type Keyword \
    --name PipelineRunId --type Keyword \
    --name SessionId --type Keyword \
    --name UserId --type Keyword \
    --name DomainCode --type Keyword

The escape hatch

# pipelex.toml — turn off custom attributes entirely
[temporal.search_attributes]
enabled = false
attributes = ["PipeCode", "PipelineRunId", "SessionId", "UserId", "DomainCode"]

• enabled = false skips both the worker-boot check and the per-workflow attribute attachment (use when the namespace is owned by a third party who will not register).
• The validator rejects unknown attribute names so typos like "PipelineRunID" fail at config load instead of silently producing no attribute.
• The new pipelex setup-temporal-namespace CLI wraps OperatorService.AddSearchAttributes so operators don't need a separate Temporal CLI install. --dry-run prints the equivalent raw command for handing off to a namespace admin.

8. Why the design is replay-safe

The load-bearing fact is that Temporal's SDK assigns activity IDs by history position — so replays produce the same IDs without Pipelex maintaining any worker-side state.

9. Before / after — the dashboard view

Event History — one workflow's activities

// BEFORE
ActivityTaskScheduled: id=craft-text, type=act_llm_gen_text
ActivityTaskScheduled: id=craft-text, type=act_llm_gen_text   ← collision, workflow crashes

// AFTER
ActivityTaskScheduled: id=1, type=act_llm_gen_text
  Summary: LLM text · pipe=translate_doc · model=gpt-4o
ActivityTaskScheduled: id=2, type=act_llm_gen_text
  Summary: LLM text · pipe=translate_doc · model=gpt-4o
ActivityTaskScheduled: id=3, type=act_llm_gen_object
  Summary: LLM object · pipe=translate_doc · class=Section

10. Where to look

• The decision log: wip/temporal-primitives/01-id-and-naming-design.md
• The per-phase execution: wip/temporal-primitives/02-id-and-naming-plan.md
• The reference inventory: wip/temporal-primitives/00-temporal-id-primitives.md
• The formatting helpers: pipelex/temporal/tprl/observability.py
• The bootstrap check + CLI: pipelex/temporal/tprl/namespace_check.py, pipelex/cli/commands/setup_temporal_namespace_cmd.py
• Companion note: queues-and-options.html — per-activity routing, per-queue options, worker-runtime profiles