[THardy98]

Summary

Add an experimental sample showing how workflow-session activity affinity lets workflows reuse worker-local conversation history, and makes the impact visible.

• One entrypoint starts independent worker processes (default 4), runs concurrent workflows (default 20 per mode) with affinity off and then on, and shuts down the workers.
• Each workflow is a conversation of sequential conversation_step activities (default 6 turns). Turn n needs every earlier turn 0..n-1. Each worker caches the turns it holds per workflow Run ID and fetches only the turns it is missing, with simulated latency per turn (--fetch-seconds, default 0.5s). Turn 0 needs no history; the history is not workflow state.
• With affinity on, the workflow's worker produced every earlier turn, so it never fetches. With affinity off, stale or cold workers fetch the turns they are missing, so cost scales with how far behind each worker is.
• Activities stream start/finish events to the parent over a multiprocessing queue, which drives:
  • an optional live Rich view (live.py) of how far each worker holds each conversation, plus per-workflow placement strips (○2 = worker 2 had every earlier turn, ●2(3) = worker 2 fetched 3 missing turns); disabled with --no-live or when not a TTY;
  • a final summary with side-by-side placement strips and an impact table (turns fetched, steps that had to fetch, time spent fetching, cached turns across the fleet, p50/p95 latency, wall time).
• Workflows start only after all workers are polling; eager activity execution is disabled; the command exits non-zero if any affinity-on workflow ran on more than one worker or fetched any turn.
• Supports activity-only workers (--activity-workers) alongside session workers.

Requirements and scope

Requires the experimental SDK from temporalio/sdk-python#1979 and server from temporalio/temporal#12630, with sticky activity execution enabled for the namespace. The README explains running with the feature SDK interpreter.

Demonstrates healthy-worker affinity and cache reuse, not failover. Ordinary routing may colocate activities by chance.

Validation

• Manual run against the custom server with defaults: affinity off fetched 180 turns (90s of fetching) vs 0 with affinity on; p50 workflow latency 5.0s vs 0.6s.
• Cache/report tests: 10 passed; 3 custom-server integration tests skipped.
• ruff check/format passed.