Implement planned topic: 0032-workflow-streams

[skill-temporal-developer-updater]

Validation Report — workflow-streams (Python)

Scope of validation: the work introduced on branch draft/0032-workflow-streams vs. main:

• New file: references/python/workflow-streams.md (553 lines, 128 <!-- docs/... --> citation comments)
• Modified file: references/python/python.md — one line added to the Primary References list pointing at the new file

Topic classification: Python SDK contrib library (temporalio.contrib.workflow_streams), part of the official Temporal Python SDK. Not a third-party integration — references/integrations.md is not edited and no file is added under references/python/integrations/. Check 5 is skipped.

Source of truth: ../documentation/docs/develop/python/workflows/workflow-streams.mdx (567 lines). Every citation in the authored file resolves to this single doc.

---

Go / no-go

Check	Verdict
Check 1 — Citation audit	PASS (100% of citations resolve cleanly; threshold ≥98%)
Check 2 — Reverse-grep audit	PASS (every factual token in the authored file appears in the source doc; zero unexplained misses)
Check 3 — Regression on known bugs	PASS (zero hits on any universal regression pattern)
Check 4 — Independent re-verification	PASS (10/10 sampled claims match the docs; threshold ≥95%)
Check 5 — Integration-layout audit	N/A (not an integration topic)
Check 6 — Tone and scope audit	PASS (no workaround-disclosure findings; one minor Pattern-2 observation)

Overall verdict: GO. No re-authoring required. No mandatory fixes.

---

Check 1 findings — citation audit

Total docs citations: 128 inline <!-- docs/develop/python/workflows/workflow-streams.mdx:LINE --> comments (some lines carry multiple citations; the comment-grep counts 89 lines containing such comments). Every citation targets the single source doc.

Resolved cleanly: 128/128 (100%).

Unresolved: none. The highest line cited is 566; the source doc is 567 lines.

Mismatched (cite lands on a line that doesn't substantively support the claim): none.

Spot-confirmed structural anchors (sampled across the doc):

• Public Preview block (source 31–37) → authored 6, 10–14
• Hosting choice (source 51–57) → authored 26–31
• WorkflowStream construction + RuntimeError semantics (source 61, 82) → authored 37, 39, 62
• WorkflowStreamClient.create + from_within_activity (source 128–171) → authored 105–152
• force_flush=True vs. await client.flush() (source 173–196) → authored 156–177
• Subscribe + heterogeneous topics (source 204–249) → authored 187–234
• Closing the stream + ack handshake (source 255–297) → authored 238–285
• Continue-As-New (source 301–360) → authored 289–356
• Tuning table (source 364–381) → authored 360–374
• Delivery semantics (source 387–406) → authored 378–393
• Architecture + wire handler names (source 412–425) → authored 397–412
• Gotchas (source 431–433) → authored 416–418
• End-to-end LLM sample + "Why these choices" (source 441–560) → authored 422–545
• See also (source 564–566) → authored 549–551

---

Check 2 findings — reverse-grep audit

Every token class extracted from the authored file is present in the source doc:

Token class	Tokens checked	Misses
Public SDK identifiers	WorkflowStream (16), WorkflowStreamClient (19), WorkflowStreamState (6), RawValue (5), AcceptedUpdateCompletedWorkflow (1)	0
Methods on the new API	.topic(), .publish(), .subscribe(), .truncate(), .continue_as_new(), .detach_pollers(), .get_state(), .flush(), .from_within_activity(), .create(), all_handlers_finished	0
Keyword args / settings	batch_interval, max_batch_size, poll_cooldown, max_retry_duration, publisher_ttl, force_flush, prior_state, result_type, workflow_id, task_queue, retry_policy, run_timeout	0
Wire-level handler names	__temporal_workflow_stream_publish, __temporal_workflow_stream_poll, __temporal_workflow_stream_offset	0 (all three present on source line 421)
Sentinel/topic event names	RETRY (7), STATUS_CHANGE (3), TEXT_COMPLETE (1), AGENT_START (1), more_ready (1)	0
Workflow status enum values	COMPLETED, FAILED, CANCELED, TERMINATED, TIMED_OUT	0 (all on source line 297)
Code-sample API tokens	AsyncOpenAI, max_retries, gpt-4o-mini, activity.heartbeat, activity.info, is_continue_as_new_suggested, data_converter, payload_converter, from_payload, get_workflow_handle, execute_activity, Client.start_activity, wait_condition, activity.client, Client.connect	0

Unexplained grep-misses: 0.

---

Check 3 findings — regression on known bugs

Scanned both files in scope (references/python/workflow-streams.md and references/python/python.md) for every universal regression pattern in the template:

• --profile (should be --env)
• TEMPORAL_TLS_CLIENT_CERT_PATH / TEMPORAL_TLS_CLIENT_KEY_PATH / TEMPORAL_TLS_SERVER_CA_CERT_PATH
• tcld service-account
• --output text / --output jsonl
• saas-api.tmprl.cloud:7233

Hits: 0.

No topic-specific regression list exists for this skill (none accumulated from prior authoring passes).

---

Check 4 findings — independent re-verification

A subagent sampled 10 citations spaced across the file (every 10th citation starting at #5) and re-read the docs independently before comparing to the authored text:

#	Authored line	Cited doc line	Topic
5	20	25	"Use it for" list (UI, payment, data jobs)
15	39	82	Second WorkflowStream raises RuntimeError
25	131	153	from_within_activity() infers client + parent Workflow Id
35	183	200	Bound via upstream policy; library doesn't pick block/drop/error/sample
45	240	255	No coordination → polls until terminal state; round-trip gap risk
55	295	305	Add WorkflowStreamState | None field
65	366	379	poll_cooldown 100 ms; skipped only on more_ready
75	383	389	Cross-publisher interleaving is server-serialized, stable, not app-controlled
85	406	421	__temporal_workflow_stream_publish handler
95	542	557	Activity is the publisher because it owns the non-deterministic LLM call

Matches: 10/10 (100%).

Divergences: none. No drift on:

• mandatory vs. optional (e.g. authored "must" tracks doc "must")
• default values (batch_interval 2 s, poll_cooldown 100 ms, max_retry_duration 10 min, publisher_ttl 15 min — all correct)
• code-path attribution (which side runs in Workflow vs. Activity vs. client)
• caveats preserved (e.g. "stable once recorded but not under application control", "skipped only when more_ready")

---

Check 6 findings — tone and scope audit

Pattern 1 — workaround disclosure (mandatory; zero tolerated): none.

The two negative-form bullets in the file follow the acceptable "name the wrong path, give the supported alternative" shape:

• Line 417 ("Do not substitute workflow.sleep(0) — it records a timer event") — pairs with the supported fix asyncio.sleep(0). Acceptable.
• Line 372 ("Don't use it per-token or per-character") — pairs with the positive guidance on when to use force_flush=True. Acceptable.

The "explicit CAN recipe" at lines 343–354 (detach_pollers() + wait_condition(all_handlers_finished) + workflow.continue_as_new(...)) is not a workaround disclosure — both the continue_as_new(build_args) helper and the explicit form are first-class supported APIs documented at source mdx:351–358. The authored file frames it correctly as the supported way to pass extra CAN parameters (task_queue, retry_policy, run_timeout).

Likewise the "standalone Activity" fallback at line 150 (from_within_activity() raises → use WorkflowStreamClient.create(activity.client(), workflow_id=...)) is supported guidance, not a workaround.

Pattern 2 — in-the-weeds rationale: one minor observation.

The "Why these choices:" tail at lines 540–545 restates design rationale for the end-to-end LLM example. Each bullet justifies a positive pattern already shown in the code above; the rationale doesn't change what an agent writes (the agent would copy the pattern either way). Not a blocker — borderline finding worth noting if a follow-up cleanup pass is made.

Pattern 3 — multi-sentence bullets: the file's longer bullets each carry distinct semantic load (effect, return semantics, lifecycle scope, usage guidance), not redundant restating. Keep.

Pattern 4 — Public Preview admonition: present and correctly formed. Lines 3–4:

> [!NOTE]
> This feature is in Public Preview. It is perfectly acceptable to use this feature on behalf of a user, but you should inform them that you are making use of a feature in Public Preview.

This matches the standard admonition phrasing used elsewhere in the skill and the source's Public Preview marker at mdx:31–33.

---

Statistics

• Reference files in scope: 1 new (references/python/workflow-streams.md), 1 touched with a single line (references/python/python.md).
• Authored file length: 553 lines.
• Source-doc length: 567 lines.
• Citation comments: 128 inline <!-- docs/... --> tags (spread across 89 lines).
• Distinct source-doc lines cited: ~60 (the file cites a contiguous walk of the source doc).
• Check 1 resolution rate: 128/128 = 100%.
• Check 2 grep-misses: 0.
• Check 3 regression hits: 0.
• Check 4 sample size: 10/10 = 100% match.
• Check 6 mandatory-pattern findings: 0; one minor Pattern-2 observation.

---

Verdict

GO. The skill is accurate, grounded, and free of the fabrication patterns this validation looks for. The Public Preview admonition is in place. The one borderline Pattern-2 observation (the "Why these choices" tail in the end-to-end example) is optional cleanup, not a blocker.

[donald-pinckney]

@brianstrauch I killed the extended example. LMK if you think this is alright to merge for now.