[moetemp]

This PR moves the Streams API into temporalio.common, with the API of the SDK review and the fixes of an independent review.

The SDK review asked for Streams as a first-class SDK API, with native as the default backend. It also asked for backends registered on the client, and an owner that closes each Stream. An earlier commit of this PR put the API in temporalio.common.streams. It's now in temporalio.common itself, with the same public names.

What changed?

Modules.

• temporalio/common.py is now a package. The Stream code is in the private temporalio.common._streams. temporalio.common loads the Stream names on first use, so import temporalio.common loads no Stream code.
• Redis is temporalio.contrib.stream (RedisStreamBackend, create(client, ...) and workflow.*). The memory backend is temporalio.contrib.stream.testing.MemoryStreamBackend. temporalio.contrib.streams is gone.

Registration and entry points.

• Backends register with Client.connect(..., stream_backends=[...]). A Worker uses the backends of its client, and Replayer and WorkflowEnvironment take stream_backends=. With more than one backend, exactly one has default=True. A backend in plugins= is refused.
• With no backend marked, the default name is native. Brook has no native backend (Jetty adds it), so a create with no backend raises StreamConfigError.
• The entry points are workflow.create_stream, create_stream_nowait and stream_handle, Client.stream, and WorkflowHandle.stream. StreamClient is gone.
• Reads take offset and topic_prefixes. Only a Stream subscribes, not a Topic.
• WorkflowTopic.publish is a plain method. It starts the write when called and returns its asyncio.Future[int], so the write has its place in the Stream's order also with no await. await gives the offset or raises as before. A failed write that no caller awaits or checks fails the run at the run end.
• The *_nowait docstrings say that a StreamError fails the run and a config error fails the Workflow Task. The behavior is the same as before.

Lifecycle.

• No auto_close and no close_with_run. On Redis, a run end closes nothing.
• A Workflow close is a regular Activity, so it commits with its Workflow Task. A Local Activity can't close a Workflow's Stream.
• A block end closes the Stream at once only when the run can't get a retry run. Else the run end closes it, unless the run fails and the server starts a retry run. A cron run leaves the Stream open. When a cancel of the run ends the block, the Stream closes as CANCELED.
• Plugin.on_workflow_evicted, workflow.Info.execution_expiration_time and the plugin shutdown wait of the Worker are removed.

Other review fixes.

• Writes. An Activity retry continues with a closed or expired Stream argument, and the first write raises the real error. Pending Workflow appends are keyed by namespace, Stream and Producer, and are limited to 64 MiB. A refused append is dropped. A create of an expired Stream raises StreamExpiredError. A Record or batch over the Store limit raises the new StreamTooLargeError.
• Reads. A no-wait read continues while an empty page advances next_offset. A Closed item's failure is decoded with the reader's converter. A Record that fails to decode raises StreamError with its offset, and next_offset is the offset after it. The reader stores no offsets of client Records.
• API. async with on a client handle of a Workflow's Stream raises StreamNotOwnerError before the block runs. Client.stream refuses an empty id. End is public. A run adds the Stream key header to its Activities only when it uses Streams.
• Converter. A transfer type dataclass in a top-level list is written as its fields.
• Docs. Retention is a Record's age, also on an open Stream. The docstrings of Subscription.aclose, the errors and the eviction match the code.

Pins and CI.

• Pins crate s23 ee6d1e51 and Core c8 f7826366, with regenerated protos and bindings.
• The Stream tests decode the crate's vectors as UTF-8, for Windows. The backends take a client config with no interceptors. The generated Stream Nexus clients are hidden from the API docs. Upstream's pydantic 2.14 annotation (fix: annotate pydantic TypeAdapter cache for pydantic 2.14 temporalio/sdk-python#2011) is cherry-picked for test-latest-deps. Changelog fragments in added/ and changed/ describe the new API.

Known limits.

• A Worker with a Redis backend polls Activities on its task queue for the close Activity. So every Worker on that queue must register the backend. A Worker with Streams and no_remote_activities=True logs a warning, since another Worker must run the close.
• The run-end check doesn't see the execution timeout. If the chain's execution timeout stops a retry, the Stream stays open.

Why?

A close must not apply if its Workflow Task fails, so it runs as an Activity. The independent review of Brook and Jetty found that a Local Activity could still close early. It also found that a cancel closed a Stream as failed, that filtered reads could stall, and that an Activity retry failed on a closed Stream.

How did you test it?

Each review fix has a test that fails without it, apart from the docstring fixes. At the head, pytest tests/contrib/streams and the worker, replayer and testing suites pass on memory and Redis. New tests cover a publish with no await and a failed publish that no caller gets. A test checks that import temporalio.common loads no temporalio.common._streams in a fresh interpreter. The client, plugin, pydantic and converter suites pass. The upstream test_schedule_basics failed once on a shared dev server with schedules of other tests, and it passes alone. poe lint (ruff, pyright, mypy, basedpyright and pydocstyle) and poe gen-docs are clean.

On the fork CI, every job passes except check-protos and the arm64 jobs. check-protos waits on a nexgen release with temporalio/nexgen#260, which merged after v0.2.10. The arm64 jobs have no runner on the fork.

The superproject branch temporalio/internal-ai-prototypes 2026/10/ai198-streams pins the head, 415fb36a. sdk-python j9 and the harness use the new temporalio.common names.

• Unit Tests
• Staging
• End to End Tests

[moetemp]

Closed in favor of the review series. The net change is G1 to G3, B1 and S1 to S9, #367 to #379, cut fresh onto upstream main (plan: Brook: code review and upstream plan). The branch stays, since the superproject pins it and Jetty's #366 builds on it.