Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

docs(wip): tidy and reconcile work-in-progress docs (Phases 1-3) (#951)

Louis Choquel9547d46dd880
diff --git a/TODOS.md b/TODOS.md
index ddb0dcfb4..d1a5140fc 100644
--- a/TODOS.md
+++ b/TODOS.md
@@ -1,307 +1,15 @@
-# Data-Class Best-Practices Refactor — Working Ledger (`refactor/Dataclasses`)
+# WIP-Docs Tidy — Recap
-Give every data holder the right shape. Eradicate every stdlib `@dataclass` (HARD RULE 1) — but replace it with whichever form fits the site, NOT uniformly with `BaseModel`.
+A cleanup of the `_docs/wip/` documentation tree (branch `docs/Tidy`), aimed at making `wip/` hold only real work-in-progress and making the surviving docs read as current reality. What it did, in kind:
-**On the Temporal wire:** `BaseModel` or (after Phase 0) a pydantic dataclass — the two forms `BaseModelPayloadConverter` routes through kajson with type preservation.
+- **Reorganized the tree.** Grouped loose top-level docs into topic folders, separated finished material from active work, and deleted derived `.html` renders and dead duplicates.
-**Off the wire, choose per-site** (this is the premise — pydantic dataclass is a first-class option here, often the lowest-churn one):
+- **Moved finished material out of the public repo.** Completed plans and design history went to the private workspace `docs/history/`; internal forward-looking plans (e.g. the Temporal enterprise-readiness roadmap) went to private `docs/plans/`. `wip/` now contains only things started or about to start — active plans, designs, and current-state trackers with open gaps.
-- **`NamedTuple`** — a small fixed immutable record replacing a bare tuple. Also the only safe form when a field is a bare `@runtime_checkable` Protocol / arbitrary non-pydantic type, because it skips validation (no `arbitrary_types_allowed` dance). Avoid when the type is returned in a union alongside a real `tuple` (a NamedTuple *is* a tuple → ambiguous `isinstance`).
-- **pydantic dataclass** (`from pydantic.dataclasses import dataclass`) — a validated record that wants to keep dataclass idioms (`field(default_factory=...)`, computed `@property`, `frozen=`) with **minimal churn** (often just swap the decorator import). Wire-legal since Phase 0. **Use it ONLY for internal records that are constructed + field-read and never serialized.** A pydantic dataclass has no `.model_dump()` / `.model_validate()` methods — and "does this ever need serializing/dumping?" is the *deciding* question, not an afterthought: **if it ever needs dumping, make it a `BaseModel` from the start — do NOT reach for `TypeAdapter`.** Needing `TypeAdapter` means the wrong shape was picked; keep `TypeAdapter` out of the codebase entirely.
-- **frozen `BaseModel`** — an immutable validated value object that needs the full model API (`model_dump`, validators, discriminated unions) OR sits in a layer that is uniformly `BaseModel` (e.g. `pipelex/builder/`), OR must stay type-distinct from a sibling `tuple` in a union return.
-- **plain mutable `BaseModel`** — genuinely mutated in place AND wants the model API / layer-consistency; otherwise a non-frozen pydantic dataclass is the lighter choice for in-place-mutated records.
+- **Made the public docs self-contained and current.** Removed every pointer from the public repo into the private one, and scrubbed the history/PR noise that misled agents about present state — PR numbers, commit hashes, branch and ledger names, dated checkpoint narrative, "archived plans" lists. Docs now describe what the code does today, not how it got there.
-Phase 0 is the foundation: generalize the Temporal converter (and kajson, in `../kajson`) so pydantic dataclasses are wire-legal, relaxing the "must be BaseModel on the wire" constraint. It is purely additive — no current wire type is a pydantic dataclass, so no existing payload changes. Everything after Phase 0 is off-wire and chosen per-site.
+- **Corrected stale claims** in the surviving current-state docs, each verified against the code in this worktree, and trimmed one landed-but-written-as-a-proposal doc down to an as-built reference.
-This ledger supersedes the completed `feature/API-readiness-4` ledger (archived to `wip/error-handling/archive-todos-api-readiness-4.md` on 2026-05-29). The original free-form plan that seeded this ledger was at `wip/data-class-best-practices-plan.md` (now removed; this file replaces it).
+- **Split out the remaining work.** The runtime code-fix follow-ups the tidy surfaced live in [`wip/runtime-code-fixes.md`](wip/runtime-code-fixes.md); everything else open is tracked per-feature inside the relevant `wip/` track or standalone doc (see [`wip/README.md`](wip/README.md)).
----
-
-## Cold-start reading order
-
-A fresh session should read, in order:
-
-1. **This file, top to bottom.** It is the single source of truth for what to do and what's done.
-2. **The "Session log" at the bottom** — the most recent entry is the handoff note from the last session: what landed, decisions taken, open questions, and the exact next action.
-3. **`pipelex/temporal/temporal_data_converter.py`** — the converter being generalized in Phase 0. Read `BaseModelPayloadConverter.to_payload` / `from_payload`.
-4. **`../kajson/kajson/json_decoder.py`** (`_apply_decoder_strategies`, ~line 196) and **`json_encoder.py`** (`default`, ~line 107) — the kajson dispatch Phase 0 extends.
-5. The per-item detail sections below carry the *why* for each conversion; trust them but re-confirm any path/line reference against the current tree before editing (the off-wire audit was originally taken against a sibling `refactor/Paths` worktree).
-
----
-
-## How to use this ledger
-
-- **Checkboxes** track progress. Flip `[ ]` → `[x]` the moment a task lands (with its verification green), and append a one-line result (what changed + where) right under it. Do not batch.
-- **Checkpoints are HARD STOPS.** When you reach a `🛑 HARD STOP` marker you MUST end the session after completing the context-save protocol below — do not roll into the next phase in the same session. They sit at natural handoff points where a coherent unit has landed and context has grown enough to warrant a fresh start.
-- **Context-save protocol** (run at every hard stop, before ending the session):
- 1. Flip all completed checkboxes and write their one-line results.
- 2. Append a new **Session log** entry (template at the bottom): date, what landed, decisions taken, open questions, current code state (clean? mid-edit?), and the single exact next action for the next session.
- 3. Record any deviation from this plan inline in the relevant item, with the reason.
- 4. Confirm the tree is in a clean, committed (or clearly-described) state — the next session must be able to cold-start with zero memory of this one.
-- **Verification commands** (run as noted per phase; never skip on a hard stop):
- - `make agent-check` — after every code change.
- - `make tb` — after any change touching boot/config/import paths.
- - `.venv/bin/pytest tests/integration/pipelex/temporal/` — after any change in `pipelex/temporal/` or the converter/kajson.
- - `make agent-test` — full suite, at the final gate.
-
----
-
-## Safety boundary — wire types must be BaseModel or pydantic dataclass
-
-These types cross the Temporal wire directly or transitively. After Phase 0, each MUST be a `BaseModel` **or** a pydantic dataclass — the two forms `BaseModelPayloadConverter` routes through kajson with type preservation. A `NamedTuple`, stdlib dataclass, or arbitrary class here falls through to Temporal's stock JSON path and silently corrupts distributed execution or hard-fails deserialization.
-
-**Every type on this list currently is, and should remain, a `BaseModel`.** They rely on machinery pydantic dataclasses don't provide as cleanly — discriminated unions, model validators, `model_dump`, the dynamic-class `__kajson_class_source__` mechanism. Phase 0 widens what is *legal* on the wire; it does NOT motivate converting anything already here. Do not convert these to pydantic dataclasses just because Phase 0 makes it possible.
-
-- `PipeRunArg` (`pipelex/temporal/tprl_pipe/pipe_run_arg.py`) — direct argument of `WfPipeRun.run`. Already `BaseModel`.
-- `PipeJob` (`pipelex/pipe_run/pipe_job.py`) — argument of `WfPipeRouter.run`; field of `PipeRunArg`.
-- `PipeOutput` (`pipelex/core/pipes/pipe_output.py`) — return of both router workflows; field of `DeliveryActivityArg`.
-- `DeliveryAssignment` (`pipelex/pipe_run/delivery_assignment.py`) — field of `PipeRunArg` and `DeliveryActivityArg`.
-- `DeliveryActivityArg` (`pipelex/temporal/tprl_pipe/act_deliver.py`) — argument of `act_deliver`.
-- `DeliveryStatus` (StrEnum, `pipelex/pipe_run/delivery_assignment.py`) — enclosed in `DeliveryActivityArg`; the StrEnum is fine, keep the enclosing type a `BaseModel`.
-- `ErrorReport` (`pipelex/base_exceptions.py`) — field of `DeliveryActivityArg`.
-- `AssembleGraphArg` (`pipelex/temporal/tprl_pipe/act_assemble_graph.py`) — argument of `act_assemble_graph`.
-- `GraphSpec` (`pipelex/graph/graphspec.py`) — return of `act_assemble_graph`; field of `PipeOutput`.
-- `PipelineRef` (`pipelex/graph/graphspec.py`) — embedded in the returned `GraphSpec`.
-- `FlushTraceEventsArg` (`pipelex/temporal/tprl_pipe/act_flush_trace_events.py`) — argument of `act_flush_trace_events`.
-- `JobMetadata` (`pipelex/pipeline/job_metadata.py`) — field of `PipeJob`.
-- `GraphContext` (confirm path: `grep -rn "class GraphContext" pipelex/`) — field of `JobMetadata`, transitively on `PipeJob`.
-- `WorkingMemory` (`pipelex/core/memory/working_memory.py`) — field of `PipeJob` and `PipeOutput`.
-- `PipeRunParams` (`pipelex/core/pipes/pipe_run_params.py`) — field of `PipeJob`.
-- `PipeAbstract` + all concrete pipe subclasses (`pipelex/core/pipes/pipe_abstract.py`; confirm) — the `pipe` field of `PipeJob`.
-- `LibraryCrate` (confirm path: `grep -rn "class LibraryCrate" pipelex/`) — field of `PipeJob`.
-- `Stuff` (`pipelex/core/stuffs/stuff.py`) — contained in `WorkingMemory`.
-- `StuffContent` + the entire discriminated-union hierarchy (`pipelex/core/stuffs/stuff_content.py`): `TextContent`, `ImageContent`, `PdfContent`, `ListContent`, `StructuredContent`, `HtmlContent`, `NumberContent`, etc.
-- `ImageContent` — return element of content-gen activities (`list[ImageContent]`).
-- `PageContent` (confirm exact file) — return element of a content-gen activity (`list[PageContent]`).
-- Page-view content payload(s) — returned by the render-page-views activity, embedded in `PageContent.page_view`. Confirm exact class name(s) by reading the activity return annotation and the `PageContent.page_view` field BEFORE touching anything nearby; highest-risk list-element serialization spot.
-- `TraceEvent` + subtypes (`pipelex/tracing/...`) — element type of `FlushTraceEventsArg.events`. Confirm via the `events` annotation and `BufferingEventLog.drain` return type.
-
----
-
-## Pre-flight — freeze the boundary (do before any edit)
-
-- [x] Re-confirm the wire layer is clean: `grep -rn "@dataclass\|NamedTuple" pipelex/temporal/` returns nothing.
- - Result: only two matches, both off-wire and slated for later phases — `config_temporal.py:366` (`DispatchOptions`, Phase 5) and `tprl/namespace_check.py:50` (`RegistrationFailure`, Phase 4). No *wire* type is a dataclass/NamedTuple.
-- [x] Resolve every "confirm path" entry in the safety boundary above (`GraphContext`, `LibraryCrate`, `PipeAbstract`, `PageContent`, page-view payload, `TraceEvent`) and pin the paths.
- - Result (all `BaseModel`): `GraphContext`=`pipelex/graph/graph_context.py:12`; `LibraryCrate`=`pipelex/libraries/library_crate.py:11`; `PipeAbstract`=`pipelex/core/pipes/pipe_abstract.py:46`; `PageContent`=`pipelex/core/stuffs/page_content.py:13` (StructuredContent); page-view payload = `PageContent.page_view: ImageContent | None` (line 15) → already-listed `ImageContent`; `TraceEvent`=`pipelex/tracing/trace_events.py:34`.
-
----
-
-## Phase 0 — Generalize the converter (+ kajson) to accept pydantic dataclasses
-
-Goal: stop the converter from being the sole arbiter of domain-model shape. Today `BaseModelPayloadConverter` routes only `BaseModel` / `Optional[BaseModel]` / `list[BaseModel]` through kajson; everything else falls through to Temporal's stock JSON. Phase 0 widens that to pydantic dataclasses (and `Optional` / `list` of them). Scope is pydantic dataclasses ONLY — `NamedTuple` stays out (kajson flattens it to a bare JSON array, losing field names + type), stdlib dataclasses stay out (HARD RULE 1 eradicates them), arbitrary classes stay out (unsafe `__dict__`-replace path).
-
-### Layer 1 — kajson (`../kajson`, editable via this worktree's `uv.lock`)
-
-kajson v0.5.0 has no dataclass support and no dataclass tests. A pydantic dataclass currently only survives via the untested generic catch-all: encode via `__dict__` (`json_encoder.py` ~160), decode via `the_class(**the_dict)` (`json_decoder.py` ~293). The decode path is fragile — if validation raises there, the next line swallows it (`except Exception: pass`) and falls through to the unsafe `obj.__dict__ = the_dict` path, then to returning a raw dict. Silent corruption instead of a loud error.
-
-- [x] **0.1** Add an explicit pydantic-dataclass branch in `_apply_decoder_strategies` (after the `Enum` / `BaseModel` branches, before the generic constructor), using `pydantic.dataclasses.is_pydantic_dataclass`. Reconstruct via the dataclass' pydantic validator (validates), and on `ValidationError` raise `KajsonDecoderError` loudly with dict context — mirroring the existing `BaseModel` branch (~line 265). No silent fall-through.
- - Result: added `is_pydantic_dataclass` import + the branch in `../kajson/kajson/json_decoder.py` (`return the_class(**the_dict)`, `except ValidationError → raise KajsonDecoderError(...) from exc`). Confirmed the prior behavior was silent corruption (bad dataclass payload returned a raw `dict`); now raises loudly.
-- [x] **0.2** Add kajson round-trip tests in `../kajson/tests`: pydantic dataclass with (a) nested `BaseModel` field, (b) `Optional` field, (c) `list` of pydantic dataclasses, (d) `timedelta` field, (e) a subclass (type preservation); plus a negative test that a bad payload raises `KajsonDecoderError` (not silent corruption). Lock encode-via-`__dict__` with an explicit assertion rather than relying on the catch-all.
- - Result: `../kajson/tests/unit/test_pydantic_dataclass.py` (7 tests, all cases above + encode-via-`__dict__` metadata assertion + negative test). The negative test was the TDD red (DID NOT RAISE before 0.1, green after). Full kajson suite green (257 passed, 1 skipped); kajson `make agent-check` clean.
- - Follow-up from code review: the timedelta round-trip initially needed a band-aid (an earlier suite test, `test_json_encoder`, clears the process-global codec registry without restoring). Fixed the **root cause** instead — `test_json_encoder.py` / `test_json_decoder.py` autouse fixtures now snapshot the registry and restore it on teardown — and removed the band-aid. The new dataclass tests are order-independent without re-registering anything.
-- [x] **0.3** Bump kajson version in `../kajson/pyproject.toml` + add a CHANGELOG entry (genuine new capability, benefits all kajson users).
- - Result: `0.5.0` → `0.6.0` + dated CHANGELOG entry. kajson is on its own `feature/Support-more-types` branch (versioned-only CHANGELOG convention — no `[Unreleased]`). Editable install means the pipelex venv serves the live source; installed metadata stays `0.5.0`, so the pipelex `kajson==0.5.0` pin is still satisfied. **Do NOT run `uv lock`/`uv sync` in this worktree until the pin is bumped** — the `==0.5.0` exact pin would conflict with the editable `0.6.0`. Pin bump stays bundled with the PyPI publish at the release gate (below).
-
-### Layer 2 — the converter (`pipelex/temporal/temporal_data_converter.py`)
-
-Widen two predicates; leave the `BaseModel` path byte-identical.
-
-- [x] **0.4** `to_payload` (~line 56): factor `_is_kajson_wire_value(value) -> bool` = `isinstance(value, BaseModel) or is_pydantic_dataclass(type(value))`; route both single-value and first-element-of-list cases through kajson when it holds. `BaseModel` check first (hot-path short-circuit). The `__kajson_class_source__` lookup stays (it's `None` for dataclasses — harmless).
- - Result: added `_is_kajson_wire_value(value: object)` + extracted `_kajson_to_payload(value, source_type_holder)` (shared by the scalar and list branches) + `_first_kajson_list_element` (list probe). BaseModel path is byte-identical (locked by the 0.6 regression guard). **Type-checking deviation:** the original relied on inline `isinstance` narrowing; the predicate is non-narrowing, so to keep pyright-strict `reportUnknownArgumentType` happy I typed the value predicate param as `object` (so `type(value)` is `type[object]`, not `type[Unknown]`) and kept `value` explicitly `Any` at call sites.
-- [x] **0.5** `from_payload` (~line 138): factor `_is_kajson_type(tp) -> bool` = `BaseModel` subclass **or** `is_pydantic_dataclass(tp)`; reuse it in all three hint checks (scalar, `Optional`, `list`). `_restore_class_source` only fires when `class_source_code is not None` (BaseModel-only), so dataclasses correctly skip it.
- - Result: added `_is_kajson_type(type_hint)`, generalized `_unwrap_optional_base_model` → `_unwrap_optional_kajson_type`, and reused `_is_kajson_type` in all three checks (scalar, Optional, list). `is_pydantic_dataclass` is runtime-safe on non-class hints (returns `False`), so the inner `Optional`/`list` args need no guard. One `cast("Any", type_hint)` collapses the post-`isinstance` `Any | type[Unknown]` for the typed probe.
-
-Perf note: adds one cheap `is_pydantic_dataclass()` check per conversion, behind the `BaseModel` short-circuit. Negligible; no benchmark needed (changes no existing payload).
-
-### Test perimeter (three layers — most safety-critical seam)
-
-- [x] **0.6** Converter unit round-trip: call `to_payload` / `from_payload` directly for a pydantic dataclass and for `Optional[...]` / `list[...]` hints; assert value + concrete type survive. **Regression guard:** assert a `BaseModel` payload is byte-identical to before (the untouched path).
- - Result: `tests/integration/pipelex/temporal/data_converter/test_data_conv_dataclass.py` — scalar / `X | None` / `list[X]` dataclass round-trips (concrete type + nested BaseModel preserved) + a byte-identical guard for a plain BaseModel (metadata == `{encoding}`, data == `kajson.dumps(model)`). 8 tests in the dir pass.
-- [x] **0.7** Temporal integration round-trip: a `@workflow.defn` / `@activity.defn` taking and returning a pydantic dataclass, exercised through the in-process test server (`tests/integration/pipelex/temporal/`).
- - Result: `tests/integration/pipelex/temporal/test_wf_dataclass_roundtrip.py` — `WfEchoDataclassPayload` forwards a `@pydantic_dataclass` (with nested BaseModel + `timedelta` fields) through an activity via `WorkflowEnvironment.start_local` + `Worker`; asserts type preserved end-to-end. Green. Broader temporal integration suite (non-inference) re-run clean: 136 passed, 4 pre-existing xdist-race xpass, no regressions.
-
-### Cross-repo wiring
-
-This worktree's `uv.lock` pins kajson as `{ editable = "../kajson" }` (confirmed) — changes in `../kajson` are picked up live, no publish needed for dev/test. `pipelex/pyproject.toml` still declares `kajson==0.5.0`; that specifier only bites at pipelex release time.
-
-- [x] **0.8** After 0.4/0.5 land, update the "Safety boundary" heading wording in this file from "must be BaseModel" framing to the now-true "BaseModel or pydantic dataclass" (already drafted above — just confirm it matches what shipped).
- - Result: confirmed — the heading and body wording ("each MUST be a `BaseModel` **or** a pydantic dataclass — the two forms `BaseModelPayloadConverter` routes through kajson") matches what shipped (`_is_kajson_wire_value` / `_is_kajson_type` route both forms through kajson). No edit needed.
-- [x] **0.9** Verify the editable kajson install survives any `uv sync` run during this phase (re-check `uv.lock` line for `editable = "../kajson"`).
- - Result: `uv.lock` still pins `source = { editable = "../kajson" }` (line 1972); no `uv lock`/`uv sync` was run. Verified the pipelex worktree's `.venv` serves the live kajson source (imports the new decode branch; bad payload raises `KajsonDecoderError`) with installed metadata still `0.5.0`. **Caveat:** a `uv lock` regeneration WOULD now conflict (editable `0.6.0` vs `kajson==0.5.0` pin) — defer until the release-gate pin bump.
-
-**Verify Phase 0:** kajson dataclass tests green · converter unit round-trip green (incl. BaseModel-unchanged regression guard) · `.venv/bin/pytest tests/integration/pipelex/temporal/` green · `make agent-check` + `make tb` clean.
-
-> 🛑 **HARD STOP 1 — Converter generalized.** Foundation in place across two repos; wire rule is now "BaseModel or pydantic dataclass." Run the context-save protocol and END THE SESSION. The off-wire refactor (Phases 1–5) builds on top without depending on Phase 0's internals, so a fresh session can pick up cleanly. **Release-gate to record (not dev-blocking):** publish the new kajson to PyPI + bump the `kajson==` pin in `pipelex/pyproject.toml` before pipelex ships a release depending on the new feature.
-
----
-
-## Phase 1 — ~~Capture perf baseline~~ → DROPPED after review (no production code changes either way)
-
-**The whole perf-measurement effort (this phase + Phase 6's perf diff) was BUILT, then DROPPED on review (user decision, 2026-05-29).** The harness (`tests/perf/test_dataclass_forms_bench.py` + `tests/perf/baselines/dataclass_refactor_pre.json`) was deleted.
-
-Why it measured nothing useful:
-
-- It benchmarked **synthetic stand-ins**, not the real classes. The `DispatchOptions*` stand-ins matched the real field shape, but the "wire anchor" was a fake type that timed pydantic's native `model_dump_json`/`model_validate_json` — **NOT** the real Temporal wire path (`BaseModelPayloadConverter` → kajson with type-preservation metadata). So the one number meant to guard "no wire type got heavier" never touched the actual wire code.
-- The costs are **negligible in context**: the only conversion that could plausibly regress is `DispatchOptions` (one build per activity dispatch, ~360ns form-delta) — dwarfed by the 10²–10³ ms network round-trip of the activity it configures.
-- **None of the Phase 2/3/4 conversions sit on a hot path** (build-time, per-usage-event, dev-CLI, template-prep, worker-boot), so their construction speed never shows up in real behavior.
-
-Consequence for the `DispatchOptions` form decision (Phase 5): it now rests on **reasoning** (per-dispatch cost is negligible vs the network round-trip), not measurement — no perf data is needed to accept frozen `BaseModel`.
-
-- [x] **1.1 / 1.2** — built the harness + captured the pre-change baseline, then **removed both** per the review above.
-
----
-
-## Phase 2 — NamedTuple upgrades (off-wire bare-tuple returns, lowest risk)
-
-Verified-to-exist bare-tuple returns where named fields prevent positional swaps. All off the wire, already-typed, no validation needed → NamedTuple (not pydantic dataclass). Replace `from typing import Tuple` annotations; keep `NamedTuple` defs module-local next to the function (or shared where two siblings return the same shape).
-
-- [x] **2.1** `_handle_basic_blueprint` (~line 336) + `_handle_refines` (~line 377) in `pipelex/core/concepts/concept_factory.py` — both return `(structure_class_name, refine_string)` with `refine_string: str | None`. Define ONE shared NamedTuple (e.g. `StructureNameAndRefine`) and reuse for both.
- - Result: added module-level `class StructureNameAndRefine(NamedTuple)` with `structure_class_name: str`, `refine_string: str | None`. Both methods now return it (6 return sites wrapped: 4 in `_handle_basic_blueprint`, 2 in `_handle_refines`). `_handle_refines`'s refine widened from `str` → `str | None` (its sole caller passes straight to `Concept.refines: str | None`, so type-safe). All 3 call sites use positional unpacking — unchanged. Confirmed `Concept.refines` is `str | None`.
-- [x] **2.2** `split_cross_package_ref` (~line 197) in `pipelex/core/qualified_ref.py` — `(alias, remainder)`. Define e.g. `CrossPackageRef(alias, remainder)`. All call sites (`qualified_ref.py`, `core/domains/validation.py`, `core/concepts/concept_factory.py`, `core/concepts/validation.py`, `libraries/library.py`, `libraries/library_manager.py`, `libraries/pipe/pipe_library.py`, `libraries/concept/concept_library.py`) destructure into two locals — none relies on plain-tuple `len`/concat or passes the tuple onto a wire path. Safe.
- - Result: added module-level `class CrossPackageRef(NamedTuple)` with `alias: str`, `remainder: str`; `split_cross_package_ref` now returns `CrossPackageRef(alias=..., remainder=...)`. Re-grepped ALL 12 current call sites (the plan's list was close but I verified against the live tree) — every one uses positional 2-tuple unpacking (`alias, remainder = ...` or `_, remainder = ...`), so none changed. Core+pipes suite green (1323 passed).
-- [x] **2.3** ~~`_get_is_prod_and_runtime_mode` in `pipelex/system/runtime_manager.py`~~ — **DOES NOT EXIST in current tree (skipped).** There is no `runtime_manager.py`; runtime mode lives in `pipelex/system/runtime.py` and is now fully **property-based** on a `RuntimeManager(BaseModel)` (`is_unit_testing`, `is_ci_testing`, `environment`, `run_mode` props) — no `(is_prod, runtime_mode)` tuple helper anywhere (grep-confirmed). The stale audit predates that refactor. Nothing to convert.
-- [x] **2.4** ~~`_find_project_root` in `pipelex/config_manager.py`~~ — **DOES NOT EXIST in current tree (skipped).** `config_manager.py` is now `pipelex/system/configuration/config_loader.py` (`config_manager = ConfigLoader()`); its `find_project_root(start_dir) -> Path | None` returns just `Path | None` — the `found_root_marker` bool was dropped in the refactor, so there is no `(Path, bool)` tuple to convert (grep-confirmed no such tuple anywhere).
-
-**Verify:** `make agent-check`; `make tb` (runtime_manager / config_manager touch boot paths). Temporal suite not required (nothing near the wire).
- - Result: `make agent-check` clean (pyright 0/0, mypy 1932 files); `make tb` 2 passed; targeted `tests/unit|integration/pipelex/core/` + `tests/integration/pipelex/pipes/` → 1323 passed, 1 xfailed (pre-existing known-bug marker).
-
----
-
-## Phase 3 — Off-wire stdlib dataclass removals (no wire, no hot-path concern)
-
-HARD RULE 1: every stdlib `@dataclass` must go. These four are off-wire and not perf-critical. Form chosen per-site per the form-selection guide at the top of this file — **including pydantic dataclass**, which for records already written in dataclass style (`field(default_factory=...)` + computed `@property`) is the lowest-churn replacement (just swap the decorator import).
-
-- [x] **3.1** `_EventLogContext` — `pipelex/reporting/reporting_manager.py` → **NamedTuple**. Fields `event_log: EventLogProtocol`, `workflow_id`, `pipeline_run_id`. Private manager state in `ReportingManager._event_log_contexts`, set wholesale + popped, never field-mutated, never serialized. `event_log` is a bare `@runtime_checkable` Protocol instance stored as-is. NamedTuple avoids needing `arbitrary_types_allowed`.
- - Result: `@dataclass\nclass _EventLogContext` → `class _EventLogContext(NamedTuple)`; removed the now-unused `from dataclasses import dataclass`. Confirmed all uses are kwargs-construction (line ~90), dict store/pop, and attribute reads (`context.event_log.next_sequence()`, `.pipeline_run_id`, `.workflow_id`, `.event_log.emit(...)`) — no field mutation. Reporting unit suite green.
-- [x] **3.2** `ErrorPagesReport` — `pipelex/errors/error_pages_generator.py` → **frozen `BaseModel`**. Four `list[Path]` fields via `Field(default_factory=list)` + a computed `total` `@property`. ~~Single full-kwargs construction, no in-place `.append` on instances → frozen holds.~~ `Path` serializes natively in pydantic v2; the computed-property + default_factory pattern argues for BaseModel over NamedTuple.
- - Result (FINAL, after 2nd review pass): **frozen pydantic dataclass** (`@pydantic.dataclasses.dataclass(frozen=True)`, `field(default_factory=list[Path])` ×4 + the `total` `@property`). This is the near-zero-diff replacement of the original `@dataclass(frozen=True)` — just swapped `from dataclasses import dataclass` → `from pydantic.dataclasses import dataclass` (kept `from dataclasses import field`). It's a dev-tool report with no model-API need, so a pydantic dataclass fits better than `BaseModel` (which I'd used in the first pass — reverted). **DEVIATION from plan rationale (still applies):** the plan claimed "single full-kwargs construction, no in-place `.append`" — STALE: it's built empty (`ErrorPagesReport()`) then **appended in place** (`_commit_page`/`_remove_orphans`). `frozen=True` (stdlib dataclass, pydantic dataclass, AND BaseModel) blocks attribute *reassignment*, NOT list mutation — `.append` works under all. Errors suite + type_uri-uniqueness test green (318 passed in the errors+jinja2+templating run).
-- [x] **3.3** `CustomClassInfo` — `pipelex/builder/runner_code.py` → **frozen `BaseModel`**. Scalar fields (`class_name`, `domain_code`, `concept_code`) + two computed `@property` (`module_name`, `import_statement`). Builder/codegen artifact, never mutated, never a Temporal arg/return. `builder/CLAUDE.md` says the builder layer is uniformly pydantic; the properties make NamedTuple awkward.
- - Result: `@dataclass` → `class CustomClassInfo(BaseModel)` with `model_config = ConfigDict(frozen=True)`; both properties kept; removed `from dataclasses import dataclass`. Confirmed all uses are kwargs-construction (line ~116) + attribute reads + use as `dict[str, CustomClassInfo]` values — no field mutation, no instance hashing relied upon (frozen makes it hashable anyway, a superset). Builder suite green.
-- [x] **3.4** `VariableReference` — `pipelex/tools/jinja2/jinja2_required_variables.py` → **mutable (non-frozen) `BaseModel`** with `filters: list[str] = Field(default_factory=list)`. CRITICAL: it is MUTATED IN PLACE — `_collect_variable_references` does `references[full_path].filters.append(filter_name)` on re-seen variables. In-place mutation rules out NamedTuple and any frozen form. Do NOT freeze it. (low-medium risk: preserve the append-after-construction contract.)
- - Result (FINAL, after 2nd review pass): **non-frozen pydantic dataclass** (`@pydantic.dataclasses.dataclass`, `path: str` + `filters: list[str] = field(default_factory=list[str])`). Near-zero-diff replacement of the original `@dataclass` — swapped `from dataclasses import dataclass` → `from pydantic.dataclasses import dataclass` (kept `field`), and used `list[str]` as the factory so no `# pyright: ignore` is needed (the original had one). Chosen over `BaseModel` (first pass — reverted): it's mutated in place and has no model-API need, so a pydantic dataclass is the lighter, more idiomatic fit. Confirmed the in-place `.filters.append(...)` works (pydantic dataclasses don't validate on attribute access/mutation, only on init). jinja2 var-ref unit tests + templating pipeline green.
-
-**Verify:** `make agent-check` after each; `make tb` after the group.
- - Result: `make agent-check` clean (pyright 0/0, mypy 1932 files); `make tb` 2 passed; targeted `builder` + `tools` + `errors` + `reporting` suites → 1676 passed, 1 pre-existing skip.
-
----
-
-## Phase 4 — Temporal-adjacent stdlib removal (low risk)
-
-- [x] **4.1** `RegistrationFailure` — `pipelex/temporal/tprl/namespace_check.py` (~line 50) → **NamedTuple**. Fields `namespace: str`, `missing: tuple[str, ...]`, `rpc_error_message: str`. Off-wire admin plumbing — produced by `ensure_required_search_attributes_registered` at worker boot/setup, consumed only by `pipelex/cli/commands/setup_temporal_namespace_cmd.py` to format a runbook; never an `@activity.defn` return nor a wire field. **Implementer note:** a NamedTuple is also a `tuple`, so all consumers must keep discriminating the `RegistrationFailure | tuple[str, ...]` return via `isinstance(x, RegistrationFailure)` (CLI already does, ~line 148), never `isinstance(x, tuple)`.
- - Result: `@dataclass(frozen=True)` → **frozen `BaseModel`** (`model_config = ConfigDict(frozen=True)`). **DEVIATION from the plan's NamedTuple target — deliberately chose BaseModel over NamedTuple here** (decided on review, 2026-05-29): the return type is a union `RegistrationFailure | tuple[str, ...]`, and a NamedTuple IS a tuple, so a NamedTuple form makes BOTH arms tuples and leans entirely on every caller using `isinstance(x, RegistrationFailure)`. A `BaseModel` is **not** a tuple, so it stays cleanly type-distinct from the `tuple[str, ...]` success arm — strictly safer for this union. Its fields (`str`, `tuple[str, ...]`, `str`) are all pydantic-native, so NO `arbitrary_types_allowed` is needed. (A frozen *pydantic dataclass* would also have worked and been an even smaller diff — noted as the minimal-churn alternative.) Verified all consumers: 3 discrimination sites use `isinstance(..., RegistrationFailure)` (`setup_temporal_namespace_cmd.py:148`, `test_ensure_search_attributes_registered.py:117/140`, `integration/.../conftest.py:156`); none uses `isinstance(x, tuple)`; field access is `.namespace`/`.missing`/`.rpc_error_message`; construction is kwargs. Temporal unit+integration + setup-namespace CLI tests green (452 passed, 4 pre-existing xpass).
-
-**Verify:** `make agent-check`; `make tb`; `.venv/bin/pytest tests/integration/pipelex/temporal/`.
- - Result: `make agent-check` clean; `make tb` 2 passed; `tests/unit/pipelex/temporal/` + `tests/integration/pipelex/temporal/` → 445 passed, 4 xpassed (the documented pre-existing xdist class-registration race flakes — passes in isolation; no regressions). No stray temporal processes after the run.
-
-> 🛑 **HARD STOP 2 — All mechanical off-wire work done.** NamedTuple upgrades + four off-wire stdlib removals + the temporal-adjacent one have landed; the only remaining conversion is the reviewed `DispatchOptions`, which needs a without-temporal-extra import check that's cleanest in a fresh session. Run the context-save protocol and END THE SESSION.
-
----
-
-## Phase 5 — The reviewed item: `DispatchOptions` (needs human-review gate)
-
-`DispatchOptions` — `pipelex/temporal/config_temporal.py` (~line 366) → **frozen `BaseModel`** with `model_config = ConfigDict(arbitrary_types_allowed=True)`. Off-wire (built only inside `WorkerConfig.resolve_dispatch`, immediately consumed by splatting `to_execute_kwargs()` into `workflow.execute_activity(...)`; never a workflow/activity arg/return, never a wire field). Holds a live `temporalio` `RetryPolicy` (non-JSON, `TYPE_CHECKING` forward ref) + the `to_execute_kwargs()` behavior method → `arbitrary_types_allowed` required, `frozen` matches the build-once-read-only lifecycle. NamedTuple/pydantic dataclass are wrong (the method + arbitrary SDK field; and a pydantic dataclass hits the SAME class-def-time annotation-resolution risk as BaseModel — Phase 0 does not change this).
-
-**Load-bearing invariant (the gate):** the module must import without `temporalio` installed. `temporalio` is imported only under `TYPE_CHECKING` and lazily inside `make_retry_policy`; `retry_policy: "RetryPolicy"` is a forward ref. A pydantic model builds a validator at class-def time and may try to resolve that annotation, risking pulling `temporalio` into the plain import path.
-
-- [x] **5.1** GATE: verify the `temporalio`-not-installed import path — run `make tb` on an environment WITHOUT the temporal extra and confirm import + config-load succeed. Keep `RetryPolicy` under `TYPE_CHECKING` (or typed `Any`).
- - Result: **this worktree HAS the temporal extra**, so `make tb` here can't exercise the no-extra path (the prior session flagged exactly this). Used a **subprocess import-block** instead (a `sys.meta_path` finder that raises `ModuleNotFoundError` for `temporalio*`), then imported `config_temporal` and built `DispatchOptions` + the `Temporal` config submodels in that blocked interpreter — all green. **Key finding (the gate's real risk, now characterized):** a bare forward ref `retry_policy: "RetryPolicy"` (TYPE_CHECKING-only, no runtime binding) IMPORTS fine (pydantic *defers* the unresolved schema) but raises `PydanticUserError` the moment a `DispatchOptions` is **constructed** without the extra. Mitigation: an `else: RetryPolicy = Any` branch on the `TYPE_CHECKING` guard binds the annotation to `Any` at runtime, so the field needs no resolution and no `temporalio` — type-checkers still see the real `RetryPolicy`. Locked with a NEW permanent regression test `tests/unit/pipelex/temporal/test_dispatch_options_no_temporalio.py` (subprocess, temporalio blocked) — complements the existing AST scan in `test_config_temporal_optional_dep.py`, which would NOT catch a revert to a bare forward ref (it adds no import statement).
-- [x] **5.2** Convert `DispatchOptions` to frozen `BaseModel(arbitrary_types_allowed=True)`, preserving `to_execute_kwargs()`. If the import-clean path proves infeasible, FALL BACK to a NamedTuple with `timedelta | None` fields + the `to_execute_kwargs` method (still off-wire-legal) — record the decision in the Session log.
- - Result: converted to a **frozen pydantic dataclass** (`@pydantic.dataclasses.dataclass(frozen=True)`), `to_execute_kwargs()` + field order unchanged, dropped `from dataclasses import dataclass` → `from pydantic.dataclasses import dataclass`. **DEVIATION 1 — `arbitrary_types_allowed` NOT needed (plan wording superseded):** with the `else: RetryPolicy = Any` binding the `retry_policy` field resolves to `Any` at runtime (no `isinstance`/arbitrary-type handling), so `frozen=True` alone suffices — `arbitrary_types_allowed=True` would be dead config. **DEVIATION 2 — final form is a frozen pydantic dataclass, NOT the plan's frozen `BaseModel`:** this went through TWO gate passes. (a) I first recommended pydantic dataclass; at the review gate the **user initially chose frozen `BaseModel`**, which I implemented (agent-check + full suite green on that form). (b) The user then observed the deciding point: **a frozen `BaseModel` needs the SAME `else: RetryPolicy = Any` binding** (both forms build a validator at class-def time), so BaseModel buys nothing on the import axis — and once the `else:` cost is unavoidable, the lower-churn pydantic dataclass (keep the decorator, no base-class change, no `model_config`) is the net win, and it fits the form guide's off-wire/never-serialized criterion exactly. **Switched to frozen pydantic dataclass.** Empirically reconfirmed import + construct under blocked `temporalio` (`is_pydantic_dataclass(DispatchOptions) == True`; frozen enforced via `FrozenInstanceError`). No NamedTuple fallback — the import-clean path is fully feasible. Behavior preserved: `test_resolve_dispatch.py` still builds real `RetryPolicy` objects and reads `.non_retryable_error_types` off them (14 targeted tests green incl. the new no-temporalio + AST optional-dep tests).
-
-**Verify:** `make agent-check`; `make tb`; `.venv/bin/pytest tests/integration/pipelex/temporal/`.
-
----
-
-## Phase 6 — Final gate
-
-(Perf-diff steps removed — the harness was dropped in Phase 1; the `DispatchOptions` form decision rests on reasoning, not measurement.)
-
-- [x] **6.1** Final gate: **no stdlib `@dataclass` decorator** — `grep -rn "from dataclasses import" pipelex/ | grep -w dataclass` returns nothing (currently flags only `config_temporal.py`, cleared by Phase 5). **NOTE:** plain `from dataclasses import field` is ALLOWED and expected — the pydantic dataclasses (`error_pages_generator.py`, `jinja2_required_variables.py`) use `dataclasses.field(default_factory=...)` for their defaults; that helper is not a stdlib `@dataclass`, so do NOT grep for the bare `"from dataclasses import"` string (it false-positives on `field`). Then: full `make agent-check` · full `.venv/bin/pytest tests/integration/pipelex/temporal/` · `make agent-test`.
- - Result: `grep -rn "from dataclasses import" pipelex/ | grep -w dataclass` → **NONE** (HARD RULE 1 satisfied). Only `from dataclasses import field` remains (in `jinja2_required_variables.py` + `error_pages_generator.py`, the Phase 3 pydantic dataclasses) — allowed. `make agent-check` clean (ruff + plxt pass, **pyright 0/0**, **mypy 1930 files Success**) · `make tb` 2 passed · `tests/unit/pipelex/temporal/` + `tests/integration/pipelex/temporal/` → **419 passed, 4 xpassed** (the documented pre-existing pytest-xdist class-registration race flakes; pass in isolation), no stray temporal processes · **`make agent-test` full suite green (exit 0)**.
-- [x] **6.2** Record the release-time follow-up (still pending): publish new kajson to PyPI + bump the `kajson==` pin in `pipelex/pyproject.toml`.
- - Result: **recorded, still pending (not dev-blocking).** kajson is bumped to `0.6.0` on its `feature/Support-more-types` branch and consumed editable from `../kajson` (live source serves the venv; installed metadata stays `0.5.0`, so the pipelex `kajson==0.5.0` pin holds). Release gate = publish kajson `0.6.0` to PyPI **then** bump the `kajson==` pin in `pipelex/pyproject.toml` to match, before pipelex ships a release that depends on the new pydantic-dataclass wire support. **Do NOT run `uv lock`/`uv sync` in this worktree until that pin bump** — the editable `0.6.0` would conflict with the `==0.5.0` pin.
-
-> 🛑 **HARD STOP 3 — Done.** Converter + kajson generalized (wire rule now BaseModel-or-pydantic-dataclass), all stdlib dataclasses removed, NamedTuple upgrades landed, temporal suite green, denylist types never converted away from BaseModel. Run the context-save protocol; final Session log entry records the Phase 0 test results, the `DispatchOptions` import-invariant outcome, and the pending release-gate.
-
----
-
-## Leave-as-is (do NOT convert) — confirmed correct already
-
-- `_ThinkingParams` — `pipelex/plugins/anthropic/anthropic_llm_worker.py` — a legitimate pydantic dataclass; off-wire, built+consumed within a single `_gen_text` call. Right tool already. (No longer the *only* pydantic dataclass — `ErrorPagesReport` (3.2), `VariableReference` (3.4), and `DispatchOptions` (5.2) joined it.)
-- `ResultFile` (`pipelex/pipe_run/delivery_executor.py`), `SupportCheck` (`pipelex/cogt/img_gen/img_gen_param_support.py`), `StoredData` (`pipelex/tools/storage/storage_provider_abstract.py`), `PipeJobComponents` (`pipelex/pipe_run/pipe_job_factory.py`) — existing off-wire NamedTuples, all correct. (`PipeJobComponents` is a local unpack container for building `PipeJob`; anything embedded INTO `PipeJob` must still be wire-legal.)
-- `iter_model_fields` (`pipelex/tools/misc/model_utils.py`, `pipelex/tools/typing/field_helpers.py`) and `items` (`pipelex/tools/misc/func_registry.py`) — keep as plain `Iterator[Tuple[...]]` (`dict.items()` convention). Best follow-up (separate refactor) is consolidating the two duplicate `iter_model_fields`, not changing their data form.
-- `generate_from_structure_blueprint` (`pipelex/core/concepts/structure_generation/generator.py` ~line 78) — `(class_code, generated_class)`; one element is a live `type`. Firmly off-wire (a `type` can't round-trip the converter). NamedTuple would be harmless polish but optional — leave unless doing a broader codegen cleanup.
-
-## Rejected — stale candidates that do NOT exist (do not re-propose)
-
-Verified absent by full-tree grep + directory listing. Listed so a future session doesn't re-derive them: `pipelex/cli/run_helpers.py` (`execute_method_and_output`, `_resolve_inputs_and_memory`); `pipelex/cli/ui_helpers.py` (`prompt_for_methods_and_output`); `pipelex/cli/blueprint_writer.py` (the four `_write_*_stub_file`); the entire `pipelex/pipe_operators/ocr/` path; `pipe_func._resolve_content_generator_and_func_name`; `pipe_img_gen_factory._resolve_blueprint_and_factory`; `pipe_llm_blueprint._split_prompt_template`; `pipe_llm_factory._resolve_prompt_template_and_target`; `toml_utils.load_toml_from_path_and_get_content`; `template_provider_abstract._provide_template_text_and_source`; `file_utils._split_filepath_into_components(_with_extension)`; `hub.get_pipelex_hub_and_pipe_router`; `sub_pipe._resolve_condition_expression`; `library_manager.get_library_paths`; `concept_native.NativeConceptClassNamePair`; `concept_factory._parse_concept_string`; `stuff_factory.make_from_str` (returns a single `Stuff`, misdescribed); the removed `pipelex/cocktail/` directory (`_detect_action_type_and_agent`, `_parse_command_line`). The nearest real shape to the gone `blueprint_writer` is `structures_cmd._generate_structures_for_inline` returning `list[tuple[str, str]]` — a weak list-element case, separately scoped; do not fold the non-existent functions into it.
-
----
-
-## Session log (newest first)
-
-Append one entry per session, especially at every hard stop. Template:
-
-```
-### YYYY-MM-DD — <phase / what this session covered>
-- Landed: <checkboxes flipped + one-line results>
-- Decisions: <any choice taken, with reason>
-- Open questions: <anything unresolved for the next session>
-- Code state: <clean & committed? mid-edit? which files dirty?>
-- NEXT ACTION: <the single exact thing the next session should do first>
-```
-
-### 2026-05-29 — Phase 5 (`DispatchOptions`) + Phase 6 final gate complete — 🛑 HARD STOP 3 reached (refactor DONE)
-- Landed: **5.1, 5.2, 6.1, 6.2** flipped with per-item results above. HARD RULE 1 fully satisfied — **zero stdlib `@dataclass` decorators remain in `pipelex/`**. Files touched this session:
- - `pipelex/temporal/config_temporal.py` — `DispatchOptions` `@dataclass` → **frozen pydantic dataclass** (`@pydantic.dataclasses.dataclass(frozen=True)`); added `else: RetryPolicy = Any` runtime binding on the `TYPE_CHECKING` guard; swapped `from dataclasses import dataclass` → `from pydantic.dataclasses import dataclass`.
- - `tests/unit/pipelex/temporal/test_dispatch_options_no_temporalio.py` — **NEW** runtime regression test (subprocess with `temporalio` blocked → import + construct `DispatchOptions`).
- - `TODOS.md` — this update.
-- Decisions / deviations:
- - **Form decision: frozen pydantic dataclass, settled over two gate passes.** (a) I recommended a frozen pydantic dataclass (lowest churn from the stdlib `@dataclass`; matches the form guide rewritten last session; the plan's BaseModel-over-pydantic-dataclass reasons don't hold — identical import risk, methods fine on pydantic dataclasses). At the review gate the **user first chose frozen `BaseModel`**, which I implemented and verified (agent-check + full suite green). (b) The user then nailed the deciding point: **a frozen `BaseModel` needs the SAME `else: RetryPolicy = Any` binding**, so it has no import-axis advantage — and with the `else:` cost unavoidable, the lower-churn pydantic dataclass is the net win. **Switched to frozen pydantic dataclass** and re-verified end-to-end. Lesson for the form guide: when an arbitrary-SDK field forces an `else: Any` binding regardless, that cost is NOT a reason to prefer BaseModel — churn + the never-serialized criterion decide, both favoring the pydantic dataclass.
- - **`arbitrary_types_allowed` proved unnecessary** (plan said `BaseModel(arbitrary_types_allowed=True)`). With `else: RetryPolicy = Any`, the `retry_policy` field resolves to `Any` at runtime → no arbitrary-type handling needed; `@dataclass(frozen=True)` alone. Adding `arbitrary_types_allowed` would be dead config, so it was omitted.
- - **The real import invariant, characterized:** a bare forward ref imports (pydantic defers the schema) but raises `PydanticUserError` on *construction* without the extra. `DispatchOptions` is only ever constructed inside `resolve_dispatch` (which already requires `temporalio`), so even a bare ref wouldn't break a real no-extra deployment — but the `else: Any` binding makes import+construct robust regardless, and the new subprocess test locks it.
- - **No fallback to NamedTuple** — the import-clean frozen-BaseModel path is fully feasible (proven by the subprocess gate), so 5.2's fallback clause didn't fire.
- - **Inline-LSP noise reconfirmed:** during editing the inline pyright emitted `temporalio.* could not be resolved` on `config_temporal.py` + a STALE `"dataclass" is not defined` at a pre-edit line number. Authoritative `make agent-check` pyright = **0 errors**; grep confirmed zero `@dataclass`. Trust `make agent-check`, not the inline stream (as the prior sessions noted).
-- Verification (all green): `make agent-check` (ruff+plxt clean, pyright 0/0, mypy 1930 files) · `make tb` 2 passed · temporal unit+integration 419 passed / 4 pre-existing xdist xpass / no stray procs · targeted 14-test slice (new no-temporalio + AST optional-dep + resolve_dispatch) green · **`make agent-test` full suite exit 0**.
-- Open questions / carry-forward: **the deferred release gate (6.2) is the only thing left** — publish kajson `0.6.0` to PyPI + bump the `kajson==` pin in `pipelex/pyproject.toml`; until then do NOT run `uv lock`/`uv sync` in this worktree (editable `0.6.0` vs `==0.5.0` pin conflict). This is a release-time action, not part of the refactor.
-- Code state: **COMMITTED + PUSHED** — commit `326d3232` on `refactor/Dataclasses` (tracks `origin/refactor/Dataclasses`), working tree clean. 3 files: `pipelex/temporal/config_temporal.py`, new `tests/unit/pipelex/temporal/test_dispatch_options_no_temporalio.py`, + this `TODOS.md`. `uv.lock` untouched. A post-implementation code-review pass (self + independent reviewer) fixed two doc-accuracy issues before the commit: the new test's stale "frozen Pydantic `BaseModel`" docstring → "frozen Pydantic dataclass", and trimmed the `DispatchOptions` docstring's BaseModel-vs-dataclass rationale (it lives here in the ledger, not in code). (This `TODOS.md` cold-start update lands as a small follow-up commit after `326d3232`.)
-- NEXT ACTION: HARD STOP 3 — the data-class refactor is **DONE** (converter + kajson generalized, all stdlib dataclasses removed, NamedTuple upgrades + per-site forms landed, full suite green). The only remaining item is the release-time kajson PyPI publish + pin bump (6.2), to be done when pipelex cuts a release depending on the new wire support — not a dev task. END THE SESSION.
-
-### 2026-05-29 — Phases 1–4 complete (NamedTuple upgrades + off-wire stdlib removals; perf harness built then dropped) — 🛑 HARD STOP 2 reached
-- **POST-REVIEW ADJUSTMENTS (same session, after the user reviewed the work):** (1) **Perf harness DROPPED** — `tests/perf/` deleted entirely. It measured nothing realistic (synthetic stand-ins; the wire-anchor never used the real kajson converter path; costs negligible vs network-bound activities; nothing on a hot path). Phase 1 & Phase 6's perf-diff are struck; the `DispatchOptions` form decision now rests on reasoning. (2) **4.1 `RegistrationFailure` switched NamedTuple → frozen `BaseModel`** — a NamedTuple IS a tuple, which collides with the `tuple[str, ...]` success arm of its union return; a BaseModel stays type-distinct. (3) **2nd review pass — premise update + 3.2/3.4 → pydantic dataclass.** The user clarified the premise: the goal is the *right per-site shape*, and a **pydantic dataclass** (wire-legal since Phase 0) is a first-class off-wire option, often the lowest-churn one. Rewrote the top-of-file form-selection guide accordingly, then converted **3.2 `ErrorPagesReport` → frozen pydantic dataclass** and **3.4 `VariableReference` → non-frozen pydantic dataclass** (both near-zero-diff: keep `field(default_factory=...)` + properties, just swap the decorator import). Kept 3.1 NamedTuple (Protocol field), 3.3 BaseModel (uniform builder layer), 4.1 BaseModel (type-distinct from tuple). agent-check clean (pyright 0/0, mypy 1929); errors+jinja2+templating 318 passed; temporal + setup-namespace 452 passed/4 pre-existing xpass.
-- Landed: **2.1, 2.2, 3.1, 3.2, 3.3, 3.4, 4.1** flipped with per-item results above. **1.1/1.2 built-then-dropped** (see above). **2.3 and 2.4 skipped — target code no longer exists in the current tree** (see deviations). Files touched (final state):
- - **Phase 2 (NamedTuple):** `pipelex/core/concepts/concept_factory.py` (+`StructureNameAndRefine`), `pipelex/core/qualified_ref.py` (+`CrossPackageRef`).
- - **Phase 3 (off-wire stdlib removals):** `pipelex/reporting/reporting_manager.py` (`_EventLogContext`→NamedTuple), `pipelex/errors/error_pages_generator.py` (`ErrorPagesReport`→frozen BaseModel), `pipelex/builder/runner_code.py` (`CustomClassInfo`→frozen BaseModel), `pipelex/tools/jinja2/jinja2_required_variables.py` (`VariableReference`→mutable BaseModel).
- - **Phase 4 (temporal-adjacent):** `pipelex/temporal/tprl/namespace_check.py` (`RegistrationFailure`→**frozen BaseModel**, post-review).
- - **Final per-site forms:** 3.1 `_EventLogContext`→NamedTuple · 3.2 `ErrorPagesReport`→**frozen pydantic dataclass** · 3.3 `CustomClassInfo`→frozen BaseModel · 3.4 `VariableReference`→**pydantic dataclass** · 4.1 `RegistrationFailure`→frozen BaseModel · 2.1/2.2→NamedTuple.
-- Decisions / deviations:
- - **2.3 / 2.4 do not exist (the audit was stale — taken against the sibling `refactor/Paths` worktree).** `runtime_manager.py` is gone; runtime mode is now property-based in `pipelex/system/runtime.py`. `config_manager.py` is now `pipelex/system/configuration/config_loader.py` and its `find_project_root() -> Path | None` already dropped the `found_root_marker` bool. Both grep-confirmed absent — nothing to convert, so both checkboxes are marked done-by-absence (struck through inline).
- - **3.2 `ErrorPagesReport` — plan rationale was stale; final form is frozen pydantic dataclass.** Plan said "single full-kwargs construction, no in-place `.append`"; actually it's built empty and `.append`-ed in place. `frozen=True` blocks attribute *reassignment*, not list mutation, under stdlib-dataclass / pydantic-dataclass / BaseModel alike — so all three are behavior-equivalent for the append pattern. Final choice (2nd review pass): frozen **pydantic dataclass** — lowest churn (kept `field(default_factory=list[Path])`) and no model-API need.
- - **4.1 `RegistrationFailure` implementer-note verified, not assumed:** re-grepped all consumers; every discrimination is `isinstance(x, RegistrationFailure)`, none is `isinstance(x, tuple)`; success path returns plain tuples (never NamedTuple-subclass instances) so discrimination stays exact.
- - **Only ONE stdlib dataclass remains in `pipelex/`:** `pipelex/temporal/config_temporal.py` (`DispatchOptions`, Phase 5) — grep-confirmed. HARD RULE 1 is one conversion away from satisfied.
- - **Inline LSP noise (informational):** throughout, the editor's inline pyright kept emitting `temporalio.*` "could not be resolved" / "type unknown" diagnostics on temporal files I touched (and the Phase 0 files). That inline checker lacks the temporal extra; the authoritative `make agent-check` pyright resolves `temporalio` and reports **0 errors**. One round of jinja2 diagnostics was also stale (referenced pre-edit line numbers) — verified the file by re-reading; conversion was correct. Trust `make agent-check`, not the inline stream.
-- Verification (all green): `make agent-check` clean (ruff+plxt, pyright 0/0, mypy 1932 files) · `make tb` 2 passed · core+pipes 1323 passed/1 xfailed (pre-existing) · temporal unit+integration 445 passed/4 xpassed (pre-existing xdist flakes, no stray procs) · builder+tools+errors+reporting 1676 passed/1 pre-existing skip.
-- Open questions / carry-forward: (1) **deferred release gate still pending** — publish new kajson `0.6.0` to PyPI + bump `kajson==` pin in `pipelex/pyproject.toml`; do NOT run `uv lock`/`uv sync` in this worktree until then (editable `0.6.0` vs `==0.5.0` pin would conflict). (2) Phase 5 gate 5.1 wants `make tb` on an env WITHOUT the temporal extra — but THIS worktree HAS temporalio installed, so the next session must arrange a no-temporal-extra import check (separate venv, or a targeted import-isolation test) rather than assuming the local env exercises that path.
-- Code state: **COMMITTED + PUSHED** — commit `72e1800f` on `refactor/Dataclasses` (tracks `origin/refactor/Dataclasses`), working tree clean. 8 files: `pipelex/core/concepts/concept_factory.py`, `pipelex/core/qualified_ref.py`, `pipelex/reporting/reporting_manager.py`, `pipelex/errors/error_pages_generator.py`, `pipelex/builder/runner_code.py`, `pipelex/tools/jinja2/jinja2_required_variables.py`, `pipelex/temporal/tprl/namespace_check.py`, + this `TODOS.md`. No new files (the `tests/perf/` harness was created then deleted in the same session). `uv.lock` untouched. (This `TODOS.md` cold-start update lands as a small follow-up commit after `72e1800f`.)
-- NEXT ACTION: HARD STOP 2 — END THE SESSION. A fresh session starts **Phase 5** — convert `DispatchOptions` in `pipelex/temporal/config_temporal.py` to frozen `BaseModel(arbitrary_types_allowed=True)`. **Do gate 5.1 FIRST:** confirm the module still imports without the `temporalio` extra (RetryPolicy stays under `TYPE_CHECKING`/typed `Any`); this worktree has temporalio installed, so arrange a no-extra import check. If the import-clean path proves infeasible, fall back to the NamedTuple form (5.2) and record it.
-
-### 2026-05-29 — Phase 0 complete (converter + kajson generalized) — 🛑 HARD STOP 1 reached
-- Landed: Pre-flight (both boxes) + **0.1–0.9** all flipped with per-item results above. Two-repo change:
- - **kajson** (`../kajson`, branch `feature/Support-more-types`): `json_decoder.py` gained an explicit `is_pydantic_dataclass` decode branch (validates via the dataclass, raises `KajsonDecoderError` loudly instead of silently returning a raw dict); new `tests/unit/test_pydantic_dataclass.py`; version `0.5.0`→`0.6.0` + CHANGELOG entry.
- - **pipelex** (`_data` worktree): `pipelex/temporal/temporal_data_converter.py` widened — `_is_kajson_wire_value` (to_payload, BaseModel-short-circuit first) and `_is_kajson_type` (from_payload scalar/Optional/list) now also accept pydantic dataclasses; BaseModel path byte-identical. New tests: `data_converter/test_data_conv_dataclass.py` (direct converter + byte-identical regression guard) and `test_wf_dataclass_roundtrip.py` (in-process-server round-trip).
-- Decisions / deviations:
- - **kajson test isolation (fixed at root after code review):** `test_json_encoder` / `test_json_decoder` autouse fixtures used to `clear_*coders()` on teardown without restoring, wiping kajson's import-time default codecs process-wide. Now they snapshot the registry and restore it on teardown. An initial band-aid (re-registering `timedelta` in the new dataclass test) was removed.
- - **pyright-strict refactor:** replacing the original inline `isinstance` narrowing with non-narrowing bool predicates surfaced `reportUnknownArgumentType` errors (`type(Any)` → `type[Unknown]`). Resolved cleanly: value predicate param typed `object`, list-head probe extracted to an `object`-typed helper, call sites keep `value` explicitly `Any`, and one `cast("Any", type_hint)` collapses the post-`isinstance` union. No `# pyright: ignore` added in the converter.
- - **Version/pin tension (IMPORTANT for next session):** kajson is bumped to `0.6.0` but pipelex still pins `kajson==0.5.0` (editable source serves live code; installed metadata stays `0.5.0`, so the pin holds and the `.venv` works). Running `uv lock`/`uv sync` here would now FAIL (editable `0.6.0` vs `==0.5.0`). The pin bump + PyPI publish remain the deferred release gate.
-- Verification (all green): kajson suite 257 passed / 1 skipped + kajson `make agent-check` clean · pipelex `make agent-check` (pyright 0/0, mypy 1929 files) · `make tb` 2 passed · converter+integration round-trips 11 passed · full temporal integration (non-inference) 136 passed, 4 pre-existing xdist-race xpass, no regressions, no stray temporal processes.
-- Open questions: none blocking Phase 1. The only live item is the deferred kajson PyPI publish + `kajson==` pin bump (release gate, not dev-blocking).
-- Code state: **uncommitted** (per instruction — not committing without explicit ask). Dirty: kajson = `CHANGELOG.md`, `kajson/json_decoder.py`, `pyproject.toml`, new `tests/unit/test_pydantic_dataclass.py`, plus the code-review root-cause fix in `tests/unit/test_json_encoder.py` + `tests/unit/test_json_decoder.py`; pipelex `_data` = `pipelex/temporal/temporal_data_converter.py`, new `tests/integration/pipelex/temporal/data_converter/test_data_conv_dataclass.py`, new `tests/integration/pipelex/temporal/test_wf_dataclass_roundtrip.py`, and this `TODOS.md`. Tree otherwise clean; `uv.lock` untouched.
-- NEXT ACTION: HARD STOP 1 — END THE SESSION. A fresh session starts Phase 1 (perf baseline harness at `tests/perf/test_dataclass_forms_bench.py`, task 1.1), which does not depend on Phase 0 internals. Before any `uv` re-lock, remember the version/pin tension above.
-
-### 2026-05-29 — Ledger created (planning only, no code changes)
-- Landed: nothing implemented yet. This ledger was created from the former `wip/data-class-best-practices-plan.md` (removed). The previous root ledger (`feature/API-readiness-4`, all complete) was archived to `wip/error-handling/archive-todos-api-readiness-4.md`.
-- Decisions: (1) per-site type strategy for the six stdlib dataclasses — NOT a uniform pydantic-dataclass conversion. (2) Generalize the converter + kajson FIRST as Phase 0, scoped to pydantic dataclasses only. (3) kajson is consumed editable from `../kajson` in this worktree, so no PyPI publish needed for dev; publish + pin bump is a release-time gate.
-- Open questions: none blocking. The `DispatchOptions` import-without-temporalio invariant (Phase 5) is the one real unknown — gated by 5.1.
-- Code state: clean working tree except this ledger + the archived file move. No production code touched.
-- NEXT ACTION: start Phase 0 — Pre-flight boundary freeze, then task 0.1 (kajson `is_pydantic_dataclass` decode branch in `../kajson/kajson/json_decoder.py`), TDD: write the kajson round-trip tests (0.2) first.
+Result: `wip/` is active-only and link-clean; finished history and internal plans live in the private workspace; the public docs carry no cross-repo references.
diff --git a/wip/02-master-plan.md b/wip/02-master-plan.md
deleted file mode 100644
index 41672d5ef..000000000
--- a/wip/02-master-plan.md
+++ /dev/null
@@ -1,157 +0,0 @@
-# Master Plan v3 — Distributed Workers
-
-> **Status**: Live plan — drives the next round of distributed-execution work.
-> **Date**: 2026-05-04
-> **Predecessors**: [archive/00-master-plan.md](archive/00-master-plan.md) (Phases 0–5, shipped) · [archive/01-master-plan.md](archive/01-master-plan.md) (interim plan, now split into per-topic files).
-
-The big direction now is to actually run **activities on standalone Worker pools** — separate processes from the workflow Worker pool — so we can scale workflow orchestration and inference activity execution independently. Today's tracing / cost-reporting design was built for the single-bundle-per-Worker case and breaks the moment activities move off-process. That has to be fixed before anything else.
-
----
-
-## Priority order
-
-| # | Item | Status | Owner file |
-|---|---|---|---|
-| **P0** | **Tracing & cost reporting across separate-process workers** | Done — shipped on `fix/Tracing-across-workers`; see [tracing-cost-reporting-as-built.md](tracing-cost-reporting-as-built.md) (T1 marked fixed) | this file (problem statement) |
-| **P0.1** | **Dry-run through activity dispatch (testing affordance)** | Not started — surfaced during P0 Phase 6 validation | this file (problem statement) |
-| **P0.2** | **Deferred follow-ons from P0** | Not started — surfaced during P0 eng review + PR #860 SWE-agent review | this file (problem statement) |
-| **P1** | **Cross-worker cost report assembly wiring** | Not started — depends on P0 design | this file (problem statement) |
-| **P2** | Phase 6a — Local cross-package dependencies in crate | Not started | [phase6a-local-cross-package-deps.md](phase6a-local-cross-package-deps.md) |
-| **P3** | Phase 6b — Remote dependencies from GitHub | Not started — needs P2 | [phase6b-remote-deps-from-github.md](phase6b-remote-deps-from-github.md) |
-
-What's already shipped on this front: see [tracing-cost-reporting-as-built.md](tracing-cost-reporting-as-built.md). It also enumerates the open issues (T1, T2, T3) that motivate P0 and P1.
-
-Sibling tracks (separate branches, not in this plan): worker error-handling Phases 4–7 (`error-handling-phase-{4,5,6,7}-*.md`), instructor-unwrap port (`instructor-unwrap-other-workers.md`).
-
----
-
-## P0 — Tracing & cost reporting across separate-process workers — DONE
-
-Shipped on `fix/Tracing-across-workers`. The full implementation history (six phases, eng-review notes, decisions, test inventory, atomic-commit list) is preserved in the branch's git log and summarized in [tracing-cost-reporting-as-built.md](tracing-cost-reporting-as-built.md). The architectural notes below are kept for context. Follow-ons that were explicitly deferred during implementation are tracked under §P0.2.
-
-### Why this is top priority
-
-The whole point of the distributed-execution work is to allow **activities on standalone Worker pools** (separate processes from the workflow Worker pool). The current tracing implementation cannot serve that topology — it relies on the activity sharing the workflow's process so the singleton `ReportingManager` already has `set_event_log` configured. Until P0 is solved, splitting activities off is a regression on observability and cost reporting, not a feature.
-
-### Problems with the current implementation
-
-(All concretely enumerated in [tracing-cost-reporting-as-built.md](tracing-cost-reporting-as-built.md). Summarized here so the priority is legible.)
-
-1. **Standalone activity workers lose usage events.** When an activity runs on a process that never executed `WfPipeRouter.run()`, that process's `ReportingManager._event_log_contexts` is empty for the workflow's `lookup_key`. `_emit_usage_event` returns silently; usage data is dropped. The `_get_registry` TODO at `reporting_manager.py:111-117` ("Auto-create registry for unknown pipeline IDs ... TODO: replace with proper distributed reporting system") confirms this is a known gap.
-2. **`BufferingEventLog` + `act_flush_trace_events` is workflow-scoped.** Both pieces are tied to the workflow lifecycle (buffer in workflow context, flush after pipe execution). They cannot serve a standalone activity Worker that has no enclosing workflow process.
-3. **`set_event_log` lives on a process-singleton `ReportingManager`.** The per-context `_event_log_contexts` dict pattern relies on the activity emitting from the same process that configured the event log. The moment activity execution moves off-process, the activity has no way to discover its event log without something flowing in via request data (`JobMetadata` / a new `TracingContext`) instead of via a process-local dict.
-
-### Design discussion (deferred)
-
-We're not designing the fix yet — that comes when we pick up P0. The two natural starting points are (a) the original Phase 4.5 Step 6 `TracingActivityInboundInterceptor` design (now in `archive/00-master-plan.md` and `archive/01-master-plan.md`), and (b) plumbing tracing config + workflow id through `JobMetadata` so each activity can construct its own event log directly. Either way the activity needs request-scoped tracing data, not process-scoped state.
-
-### Acceptance criteria — all met
-
-- [x] Activities deployed on standalone Worker pools (separate process from workflow Workers) emit `UsageReportEvent`s that land in the same backend partition as the rest of the run.
-- [x] No reliance on `WfPipeRouter` having executed in the activity's process.
-- [x] No silent drops — if tracing is enabled, an activity that fails to emit raises or logs explicitly.
-- [x] Direct mode and the current single-bundle Worker mode keep working unchanged.
-- [x] Tests covering: standalone activity Worker, mixed worker pool, tracing disabled, NDJSON backend, DynamoDB backend (unit-level via stubbed boto3; full DDB e2e gated on `pytest -m dynamodb`).
-
----
-
-## P0.1 — Dry-run through activity dispatch (testing affordance)
-
-Today, `--dry-run` instantiates `ContentGeneratorDry()` directly inside the workflow body (`pipe_llm.py:515`, and similar sites in `pipe_extract.py`, `pipe_compose.py`, `pipe_img_gen.py`). The activity (`act_llm_gen_text` etc.) is never dispatched. As a result, the cross-worker `UsageReportEvent` emission path that P0 ships cannot be exercised in dry-run mode against router+runner workers — the runner-side fallback only fires when the activity actually dispatches across processes.
-
-This was discovered while validating P0 Phase 6.1: a vanilla `pipelex run bundle --temporal --dry-run --mock-inputs` against a 2-worker (router+runner) topology produces only `writer_id="primary"` events; no `wf_*__w_act_*.ndjson` files appear. The Phase 4 integration test (`TestSplitWorkerUsageEmission`) works around this by substituting `act_llm_gen_text` with a wrapper that synthesizes an `LLMJob` server-side, but that's test-internal scaffolding, not a general-purpose mode.
-
-### What's needed
-
-A run mode that combines "no real LLM call" with "still go through the activity dispatch path", so a `pipelex run bundle` against router+runner workers exercises the same code path as live mode, just with mocked inference inside the activity. Concretely:
-
-- `act_llm_gen_text` is dispatched to the runner as in live mode.
-- Inside the activity, the inference is mocked (use `ContentGeneratorDry` *inside* the activity body, not in place of dispatching it).
-- All cross-process surfaces — `_event_log_contexts` lookup miss, runner-side fallback, `writer_id="act_*"` emission — fire normally.
-
-### Why this matters beyond P0
-
-Same affordance unlocks dry-run e2e for any future cross-process work (P1 cost report assembly, distributed graph assembly, payload codec stress testing, etc.) without needing real LLM spend.
-
-### Acceptance criteria (sketch)
-
-- [ ] A `--mock-inference` (or similar) flag — distinct from `--dry-run` — that keeps activity dispatch but mocks inside the activity. Or: redefine `--dry-run` to mean "dispatch activities, mock inside" and rename the current behavior.
-- [ ] `temporal-e2e-validate` Tier 8 can run in this mode and surface `wf_*__w_act_*.ndjson` files deterministically.
-- [ ] Equivalent mocking sites in `pipe_extract.py`, `pipe_compose.py`, `pipe_img_gen.py` updated.
-
----
-
-## P0.2 — Deferred follow-ons from P0
-
-Items surfaced during the P0 eng review and the post-merge SWE-agent review of PR #860. Each is independently scoped and not blocking for P0.1 / P1 / P2 / P3. Pick up individually as priorities and signals dictate.
-
-### From eng review (logged at the time of P0 implementation)
-
-- [ ] **`tracing_config.strict_mode: bool`** — opt-in flag that raises (instead of WARNING + drop) when the runner-side emit path fails. Useful for compliance/audit deployments where missing trace data is a hard error. (Eng review R6.)
-- [ ] **DynamoDB `BatchWriteItem` for runner emission** — current path does one `PutItem` per usage event. At high-concurrency runners that's one boto3 call per emit; `BatchWriteItem` batches up to 25. Defer until actual throughput shows it matters. (Eng review R3.)
-- [ ] **NDJSON shared-filesystem invariant enforcement** — the NDJSON backend assumes `traces_dir` is visible to all writer processes (router pool + runner pool + `act_flush_trace_events`). For multi-host deployments this needs NFS/EFS or equivalent. Follow-up: a startup check that warns if `traces_dir` looks like a local-only path on a multi-worker deployment. (Eng review TODO-2.)
-
-### From PR #860 SWE-agent review (post-merge triage of `fix/Tracing-across-workers`)
-
-- [ ] **Per-thread `writer_id` for activity event log** — the surgical lock fix from PR #860 closes the duplicate-sequence race on `next_sequence()`, but a per-thread writer_id would eliminate the contention entirely and align the design with how Temporal's worker pool already partitions activities. Each thread would emit into its own writer namespace; dedup naturally drops to per-thread, no lock needed in the hot path.
-- [ ] **Project-wide migration of `JobMetadata.started_at` to timezone-aware datetimes** — the PR #860 patch builds the synthetic `now` with the same `tzinfo` as the incoming `started_at`, which removes the immediate `TypeError` crash but doesn't fix the underlying inconsistency: `JobMetadata.started_at` default factory is naive (`datetime.now`) while several callers (e.g. `pipe_abstract.py:428`) construct aware datetimes (`datetime.now(timezone.utc)`). A clean migration would standardize on `datetime.now(timezone.utc)` everywhere, document the tz contract on `JobMetadata`, and let `duration` subtract without defensive tzinfo matching at every site.
-
----
-
-## P1 — Cross-worker cost report assembly wiring
-
-### Why this is second, not first
-
-Even if P0 ships, the events still need to be turned into a cost report. Today the read-back path exists for the **graph** (`assemble_graph_on_output` / `act_assemble_graph` → `GraphSpecAssembler`) but not for **usage**. The pieces all exist on the manager side:
-
-- `UsageAggregator.aggregate(events) → list[AnyTokensUsage]` (`pipelex/tracing/usage_aggregator.py`).
-- `ReportingManager.inject_tokens_usages(pipeline_run_id, tokens_usages)` (`reporting_manager.py:191`) — docstring: *"Used after assembling usage data from distributed trace events, so that generate_report() can produce a complete cost report across all workers."*
-- `ReportingManager.generate_report(pipeline_run_id)` (`reporting_manager.py:247`).
-
-Nothing in the runtime calls these. `generate_report()` has zero runtime callers; only integration tests invoke it. Captured events sit in the backend and never become a cost report.
-
-This is a small piece of plumbing once P0's design is settled — the same place that calls the graph assembler can call the usage aggregator and inject the result into the report delegate before `generate_report` runs.
-
-### Acceptance criteria (sketch)
-
-- [ ] Runtime path: read events for `pipeline_run_id` → `UsageAggregator.aggregate()` → `ReportingManager.inject_tokens_usages()` → `generate_report()`.
-- [ ] Wired in both direct mode (in `pipelex/pipeline/runner.py`) and Temporal mode (alongside or inside the existing graph-assembly hook).
-- [ ] Cross-worker case verified: parent workflow on Worker A, child workflow on Worker B, activity on Worker C — single end-of-run cost report contains usage from all three.
-- [ ] Replace / remove the `_get_registry` TODO at `reporting_manager.py:111-117` since the proper distributed path now exists.
-
----
-
-## P2 — Phase 6a: Local cross-package dependencies in crate
-
-Detailed plan: [phase6a-local-cross-package-deps.md](phase6a-local-cross-package-deps.md).
-
-In one line: ship dependency blueprints inside the `LibraryCrate` so workers don't need the dependency packages on PIPELEXPATH. Prerequisite for P3.
-
----
-
-## P3 — Phase 6b: Remote dependencies from GitHub
-
-Detailed plan: [phase6b-remote-deps-from-github.md](phase6b-remote-deps-from-github.md).
-
-In one line: extend the blueprint collector from P2 with a remote (GitHub) resolver so the crate can carry deps fetched from external addresses, making workers fully stateless.
-
----
-
-## Dependencies between items
-
-```
-P0 (Tracing across separate workers)
- │
- ├─► P0.1 (Dry-run through activity dispatch — testing affordance)
- ├─► P0.2 (Deferred follow-ons — independent, pick up individually)
- │
- ▼
-P1 (Cross-worker cost report assembly)
-
-P2 (Phase 6a — local cross-package deps)
- │
- ▼
-P3 (Phase 6b — remote deps from GitHub)
-```
-
-P0/P0.1/P0.2/P1 and P2/P3 are independent tracks; P0 unlocks P0.1, P0.2, and P1; P2 blocks P3. P0.1 is a parallel testing affordance that improves P0 / P1 / future cross-process work confidence. P0.2 items are independent of each other — pick them up individually as needs and signals dictate.
diff --git a/wip/README.md b/wip/README.md
new file mode 100644
index 000000000..a803d4127
--- /dev/null
+++ b/wip/README.md
@@ -0,0 +1,35 @@
+# `wip/` — Work in Progress
+
+This folder holds the **active** planning, design, and current-state docs for the Pipelex runtime — the things that are started or about to start. Finished plans and design history live in the private workspace (`docs/history/`, `docs/plans/`), not here. If a doc describes how the code got to where it is rather than where it is or is going, it does not belong in `wip/`.
+
+## How this is organized
+
+- **Track folders** group a multi-doc concern. Each has its own `README.md` that maps the track and states what's open. Open the README first.
+- **Standalone docs** are single-topic designs that have no siblings — they live loose at the root with self-describing names (no folder needed).
+- There is **no consolidated cross-cutting backlog** — deferred items and follow-ups live with their feature, in the relevant track or standalone doc's own "open / deferred" section. Follow-ups to features that already shipped live with that feature's record in the private workspace (`docs/history/`, `docs/plans/`), not here.
+
+## Tracks
+
+- **[distributed-execution/](distributed-execution/)** — running MTHDS methods as Temporal workflows across separate worker processes. Its [README](distributed-execution/README.md) is the priority-ordered plan; the folder also holds the tracing/cost-reporting as-built reference, the crate-packaging phases (6a/6b) and crate-first vision, the implemented Temporal IDs/naming design, and the deferred Temporal-exception and schema-reconstruction hardening proposals. **This is the active headline track.**
+- **[error-handling/](error-handling/)** — the current-state reference for error handling across Pipelex, track-organized (metadata model, worker classification, extract/classify/render, retry, CLI delivery, Temporal integration, testing). Mostly landed; its [README](error-handling/README.md) lists what's still open.
+- **[concurrency/](concurrency/)** — direct-mode batching / backpressure design. The retry-jitter quick win shipped; the remaining design work is split into fan-out scheduling, rate limiting, and batch partial-failure docs. Status: design scoping.
+
+## Standalone docs
+
+- **[webhook-signing.md](webhook-signing.md)** — security track: HMAC body-signing for the completion-callback webhook, with a 3-step cross-repo rollout. The last open piece of the error-handling API-readiness companion work. Plan ready, not started.
+- **[runtime-code-fixes.md](runtime-code-fixes.md)** — verified `pipelex/` runtime fixes to pick up.
+- **[structured-logging.md](structured-logging.md)** — kickoff briefing for replacing string-interpolated log context with structured logging + contextvars. Kicked off, not started; sequenced after the error-handling stack merges.
+- **[stuffs-as-nodespec.md](stuffs-as-nodespec.md)** — future graph-model rework to make stuffs first-class `NodeSpec` instances. A starter, not a worked plan.
+- **[blueprint-elaboration-directives.md](blueprint-elaboration-directives.md)** — extending the build-time blueprint-elaboration system: first-class synthetic-pipe handling, a directive plugin registry, and supporting tooling.
+- **[pathlib-refactor.workflow.js](pathlib-refactor.workflow.js)** — a runnable multi-agent workflow that refactors filesystem path handling to `pathlib.Path` across `pipelex/` (intended for the `refactor/Paths` branch). Tooling, not a doc.
+
+## Suggested priorities
+
+A pickup order grounded in each doc's own status — adjust to current signals.
+
+1. **[runtime-code-fixes.md](runtime-code-fixes.md)** — smallest and already verified. The `request_id`-on-delivery-failure fix is a quick win; the cross-worker cost-report assembly wiring is the one genuine functional gap (it is also **P1** of the distributed-execution track).
+2. **[distributed-execution/](distributed-execution/)** — the active headline track. Take P1 (cross-worker cost report assembly) first, then the crate phases P2 (local cross-package deps) → P3 (remote deps).
+3. **[webhook-signing.md](webhook-signing.md)** — security-reviewed plan, ready to execute; closes the last open error-handling-companion item. Cross-repo, so coordinate the rollout.
+4. **error-handling long tail** — the metadata-model followups and the `request_id` correlation on delivery error paths in [error-handling/](error-handling/). Mostly landed; these are the remainder.
+5. **[concurrency/](concurrency/)** — pick up when batch-at-scale becomes a priority. Fan-out scheduling and batch partial-failure are coupled (take together); rate limiting is independent.
+6. **Deferred / larger / future** — [structured-logging.md](structured-logging.md) (after error-handling merges), [pathlib-refactor.workflow.js](pathlib-refactor.workflow.js) (run when ready), [stuffs-as-nodespec.md](stuffs-as-nodespec.md), the deferred Temporal-exception and schema-reconstruction proposals in [distributed-execution/](distributed-execution/), and [blueprint-elaboration-directives.md](blueprint-elaboration-directives.md). Take individually as needs and signals dictate.
diff --git a/wip/api-readiness-2-handoff-drafts.md b/wip/api-readiness-2-handoff-drafts.md
deleted file mode 100644
index 3658fc044..000000000
--- a/wip/api-readiness-2-handoff-drafts.md
+++ /dev/null
@@ -1,76 +0,0 @@
-# API handoff — message drafts for `feature/API-readiness-2`
-
-> The drafts below were written when the execution ledger lived at the repo root as `_for_api/TODOS.md`. That file was archived 2026-05-28 to `_for_api/wip/error-handling/archive-todos-api-readiness-2.md` — translate any `TODOS.md` path reference below to the archived location if reusing these drafts.
-
-Two forms below — pick the one matching the channel. Both point at source docs rather than restating them.
-
----
-
-## Form 1 — human (Slack / email)
-
-**Subject:** `feature/API-readiness-2` ready for review — error-handling finalization + error-class refactor
-
-Hey team — the follow-up branch to PR #931 is ready. It bundles the in-repo finalization of the error-handling overhaul (Phases 0–4 of pipelex `_for_api/TODOS.md`) and a structural refactor of where error classes live in the source tree (Phase 6).
-
-**Things to be aware of on the API side:**
-
-- **STRICT disclosure keying changed.** `ErrorReport.to_dict(STRICT)` / `to_problem_document(STRICT)` now key the `message` passthrough on a per-class `caller_facing_message` flag, not on `error_domain == INPUT`. Only `PipelexInterpreterError` / `ValidateBundleError` are flagged caller-facing today; everything else gets the redacted placeholder. Provider metadata (`provider` / `model` / `provider_metadata`) is now stripped under STRICT unconditionally. Background: `_for_api/wip/error-handling/track-strict-disclosure-input-domain-gap.md`.
-- **`WebhookTarget.payload` rejects reserved keys at construction** — `pipeline_run_id` / `status` / `result_url` / `error`. Loud `ValidationError`, not a silent overwrite at delivery. Background: `_for_api/wip/error-handling/track-webhook-payload-collision.md`.
-- **`request_id` is now end-to-end through Temporal workflow logs.** `WfPipeRun` / `WfPipeRouter` build a per-invocation `WorkflowLog` from `JobMetadata.request_id` at entry; every workflow log record carries it in `extra`. The `webhook.payload["request_id"]` piggyback can be dropped — `request_id` rides natively now.
-- **Error class import paths moved (Phase 6).** Every `PipelexError` subclass now lives in `exceptions.py` or `<topic>_exceptions.py`. `MthdsDecodeError` is **deleted** — fold any `except MthdsDecodeError` into `except PipelexInterpreterError`. Class names are unchanged; only module paths shifted. The Checkpoint 6 entry in `_for_api/TODOS.md` enumerates every move.
-
-**Pending cross-repo work** — **Webhook signing** (Phase 5 / Item F). 3-step rollout per `_for_api/wip/security/webhook-signing.md`: receiver-side dual-format verification ships first (pipelex-api), then pipelex worker switches to body-signing, then drop legacy. Independent of this PR; pick a window when you have bandwidth.
-
-PR: [URL once opened]
-Authoritative tracker: `pipelex/_for_api/TODOS.md`
-Contract doc (the one to read first): `pipelex/_for_api/wip/error-handling/api-companion-revisions.md`
-
-— Louis
-
----
-
-## Form 2 — agent prompt (paste into Claude Code in `pipelex-api/`)
-
-The pipelex branch `feature/API-readiness-2` has landed (PR [URL]). It is the in-repo finalization of the error-handling overhaul (Phases 0–4 of pipelex `_for_api/TODOS.md`) plus a Phase 6 structural refactor of where error classes live. Your job in `pipelex-api/` is to adapt this repo to the new pipelex surface: bump the `pipelex` pin, fix any broken imports, and update any code that relied on the old STRICT-disclosure keying or webhook-payload semantics.
-
-### Read first — in the sibling pipelex repo
-
-The pipelex repo lives side-by-side with `pipelex-api/`. The work happened on a worktree at `../_for_api/` (or look for `feature/API-readiness-2` in `../pipelex/`). Read these in order:
-
-1. `_for_api/wip/error-handling/api-companion-revisions.md` — the **contract** for what pipelex exposes to API consumers. Authoritative. Supersedes `changes-for-api-early-draft.md` (banner at the top of the draft confirms this).
-2. `_for_api/TODOS.md` — phase-by-phase changes. The Session log entries at the bottom are ground truth for what shipped.
-3. `_for_api/wip/error-handling/README.md` — current state of the error-handling tracks.
-4. `_for_api/wip/error-handling/track-strict-disclosure-input-domain-gap.md` — STRICT keying shift.
-5. `_for_api/wip/error-handling/track-webhook-payload-collision.md` — webhook reserved-key validator.
-6. `_for_api/wip/security/webhook-signing.md` — the cross-repo Phase 5 plan (NOT in this PR; separate coordination).
-
-Then `git log main..feature/API-readiness-2 --oneline` in the pipelex worktree to see the commit shape.
-
-### What changed that pipelex-api needs to react to
-
-**1. STRICT disclosure keying.** `to_dict(STRICT)` and `to_problem_document(STRICT)` now key the `message` passthrough on a per-class `caller_facing_message` flag (provenance) rather than `error_domain == INPUT` (inherited classification). Only `PipelexInterpreterError` and `ValidateBundleError` are flagged caller-facing today. For everything else under STRICT: `message` is replaced with `"An internal error occurred."`, `user_action` is dropped, stable identifiers are kept. Provider metadata (`provider` / `model` / `provider_metadata`) is now stripped under STRICT unconditionally. Action: review any path that calls `to_dict(STRICT)` / `to_problem_document(STRICT)`. If it relied on `error_domain == INPUT` to surface caller-facing copy, that reasoning is gone — trust the projected dict.
-
-**2. `WebhookTarget.payload` reserved-key validator.** `pipelex.pipe_run.delivery_assignment.WebhookTarget` now has a `field_validator` on `payload` that rejects the reserved set `{"pipeline_run_id", "status", "result_url", "error"}` at construction time. Any code or test that stuffs these into a static webhook payload now raises `pydantic.ValidationError`. Action: grep for `WebhookTarget(` and `WebhookTarget.model_validate(` and remove any reserved keys from static payloads.
-
-**3. `request_id` is end-to-end now.** `pipeline_run_setup(request_id=...)` populates `JobMetadata.request_id`, which the worker reads at workflow entry to bind a per-invocation `WorkflowLog`. Every workflow log record then carries `request_id` in `extra`. Action: if pipelex-api still uses the legacy `webhook.payload["request_id"]` piggyback (as the original spec mentioned), drop it — `request_id` rides natively now and round-trips through `JobMetadata`. Populate it from your inbound `X-Request-ID` middleware at dispatch time.
-
-**4. Error class import path moves (Phase 6).** Every `PipelexError` subclass now lives in a module named `exceptions.py` (default — one per package directory) or `<topic>_exceptions.py` (for directories hosting multiple separate-concern error modules — matches the existing `pipelex/plugins/*/` convention). The `*_errors.py` synonym is dropped. `pipelex/errors/error_module_registry.py` is deleted entirely. The "Checkpoint 6 (Phase 6 complete)" entry in `_for_api/TODOS.md` enumerates every file moved or created. Class names are unchanged; only module paths shifted. **`MthdsDecodeError` is deleted** — callers should catch `PipelexInterpreterError` instead (already `error_domain=INPUT` + `caller_facing_message=True`); fold any `except MthdsDecodeError` clauses. Action: grep `from pipelex.` for `*Error` imports and fix paths.
-
-**5. `docs/errors/` is complete.** This branch's Phase 7 commit closes the previously-known discovery gap — every `PipelexError` subclass now has a generated reference page; every `type_uri` value resolves to a live page on docs.pipelex.com. No action in pipelex-api.
-
-**6. Webhook signing (Phase 5 / cross-repo, separate track).** Not in this PR. Authoritative plan: `_for_api/wip/security/webhook-signing.md`. 3-step rollout designed to avoid lockstep deploy — receiver-side dual-format first (pipelex-api ships first, adds `sha256=<hex>` support alongside legacy bare-hex), then worker-side body-signing, then drop legacy. The pipelex-api side carries Item 1 + Item 3. Wait for Louis's green light before starting.
-
-### How to verify your adaptation
-
-After bumping the `pipelex` pin and applying any import path fixes:
-
-- Run pipelex-api's full test suite. `ImportError` is the Phase 6 signal — fix paths, re-run.
-- Run any test that constructs a `WebhookTarget` with a static payload. The reserved-key validator will surface any collision.
-- If pipelex-api has integration tests that assert STRICT problem-document output for input errors, expect changed JSON: provider metadata stripped, `error_domain` no longer drives the passthrough.
-
-### Don't
-
-- Don't re-derive the spec from `changes-for-api-early-draft.md` — it is superseded by `api-companion-revisions.md`.
-- Don't try to land Phase 5 webhook signing in this work — separate track, separate rollout. Wait for Louis's go.
-- Don't restate the pipelex-side changes in pipelex-api code comments or PR descriptions — link to the pipelex tracker docs.
-- Don't drop the trailing slash on `type_uri` values when comparing strings — pipelex emits `<base>/<kebab-class-name>/` to match MkDocs' `use_directory_urls: true` canonical form.
diff --git a/wip/api-readiness-2-handoff.md b/wip/api-readiness-2-handoff.md
deleted file mode 100644
index 71081a94b..000000000
--- a/wip/api-readiness-2-handoff.md
+++ /dev/null
@@ -1,81 +0,0 @@
-# API team handoff — `feature/API-readiness-2`
-
-**Status.** In-repo work on this branch is at a natural pause point. The branch is shippable as a coherent unit; no PR is open yet. Two threads still need API-team coordination (one cross-repo, one in-repo follow-up). This doc is a *launchpad* for the next session — it tells you what to read and what to decide, not what to write.
-
-> The execution ledger originally lived at the repo root as `TODOS.md`; it was archived 2026-05-28 to `wip/error-handling/archive-todos-api-readiness-2.md`. Paths below refer to the archived location.
-
-**Audience.** A fresh Claude Code session pointed at this file by Louis.
-
----
-
-## How to use this doc
-
-Do **not** draft anything from this file alone. Read the authoritative sources first, then come back here to follow the structure.
-
-Cold-start reading order:
-
-1. `wip/error-handling/archive-todos-api-readiness-2.md` end-to-end — Phases, Decisions, full Session log. The Session log is the ground truth for what shipped.
-2. `wip/error-handling/README.md` and the tracker docs it links.
-3. `wip/security/webhook-signing.md`.
-4. `git log main..HEAD --oneline` and `git diff main...HEAD --stat` to see the actual shape of the branch.
-5. The repo-root `CLAUDE.md` for the workspace map — which downstream repos (`pipelex-api`, `pipelex-platform`, `pipelex-api-deploy`, `pipelex-app`, `pipelex-back-office`, `n8n-nodes-pipelex`, cookbooks/templates) consume what.
-
-Only after that should you produce the deliverables (below).
-
----
-
-## What sits on this branch
-
-Don't restate it. Re-derive from `wip/error-handling/archive-todos-api-readiness-2.md` + the Session log entries for the completed Checkpoints. The shape is:
-
-- A coherent error-handling and webhook-contract overhaul (multiple Phases, all in-repo).
-- One large structural refactor of where error classes live in the source tree.
-- A documented follow-up that the recent `/code-review` pass uncovered, partially fixed, and partially deferred.
-
-What's **not** on this branch: webhook signing (the cross-repo track). It is flagged in `wip/error-handling/archive-todos-api-readiness-2.md`.
-
----
-
-## Topics to cover when talking to the API team
-
-Bucket them — don't list flat. For each topic, re-derive the actual change from the source files and decide which API-side repo it touches. The buckets:
-
-- **Behavior changes in shipped code** — anything that changes what an API caller / webhook subscriber / Temporal log consumer sees.
-- **Code-shape changes** — anything that affects import paths, exception-type names, or the surface that downstream tests pin against.
-- **Docs-site state** — what's in `docs/errors/` right now, including anything temporarily missing or renamed.
-- **Cross-repo work still pending** — the security track + the follow-up Phase.
-
-For each topic, tag with: (a) which API-side repo is affected, (b) whether it's a breaking change, (c) whether the API team needs to act in lockstep with this PR landing or just be aware.
-
----
-
-## Questions to resolve before drafting anything
-
-- Which topics require API-side action vs. only awareness?
-- Does any behavior change need a coordinated rollout (version pin, feature flag, joint release)?
-- What's the version-bump / `CHANGELOG.md` `[Unreleased]` strategy for this branch? Look at the current `[Unreleased]` block before adding to it.
-- Is now the right moment to kick off the deferred cross-repo track, or should it wait until this branch lands?
-- Which downstream repo is the right *first* recipient of the handoff? (The list of consumers is in the repo-root `CLAUDE.md`.)
-- Should the deferred in-repo follow-up be flagged to the API team at all, or kept internal?
-- What's the right communication channel — Slack, PR description, GitHub issue, a cross-repo doc?
-
----
-
-## Deliverables expected from the fresh session
-
-1. **A short plan for Louis.** Order of operations (PR first vs. message first vs. parallel), risks, recommended next action. Two paragraphs max.
-2. **A draft handoff message in two forms:**
- - *Human form* — short, points at source docs, suitable for Slack/email.
- - *Agent-prompt form* — self-contained, suitable for pasting into a Claude Code session in one of the API-side repos to drive their adaptation work. Should give that downstream agent enough context to read the right files in *this* repo without needing follow-up.
-
-Both forms should *point at* source-of-truth docs, not restate them. The API team will read the PR and the tracker files directly.
-
----
-
-## Don'ts
-
-- Don't restate the Session log here. Point at it.
-- Don't enumerate every changed file, moved class, or renamed module. Point at the relevant Checkpoint entry.
-- Don't draft the handoff message *inside this file*. That's a deliverable, not a tracker.
-- Don't treat the deferred Phases as in progress. They aren't.
-- Don't expand this file as new work lands. If the picture changes, update `wip/error-handling/archive-todos-api-readiness-2.md` (the source of truth) and revisit this brief.
diff --git a/wip/archive/00-master-plan.md b/wip/archive/00-master-plan.md
deleted file mode 100644
index 1d9c706f5..000000000
--- a/wip/archive/00-master-plan.md
+++ /dev/null
@@ -1,409 +0,0 @@
-# Master Plan v2: LibraryCrate & Distributed Execution — SHIPPED
-
-> **Status**: Archived (2026-05-04). All phases complete and merged.
-> **Date**: 2026-03-23 (originally drafted)
-> **Successor**: [../01-master-plan.md](../01-master-plan.md) (Phase 4.5 Step 6 + Phase 6 — next phases)
-> **Related**: [early-library-as-execution-context.md](early-library-as-execution-context.md), [phase0-pipe-namespace-fix.md](phase0-pipe-namespace-fix.md), [phase4-explicit-class-registry.md](phase4-explicit-class-registry.md), [phase5-payload-codec-strategy.md](phase5-payload-codec-strategy.md), [phase2-crate-propagation-rationale.md](phase2-crate-propagation-rationale.md)
-
----
-
-## Goal
-
-Introduce the LibraryCrate as the universal intermediate representation for library loading, then leverage it to enable distributed execution (Temporal) with full library context. Get there incrementally with fast, testable results at each phase.
-
----
-
-## Design Principles
-
-1. **Three-stage pipeline.** `Bundles (files) → LibraryCrate (data) → Library (live)`. The crate is the clean boundary between sourcing and execution.
-
-2. **Flat and ref-keyed.** The crate is two flat dicts: concepts keyed by `concept_ref`, pipes keyed by `pipe_ref`. Domain is a namespace prefix in the key, not a structural container. No source paths, no package provenance.
-
-3. **Same API for direct and distributed execution.** The LibraryCrate is not Temporal-specific. Direct mode builds and loads it in-process. Distributed mode serializes and ships it. The crate model is identical.
-
-4. **Transparency in dashboards.** Everything in PipeJob remains visible as structured JSON in Temporal dashboards. No opaque bytes.
-
-5. **TDD where it makes sense.** Each phase defines clear "done" criteria with specific tests. Write tests first for the new models and interfaces.
-
----
-
-## Architecture Summary
-
-| Phase | Component | What it solves |
-|-------|-----------|----------------|
-| **0** | Pipe namespace fix (`pipe_ref`) | Prerequisite: pipes indexed by domain-qualified ref, symmetric with concepts |
-| **1** | LibraryCrate (direct mode) | Universal intermediate between bundles and live library |
-| **2** | LibraryCrate on Temporal | Library loading on workers (Layer 2: pipe resolution) |
-| **3** | Deferred WorkingMemory hydration | Dynamic class registration timing (Layer 1: Kajson deser) |
-| **4** | Explicit ClassRegistry | Library-owned registries, no singleton scoping in Kajson |
-| **4.5** | Distributed Tracing & Reporting | Cross-worker graph tracing and cost reporting via NDJSON event log |
-| **5** | StoragePayloadCodec | Payload size limits (2MB) for large libraries and WorkingMemory |
-| **6** | Cross-Package Dependencies in Crate | Dependency content included in crate; remote fetch from GitHub |
-
----
-
-## Phase 0: Pipe Namespace Fix (`pipe_ref`)
-
-> **Status**: Complete — PR #780 (628e414d)
-
-**Goal**: Pipes are indexed by domain-qualified `pipe_ref` (`domain.pipe_code`), symmetric with how concepts use `concept_ref` (`domain.ConceptCode`). Multiple bundles can contribute to the same domain.
-
-**Why first**: The LibraryCrate organizes content by domain. If pipes can collide across domains, the crate can't reliably merge content. This fix is also valuable independently — it eliminates a latent bug.
-
-See [phase0-pipe-namespace-fix.md](phase0-pipe-namespace-fix.md) for the full technical spec.
-
-### Changes
-
-- Add `pipe_ref` property to `PipeAbstract` = `f"{domain_code}.{code}"`
-- Rekey `PipeLibrary` root dict from bare `code` to `pipe_ref`
-- Update `add_new_pipe()`, `get_optional_pipe()`, `get_required_pipe()` to use `pipe_ref` as primary key
-- Update `library_manager.load_from_blueprints()` pipe tracking and source mapping
-- Fix `DomainLibrary.add_domain()` to support additive merging (or make idempotent for same-domain re-adds)
-- Update all call sites that assume bare-code pipe indexing
-
-### Key files
-
-| File | Change |
-|------|--------|
-| `pipelex/core/pipes/pipe_abstract.py` | Add `pipe_ref` property |
-| `pipelex/libraries/pipe/pipe_library.py` | Rekey root dict by `pipe_ref`, update all lookup methods |
-| `pipelex/libraries/pipe/pipe_library_abstract.py` | Update interface signatures |
-| `pipelex/libraries/library_manager.py` | Update `pipe_source_in_this_load`, source map tracking |
-| `pipelex/libraries/domain/domain_library.py` | Support additive domain merging |
-| `pipelex/hub.py` | Update global pipe lookup helpers |
-| `pipelex/pipe_controllers/sub_pipe.py` | Update pipe resolution |
-| Multiple call sites | Audit all `get_required_pipe(pipe_code=...)` calls |
-
-### Done when
-
-- [x] All existing tests pass with `pipe_ref`-based indexing
-- [x] New unit test: two pipes with same code in different domains coexist in one `PipeLibrary`
-- [x] New unit test: domain-qualified lookup returns correct pipe when same code exists in multiple domains
-- [x] New unit test: bare-code lookup still works when unambiguous (single domain)
-- [x] New unit test: bare-code lookup raises when ambiguous (same code in multiple domains)
-- [x] New unit test: multiple bundles for the same domain can be loaded (domain merging)
-- [x] `make agent-check` passes
-- [x] `make agent-test` passes
-
----
-
-## Phase 1: LibraryCrate (Direct Mode)
-
-> **Status**: Complete
-
-**Goal**: All library loading goes through `LibraryCrate` as an intermediate. The three-stage pipeline (`bundles → crate → library`) is the only path. Works in direct execution mode.
-
-### LibraryCrate model
-
-```python
-class LibraryCrate(BaseModel):
- """Complete library content, ready to load into a live Library."""
- concepts: dict[str, ConceptBlueprint | str] # concept_ref -> blueprint or description
- pipes: dict[str, PipeBlueprintUnion] # pipe_ref -> blueprint
- domains: dict[str, DomainBlueprint] # domain_code -> domain metadata
- source_map: dict[str, str] # ref -> source file path
- fingerprint: str # SHA256 of serialized content
-```
-
-Flat structure. Domain is implicit in the keys — `scoring.WeightedScore`, `scoring.compute_score`. No `DomainCrate` wrapper.
-
-### Changes
-
-- Define `LibraryCrate` model with serialization tests
-- `LibraryCrateFactory.make_from_blueprints(blueprints)`: for each bundle, qualify concept codes and pipe codes with the bundle's domain, add to flat dicts, compute fingerprint. Same ref appearing twice = error.
-- New `LibraryManager.load_from_crate(library_id, crate)`: extract domain codes from refs, create domains/concepts/pipes. This becomes the single entry point for loading.
-- Refactor `load_from_blueprints()`: internally builds a crate, then calls `load_from_crate()`. Callers don't change yet, but the path goes through the crate.
-- Update `pipeline_run_setup()` to route through the crate path.
-
-### Key files
-
-| File | Change |
-|------|--------|
-| `pipelex/libraries/library_crate.py` | **New** — `LibraryCrate` model |
-| `pipelex/libraries/library_crate_factory.py` | **New** — `make_from_blueprints()`, fingerprint computation |
-| `pipelex/libraries/library_manager.py` | Add `load_from_crate()`, refactor `load_from_blueprints()` to go through crate |
-| `pipelex/pipeline/pipeline_run_setup.py` | Route through crate |
-
-### Done when
-
-- [x] `LibraryCrate` model serializes and deserializes correctly (unit test: JSON round-trip)
-- [x] `make_from_blueprints()` merges correctly (unit test: two blueprints for same domain → both pipes/concepts in flat crate with qualified refs)
-- [x] `make_from_blueprints()` raises on concept/pipe code collision within a domain (unit test)
-- [x] `load_from_crate()` produces a valid library equivalent to `load_from_blueprints()` (integration test)
-- [x] All existing pipeline tests pass through the new `bundles → crate → library` path
-- [x] `make agent-check` passes
-- [x] `make agent-test` passes
-
----
-
-## Phase 2: LibraryCrate on Temporal
-
-> **Status**: Complete
-
-**Goal**: Temporal workers receive and load a LibraryCrate. Pipe controllers (PipeSequence, PipeCondition, PipeBatch, PipeParallel) work on workers. This solves Layer 2 (pipe resolution).
-
-**What it does NOT solve yet**: Layer 1 (dynamic class deserialization) for concepts introduced by `mthds_content` that aren't in PIPELEXPATH. That's Phase 3.
-
-See [phase2-crate-propagation-rationale.md](phase2-crate-propagation-rationale.md) for the design rationale and rejected alternatives.
-
-### Design
-
-The `LibraryCrate` lives on `PipeJob` and propagates through the signature chain so that every child workflow receives it — each child workflow is an independent Temporal workflow that can land on any worker, so the crate must travel in the serialized `PipeJob`.
-
-Each `WfPipeRouter` loads the crate inline via `load_from_crate()`, idempotent via fingerprint.
-
-### Propagation chain
-
-```
-WfPipeRouter.run(pipe_job)
- # 1. Load crate into this worker's library (idempotent via fingerprint)
- # 2. Pass crate through the signature chain:
- → pipe.run_pipe(..., library_crate=pipe_job.library_crate)
- → _live_run_pipe(..., library_crate)
- → [PipeController] _live_run_controller_pipe(..., library_crate)
- → SubPipe.run_pipe(..., library_crate)
- → PipeJobFactory.make_pipe_job(..., library_crate)
- → PipeRouterChild → new WfPipeRouter(child_pipe_job)
- # child_pipe_job.library_crate is set → cycle repeats
-```
-
-`library_crate` is an optional parameter (default `None`) at each level. Pipe operators receive it but ignore it — they have no child pipes.
-
-### Changes
-
-- Add `library_crate: LibraryCrate | None` field to `PipeJob`
-- In `PipeRouterTop`: after `pipeline_run_setup()` loads the library, build the flat crate from the blueprints that were loaded beyond PIPELEXPATH base. Attach to `PipeJob`.
-- In `WfPipeRouter.run()`: load the crate inline via `load_from_crate()`, pass to `pipe.run_pipe()`
-- Thread `library_crate` through the signature chain: `PipeAbstract.run_pipe()` → `_live_run_pipe()` → `PipeController._live_run_controller_pipe()` → `SubPipe.run_pipe()` → `PipeJobFactory.make_pipe_job()`
-- `PipeOperator._live_run_pipe()`: accept param, ignore it (no child pipes)
-
-### Key files
-
-| File | Change |
-|------|--------|
-| `pipelex/pipe_run/pipe_job.py` | Add `library_crate: LibraryCrate | None` field |
-| `pipelex/pipe_run/pipe_job_factory.py` | Accept and forward `library_crate` |
-| `pipelex/core/pipes/pipe_abstract.py` | Add optional `library_crate` param to `run_pipe()`, `_live_run_pipe()` |
-| `pipelex/pipe_operators/pipe_operator.py` | Add param to `_live_run_pipe()` (ignored) |
-| `pipelex/pipe_controllers/pipe_controller.py` | Add param to `_live_run_pipe()`, `_live_run_controller_pipe()` |
-| `pipelex/pipe_controllers/sequence/pipe_sequence.py` | Forward `library_crate` to `SubPipe.run_pipe()` |
-| `pipelex/pipe_controllers/batch/pipe_batch.py` | Forward `library_crate` to child pipe execution |
-| `pipelex/pipe_controllers/condition/pipe_condition.py` | Forward `library_crate` to child pipe execution |
-| `pipelex/pipe_controllers/parallel/pipe_parallel.py` | Forward `library_crate` to `SubPipe.run_pipe()` |
-| `pipelex/pipe_controllers/sub_pipe.py` | Add param, set on child `PipeJob` via factory |
-| `pipelex/pipe_run/pipe_router.py` | Pass `library_crate` from `PipeJob` to `run_pipe()` |
-| `pipelex/temporal/tprl_pipe/wf_pipe_router.py` | Load crate inline, pass `library_crate` to `run_pipe()` |
-| `pipelex/temporal/tprl_pipe/pipe_router_top.py` | Build `LibraryCrate` when dispatching |
-
-### Done when
-
-- [x] Integration test: PipeSequence through Temporal with PIPELEXPATH-based library only (no crate needed)
-- [x] Integration test: PipeSequence with `mthds_content` containing additional pipes (crate shipped, loaded on worker)
-- [x] `get_required_pipe()` works on worker for child pipes
-- [x] Crate is visible as structured JSON in Temporal dashboard
-- [x] `make agent-check` passes
-- [x] `make agent-test` passes
-
----
-
-## Phase 3: Deferred WorkingMemory Hydration
-
-> **Status**: Complete
-
-**Goal**: Handle Layer 1 — when `mthds_content` introduces dynamic concept classes that the worker doesn't know about at deserialization time.
-
-**The problem**: Temporal auto-deserializes PipeJob via the Kajson data converter. If WorkingMemory contains Stuff objects with dynamic content classes (e.g., `RawText`), Kajson fails because those classes aren't registered on the worker yet. The crate loading can't happen until the workflow starts, but the workflow input must be deserialized first.
-
-**The solution**: WorkingMemory travels as a raw JSON dict when it contains dynamic concepts. After library setup registers the classes, the dict is hydrated into a typed `WorkingMemory`.
-
-### PipeJob changes
-
-```python
-class PipeJob(BaseModel):
- pipe: PipeAbstract
- working_memory: WorkingMemory | None = None # typed (direct mode, or no dynamic concepts)
- working_memory_raw: dict[str, Any] | None = None # raw JSON (when deferred hydration needed)
- pipe_run_params: PipeRunParams
- job_metadata: JobMetadata
- output_name: str | None = None
- library_crate: LibraryCrate | None = None
-```
-
-### Key files
-
-| File | Change |
-|------|--------|
-| `pipelex/pipe_run/pipe_job.py` | Add `working_memory_raw: dict[str, Any] | None` field |
-| `pipelex/temporal/tprl_pipe/pipe_router_top.py` | Detect dynamic concepts, serialize WM to raw dict |
-| `pipelex/temporal/tprl_pipe/wf_pipe_router.py` | Hydration logic after library setup |
-| `pipelex/temporal/tprl_pipe/hydration.py` | **New** — `hydrate_working_memory()` utility |
-
-### Done when
-
-- [x] Integration test: PipeSequence with `mthds_content` containing a custom concept with inline structure (dynamic class)
-- [x] `working_memory_raw` hydrates correctly after library setup
-- [x] Stuff objects have correct typed content after hydration
-- [x] `working_memory_raw` is visible as plain JSON in Temporal dashboard
-- [x] `make agent-check` passes
-- [x] `make agent-test` passes
-
----
-
-## Phase 4: Explicit ClassRegistry
-
-> **Status**: Complete
-
-**Goal**: Move ClassRegistry scoping out of Kajson (a serialization library) and into Pipelex's Library lifecycle. Fix two bugs that only manifest with separate Temporal worker processes: decoder bypass (dynamic classes with `__module__="builtins"`) and teardown clobber (non-stack-safe `finally` block).
-
-See [phase4-explicit-class-registry.md](phase4-explicit-class-registry.md) for the full design.
-
-### Design
-
-- **Kajson becomes a pure library**: `loads()`/`load()` accept an explicit `class_registry` parameter. ContextVar and `set_scoped_class_registry()` are removed from `KajsonManager`.
-- **Library owns its ClassRegistry**: `Library` gets a `PrivateAttr` `_class_registry`. Each workflow creates a plain `ClassRegistry` pre-seeded from global, attaches it to its Library. GC'd with the Library — no teardown bugs, no memory leaks.
-- **Reuse existing `_library_id` ContextVar**: `hub.get_class_registry()` reads the active library_id, gets that library's ClassRegistry. No new ContextVar, no CompositeClassRegistry.
-- **Explicit at the boundary**: `temporal_data_converter` passes the registry to `kajson.loads()`.
-- **Migrate ~20 callers**: `KajsonManager.get_class_registry()` → `hub.get_class_registry()` (mechanical).
-
-### Key files
-
-| File | Change |
-|------|--------|
-| `kajson/kajson.py` | Add `class_registry` param to `loads()`/`load()` |
-| `kajson/json_decoder.py` | Accept + use explicit registry in decoder |
-| `kajson/kajson_manager.py` | Remove ContextVar, simplify to global-only |
-| `pipelex/libraries/library.py` | PrivateAttr ClassRegistry on Library |
-| `pipelex/hub.py` | `get_class_registry()` reads from library |
-| `pipelex/temporal/tprl_pipe/wf_pipe_router.py` | Plain ClassRegistry, library-associated |
-| `pipelex/temporal/temporal_data_converter.py` | Pass explicit registry to `kajson.loads()` |
-| ~9 Pipelex files | Migrate `KajsonManager.get_class_registry()` → `hub.get_class_registry()` |
-
-### Done when
-
-- [x] `kajson.loads(data, class_registry=reg)` resolves dynamic classes with `__module__="builtins"` (new unit test)
-- [x] `KajsonManager` has no ContextVar, no `set_scoped_class_registry`
-- [x] `Library._class_registry` is a PrivateAttr, GC'd with Library
-- [x] All ~20 callers migrated from `KajsonManager.get_class_registry()` to `hub.get_class_registry()`
-- [x] Manual Temporal test: 3-process setup with `dynamic_concept_sequence.mthds` passes
-- [x] `make agent-check` passes (both repos)
-- [x] `make agent-test` passes (both repos)
-
----
-
-## Phase 4.5: Distributed Tracing & Reporting (Local Version)
-
-> **Status**: Complete (Steps 0–5). Step 6 moved to [01-master-plan.md](01-master-plan.md).
-
-**Goal**: Add a file-based event log to GraphTracer so that graph tracing and cost reporting work across Temporal workers. The in-memory path is preserved unchanged for direct mode. Full implementation details in [phase4.5-distributed-tracing-implementation.md](phase4.5-distributed-tracing-implementation.md).
-
-**Design**: Dual-write in GraphTracer — when an `EventLogProtocol` is provided, events are emitted to NDJSON files alongside the existing in-memory accumulation. After all workflows complete, an assembler reads events from all files and reconstructs a cross-worker `GraphSpec`. No new tracer class, no call site changes.
-
-### Done when
-
-- [x] **Step 0 — Event Models**: `TraceEvent` hierarchy with discriminated union, serialization round-trips, `TokensUsage` models fixed to `Literal` discriminators
-- [x] **Step 1 — EventLogProtocol & NDJSON Backend**: `NdjsonEventLog` with emit/read/cleanup/dedup, `InMemoryEventLog` for tests, corrupt-line handling, multiprocess concurrent write safety
-- [x] **Step 2 — GraphSpec Assembler**: Two-pass assembly (nodes + producer map → edges), structural equivalence with current `GraphTracer` output, `UsageAggregator`
-- [x] **Step 3 — Emit Integration**: Dual-write in `GraphTracer` (optional `EventLogProtocol`), `ReportingManager` emits `UsageReportEvent`, node/edge IDs include `workflow_id` segment
-- [x] **Step 4 — Wire into Pipeline Lifecycle**: `TracingConfig`, `NdjsonEventLog` created in `WfPipeRouter` and `pipeline_run_setup`, assembly in `runner.py` finally block, direct mode unchanged
-- [x] **Step 5 — Temporal Integration Tests**: PipeSequence/PipeParallel/PipeBatch through Temporal produce correct GraphSpec, replay dedup, failure/graph-output tests
-- **Step 6 — Standalone Activity Tracing**: moved to [01-master-plan.md](01-master-plan.md)
-
----
-
-## Phase 5: StoragePayloadCodec
-
-**Goal**: Remove the 2MB payload size limit for production workloads with large libraries or WorkingMemory containing images/documents.
-
-**Why last**: Phases 0-4 work for small-to-medium payloads. Phase 5 is needed when payloads grow beyond Temporal's limits.
-
-### StoragePayloadCodec
-
-Extends `temporalio.converter.PayloadCodec`. Operates at the wire boundary — transparent to all application code.
-
-```
-Application code StoragePayloadCodec Temporal Server
------ ----- -----
-pass WorkingMemory (50MB) --> encode(): upload to storage, --> stores small ref
- replace with storage key ref in Event History
-
-receive storage ref <-- decode(): download from storage, <-- reads ref from
-return WorkingMemory (50MB) reconstruct original payload Event History
-```
-
-- Content-addressed (SHA256 key) = natural deduplication
-- Uses Pipelex's existing `StorageProviderAbstract`
-- V1: `LocalStorageProvider` (same filesystem for dev)
-- Threshold: 1MB (configurable, well under 2MB hard limit)
-
-### Key files
-
-| File | Change |
-|------|--------|
-| `pipelex/temporal/storage_payload_codec.py` | **New** — StoragePayloadCodec class |
-| `pipelex/temporal/temporal_data_converter.py` | Add codec to DataConverter |
-| `pipelex/temporal/temporal_connect.py` | Pass codec-enabled converter |
-| `pipelex/temporal/worker_cli.py` | Pass codec-enabled converter |
-| `pipelex/temporal/config_temporal.py` | Add payload codec config |
-| `pipelex/pipelex.toml` | Add `[pipelex.temporal.payload_codec]` |
-
-### Done when
-
-- [x] Unit test: payloads above threshold are stored externally, below threshold pass through
-- [x] Unit test: content-addressed deduplication works
-- [x] Integration test: large WorkingMemory survives Temporal round-trip
-- [x] `make agent-check` passes
-- [x] `make agent-test` passes
-
----
-
-## E2E Test Coverage
-
-> **Status**: Complete — all controllers passing
-
-**Goal**: Comprehensive Temporal regression test suite covering all pipe controller types (PipeSequence, PipeParallel, PipeCondition, PipeBatch) and non-LLM operators (PipeCompose). Validates that LibraryCrate propagation, deferred hydration, and per-workflow isolation work across all pipe dispatch patterns.
-
-### What was added
-
-5 new `.mthds` bundles in `tests/integration/pipelex/temporal/library_crate/`:
-
-| Bundle | Controller/Operator | Pattern |
-|--------|-------------------|---------|
-| `temporal_condition.mthds` | PipeCondition | Sequence → LLM → Condition → 3 outcome LLMs |
-| `temporal_parallel.mthds` | PipeParallel | Sequence → Parallel (2 branches) → LLM summary |
-| `temporal_batch.mthds` | PipeBatch | Sequence → LLM (list) → Batch fan-out → LLM per-item |
-| `temporal_compose.mthds` | PipeCompose | Sequence → 2 LLMs → Compose construct (+ dynamic Report concept) |
-| `temporal_combined.mthds` | Mixed | Sequence → Parallel → Condition → LLM (nested dispatch) |
-
-5 new test files with 10 tests (5 crate structure + 5 execution) — all passing.
-
-### StuffArtefact serialization issue — Resolved
-
-**Was**: PipeCondition and PipeCompose dispatched `WfMakeJinja2Text` (a `ContentGeneratorChild` Temporal sub-workflow) for expression/template evaluation. These sub-workflows serialized working memory through the Temporal data converter, and `StuffArtefact` (a plain Python object, not a Pydantic model) was not JSON-serializable. PipeBatch had a related hang.
-
-**Resolution**: Jinja2 templating no longer routes through a `ContentGeneratorChild` Temporal sub-workflow — it happens in-process. Working memory is never serialized across processes for templating, so `StuffArtefact` objects in dry-run mode are no longer a problem. No changes to `StuffArtefact` itself were needed.
-
-### Test summary
-
-| Controller | Crate structure | Execution (dry-run) | Execution (live) |
-|------------|:-:|:-:|:-:|
-| PipeSequence | pass | pass | pass |
-| PipeParallel | pass | pass | untested |
-| PipeCondition | pass | pass | untested |
-| PipeBatch | pass | pass | untested |
-| PipeCompose | pass | pass | untested |
-| Combined (Parallel+Condition) | pass | pass | untested |
-
----
-
-**Next phases**: See [../01-master-plan.md](../01-master-plan.md) for Phase 4.5 Step 6 (Standalone Activity Tracing), Phase 6 (Cross-Package Dependencies), and Future Phases.
-
----
-
-## Implementation Pattern Per Phase
-
-1. **Tests first** — Define new models, write serialization/unit tests before implementation
-2. **Model + core logic** — Implement models and core functions, pass unit tests
-3. **Integration** — Wire into existing plumbing, pass integration tests
-4. **`make agent-check`** — Lint + type check
-5. **`make agent-test`** — Full suite passes
-6. **Review "done" checklist** — All criteria met before moving to next phase
diff --git a/wip/archive/01-master-plan.md b/wip/archive/01-master-plan.md
deleted file mode 100644
index fe094aa2b..000000000
--- a/wip/archive/01-master-plan.md
+++ /dev/null
@@ -1,134 +0,0 @@
-# Master Plan v2 — Next Phases (Distributed Execution)
-
-> **Status**: Live plan — drives the remaining LibraryCrate / distributed-execution work
-> **Last refreshed**: 2026-05-04
-> **Predecessor**: [archive/00-master-plan.md](archive/00-master-plan.md) — Phases 0–5 + E2E coverage, all shipped.
-
-This file tracks the **distributed execution** work that follows the LibraryCrate refactor. Worker error-handling work lives in its own files (see "Sibling work streams" below).
-
----
-
-## What's left
-
-| Item | Status | Why we still need it |
-|---|---|---|
-| **Phase 6a — Local cross-package dependencies in crate** | Not started | Today the crate only ships the main package's blueprints; cross-package deps still resolve via PIPELEXPATH on the worker. Removing this is the prerequisite to truly stateless workers. |
-| **Phase 6b — Remote (GitHub) dependencies** | Not started | Builds on 6a; lets the crate carry deps fetched from remote addresses so workers don't need any package pre-installed. |
-
-## Recently shipped (since 00-master-plan)
-
-| Item | What actually shipped |
-|---|---|
-| **Phase 4.5 Step 6 — Cross-process tracing** | Shipped via `feature/dynamodb-tracer`, but with a different design than the originally proposed `TracingActivityInboundInterceptor`. See "Phase 4.5 Step 6 — as built" below. |
-
-Open architectural notes and known limitations live in [deferred-items.md](deferred-items.md). Long-term direction in [future-crate-first-architecture.md](future-crate-first-architecture.md). Tracing background (pre-implementation analysis — decisions superseded) in [distributed-tracing-and-reporting.md](distributed-tracing-and-reporting.md).
-
----
-
-## Phase 4.5 Step 6 — as built
-
-The original Step 6 plan called for a `TracingActivityInboundInterceptor` to set up an NDJSON event log per standalone activity. The team picked a different design:
-
-- **Pluggable backends behind `EventLogProtocol`** — `pipelex/tracing/event_log_protocol.py`. Implementations:
- - `NdjsonEventLog` — local file backend (`pipelex/tracing/ndjson_event_log.py`).
- - `DynamoDBEventLog` — cloud backend (`pipelex/tracing/dynamodb_event_log.py`), schema compatible with `pipelex-api-infra`'s `TraceEventDynamoDBAdapter`. Available behind `pip install "pipelex[dynamodb]"`.
- - `BufferingEventLog` — in-memory buffer used **inside** Temporal workflow code (`pipelex/tracing/buffering_event_log.py`). Synchronous I/O is forbidden in workflow context, so workflows buffer here and flush via an activity.
- - `InMemoryEventLog` — for tests.
- - Backend chosen at runtime via `make_event_log(tracing_config)` in `pipelex/tracing/event_log_factory.py` (`TracingBackend.NDJSON | DYNAMODB | TEMPORAL_DYNAMODB`).
-- **Workflow → activity flush, not interceptor.** `WfPipeRouter.run()` (`pipelex/temporal/tprl_pipe/wf_pipe_router.py`) wires a `BufferingEventLog` into the per-workflow `GraphTracerManager` and into the `ReportingManager` via `set_event_log(context_key=workflow_id, ...)`. After pipe execution, buffered events are drained and persisted by `act_flush_trace_events` (`pipelex/temporal/tprl_pipe/act_flush_trace_events.py`), which runs the synchronous boto3 / file writes off the workflow thread.
-- **Per-context keying** — `ReportingManager` holds a dict of `_event_log_contexts` keyed by `graph_context.lookup_key`, so concurrent workflows don't trample each other.
-- **Direct mode unchanged** — `pipeline_run_setup.py:282` calls the same `set_event_log` path, so the same `EventLogProtocol` machinery runs in-process for non-Temporal execution.
-
-Trade-off vs the original interceptor design: this approach does not capture usage events emitted from activities running in a **separate worker process** that doesn't share the workflow's `ReportingManager`. In the current deployment shape (workflows + activities on the same Worker bundle) this is a non-issue. If we ever split activities onto standalone Workers, the interceptor pattern from the old plan becomes the natural extension — at that point reopen this as a follow-up.
-
-Pre-implementation analysis (proposed SQLite/Redis backends, decision gates, etc.) is in [distributed-tracing-and-reporting.md](distributed-tracing-and-reporting.md), kept as historical context.
-
----
-
-## Phase 6: Cross-Package Dependencies in Crate
-
-> **Status**: Not started
-
-**Goal**: Include cross-package dependency content in the LibraryCrate so that Temporal workers can execute pipelines that reference concepts and pipes from other packages — without those packages being installed on the worker. Then extend to remote dependencies fetched from GitHub.
-
-See [future-crate-first-architecture.md](future-crate-first-architecture.md) for the full crate-first architectural vision and design rationale.
-
-### Why
-
-Today, cross-package dependencies (`alias->domain.ConceptCode`, `alias::domain.pipe_code`) resolve through child library lookups at loading time. The `LibraryCrate` shipped to Temporal workers does NOT include dependency content — only the main package's blueprints. This means workers must have all dependency packages pre-installed on PIPELEXPATH. Phase 6 removes this requirement: the crate becomes truly self-contained.
-
-### Phase 6a: Local Cross-Package Dependencies
-
-**Goal**: Dependency blueprints are included in the crate. Workers can execute pipelines with cross-package deps without having the dependency packages installed.
-
-**Key changes**:
-
-1. **Extract blueprint collector from `_load_single_dependency`**: Split the current method into two parts:
- - **Collect**: resolve the dependency, parse its `.mthds` files into blueprints, determine exports
- - **Load**: create child Library, load domains/concepts/pipes, register aliases
- The collector produces blueprints that accumulate into `_blueprints[library_id]` alongside the main package's blueprints.
-
-2. **Resolve cross-package aliases in the flattened crate**: Cross-package refs use alias-based syntax (`alias->domain.ConceptCode`). In a flattened crate, there are no child libraries. Options:
- - Resolve aliases during crate building (replace `alias->domain.ConceptCode` with `domain.ConceptCode` in all blueprints)
- - Carry alias mappings in the crate (`aliases: dict[str, str]`) for runtime resolution
- Decision TBD when starting implementation.
-
-3. **Update `load_from_crate()`**: Handle dependency content in the flat crate — register domains, concepts, and pipes from deps.
-
-**Done when**:
-
-- [ ] `_load_single_dependency` split into collect + load
-- [ ] Dependency blueprints accumulate into `_blueprints[library_id]`
-- [ ] `get_crate()` produces a crate that includes dependency content
-- [ ] Cross-package aliases resolved (either at crate build time or via alias map)
-- [ ] `load_from_crate()` handles dependency content correctly
-- [ ] Integration test: PipeSequence referencing a cross-package concept/pipe, executed on Temporal worker without the dependency package on PIPELEXPATH
-- [ ] `make agent-check` passes
-- [ ] `make agent-test` passes
-
-### Phase 6b: Remote Dependencies (GitHub)
-
-**Goal**: Dependencies can be fetched from remote addresses (e.g., `github.com/org/repo/package`). The crate becomes fully self-contained for cloud-native execution where workers are stateless.
-
-**Key changes**:
-
-1. **Remote resolution strategy**: Add a `REMOTE` resolution strategy to the blueprint collector extracted in 6a. Remote fetch clones/downloads the package from GitHub, parses its `.mthds` files into blueprints, and includes them in the collection.
-
-2. **Dependency address format**: Define the address format for remote deps (e.g., `github.com/org/repo@version/path/to/package`). The address goes in the package manifest.
-
-3. **Caching**: Cache fetched packages locally (content-addressed by address + version) to avoid redundant clones.
-
-4. **Transitive deps**: Remote packages may themselves have dependencies (local or remote). The collector recurses.
-
-**Done when**:
-
-- [ ] Remote fetch strategy implemented (git clone or archive download)
-- [ ] Dependency address format defined and parsed
-- [ ] Remote package blueprints included in crate
-- [ ] Local cache for fetched packages
-- [ ] Transitive remote deps resolved
-- [ ] Integration test: pipeline with remote dep from a GitHub repo, executed on Temporal worker
-- [ ] `make agent-check` passes
-- [ ] `make agent-test` passes
-
----
-
-## Dependencies between remaining items
-
-```
-Phase 6a (Local cross-package deps) ← requires Phase 2's crate propagation (shipped)
- │
- ▼
-Phase 6b (Remote deps from GitHub) ← requires Phase 6a's blueprint collector
-```
-
----
-
-## Sibling work streams (not in this plan)
-
-These tracks are tracked in their own files and ship on their own branches:
-
-| Stream | Files | Branch |
-|---|---|---|
-| Worker error-handling Phases 4–7 | `error-handling-phase-{4,5,6,7}-*.md`, `error-handling-phases-0-3-completed.md`, `worker-error-handling-review.md`, `error-handling-review.md` | `refactor/Inference-error-handling` |
-| Instructor-unwrap port to OpenAI/Mistral/Google workers | `instructor-unwrap-other-workers.md` | (open — Anthropic done, four workers remaining) |
diff --git a/wip/archive/activity_storage-plan.md b/wip/archive/activity_storage-plan.md
deleted file mode 100644
index 575288ac5..000000000
--- a/wip/archive/activity_storage-plan.md
+++ /dev/null
@@ -1,123 +0,0 @@
-# Activity-Level Storage — Execution Plan
-
-> Design: [wip/activity_storage.md](wip/activity_storage.md)
-> Branch: `fix/Temporal-Img`
-
----
-
-## Phase 1: Image Generation (fixes the immediate bug) ✅
-
-### 1.1 Modify `act_img_gen_images` to include storage
-
-- [x] **File**: `pipelex/cogt/content_generation/img_gen_generate.py`
- - Add `img_gen_single_image_and_store()` and `img_gen_image_list_and_store()` functions
- - These call the existing generation logic, then use `GeneratedContentFactory` (with `get_storage_provider()`) to store and return `ImageContent`
- - Keep the original `img_gen_single_image()` and `img_gen_image_list()` functions for the non-Temporal path
-
-- [x] **File**: `pipelex/temporal/tprl_content_generation/act_img_gen_generate.py`
- - Change `act_img_gen_images` return type: `list[GeneratedImageRawDetails]` → `list[ImageContent]`
- - Call the new `_and_store` functions instead of the raw generation functions
- - The activity receives `ImgGenAssignment` (unchanged) which already has `job_metadata` with `user_id` and `pipeline_run_id`
-
-### 1.2 Update `WfMakeImages`
-
-- [x] **File**: `pipelex/temporal/tprl_content_generation/wf_make_images.py`
- - Change return type: `list[GeneratedImageRawDetails]` → `list[ImageContent]`
- - No logic changes — just the type annotation
-
-### 1.3 Update `ContentGeneratorChild` and `ContentGeneratorTop`
-
-- [x] **File**: `pipelex/temporal/tprl_content_generation/content_generator_child.py`
- - `make_single_image()`: Gets `list[ImageContent]` from `WfMakeImages`, extracts the single item directly. Removed `make_image_content()` call
- - `make_image_list()`: Gets `list[ImageContent]` from `WfMakeImages`, returns directly. Removed comprehension calling `make_image_content()`
- - `make_image_content()`: Kept for protocol compliance but no longer called from image generation paths
-
-- [x] **File**: `pipelex/temporal/tprl_content_generation/content_generator_top.py`
- - Same changes as `ContentGeneratorChild` — `make_single_image()` and `make_image_list()` now use `ImageContent` directly from workflow
-
-### 1.4 Update test workflow
-
-- [x] **File**: `pipelex/temporal/test_extras/wf_test_content_generator_child.py`
- - Image generation is commented out (pre-existing TODO). No changes needed
-
-### 1.5 Lint + test
-
-- [x] Run `make agent-check` — 0 errors, 0 warnings
-- [x] Run `make agent-test` — all tests passed
-
----
-
-## Phase 2: Extraction with images ✅
-
-### 2.1 Modify `act_extract_gen_extract_pages` to include storage
-
-- [x] **File**: `pipelex/cogt/content_generation/extract_generate.py`
- - Added `extract_gen_pages_and_store()` that calls extraction, then uses `GeneratedContentFactory.make_page_contents()` to store extracted images and return `list[PageContent]`
- - Kept original `extract_gen_pages()` for non-Temporal path
-
-- [x] **File**: `pipelex/temporal/tprl_content_generation/act_extract_generate.py`
- - Changed return type: `ExtractOutput` → `list[PageContent]`
- - Calls the new `_and_store` function
-
-### 2.2 Update `WfMakeExtract`
-
-- [x] **File**: `pipelex/temporal/tprl_content_generation/wf_make_extract.py`
- - Changed return type: `ExtractOutput` → `list[PageContent]`
-
-### 2.3 Update `ContentGeneratorChild.make_extract_pages` and `ContentGeneratorTop`
-
-- [x] **File**: `pipelex/temporal/tprl_content_generation/content_generator_child.py`
- - `make_extract_pages()`: Gets `list[PageContent]` from `WfMakeExtract`, returns directly. Removed `make_page_contents()` call
-
-- [x] **File**: `pipelex/temporal/tprl_content_generation/content_generator_top.py`
- - Same changes as `ContentGeneratorChild`
-
-### 2.4 Lint + test
-
-- [x] Run `make agent-check` — 0 errors, 0 warnings
-- [x] Run `make agent-test` — all tests passed
-
----
-
-## Phase 3: Page view rendering ✅
-
-### 3.1 Create new activity and workflow for page view rendering
-
-- [x] **File**: `pipelex/cogt/content_generation/assignment_models.py`
- - Added `RenderPageViewsAssignment` model with `job_metadata`, `document_uri`, `page_views_dpi`
-
-- [x] **File** (new): `pipelex/temporal/tprl_content_generation/act_render_page_views.py`
- - Created `act_render_page_views` activity
- - Renders PDF pages via pypdfium2, stores images, returns `list[ImageContent]`
-
-- [x] **File** (new): `pipelex/temporal/tprl_content_generation/wf_render_page_views.py`
- - Created `WfRenderPageViews` workflow wrapping the activity
-
-### 3.2 Update `ContentGeneratorChild.make_render_page_views` and `ContentGeneratorTop`
-
-- [x] **File**: `pipelex/temporal/tprl_content_generation/content_generator_child.py`
- - `make_render_page_views()`: Delegates to `WfRenderPageViews` child workflow. Removed direct pypdfium2 rendering and `make_image_content` calls
-
-- [x] **File**: `pipelex/temporal/tprl_content_generation/content_generator_top.py`
- - Same changes — delegates to `WfRenderPageViews` workflow
-
-### 3.3 Register in task catalog
-
-- [x] **File**: `pipelex/temporal/tasks.py`
- - Added `WfRenderPageViews` to `CRAFTING` workflow list
- - Added `act_render_page_views` to `CRAFTING` activity list
-
-### 3.4 Lint + test
-
-- [x] Run `make agent-check` — 0 errors, 0 warnings (ruff auto-removed unused imports)
-- [x] Run `make agent-test` — all tests passed
-
----
-
-## Phase 4: Cleanup and full validation ✅
-
-- [x] Run `make agent-check` (full lint + type check) — 0 errors
-- [x] Run `make agent-test` (full test suite) — all passed
-- [ ] Verify no `PayloadSizeWarning` in worker logs (requires live Temporal test)
-- [ ] Verify no `NotImplementedError` crashes (requires live Temporal test)
-- [ ] Run `/temporal-e2e-validate` Mode 2 (3-process test) — includes image payload tiers
diff --git a/wip/archive/activity_storage.md b/wip/archive/activity_storage.md
deleted file mode 100644
index e06125f76..000000000
--- a/wip/archive/activity_storage.md
+++ /dev/null
@@ -1,207 +0,0 @@
-# Activity-Level Storage: Fixing Non-Deterministic I/O in Temporal Workflows
-
-> **Status**: Design
-> **Date**: 2026-04-01
-> **Related**: [phase5-payload-codec-strategy.md](phase5-payload-codec-strategy.md), Temporal img pipeline bug (fix/Temporal-Img branch)
-> **Trigger**: `NotImplementedError` when running `test_image_out_in.mthds` through Temporal — aiohttp's connector cleanup calls `loop.is_closed()` on Temporal's sandboxed event loop
-
----
-
-## 1. The Bug
-
-When running an image-generation pipeline through Temporal, the workflow crashes at the S3 storage step:
-
-```
-wf_pipe_router.py:127 → pipe_img_gen.py:214 → content_generator_child.py:372
-→ content_generator_child.py:306 → generated_content_factory.py:113
-→ s3_storage_provider.py:157 → aiohttp connector close → NotImplementedError
-```
-
-`ContentGeneratorChild.make_image_content()` calls `GeneratedContentFactory.make_image_content()` directly within the workflow context. The factory does S3 storage via aiobotocore/aiohttp. aiohttp's cleanup calls `loop.is_closed()` on Temporal's restricted event loop, which doesn't implement that method.
-
-**Root cause**: Non-deterministic I/O (S3 upload, HTTP fetch) executing inside a Temporal workflow instead of an activity.
-
----
-
-## 2. Scope of the Problem
-
-Three methods in `ContentGeneratorChild` perform I/O directly in workflow context:
-
-| Method | Line | I/O performed | Called by |
-|--------|------|---------------|-----------|
-| `make_image_content` | 300-314 | S3 storage via factory | `make_single_image`, `make_image_list`, `make_render_page_views` |
-| `make_page_contents` | 317-326 | S3 storage via factory (for each page image) | `make_extract_pages` |
-| `make_render_page_views` | 462-490 | pypdfium2 PDF rendering + S3 storage via `make_image_content` | `make_extract_pages` |
-
-All other content generation methods (LLM text, objects, image generation, extraction, templating) correctly delegate to child workflows that run activities.
-
----
-
-## 3. Why a Separate Storage Activity is Not the Right Fix
-
-The naive fix — create an activity that wraps the storage call — has two problems:
-
-1. **Payload size limit**: Temporal enforces a **2MB limit per individual payload** (inputs and outputs of both activities and workflows). The current `act_img_gen_images` already returns `list[GeneratedImageRawDetails]` containing base64 image data. We already see `PayloadSizeWarning` at 1.8MB. Larger images would hard-fail. A separate storage activity would need to receive the same large data as input — hitting the same limit.
-
-2. **Double history pollution**: The large image data would enter workflow history twice — once as the generation activity output, once as the storage activity input.
-
-The Temporal-recommended "Large Data Handling" pattern (see `phase5-payload-codec-strategy.md` section "Large Data Handling" from the Temporal developer skill): activities should read AND write large data internally, passing only small references through the workflow.
-
----
-
-## 4. The Solution: Merge Storage into Generation Activities
-
-### 4.1 Core Principle
-
-Each content generation activity becomes responsible for the full lifecycle: **generate → store → return lightweight reference**. Large binary data never crosses a Temporal boundary.
-
-### 4.2 New Activity Signatures
-
-**Image generation** (currently returns large `GeneratedImageRawDetails`):
-
-```python
-# BEFORE
-async def act_img_gen_images(img_gen_assignment: ImgGenAssignment) -> list[GeneratedImageRawDetails]:
- ... # generate, return raw base64 data
-
-# AFTER
-async def act_img_gen_images(img_gen_assignment: ImgGenAssignment) -> list[ImageContent]:
- ... # generate, store to S3, return ImageContent with URLs
-```
-
-The activity internally:
-1. Generates the image (existing logic)
-2. Calls `GeneratedContentFactory.make_image_content()` to store and build `ImageContent`
-3. Returns `ImageContent` (only URLs, no binary data)
-
-**Extraction** (currently returns `ExtractOutput` which can contain large extracted images):
-
-```python
-# BEFORE
-async def act_extract_gen_extract_pages(extract_assignment: ExtractAssignment) -> ExtractOutput:
- ... # extract, return raw extracted data with images
-
-# AFTER
-async def act_extract_gen_extract_pages(extract_assignment: ExtractAssignment) -> list[PageContent]:
- ... # extract, store images, return PageContent with URLs
-```
-
-**Page view rendering** (currently done entirely in workflow context):
-
-```python
-# NEW
-async def act_render_page_views(render_assignment: RenderPageViewsAssignment) -> list[ImageContent]:
- ... # render PDF pages, store images, return ImageContent with URLs
-```
-
-### 4.3 Workflow Changes
-
-**`WfMakeImages`**: Returns `list[ImageContent]` instead of `list[GeneratedImageRawDetails]`.
-
-**`WfMakeExtract`**: Returns `list[PageContent]` instead of `ExtractOutput`.
-
-**New `WfRenderPageViews`**: Wraps the new `act_render_page_views` activity.
-
-### 4.4 ContentGeneratorChild Changes
-
-`make_image_content` and `make_page_contents` become trivial or eliminated — the child workflows already return the final content types.
-
-| Method | Before | After |
-|--------|--------|-------|
-| `make_single_image` | Calls `WfMakeImages` (returns raw details) → `make_image_content` (S3 I/O in workflow) | Calls `WfMakeImages` (returns `ImageContent`) → done |
-| `make_image_list` | Same pattern as above | Same fix |
-| `make_image_content` | Direct factory call with S3 I/O | No longer needed for Temporal path — storage happens in activity |
-| `make_extract_pages` | Calls `WfMakeExtract` (returns `ExtractOutput`) → `make_page_contents` (S3 I/O in workflow) | Calls `WfMakeExtract` (returns `list[PageContent]`) → done |
-| `make_page_contents` | Direct factory call with S3 I/O | No longer needed for Temporal path |
-| `make_render_page_views` | pypdfium2 rendering + S3 I/O in workflow | Calls `WfRenderPageViews` → done |
-
-### 4.5 Non-Temporal Path Unchanged
-
-`ContentGenerator` (the non-Temporal implementation) continues to work as-is. The factory-level `make_image_content` and `make_page_contents` remain for the non-Temporal path. The change is only in the Temporal activities and `ContentGeneratorChild`.
-
----
-
-## 5. New Assignment Models
-
-The activities need assignment models that carry enough context for storage:
-
-```python
-class ImgGenAssignment(BaseModel):
- # existing fields...
- job_metadata: JobMetadata # already has user_id, pipeline_run_id for storage keys
- img_gen_handle: str
- img_gen_prompt: ImgGenPrompt
- img_gen_job_params: ImgGenJobParams
- img_gen_job_config: ImgGenJobConfig
- nb_images: int
- # NO NEW FIELDS NEEDED — job_metadata already carries what storage needs
-```
-
-`ImgGenAssignment` already contains `job_metadata` (with `user_id` and `pipeline_run_id`) which the `GeneratedContentFactory` needs for building storage keys. No model changes required for image generation.
-
-For page view rendering, a new assignment model:
-
-```python
-class RenderPageViewsAssignment(BaseModel):
- job_metadata: JobMetadata
- document_uri: str
- page_views_dpi: int
-```
-
----
-
-## 6. How the Activity Gets the Storage Provider
-
-Activities run in the worker process, which has the full Pipelex runtime initialized. The activity can access storage via:
-
-```python
-from pipelex.hub import get_storage_provider
-
-storage_provider = get_storage_provider()
-generated_content_factory = GeneratedContentFactory(storage_provider=storage_provider)
-```
-
-This is already the pattern used by other worker-side code (`gateway_extract_worker.py`, `pypdfium2_worker.py`).
-
----
-
-## 7. Impact on the `ContentGeneratorProtocol`
-
-The protocol defines `make_image_content` and `make_page_contents` as public methods. After this change:
-
-- **Non-Temporal** (`ContentGenerator`): Still uses them — no change.
-- **Temporal** (`ContentGeneratorChild`): These methods are no longer called from workflow context. They could be removed from the child, or kept as pass-throughs.
-
-**Decision**: Keep the protocol unchanged. The `ContentGeneratorChild` implementations of `make_image_content` and `make_page_contents` will still exist but won't be called from workflow code paths. They're kept for protocol compliance and in case they're called from non-workflow contexts in the future.
-
----
-
-## 8. Relationship to PayloadCodec (Phase 5)
-
-The PayloadCodec (`phase5-payload-codec-strategy.md`) is the general solution for large payload offloading — it transparently offloads any payload exceeding a size threshold to external storage at the wire boundary.
-
-This design is complementary, not competing:
-
-| Concern | This design | PayloadCodec |
-|---------|-------------|--------------|
-| Non-deterministic I/O in workflow | **Fixes** — moves I/O to activities | Does not fix — codec doesn't change where I/O happens |
-| Large payloads through Temporal | **Fixes for images** — activities return URLs | **Fixes for everything** — transparent offloading |
-| Required regardless of codec? | **Yes** — even with a codec, S3 I/O cannot run in workflow context | N/A |
-
-Even after PayloadCodec is implemented, activities should still handle their own storage. The codec is a safety net for payloads that are unavoidably large (e.g., library contexts), not a substitute for proper activity design.
-
----
-
-## 9. Risk Assessment
-
-| Risk | Likelihood | Mitigation |
-|------|-----------|------------|
-| Changing `WfMakeImages` return type breaks existing tests | High | Update test assertions; tests already use `InMemoryStorageProvider` |
-| Extract output loss of detail (returning `PageContent` instead of `ExtractOutput`) | Medium | Ensure all needed fields from `ExtractOutput` are captured in `PageContent` |
-| `make_render_page_views` in `ContentGeneratorChild` also uses pypdfium2 I/O | Known | Covered by the new `WfRenderPageViews` workflow |
-| Storage provider not initialized in worker | Low | Worker init already sets up full Pipelex runtime; other activities use `get_storage_provider()` |
diff --git a/wip/archive/collapse-content-generation-workflow-layer-v1.md b/wip/archive/collapse-content-generation-workflow-layer-v1.md
deleted file mode 100644
index 5e30651b8..000000000
--- a/wip/archive/collapse-content-generation-workflow-layer-v1.md
+++ /dev/null
@@ -1,254 +0,0 @@
-# Analysis: Collapsing the `tprl_content_generation/` Workflow Layer
-
-This is the narrower scope hinted at in `wip/operators-as-activities-analysis.md`'s recommendation: keep `PipeOperators` running inside `WfPipeRouter` as today, but delete the `WfMake*` / `WfRenderPageViews` workflow wrappers and have the per-workflow `ContentGenerator` call `workflow.execute_activity(act_*, …)` directly instead of `execute_child_workflow(WfMake*, …)`.
-
-The proposed shape:
-
-```
-WfPipeRun (top, unchanged)
- └─ WfPipeRouter (orchestrator, unchanged)
- └─ [PipeController iterates sub-pipes]
- ├─ WfPipeRouter (child sub-pipe, unchanged)
- │ └─ [PipeOperator's ContentGenerator]
- │ └─ workflow.execute_activity(act_llm_gen_text, …) ← direct activity call
-```
-
-versus today's:
-
-```
-WfPipeRouter
- └─ [PipeOperator's ContentGenerator]
- └─ execute_child_workflow(WfMakeLLMText)
- └─ workflow.start_activity(act_llm_gen_text, …)
-```
-
----
-
-## 1. Concrete file-level inventory
-
-### Delete
-
-All under `pipelex/temporal/tprl_content_generation/`:
-
-- `wf_make_llm_text.py` — `WfMakeLLMText` (`pipelex/temporal/tprl_content_generation/wf_make_llm_text.py:14-37`); a single `start_activity(act_llm_gen_text, …, task_queue=worker_config.inference_task_queue)` wrapped in `ActivityError → TemporalError` translation.
-- `wf_make_object.py` — four workflow defs (`WfMakeObject`, `WfMakeObjectList`, `WfMakeTextThenObject`, `WfMakeTextThenObjectList`, `pipelex/temporal/tprl_content_generation/wf_make_object.py:24-169`). The two `…ThenObject…` variants invoke two activities in sequence and assemble the second `LLMAssignment` between them.
-- `wf_make_images.py` — `WfMakeImages` (`pipelex/temporal/tprl_content_generation/wf_make_images.py:16-40`).
-- `wf_make_jinja2_text.py` — `WfMakeJinja2Text` (`pipelex/temporal/tprl_content_generation/wf_make_jinja2_text.py:18-40`).
-- `wf_make_extract.py` — `WfMakeExtract` (`pipelex/temporal/tprl_content_generation/wf_make_extract.py:16-40`).
-- `wf_render_page_views.py` — `WfRenderPageViews` (`pipelex/temporal/tprl_content_generation/wf_render_page_views.py:16-40`).
-- `content_generator_top.py` — `ContentGeneratorTop` (`pipelex/temporal/tprl_content_generation/content_generator_top.py:53-447`). This class is only used in tests (see §4 *Tests*); it dispatches `WfMake*` as top-level workflows from the submitter side. Once the `WfMake*` types are gone there is no top-level workflow to dispatch and the class becomes meaningless.
-- `content_generator_top_factory.py` — its only producer (`pipelex/temporal/tprl_content_generation/content_generator_top_factory.py:12-35`).
-- `content_generator_child.py` — `ContentGeneratorChild` (`pipelex/temporal/tprl_content_generation/content_generator_child.py:74-532`). Each method dispatches a `WfMake*` via `WorkflowExecutorFactory[…].execute_child_workflow(…)`. Becomes redundant once we call activities directly.
-- `content_generator_child_factory.py` — its only producer (`pipelex/temporal/tprl_content_generation/content_generator_child_factory.py:10-34`).
-- `content_generator_models.py` — `AssignmentType` / `ResultType` unions, only consumed by `ContentGeneratorTop`/`ContentGeneratorChild` (`pipelex/temporal/tprl_content_generation/content_generator_models.py:8-20`).
-
-### Probably delete (after a usage review)
-
-- `pipelex/temporal/tprl/conditional_worker.py` — `with_conditional_worker` (`pipelex/temporal/tprl/conditional_worker.py:14-41`). The decorator is currently applied in three places:
- 1. Each `ContentGeneratorTop` method (`pipelex/temporal/tprl_content_generation/content_generator_top.py:59` and the eight other methods at lines 90, 124, 169, 203, 278, 317, 352, 383, 418).
- 2. `TemporalPipeRouter._run_pipe_job` (`pipelex/temporal/tprl_pipe/temporal_pipe_router.py:47`).
- 3. `TemporalPipeRun.run` and `.start` (`pipelex/temporal/tprl_pipe/temporal_pipe_run.py:42, 72`).
-
- After the refactor, (1) is gone with `ContentGeneratorTop`. (2) and (3) remain — they exist so that, when running the pipelex test suite with `worker_environment=INTERNAL`, the test process spins up an in-process worker on a per-call task queue and tears it down (`pipelex/temporal/tprl/conditional_worker.py:23-37`). That capability is still used by the temporal test fixtures regardless of the content-generation layer, so the decorator file itself should stay; only the imports from `content_generator_top.py` / `content_generator_child.py` go away.
-
-- The `WorkflowExecutor.execute_child_workflow` / `start_child_workflow` methods on `pipelex/temporal/tprl/workflow_caller.py:150-216` are used today only by `ContentGeneratorChild`'s `WorkflowExecutorFactory[…].create_executor().execute_child_workflow(…)` calls (`pipelex/temporal/tprl_content_generation/content_generator_child.py:99-105` and the parallel calls in each of its other methods) and indirectly by `TemporalPipeRouter` for `WfPipeRouter` child dispatch (`pipelex/temporal/tprl_pipe/temporal_pipe_router.py:62-67`). After the refactor (2) keeps using them. Don't delete the methods, but they're free to slim if `TemporalPipeRouter` is rewritten to call `workflow.execute_child_workflow` directly.
-
-### Modify
-
-- `pipelex/temporal/tasks.py` — drop the `WfMake*` / `WfRenderPageViews` entries from the `crafting` `TaskPack`'s `workflow_list` (`pipelex/temporal/tasks.py:30-51`). The `activity_list` is unchanged: `act_llm_gen_text`, `act_llm_gen_object`, `act_llm_gen_object_list`, `act_img_gen_images`, `act_jinja2_gen_text`, `act_extract_gen_extract_pages`, `act_render_page_views` all stay registered on the `crafting` pack.
-
-- `pipelex/pipelex.py:338-351` — the runtime branch that builds a `ContentGeneratorChild` when `temporal.is_enabled` (`pipelex/pipelex.py:341-347`) needs to construct *something else*. The natural choice: a new `ContentGeneratorTemporalActivities` (subclass of `ContentGeneratorProtocol`) that, inside each method, picks between (a) calling the activity via `workflow.execute_activity(…)` when `is_in_temporal_workflow()` is true, and (b) doing nothing reasonable when called outside a workflow — because today, `ContentGeneratorChild` is *only* meaningful when called from within `WfPipeRouter`. (See §2 *Direct-mode* for why this branch is essentially never hit at top level.)
-
- A simpler alternative that matches today's contract more tightly: register the regular non-Temporal `ContentGenerator` (`pipelex/cogt/content_generation/content_generator.py:41-405`) in the hub even when `temporal.is_enabled`, and have a thin adapter that overrides only the methods that *must* hop through an activity for durability. With Pipelex's "activity worker may be a different process from the workflow worker" deployment topology (the `router` / `runner` worker scopes in `pipelex/pipelex.toml:535-567`), every LLM / extract / image / page-view / jinja2 method needs the activity hop — direct-call would run inference inside the workflow process, which breaks the split-worker setup. So in practice the new generator overrides every method.
-
-- `pipelex/temporal/test_extras/wf_test_content_generator_child.py` — `WfTestContentGeneratorChild` constructs a `ContentGeneratorChildFactory.make_content_generator_child(…)` inside the workflow body (`pipelex/temporal/test_extras/wf_test_content_generator_child.py:62-65`). Replace that with construction of the new in-workflow content generator. The test workflow itself — and its registration in `pipelex/temporal/test_extras/temporal_test_tasks.py:1-10` — stay.
-
-- Tests under `tests/integration/pipelex/temporal/content_generation/`:
- - `conftest.py` (`tests/integration/pipelex/temporal/content_generation/conftest.py:46-73`) — both fixtures `top_crafter` and `child_crafter` go away. Replace with a single fixture that builds the new in-workflow `ContentGenerator` (or skip the layer entirely and test the activities directly).
- - `test_tprl_content_generator_top.py` (the whole file, `tests/integration/pipelex/temporal/content_generation/test_tprl_content_generator_top.py:57-232`) — the cleanest move is delete: this file tests `ContentGeneratorTop` end-to-end, and that whole class is being removed. The same test scenarios are covered, in-workflow, by `WfTestContentGeneratorChild` in `test_tprl_content_generator_child.py` / `test_wf_child_crafter.py`.
- - `test_tprl_content_generator_child.py` (`tests/integration/pipelex/temporal/content_generation/test_tprl_content_generator_child.py:18-33`) — keep, but re-point `WfTestContentGeneratorChild` at the new in-workflow generator.
- - `test_tprl_make_content_generator.py` — references `ContentGeneratorTopFactory` (`tests/integration/pipelex/temporal/content_generation/test_tprl_make_content_generator.py:5-11`); deleted alongside the factory.
-
-- `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py` — its `configure_inference_task_queue` fixture overrides `worker_config.inference_task_queue` (`tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py:77-89`) so that `WfMakeLLMText.start_activity(…, task_queue=worker_config.inference_task_queue, …)` (`pipelex/temporal/tprl_content_generation/wf_make_llm_text.py:30`) routes to the runner queue. After the refactor, the same `task_queue=worker_config.inference_task_queue` argument has to be passed at the new in-workflow `workflow.execute_activity(act_llm_gen_text, …)` call site. The test still works as written, but the *site we override* moves; documentation strings in `test_split_worker_usage.py` and `tracing/helpers.py:179-231` will be out of date and need a pass.
-
-- `tests/integration/pipelex/temporal/workflows/test_wf_child_crafter.py` (`tests/integration/pipelex/temporal/workflows/test_wf_child_crafter.py:17-32`) — runs `WfTestContentGeneratorChild` and depends on `TEMPORAL_TEST_WORKFLOWS`/`TEMPORAL_TEST_ACTIVITIES`. Keep, contingent on the rewrite of `WfTestContentGeneratorChild`.
-
-- `tests/integration/pipelex/temporal/workflows/test_wf_gen_text.py` and `test_wf_jinja2.py` — already commented-out historical tests that referenced `WfMakeLLMText` / `WfMakeJinja2Text`. Delete the files outright.
-
-### Stays unchanged
-
-- All seven inference activities — `act_llm_gen_text`, `act_llm_gen_object`, `act_llm_gen_object_list` (`pipelex/temporal/tprl_content_generation/act_llm_generate.py:9-25`), `act_img_gen_images` (`pipelex/temporal/tprl_content_generation/act_img_gen_generate.py:11-30`), `act_jinja2_gen_text` (`pipelex/temporal/tprl_content_generation/act_jinja2_generate.py:8-12`), `act_extract_gen_extract_pages` (`pipelex/temporal/tprl_content_generation/act_extract_generate.py:11-25`), `act_render_page_views` (`pipelex/temporal/tprl_content_generation/act_render_page_views.py:13-39`).
-- The `ContentGeneratorProtocol` interface (`pipelex/cogt/content_generation/content_generator_protocol.py:46-159`) and the direct-mode `ContentGenerator` (`pipelex/cogt/content_generation/content_generator.py`) — both untouched.
-- `WfPipeRun`, `WfPipeRouter`, `TemporalPipeRouter`, `TemporalPipeRun`, all `act_*` activities under `tprl_pipe/`, and the entire `tprl/` directory of helpers.
-- The pipe operators themselves: `pipelex/pipe_operators/llm/pipe_llm.py`, `pipe_img_gen.py`, `pipe_extract.py`, `pipe_compose.py`, `structured_content_composer.py`. They consume `get_content_generator()` (`pipelex/pipe_operators/llm/pipe_llm.py:191`, `pipe_img_gen.py:147`, `pipe_extract.py:128`, `pipe_compose.py:152, 297`, `structured_content_composer.py:61`) and don't care which implementation is registered.
-
----
-
-## 2. Behavioral diff
-
-### Temporal history shape per LLM call
-
-Today, a single `make_llm_text` from inside `WfPipeRouter` produces this scheduling chain in the parent's history (the events with corresponding `Started`/`Completed`/`Failed` siblings are listed compactly):
-
-- `StartChildWorkflowExecutionInitiated` → `ChildWorkflowExecutionStarted` (for `WfMakeLLMText`)
-- `ChildWorkflowExecutionCompleted` (or `Failed`)
-
-…and the `WfMakeLLMText` child's *own* history adds:
-
-- `WorkflowExecutionStarted`
-- `WorkflowTaskScheduled` / `WorkflowTaskStarted` / `WorkflowTaskCompleted`
-- `ActivityTaskScheduled` (`act_llm_gen_text`) → `ActivityTaskStarted` → `ActivityTaskCompleted` / `Failed`
-- `WorkflowTaskScheduled` / `WorkflowTaskStarted` / `WorkflowTaskCompleted`
-- `WorkflowExecutionCompleted`
-
-So per LLM call: roughly **two `Initiated`/`Started`/`Completed` triplets in the parent + a full child workflow history of about a dozen events**, plus a separate child workflow execution to track.
-
-After the collapse, the same call inside the parent is just:
-
-- `ActivityTaskScheduled` → `ActivityTaskStarted` → `ActivityTaskCompleted` / `Failed`
-
-…three events, in the parent's history, no child workflow. For a `make_text_then_object` (today: one `WfMakeTextThenObject` child wrapping two `act_llm_gen_*` activities — `pipelex/temporal/tprl_content_generation/wf_make_object.py:87-111`), the saving is the same: lose the child-workflow framing events, keep the two activity invocations.
-
-A long `PipeSequence` of N LLM steps therefore goes from "N child-workflow scheduling pairs in parent + N small child histories" to "N activity scheduling pairs in parent". This is the bulk of the history-event reduction motivating the wider refactor — and unlike the wholesale "operators-as-activities" alternative, it does not cost any per-LLM-call durability, because the activity boundary is still there.
-
-### Worker registration
-
-`pipelex/temporal/tasks.py:30-51`: `crafting` `TaskPack`'s `workflow_list` shrinks from nine workflow types to zero (or to whatever auxiliary workflows we want to keep there — currently nothing). The `activity_list` (the seven `act_*` functions) is unchanged. `pipe` `TaskPack` is unchanged.
-
-The `worker_scopes` config in `pipelex/pipelex.toml:535-567` ("full", "router", "runner") is by reference: it requires the `crafting` and `pipe` packs by *name*, so the scope definitions don't need to change. The bare `router` scope (which sets `disable_all_activities=true`) currently registers nine fewer workflows; the runner scope (which sets `disable_all_workflows=true`) is unaffected.
-
-### Retry semantics
-
-Today, each `WfMake*` workflow constructs its `start_activity(…)` call with `retry_policy=worker_config.retry_policy` (`pipelex/temporal/tprl_content_generation/wf_make_llm_text.py:25-31`, and the parallel sites in the other `wf_make_*` files). That's a single global default — the per-workflow retry knob in `WorkflowExecutorFactory.create_executor(…)` (`pipelex/temporal/tprl/workflow_caller.py:219-248`) lets a *caller* override the policy at workflow-dispatch time, but `ContentGeneratorChild` doesn't pass anything custom (`pipelex/temporal/tprl_content_generation/content_generator_child_factory.py:29` plumbs the config default through). So in practice, every content-gen activity already runs under the same `worker_config.retry_policy_config`.
-
-After the collapse, the new in-workflow `ContentGenerator` should pass `retry_policy=get_config().temporal.worker_config.retry_policy` at every `workflow.execute_activity(…)` call site. This preserves identical semantics. Any future "per-content-generation-kind retry policy" feature would now plug in at the activity invocation in the new generator rather than on a per-workflow basis — practically the same surface, just relocated.
-
-The non-retryable error list in `pipelex/pipelex.toml:494-501` (`ExtractHandleNotFoundError`, `FileNotFoundError`, `ImgGenHandleNotFoundError`, `LLMHandleNotFoundError`, `ModelNotFoundError`, `ValidationError`) survives untouched — it's part of `worker_config.retry_policy`.
-
-### Per-call timeouts and task-queue routing
-
-The current `WfMake*` workflows pin both `start_to_close_timeout=worker_config.workflow_execution_timeout` and (in the LLM-text case only, `pipelex/temporal/tprl_content_generation/wf_make_llm_text.py:30`) `task_queue=worker_config.inference_task_queue`. The other `wf_make_*` files do **not** route to `inference_task_queue`; their activities run on the workflow's own task queue. So today's de-facto routing rule is:
-
-- LLM-text completions → `inference_task_queue` (when set)
-- Object-mode LLM, image gen, extract, render-page-views, templating → workflow's own queue
-
-After the collapse, the new in-workflow `ContentGenerator` re-applies the same rule at each call site: pass `task_queue=worker_config.inference_task_queue` only on the `act_llm_gen_text` invocation. This preserves the split-worker test in `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py:77-89`. It does not change the production deployment topology.
-
-The `WfMake*` workflows' own `workflow_execution_timeout` argument (passed at child dispatch from `ContentGeneratorChild`'s `execute_child_workflow(…)`, ultimately `pipelex/temporal/tprl/workflow_caller.py:167`) disappears. The activity-level `start_to_close_timeout` already plays an equivalent role: it bounds how long an LLM call may run. Today's "child workflow execution timeout" was always larger than or equal to its single activity's `start_to_close_timeout` — both came from the same `worker_config.workflow_execution_timeout` (`pipelex/temporal/tprl_content_generation/wf_make_llm_text.py:28`), so collapsing to just the activity timeout is a no-op for happy-path execution and slightly tighter on the failure path (no separate workflow timeout to wait through).
-
-### Direct-mode (non-Temporal) execution
-
-In `pipelex/pipelex.py:338-351`, when `temporal.is_enabled` is false, `ContentGenerator` (the direct, non-Temporal one) is registered. That branch is unchanged; non-Temporal flows keep their current behavior end-to-end.
-
-The `ContentGeneratorChild` branch (`pipelex/pipelex.py:341-347`) is reached when `temporal.is_enabled` is true. In production, `get_content_generator()` is called from inside `WfPipeRouter` (via the operator's `pipe_llm.py` / `pipe_img_gen.py` / etc.), so the registered child generator is always invoked from a workflow context. There is no production code path that calls `ContentGeneratorChild`'s methods at top-level outside of a workflow — `ContentGeneratorChild.make_llm_text` (`pipelex/temporal/tprl_content_generation/content_generator_child.py:80-116`) calls `WorkflowExecutorFactory[…].create_executor().execute_child_workflow(WfMakeLLMText, …)`, which uses `workflow.execute_child_workflow` from the `temporalio.workflow` module (`pipelex/temporal/tprl/workflow_caller.py:161`); that call hard-fails outside a workflow. So the *existing* contract is "this generator only works inside a workflow."
-
-After the collapse, the new in-workflow generator's contract is the same: each method calls `workflow.execute_activity(…)`, which also hard-fails outside a workflow. Direct-mode is unaffected because direct-mode never gets this generator wired in.
-
-### Dry-run path
-
-In dry mode, `ContentGeneratorDry` is registered at `pipelex/pipelex.py:339-340`. `temporal.is_enabled` is gated *after* the dry check, so dry-mode does not depend on the temporal generator. The collapse does not touch this. `WfTestContentGeneratorChild` in `pipelex/temporal/test_extras/wf_test_content_generator_child.py:53-66` switches between `ContentGeneratorDry` and (post-refactor) the new in-workflow generator based on its `is_dry_run` arg — same shape as today.
-
-### Routing of nested controller calls
-
-`TemporalPipeRouter._run_pipe_job` (`pipelex/temporal/tprl_pipe/temporal_pipe_router.py:46-91`) is unchanged. `PipeController` sub-pipes still dispatch as `WfPipeRouter` child workflows, exactly as today. The collapse only affects what happens *inside* the leaf `WfPipeRouter` when its pipe is a `PipeOperator`.
-
----
-
-## 3. Pros vs. current code
-
-- **History-event reduction.** Concretely measurable: each LLM/img/extract/jinja2 call inside a `WfPipeRouter` drops from "child workflow + activity" (≈15 events including child-workflow framing) to "activity only" (3 events). On a deep `PipeSequence` this is the dominant factor in approaching the 10K-event soft limit. The wholesale alternative documented in `wip/operators-as-activities-analysis.md` got the same reduction at the cost of per-LLM-call durability; this narrower refactor gets the reduction without that cost, because the activity is preserved.
-- **One fewer indirection in the Temporal UI.** Today, finding the actual LLM call requires drilling into `WfPipeRouter` → `WfMakeLLMText` → `act_llm_gen_text` (three workflow-execution levels in `pipelex/temporal/tprl_pipe/wf_pipe_router.py:127` → `pipelex/temporal/tprl_content_generation/content_generator_child.py:99-105` → `pipelex/temporal/tprl_content_generation/wf_make_llm_text.py:25-31`). After: `WfPipeRouter` → `act_llm_gen_text`. The activity is one level below the controller it belongs to, which matches the actual semantics.
-- **Less code to maintain.** Two near-duplicate generator implementations (`ContentGeneratorTop` + `ContentGeneratorChild`) — the only real difference between them is `execute_workflow` versus `execute_child_workflow` — collapse into one in-workflow generator. Their factories and the `AssignmentType`/`ResultType` plumbing in `content_generator_models.py` are gone.
-- **No new abstractions required.** Activities, the `act_*` functions, the registration in `tasks.py`'s `crafting` pack — all already exist and stay in place. The refactor is largely deletion.
-- **`make_text_then_object` becomes more honest.** Today, `WfMakeTextThenObject` (`pipelex/temporal/tprl_content_generation/wf_make_object.py:76-120`) wraps two activities in a child workflow whose only job is to glue them together with an `LLMAssignmentFactory.make_llm_assignment(preliminary_text=…)` call between them (`wf_make_object.py:96-104`). After collapsing, that same Python glue runs in the parent `WfPipeRouter` (between two `workflow.execute_activity` calls) — fewer hops, same logic.
-- **Eliminates the "where does retry / timeout / task_queue config live?" dual-source-of-truth problem.** Today some of those knobs are on the `WfMake*` workflow's `start_activity(…)` call (`wf_make_llm_text.py:25-31`), some are on the `ContentGeneratorChild` factory plumbing (`content_generator_child_factory.py:13-34`), and the test override in `test_split_worker_usage.py:77-89` mutates `worker_config.inference_task_queue` and *trusts* `WfMakeLLMText` to read it on every child-workflow invocation. After collapsing, all those knobs apply at the single `workflow.execute_activity(…)` call site.
-
----
-
-## 4. Cons / risks vs. current code
-
-- **Loss of distinct workflow IDs per content-generation call in the Temporal UI.** Today, `ContentGeneratorChild.make_llm_text` builds a `child_workflow_id` from the parent's id + `wfid` (`pipelex/temporal/tprl_content_generation/content_generator_child.py:57-71, 102-106`), and the same is true for every other method. Operators and tests pass `wfid=` to give a Temporal-UI-visible name to a specific content-generation step. After the collapse, the activity has no comparable "ID" surface — only `activity_id`, which is auto-assigned by the SDK and not user-controllable. Effect on observability: per-step naming is lost in the Temporal UI; you'd need to rely on activity logs, the `act_*` function name, and the `JobMetadata.content_generation_job_id` field that `update_job_metadata` already stamps on the `JobMetadata` (`pipelex/cogt/content_generation/content_generator_protocol.py:26-43`). This is the most concrete observability regression.
-- **Loss of the per-content-generation `workflow_execution_timeout`.** Today each `WfMake*` carries its own `execution_timeout` (today derived from `worker_config.workflow_execution_timeout`, but a future per-call override is on the table). After the collapse there is only the activity's `start_to_close_timeout`. In practice this is the same value today (see §2 *Per-call timeouts*), so no regression today — but you've lost a future axis of independent control.
-- **`with_conditional_worker` removal from the content-gen path.** This is the decorator at `pipelex/temporal/tprl/conditional_worker.py:14-41` that, in `INTERNAL` worker mode, spins up a per-call worker on a UUID-suffixed task queue (`conditional_worker.py:25-37`). Today every method on `ContentGeneratorTop` is wrapped with it. The decorator is *only* relevant for top-level dispatch (it spins up a *workflow* worker; activities can ride on whatever worker is already up). Post-refactor, `ContentGeneratorTop` is gone, so the wrap on those methods disappears for free; the decorator file remains because `TemporalPipeRouter` and `TemporalPipeRun` still use it. Net: fewer call sites, no behavioral change for the test suite that uses `INTERNAL` mode against `WfPipeRouter` / `WfPipeRun`.
-- **Determinism implications.** This is the biggest "subtle bug" risk. Today the `wf_make_*` workflow body is a thin layer (typically just `start_activity` + error translation), all calls run inside `WfPipeRouter`'s sandbox already, and the `ContentGenerator` adapter for child workflows lives in `content_generator_child.py` outside the sandboxed import path. After the refactor, the new in-workflow generator's *whole* method body — including any helper utility it calls — runs inside `WfPipeRouter`'s sandbox.
-
- Looking at `ContentGeneratorChild` today, its method bodies already do (a) construct `LLMAssignment` / `ObjectAssignment` / `TemplatingAssignment` / `ImgGenAssignment` / `ExtractAssignment` / `RenderPageViewsAssignment` Pydantic models, (b) call `LLMPromptTemplate.make_for_structuring_from_preliminary_text()` for the `…ThenObject…` path, (c) re-validate the returned object via `object_class.model_validate(obj.model_dump(serialize_as_any=True))` (`content_generator_child.py:157, 207, 248-299`), and (d) build child workflow IDs via `make_child_workflow_id(…)` (`content_generator_child.py:57-71`). All of those already run inside `WfPipeRouter`'s sandboxed workflow code today (they're imported through the `with workflow.unsafe.imports_passed_through():` block in `wf_pipe_router.py:8-22` indirectly, since `pipe.run_pipe(…)` reaches operator code that calls `get_content_generator()` and dispatches).
-
- So there is *no new* determinism surface introduced by collapsing — the same code already runs inside the workflow today. The only new line is `workflow.execute_activity(…)` replacing `WorkflowExecutorFactory[…].create_executor().execute_child_workflow(…)`. Both are deterministic Temporal SDK calls. The risk is therefore mostly one of *reorganization* — making sure the new generator doesn't accidentally pull in a non-passing-through import on top of what's already there. A boot test (`make tb`) and the existing `library_crate` integration suite catch this kind of regression cheaply.
-- **Default activity worker.** Today, `WfMakeLLMText` is the only call with `task_queue=worker_config.inference_task_queue` (`wf_make_llm_text.py:30`). The other `wf_make_*` files don't pass `task_queue`, so their activities run on the *workflow's* task queue (`wf_make_object.py:38-40, 64-66, 88-92, 106-111, 134-139, 153-158`; `wf_make_images.py:27-32`; `wf_make_jinja2_text.py:29-34`; `wf_make_extract.py:27-32`; `wf_render_page_views.py:27-32`). After the refactor, the new in-workflow generator must replicate this choice exactly. Easy to mis-handle if a reviewer thinks "we should route everything to inference_task_queue" — it'd break the `crafting` pack registration on the runner workers (which today register the LLM activity on the inference queue and the others on the default queue).
-
- Mitigation: write the new generator with a comment at the LLM-text site explicitly stating the asymmetric routing rule, and add a unit test that asserts the call-site `task_queue` parameter for each method.
-- **Tests that depend on the current workflow topology.** The biggest cluster:
- - `test_tprl_content_generator_top.py` (deletes wholesale).
- - `test_tprl_make_content_generator.py` (deletes wholesale).
- - `test_tprl_content_generator_child.py` (small touch — re-points).
- - `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py` (test logic still works; docstrings need updating to reflect that the `inference_task_queue` override now applies at the activity-call site rather than at `WfMakeLLMText.start_activity`).
- - `tests/integration/pipelex/temporal/workflows/test_wf_gen_text.py` and `test_wf_jinja2.py` — already commented-out historical tests that referenced `WfMakeLLMText` / `WfMakeJinja2Text`. Delete the files outright.
- - The `library_crate/` test suite (`tests/integration/pipelex/temporal/library_crate/`) tests `WfPipeRouter`-level behavior and does not directly reference the `WfMake*` classes — should pass unchanged.
- - The `tracing/` suite primarily exercises `WfPipeRouter` and its `act_flush_trace_events` activity; its dependence on `WfMake*` is only indirect (through the inference activity dispatch). Should pass unchanged after the LLM-call site is correctly task-queue-routed.
-
- Replay tests, if any, that pickle a `WfMake*` history will break — none in the current tree.
-- **Pre-existing behavioral divergence to be aware of (flag-and-fix candidate).** `ContentGenerator.make_extract_pages` (the direct-mode one, `pipelex/cogt/content_generation/content_generator.py:386-405`) augments its return with `make_render_page_views(…)` when `extract_job_params.should_include_page_views` is true. The Temporal-mode `ContentGeneratorChild.make_extract_pages` (`pipelex/temporal/tprl_content_generation/content_generator_child.py:497-532`) does not — it just dispatches `WfMakeExtract` and returns the page contents as-is, missing the page-view augmentation. The collapse is a good moment to fix that asymmetry: the new in-workflow generator can mirror `ContentGenerator.make_extract_pages`'s control flow exactly, dispatching `act_extract_gen_extract_pages` and (when needed) `act_render_page_views` as two separate activity calls. Today's `WfMakeExtract` cannot do that because it's a single-activity wrapper. This flag-and-fix is in scope per the project's "flag and fix existing bugs" principle.
-
----
-
-## 5. Refactoring plan
-
-The ordering below preserves direct-mode parity at every step (direct-mode never depends on the temporal content-generation classes) and keeps Temporal mode green at every checkpoint. Each numbered step ends with `make agent-check && make agent-test` (or, during local dev, the `tests/integration/pipelex/temporal/` subset).
-
-1. **Add the new in-workflow content generator class.** Create `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py`. Implement `ContentGeneratorInWorkflow` (or pick a better name) with the same `ContentGeneratorProtocol` surface and method-by-method bodies that call `workflow.execute_activity(act_*, arg=..., start_to_close_timeout=worker_config.workflow_execution_timeout, retry_policy=worker_config.retry_policy [, task_queue=worker_config.inference_task_queue for LLM-text only])`. Wrap with the `ActivityError → TemporalError.from_app_error(…)` translation that today lives in each `wf_make_*` (`wf_make_llm_text.py:32-35` and parallels). Add a factory that returns the instance (no kwargs needed beyond the `GeneratedContentFactory`).
-
- At this step, nothing is wired yet. Run `make agent-check`.
-
-2. **Wire the new generator behind a feature flag.** Add a temporary boolean in `pipelex/pipelex.py`'s ContentGenerator selection (`pipelex.py:338-351`) — e.g., environment-flag-gated — that picks the new generator instead of `ContentGeneratorChild` when `temporal.is_enabled`. Default: still `ContentGeneratorChild`. This is a *transient* flag; do not add it to `pipelex.toml`. Run `tests/integration/pipelex/temporal/library_crate/` and `tracing/` with the flag flipped on; assert that the suites pass. The flag isolates risk.
-
-3. **Re-point `WfTestContentGeneratorChild`.** Update `pipelex/temporal/test_extras/wf_test_content_generator_child.py:62-65` to construct the new in-workflow generator (rather than `ContentGeneratorChild`). This validates one full `make_llm_text` / `make_object_direct` / `make_text_then_object` / `make_object_list_direct` / `make_text_then_object_list` / `make_templated_text` / `make_extract_pages` round-trip via `test_wf_child_crafter.py:17-32` and `test_tprl_content_generator_child.py:18-33`. The test workflow itself is the harness for the new code path.
-
-4. **Migrate the `make_extract_pages` page-views augmentation.** While the new generator is being written, mirror `ContentGenerator.make_extract_pages`'s `should_include_page_views` branch by calling `act_render_page_views` inline after `act_extract_gen_extract_pages` returns. This fixes the pre-existing divergence noted in §4.
-
-5. **Flip the default.** Once §3 is green, swap the feature flag default so the new generator is the production path. Run `make agent-test`.
-
-6. **Delete `ContentGeneratorChild`, `ContentGeneratorTop`, factories, and the `wf_make_*` workflow files.** All in one commit, per the project's "no backward compatibility" rule:
- - Files listed under §1 *Delete*.
- - Imports in `pipelex/temporal/tasks.py:30-51` (drop the `WfMake*` and `WfRenderPageViews` from `crafting.workflow_list`).
- - The feature flag added in step 2.
- - `tests/integration/pipelex/temporal/content_generation/test_tprl_content_generator_top.py` (whole file).
- - `tests/integration/pipelex/temporal/content_generation/test_tprl_make_content_generator.py` (whole file).
- - `tests/integration/pipelex/temporal/workflows/test_wf_gen_text.py` and `test_wf_jinja2.py` (whole files — already commented-out historical tests).
- - The `top_crafter` and `child_crafter` fixtures in `tests/integration/pipelex/temporal/content_generation/conftest.py:46-73`.
-
-7. **Update docstrings.** `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py:60-68, 77-89` and `tracing/helpers.py:179-231` reference `WfMakeLLMText` by name. Rewrite the docstrings to describe the new direct-activity-call topology. The test logic does not change.
-
-8. **No `patched()` calls needed if the deploy is hard-cut.** Per project rule: there is no backward-compat transition. The constraint is that no in-flight Pipelex workflows may be running during the deploy. If that constraint cannot be enforced operationally — i.e. there are persistent long-running pipelines in production — then `workflow.patched("collapse-content-generation-layer")` would be needed at *every* `ContentGenerator.make_*` call in the new generator, with a fallback path that dispatches the legacy `WfMake*`. Recommendation: enforce the drain-before-deploy constraint and skip `patched()`.
-
----
-
-## 6. Size estimate
-
-- **Files deleted:** the `wf_make_*.py` set (six files) plus `wf_render_page_views.py`, `content_generator_top.py`, `content_generator_top_factory.py`, `content_generator_child.py`, `content_generator_child_factory.py`, `content_generator_models.py`. Plus four test files (`test_tprl_content_generator_top.py`, `test_tprl_make_content_generator.py`, `test_wf_gen_text.py`, `test_wf_jinja2.py`).
-- **Files created:** one (`content_generator_in_workflow.py`).
-- **Files modified:** `pipelex/temporal/tasks.py`, `pipelex/pipelex.py`, `pipelex/temporal/test_extras/wf_test_content_generator_child.py`, `tests/integration/pipelex/temporal/content_generation/conftest.py`, `tests/integration/pipelex/temporal/content_generation/test_tprl_content_generator_child.py`, `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py` (docstring only), `tests/integration/pipelex/temporal/tracing/helpers.py` (docstring only).
-- **Effort:** small. Most of the work is mechanical — the `ContentGeneratorChild.make_*` method bodies are already in the right shape; the change at each call site is replacing a `WorkflowExecutorFactory[…].execute_child_workflow(WfMakeXxx, …)` with `workflow.execute_activity(act_xxx, …)` and folding the `wf_make_*.py` argument-assembly inline (mostly trivial — see `wf_make_object.py:87-104` for the only nontrivial case, the `…ThenObject…` glue between two activities). Budget: a focused day for code, plus a day for the test-fixture migration and flipping the feature flag.
-- **Where bugs are likely to hide:**
- - The asymmetric `task_queue=worker_config.inference_task_queue` rule — easy to forget on the LLM-text site or to over-apply to other sites. Add an explicit unit test that mocks `workflow.execute_activity` and asserts the `task_queue=` kwarg per method.
- - The `make_text_then_object` / `…_list` glue between two activities. The current `wf_make_object.py:96-104` does an `await workflow_arg.llm_assignment_factory_to_object.make_llm_assignment(preliminary_text=preliminary_text)` *between* the two activities; that line currently runs inside the child-workflow sandbox. After the refactor it runs inside `WfPipeRouter`'s sandbox instead. `LLMAssignmentFactory.make_llm_assignment` is async — verify it doesn't internally do anything sandbox-forbidden (network I/O, time access, random). Quick code read suggests it just constructs a Pydantic model from the prompt template; safe.
- - The `model_validate(obj.model_dump(serialize_as_any=True))` round-trips at `content_generator_child.py:157, 207, 248-299`. These are needed because the activity boundary returns a generic `BaseModel` (`act_llm_gen_object` is typed `-> BaseModel` at `act_llm_generate.py:16`). The new generator must keep these round-trips at the same place; otherwise structured-output validation regresses. The temporal data converter handles `BaseModel` inheritance via `kajson` already (`pipelex/temporal/temporal_data_converter.py`), but `model_validate` against the *concrete* class is what guarantees the output type expected by callers.
- - The page-views augmentation in `make_extract_pages` (today missing, fixed during the refactor). Make sure the new branch doesn't double-emit when `should_include_page_views` is false.
-- **Replay-history compatibility:** none. Any workflow that's mid-flight at deploy time and references `WfMakeLLMText` etc. in its history will fail to replay. Drain or fail-fast all in-flight Pipelex workflows before deploy.
-
----
-
-## 7. Recommendation
-
-**Yes, do this — and do it before the wholesale operators-as-activities refactor (if that ever happens).**
-
-The wholesale alternative (`wip/operators-as-activities-analysis.md`) explicitly recommends this narrower change as the most-of-the-benefit, fraction-of-the-risk subset. The analysis here confirms that:
-
-- The history-event reduction is real (≈12 events per LLM call → 3) and is the dominant practical motivation for either refactor.
-- Per-LLM-call durability — the biggest concern about the wholesale alternative — is **fully preserved**, because the activity boundary is unchanged.
-- The `LibraryCrate` / `ClassRegistry` / `WorkingMemory` transit machinery — which is where most of the bug-finding effort would go in the wholesale alternative — is **completely untouched** here. That's the determinism work this scope explicitly avoids.
-- The deletion is mostly mechanical and concentrated in one directory (`pipelex/temporal/tprl_content_generation/`).
-
-**Ordering vs. other open work.** This refactor is best done when the temporal integration tests are otherwise green and stable, since the move flips which generator is registered into the hub. It is *not* worth coupling with a release: do it on a dev branch, run the full temporal suite + the `library_crate` and `tracing` subdirectories, and only land it once those pass. If a release or a Temporal-related feature is in flight (e.g. payload codec work, `ClassRegistry` propagation work), defer this until after the in-flight feature lands and stabilizes — the refactor is purely subtractive and gains nothing by being interleaved.
-
-**Open question to surface during implementation, not before:** the "loss of distinct workflow IDs per content-generation call in the Temporal UI" cost in §4. If the UI breadcrumbs are heavily used by ops today, consider before §6 whether to invest in setting `activity_id=` explicitly via the SDK's `activity.start_activity(...)` overrides to reproduce the `wfid`-based naming, or whether logs + `JobMetadata.content_generation_job_id` are sufficient. The decision can be made independently of the rest of the refactor.
diff --git a/wip/archive/collapse-content-generation-workflow-layer-v2-plan.md b/wip/archive/collapse-content-generation-workflow-layer-v2-plan.md
deleted file mode 100644
index b1efcdfe6..000000000
--- a/wip/archive/collapse-content-generation-workflow-layer-v2-plan.md
+++ /dev/null
@@ -1,395 +0,0 @@
-# Plan: Collapse `tprl_content_generation/` Workflow Layer
-
-> **Required reading before Phase 1:** `wip/temporal-primitives/collapse-content-generation-workflow-layer-v2.md` — the architectural analysis (current `WfMake*` shapes in §0, full file-level inventory in §1, behavioral diff incl. retry / task_queue / dry-mode in §2, the asymmetric `inference_task_queue` rule, and the `make_extract_pages` pre-existing divergence). This file is the executable plan; v2 is the *why*. Do not start Phase 1 without reading v2 first — the phases below assume that context.
->
-> **Branch:** `refactor/Temporal-primitives` (start work here; ship via PR to `main`).
-
-## Goal
-
-Replace `WfMake*` child-workflow dispatch with direct `workflow.execute_activity(act_*, …)` calls inside `WfPipeRouter`. Deletes seven workflow types, two near-duplicate generator implementations (`ContentGeneratorTop` + `ContentGeneratorChild`) and their factories, and a small assignment-types models file. Adds one new in-workflow generator. Net: history-event reduction ≈12 → 3 per content-generation call; per-LLM-call durability preserved; deletion is concentrated and mechanical.
-
-## Status
-
-- [x] **Phase 0 — Pre-flight audit** (uniqueness invariants for `activity_id`)
-- [x] **Phase 1 — Build new generator** (no wiring)
-- [x] **Phase 2 — Wire behind feature flag** (default old)
-- [x] **Phase 3 — Re-point `WfTestContentGeneratorChild`**
-- [x] **Phase 4 — Fix `make_extract_pages` page-views asymmetry**
-- [x] ✅ **Checkpoint A** — new generator validated end-to-end, ready to flip
-- [x] **Phase 5 — Flip default to new generator**
-- [x] **Phase 6 — Delete old surface** (one commit)
-- [x] **Phase 7 — Strengthen cross-process e2e coverage** (object/object-list, image-gen split-worker, extract page-views; isolate `inference_task_queue` to a single stopgap helper, pending the per-activity-routing follow-up at `wip/temporal-primitives/per-activity-queue-routing-v1.md`)
-- [x] **Phase 8 — Update docstrings and docs**
-- [x] ✅ **Checkpoint B** — old surface gone, codebase in target state
-- [x] **Phase 9 — Final verification** (full real-server pytest run + Temporal history smoke complete)
-
-Each phase ends with `make agent-check && make agent-test` (or, during local dev, the `tests/integration/pipelex/temporal/` subset). If a phase reveals a hidden divergence, stop and update this doc + the v2 analysis before proceeding.
-
----
-
-## Decisions
-
-- **Generator class name:** `ContentGeneratorInWorkflow`. The `InWorkflow` suffix flags the load-bearing constraint at every import site — this class only works when called from inside a workflow's `run()` (because each method calls `workflow.execute_activity(…)`, which hard-fails outside a workflow context).
-- **`activity_id=` for observability:** Thread `wfid` into `activity_id=` at every `workflow.execute_activity(…)` call. Preserves the Temporal Web UI per-step breadcrumb that ops use to triage failures. Uniqueness strategy depends on the Phase 0 audit outcome — see Phase 0 for the two branches.
-- **Activity-id uniqueness strategy:** **Strategy (i) — "default-`wfid`-is-unique-per-workflow"**, with three mitigations recorded in Phase 0. Today's invariant is "at most one call per `ContentGeneratorProtocol` method per `WfPipeRouter` execution"; the audit (see Phase 0 below) confirms it. Phase 1 must:
- 1. Use distinct method-default `wfid`s, FIXING the pre-existing duplicate where both `make_single_image` and `make_image_list` default to `"craft-image"` — split into `"craft-image-single"` and `"craft-image-list"` so the strategy is robust if a future site ever calls both within one execution.
- 2. Inside `make_extract_pages` (which post-Phase-4 dispatches TWO activities), explicitly construct distinct activity_ids for the inner calls (e.g. `f"{wfid}-extract-pages"` for `act_extract_gen_extract_pages` and `f"{wfid}-render-page-views"` for the conditional `act_render_page_views`). Do not rely on the inbound single `wfid` for both.
- 3. **Runtime-check the invariant**, don't just comment it. The generator carries `self._seen_activity_ids: dict[str, set[str]]` keyed by `workflow.info().workflow_id` (NOT a flat `set[str]` — the generator is set once on the hub and reused across many workflow runs, so a flat set produces cross-run false positives). The check is gated by `workflow.unsafe.is_replaying()` and short-circuits during replay, otherwise a cache-eviction replay on the same worker process would raise spurious "duplicate activity_id" errors against the populated set from the original execution. Each `make_*` method adds its computed `activity_id` to the per-workflow set and raises `ContentGenerationError` on duplicate insert. The audit proves no current call site triggers this, so the check is a regression guard, not a runtime cost. (Follow-up: the dict has no eviction; see Follow-up TODOs for the cleanup hook.)
-
- Strategy (ii) (per-method counter) was considered and rejected — adds complexity to solve a problem we don't have today, and would be replay-stable but harder to read in the Temporal UI.
-
----
-
-## Phase 0 — Pre-flight audit
-
-The `activity_id=wfid` strategy depends on activity-ids being unique within each workflow execution. `ContentGeneratorChild` defaults `wfid` to method-specific constants — `"craft-text"`, `"craft-object-direct"`, `"craft-object-list-direct"`, `"craft-image"`, `"jinja2-text"`, `"render-page-views"`, `"extract"` (`content_generator_child.py:95, 137, 178, 248, 294, 331, 372, 411`). Today these collide-by-design with each other within a single workflow because `make_child_workflow_id` prepends the parent's globally-unique `workflow_id`. After collapse, activity-ids only get the workflow's own scope — no parent prefix to fall back on. So we need to confirm the per-workflow invariant or add a counter.
-
-**Cost of skipping:** a duplicate-`activity_id` runtime error on the second call. Cost of doing the audit: ~30 minutes.
-
-- [x] Grep operator call sites for `ContentGeneratorProtocol` method calls:
- ```bash
- grep -rn "content_generator\.\(make_llm_text\|make_object\|make_object_list\|make_single_image\|make_image_list\|make_templated_text\|make_render_page_views\|make_extract_pages\)" pipelex/pipe_operators/ pipelex/pipe_controllers/ pipelex/temporal/test_extras/
- ```
- Result — six operator-side matches (no `pipe_controllers/` matches), plus six in `wf_test_content_generator_child.py`:
- - `pipe_operators/llm/pipe_llm.py:265` — `make_llm_text`
- - `pipe_operators/llm/pipe_llm.py:374` — `make_object_list`
- - `pipe_operators/llm/pipe_llm.py:392` — `make_object`
- - `pipe_operators/extract/pipe_extract.py:158` — `make_extract_pages`
- - `pipe_operators/img_gen/pipe_img_gen.py:237` — `make_image_list`
- - `pipe_operators/img_gen/pipe_img_gen.py:254` — `make_single_image`
- - `temporal/test_extras/wf_test_content_generator_child.py:64, 72, 80, 88, 98, 105` — one call per method (six methods)
-- [x] For each match, inspect surrounding control flow. Findings: no call site is inside a `for`/`while` loop; no method is invoked more than once per `_live_run_operator_pipe`; the only shared default is `"craft-image"` between `make_single_image` and `make_image_list` (mitigation in Decisions).
-- [x] Specifically confirm:
- - [x] `PipeLLM._live_run_operator_pipe` calls at most one of `make_llm_text` / `make_object` / `make_object_list` per execution. **Confirmed.** `pipe_llm.py:253-317`: the outer `if (text concept and not multiple) … else …` branch goes to `make_llm_text` xor `_llm_gen_object_stuff_content`; inside `_llm_gen_object_stuff_content` (`pipe_llm.py:354-402`), the `if is_multiple_output / else` branch goes to `make_object_list` xor `make_object`. The three methods are mutually exclusive within one execution.
- - [x] `PipeImgGen` calls `make_single_image` / `make_image_list` at most once per execution. **Confirmed.** `pipe_img_gen.py:236-260`: `if nb_images > 1 → make_image_list; else → make_single_image`. Mutually exclusive.
- - [x] `PipeExtract` calls `make_extract_pages` at most once per execution. **Confirmed.** `pipe_extract.py:158` is the sole, unconditional call inside `_live_run_operator_pipe`.
- - [x] `PipeCompose` and `structured_content_composer` consume `content_generator`. **Confirmed pure plumbing — no protocol-method invocation.** `pipe_compose.py` accepts `content_generator` and passes it down to `StructuredContentComposer` (line 255) and recursively to nested composers (`structured_content_composer.py:691`), but neither calls any `make_*` method on it. `_resolve_template`-style flows call `render_template(...)` directly (`structured_content_composer.py:660-665`), bypassing `make_templated_text`. So `make_templated_text` and `make_render_page_views` have NO operator-side call sites today.
- - [x] `WfTestContentGeneratorChild` calls each method at most once with the default `wfid`. **Confirmed.** Six calls (`wf_test_content_generator_child.py:64, 72, 80, 88, 98, 105`) cover six methods, each once. Method-specific defaults are pairwise distinct (`"craft-text"`, `"craft-object-direct"`, `"craft-object-list-direct"`, `"craft-image"`, `"jinja2-text"`, `"extract"`) — safe for this test workflow.
-- [x] Record the result in **Decisions** above. **Strategy (i) chosen** — see Decisions section.
-- [x] Note: `make_extract_pages` post-Phase-4 dispatches TWO activities (`act_extract_gen_extract_pages` + optionally `act_render_page_views`). These have different `act_*` names but share the same wrapper method. Plan their `activity_id`s explicitly: e.g. `f"{wfid}-extract"` and `f"{wfid}-render-page-views"`, or pass `wfid=` for the first and `wfid=f"{wfid}-pageviews"` for the second. **Recorded as Decisions item (2).**
-
-**Audit result summary:**
-
-| Method | Operator site(s) | Branch | Per-execution count | Default `wfid` |
-|---|---|---|---|---|
-| `make_llm_text` | `pipe_llm.py:265` | text-concept and not multiple | ≤1 | `"craft-text"` |
-| `make_object` | `pipe_llm.py:392` | `not is_multiple_output` (object branch) | ≤1 | `"craft-object-direct"` |
-| `make_object_list` | `pipe_llm.py:374` | `is_multiple_output` (object branch) | ≤1 | `"craft-object-list-direct"` |
-| `make_single_image` | `pipe_img_gen.py:254` | `nb_images == 1` | ≤1 | `"craft-image"` ⚠ |
-| `make_image_list` | `pipe_img_gen.py:237` | `nb_images > 1` | ≤1 | `"craft-image"` ⚠ |
-| `make_extract_pages` | `pipe_extract.py:158` | unconditional | exactly 1 | `"extract"` |
-| `make_templated_text` | (none in operators — only test workflow) | — | — | `"jinja2-text"` |
-| `make_render_page_views` | (none in operators — only invoked internally from `make_extract_pages`) | — | — | `"render-page-views"` |
-
-⚠ Pre-existing duplicate default `"craft-image"` shared by `make_single_image` and `make_image_list`. They never run together today (mutually exclusive in `PipeImgGen`; `WfTestContentGeneratorChild` only calls `make_single_image`). Phase 1 must split them into `"craft-image-single"` / `"craft-image-list"` — see Decisions.
-
-**Conclusion:** Today's per-workflow uniqueness invariant **holds** for Strategy (i). Strategy (i) is adopted, with the mitigations documented in Decisions (distinct method-default `wfid`s including the `craft-image` split, distinct activity_ids inside `make_extract_pages`, and a runtime uniqueness check in the new generator).
-
-**Verification:** no code changes. This phase produces an entry in **Decisions** and unblocks Phase 1.
-
----
-
-## Phase 1 — Build new in-workflow content generator ✅
-
-Add the new generator next to the existing files. No wiring yet — just code.
-
-- [x] Create `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py`.
-- [x] Define class `ContentGeneratorInWorkflow` implementing `ContentGeneratorProtocol` with all current methods.
-- [x] At every `workflow.execute_activity(…)` site, pass `start_to_close_timeout=worker_config.workflow_execution_timeout` and `retry_policy=worker_config.retry_policy`.
-- [x] Thread `wfid` into `activity_id=` per **Strategy (i)**.
-- [x] Runtime uniqueness check from Decisions item (3) — keyed by `workflow.info().workflow_id` (the generator instance is shared across workflow runs via the hub, so the per-instance set in the original plan was insufficient; scoped by workflow_id instead).
-- [x] Wrap each method body in `try/except ActivityError` to translate `ApplicationError → TemporalError.from_app_error(...)`. Did NOT carry over `except PipelexError → TemporalError.from_message_exception(...)` clause.
-- [x] Keep the `@update_job_metadata` decorator on each method.
-- [x] Inline comment at the LLM-text site stating the asymmetric routing rule.
-- [x] Create factory module `content_generator_in_workflow_factory.py`.
-- [x] Unit tests at `tests/unit/pipelex/temporal/test_content_generator_in_workflow.py` covering: positive task_queue assertion for `make_llm_text`, negative task_queue absence for non-LLM methods, activity_id threading per method, distinct default ids for image methods (`craft-image-single` / `craft-image-list`), single-vs-two-activity branching in `make_extract_pages`, the runtime duplicate check, replay-safety of the duplicate check, and `ActivityError → TemporalError` translation (both the `ApplicationError`-cause and other-cause branches).
-
-**Verification:** `make agent-check` passes; targeted unit tests green.
-
----
-
-## Phase 2 — Wire behind a temporary feature flag ✅
-
-- [x] In `pipelex/pipelex.py`, env-flag-gated branch on `os.environ.get("PIPELEX_USE_IN_WORKFLOW_CONTENT_GENERATOR")` (renamed in Phase 5 to `PIPELEX_USE_LEGACY_CONTENT_GENERATOR` when the polarity flipped). Default OFF (legacy was the default at Phase 2).
-- [x] Did NOT add to `pipelex.toml`. Transient.
-- [x] Mirrored env-flag branch in `tests/integration/pipelex/temporal/conftest.py` and `test_payload_codec_pipeline.py`.
-- [x] Validated locally with flag ON: targeted Temporal subsets pass — `library_crate/`, `tracing/` (incl. `test_split_worker_usage.py` that exercises the asymmetric `inference_task_queue` routing), `content_generation/`, `workflows/`.
-- [x] Validated with flag OFF: same subsets pass identically (baseline preserved).
-
-**Verification:** `make agent-check` passes; targeted Temporal subsets pass with both flag values.
-
----
-
-## Phase 3 — Re-point `WfTestContentGeneratorChild` ✅
-
-- [x] Updated `pipelex/temporal/test_extras/wf_test_content_generator_child.py` to import and construct via `ContentGeneratorInWorkflowFactory`.
-- [x] `is_dry_run` branch still picks `ContentGeneratorDry`.
-- [x] `tests/integration/pipelex/temporal/content_generation/test_tprl_content_generator_child.py` passes.
-
-The test workflow now exercises the new code unconditionally regardless of flag state.
-
-**Verification:** `make agent-check` passes; content_generation targeted subset green.
-
----
-
-## Phase 4 — Fix `make_extract_pages` page-views asymmetry ✅
-
-Implemented inline within Phase 1 since `make_extract_pages` is a Phase 1 method.
-
-- [x] Signature follows `ContentGeneratorProtocol` (non-None params).
-- [x] Dispatches `act_extract_gen_extract_pages` first.
-- [x] If `should_include_page_views` is true:
- - [x] `document_uri` → dispatch `act_render_page_views`.
- - [x] `image_uri` → build single-element `[ImageContent(url=extract_input.image_uri)]` inline.
-- [x] Length-match validation; raises `ContentGenerationError` on mismatch.
-- [x] Attaches via `pop(0)` loop.
-- [x] No double-emit when false.
-- [x] Distinct `activity_id`s: `f"{base_id}-pages"` and `f"{base_id}-render-page-views"`.
-- [x] Unit tests cover all branches (no-page-views, image_uri, document_uri+document branch).
-- [x] Real-PDF integration coverage added (post Phase 6):
- - New test fixture workflow `pipelex/temporal/test_extras/wf_test_content_generator_pdf_page_views.py` (`WfTestContentGeneratorPdfPageViews`) registered in `TEMPORAL_TEST_WORKFLOWS`.
- - New test class `tests/integration/pipelex/temporal/content_generation/test_tprl_content_generator_pdf_page_views.py:TestTprlContentGeneratorPdfPageViews` exercises the `document_uri` + `should_include_page_views=True` branch end-to-end through real Temporal: `act_extract_gen_extract_pages` for OCR + `act_render_page_views` for pypdfium2 rendering, with the in-workflow page_view attachment loop asserted page-by-page. Marked `@extract @inference @dry_runnable @temporal`.
- - Uses local 2-page `tests/data/documents/Job-Offer.pdf` (added as `PipeTestCases.JOB_OFFER_PDF_LOCAL` in `tests/integration/pipelex/temporal/test_data.py`) — multi-page catches `pop(0)` ordering bugs that a 1-page PDF would not.
-
-**Verification:** `make agent-check` passes; unit tests verify all branches.
-
----
-
-## ✅ Checkpoint A — Ready to flip (REACHED)
-
-State at this checkpoint:
-- New generator (`ContentGeneratorInWorkflow`) implemented in `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py`, factory in `content_generator_in_workflow_factory.py`, unit tests in `tests/unit/pipelex/temporal/test_content_generator_in_workflow.py`.
-- Wired behind env-flag `PIPELEX_USE_IN_WORKFLOW_CONTENT_GENERATOR` (Phase 5 renamed to `PIPELEX_USE_LEGACY_CONTENT_GENERATOR`) in `pipelex.py` and both Temporal conftests (`tests/integration/pipelex/temporal/conftest.py` and `test_payload_codec_pipeline.py`); default OFF at Checkpoint A.
-- `pipelex/temporal/test_extras/wf_test_content_generator_child.py` re-pointed to construct the new generator unconditionally (this is a test fixture workflow; the env flag does not gate it).
-- `make_extract_pages` page-views asymmetry fixed; both single-image (`image_uri`) and multi-page (`document_uri`) branches covered by unit tests.
-- `ContentGeneratorChild` and `ContentGeneratorTop` still exist; production traffic still goes through `ContentGeneratorChild` (flag OFF).
-
-Validated locally — targeted Temporal subsets pass with both flag values: `library_crate/`, `tracing/` (incl. `test_split_worker_usage.py`, which is the only test exercising the asymmetric `inference_task_queue` routing rule and so the load-bearing test for that rule under the new code path), `content_generation/`, `workflows/`.
-
-Notable design fix applied during Phase 1 (after a silent-failure-hunter review): the runtime activity-id uniqueness check is keyed by `workflow.info().workflow_id` (dict of sets) rather than a flat instance-level set, AND short-circuits during replay via `workflow.unsafe.is_replaying()`. The original plan's flat set would have produced cross-run false positives; without the replay guard, cache-eviction replays on the same worker process would have raised spurious duplicates against the populated set from the original execution. See Decisions item (3) and the file's docstring/comments.
-
-Code review feedback applied (silent-failure-hunter + code-reviewer agents):
-- C1 (replay false positives) — fixed via `is_replaying()` guard.
-- S5 (no test coverage on the catch blocks) — added two tests for `ActivityError → TemporalError` translation (`ApplicationError`-cause path and other-cause re-raise path).
-- Findings deferred (mirror legacy behavior or low-value vs. blast-radius): orphan storage on partial `make_extract_pages` failure (S2), `nb_items` parameter being silently ignored (S3, pre-existing across all generators), code duplication between standalone `make_render_page_views` and the inline dispatch in `make_extract_pages` (S4), choice of `log` vs `workflow_log` in catch blocks (S6, replicates legacy `wf_make_images.py` pattern).
-- Findings filed as Follow-up TODOs: `_seen_activity_ids` unbounded growth.
-
-Working-tree state (uncommitted):
-- 8 changed files (3 added, 5 modified). Run `git status` to see them. Nothing has been committed yet — Checkpoint A is the natural commit boundary; recommended to commit before Phase 5 so the flip can be reverted cheaply.
-
-Open questions / decisions for next session:
-- [ ] Land Checkpoint A as a standalone commit before Phase 5 (strongly recommended).
-
----
-
-## Phase 5 — Flip the feature flag default ✅
-
-- [x] In `pipelex/pipelex.py`, flipped the env-flag default. Renamed the variable to `PIPELEX_USE_LEGACY_CONTENT_GENERATOR` so the polarity is self-documenting: unset → new in-workflow generator (default); set → legacy `ContentGeneratorChild` escape hatch.
-- [x] Mirrored the rename + flipped polarity in `tests/integration/pipelex/temporal/conftest.py` and `tests/integration/pipelex/temporal/test_payload_codec_pipeline.py`.
-- [x] `make agent-check` passes (ruff/pyright/mypy clean).
-- [x] `make agent-test` passes (full suite).
-- [x] Targeted `tests/integration/pipelex/temporal/content_generation/` (9 tests) and `tests/integration/pipelex/temporal/tracing/` (36 tests, including `test_split_worker_usage.py` which is the load-bearing test for the asymmetric `inference_task_queue` routing rule) pass under the new default.
-- [ ] Optional: run against a real Temporal server (`.venv/bin/pytest tests/integration/pipelex/temporal/ --temporal-server local`) — not run this session (requires local Temporal server).
-- [ ] Optional: manual UI inspection of a `library_crate/` pipeline run — requires human inspection.
-
-**Note for Phase 6:** the env var was renamed from `PIPELEX_USE_IN_WORKFLOW_CONTENT_GENERATOR` to `PIPELEX_USE_LEGACY_CONTENT_GENERATOR`. Phase 6 must grep/delete the new name.
-
----
-
-## Phase 6 — Delete the old surface (one commit) ✅
-
-Per the project's "no backward compatibility" rule, deleted in a single commit:
-
-**Files deleted under `pipelex/temporal/tprl_content_generation/`:**
-
-- [x] `wf_make_llm_text.py`
-- [x] `wf_make_object.py`
-- [x] `wf_make_images.py`
-- [x] `wf_make_jinja2_text.py`
-- [x] `wf_make_extract.py`
-- [x] `wf_render_page_views.py`
-- [x] `content_generator_top.py`
-- [x] `content_generator_top_factory.py`
-- [x] `content_generator_child.py`
-- [x] `content_generator_child_factory.py`
-- [x] `content_generator_models.py`
-
-**Test files deleted:**
-
-- [x] `tests/integration/pipelex/temporal/content_generation/test_tprl_content_generator_top.py`
-- [x] `tests/integration/pipelex/temporal/content_generation/test_tprl_make_content_generator.py`
-- [x] `tests/integration/pipelex/temporal/workflows/test_wf_gen_text.py` (already commented-out)
-- [x] `tests/integration/pipelex/temporal/workflows/test_wf_jinja2.py` (already commented-out)
-
-**Edits:**
-
-- [x] `pipelex/temporal/tasks.py` — dropped the `WfMake*` / `WfRenderPageViews` import lines; the `crafting` `TaskPack` now has `workflow_list=[]`. Activity list unchanged.
-- [x] `pipelex/pipelex.py` — removed the feature-flag branch (`PIPELEX_USE_LEGACY_CONTENT_GENERATOR` and the surrounding `if/else`); when `temporal.is_enabled` is true, `ContentGeneratorInWorkflowFactory.make_content_generator_in_workflow(...)` is now constructed unconditionally. Dropped the `os` import (no longer used).
-- [x] `tests/integration/pipelex/temporal/conftest.py` — dropped the env-flag branch and inline `import os`; conftest now imports `ContentGeneratorInWorkflowFactory` at the top of the function and constructs it unconditionally.
-- [x] `tests/integration/pipelex/temporal/test_payload_codec_pipeline.py` — same pattern as the parent conftest.
-- [x] `tests/integration/pipelex/temporal/content_generation/conftest.py` — removed the `ContentGeneratorChild` / `ContentGeneratorChildFactory` / `ContentGeneratorTopFactory` imports along with the `top_crafter` and `child_crafter` fixtures and their now-unused supporting imports (`AsyncGenerator`, `pytest_asyncio`, `TemporalClient`, `ContentGeneratorDry`, `ContentGeneratorProtocol`, `GeneratedContentFactory`, `PipeRunMode`, `TemporalWorkerEnvironment`).
-- [x] `test_tprl_content_generator_child.py` — no edit needed; only imports the surviving `WfTestContentGeneratorChild` test fixture workflow.
-- [x] **Bonus:** removed the now-stale code comment in `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py:211` that referenced the deleted `ContentGeneratorChild`.
-
-**Verification:**
-
-- [x] `make cleanderived` (regenerated `_generated_model_sets.py` afterwards via `pipelex-dev preprocess-test-models --generate-fixtures --profile ci`, otherwise pyright fails on the missing-import).
-- [x] `make agent-check` — ruff + plxt + pyright + mypy clean.
-- [x] `make agent-test` — full suite passes.
-- [x] `make tb` — boot test passes.
-
-**Notes / known follow-ups handed to Phase 8:**
-
-- Three stale references to `WfMakeLLMText` survive in `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py` (lines 3, 63, 80). These are docstrings/comments; Phase 8 explicitly owns this rewrite together with `tracing/helpers.py` and `docs/under-the-hood/`.
-- The `WfTestContentGeneratorChild` test fixture workflow (in `pipelex/temporal/test_extras/`) is intentionally kept — it was re-pointed in Phase 3 to use the new in-workflow generator and is the only thing Phase 6 leaves with "Child" in the name.
-
----
-
-## Phase 7 — Strengthen cross-process e2e coverage ✅
-
-Goal: bring the post-collapse code paths (object/object-list, image-gen across split workers, extract page-views) up to the cross-process coverage level that `make_llm_text` already has via `tracing/test_split_worker_usage.py`. Also isolate the provisional `inference_task_queue` two-queue logic to a single deletion point, so the future per-activity routing migration (designed in `wip/temporal-primitives/per-activity-queue-routing-v1.md`) is mechanical rather than archeology.
-
-### Coverage gap analysis
-
-After Phase 6, the six `ContentGeneratorProtocol` methods have wildly different e2e coverage levels:
-
-| Method | In-process worker | Cross-process / split-worker |
-|---|---|---|
-| `make_llm_text` → `act_llm_gen_text` | ✅ `WfTestContentGeneratorChild` | ✅ `tracing/test_split_worker_usage.py` |
-| `make_object` → `act_llm_gen_object_direct` | ✅ same | ❌ none — biggest gap |
-| `make_object_list` → `act_llm_gen_object_list_direct` | ✅ same | ❌ none |
-| `make_single_image` / `make_image_list` → `act_img_gen` | ✅ same | ⚠ skill Tier 4/5 default to single worker |
-| `make_extract_pages` (one-activity branch) | ✅ same | ❌ none |
-| `make_extract_pages` (two-activity, real PDF) | ✅ `TestTprlContentGeneratorPdfPageViews` | ❌ none |
-
-Every existing `library_crate/*.mthds` bundle outputs `Text`, so `act_llm_gen_object_direct` and `act_llm_gen_object_list_direct` never go through the real Temporal data converter cross-process. The pre-existing serialization asymmetry between `make_object` (uses `model_dump(mode="json", serialize_as_any=True)`) and `make_object_list` (omits `mode="json"` — see v2 §6 and Phase 0 audit) survived the collapse and is still untested at the cross-process boundary. The two-activity `make_extract_pages` branch is the most fragile post-collapse: it's the only method that dispatches more than one activity, and so the only one whose `activity_id` uniqueness mitigation (`f"{base_id}-pages"` and `f"{base_id}-render-page-views"`) actually matters in production.
-
-### The `inference_task_queue` asymmetry is provisional
-
-The current binary model — "LLM goes to `inference_task_queue`, everything else goes to default" — was introduced as a quick split-worker test setup. It is NOT the long-term design. Real deployments will want per-provider, per-model, per-activity-class routing (one worker pool per AI provider, or per model, or per activity type), covering LLM + image-gen + extract under the same routing system.
-
-The proper general design is documented in [`wip/temporal-primitives/per-activity-queue-routing-v1.md`](wip/temporal-primitives/per-activity-queue-routing-v1.md) and is **out of scope for this PR**. Implementing it is a follow-up with its own branch, CHANGELOG entry, and migration story.
-
-What this PR needs is to survive the two-queue model cleanly: centralize the one place that knows about it, mark it as provisional, and pin tests so the future migration is mechanical.
-
-### Stopgap for this PR
-
-The proper design (linked above) deletes everything below. Until it lands, do the minimum to keep the current 2-queue model from rotting:
-
-- [x] In `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py`, extract a tiny module-private helper `_inference_dispatch_kwargs(worker_config) -> dict[str, Any]` that returns `{"task_queue": worker_config.inference_task_queue}`. Called at the single LLM-text dispatch site by `**`-unpacking.
-- [x] Docstring on `_inference_dispatch_kwargs` records the stopgap status and points at `wip/temporal-primitives/per-activity-queue-routing-v1.md`.
-- [x] `tests/unit/pipelex/temporal/test_content_generator_in_workflow.py` pinned to the helper symbol on both positive (LLM-text passes `task_queue=worker_config.inference_task_queue`) and negative (other methods do NOT pass it) assertions.
-- [x] `.claude/skills/temporal-e2e-validate/SKILL.md` Tier 4 / Tier 5 sections updated: split workers promoted from "recommended" to **required**, with a Tier 10 negative-routing assertion (`tmux capture-pane -t temporal-worker-runner -p -S -200 | grep -c "act_img_gen"` must return 0).
-- [x] Follow-up TODOs entry already in place pointing at `wip/temporal-primitives/per-activity-queue-routing-v1.md` (see bottom of this file) — explicitly references `_inference_dispatch_kwargs` as the deletion point.
-
-### New tests — pytest and skill side-by-side
-
-Each tier ships with a **pytest integration test** (CI-runnable via `make agent-test`, optionally against `--temporal-server local`) and, where applicable, a **skill artifact** (a bundle or SKILL.md edit, for manual tmux-driven verification). Tier 10 is skill-only — it's a tightening of existing instructions, not new code.
-
-The pytest tests follow the existing pattern in `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py` (two scope-bound workers, submission via `TemporalClient`, assertions on workflow history or output).
-
-- [x] **Tier 9 — Object generation through Temporal cross-process.**
- - **pytest:** `tests/integration/pipelex/temporal/tracing/test_split_worker_object_gen.py:TestSplitWorkerObjectGen` (passes, marked `@temporal`). Submits `WfTestStructuredOutputCrossProcess` parameterized as single + list. Substitutes `act_llm_gen_object` / `act_llm_gen_object_list` with stubs returning canonical `FixtureInvoice` instances (custom nested concept: `FixtureCustomer` + `list[FixtureLineItem]`, registered in `temporal_registry_test_models.py`). The fixture workflow asserts the round-trip preserved nested types and field values — `model_dump(mode="json", serialize_as_any=True)` → Temporal data converter → `model_validate(...)`. Workflow assertions raise `ContentGenerationError` on regression, surfacing as `WorkflowFailureError`.
- - **skill bundle:** `tests/integration/pipelex/temporal/library_crate/structured_output_sequence.mthds` with `Invoice` (nested `Customer` + `LineItem` list) and two PipeLLM pipes (`generate_invoice_single` / `generate_invoice_list`). Tier 9 entry in SKILL.md (Step 5c).
- - **Deviation from original spec:** the test uses a **single-worker** setup, not split workers. Reason: object-gen activities don't currently pass `task_queue=` so they always run on the workflow's queue — there's no `inference_task_queue` analog for object-gen until per-activity routing lands. Single-worker is sufficient because Temporal's data converter still serializes/deserializes the activity return value across the activity boundary regardless of process count. The test file's docstring records this rationale.
-
-- [x] **Tier 10 — Image generation across split workers** (skill-only — negative-routing assertion).
- `.claude/skills/temporal-e2e-validate/SKILL.md` Tier 4 + Tier 5 promoted to require split workers, with the post-run negative-routing assertion (`grep -c "act_img_gen"` on the runner pool must return 0). Tier 10 row added to the final report table.
-
-- [x] **Tier 11 — `make_extract_pages` two-activity cross-process** (regression guard for the most fragile path).
- - **pytest:** `tests/integration/pipelex/temporal/tracing/test_split_worker_extract_pages.py:TestSplitWorkerExtractPages` (passes, marked `@temporal`). Reuses `WfTestContentGeneratorPdfPageViews` (the `document_uri` + `should_include_page_views=True` branch) with substitutes for both `act_extract_gen_extract_pages` and `act_render_page_views` returning canonical 2-page outputs. Asserts via `WorkflowHandle.fetch_history()` that two `ActivityTaskScheduled` events appear with activity_ids `"extract-pages"` and `"extract-render-page-views"` — pins the activity_id contract from `make_extract_pages`.
- - **skill entry:** Tier 11 added in SKILL.md Step 5d.
- - **Deviation from original spec:** marker simplified from `@extract @temporal` to `@temporal` (the substitutes mean no real Azure/pypdfium2 dependencies are touched). Single-worker setup vs. split-worker for the same reason as Tier 9 (extract activities don't have task_queue routing yet).
-
-- [ ] ~~**Optional — activity_id observability contract test.**~~ Skipped. The existing unit tests in `tests/unit/pipelex/temporal/test_content_generator_in_workflow.py` already pin every method's default activity_id. Adding a hermetic integration counterpart would require substituting 5+ activities just to re-validate the same contract, so the marginal value is low. Can be revisited if production triage ever surfaces a real activity_id rename gap.
-
-**Verification:** `make agent-check` clean (ruff/plxt/pyright/mypy). The three new tests pass under `pytest --timeout=60 --timeout-method=thread`. Targeted Temporal subset (`tests/unit/pipelex/temporal/ tests/integration/pipelex/temporal/`) shows 184 passed; the 4 failures in `tracing/test_wf_graph_tracing_batch.py` under `-n auto` are pre-existing flakes (documented in `tracing/conftest.py`: PipeBatch/PipeParallel + `WorkflowEnvironment.start_local` contend under pytest-xdist parallelism) and pass in isolation.
-
----
-
-## Phase 8 — Update docstrings and docs ✅
-
-- [x] `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py` — module docstring + the two fixture docstrings (`live_sequence_tracing_job`, `configure_inference_task_queue`) now describe the direct-activity-call topology. The fallback being exercised is now stated as "`WfPipeRouter` dispatches `act_llm_gen_text` to a separate task queue" via `ContentGeneratorInWorkflow.make_llm_text` calling `workflow.execute_activity(...)` directly — no child workflow layer between the router and the activity.
-- [x] `tests/integration/pipelex/temporal/tracing/helpers.py` — re-read; the docstrings of `make_split_workers` and `_runner_isolated_act_llm_gen_text` describe the topology in terms of "router worker / runner worker" and `workflow's start_activity call` (line 178 in the pre-collapse file). They never named `WfMake*`, so they are already accurate for the post-collapse topology. No edit needed.
-- [x] `docs/under-the-hood/pipe-routing-and-execution.md` — renamed the "Content Generation Workflows" section to "Content Generation Activities" and replaced the two-column `Workflow | Activity | Purpose` table with a single-column `Activity | Purpose` table that lists all seven content-generation activities (`act_llm_gen_text`, `act_llm_gen_object`, `act_llm_gen_object_list`, `act_jinja2_gen_text`, `act_extract_gen_extract_pages`, `act_render_page_views`, `act_img_gen_images`). Added a sentence pointing at `ContentGeneratorInWorkflow` as the dispatch entry point and noting the asymmetric `inference_task_queue` rule for `act_llm_gen_text`. Updated the StuffArtefact dry-run paragraph to describe `act_jinja2_gen_text` (internal activity) instead of `WfMakeJinja2Text` (internal sub-workflow).
-- [x] `docs/under-the-hood/temporal-integration.md` — updated four references:
- - The PipeSequence topology box (was "1 child WfMakeLLMText + 1 ActLLMGenText activity") now says "1 act_llm_gen_text activity (dispatched directly from WfPipeRouter via ContentGeneratorInWorkflow.make_llm_text)".
- - The Controller Dispatch Patterns table's PipeCondition row now mentions "an internal `act_jinja2_gen_text` activity" instead of `WfMakeJinja2Text`.
- - The "Internal sub-workflows" subsection renamed to "Internal templating activities"; both PipeCondition and PipeCompose now name `act_jinja2_gen_text` and the trailing paragraph mentions `ContentGeneratorInWorkflow.make_templated_text` + `workflow.execute_activity(...)` as the dispatch path.
- - The "Known Limitation: StuffArtefact Serialization in Dry-Run" section's PipeCondition / PipeCompose bullets now name `act_jinja2_gen_text`.
-- [x] Grep verification — `grep -rn "WfMake\|wf_make_\|WfRenderPageViews\|wf_render_page_views\|ActLLMGenText" docs/ tests/ pipelex/` returns zero matches across the post-Phase-8 tree (CHANGELOG.md retains historical references to the deleted workflow types in the new `[Unreleased]` Changed entry, which is intentional — the changelog is the one place those names should still appear).
-- [x] CHANGELOG `[Unreleased]` — added a `### Changed` block above the existing `### Fixed` block. Entry covers: which workflow types and generators were deleted, why the collapse is durability-neutral (retry stays at the activity level), how per-step naming is preserved via `activity_id` with the new runtime uniqueness check, the preserved-and-isolated `inference_task_queue` rule, and the page-views asymmetry fix in `make_extract_pages` (the pre-existing image_uri-skips-page-views divergence that Phase 4 fixed).
-
-**Verification:** `make agent-check` not re-run this session (docs/comments-only changes; no Python semantics touched). Run at the top of Phase 9.
-
----
-
-## ✅ Checkpoint B — Codebase in target state (REACHED)
-
-State at this checkpoint:
-- `tprl_content_generation/` contains only the `act_*.py` activity modules (`act_llm_generate.py` defines `act_llm_gen_text` / `act_llm_gen_object` / `act_llm_gen_object_list`; plus `act_img_gen_generate.py`, `act_jinja2_generate.py`, `act_extract_generate.py`, `act_render_page_views.py`) and the new `content_generator_in_workflow.py` (+ its factory `content_generator_in_workflow_factory.py`).
-- `pipelex.py` always wires the new generator when `temporal.is_enabled` (env-flag escape hatch deleted in Phase 6).
-- All `WfMake*` / `wf_make_*` / `WfRenderPageViews` / `wf_render_page_views` / `ActLLMGenText` references gone from `pipelex/`, `tests/`, and `docs/`. The only surviving mentions are in `CHANGELOG.md`'s `[Unreleased]` Changed entry, which is intentional (historical record of what was deleted).
-- Page-views augmentation works in Temporal mode (both `document_uri` → `act_render_page_views` and `image_uri` → inline single-element branches; real-PDF integration test `TestTprlContentGeneratorPdfPageViews` exercises the multi-page `document_uri` branch end-to-end; cross-process regression guard `TestSplitWorkerExtractPages` pins the two-activity dispatch contract).
-- All Temporal integration tests pass under `make agent-test` (full suite green at end of Phase 8).
-- `make agent-check` clean: ruff + plxt (TOML/MTHDS) + pyright + mypy all clean.
-
-Working-tree state (uncommitted): TODOS.md + CHANGELOG.md + the two updated docs + the test docstring rewrite. Natural commit boundary before Phase 9's external-infrastructure steps.
-
----
-
-## Phase 9 — Final verification
-
-- [x] `make agent-check && make agent-test` — full suite green. Ran at end of Phase 8 after the docs rewrite.
-- [x] `.venv/bin/pytest tests/integration/pipelex/temporal/ --temporal-server local` — against a real Temporal dev server (`temporal server start-dev` on `localhost:7233`). Two runs:
- - `tests/integration/pipelex/temporal/library_crate/ -m temporal --temporal-server local` → **63 passed, 2 xpassed** in 52.7s.
- - `tests/integration/pipelex/temporal/ -m temporal --temporal-server local --ignore=…/library_crate/` → **52 passed** in 36.4s.
- - Notable passes: `TestTprlContentGeneratorChild`, `TestTprlContentGeneratorPdfPageViews` (Phase 4 real-PDF), `TestSplitWorkerExtractPages` (Phase 7 Tier 11 cross-process two-activity dispatch), `TestSplitWorkerObjectGen` (Tier 9 nested-field round-trip), `TestSplitWorkerUsageEmission` (Tier 8 cross-worker usage emission), `TestPayloadCodecPipeline` (Phase 5 codec end-to-end). The 2 xpassed are the documented `pytest-xdist` flake for `TestWfPipeBatch` — passes in isolation.
-- [x] Manual smoke equivalent: Temporal history smoke against split workers (router + runner processes from `worker_cli --scope router|runner`). Submitted Tier 1 (`native_text_sequence`) and Tier 3 (`temporal_parallel.mthds`); inspected `temporal workflow list` + `temporal workflow show` outputs.
- - Workflow types observed across the namespace: **only `wf_pipe_run`, `wf_pipe_router`, `wf_test_content_generator_child`** — zero `wf_make_*` / `wf_render_page_views` types.
- - Tier 3 (PipeParallel) tree: 1 `wf_pipe_run` + 5 `wf_pipe_router` (orchestrator + 2 branch routers + 2 step routers). Activities (`act_flush_trace_events`, content-generation `act_*`) scheduled directly from `wf_pipe_router` via `workflow.execute_activity(...)` — no intermediate `wf_make_*` layer.
- - Real-activity dispatch evidence comes from the pytest tests above (dry-run `pipelex run bundle` uses `ContentGeneratorDry` inline so the activity-dispatch path is exercised by the integration tests, not the CLI smoke).
-- [x] Replay-history check: confirmed no test fixtures depend on old `WfMake*` history.
- - [x] `grep -rn "WfMake\|wf_make_\|WfRenderPageViews\|wf_render_page_views" tests/` returns nothing.
- - [x] `find tests/ \( -name "*.bin" -o -name "*history*" -o -name "*replay*" \) -type f` returns nothing — no binary or JSON replay fixtures exist in the tree.
- - [x] Recorded finding: no replay fixtures exist (matches v2 §6 prediction "Replay-history compatibility: none").
-
-> Deploy/ship operations are out of scope for this plan — handled separately when the branch is ready to land.
-
----
-
-## Verification matrix (quick reference)
-
-| After phase | Command |
-|---|---|
-| 0 | (no code changes — record finding in Decisions) |
-| 1 | `make agent-check` |
-| 2 | `make agent-check && make agent-test` (flag OFF and ON locally) |
-| 3 | `make agent-check && make agent-test` |
-| 4 | `make agent-check && make agent-test` |
-| 5 | `make agent-test`; `--temporal-server local`; manual UI inspection |
-| 6 | `make cleanderived && make agent-check && make agent-test && make tb` |
-| 7 | `make agent-check && make agent-test`; e2e skill Tiers 9-11 against `--temporal-server local` with split workers |
-| 8 | `make agent-check` |
-| 9 | full suite + real-server suite + manual smoke + replay-history check |
-
----
-
-## Where bugs are likely to hide (from v2 §6)
-
-- **Asymmetric `task_queue=worker_config.inference_task_queue` rule.** Easy to forget at the LLM-text site or to over-apply elsewhere. Covered by the unit test added in Phase 1 — including the negative assertion that non-LLM-text methods must NOT pass `task_queue=`. Mis-routing image-gen to the inference queue would break split-worker production where the runner doesn't register the image-gen activity. Note: this rule is *provisional* — Phase 7 isolates it to the `_inference_dispatch_kwargs` helper, and the proper general design (per-activity, per-handle routing covering LLM + image-gen + extract) is in `wip/temporal-primitives/per-activity-queue-routing-v1.md`.
-- **`activity_id` collisions** under repeated calls — see Phase 0. The default `wfid` values are method-specific constants; they do NOT disambiguate repeated calls to the same method. The Phase 1 runtime check (`dict[workflow_id, set[str]]` on the singleton generator, gated by `workflow.unsafe.is_replaying()`) converts this from a documented invariant to a checked one and is replay-safe (cache-eviction replays do not raise spurious duplicates).
-- **`model_validate(obj.model_dump(mode="json", serialize_as_any=True))` round-trips** for `make_object` / `make_object_list`. Required because the activity boundary returns a generic `BaseModel`. Don't drop these. **Use `mode="json"` on BOTH** — `ContentGeneratorChild.make_object_list:189` omits it today (pre-existing asymmetry vs. `make_object:148`).
-- **Page-views augmentation** in `make_extract_pages` (Phase 4). Mirror the direct generator's branching exactly: don't double-emit when `should_include_page_views` is false; handle both `document_uri` (multi-page render) and `image_uri` (single-image) inputs; assert length match. Both branches are covered by unit tests; the `document_uri` branch additionally has a real-PDF end-to-end integration test (`TestTprlContentGeneratorPdfPageViews`).
-- **Test infrastructure bypass.** Both `tests/integration/pipelex/temporal/conftest.py` and `test_payload_codec_pipeline.py` explicitly call `pipelex_hub.set_content_generator(...)` after `Pipelex.make()`, so the env-flag branch in `pipelex.py` is bypassed in tests. Phase 2 must mirror the env flag in both conftests; Phase 6 must update both as part of cleanup.
-
----
-
-## Follow-up TODOs (out of scope for this PR)
-
-- **Per-activity, per-handle Temporal queue routing.** Replace the provisional `inference_task_queue` binary model with a general routing system covering LLM, image-gen, and extract activities — keyed by `(activity_name, runtime_handle)`. Full design in [`wip/temporal-primitives/per-activity-queue-routing-v1.md`](wip/temporal-primitives/per-activity-queue-routing-v1.md). Enables per-provider and per-model worker pools. The Phase 7 stopgap helper (`_inference_dispatch_kwargs`) is the deletion point when this lands.
-- **Watch task-queue saturation post-deploy.** Today, a `PipeSequence` of N inference calls schedules N child workflows, decoupling activity scheduling across child task lists. Post-collapse, all N activities run through the parent's task list (or `inference_task_queue` for LLM-text). For deep pipelines (N > 50), single-queue QPS could spike. After the first production deploy after this lands, watch `ScheduleToStartLatency` on the parent worker queue and on `inference_task_queue`. If it rises, investigate batching or per-pipe queue assignment. Not blocking; upside (history-event reduction) dominates.
-- **Drop `make_render_page_views` from `ContentGeneratorProtocol`** if no operator caller emerges within one release cycle. Today it's only invoked internally from `make_extract_pages`; post-Phase-4 the same is true. The Protocol method becomes dead code from the operator side. Inline its behavior into `make_extract_pages` and remove from the Protocol + every implementation. Estimated savings: ~50 lines across four files.
-- **Fix `ContentGenerator.make_extract_pages` Protocol-violating signature.** `content_generator.py:259-267` declares `extract_job_params: ExtractJobParams | None = None` and `extract_job_config: ExtractJobConfig | None = None`, while the Protocol requires non-None. Tighten the signature to match the Protocol; default-construct at the operator boundary instead. Pre-existing divergence; project's "flag and fix" rule applies, but bundling into this refactor would expand the diff for marginal gain.
-- **Bound `_seen_activity_ids` growth in `ContentGeneratorInWorkflow`.** The dict is keyed by `workflow.info().workflow_id`, gated by `workflow.unsafe.is_replaying()` to be replay-safe, but never evicts entries. A long-running worker accumulates one entry per processed workflow id over its lifetime. Add eviction on workflow completion via a context manager hook, or move the set into workflow-local state (e.g., a contextvar set at the start of `WfPipeRouter.run` and cleared in `finally`). Cheap follow-up; not blocking Checkpoint A.
-- **Update v2 doc claim.** `wip/temporal-primitives/collapse-content-generation-workflow-layer-v2.md` §5 step 3 says image-gen path in `wf_test_content_generator_child.py:87-92` is commented out. It is not — the path is live. Doc-only fix.
diff --git a/wip/archive/collapse-content-generation-workflow-layer-v2.md b/wip/archive/collapse-content-generation-workflow-layer-v2.md
deleted file mode 100644
index ee31a9849..000000000
--- a/wip/archive/collapse-content-generation-workflow-layer-v2.md
+++ /dev/null
@@ -1,286 +0,0 @@
-# Analysis: Collapsing the `tprl_content_generation/` Workflow Layer (v2)
-
-> **What changed since v1.** The "text-then-object" structuring path was removed end-to-end (commit `16b775b8`): `WfMakeTextThenObject` / `WfMakeTextThenObjectList` are gone, `LLMAssignmentFactory` and `TextThenObjectAssignment` are gone, `make_text_then_object` / `make_text_then_object_list` are gone from `ContentGeneratorProtocol` and all four implementations, `make_object_direct` was renamed to `make_object`, and `make_object_list_direct` was renamed to `make_object_list`. The `StructuringMethod.PRELIMINARY_TEXT` enum value still exists but `PipeLLM` raises `NotImplementedError` if it's selected.
->
-> **Net effect on this refactor.** The single nontrivial case in the v1 plan — the two-activity glue inside `WfMakeTextThenObject` — is gone. Every surviving `WfMake*` workflow is now a structurally identical single-activity wrapper. The collapse is now pure boilerplate deletion.
-
----
-
-## 0. The shape of what's left
-
-After the text-then-object removal, the seven surviving workflow types in `pipelex/temporal/tprl_content_generation/` are all the same shape:
-
-```python
[email protected](name="wf_…")
-class WfMakeXxx(WorkflowClass[XxxAssignment, ResultType]):
- @workflow.run
- async def run(self, workflow_arg: XxxAssignment) -> ResultType:
- worker_config = get_config().temporal.worker_config
- try:
- result = await workflow.start_activity(
- activity=act_xxx,
- arg=workflow_arg,
- start_to_close_timeout=worker_config.workflow_execution_timeout,
- retry_policy=worker_config.retry_policy,
- # task_queue=worker_config.inference_task_queue ← LLM-text only
- )
- except ActivityError as exc:
- if isinstance(exc.cause, ApplicationError):
- raise TemporalError.from_app_error(exc=exc.cause) from exc
- raise
- return result
-```
-
-Concretely, with line refs to the current code:
-
-| Workflow | File | Activity | Special routing |
-|---|---|---|---|
-| `WfMakeLLMText` | `wf_make_llm_text.py:14-37` | `act_llm_gen_text` | `task_queue=inference_task_queue` |
-| `WfMakeObject` | `wf_make_object.py:19-42` | `act_llm_gen_object` | — |
-| `WfMakeObjectList` | `wf_make_object.py:45-68` | `act_llm_gen_object_list` | — |
-| `WfMakeImages` | `wf_make_images.py:16-40` | `act_img_gen_images` | — |
-| `WfMakeJinja2Text` | `wf_make_jinja2_text.py:18-40` | `act_jinja2_gen_text` | — |
-| `WfMakeExtract` | `wf_make_extract.py:16-40` | `act_extract_gen_extract_pages` | — |
-| `WfRenderPageViews` | `wf_render_page_views.py:16-40` | `act_render_page_views` | — |
-
-There is no remaining workflow body that does anything between activities. Every workflow is `1 activity = 1 result`.
-
----
-
-## 1. Concrete file-level inventory
-
-### Delete
-
-All under `pipelex/temporal/tprl_content_generation/`:
-
-- `wf_make_llm_text.py` — `WfMakeLLMText`.
-- `wf_make_object.py` — `WfMakeObject`, `WfMakeObjectList` (down from four classes in v1; `WfMakeTextThenObject*` already gone).
-- `wf_make_images.py` — `WfMakeImages`.
-- `wf_make_jinja2_text.py` — `WfMakeJinja2Text`.
-- `wf_make_extract.py` — `WfMakeExtract`.
-- `wf_render_page_views.py` — `WfRenderPageViews`.
-- `content_generator_top.py` — `ContentGeneratorTop` (`content_generator_top.py:44-347`). Used only in tests; dispatches `WfMake*` from the submitter side and is meaningless once those workflows are gone.
-- `content_generator_top_factory.py` — its only producer.
-- `content_generator_child.py` — `ContentGeneratorChild` (`content_generator_child.py:65-422`). Each method dispatches a `WfMake*` via `WorkflowExecutorFactory[…].execute_child_workflow(…)`.
-- `content_generator_child_factory.py` — its only producer.
-- `content_generator_models.py` — `AssignmentType` / `ResultType` unions, only consumed by the two generators above.
-
-### Stays unchanged
-
-- All seven inference activities — `act_llm_gen_text`, `act_llm_gen_object`, `act_llm_gen_object_list`, `act_img_gen_images`, `act_jinja2_gen_text`, `act_extract_gen_extract_pages`, `act_render_page_views`. The activity bodies have not changed.
-- The `ContentGeneratorProtocol` interface (`pipelex/cogt/content_generation/content_generator_protocol.py:45-135`) and the direct-mode `ContentGenerator` (`pipelex/cogt/content_generation/content_generator.py:37-301`) — both untouched. The protocol surface is now nine methods (it had eleven before the text-then-object removal).
-- `WfPipeRun`, `WfPipeRouter`, `TemporalPipeRouter`, `TemporalPipeRun`, all `act_*` activities under `tprl_pipe/`, and the `tprl/` directory of helpers.
-- The pipe operators: `pipelex/pipe_operators/llm/pipe_llm.py`, `pipe_img_gen.py`, `pipe_extract.py`, `pipe_compose.py`, `structured_content_composer.py`. After the text-then-object removal, `PipeLLM._llm_gen_object_stuff_content` (`pipe_llm.py:354-405`) is now a clean 2-way split (single vs list); it consumes `make_object` / `make_object_list` / `make_llm_text` from whichever generator is registered.
-- `with_conditional_worker` (`pipelex/temporal/tprl/conditional_worker.py:14-41`). The decorator is still used by `TemporalPipeRouter._run_pipe_job` (`temporal_pipe_router.py:47`) and `TemporalPipeRun.run` / `.start` (`temporal_pipe_run.py:42, 72`) for `INTERNAL` worker mode in the test suite. It just stops being applied to `ContentGeneratorTop` (which is being deleted). The file itself stays.
-- `WorkflowExecutor.execute_child_workflow` / `start_child_workflow` (`pipelex/temporal/tprl/workflow_caller.py:150-216`). After the refactor they are still used by `TemporalPipeRouter` for `WfPipeRouter` child dispatch (`temporal_pipe_router.py:62-67`).
-
-### Modify
-
-- `pipelex/temporal/tasks.py:30-49` — drop the seven `WfMake*` / `WfRenderPageViews` entries from the `crafting` `TaskPack`'s `workflow_list`. The `activity_list` (the seven `act_*` functions) is unchanged; the `pipe` `TaskPack` is unchanged.
-
-- `pipelex/pipelex.py:338-351` — the runtime branch that builds a `ContentGeneratorChild` when `temporal.is_enabled` (`pipelex.py:341-347`) needs to construct a new in-workflow generator instead. See §2 *Direct-mode* for why every method must hop through an activity rather than calling the direct `ContentGenerator` inline (the split-worker deployment requires it).
-
-- `pipelex/temporal/test_extras/wf_test_content_generator_child.py:43-114` — `WfTestContentGeneratorChild` constructs a `ContentGeneratorChildFactory.make_content_generator_child(…)` inside the workflow body (`wf_test_content_generator_child.py:53-55`). Replace with construction of the new in-workflow generator. The test workflow itself — and its registration in `pipelex/temporal/test_extras/temporal_test_tasks.py:5` — stay.
-
-- Tests under `tests/integration/pipelex/temporal/content_generation/`:
- - `conftest.py:46-73` — both fixtures `top_crafter` and `child_crafter` go away. The `top_crafter` fixture wires `ContentGeneratorTopFactory.make_content_generator_top(…)` for tests in the (deleted) top suite; the `child_crafter` fixture wires `ContentGeneratorChildFactory.make_content_generator_child(…)` directly (it works today because the construction itself is async-safe outside a workflow — only the *call sites* hard-fail outside a workflow). Both can be replaced with a single fixture that builds the new in-workflow generator if any direct-construction tests are kept; otherwise just delete both.
- - `test_tprl_content_generator_top.py` (whole file, `test_tprl_content_generator_top.py:45-185`) — delete. This file tests `ContentGeneratorTop` end-to-end (seven methods including `make_object`, `make_object_list`, image, jinja2, extract, error-path); the same scenarios are covered in-workflow by `WfTestContentGeneratorChild` (`test_extras/wf_test_content_generator_child.py:43-114`) via `test_tprl_content_generator_child.py` and `test_wf_child_crafter.py`. Note: there is also `test_tprl_make_llm_text_with_error` at `:144-184` which validates that bad `LLMSetting.model` fails through the `WorkflowFailureError` envelope — keep an equivalent assertion in the new in-workflow test (or in a small unit test that mocks `workflow.execute_activity` to raise `ActivityError(ApplicationError(...))`).
- - `test_tprl_content_generator_child.py` (`test_tprl_content_generator_child.py:18-33`) — keep; `WfTestContentGeneratorChild` is re-pointed in step 3.
- - `test_tprl_make_content_generator.py:9-20` — references both `ContentGeneratorTopFactory` and `ContentGeneratorChildFactory`; deleted alongside the factories.
-
-- `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py:77-89` — the `configure_inference_task_queue` fixture mutates `worker_config.inference_task_queue` so that `WfMakeLLMText.start_activity(…, task_queue=worker_config.inference_task_queue, …)` (`wf_make_llm_text.py:30`) routes to the runner queue. After the refactor, the same `task_queue=worker_config.inference_task_queue` argument is read at the new in-workflow `workflow.execute_activity(act_llm_gen_text, …)` call site. The test logic is unchanged. The docstring and the comment at `test_split_worker_usage.py:1-9, 60-68, 78-83` reference `WfMakeLLMText` by name and need a small rewrite.
-
-- `tests/integration/pipelex/temporal/tracing/helpers.py:179-231` — references `WfMakeLLMText` in docstrings; rewrite to describe the direct-activity-call topology.
-
-- `tests/integration/pipelex/temporal/workflows/test_wf_gen_text.py` and `test_wf_jinja2.py` — already commented-out historical tests that referenced `WfMakeLLMText` / `WfMakeJinja2Text` (`test_wf_gen_text.py:1-60` is entirely commented). Delete the files outright.
-
-- `tests/integration/pipelex/temporal/workflows/test_wf_child_crafter.py:17-32` — runs `WfTestContentGeneratorChild`; keep, contingent on the rewrite of `WfTestContentGeneratorChild`.
-
-- `docs/under-the-hood/pipe-routing-and-execution.md:232` and any nearby table entries that reference `wf_make_object` / `wf_make_llm_text` etc. as workflow types — update to describe direct activity dispatch.
-
----
-
-## 2. Behavioral diff
-
-### Temporal history shape per content-generation call
-
-Today, a single `make_llm_text` from inside `WfPipeRouter` produces this scheduling chain in the parent's history:
-
-- `StartChildWorkflowExecutionInitiated` → `ChildWorkflowExecutionStarted` (for `WfMakeLLMText`)
-- `ChildWorkflowExecutionCompleted` (or `Failed`)
-
-…and the `WfMakeLLMText` child's own history adds `WorkflowExecutionStarted` + workflow-task framing + `ActivityTaskScheduled` → `ActivityTaskStarted` → `ActivityTaskCompleted` (or `Failed`) + workflow-task framing + `WorkflowExecutionCompleted` — about a dozen events for a single LLM call.
-
-After the collapse, the same call inside the parent is just:
-
-- `ActivityTaskScheduled` → `ActivityTaskStarted` → `ActivityTaskCompleted` (or `Failed`)
-
-…three events, in the parent's history, no child workflow.
-
-A long `PipeSequence` of N LLM steps therefore goes from "N child-workflow scheduling pairs in parent + N small child histories" to "N activity scheduling pairs in parent". Per-LLM-call durability is preserved — the activity boundary is unchanged.
-
-> **What v1 said about `make_text_then_object` no longer applies.** v1 noted that the same reduction applied to two-activity workflows (`WfMakeTextThenObject*`) — those don't exist anymore. There is no surviving multi-activity workflow in `tprl_content_generation/`.
-
-### Worker registration
-
-`pipelex/temporal/tasks.py:30-49`: `crafting` `TaskPack`'s `workflow_list` shrinks from seven workflow types to zero. The `activity_list` is unchanged. `pipe` `TaskPack` is unchanged.
-
-The `worker_scopes` config in `pipelex/pipelex.toml` ("full", "router", "runner") is by reference: it requires the `crafting` and `pipe` packs by *name*, so the scope definitions don't need to change. The bare `router` scope (`disable_all_activities=true`) registers seven fewer workflows; the `runner` scope (`disable_all_workflows=true`) is unaffected.
-
-### Retry semantics
-
-Every `WfMake*` constructs its `start_activity(…)` with `retry_policy=worker_config.retry_policy` (`wf_make_llm_text.py:29`, identical at every parallel site). That's a single global default; the per-workflow retry knob in `WorkflowExecutorFactory.create_executor(…)` (`workflow_caller.py:219-248`) is plumbed through but `ContentGeneratorChildFactory` only passes the config default (`content_generator_child_factory.py:29`). So in practice every content-gen activity already runs under the same `worker_config.retry_policy_config`.
-
-After the collapse, the new in-workflow generator passes `retry_policy=get_config().temporal.worker_config.retry_policy` at every `workflow.execute_activity(…)` call site. Identical semantics. The non-retryable error list in `pipelex/pipelex.toml` survives untouched — it's part of `worker_config.retry_policy`.
-
-### Per-call timeouts and task-queue routing
-
-The current `WfMake*` workflows pin both `start_to_close_timeout=worker_config.workflow_execution_timeout` and (LLM-text only, `wf_make_llm_text.py:30`) `task_queue=worker_config.inference_task_queue`. Today's de-facto routing rule is:
-
-- LLM-text completions → `inference_task_queue` (when set)
-- Object-mode LLM, image gen, extract, render-page-views, templating → workflow's own queue
-
-After the collapse, the new in-workflow generator re-applies the same rule at each call site: `task_queue=worker_config.inference_task_queue` only on `act_llm_gen_text`. This preserves `test_split_worker_usage.py:77-89`. Production deployment topology is unchanged.
-
-The `WfMake*` workflows' `workflow_execution_timeout` argument (passed at child dispatch from `ContentGeneratorChild` via `WorkflowExecutor.execute_child_workflow`, `workflow_caller.py:167`) disappears. The activity-level `start_to_close_timeout` already plays the equivalent role; both come from `worker_config.workflow_execution_timeout`, so collapsing to just the activity timeout is a no-op for happy-path execution and slightly tighter on the failure path.
-
-### Direct-mode (non-Temporal) execution
-
-`pipelex/pipelex.py:338-351`: when `temporal.is_enabled` is false, the direct, non-Temporal `ContentGenerator` is registered. Unchanged.
-
-The `ContentGeneratorChild` branch (`pipelex.py:341-347`) is reached when `temporal.is_enabled` is true. In production, `get_content_generator()` is called from inside `WfPipeRouter` (via the operator's `pipe_llm.py` etc.), so the registered child generator is always invoked from a workflow context. There is no production code path that calls `ContentGeneratorChild`'s methods at top-level outside of a workflow — its method bodies use `workflow.execute_child_workflow`, which hard-fails outside a workflow. So the *existing* contract is "this generator only works inside a workflow."
-
-After the collapse, the new in-workflow generator's contract is the same: each method calls `workflow.execute_activity(…)`, which also hard-fails outside a workflow. Direct-mode is unaffected because direct-mode never gets this generator wired in.
-
-### Dry-run path
-
-In dry mode, `ContentGeneratorDry` is registered at `pipelex.py:339-340`. `temporal.is_enabled` is gated *after* the dry check, so dry-mode does not depend on the temporal generator. The collapse does not touch this. `WfTestContentGeneratorChild` (`wf_test_content_generator_child.py:46-55`) switches between `ContentGeneratorDry` and (post-refactor) the new in-workflow generator based on its `is_dry_run` arg — same shape as today.
-
-### Routing of nested controller calls
-
-`TemporalPipeRouter._run_pipe_job` (`temporal_pipe_router.py:46-91`) is unchanged. `PipeController` sub-pipes still dispatch as `WfPipeRouter` child workflows. The collapse only affects what happens *inside* the leaf `WfPipeRouter` when its pipe is a `PipeOperator`.
-
----
-
-## 3. Pros vs. current code
-
-- **History-event reduction.** Each LLM/img/extract/jinja2/render call inside a `WfPipeRouter` drops from "child workflow + activity" (≈12 events including child-workflow framing) to "activity only" (3 events). On a deep `PipeSequence` this is the dominant factor in approaching the 10K-event soft limit. Per-LLM-call durability is preserved because the activity boundary is unchanged.
-
-- **One fewer indirection in the Temporal UI.** Today: `WfPipeRouter` → `WfMakeLLMText` → `act_llm_gen_text` (three execution levels). After: `WfPipeRouter` → `act_llm_gen_text`. The activity is one level below the controller it belongs to, which matches the actual semantics.
-
-- **Less code to maintain.** Two near-duplicate generator implementations (`ContentGeneratorTop` + `ContentGeneratorChild`, ≈770 lines combined) — the only real difference is `execute_workflow` versus `execute_child_workflow` — collapse into one in-workflow generator (estimated ≈300 lines, one method per activity).
-
-- **No new abstractions required.** The activities, the `act_*` functions, the `crafting` pack registration — all already exist and stay in place. The refactor is largely deletion.
-
-- **Eliminates a dual-source-of-truth for retry / timeout / task_queue config.** Today some knobs are on the `WfMake*` workflow's `start_activity(…)` (`wf_make_llm_text.py:25-31`), some are on `ContentGeneratorChildFactory` plumbing (`content_generator_child_factory.py:13-34`), and `test_split_worker_usage.py:77-89` mutates `worker_config.inference_task_queue` and *trusts* `WfMakeLLMText` to read it on every child-workflow invocation. After collapsing, all those knobs apply at the single `workflow.execute_activity(…)` call site.
-
-- **Workflows are now structurally identical.** This is the main difference vs. v1's pros list. With `WfMakeTextThenObject*` gone, every surviving `WfMake*` is the same template (see §0). Deleting seven copies of the same five-line wrapper is a strict simplification — no logic is being relocated, just moved one frame up the stack.
-
----
-
-## 4. Cons / risks vs. current code
-
-- **Loss of distinct workflow IDs per content-generation call in the Temporal UI.** `ContentGeneratorChild.make_llm_text` builds `child_workflow_id` from the parent's id + `wfid` (`content_generator_child.py:48-62, 95`). Operators and tests pass `wfid=` to give a Temporal-UI-visible name to a specific content-generation step. After the collapse, the activity has no comparable user-controllable "ID" surface — only `activity_id`, auto-assigned by the SDK. Per-step naming is lost in the Temporal UI; observability falls back to activity logs, the `act_*` function name, and the `JobMetadata.content_generation_job_id` field that `update_job_metadata` already stamps (`content_generator_protocol.py:25-42`). This is the most concrete observability regression.
-
-- **Loss of the per-content-generation `workflow_execution_timeout`.** Each `WfMake*` carries its own `execution_timeout` today (derived from `worker_config.workflow_execution_timeout`, but a future per-call override is on the table). After the collapse there is only the activity's `start_to_close_timeout`. In practice this is the same value, so no regression today — but you've lost a future axis of independent control.
-
-- **Determinism implications — smaller surface than v1 estimated.** Today the `wf_make_*` workflow body is a thin layer (just `start_activity` + error translation). All calls run inside `WfPipeRouter`'s sandbox already, since `pipe.run_pipe(…)` reaches operator code that calls `get_content_generator()` and dispatches via `ContentGeneratorChild`'s methods. The construction of `LLMAssignment` / `ObjectAssignment` / `TemplatingAssignment` / `ImgGenAssignment` / `ExtractAssignment` / `RenderPageViewsAssignment` Pydantic models, plus `ObjectAssignment.make_for_class(...)`, plus the `model_validate(obj.model_dump(serialize_as_any=True))` re-validation at `content_generator_child.py:148, 189`, plus `make_child_workflow_id(…)` — all already run inside `WfPipeRouter`'s sandboxed code today. The new line is just `workflow.execute_activity(…)` replacing `WorkflowExecutorFactory[…].create_executor().execute_child_workflow(…)`. Both are deterministic Temporal SDK calls.
-
- **Why this is smaller than v1.** v1 flagged `LLMAssignmentFactory.make_llm_assignment(preliminary_text=…)` running between two activities inside the workflow sandbox as the riskiest piece of glue. That code is gone. There is no longer any inter-activity glue that needs to run inside the new in-workflow generator. The whole determinism-risk paragraph reduces to "make sure no new non-passing-through import sneaks in" — which `make tb` and the `library_crate` integration suite catch cheaply.
-
-- **Default activity worker / asymmetric task_queue routing.** Today, only `WfMakeLLMText` passes `task_queue=worker_config.inference_task_queue` (`wf_make_llm_text.py:30`). The other six wrappers don't pass `task_queue`, so their activities run on the workflow's task queue. The new generator must replicate this exactly. Easy to mis-handle if a reviewer thinks "we should route everything to inference_task_queue" — that would break the `crafting` pack registration on the runner workers (which today register the LLM activity on the inference queue and the others on the default queue).
-
- *Mitigation:* a comment at the LLM-text site explicitly stating the asymmetric routing rule, plus a small unit test that mocks `workflow.execute_activity` and asserts the `task_queue=` kwarg per method.
-
-- **Pre-existing behavioral divergence to flag-and-fix.** `ContentGenerator.make_extract_pages` (`content_generator.py:259-300`) augments its return with `make_render_page_views(…)` when `extract_job_params.should_include_page_views` is true (or sets a single-image page view when `extract_input.image_uri` is set). The Temporal-mode `ContentGeneratorChild.make_extract_pages` (`content_generator_child.py:386-422`) does not — it just dispatches `WfMakeExtract` and returns the page contents as-is, missing both augmentations. The collapse is the right moment to fix this asymmetry: the new in-workflow generator can mirror `ContentGenerator.make_extract_pages` exactly, dispatching `act_extract_gen_extract_pages` and (when needed) `act_render_page_views` as two separate activity calls, then attaching page views to the page contents in-workflow. This is in scope per the project's "flag and fix existing bugs" principle.
-
-- **Tests that depend on the current workflow topology.** Same cluster as v1, slightly smaller now:
- - `test_tprl_content_generator_top.py` (delete wholesale).
- - `test_tprl_make_content_generator.py` (delete wholesale).
- - `test_tprl_content_generator_child.py` (small touch — re-points).
- - `test_split_worker_usage.py` (test logic unchanged; docstrings stale).
- - `test_wf_gen_text.py` and `test_wf_jinja2.py` (already commented-out — delete the files).
- - `library_crate/` and `tracing/` suites — pass unchanged after the LLM-text site is correctly task-queue-routed.
-
- Replay tests, if any, that pickle a `WfMake*` history will break — none in the current tree.
-
-- **`with_conditional_worker` removal from the content-gen path.** This decorator (`pipelex/temporal/tprl/conditional_worker.py:14-41`) wraps every method on `ContentGeneratorTop` today. Post-refactor, `ContentGeneratorTop` is gone, so the wrap on those methods disappears. The decorator file remains because `TemporalPipeRouter` and `TemporalPipeRun` still use it. Net: fewer call sites, no behavioral change for the `INTERNAL`-mode test fixtures that drive `WfPipeRouter` / `WfPipeRun`.
-
----
-
-## 5. Refactoring plan
-
-The ordering preserves direct-mode parity at every step (direct-mode never depends on the temporal content-generation classes) and keeps Temporal mode green at every checkpoint. Each numbered step ends with `make agent-check && make agent-test` (or, during local dev, the `tests/integration/pipelex/temporal/` subset).
-
-1. **Add the new in-workflow content generator.** Create `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py`. Implement `ContentGeneratorInWorkflow` (or pick a better name) with the same `ContentGeneratorProtocol` surface — nine methods now that text-then-object is gone — and method bodies that call `workflow.execute_activity(act_*, arg=..., start_to_close_timeout=worker_config.workflow_execution_timeout, retry_policy=worker_config.retry_policy [, task_queue=worker_config.inference_task_queue for LLM-text only])`. Wrap with `try/except ActivityError` to translate `ApplicationError → TemporalError.from_app_error(...)`, mirroring what each `wf_make_*.py` does today (`wf_make_llm_text.py:32-35` and parallels). Add a factory.
-
- No wiring yet. Run `make agent-check`.
-
-2. **Wire the new generator behind a temporary feature flag.** Add a transient boolean in `pipelex/pipelex.py:338-351` (env-flag-gated, *not* in `pipelex.toml`) that picks the new generator instead of `ContentGeneratorChild` when `temporal.is_enabled`. Default: still `ContentGeneratorChild`. Flip the flag locally and run `tests/integration/pipelex/temporal/library_crate/` and `tracing/`; assert green.
-
-3. **Re-point `WfTestContentGeneratorChild`.** Update `pipelex/temporal/test_extras/wf_test_content_generator_child.py:53-55` to construct the new in-workflow generator. This validates a full `make_llm_text` / `make_object` / `make_object_list` / `make_templated_text` / `make_extract_pages` round-trip via `test_wf_child_crafter.py:17-32` and `test_tprl_content_generator_child.py:18-33`. (Image-gen path is currently commented out at `wf_test_content_generator_child.py:87-92`; consider re-enabling it now that the page-views augmentation is being addressed in step 4 — an in-workflow `make_single_image` exercise here would cover img-gen via the new generator.)
-
-4. **Migrate the `make_extract_pages` page-views augmentation.** While writing the new generator, mirror `ContentGenerator.make_extract_pages`'s `should_include_page_views` branch: dispatch `act_extract_gen_extract_pages`, then if `extract_input.document_uri` is set and `should_include_page_views` is true call `act_render_page_views` as a second activity, else if `extract_input.image_uri` is set construct a single-image page-view list inline. Attach to `page_contents` in-workflow. Fixes the pre-existing divergence noted in §4.
-
-5. **Flip the default.** Once §3 is green, swap the feature flag default so the new generator is the production path. Run `make agent-test`.
-
-6. **Delete the old surface.** All in one commit, per the project's "no backward compatibility" rule:
- - Files listed under §1 *Delete*.
- - Imports in `pipelex/temporal/tasks.py` (drop `WfMake*` and `WfRenderPageViews` from `crafting.workflow_list`; drop the `wf_make_*` import lines).
- - The feature flag added in step 2.
- - `tests/integration/pipelex/temporal/content_generation/test_tprl_content_generator_top.py` (whole file).
- - `tests/integration/pipelex/temporal/content_generation/test_tprl_make_content_generator.py` (whole file).
- - `tests/integration/pipelex/temporal/workflows/test_wf_gen_text.py` and `test_wf_jinja2.py` (whole files — already commented-out).
- - The `top_crafter` and `child_crafter` fixtures + their imports in `conftest.py:18-20, 46-73`.
-
-7. **Update docstrings and docs.**
- - `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py:1-9, 60-68, 78-83` references `WfMakeLLMText` by name; rewrite for the direct-activity-call topology.
- - `tests/integration/pipelex/temporal/tracing/helpers.py:179-231` — same.
- - `docs/under-the-hood/pipe-routing-and-execution.md:232` — update the "workflow → activity" table to describe direct activity dispatch.
-
-8. **No `patched()` calls if the deploy is hard-cut.** Per project rule, there is no backward-compat transition. The constraint is that no in-flight Pipelex workflows may be running during the deploy. If that constraint cannot be enforced operationally, `workflow.patched("collapse-content-generation-layer")` would be needed at every `make_*` call site in the new generator, with a fallback that dispatches the legacy `WfMake*`. Recommendation: enforce drain-before-deploy and skip `patched()`.
-
----
-
-## 6. Size estimate
-
-- **Files deleted:** seven workflow files (`wf_make_llm_text.py`, `wf_make_object.py`, `wf_make_images.py`, `wf_make_jinja2_text.py`, `wf_make_extract.py`, `wf_render_page_views.py`), four generator/factory files (`content_generator_top.py`, `content_generator_top_factory.py`, `content_generator_child.py`, `content_generator_child_factory.py`), one models file (`content_generator_models.py`), and four test files (`test_tprl_content_generator_top.py`, `test_tprl_make_content_generator.py`, `test_wf_gen_text.py`, `test_wf_jinja2.py`).
-- **Files created:** one (`content_generator_in_workflow.py`).
-- **Files modified:** `pipelex/temporal/tasks.py`, `pipelex/pipelex.py`, `pipelex/temporal/test_extras/wf_test_content_generator_child.py`, `tests/integration/pipelex/temporal/content_generation/conftest.py`, `tests/integration/pipelex/temporal/content_generation/test_tprl_content_generator_child.py`, `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py` (docstring/comments only), `tests/integration/pipelex/temporal/tracing/helpers.py` (docstring only), `docs/under-the-hood/pipe-routing-and-execution.md` (table only).
-- **Effort:** smaller than v1 estimated. The change at each call site is replacing a `WorkflowExecutorFactory[…].execute_child_workflow(WfMakeXxx, …)` with `workflow.execute_activity(act_xxx, …)`. There is no longer any inter-activity glue to relocate. Budget: a focused half-day for code, plus a half-day for the test-fixture migration and feature-flag flip.
-- **Where bugs are likely to hide:**
- - The asymmetric `task_queue=worker_config.inference_task_queue` rule — easy to forget on the LLM-text site or to over-apply elsewhere. Add an explicit unit test that mocks `workflow.execute_activity` and asserts the `task_queue=` kwarg per method.
- - The `model_validate(obj.model_dump(mode="json", serialize_as_any=True))` round-trips at `content_generator_child.py:148, 189`. These are needed because the activity boundary returns a generic `BaseModel` (`act_llm_gen_object` is typed `-> BaseModel` at `act_llm_generate.py:16`). The new generator must keep these round-trips at the same place; otherwise structured-output validation regresses. The temporal data converter handles `BaseModel` inheritance via `kajson` already (`pipelex/temporal/temporal_data_converter.py`), but `model_validate` against the *concrete* class is what guarantees the output type expected by callers.
- - The page-views augmentation in `make_extract_pages` (today missing in Temporal mode, fixed during the refactor). Mirror the direct generator's branching exactly: don't double-emit when `should_include_page_views` is false; handle both `document_uri` (multi-page render) and `image_uri` (single-image) inputs.
-- **Replay-history compatibility:** none. Any workflow mid-flight at deploy time that references `WfMakeLLMText` etc. in its history will fail to replay. Drain or fail-fast all in-flight Pipelex workflows before deploy.
-
----
-
-## 7. Recommendation
-
-**Yes — and the case is strictly stronger than in v1.**
-
-The text-then-object removal eliminated the only nontrivial workflow in `tprl_content_generation/`. The remaining seven `WfMake*` are now structurally identical thin wrappers (§0). The collapse becomes pure boilerplate deletion:
-
-- **History-event reduction is unchanged:** ≈12 → 3 events per content-generation call.
-- **Per-LLM-call durability is preserved:** the activity boundary is unchanged.
-- **The single subtle-glue risk v1 flagged is gone.** v1's §6 "where bugs are likely to hide" listed `LLMAssignmentFactory.make_llm_assignment(preliminary_text=…)` running between two activities inside the workflow sandbox as the highest-risk piece. There is no longer any inter-activity glue.
-- **The deletion is concentrated and mechanical.** Eleven files in one directory plus four test files; one new generator file with nine method bodies that each look almost identical.
-
-**Open question for implementation, not before:** the "loss of distinct workflow IDs per content-generation call in the Temporal UI" cost in §4. If ops rely on those IDs as breadcrumbs today, decide between (a) setting `activity_id=` explicitly via the SDK overrides to reproduce the `wfid`-based naming, or (b) accepting logs + `JobMetadata.content_generation_job_id` as sufficient. Independent of the rest of the refactor.
-
-**Ordering vs. other open work.** Do this on a dev branch when the temporal integration tests are otherwise green. It's not worth coupling with a release. If a Temporal-related feature is in flight (payload codec, `ClassRegistry` propagation), defer until after — the refactor is purely subtractive and gains nothing by being interleaved.
-
----
-
-## 8. What changed vs. v1 (summary)
-
-| Aspect | v1 | v2 |
-|---|---|---|
-| Workflows to delete | 9 (incl. `WfMakeTextThenObject`, `WfMakeTextThenObjectList`) | 7 |
-| Protocol methods to migrate | 11 | 9 |
-| Non-trivial workflow body | `WfMakeTextThenObject*` (two activities + `LLMAssignmentFactory` glue) | None |
-| `ObjectAssignment` factory wired through `LLMAssignmentFactory.make_llm_assignment_for_class(...)` | Yes | Replaced by direct `ObjectAssignment.make_for_class(...)` calls (already done) |
-| Determinism-risk surface in §4 | "Verify `LLMAssignmentFactory.make_llm_assignment` is sandbox-safe" | Empty (no inter-activity glue) |
-| Effort estimate | "focused day for code + day for tests" | "half-day for code + half-day for tests" |
-| Other items (history reduction, retry, task-queue, `make_extract_pages` divergence, observability) | Same | Same |
diff --git a/wip/archive/collapse-content-generation-workflow-layer.html b/wip/archive/collapse-content-generation-workflow-layer.html
deleted file mode 100644
index 8c593aec4..000000000
--- a/wip/archive/collapse-content-generation-workflow-layer.html
+++ /dev/null
@@ -1,651 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<title>Collapsing the tprl_content_generation workflow layer</title>
-<style>
- :root {
- --fg: #1f2328;
- --muted: #57606a;
- --border: #d0d7de;
- --bg-soft: #f6f8fa;
- --bg-info: #ddf4ff;
- --bg-warn: #fff8c5;
- --bg-ok: #dafbe1;
- --add-bg: #e6ffec;
- --add-fg: #1a7f37;
- --del-bg: #ffebe9;
- --del-fg: #cf222e;
- --accent: #0969da;
- --kept: #1a7f37;
- --gone: #cf222e;
- }
- * { box-sizing: border-box; }
- body {
- font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
- color: var(--fg);
- max-width: 1040px;
- margin: 2.5rem auto;
- padding: 0 1.5rem;
- line-height: 1.55;
- }
- h1 { font-size: 1.9rem; margin-bottom: 0.25rem; }
- h2 { font-size: 1.4rem; margin-top: 2.5rem; padding-bottom: 0.25rem; border-bottom: 1px solid var(--border); }
- h3 { font-size: 1.1rem; margin-top: 1.5rem; }
- p { margin: 0.6rem 0; }
- code { font-family: "SF Mono", Menlo, Consolas, monospace; font-size: 0.9em; background: var(--bg-soft); padding: 0.1em 0.35em; border-radius: 4px; }
- pre { font-family: "SF Mono", Menlo, Consolas, monospace; font-size: 0.85em; background: var(--bg-soft); padding: 1rem 1.2rem; border-radius: 6px; overflow-x: auto; line-height: 1.45; }
- pre.diagram { background: #f6f8fa; border-left: 3px solid var(--accent); }
- .meta { color: var(--muted); font-size: 0.92rem; margin-top: 0; }
- .tldr {
- background: var(--bg-info);
- border-left: 4px solid var(--accent);
- padding: 0.9rem 1.2rem;
- border-radius: 0 6px 6px 0;
- margin: 1rem 0 2rem;
- }
- .tldr p { margin: 0.3rem 0; }
- .pill { display: inline-block; padding: 0.1em 0.6em; border-radius: 999px; font-size: 0.78em; font-weight: 600; }
- .pill-keep { background: #dafbe1; color: var(--kept); }
- .pill-drop { background: #ffebe9; color: var(--gone); }
- .pill-modify { background: #ddf4ff; color: var(--accent); }
- .pill-new { background: #fff8c5; color: #9a6700; }
- table { border-collapse: collapse; margin: 0.8rem 0; width: 100%; }
- th, td { padding: 0.55rem 0.85rem; text-align: left; border-bottom: 1px solid var(--border); vertical-align: top; }
- th { background: var(--bg-soft); font-weight: 600; }
- tr:last-child td { border-bottom: none; }
- /* unified diff */
- .diff { font-family: "SF Mono", Menlo, Consolas, monospace; font-size: 0.82em; background: #fff; border: 1px solid var(--border); border-radius: 6px; overflow: hidden; margin: 0.7rem 0; }
- .diff-header { background: var(--bg-soft); padding: 0.35rem 0.85rem; color: var(--muted); border-bottom: 1px solid var(--border); font-size: 0.85em; }
- .diff pre { margin: 0; background: transparent; padding: 0.5rem 0; border-radius: 0; }
- .diff .line { display: block; padding: 0 0.85rem; white-space: pre; }
- .diff .add { background: var(--add-bg); color: var(--add-fg); }
- .diff .del { background: var(--del-bg); color: var(--del-fg); }
- .diff .ctx { color: var(--fg); }
- .diff .hunk { color: var(--muted); background: var(--bg-soft); padding: 0.15em 0.85rem; }
- /* side-by-side */
- .side {
- display: grid;
- grid-template-columns: 1fr 1fr;
- gap: 1rem;
- margin: 0.8rem 0;
- }
- .side > div { background: var(--bg-soft); border-radius: 6px; padding: 0.9rem 1.1rem; }
- .side h4 { margin: 0 0 0.5rem; font-size: 0.92rem; color: var(--muted); text-transform: uppercase; letter-spacing: 0.04em; }
- .side pre { background: #fff; padding: 0.7rem 0.9rem; font-size: 0.82em; }
- .layer {
- border-left: 3px solid var(--border);
- padding: 0.4rem 0 0.4rem 1rem;
- margin: 0.6rem 0;
- }
- .layer.l1 { border-left-color: #0969da; }
- .layer.l2 { border-left-color: #1a7f37; }
- .layer.l3 { border-left-color: #d4a72c; }
- .layer.l4 { border-left-color: #bf3989; }
- .layer.l5 { border-left-color: #cf222e; }
- .layer h3 { margin-top: 0; }
- ul.tight { margin: 0.3rem 0 0.6rem 1.4rem; }
- ul.tight li { margin: 0.15rem 0; }
- details { margin: 0.5rem 0; }
- summary { cursor: pointer; font-weight: 600; color: var(--accent); }
- .stats {
- display: grid;
- grid-template-columns: repeat(4, 1fr);
- gap: 0.7rem;
- margin: 1rem 0;
- }
- .stat { background: var(--bg-soft); border-radius: 6px; padding: 0.7rem 0.9rem; text-align: center; }
- .stat .num { font-size: 1.6rem; font-weight: 700; color: var(--accent); display: block; }
- .stat .lbl { font-size: 0.8rem; color: var(--muted); }
- .note {
- background: var(--bg-warn);
- border-left: 4px solid #d4a72c;
- padding: 0.7rem 1rem;
- border-radius: 0 6px 6px 0;
- margin: 1rem 0;
- font-size: 0.93em;
- }
- .ok {
- background: var(--bg-ok);
- border-left: 4px solid var(--kept);
- padding: 0.7rem 1rem;
- border-radius: 0 6px 6px 0;
- margin: 1rem 0;
- font-size: 0.93em;
- }
- .gridcards {
- display: grid;
- grid-template-columns: repeat(2, 1fr);
- gap: 0.8rem;
- margin: 0.8rem 0;
- }
- .card { background: var(--bg-soft); border-radius: 6px; padding: 0.9rem 1.1rem; }
- .card h4 { margin: 0 0 0.4rem; font-size: 0.95rem; }
- .small { font-size: 0.85em; color: var(--muted); }
-</style>
-</head>
-<body>
-
-<header>
- <h1>Collapsing the <code>tprl_content_generation/</code> workflow layer</h1>
- <p class="meta">Branch <code>refactor/Temporal-primitives</code> · 9 phases, 2 checkpoints · companion to <code>collapse-content-generation-workflow-layer-v2.md</code></p>
-</header>
-
-<div class="tldr">
- <p><strong>What.</strong> Replaced seven near-identical <code>WfMake*</code> child workflows with direct <code>workflow.execute_activity(act_*, …)</code> calls inside <code>WfPipeRouter</code>. Deleted two near-duplicate generator implementations (<code>ContentGeneratorTop</code> + <code>ContentGeneratorChild</code>) and their factories, and a small assignment-types models file. Added one new in-workflow generator: <code>ContentGeneratorInWorkflow</code>.</p>
- <p><strong>Why.</strong> Every surviving <code>WfMake*</code> was a structurally identical 5-line wrapper around a single <code>start_activity(…)</code> call. The child-workflow indirection added ≈9 Temporal history events per content-generation call with zero behavioral payoff. On deep <code>PipeSequence</code>s this was the dominant factor approaching the 10K-event soft limit.</p>
- <p><strong>Impact.</strong> History events per content-generation call drop from <strong>≈12 → 3</strong>. Per-LLM-call durability is preserved — the activity boundary is unchanged. Retry policy, timeouts, and the asymmetric <code>inference_task_queue</code> routing rule are re-applied at the new dispatch site. Net deletion is concentrated and mechanical: 11 files gone, 1 file added.</p>
-</div>
-
-<div class="stats">
- <div class="stat"><span class="num">12 → 3</span><span class="lbl">history events / call</span></div>
- <div class="stat"><span class="num">−11</span><span class="lbl">files deleted</span></div>
- <div class="stat"><span class="num">+1</span><span class="lbl">file added</span></div>
- <div class="stat"><span class="num">9</span><span class="lbl">phases shipped</span></div>
-</div>
-
-<h2>1 — The shape of the problem (before)</h2>
-
-<p>When a <code>PipeLLM</code> operator inside <code>WfPipeRouter</code> needed to generate text, the call path went through three execution levels: router workflow, content-generation workflow, activity.</p>
-
-<pre class="diagram">
-WfPipeRouter (parent workflow)
- │
- ├─ pipe_llm._live_run_operator_pipe(...)
- │ └─ get_content_generator() ◄── returns ContentGeneratorChild
- │ └─ content_generator.make_llm_text(...)
- │ │
- │ ▼
- │ ContentGeneratorChild.make_llm_text(...)
- │ │
- │ └─ WorkflowExecutorFactory[...].execute_child_workflow(WfMakeLLMText, ...)
- │ │
- │ ▼
- │ ┌───────────────────────────────────────────────┐
- │ │ WfMakeLLMText (child workflow) │
- │ │ │
- │ │ workflow.start_activity( │
- │ │ activity=act_llm_gen_text, │
- │ │ arg=llm_assignment, │
- │ │ start_to_close_timeout=..., │
- │ │ retry_policy=..., │
- │ │ task_queue=inference_task_queue, ◄── LLM-text only
- │ │ ) │
- │ │ │
- │ │ try / except ActivityError → │
- │ │ TemporalError.from_app_error(...) │
- │ └───────────────────────────────────────────────┘
- │ │
- │ ▼
- │ act_llm_gen_text (activity)
- │ │
- └───── result ◄──────────┘
-</pre>
-
-<p>Every <code>WfMake*</code> workflow had the exact same shape:</p>
-
-<pre class="diagram">
[email protected](name="wf_…")
-class WfMakeXxx(WorkflowClass[XxxAssignment, ResultType]):
- @workflow.run
- async def run(self, workflow_arg: XxxAssignment) -> ResultType:
- worker_config = get_config().temporal.worker_config
- try:
- result = await workflow.start_activity(
- activity=act_xxx,
- arg=workflow_arg,
- start_to_close_timeout=worker_config.workflow_execution_timeout,
- retry_policy=worker_config.retry_policy,
- # task_queue=worker_config.inference_task_queue ← LLM-text only
- )
- except ActivityError as exc:
- if isinstance(exc.cause, ApplicationError):
- raise TemporalError.from_app_error(exc=exc.cause) from exc
- raise
- return result
-</pre>
-
-<p>Seven copies of the same template, one per content-generation activity:</p>
-
-<table>
- <thead><tr><th>Workflow</th><th>Activity</th><th>Special routing</th></tr></thead>
- <tbody>
- <tr><td><code>WfMakeLLMText</code></td><td><code>act_llm_gen_text</code></td><td><code>task_queue=inference_task_queue</code></td></tr>
- <tr><td><code>WfMakeObject</code></td><td><code>act_llm_gen_object</code></td><td>—</td></tr>
- <tr><td><code>WfMakeObjectList</code></td><td><code>act_llm_gen_object_list</code></td><td>—</td></tr>
- <tr><td><code>WfMakeImages</code></td><td><code>act_img_gen_images</code></td><td>—</td></tr>
- <tr><td><code>WfMakeJinja2Text</code></td><td><code>act_jinja2_gen_text</code></td><td>—</td></tr>
- <tr><td><code>WfMakeExtract</code></td><td><code>act_extract_gen_extract_pages</code></td><td>—</td></tr>
- <tr><td><code>WfRenderPageViews</code></td><td><code>act_render_page_views</code></td><td>—</td></tr>
- </tbody>
-</table>
-
-<p>There was no remaining workflow body that did anything between activities. The previous text-then-object stack — the one nontrivial case in the v1 plan — had already been removed in commit <code>16b775b8</code>. Every surviving <code>WfMake*</code> was just <code>1 activity = 1 result</code>.</p>
-
-<h2>2 — The Temporal history cost</h2>
-
-<p>A single <code>make_llm_text</code> from inside <code>WfPipeRouter</code> produced this event chain in the parent's history:</p>
-
-<pre class="diagram">
-[parent: WfPipeRouter]
- StartChildWorkflowExecutionInitiated
- ChildWorkflowExecutionStarted ◄── child framing
- ChildWorkflowExecutionCompleted/Failed
-
-[child: WfMakeLLMText]
- WorkflowExecutionStarted
- WorkflowTaskScheduled/Started/Completed
- ActivityTaskScheduled
- ActivityTaskStarted
- ActivityTaskCompleted/Failed
- WorkflowTaskScheduled/Started/Completed
- WorkflowExecutionCompleted
-
-≈ 12 events per LLM call
-</pre>
-
-<p>After the collapse, the same call inside the parent is just:</p>
-
-<pre class="diagram">
-[parent: WfPipeRouter]
- ActivityTaskScheduled
- ActivityTaskStarted
- ActivityTaskCompleted/Failed
-
-3 events per LLM call
-</pre>
-
-<p>For a long <code>PipeSequence</code> of N LLM steps, the history goes from "N child-workflow scheduling pairs in the parent + N small child histories" to "N activity scheduling pairs in the parent". <strong>Per-LLM-call durability is preserved</strong> — the activity boundary is unchanged, so the retry semantics and the durable-checkpoint guarantee on each LLM call are unaffected.</p>
-
-<h2>3 — The after picture</h2>
-
-<pre class="diagram">
-WfPipeRouter (parent workflow)
- │
- ├─ pipe_llm._live_run_operator_pipe(...)
- │ └─ get_content_generator() ◄── returns ContentGeneratorInWorkflow
- │ └─ content_generator.make_llm_text(...)
- │ │
- │ ▼
- │ ContentGeneratorInWorkflow.make_llm_text(...)
- │ │
- │ └─ workflow.execute_activity( ◄── one frame, not two
- │ act_llm_gen_text,
- │ llm_assignment,
- │ start_to_close_timeout=...,
- │ retry_policy=...,
- │ task_queue=inference_task_queue, ◄── LLM-text only
- │ activity_id=wfid, ◄── for Temporal UI
- │ )
- │
- └───── result
-</pre>
-
-<p>The activities themselves (<code>act_llm_gen_text</code>, <code>act_llm_gen_object</code>, …) are unchanged. The worker registration is unchanged (the seven <code>act_*</code> functions still live in the <code>crafting</code> <code>TaskPack</code>). The only thing that disappears is the layer between the router and the activity.</p>
-
-<h2>4 — Why this is a good trade</h2>
-
-<div class="gridcards">
- <div class="card">
- <h4>History-event reduction</h4>
- <p>≈12 → 3 events per content-generation call. On deep <code>PipeSequence</code>s this is the dominant factor approaching Temporal's 10K-event soft limit. The router's history stays compact.</p>
- </div>
- <div class="card">
- <h4>Durability preserved</h4>
- <p>The activity boundary is where retries and durable checkpoints live. We collapsed the workflow wrapper above it, not the activity below it. <code>retry_policy</code> and <code>start_to_close_timeout</code> are re-applied at the new dispatch site.</p>
- </div>
- <div class="card">
- <h4>Less code to maintain</h4>
- <p>Two near-duplicate generator implementations (<code>ContentGeneratorTop</code> + <code>ContentGeneratorChild</code>, ≈770 lines combined — the only real difference was <code>execute_workflow</code> vs <code>execute_child_workflow</code>) collapse into one in-workflow generator.</p>
- </div>
- <div class="card">
- <h4>One fewer indirection in the UI</h4>
- <p>Before: <code>WfPipeRouter → WfMakeLLMText → act_llm_gen_text</code>. After: <code>WfPipeRouter → act_llm_gen_text</code>. The activity now sits one level below the controller it belongs to — matching the actual semantics.</p>
- </div>
- <div class="card">
- <h4>One source of truth for dispatch config</h4>
- <p>Today's retry / timeout / task-queue knobs were spread across the <code>WfMake*</code> body, <code>ContentGeneratorChildFactory</code> plumbing, and a test that mutates <code>worker_config.inference_task_queue</code>. Post-collapse, all of it applies at the single <code>execute_activity(…)</code> call site.</p>
- </div>
- <div class="card">
- <h4>No new abstractions</h4>
- <p>The activities, the <code>act_*</code> functions, the <code>crafting</code> pack registration — all already existed. The refactor is largely deletion: 11 files out, 1 file in.</p>
- </div>
-</div>
-
-<h2>5 — Key design decisions</h2>
-
-<div class="layer l1">
- <h3>5.1 · Class name: <code>ContentGeneratorInWorkflow</code></h3>
- <p>The <code>InWorkflow</code> suffix flags a load-bearing constraint at every import site: <strong>this class only works when called from inside a workflow's <code>run()</code></strong>, because each method calls <code>workflow.execute_activity(…)</code>, which hard-fails outside a workflow context. The previous <code>ContentGeneratorChild</code> had the same constraint but the name didn't reflect it — easy to misuse from a test that tried to construct one and call its methods directly.</p>
-</div>
-
-<div class="layer l2">
- <h3>5.2 · <code>activity_id=</code> for Temporal UI observability</h3>
- <p>Today, <code>ContentGeneratorChild</code> builds a <code>child_workflow_id</code> from the parent's id plus a <code>wfid</code> kwarg (e.g. <code>"craft-text"</code>, <code>"craft-object-direct"</code>, <code>"extract"</code>). Operators and tests pass <code>wfid=</code> to give a Temporal-UI-visible name to a specific content-generation step. After the collapse, child workflow IDs are gone, but the <code>activity_id=</code> kwarg on <code>execute_activity</code> serves the same role — Temporal Web UI shows it as the per-step breadcrumb that ops use to triage failures.</p>
- <p>We thread <code>wfid</code> into <code>activity_id=</code> at every dispatch site. Default <code>wfid</code> values are method-specific constants (<code>"craft-text"</code>, <code>"craft-object-direct"</code>, <code>"craft-image-single"</code>, …), so the breadcrumb survives intact for ops triage.</p>
-</div>
-
-<div class="layer l3">
- <h3>5.3 · Activity-id uniqueness: Strategy (i)</h3>
- <p>Today's <code>WfMake*</code> child workflows get globally-unique IDs because <code>make_child_workflow_id</code> prepends the parent's workflow_id. After collapse, activity_ids only get the workflow's own scope — no parent prefix to fall back on. Temporal requires <code>activity_id</code>s to be unique within a workflow execution.</p>
- <p>A <strong>Phase 0 audit</strong> confirmed today's invariant: <em>at most one call per <code>ContentGeneratorProtocol</code> method per <code>WfPipeRouter</code> execution</em>. <code>PipeLLM._live_run_operator_pipe</code>'s branching ensures <code>make_llm_text</code> / <code>make_object</code> / <code>make_object_list</code> are mutually exclusive; <code>PipeImgGen</code> branches between <code>make_single_image</code> and <code>make_image_list</code>; <code>PipeExtract</code> calls <code>make_extract_pages</code> exactly once.</p>
- <p><strong>Strategy (i)</strong> — "default <code>wfid</code> is unique per workflow" — was chosen over Strategy (ii) (per-method counter) because the latter adds complexity for a problem we don't have today and would be harder to read in the Temporal UI. Three mitigations bolt the invariant down:</p>
- <ul class="tight">
- <li><strong>Distinct method-default <code>wfid</code>s</strong>, fixing the pre-existing duplicate <code>"craft-image"</code> shared by <code>make_single_image</code> and <code>make_image_list</code> — split into <code>"craft-image-single"</code> / <code>"craft-image-list"</code>.</li>
- <li><strong>Distinct activity_ids inside <code>make_extract_pages</code></strong>: this is the only method that dispatches two activities, so we explicitly construct <code>f"{wfid}-pages"</code> for <code>act_extract_gen_extract_pages</code> and <code>f"{wfid}-render-page-views"</code> for the conditional <code>act_render_page_views</code>.</li>
- <li><strong>Runtime check the invariant</strong> — see below.</li>
- </ul>
-</div>
-
-<div class="layer l4">
- <h3>5.4 · Runtime uniqueness check, replay-safe</h3>
- <p>The generator carries a <code>self._seen_activity_ids: dict[str, set[str]]</code> keyed by <code>workflow.info().workflow_id</code>. Each <code>make_*</code> method adds its computed <code>activity_id</code> to the per-workflow set and raises <code>ContentGenerationError</code> on duplicate insert. Two non-obvious choices:</p>
- <ul class="tight">
- <li><strong>Keyed by workflow_id, not a flat set.</strong> The generator instance is set once on the hub and reused across many workflow runs (<code>pipelex.py</code> wires it once). A flat <code>set[str]</code> would produce cross-run false positives the second time any workflow hits the same default <code>wfid</code>.</li>
- <li><strong>Gated by <code>workflow.unsafe.is_replaying()</code>.</strong> During replay, the check short-circuits. Without this, a cache-eviction replay on the same worker process would raise a spurious "duplicate activity_id" against the populated set from the original execution — the worker process holds the set in memory across replays of the same workflow_id.</li>
- </ul>
- <p>The audit proves no current call site triggers this, so the check is a regression guard, not a runtime cost. (Follow-up: the dict has no eviction — see Follow-up TODOs.)</p>
-</div>
-
-<div class="layer l5">
- <h3>5.5 · Asymmetric <code>inference_task_queue</code> rule — provisional, isolated</h3>
- <p>Today's routing rule: <strong>LLM-text goes to <code>inference_task_queue</code>, everything else goes to the workflow's default queue.</strong> This was introduced as a quick split-worker test setup; it is NOT the long-term design. Real deployments will want per-provider, per-model, per-activity-class routing (full design in <code>per-activity-queue-routing-v1.md</code>, out of scope for this PR).</p>
- <p>To survive cleanly until that lands, we extracted a tiny module-private helper:</p>
- <div class="diff">
- <div class="diff-header">pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py</div>
- <pre><span class="line ctx">def _inference_dispatch_kwargs(worker_config) -&gt; dict[str, Any]:</span>
-<span class="line ctx"> """Stopgap. Single deletion point when per-activity routing lands.</span>
-<span class="line ctx"> See wip/temporal-primitives/per-activity-queue-routing-v1.md."""</span>
-<span class="line ctx"> return {"task_queue": worker_config.inference_task_queue}</span></pre>
- </div>
- <p>Called at the single LLM-text dispatch site by <code>**</code>-unpacking. Unit tests pin both directions: LLM-text passes <code>task_queue=worker_config.inference_task_queue</code>, every other method must NOT pass <code>task_queue=</code> (over-routing would break split-worker production where the runner doesn't register image-gen / extract on the inference queue).</p>
-</div>
-
-<h2>6 — Code: the LLM-text dispatch, before vs after</h2>
-
-<p>The whole refactor boils down to substituting one Temporal SDK call for another. Below is the LLM-text path. The other six methods follow the identical pattern.</p>
-
-<div class="side">
- <div>
- <h4>Before — ContentGeneratorChild + WfMakeLLMText</h4>
-<pre># content_generator_child.py
-async def make_llm_text(
- self,
- llm_assignment: LLMAssignment,
- wfid: str = "craft-text",
- ...
-) -&gt; str:
- child_workflow_id = make_child_workflow_id(
- parent_id=workflow.info().workflow_id,
- wfid=wfid,
- )
- return await self._workflow_executor \
- .execute_child_workflow(
- WfMakeLLMText,
- arg=llm_assignment,
- id=child_workflow_id,
- ...
- )
-
-# wf_make_llm_text.py
[email protected](name="wf_make_llm_text")
-class WfMakeLLMText(
- WorkflowClass[LLMAssignment, str]
-):
- @workflow.run
- async def run(
- self, arg: LLMAssignment
- ) -&gt; str:
- wc = get_config().temporal.worker_config
- try:
- return await workflow.start_activity(
- activity=act_llm_gen_text,
- arg=arg,
- start_to_close_timeout=
- wc.workflow_execution_timeout,
- retry_policy=wc.retry_policy,
- task_queue=wc.inference_task_queue,
- )
- except ActivityError as exc:
- if isinstance(exc.cause, ApplicationError):
- raise TemporalError.from_app_error(
- exc=exc.cause
- ) from exc
- raise</pre>
- </div>
- <div>
- <h4>After — ContentGeneratorInWorkflow only</h4>
-<pre># content_generator_in_workflow.py
-async def make_llm_text(
- self,
- llm_assignment: LLMAssignment,
- wfid: str = "craft-text",
- ...
-) -&gt; str:
- self._check_activity_id_unique(wfid)
- wc = get_config().temporal.worker_config
- try:
- # LLM-text only: route to inference queue.
- # See _inference_dispatch_kwargs docstring.
- return await workflow.execute_activity(
- act_llm_gen_text,
- llm_assignment,
- start_to_close_timeout=
- wc.workflow_execution_timeout,
- retry_policy=wc.retry_policy,
- activity_id=wfid,
- **_inference_dispatch_kwargs(wc),
- )
- except ActivityError as exc:
- if isinstance(exc.cause, ApplicationError):
- raise TemporalError.from_app_error(
- exc=exc.cause
- ) from exc
- raise
-
-# wf_make_llm_text.py
-# ──────── DELETED ────────</pre>
- </div>
-</div>
-
-<p>Notice what stayed identical: the <code>try/except ActivityError → TemporalError.from_app_error(…)</code> translation, the <code>start_to_close_timeout</code> + <code>retry_policy</code> values, and the asymmetric <code>task_queue</code> routing. The behavioral surface is preserved; only the indirection is gone.</p>
-
-<h2>7 — The runtime uniqueness check, in code</h2>
-
-<div class="diff">
- <div class="diff-header">pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py</div>
- <pre><span class="line ctx">class ContentGeneratorInWorkflow:</span>
-<span class="line ctx"> def __init__(self):</span>
-<span class="line ctx"> # Keyed by workflow_id because this generator instance is set once on</span>
-<span class="line ctx"> # the hub and reused across many workflow runs. A flat set[str] would</span>
-<span class="line ctx"> # produce cross-run false positives.</span>
-<span class="line ctx"> self._seen_activity_ids: dict[str, set[str]] = {}</span>
-<span class="line ctx"> </span>
-<span class="line ctx"> def _check_activity_id_unique(self, activity_id: str) -&gt; None:</span>
-<span class="line ctx"> # During replay, Temporal re-walks the history. The set is already</span>
-<span class="line ctx"> # populated from the original execution; without this guard, a</span>
-<span class="line ctx"> # cache-eviction replay would raise a spurious duplicate.</span>
-<span class="line ctx"> if workflow.unsafe.is_replaying():</span>
-<span class="line ctx"> return</span>
-<span class="line ctx"> wf_id = workflow.info().workflow_id</span>
-<span class="line ctx"> seen = self._seen_activity_ids.setdefault(wf_id, set())</span>
-<span class="line ctx"> if activity_id in seen:</span>
-<span class="line ctx"> msg = f"Duplicate activity_id {activity_id!r} in workflow {wf_id!r}"</span>
-<span class="line ctx"> raise ContentGenerationError(msg)</span>
-<span class="line ctx"> seen.add(activity_id)</span></pre>
-</div>
-
-<div class="note">
- <strong>Why this is a guard, not a hot-path cost.</strong> The Phase 0 audit proved no current call site can trigger this (every protocol method is mutually exclusive within one <code>PipeOperator</code> execution). The check is here to catch <em>future</em> regressions: a new operator call site that calls the same protocol method twice would silently break on Temporal's "duplicate activity_id" error; instead it now fails fast with a typed Pipelex error and a clear message.
-</div>
-
-<h2>8 — The <code>make_extract_pages</code> page-views fix</h2>
-
-<p>This is the one place where the refactor isn't pure deletion — it fixes a pre-existing behavioral divergence between the direct-mode and Temporal-mode generators.</p>
-
-<p>The <strong>direct-mode</strong> <code>ContentGenerator.make_extract_pages</code> augments its return when <code>extract_job_params.should_include_page_views</code> is true: it calls <code>make_render_page_views(…)</code> for multi-page <code>document_uri</code> inputs, or constructs a single-element page view inline for <code>image_uri</code> inputs.</p>
-
-<p>The <strong>Temporal-mode</strong> <code>ContentGeneratorChild.make_extract_pages</code> did NOT. It just dispatched <code>WfMakeExtract</code> and returned the page contents as-is, missing both augmentations. Per the project's "flag and fix existing bugs" rule, the collapse is the right moment to fix it.</p>
-
-<p>The new <code>make_extract_pages</code> mirrors the direct generator exactly — and it is the only protocol method that dispatches more than one activity, so it earns special handling for activity_id uniqueness:</p>
-
-<div class="diff">
- <div class="diff-header">ContentGeneratorInWorkflow.make_extract_pages</div>
- <pre><span class="line ctx">async def make_extract_pages(self, ...) -&gt; ExtractPagesOutput:</span>
-<span class="line ctx"> base_id = wfid # e.g. "extract"</span>
-<span class="line ctx"> pages_id = f"{base_id}-pages"</span>
-<span class="line ctx"> page_views_id = f"{base_id}-render-page-views"</span>
-<span class="line ctx"> self._check_activity_id_unique(pages_id)</span>
-<span class="line ctx"> </span>
-<span class="line ctx"> # First activity: real extraction.</span>
-<span class="line ctx"> output = await workflow.execute_activity(</span>
-<span class="line ctx"> act_extract_gen_extract_pages, ...,</span>
-<span class="line ctx"> activity_id=pages_id,</span>
-<span class="line ctx"> )</span>
-<span class="line ctx"> </span>
-<span class="line ctx"> if not extract_job_params.should_include_page_views:</span>
-<span class="line ctx"> return output # no double-emit when false</span>
-<span class="line ctx"> </span>
-<span class="line add">+ if extract_input.document_uri is not None:</span>
-<span class="line add">+ # Second activity: render page views from the document.</span>
-<span class="line add">+ self._check_activity_id_unique(page_views_id)</span>
-<span class="line add">+ page_views = await workflow.execute_activity(</span>
-<span class="line add">+ act_render_page_views, ...,</span>
-<span class="line add">+ activity_id=page_views_id,</span>
-<span class="line add">+ )</span>
-<span class="line add">+ elif extract_input.image_uri is not None:</span>
-<span class="line add">+ # Single image → single-element page view, no second activity.</span>
-<span class="line add">+ page_views = [ImageContent(url=extract_input.image_uri)]</span>
-<span class="line add">+ else:</span>
-<span class="line add">+ page_views = []</span>
-<span class="line add">+</span>
-<span class="line add">+ if len(page_views) != len(output.page_contents):</span>
-<span class="line add">+ raise ContentGenerationError("page_views length mismatch")</span>
-<span class="line add">+</span>
-<span class="line add">+ for page_content in output.page_contents:</span>
-<span class="line add">+ page_content.page_view = page_views.pop(0)</span>
-<span class="line ctx"> return output</span></pre>
-</div>
-
-<p>The two-activity branch is the most fragile post-collapse path — it's the only place where the activity_id uniqueness mitigation actually matters in production. It's covered three ways:</p>
-
-<ul class="tight">
- <li><strong>Unit tests</strong> (Phase 1): all three branches — no-page-views, <code>image_uri</code>, <code>document_uri</code>.</li>
- <li><strong>Real-PDF integration test</strong> (Phase 4): <code>TestTprlContentGeneratorPdfPageViews</code> exercises the multi-page <code>document_uri</code> branch end-to-end through real Temporal, against a local 2-page PDF (multi-page catches <code>pop(0)</code> ordering bugs that a 1-page PDF would not).</li>
- <li><strong>Cross-process regression guard</strong> (Phase 7): <code>TestSplitWorkerExtractPages</code> asserts via <code>WorkflowHandle.fetch_history()</code> that two <code>ActivityTaskScheduled</code> events appear with activity_ids <code>"extract-pages"</code> and <code>"extract-render-page-views"</code> — pins the contract.</li>
-</ul>
-
-<h2>9 — File-level inventory</h2>
-
-<div class="layer l5">
- <h3>Deleted <span class="pill pill-drop">−11 files</span></h3>
- <p>All under <code>pipelex/temporal/tprl_content_generation/</code>:</p>
- <ul class="tight">
- <li><code>wf_make_llm_text.py</code></li>
- <li><code>wf_make_object.py</code> (held both <code>WfMakeObject</code> and <code>WfMakeObjectList</code>)</li>
- <li><code>wf_make_images.py</code></li>
- <li><code>wf_make_jinja2_text.py</code></li>
- <li><code>wf_make_extract.py</code></li>
- <li><code>wf_render_page_views.py</code></li>
- <li><code>content_generator_top.py</code> + <code>content_generator_top_factory.py</code> (test-only, dispatched <code>WfMake*</code> from the submitter side)</li>
- <li><code>content_generator_child.py</code> + <code>content_generator_child_factory.py</code></li>
- <li><code>content_generator_models.py</code> (the <code>AssignmentType</code> / <code>ResultType</code> unions, only consumed by the two deleted generators)</li>
- </ul>
- <p>Plus four test files: <code>test_tprl_content_generator_top.py</code>, <code>test_tprl_make_content_generator.py</code>, and two already-commented historical files <code>test_wf_gen_text.py</code> + <code>test_wf_jinja2.py</code>.</p>
-</div>
-
-<div class="layer l3">
- <h3>Added <span class="pill pill-new">+1 file</span></h3>
- <ul class="tight">
- <li><code>content_generator_in_workflow.py</code> — the single new generator implementing <code>ContentGeneratorProtocol</code>, one method per activity, ~300 lines.</li>
- <li><code>content_generator_in_workflow_factory.py</code> — its producer.</li>
- <li><code>tests/unit/pipelex/temporal/test_content_generator_in_workflow.py</code> — covers task_queue positive/negative, activity_id threading, the <code>craft-image-single</code> / <code>craft-image-list</code> split, the two-activity branch in <code>make_extract_pages</code>, the runtime duplicate check, replay-safety of the check, and <code>ActivityError → TemporalError</code> translation (both branches).</li>
- </ul>
-</div>
-
-<div class="layer l2">
- <h3>Modified <span class="pill pill-modify">touched</span></h3>
- <ul class="tight">
- <li><code>pipelex/temporal/tasks.py</code> — dropped the <code>WfMake*</code> + <code>WfRenderPageViews</code> imports; <code>crafting</code> <code>TaskPack</code>'s <code>workflow_list</code> is now empty. Activity list unchanged.</li>
- <li><code>pipelex/pipelex.py</code> — when <code>temporal.is_enabled</code>, constructs <code>ContentGeneratorInWorkflowFactory</code> unconditionally. The feature flag (briefly named <code>PIPELEX_USE_IN_WORKFLOW_CONTENT_GENERATOR</code>, then flipped and renamed to <code>PIPELEX_USE_LEGACY_CONTENT_GENERATOR</code>) was deleted at Phase 6.</li>
- <li><code>pipelex/temporal/test_extras/wf_test_content_generator_child.py</code> — re-pointed to construct the new generator.</li>
- <li>Test conftests (parent + <code>content_generation/</code>) — removed the <code>top_crafter</code> / <code>child_crafter</code> fixtures and their imports.</li>
- <li>Tracing docs in <code>test_split_worker_usage.py</code> and <code>helpers.py</code> — describe the direct-activity-call topology.</li>
- <li><code>docs/under-the-hood/pipe-routing-and-execution.md</code> — renamed "Content Generation Workflows" section to "Content Generation Activities"; replaced the two-column workflow|activity table with a single activity table.</li>
- <li><code>docs/under-the-hood/temporal-integration.md</code> — four reference updates (PipeSequence topology box, Controller Dispatch Patterns table, "Internal sub-workflows" subsection renamed, Known Limitation section).</li>
- <li><code>CHANGELOG.md</code> <code>[Unreleased]</code> — a new <code>Changed</code> entry covering the deletions, durability invariant, activity_id naming, the isolated <code>inference_task_queue</code> rule, and the page-views fix.</li>
- </ul>
-</div>
-
-<h2>10 — Phase-by-phase landing plan</h2>
-
-<p>Each phase ends with <code>make agent-check &amp;&amp; make agent-test</code>. Two checkpoints — natural commit boundaries — are placed at A (ready to flip the flag) and B (codebase in target state).</p>
-
-<table>
- <thead><tr><th>Phase</th><th>What lands</th><th>Risk gate</th></tr></thead>
- <tbody>
- <tr><td>0</td><td>Pre-flight audit: confirm per-workflow uniqueness invariant for Strategy (i). No code changes — produces an entry in <strong>Decisions</strong>.</td><td>30 min audit vs. duplicate-activity_id runtime errors later.</td></tr>
- <tr><td>1</td><td>Build the new <code>ContentGeneratorInWorkflow</code> + factory + unit tests. No wiring.</td><td>Compile-only.</td></tr>
- <tr><td>2</td><td>Wire behind env-flag <code>PIPELEX_USE_IN_WORKFLOW_CONTENT_GENERATOR</code> in <code>pipelex.py</code> + both Temporal conftests. Default OFF.</td><td>Both flag values pass the targeted Temporal subsets.</td></tr>
- <tr><td>3</td><td>Re-point <code>WfTestContentGeneratorChild</code> to the new generator (test fixture; exercises new code regardless of flag).</td><td><code>content_generation/</code> integration suite green.</td></tr>
- <tr><td>4</td><td>Fix the <code>make_extract_pages</code> page-views asymmetry (folded into Phase 1 since it's a Phase 1 method).</td><td>Unit tests cover all three branches.</td></tr>
- <tr><td><strong>✅ A</strong></td><td><strong>Checkpoint A</strong> — new generator validated end-to-end, ready to flip. Commit boundary.</td><td></td></tr>
- <tr><td>5</td><td>Flip the env-flag default. Rename to <code>PIPELEX_USE_LEGACY_CONTENT_GENERATOR</code> so polarity is self-documenting.</td><td>Full <code>make agent-test</code> green under new default.</td></tr>
- <tr><td>6</td><td>Delete the old surface in one commit: 11 source files, 4 test files, plus the env-flag branch. Re-generate <code>_generated_model_sets.py</code> after <code>make cleanderived</code>.</td><td><code>make tb</code> + <code>make agent-test</code> green.</td></tr>
- <tr><td>7</td><td>Cross-process coverage: <code>TestSplitWorkerObjectGen</code> (Tier 9), Tier 10 image-gen split-worker negative-routing assertion, <code>TestSplitWorkerExtractPages</code> (Tier 11). Extract <code>_inference_dispatch_kwargs</code> helper to isolate the provisional 2-queue model.</td><td>Three new tests pass.</td></tr>
- <tr><td>8</td><td>Update docstrings + docs in <code>docs/under-the-hood/</code>, the tracing docstrings, and CHANGELOG.</td><td>Grep verifies no stale <code>WfMake*</code> / <code>wf_make_*</code> references outside CHANGELOG.</td></tr>
- <tr><td><strong>✅ B</strong></td><td><strong>Checkpoint B</strong> — codebase in target state. Commit boundary.</td><td></td></tr>
- <tr><td>9</td><td>Final verification: full real-server pytest run + Temporal history smoke against split workers + replay-history grep.</td><td>Zero <code>wf_make_*</code> / <code>wf_render_page_views</code> workflow types observed in <code>temporal workflow list</code>.</td></tr>
- </tbody>
-</table>
-
-<h2>11 — Where bugs are most likely to hide</h2>
-
-<div class="note">
- <strong>1. The asymmetric <code>task_queue=inference_task_queue</code> rule.</strong> Easy to forget at the LLM-text site or to over-apply elsewhere. Mis-routing image-gen to the inference queue would break split-worker production where the runner doesn't register the image-gen activity. Covered by the unit test pinning the helper symbol on both positive (LLM-text) and negative (other methods) assertions.
-</div>
-
-<div class="note">
- <strong>2. <code>activity_id</code> collisions under repeated calls.</strong> The default <code>wfid</code> values are method-specific constants; they do NOT disambiguate repeated calls to the same method. The Phase 1 runtime check (<code>dict[workflow_id, set[str]]</code>, gated by <code>workflow.unsafe.is_replaying()</code>) converts this from a documented invariant to a checked one and is replay-safe.
-</div>
-
-<div class="note">
- <strong>3. <code>model_validate(obj.model_dump(mode="json", serialize_as_any=True))</code> round-trips</strong> for <code>make_object</code> / <code>make_object_list</code>. Required because the activity boundary returns a generic <code>BaseModel</code>. Use <code>mode="json"</code> on BOTH — <code>ContentGeneratorChild.make_object_list</code> omitted it (pre-existing asymmetry). Tier 9 cross-process test (<code>TestSplitWorkerObjectGen</code>) validates the nested-field round-trip through Temporal's data converter.
-</div>
-
-<div class="note">
- <strong>4. Page-views augmentation in <code>make_extract_pages</code>.</strong> Mirror the direct generator's branching exactly: no double-emit when <code>should_include_page_views</code> is false; handle both <code>document_uri</code> (multi-page render) and <code>image_uri</code> (single-image) inputs; assert length match. Triple-covered (unit + real-PDF + cross-process).
-</div>
-
-<div class="note">
- <strong>5. Test infrastructure bypass.</strong> Both <code>tests/integration/pipelex/temporal/conftest.py</code> and <code>test_payload_codec_pipeline.py</code> explicitly call <code>pipelex_hub.set_content_generator(...)</code> after <code>Pipelex.make()</code>, so the env-flag branch in <code>pipelex.py</code> was bypassed in tests during Phase 2. Both conftests had to mirror the flag, then drop the branch at Phase 6.
-</div>
-
-<h2>12 — Follow-up TODOs (out of scope)</h2>
-
-<ul class="tight">
- <li><strong>Per-activity, per-handle Temporal queue routing.</strong> Replace the provisional <code>inference_task_queue</code> binary model with a general routing system covering LLM, image-gen, and extract — keyed by <code>(activity_name, runtime_handle)</code>. Full design in <code>wip/temporal-primitives/per-activity-queue-routing-v1.md</code>. The Phase 7 stopgap helper <code>_inference_dispatch_kwargs</code> is the single deletion point when this lands.</li>
- <li><strong>Watch task-queue saturation post-deploy.</strong> Today a <code>PipeSequence</code> of N inference calls schedules N child workflows, decoupling activity scheduling across child task lists. Post-collapse, all N activities run through the parent's task list (or <code>inference_task_queue</code> for LLM-text). For deep pipelines (N &gt; 50), single-queue QPS could spike. Watch <code>ScheduleToStartLatency</code> on both queues. Not blocking; upside dominates.</li>
- <li><strong>Drop <code>make_render_page_views</code> from <code>ContentGeneratorProtocol</code></strong> if no operator caller emerges within one release cycle. Today it's only invoked internally from <code>make_extract_pages</code>; the Protocol method is dead code from the operator side. Estimated savings: ~50 lines across four files.</li>
- <li><strong>Fix <code>make_extract_pages</code> Protocol-violating signature</strong> in the direct generator (defaults <code>extract_job_params</code> / <code>extract_job_config</code> to <code>None</code> while the Protocol requires non-None).</li>
- <li><strong>Bound <code>_seen_activity_ids</code> growth.</strong> The dict never evicts. A long-running worker accumulates one entry per processed workflow_id over its lifetime. Add an eviction hook on workflow completion, or move the set into workflow-local state via a contextvar set at the start of <code>WfPipeRouter.run</code>.</li>
-</ul>
-
-<h2>13 — TL;DR for the reviewer</h2>
-
-<div class="ok">
- <ol style="margin: 0.3rem 0 0.3rem 1.2rem;">
- <li>Seven <code>WfMake*</code> child workflows were structurally identical 5-line wrappers around one activity each. Gone.</li>
- <li>Two near-duplicate generators (<code>ContentGeneratorTop</code>, <code>ContentGeneratorChild</code>) collapse into one <code>ContentGeneratorInWorkflow</code> that calls <code>workflow.execute_activity(…)</code> directly.</li>
- <li>History events per content-generation call: ≈12 → 3. Per-LLM-call durability preserved (activity boundary unchanged).</li>
- <li>The asymmetric <code>inference_task_queue</code> rule survives — isolated in <code>_inference_dispatch_kwargs</code>, marked provisional, single deletion point when per-activity routing lands.</li>
- <li>Activity_id observability preserved via <code>activity_id=wfid</code>; runtime uniqueness check is replay-safe and per-workflow.</li>
- <li>The <code>make_extract_pages</code> page-views asymmetry between direct-mode and Temporal-mode is fixed in passing (project's "flag and fix" rule).</li>
- <li>Net: 11 files deleted, 1 added; behavior preserved on every covered path; tests strengthened cross-process for the post-collapse paths.</li>
- </ol>
-</div>
-
-<p class="small">Companion docs: <code>collapse-content-generation-workflow-layer-v2.md</code> (the why), <code>TODOS.md</code> (the executable plan), <code>per-activity-queue-routing-v1.md</code> (the deletion target for the provisional queue rule).</p>
-
-</body>
-</html>
diff --git a/wip/archive/early-library-as-execution-context.md b/wip/archive/early-library-as-execution-context.md
deleted file mode 100644
index f081a0639..000000000
--- a/wip/archive/early-library-as-execution-context.md
+++ /dev/null
@@ -1,199 +0,0 @@
-# The LibraryCrate: From File-System Bundles to Execution Context
-
-> **Status**: Architecture vision
-> **Date**: 2026-03-23
-> **Related**: [00-master-plan.md](00-master-plan.md), [phase0-pipe-namespace-fix.md](phase0-pipe-namespace-fix.md)
-
----
-
-## 1. The Three-Stage Pipeline
-
-Library loading follows a three-stage pipeline. Each stage has a distinct role and a clean boundary with the next.
-
-```
-Bundles (files) ──► LibraryCrate (data) ──► Library (live)
-```
-
-**Bundles** are file-system and packaging artifacts: `.mthds` files, method packages with manifests, remote dependencies. They are how methods are authored, versioned, and distributed. A single domain can be spread across multiple bundle files — for example, a `scoring` domain might have `scoring_core.mthds` and `scoring_advanced.mthds`.
-
-**LibraryCrate** is a flat, source-agnostic, serializable snapshot. It contains concept blueprints keyed by `concept_ref` and pipe blueprints keyed by `pipe_ref` — both fully-qualified with their domain prefix. It carries no memory of which file or package each blueprint came from. When multiple bundles contribute to the same domain, their blueprints simply land in the same flat dicts (strict merge — same ref appearing twice is an error).
-
-**Library** is the live runtime. Concepts are instantiated as `Concept` objects with generated structure classes. Pipes are instantiated as `PipeAbstract` subclass instances. The library is the execution truth — what pipe controllers query when resolving child pipes at runtime.
-
-### What about domains?
-
-Domains are a **namespace convention**, not a runtime container. A domain like `scoring` provides the prefix in `scoring.WeightedScore` (concept) and `scoring.compute_score` (pipe). Domains help organize methods at authoring time and prevent naming conflicts, but at runtime they carry no meaningful state. The `Domain` object in the library has only `code`, `description`, and an optional `system_prompt` — none of which are needed for pipe or concept resolution. The LibraryCrate doesn't need domain-level grouping; the namespace is already encoded in the refs.
-
-### Why a middle stage?
-
-Without the LibraryCrate, the system jumps directly from file-system artifacts to live objects. This creates two problems:
-
-1. **Serialization**: Live objects contain runtime state (generated classes, resolved references) that cannot be cleanly serialized. Blueprints are pure Pydantic models — they serialize trivially.
-
-2. **Decoupling**: The live library shouldn't know about files, packages, or remote repositories. The crate is the clean handoff point: everything upstream of it deals with sourcing and parsing; everything downstream deals with instantiation and execution.
-
----
-
-## 2. What a Pipeline Execution Actually Needs
-
-When a pipeline runs, it needs access to **concepts and pipes** — not files.
-
-1. **It needs all the concepts and pipes in its dependency graph.** A pipe controller resolves child pipes, which resolve their children, and so on. Each pipe references concepts for its inputs and outputs. The full transitive closure of these references defines what the execution needs.
-
-2. **It does not need anything outside that dependency graph.** A library loaded from the file system might contain 50 pipes. A given pipeline execution might only touch 15 of them and a fraction of the concepts. The rest is dead weight.
-
-This is possible to determine statically because Pipelex's execution is deterministic — the dependency graph of a pipeline is known before execution begins. There are no dynamic pipe lookups or runtime-resolved references.
-
-### How dependencies are resolved today
-
-When a pipeline is executed via CLI or API:
-
-1. The caller provides a bundle (as `mthds_content` or by referencing a file) and optionally a `pipe_code` (defaults to the bundle's `main_pipe`).
-
-2. `pipeline_run_setup()` loads **all** bundles from the provided library directories (`PIPELEXPATH`, `-L` flag, `library_dirs` parameter) and from installed methods (`.mthds/methods/` directories). This is a brute-force approach — everything available gets loaded.
-
-3. If `mthds_content` was provided, its blueprint is loaded on top.
-
-4. After loading, the library is validated: every pipe's dependencies (child pipes for controllers, concepts for inputs/outputs) must exist in the loaded library. If something is missing, validation fails.
-
-This "load everything, validate after" approach works but is wasteful. It loads pipes and concepts that will never be used, and it requires that all transitive dependencies be available on the file system at load time.
-
----
-
-## 3. The LibraryCrate
-
-The LibraryCrate is a self-contained, serializable representation of the concepts and pipes needed for execution, organized by domain.
-
-### Structure
-
-```python
-class LibraryCrate(BaseModel):
- """Complete library content, ready to load into a live Library."""
- concepts: dict[str, ConceptBlueprint] # concept_ref (domain.Code) -> blueprint
- pipes: dict[str, PipeBlueprintUnion] # pipe_ref (domain.pipe_code) -> blueprint
- fingerprint: str # SHA256 of serialized content
-```
-
-The crate is flat. No domain-level grouping — the domain is implicit in the keys (`scoring.WeightedScore`, `scoring.compute_score`). This mirrors how the live library already works for concepts (keyed by `concept_ref`), and how it will work for pipes once the `pipe_ref` fix lands.
-
-### Properties
-
-- **Flat and ref-keyed**: Two dicts, keyed by fully-qualified refs. Domain is a namespace prefix, not a structural container.
-- **Source-agnostic**: No file paths, no bundle identity, no package provenance. The crate doesn't know (or care) where its blueprints came from.
-- **Serializable**: Pure Pydantic models. JSON round-trip is trivial. This is what makes it suitable for both in-process use and wire transfer.
-- **Fingerprinted**: A SHA256 digest of the serialized content enables caching — if the same crate has already been loaded, skip the work.
-
-### How it's built
-
-```python
-# 1. Parse bundles from files
-blueprints: list[PipelexBundleBlueprint] = [
- PipelexInterpreter.make_pipelex_bundle_blueprint(bundle_path=path)
- for path in mthds_file_paths
-]
-
-# 2. Build crate: qualify refs with domain, merge into flat dicts
-crate = LibraryCrateFactory.make_from_blueprints(blueprints)
-
-# 3. Load into live library
-library_manager.load_from_crate(library_id, crate)
-```
-
-Each bundle declares a domain (e.g., `scoring`). During crate construction, concept codes become `concept_ref`s (`Score` → `scoring.Score`) and pipe codes become `pipe_ref`s (`compute_score` → `scoring.compute_score`). Multiple bundles — even for the same domain — simply add entries to the flat dicts. If the same ref appears twice, that's a conflict — error, not silent override.
-
-### What blueprints contain
-
-**ConceptBlueprint** (`core/concepts/concept_blueprint.py`): `description`, `structure`, `refines`. Clean Pydantic BaseModel.
-
-**PipeBlueprintUnion** (`core/bundles/pipelex_bundle_blueprint.py`): Discriminated union of 10 pipe blueprint types (`PipeFuncBlueprint`, `PipeLLMBlueprint`, `PipeSequenceBlueprint`, etc.). All are Pydantic models with fields for inputs, output, type-specific configuration (prompts, steps, branches, etc.).
-
-These are already the "data form" of pipes and concepts. They parse cleanly from `.mthds` files, they serialize cleanly to JSON, and the existing factory methods (`ConceptFactory.make_from_blueprint()`, `PipeFactory.make_from_blueprint()`) know how to instantiate live objects from them.
-
----
-
-## 4. Namespace Prerequisites
-
-Before building the LibraryCrate, a fundamental asymmetry in the library must be fixed.
-
-**Concepts are properly namespaced.** The `ConceptLibrary` indexes concepts by `concept_ref` = `domain.ConceptCode` (e.g., `scoring.WeightedScore`). Two concepts with the same code in different domains coexist without conflict.
-
-**Pipes are NOT namespaced.** The `PipeLibrary` indexes pipes by bare `code` (e.g., `compute_score`, not `scoring.compute_score`). If two domains define a pipe with the same code, the second one collides with the first — the library raises an error as if it were a duplicate, even though they're in different domains.
-
-This must be fixed by introducing `pipe_ref` = `domain.pipe_code` on `PipeAbstract` and rekeying `PipeLibrary` by `pipe_ref`, symmetric with how concepts work. The domain library must also support additive merging (multiple bundles contributing to the same domain).
-
-Once `pipe_ref` is in place, the flat LibraryCrate keying becomes natural — both concepts and pipes use fully-qualified refs as dict keys, and the domain is just the prefix before the dot.
-
-See [phase0-pipe-namespace-fix.md](phase0-pipe-namespace-fix.md) for the detailed technical spec.
-
----
-
-## 5. Dependency Resolution Roadmap
-
-Dependency resolution improves in phases, from brute-force to precise.
-
-### Current state: Load everything
-
-`pipeline_run_setup()` loads all bundles from all provided library paths. Validation checks that dependencies exist, but nothing is selective. The full library travels to execution even if only a fraction is needed.
-
-### Near-term: Full crate, validated
-
-The LibraryCrate contains everything that was loaded — the full set of domains, concepts, and pipes. This is equivalent to today's behavior but with the crate as the clean intermediate. No stripping yet.
-
-### Planned: Static dependency tree analysis (crate stripping)
-
-From the entry pipe, walk the transitive closure:
-- For each pipe controller, collect its `pipe_dependencies()` (child pipe codes)
-- For each pipe (controller or operator), collect its `concept_dependencies` (input/output concepts)
-- Recursively resolve until the full dependency graph is known
-
-Then strip the crate to only the domains, concepts, and pipes in the dependency graph. This reduces payload sizes for distributed execution and clarifies exactly what context is needed.
-
-This is feasible because execution is deterministic — the dependency graph is fully known at build time.
-
-### Future: Remote dependency resolution
-
-Resolve dependencies from GitHub method package addresses. When a bundle declares a dependency on `github:org/repo`, clone to a temp directory, parse the bundles, and merge into the crate. This enables running pipelines whose dependencies aren't pre-installed locally.
-
----
-
-## 6. Generalization Across Execution Modes
-
-The LibraryCrate is **not** a Temporal-specific construct. It is the universal intermediate representation for all execution modes.
-
-**Direct execution** (in-process):
-```
-Bundles → LibraryCrate → Library (live, in same process)
-```
-
-**Distributed execution** (Temporal):
-```
-Bundles → LibraryCrate → serialize → send to worker → deserialize → Library (live, on worker)
-```
-
-The only difference is that distributed execution adds a serialize/deserialize step. The crate itself is identical.
-
-This means we build and validate the LibraryCrate in direct mode first. Once it works — once all existing tests pass through the `bundles → crate → library` path — distributed execution gets serialization for free because the crate is already a Pydantic model.
-
----
-
-## 7. External Storage for Large Payloads
-
-When payloads grow beyond Temporal's 2MB limit (large libraries, WorkingMemory with images/documents), external storage becomes necessary.
-
-Each pipeline execution has a **pipeline run ID** that can serve as the storage key:
-
-- Before dispatching to Temporal, upload the crate and working memory to a storage backend
-- Workers fetch by run ID, load, execute, write back results
-- Uses the existing `StorageProviderAbstract` system
-
-This is a later optimization (Phase 4 in the master plan), not part of the core LibraryCrate design. The crate's serialization is a prerequisite — you can't upload what you can't serialize — but the storage mechanism is independent.
-
----
-
-## 8. Open Questions
-
-- **Caching by fingerprint**: If the same LibraryCrate (same fingerprint) is used across multiple pipeline runs, can workers cache the loaded library and skip re-loading? This is especially valuable for Temporal workers processing many runs with the same library.
-
-- **Storage backend choice**: S3-compatible? Redis for short-lived data? The `StorageProviderAbstract` makes this pluggable, but the default choice matters for developer experience.
-
-- **Domain `system_prompt` migration**: The bundle-level `system_prompt` currently flows into the `Domain` object and is used as a fallback by PipeLLM pipes that don't define their own. When we flatten the crate (no domain-level data), this fallback must be inlined at pipe factory time — each PipeLLM gets its system_prompt resolved during construction, before entering the crate. This is a small change in `PipeLLMFactory` but needs to be done as part of Phase 0 or Phase 1.
diff --git a/wip/archive/early-temporal-library-fix-proposals.md b/wip/archive/early-temporal-library-fix-proposals.md
deleted file mode 100644
index 4fa07fc3c..000000000
--- a/wip/archive/early-temporal-library-fix-proposals.md
+++ /dev/null
@@ -1,441 +0,0 @@
-# Architecture Discussion: Fixing Library Unavailability in Distributed Execution (v2)
-
-> **Status**: Draft v2 — for team architecture review
-> **Date**: 2026-03-22
-> **Context**: See [Pipe Routing & Execution](../under-the-hood/pipe-routing-and-execution.md) for how direct and distributed execution work. See [temporal-worker-problem.md](../../.claude/skills/temporal-diagnose/references/temporal-worker-problem.md) for the detailed root cause analysis and error patterns.
-> **Changes from v1**: Relaxed C1 (breaking changes acceptable), replaced naive `mthds_content: str` model with proper multi-bundle library context analysis, proposed `LibraryContext` model for API evolution.
-
----
-
-## 1. Problem Statement
-
-When pipe controllers (PipeSequence, PipeCondition, PipeBatch, PipeParallel) run via **distributed execution** (Temporal), they fail because the library is never loaded on the worker process.
-
-```
-API Process Temporal Worker
-───────────────────────────────────────── ──────────────────────────────
-pipeline_run_setup()
- ├─ Loads library (library_manager) (empty here)
- ├─ Generates dynamic concept classes (classes don't exist here)
- ├─ Registers them with Kajson (Kajson registry incomplete here)
- ├─ Resolves pipe by code (can't resolve here)
- └─ Creates PipeJob (top-level pipe)
- │
- └─ PipeRouterTop sends PipeJob ──────► WfPipeRouter.run(pipe_job)
- to Temporal ├─ Kajson deserializes PipeJob
- │ └─ FAILS (Layer 1): unknown class
- └─ pipe.run_pipe()
- └─ get_required_pipe() FAILS (Layer 2)
-```
-
-### Layer 1 -- Deserialization Failure (hits first)
-
-The `PipeJob`'s `WorkingMemory` contains `Stuff` objects with dynamically-generated concept content classes (e.g., `RawText` inheriting from `TextContent`). These classes are created by `ConceptFactory` during library loading and registered with Kajson's class registry. On the worker, these classes don't exist -> `KajsonDecoderError: Class 'RawText' not found in module 'builtins'`.
-
-This is a **hard blocker**: Temporal's workflow instance cannot even deserialize the workflow input.
-
-### Layer 2 -- Pipe Resolution Failure (would hit after Layer 1 is fixed)
-
-Controllers call `get_required_pipe(child_pipe_code)` to resolve child pipes at runtime. This queries the `library_manager` singleton, which is empty on the worker -> pipe not found.
-
-### Why Tests Don't Catch It
-
-- Integration tests use `PipeRouter` (direct, in-process) -- library is shared
-- Temporal tests only cover leaf workflows (text gen, jinja2) that don't call `get_required_pipe()`
-- No test sends a pipe controller through `WfPipeRouter`
-
-### Key Insight
-
-Both layers are fixed by the same fundamental action: **loading the library on the worker**. Library loading generates and registers dynamic classes (fixing Layer 1) AND populates `library_manager` with pipe definitions (fixing Layer 2).
-
----
-
-## 2. Constraints
-
-Any solution must respect these constraints:
-
-| # | Constraint | Rationale |
-|---|-----------|-----------|
-| C1 | **Minimize disruption to direct execution** | Additive changes (optional params, new methods) are welcome. Breaking changes are acceptable if justified -- discuss damage control before implementation, but retro-compatibility is not required. |
-| C2 | **Temporal replay safety** | Workflow code must be deterministic. Side effects (file I/O, library loading) belong in Activities, not workflow `run()` methods. Activities re-execute cleanly on replay. |
-| C3 | **Worker reuse** | A single worker processes jobs from different API calls, potentially with different library contexts. The solution must handle this without conflict. |
-| C4 | **Dynamic class generation is unavoidable** | Concepts declared in `.mthds` files create Python classes at library-load time. These must exist before Kajson deserialization. |
-| C5 | **Library context is multi-layered** | See section 2.1. The library is not a single string -- it's a multi-file, multi-package system with manifests, dependencies, and namespace isolation. Any solution must account for this. |
-| C6 | **Library loading is I/O-bound** | Reads files, parses TOML, generates classes, validates. Not suitable for workflow code (violates C2). |
-| C7 | **Temporal payload size** | Default limit is 2MB (configurable). Solutions that embed large payloads must account for this. |
-| C8 | **Reproduce from sources, not snapshots** | The solution should reproduce library state from source inputs (file contents, manifests, dependency metadata), not serialize the resolved `Library` object graph (which includes dependency libraries, class registries, and dynamically generated Python types). |
-
-### 2.1 Understanding the Library Data Model
-
-The current proposals v1 treated `mthds_content` as a single string that could carry "the library context." This is fundamentally incorrect. MTHDS is a **multi-bundle, multi-package** system:
-
-**A package** is a directory containing:
-
-- A `METHODS.toml` manifest (identity, exports, dependencies)
-- One or more `.mthds` bundle files (each declaring one domain)
-- Bundles within a package sharing the same domain code **merge** their namespaces
-
-**Cross-package dependencies** are declared in `METHODS.toml`:
-
-```toml
-[dependencies]
-scoring_lib = { address = "github.com/mthds/scoring-lib", version = "^0.5.0" }
-```
-
-Pipes reference cross-package pipes via alias syntax: `scoring_lib->scoring.compute_weighted_score`. Only exported pipes (declared in `[exports]`) are visible across package boundaries.
-
-**How library loading actually works** (`library_manager.load_libraries()`):
-
-1. Discovers all `.mthds` files from directory paths
-2. Walks up to find `METHODS.toml` manifests for each file
-3. Resolves dependencies (local path + address-based remote fetch)
-4. Enforces visibility/exports between packages
-5. Loads all blueprints into a `Library` with `dependency_libraries: dict[str, Library]`
-
-**The current `mthds_content` parameter** in `pipeline_run_setup()` only handles a single string -> single `PipelexBundleBlueprint`. This works for simple single-domain bundles but cannot represent multi-file packages with manifests and cross-package dependencies. This is a known limitation of the current API surface, not the target architecture.
-
-**Two loading paths exist today:**
-
-| Path | Input | Handles multi-file? | Handles deps? | Used by |
-|------|-------|---------------------|---------------|---------|
-| Directory-based | `library_dirs` (filesystem paths) | Yes | Yes | PIPELEXPATH, installed methods |
-| Content-based | `mthds_content` (single string) | No | No | API single-file bundles |
-
-The Temporal solution must work with both paths and must not bake in the assumption that all library context fits in a single string.
-
----
-
-## 3. Solution Options
-
-### Option A: Worker Startup + Per-Workflow Library Context
-
-**Summary**: Workers load base libraries from `PIPELEXPATH` at startup (Tier 1). Per-workflow library context -- whether a single bundle or a full package -- travels with the workflow input and is loaded in an Activity before the main pipe executes (Tier 2, cached by content hash).
-
-**How it fixes each layer**:
-
-- **Layer 1**: Base library loading at worker startup generates and registers all base concept classes with Kajson. For additional content, a "library setup" Activity runs before the pipe, parsing the content and registering dynamic classes.
-- **Layer 2**: Base pipes populated at startup. Additional pipes loaded in the setup Activity. `get_required_pipe()` finds everything.
-
-**Tier 1 -- Base Library at Worker Startup (already implemented)**:
-
-`worker_cli.py` already loads base libraries after `Pipelex.make()`:
-
-```python
-# In configure(), after Pipelex.make(temporal_enabled=True):
-library_manager = get_library_manager()
-library_manager.open_library(library_id="worker_base")
-effective_dirs, _ = resolve_library_dirs(library_dirs=None)
-if effective_dirs:
- library_manager.load_libraries(library_id="worker_base", library_dirs=effective_dirs)
-```
-
-This generates and registers all base concept classes with Kajson, and populates the pipe library. Fixes both layers for workflows that only use base pipes/concepts (the majority of cases).
-
-**Tier 2 -- Per-Workflow Library Context**:
-
-For workflows with additional library content beyond the base, a `LibraryContext` model travels with the workflow:
-
-```python
-class LibraryContext(BaseModel):
- """Describes library content that must be loaded on the worker before execution."""
- bundles: list[BundleContent] # One or more .mthds files
- manifest_content: str | None # METHODS.toml content, if present
- resolved_dependencies: list[ResolvedDependencyRef] | None # pre-resolved dep refs
- fingerprint: str # SHA256 hash for caching
-```
-
-This replaces the naive `mthds_content: str | None` model. For the current single-file API case, it wraps the string in `bundles` with one entry. For future multi-file support, it carries the full package context.
-
-**Changes required**:
-
-- ~~`worker_cli.py`: Add library loading~~ (already done)
-- New `LibraryContext` model in `pipelex/temporal/`
-- `PipeRouterTop`: Build `LibraryContext` from the current library state when dispatching
-- New `act_library_setup.py`: Activity that loads `LibraryContext` into the library (cached by fingerprint)
-- `WfPipeRouter`: Call the setup Activity before `pipe.run_pipe()`
-
-**Impact on direct execution**: None. `pipeline_run_setup()` and `PipeRouter` unchanged.
-
-**Replay safety**: Library loading happens in Activities (replay-safe). The Activity is idempotent -- loading the same fingerprint twice is a no-op.
-
-**Critical issue**: Layer 1 has a timing problem. Temporal automatically deserializes the PipeJob (via the data converter) *before* the workflow code runs. If the PipeJob contains custom concept instances, deserialization fails before the setup Activity can register the classes. This means **Option A alone cannot fix Layer 1 for content beyond the base library**. See Option D for the solution.
-
----
-
-### Option B: Flatten All Pipes into PipeJob (Self-Contained Job)
-
-**Summary**: At `pipeline_run_setup()` time, resolve the entire pipe tree and embed all referenced pipes directly into the PipeJob. The worker needs no library for pipe resolution.
-
-**How it fixes each layer**:
-
-- **Layer 1**: Does NOT fix. The `WorkingMemory` still contains `Stuff` objects with dynamic concept classes. Flattening pipes doesn't address deserialization of concept content classes.
-- **Layer 2**: Fixed. `get_required_pipe()` calls replaced by lookups into a `resolved_pipes` map on the PipeJob.
-
-**Changes required**:
-
-- `PipeJob`: Add `resolved_pipes: dict[str, PipeAbstract]`
-- All pipe controllers: Refactor to accept a pipe resolver instead of calling `get_required_pipe()` from the hub
-- `pipeline_run_setup()`: Recursively resolve all child pipes and attach to PipeJob
-
-**Impact on direct execution**: Significant. Pipe controllers currently call `get_required_pipe()` globally. Changing them to use a local resolver changes the interface everywhere, adding complexity even in direct mode. With relaxed C1, this is *allowed* but the cost is disproportionate.
-
-**Replay safety**: Excellent. Everything needed is in the workflow input.
-
-**Performance**: Larger PipeJob payloads. Redundant data if pipes are shared across workflows.
-
-**Complexity**: High. Requires refactoring all pipe controllers.
-
-**Verdict**: Fixes only Layer 2, high complexity. Not recommended as standalone approach. The key insight is: once the library is loaded on the worker (which is necessary for Layer 1 regardless), pipe resolution works identically to direct execution -- making the flattening effort unnecessary.
-
----
-
-### Option C: Ship Full Library State per Workflow
-
-**Summary**: Serialize the entire library (domains, concepts, pipes, class definitions) and include it in every workflow invocation. The worker reconstructs the library from this payload.
-
-**How it fixes each layer**:
-
-- **Layer 1**: Include concept structure blueprints in the payload. A pre-deserialization step regenerates dynamic classes.
-- **Layer 2**: Full pipe library reconstructed from serialized state.
-
-**Important distinction**: There are two sub-approaches here:
-
-- **C-snapshot**: Serialize the resolved `Library` object graph. This is impractical -- `Library` includes `dependency_libraries`, dynamically generated Python types, Kajson registry state, etc. Violates C8.
-- **C-sources**: Ship the source inputs (file contents, manifests, dependency metadata) and reproduce the library on the worker. This is essentially what Option A Tier 2 does with `LibraryContext`.
-
-**Verdict for C-snapshot**: Over-engineered, poor performance, every workflow carries the entire library, risk of hitting payload size limits (C7), violates C8. Not recommended.
-
-**Verdict for C-sources**: This is Option A Tier 2 by another name. The right principle ("reproduce from source inputs") is incorporated into the recommended approach.
-
----
-
-### Option D: Deferred Deserialization
-
-**Summary**: Instead of letting Temporal automatically deserialize the PipeJob, the workflow receives a raw payload (bytes or a lightweight wrapper). A library setup Activity runs first to load the library and register dynamic classes. Then the workflow manually deserializes the PipeJob via `kajson.loads()`.
-
-This is designed to solve Option A's critical timing issue with Layer 1.
-
-**How it fixes each layer**:
-
-- **Layer 1**: Library is loaded (including dynamic class registration) *before* deserialization, so all classes exist when `kajson.loads()` runs.
-- **Layer 2**: Same as Option A -- library is loaded.
-
-**When is this needed?** Only when the workflow introduces dynamic classes not already in the worker's base library. For the common case (PIPELEXPATH-based libraries loaded at worker startup), Temporal's normal deserialization works fine because all classes are registered at startup.
-
-**Changes required**:
-
-- `PipeRouterTop`: Serialize PipeJob to raw JSON bytes before dispatching
-- New envelope model:
-
-```python
-class TemporalPipeJobEnvelope(BaseModel):
- """Lightweight wrapper that Temporal can deserialize without dynamic classes."""
- library_context: LibraryContext | None # None = use worker's base library
- library_dirs_fingerprint: str | None # Verify worker's base matches API's
- raw_pipe_job_payload: bytes # Pre-serialized PipeJob JSON
-```
-
-- `WfPipeRouter`: Accept `TemporalPipeJobEnvelope` instead of `PipeJob`. Call setup Activity if `library_context` is present, then manually `kajson.loads()` the raw payload.
-- Temporal data converter: No changes -- the envelope is a simple model that deserializes without dynamic classes
-
-**Impact on direct execution**: None. Only touches Temporal layer code.
-
-**Replay safety**: Same as Option A -- Activity-based.
-
-**Performance**: Minimal overhead -- one extra serialization/deserialization step.
-
-**Complexity**: Moderate. The main conceptual shift is that the workflow input type changes from `PipeJob` to `TemporalPipeJobEnvelope`.
-
----
-
-## 4. Key Dilemmas
-
-### 4.1 Where should library loading happen?
-
-| Location | Pros | Cons |
-|----------|------|------|
-| **Worker startup** (for base library) | Amortized cost, guaranteed availability, simple | Worker restart needed if base library changes. Only handles filesystem-available content. |
-| **Per-workflow Activity** (for additional content) | Guarantees correct version, handles per-request content | Adds latency per workflow (mitigated by caching) |
-| **Hybrid** (both) | Best of both worlds | Two loading paths to maintain |
-| **Shared filesystem** (workers mount same PIPELEXPATH) | Zero additional work -- Tier 1 handles everything | Requires deployment architecture where workers access same dirs |
-
-**Recommendation**: Hybrid, with shared filesystem as the primary deployment model. Base at startup, additional content per-workflow-with-caching. In practice, most deployments will share PIPELEXPATH, making Tier 1 sufficient for the vast majority of cases.
-
-### 4.2 Should PipeJob carry resolved pipes or just pipe codes?
-
-| Approach | Pros | Cons |
-|----------|------|------|
-| **Current** (resolved top-level only) | Minimal payload | Layer 2 breaks for children |
-| **All resolved** (flattened) | Self-contained, no library needed on worker | Bloats payload, forces refactoring of controllers |
-| **Codes only + worker-side resolution** | Cleanest -- worker resolves exactly like direct mode | Requires library on worker (but we need that for Layer 1 anyway) |
-
-**Recommendation**: Codes only + worker-side resolution. Once the library is loaded on the worker (which is necessary for Layer 1 regardless), pipe resolution works identically to direct execution. No changes to controllers or the PipeJob model.
-
-### 4.3 Dynamic class registration timing
-
-This is the crux of the Layer 1 problem:
-
-```
-Temporal automatically deserializes workflow input
- +-- Uses data converter -> kajson.loads()
- +-- Needs dynamic classes registered BEFORE this point
- +-- But workflow code hasn't run yet -> can't load library first
-```
-
-Three approaches:
-
-| Approach | How | Trade-off |
-|----------|-----|-----------|
-| **Pre-load at worker level** | Load base library at worker startup | Works for base concepts only. Additional content's concepts aren't available. |
-| **Deferred deserialization** (Option D) | Send raw bytes, deserialize manually after library setup | Changes workflow input type. Small conceptual overhead. |
-| **Lazy class resolution in Kajson** | Modify Kajson decoder to load classes on demand | Invasive change to a shared library. Complex. |
-
-**Recommendation**: Pre-load at worker level for base concepts (covers the majority of cases) + deferred deserialization for additional content (Option D handles it cleanly).
-
-### 4.4 Caching strategy
-
-Caching is only relevant for Tier 2 (per-workflow library context). For Tier 1 (PIPELEXPATH), the library is loaded once at worker startup and persists for the worker's lifetime.
-
-| Strategy | Cache key | Scope | Trade-off |
-|----------|-----------|-------|-----------|
-| **No caching** | -- | Always reload | Simple but wasteful |
-| **Content-hash** | `SHA256(library_context)` | Per unique context | Handles same content from different API calls |
-| **Library-ID** | `library_id` parameter | Per library instance | Uses existing `library_manager` multi-library support |
-
-**Recommendation**: Content-hash caching for Tier 2 overlays. The `library_manager` already supports multiple concurrent libraries keyed by `library_id`. Map content hashes to library IDs. The Activity checks: "is this fingerprint already loaded?" -> skip if yes.
-
-### 4.5 What if different workflows need different library contexts?
-
-The `library_manager` already supports multiple concurrent libraries, and `set_current_library()` uses a `ContextVar` so different async tasks can have different current libraries. On the worker, each workflow's setup Activity would set the appropriate library ID before executing.
-
-**Risk**: Dynamic class names could collide if two different contexts define the same concept code with different structures. Mitigation: prefix class names with a content hash, or validate that same-named concepts have identical structures.
-
-**Assessment**: This scenario only arises with API-provided content (Tier 2). For filesystem-based libraries (Tier 1), all workers load the same content. Worth noting but not a design blocker.
-
-### 4.6 How should the API evolve for multi-file packages?
-
-The current `mthds_content: str | None` parameter in `pipeline_run_setup()` handles only a single `.mthds` file. Real packages are multi-file with manifests and dependencies. The API needs to evolve.
-
-**Proposed model -- `LibraryContext`**:
-
-```python
-class BundleContent(BaseModel):
- """A single .mthds bundle file's content with its filename for domain identification."""
- filename: str # e.g., "contracts.mthds"
- content: str # The MTHDS TOML content
-
-class ResolvedDependencyRef(BaseModel):
- """A pre-resolved dependency reference (address + version already resolved)."""
- alias: str # The dependency alias in METHODS.toml
- address: str # Resolved package address
- version: str # Resolved version
-
-class LibraryContext(BaseModel):
- """Complete library context that can be shipped to a worker."""
- bundles: list[BundleContent] # One or more .mthds files
- manifest_content: str | None = None # METHODS.toml content
- resolved_dependencies: list[ResolvedDependencyRef] | None = None # Pre-resolved deps
- fingerprint: str # Hash for caching
-```
-
-**How `pipeline_run_setup()` would consume it**:
-
-The existing `mthds_content: str | None` parameter could be supplemented or replaced with a `library_context: LibraryContext | None` parameter. For backward compatibility, `mthds_content` could be sugar for a single-bundle `LibraryContext`.
-
-**How it flows to Temporal**:
-
-The `TemporalPipeJobEnvelope` carries `library_context`. The worker's `act_library_setup` Activity:
-
-1. Checks `fingerprint` against cache -- skip if already loaded
-2. Parses each bundle in `bundles` into a `PipelexBundleBlueprint`
-3. If `manifest_content` is present, parses it and enforces visibility
-4. If `resolved_dependencies` is present, loads dependency packages from installed methods (or fetches by address)
-5. Calls `library_manager.load_from_blueprints()` with all blueprints
-
-**What about dependencies that need fetching?**
-
-For production, dependency packages should be pre-installed on the worker (via `mthds install` or shared filesystem). The `resolved_dependencies` field provides the addresses for the worker to locate them. If a dependency is not installed, the Activity can attempt to fetch it (same as `library_manager` does today for address-based deps), but this adds latency and requires network access from the worker.
-
-**Recommendation**: Start with the `LibraryContext` model. The initial implementation can focus on the single-bundle case (wrapping current `mthds_content`). Multi-bundle support is a clear extension path without architectural changes.
-
----
-
-## 5. Recommendation
-
-**Recommended approach: Option A (base at startup) + Option D (deferred deserialization with `LibraryContext`)**
-
-### Tier 1 -- Base Library at Worker Startup (done)
-
-Already implemented in `worker_cli.py`. Workers load base libraries from `PIPELEXPATH` on startup. This fixes both layers for the majority of use cases where pipes and concepts come from filesystem-based packages.
-
-### Tier 2 -- Deferred Deserialization with LibraryContext
-
-For workflows with library content beyond the base:
-
-1. `PipeRouterTop` builds a `LibraryContext` from the current library state (capturing what was loaded beyond PIPELEXPATH)
-2. Serializes PipeJob to raw bytes
-3. Wraps both in a `TemporalPipeJobEnvelope`
-4. `WfPipeRouter` receives the envelope, runs `act_library_setup` Activity if `library_context` is present
-5. Manually deserializes PipeJob via `kajson.loads()` after library is loaded
-
-### Implementation Sequence
-
-1. **(Done)** Tier 1 -- base library loading in `worker_cli.py`
-2. **Integration test** -- Send a PipeSequence through Temporal with PIPELEXPATH-based library to validate Tier 1
-3. **Design `LibraryContext` model** -- Start with single-bundle wrapper for current `mthds_content` behavior
-4. **Implement deferred deserialization** (Option D) -- `TemporalPipeJobEnvelope`, `act_library_setup`, `WfPipeRouter` changes
-5. **Library fingerprint validation** -- Worker checks its base library matches API's expectation
-6. **Multi-bundle support** -- Extend `LibraryContext` to carry multiple bundles + manifest
-
-### Why Not the Others
-
-| Option | Why not |
-|--------|---------|
-| B (flatten pipes) | Doesn't fix Layer 1. High refactoring cost for marginal benefit -- once library is loaded (required for Layer 1 anyway), pipe resolution works for free. |
-| C (ship library snapshot) | Serializing resolved `Library` is impractical. The right version of this idea (reproduce from sources) is what `LibraryContext` does. |
-
----
-
-## 6. Appendix
-
-### PipeJob Model
-
-```python
-class PipeJob(BaseModel):
- pipe: PipeAbstract # The resolved pipe object
- working_memory: WorkingMemory # Runtime data store
- pipe_run_params: PipeRunParams # Run mode, multiplicity, pipe stack
- job_metadata: JobMetadata # Pipeline run ID, user ID, OTel context
- output_name: str | None = None # Override output variable name
-```
-
-PipeJob stays unchanged -- no `mthds_content` or library context added to it. Library context travels in the `TemporalPipeJobEnvelope` wrapper, separate from the job itself.
-
-### get_required_pipe() Call Sites in Controllers
-
-| Controller | File | Usage |
-|------------|------|-------|
-| PipeSequence | `pipe_controllers/sequence/pipe_sequence.py` | Resolves each `sub_pipe.pipe_code` in the sequence |
-| PipeCondition | `pipe_controllers/condition/pipe_condition.py` | Resolves the selected branch pipe from `outcome_map` |
-| PipeBatch | `pipe_controllers/batch/pipe_batch.py` | Resolves `branch_pipe_code` for each batch item |
-| PipeParallel | `pipe_controllers/parallel/pipe_parallel.py` | Resolves each parallel branch pipe |
-| SubPipe | `pipe_controllers/sub_pipe.py` | Used during validation |
-
-### Key Code Paths
-
-| What | Where |
-|------|-------|
-| Library loading (API-side) | `pipelex/pipeline/pipeline_run_setup.py` |
-| Hub singleton + get_required_pipe | `pipelex/hub.py` |
-| Library manager | `pipelex/libraries/library_manager.py` |
-| Dynamic concept class generation | `pipelex/core/concepts/concept_factory.py` |
-| Structure generator (creates classes) | `pipelex/core/concepts/structure_generation/generator.py` |
-| Kajson class registration | `pipelex/pipelex.py` (CoreRegistryModels) + `concept_factory.py` (dynamic) |
-| Kajson data converter (Temporal serde) | `pipelex/temporal/temporal_data_converter.py` |
-| Workflow definition | `pipelex/temporal/tprl_pipe/wf_pipe_router.py` |
-| Router (Temporal) | `pipelex/temporal/tprl_pipe/pipe_router_top.py` |
-| Router (direct) | `pipelex/pipe_run/pipe_router.py` |
-| Worker startup (Tier 1 -- already implemented) | `pipelex/temporal/worker_cli.py` |
-| MTHDS package manifest spec | `../mthds/docs/spec/manifest-format.md` |
-| Namespace resolution spec | `../mthds/docs/spec/namespace-resolution.md` |
-| Package loading algorithm | `../mthds/docs/implementers/package-loading.md` |
diff --git a/wip/archive/id-and-naming-plan-pre-checkpoints.md b/wip/archive/id-and-naming-plan-pre-checkpoints.md
deleted file mode 100644
index 10b243df2..000000000
--- a/wip/archive/id-and-naming-plan-pre-checkpoints.md
+++ /dev/null
@@ -1,279 +0,0 @@
-# Temporal IDs and Naming — Implementation Plan
-
-## Status
-
-Plan ready. Implements `id-and-naming-design.md` against the failing TDD gate in `tests/unit/pipelex/temporal/test_default_activity_id_collision_bug.py`. Aligned with the problem statement in `workflow-and-activity-ids.md` and the primitives reference in `temporal-id-primitives.md`.
-
-## Cold-start orientation
-
-A fresh session picking this up should read in this order:
-
-1. `wip/temporal-primitives/workflow-and-activity-ids.md` — the problem statement and the failing TDD gate that frames this work.
-2. `wip/temporal-primitives/temporal-id-primitives.md` — what Temporal's identifier and observability surface actually offers.
-3. `wip/temporal-primitives/id-and-naming-design.md` — the authoritative spec. If anything in this plan conflicts with the design doc, the design doc wins.
-4. This file — the sequencing of work and the per-phase done-when criteria.
-
-### Key code anchors
-
-The redesign rotates around these load-bearing locations. Open them before touching anything:
-
-- `pipelex/temporal/temporal_manager.py:95-110` — current top-level workflow_id construction; Phase 1 replaces it.
-- `pipelex/temporal/tprl/workflow_caller.py:84-87` — `make_workflow_id` delegator; Phase 1 simplifies it.
-- `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py:48-109` — the LRU + `_record_activity_id` machinery deleted in Phase 2.
-- `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py:111-528` — every `make_*` method whose `wfid` parameter and `activity_id=` argument are rewritten in Phase 2.
-- `pipelex/cogt/content_generation/content_generator_protocol.py` — `wfid` on every method; dropped in Phase 2.
-- `pipelex/temporal/tprl_pipe/wf_pipe_run.py:46` — hardcoded `f"{workflow_id}-pipe-router"` child id; separator flips to `/` in Phase 3.
-- `pipelex/temporal/tprl_pipe/temporal_pipe_router.py:55-87` — child + top dispatch branches rewritten in Phase 3.
-- `pipelex/temporal/tprl_pipe/temporal_pipe_run.py:43-65, 73-101` — top-level dispatch rewritten in Phase 3.
-- `pipelex/pipe_run/pipe_run_protocol.py`, `pipe_router_protocol.py` — non-Temporal protocols still carrying `wfid`; dropped in Phase 3.
-- `pipelex/pipelex.py:347` — worker-singleton instantiation of `ContentGeneratorInWorkflow`. Why this matters: the LRU exists *because* the disambiguator lived on this singleton; once the SDK assigns activity_ids, the singleton becomes plain stateless code and the LRU goes away.
-- `pipelex/pipeline/pipeline_factory.py:17` — `make_pipeline_run_id` (UUID, unchanged; we just stop ignoring its output).
-- `pipelex/pipeline/job_metadata.py:43` — `JobMetadata.pipeline_run_id` (the canonical identity, unchanged).
-- `tests/unit/pipelex/temporal/test_default_activity_id_collision_bug.py` — the TDD gate. Run it on entry to confirm it is red; it must be green after Phase 2.
-
-### The fact that unblocks the protocol cleanup
-
-A grep at design time confirmed: **no production code passes a non-`None` `wfid`**. Every `wfid=` call site is in `tests/`. That is the empirical reason it is safe to drop the parameter from `PipeRunProtocol`, `PipeRouterProtocol`, and `ContentGeneratorProtocol` without a deprecation cycle. Re-run the grep if time has passed:
-
-```bash
-grep -rn "wfid=" pipelex/ | grep -v "wfid=None" | grep -v "wfid: str"
-```
-
-If this returns anything, stop and reassess before touching protocols.
-
-### Verification commands
-
-The "Done when" criteria in each phase reference these checks:
-
-```bash
-# Run the failing TDD gate (red on entry; green after Phase 2)
-.venv/bin/pytest -v tests/unit/pipelex/temporal/test_default_activity_id_collision_bug.py
-
-# Phase 2 done: no wfid in the activity layer
-grep -rn "wfid" pipelex/cogt/ pipelex/temporal/tprl_content_generation/
-
-# Phase 3 done: no wfid anywhere in pipelex/
-grep -rn "wfid" pipelex/
-
-# Quality gates (every phase)
-make agent-check
-make agent-test
-```
-
-### Tooling
-
-- `make agent-check` — runs ruff (fix-unused-imports, lint, format), pyright, mypy, plxt. Silent on success, full output on failure.
-- `make agent-test` — runs the test suite the same way. Use this, not `make test`.
-- `/temporal-e2e-validate` — slash-command skill (declared in the agent's skill list) that validates Temporal distributed execution against a real server. Use it once Phase 3 lands to confirm the new identity model end-to-end.
-- Integration tests support `--temporal-server local|testing|<profile>` — see CLAUDE.md "Temporal Integration Test Options."
-
-## How to use this plan
-
-Four phases, each independently mergeable. Every phase ends with `make agent-check` and `make agent-test` green. Checkpoints between phases are explicit handoff points: the next session can pick up cold by reading this doc + the checkpoint notes filled in by the previous session.
-
-The phase ordering is chosen so that the bug fix (Phase 2) lands as early as possible: foundations first, then the activity-layer rewrite that flips the TDD gate green, then the workflow-layer rewrite, then deployment & docs. Phases 3 and 4 can be reordered or parallelized if needed; Phases 1 and 2 must run in this order.
-
-Each phase section answers the same four questions: **What lands**, **Files touched**, **Tests**, **Done when**. The change set in the design doc is the authoritative spec for every file change — this plan only sequences the work.
-
----
-
-## Phase 1 — Foundations (additive only)
-
-**What lands.** A new `observability.py` helper module, a renamed/simplified `make_top_workflow_id` on `TemporalManager`, and additive `search_attributes` / `static_summary` / `static_details` / `memo` parameters on `WorkflowExecutor.execute_workflow` / `start_workflow`. No call site uses the new infrastructure yet. No behavior changes for end users.
-
-**Files touched.**
-
-- `pipelex/temporal/tprl/observability.py` (new) — five pure-function helpers:
- - `build_search_attributes(pipe_job: PipeJob) -> Mapping[str, list[str]]`
- - `build_search_attributes_for_child(child_pipe_job: PipeJob, parent_search_attrs: Mapping[str, list[str]]) -> Mapping[str, list[str]]`
- - `build_static_summary(pipe: PipeBase) -> str`
- - `build_static_details(pipe_job: PipeJob, library_crate_id: str | None) -> str`
- - `build_activity_summary(method_label: str, job_metadata: JobMetadata, **extras: str) -> str`
-- `pipelex/temporal/temporal_manager.py` — replace `make_top_workflow_id(base_id: str)` with `make_top_workflow_id(pipeline_run_id: str)`. The session-id and random-id truncations are deleted; `self.session_id` stays as an instance field so the search-attribute helper can read it.
-- `pipelex/temporal/tprl/workflow_caller.py` — `WorkflowExecutor.execute_workflow` / `start_workflow` gain optional `search_attributes`, `static_summary`, `static_details`, `memo` parameters that pass through to the Temporal SDK. `make_workflow_id(base_id: str)` is renamed to `make_workflow_id(pipeline_run_id: str)`.
-
-**Tests.**
-
-- `tests/unit/pipelex/temporal/test_observability_helpers.py` (new) — unit tests for every helper, including 200-byte UTF-8 truncation behavior, `pipe.description` absent/present, child-attribute inheritance.
-- Existing tests using the old `make_top_workflow_id(base_id=...)` signature update to the new parameter name. The only legitimate caller in production code is `WorkflowExecutor.make_workflow_id`, and that's the same change. Tests that asserted on the old `{session5}-{rand5}-{base_id}` shape are tagged for rewrite in Phase 3 — for now they continue to assert the (transitional) format the manager produces.
-
-**Done when.**
-
-- `make agent-check` clean.
-- `make agent-test` green. The TDD gate test in `test_default_activity_id_collision_bug.py` is still red (expected — Phase 2 fixes it).
-- The new helpers have unit-test coverage for the formats specified in the design doc.
-
-### Checkpoint — end of Phase 1
-
-To be filled in by the implementer at the phase boundary so the next session can pick up cleanly.
-
-- **Status.** _(planned / in progress / merged)_
-- **PR / branch.** _(URL)_
-- **Code state.** _(any deviations from this plan, helper function signatures actually shipped, edge cases discovered)_
-- **Open questions deferred.** _(any decisions that surfaced during implementation that we punted)_
-- **Handoff notes for Phase 2.** _(anything Phase 2 needs to know: gotchas in helper APIs, conftest changes that affect downstream test layout, etc.)_
-
----
-
-## Phase 2 — Activity-layer rewrite (TDD gate green)
-
-**What lands.** The bug fix. `ContentGeneratorInWorkflow` stops customizing `activity_id`, the worker-singleton LRU is deleted, the `wfid` parameter is dropped from `ContentGeneratorProtocol` and every implementation, and every `workflow.execute_activity(...)` call carries a `summary=` derived from the helpers. The TDD gate in `test_default_activity_id_collision_bug.py` flips green naturally.
-
-**Files touched.**
-
-- `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py`:
- - Delete `_seen_activity_ids`, `_MAX_SEEN_RUNS`, `_record_activity_id`, and every call site of `_record_activity_id`.
- - Drop the `wfid` parameter from every `make_*` method.
- - Drop the `activity_id = wfid or "…"` line and the `activity_id=...` argument from every `workflow.execute_activity(...)` call.
- - Add `summary=build_activity_summary(...)` per the format table in the design doc.
-- `pipelex/cogt/content_generation/content_generator_protocol.py` — drop `wfid` from every `make_*` method signature.
-- `pipelex/cogt/content_generation/content_generator.py` (direct mode) — drop `wfid`.
-- `pipelex/cogt/content_generation/content_generator_dry.py` (dry mode) — drop `wfid`.
-
-**Tests.**
-
-- `tests/unit/pipelex/temporal/test_default_activity_id_collision_bug.py` — flips green. The second test (`test_two_make_llm_text_calls_with_same_explicit_wfid_should_succeed`) cannot pass `wfid` anymore; it collapses into the first test and either is deleted or kept as a duplicate regression gate (recommend keeping one canonical gate test, deleting the other).
-- `tests/unit/pipelex/temporal/test_content_generator_in_workflow.py`:
- - Delete `test_make_llm_text_threads_explicit_wfid`, `test_duplicate_wfid_raises_content_generation_error`, `test_default_wfids_for_image_methods_are_distinct`.
- - Add `test_make_llm_text_omits_activity_id_and_sets_summary` (and equivalents per method) — asserts `mock_execute.call_args.kwargs.get("activity_id") is None` and `summary` matches the formatted helper output.
-- Any other test in `tests/unit/` / `tests/integration/` that passes `wfid=` to a `make_*` content-generator method is updated to remove the kwarg.
-
-**Done when.**
-
-- `make agent-check` clean.
-- `make agent-test` green.
-- `test_default_activity_id_collision_bug.py` is green.
-- Grep confirms zero remaining references to `wfid` in `pipelex/cogt/` and `pipelex/temporal/tprl_content_generation/`.
-- Manual smoke (optional, recommended): run a multi-step pipe via the `temporal-e2e-validate` skill and confirm in the Temporal dashboard's Event History that activity ids are now `"1"`, `"2"`, … with purple-text per-activity summaries.
-
-### Checkpoint — end of Phase 2
-
-To be filled in by the implementer at the phase boundary.
-
-- **Status.** _(planned / in progress / merged)_
-- **PR / branch.** _(URL)_
-- **TDD gate.** _(confirmed green: yes/no, link to CI run)_
-- **Code state.** _(LRU deletion confirmed, residual TODOs, anything surprising about the existing tests that touched wfid)_
-- **Open questions deferred.** _(e.g. should we keep one or both of the test_default_activity_id_collision_bug cases as the canonical gate?)_
-- **Handoff notes for Phase 3.** _(state of pipe_run/* protocols — still carrying wfid as no-op; state of temporal_pipe_run/router — still using old workflow_id shape and still threading wfid)_
-
----
-
-## Phase 3 — Workflow-layer rewrite + protocol cleanup
-
-**What lands.** Workflow IDs switch to `{env_prefix}{pipeline_run_id}`. Child workflow IDs switch to slash-separated paths. Search attributes and static summary land on every workflow start. `wfid` is dropped from `PipeRunProtocol`, `PipeRouterProtocol`, and the remaining implementations. Tests assert the new identity model.
-
-**Files touched.**
-
-- `pipelex/temporal/tprl_pipe/temporal_pipe_run.py`:
- - Drop the `wfid` parameter from `run(...)` and `start(...)`.
- - `workflow_id` is built from `pipe_job.job_metadata.pipeline_run_id` via the renamed manager method.
- - Pass `search_attributes`, `static_summary`, `static_details` to `executor.execute_workflow` / `start_workflow` using the helpers.
-- `pipelex/temporal/tprl_pipe/temporal_pipe_router.py`:
- - Drop the `wfid` parameter from `_run_pipe_job(...)`.
- - Top-level branch mirrors `temporal_pipe_run.py`.
- - Child branch: `child_workflow_id = f"{parent_workflow_id}/{pipe_job.pipe.code}-{str(workflow.uuid4())[:8]}"`. Pass `search_attributes` updated for the child via `build_search_attributes_for_child`.
-- `pipelex/temporal/tprl_pipe/wf_pipe_run.py`:
- - Line 46: switch the separator from `-` to `/`: `id=f"{workflow.info().workflow_id}/pipe-router"`.
- - Pass `search_attributes=` (re-using the parent's, since the child is the same pipe) to the `execute_child_workflow` call.
-- `pipelex/pipe_run/pipe_run.py` and `pipe_run_protocol.py` — drop `wfid` from `run(...)`.
-- `pipelex/pipe_run/pipe_router.py`, `pipe_router_protocol.py`, `dry_pipe_router.py` — drop `wfid` from `run(...)` / `_run_pipe_job(...)`.
-- Any remaining call sites of these protocols in tests update to not pass `wfid`.
-
-**Tests.**
-
-- `tests/unit/pipelex/temporal/test_workflow_id_construction.py` (new) — asserts:
- - Top-level: `{env_prefix}{pipeline_run_id}` for each `RunMode`.
- - Fixed-role child: `{parent}/pipe-router`.
- - Dynamic child: `{parent}/{pipe_code}-{8-hex-chars}`.
-- `tests/unit/pipelex/temporal/test_search_attribute_dict_construction.py` (new) — asserts the five-keyed dict from a representative `pipe_job`, plus the child-attribute inheritance / override rule.
-- Existing tests that asserted the old workflow_id shape (`{session5}-{rand5}-{ClassName}`) are rewritten to assert the new shape.
-- Integration tests under `tests/integration/pipelex/temporal/` continue to pass without modification (they don't inspect the workflow_id shape); if any does, it's rewritten.
-- Run the `temporal-e2e-validate` skill end-to-end as a final cross-check.
-
-**Done when.**
-
-- `make agent-check` clean.
-- `make agent-test` green.
-- Grep confirms zero remaining `wfid` references in `pipelex/`.
-- A manual run in the Temporal dashboard shows: top-level workflow ID = the `pipeline_run_id` (with env prefix); child workflow IDs are slash-separated paths; the `PipeCode`, `PipelineRunId`, `SessionId`, `UserId`, `DomainCode` search attributes are populated on every workflow row; static summary shows `{pipe_code} — {description}`.
-
-### Checkpoint — end of Phase 3
-
-To be filled in by the implementer at the phase boundary.
-
-- **Status.** _(planned / in progress / merged)_
-- **PR / branch.** _(URL)_
-- **Code state.** _(all wfid removed, workflow_id shape live, dashboard verified)_
-- **Operational notes.** _(in test runs, did the soft-fail warning for unregistered search attributes fire? Anything in the integration test suite that needs adjusting for the new dashboard expectations?)_
-- **Open questions deferred.** _(e.g. did we settle on whether to delete one of the two TDD gate tests, the dynamic-child uuid8 length, etc.)_
-- **Handoff notes for Phase 4.** _(state of search attribute coverage; whether any namespace has been pre-registered with the five attributes; what the deployment runbook needs to cover)_
-
----
-
-## Phase 4 — Deployment hooks, docs, CHANGELOG
-
-**What lands.** A bootstrap soft-fail check that warns when required custom search attributes are missing on the namespace. A new docs section explaining the one-time registration step. A CHANGELOG entry covering every breaking change.
-
-**Files touched.**
-
-- `pipelex/temporal/temporal_task_manager.py` (or wherever the worker boot lives) — add a `DescribeNamespace` call on worker start; if any of the five attributes is missing, log a warning that includes the exact `temporal operator search-attribute create` command. Soft fail only — in-process test servers and dev environments without registration continue to run.
-- `docs/temporal-deployment.md` (new) — section on required custom search attributes and how to register them. Cross-link from any existing Temporal-related docs.
-- `CHANGELOG.md` — `[Unreleased]` entry covering:
- - Workflow ID shape change (`{env}{session5}-{rand5}-{ClassName}` → `{env_prefix}{pipeline_run_id}`).
- - Child workflow ID separator change (`-` → `/`).
- - Activity ID change (semantic labels → SDK-default integers).
- - `wfid` parameter removed from `PipeRunProtocol`, `PipeRouterProtocol`, `ContentGeneratorProtocol`, and every implementation.
- - New required custom search attributes on the Temporal namespace.
-
-**Tests.**
-
-- `tests/unit/pipelex/temporal/test_search_attribute_bootstrap_check.py` (new) — mocks `DescribeNamespace` to return (a) all attributes present (no warning), (b) some missing (warning logged with exact command).
-
-**Done when.**
-
-- `make agent-check` clean.
-- `make agent-test` green.
-- Docs preview renders the new section.
-- CHANGELOG entry written in the project's voice (one line per breaking change is fine).
-- `temporal-e2e-validate` skill run on a clean namespace (without the attributes registered) emits the warning; with attributes registered, runs cleanly.
-
----
-
-## Cross-phase risks and mitigations
-
-- **Integration tests that asserted on workflow_id shape.** Scan early (during Phase 1) for tests that match on workflow_id substrings. Catch them in the right phase rather than waiting for CI breakage.
-- **`make_top_workflow_id` callers outside `WorkflowExecutor`.** A grep confirms there is exactly one production caller (`WorkflowExecutor.make_workflow_id`). If a stray caller is found, update it in Phase 1.
-- **Namespace registration in CI.** CI's in-process Temporal server skips search-attribute registration. Confirm in Phase 4 that the soft-fail warning is downgraded (or suppressed entirely) for the in-process server mode — otherwise CI logs fill with the warning.
-- **Replay-safety regression.** The deletion of the LRU + `is_replaying()` short-circuit is correct *because* the disambiguator stops coming from worker-singleton state. If a future change re-introduces worker-singleton state into the activity dispatch path, the determinism guarantee breaks. Phase 2's PR description calls this out so reviewers know to push back on any reintroduction.
-- **`pipe_job.pipe.code` empty in pathological inputs.** The child workflow ID format depends on `pipe_job.pipe.code` being non-empty. Add a defensive fallback (`pipe_job.pipe.code or "pipe"`) in `temporal_pipe_router.py` if a unit test exercises an empty-code path; otherwise rely on existing invariants.
-
-## Test plan (cumulative across phases)
-
-By the end of Phase 4, the following must be green:
-
-- All existing `make agent-test` tests.
-- The TDD gate tests in `test_default_activity_id_collision_bug.py`.
-- The new unit tests added in Phases 1, 3, 4 (observability helpers, workflow_id construction, search attribute dict, bootstrap check).
-- The Temporal integration test suite (`tests/integration/pipelex/temporal/`) with `--temporal-server local` and `--temporal-server testing` profiles for the dev environments that have those configured.
-- The `temporal-e2e-validate` skill against a real Temporal server with the five search attributes registered.
-
-## Open questions deferred to implementation
-
-Captured here so they are not lost between sessions. Each can be settled inside the relevant phase without re-opening the design.
-
-- **Helper module location.** `pipelex/temporal/tprl/observability.py` is the proposed home. If existing structure in `pipelex/temporal/` suggests a different submodule (e.g. `pipelex/temporal/identity/`), the implementer picks; the design does not depend on the path.
-- **One canonical gate test vs two.** The two failing tests in `test_default_activity_id_collision_bug.py` collapse into one after Phase 2 (`wfid` parameter gone, so they exercise the same code path). Keep one, delete the other.
-- **`pipe_job.pipe.code or "pipe"` fallback.** Decide in Phase 3 whether a defensive fallback is warranted or whether the existing invariants make it dead code.
-- **Static details "Input" line.** The design says "best-effort, omit when unavailable." The implementer picks the exact derivation (working_memory keys list, pipe inputs blueprint, etc.) — whatever is cheapest and least likely to grow over time.
-- **Soft-fail warning in CI.** Whether to suppress the warning entirely for the in-process test server or just downgrade its level. Decide in Phase 4 based on actual CI log noise.
-
-## Out of scope (per the design doc)
-
-These do **not** ship in this plan. They are listed here so they don't accidentally creep in:
-
-- `workflow.set_current_details(...)` for in-flight progress.
-- Memo population beyond the optional `library_crate` fingerprint.
-- Per-pipe Workflow Type registration.
-- Search attribute schema versioning / migration tooling.
-- An optional `display_label` parameter at the `PipeRun` entry point.
diff --git a/wip/archive/kajson-decoder-class-registry.md b/wip/archive/kajson-decoder-class-registry.md
deleted file mode 100644
index c262e0c9e..000000000
--- a/wip/archive/kajson-decoder-class-registry.md
+++ /dev/null
@@ -1,63 +0,0 @@
-# Kajson Decoder: ClassRegistry Fallback Not Reached for Dynamic Classes
-
-## Problem
-
-The Kajson JSON decoder (`kajson/json_decoder.py:140-153`) resolves classes in three steps:
-
-1. **Line 140-150**: If `module_name` is in `sys.modules`, use `getattr(sys.modules[module_name], class_name)`. If not found, raise `KajsonDecoderError`.
-2. **Line 151-153**: Else, try `KajsonManager.get_class_registry().get_class(name=class_name)`.
-3. **Line 155+**: Else, try `importlib.import_module(module_name)` and `getattr`.
-
-The ClassRegistry lookup (step 2) only runs when the module is NOT in `sys.modules`. Dynamic classes generated at runtime (e.g., `GreetingContent` from inline concept structures) are registered in the ClassRegistry with `__module__` set to `"builtins"`. Since `builtins` is always in `sys.modules`, the decoder takes step 1, does `getattr(builtins, "Greeting")`, fails, and raises at line 150 — **never reaching the ClassRegistry fallback at line 151**.
-
-## How It Manifests
-
-In a Temporal PipeSequence with dynamic concepts:
-
-1. Parent workflow dispatches a child workflow (e.g., `generate_greeting` PipeLLM)
-2. Child workflow executes successfully, produces `PipeOutput` with `Greeting` StructuredContent
-3. Child result is serialized by Kajson with `__class__: "Greeting"`, `__module__: "builtins"`
-4. Parent workflow receives the child result — Kajson decoder does `getattr(sys.modules["builtins"], "Greeting")` → `AttributeError` → `KajsonDecoderError` at line 150
-5. The ClassRegistry (line 151), which DOES have the `Greeting` class registered, is never consulted
-
-## Why In-Process Tests Pass
-
-The integration test runs the worker in-process (`is_not_sandboxed=True`). The test fixture pre-loads the blueprint globally, which registers the dynamic class in the ClassRegistry. Since the class was generated in the same process, `StructureGenerator` may also place it in a module that makes `getattr` succeed. With a **separate** worker process, the dynamic class is only in the ClassRegistry (loaded from the crate), not in any importable module attribute.
-
-## Verified via Manual Test
-
-Using `/temporal-diagnose` with a 3-process setup (Temporal server + separate worker + job submitter), the `dynamic_concept_sequence.mthds` bundle fails with:
-
-```
-KajsonDecoderError: Class 'Greeting' not found in module 'builtins'
-```
-
-The worker logs show the child workflow result deserialization failing at `_convert_payloads` in the Temporal SDK, which calls `kajson.loads()`.
-
-## Proposed Solution
-
-In `kajson/json_decoder.py`, when the module IS in `sys.modules` but `getattr` fails (line 149-150), fall back to the ClassRegistry before raising:
-
-```python
-# Current (line 149-150):
-else:
- raise KajsonDecoderError(f"Class '{class_name}' not found in module '{module_name}'")
-
-# Proposed:
-else:
- # Module is loaded but class not found as attribute — try ClassRegistry
- # (handles dynamic classes registered at runtime, including scoped registries)
- registered_class = KajsonManager.get_class_registry().get_class(name=class_name)
- if registered_class is not None:
- the_class = registered_class
- else:
- raise KajsonDecoderError(f"Class '{class_name}' not found in module '{module_name}' or ClassRegistry")
-```
-
-This preserves the existing priority (module attribute first, registry second) and only changes behavior when `getattr` fails for a non-generic class.
-
-## Dependencies
-
-- Scoped registry teardown (token-based, see `wip/scoped-registry-teardown.md`) should be implemented first, so the decoder uses the correct scoped registry in concurrent workflow scenarios
-- The Kajson decoder change should be tested with both global and scoped registry scenarios
-- The `hub.get_class_registry()` → `KajsonManager.get_class_registry()` change (already applied in `pipelex/hub.py`) is complementary — it fixes explicit lookups (e.g., `StuffContentFactory`) while this fix covers Kajson deserialization
diff --git a/wip/archive/offline-mode-remote-config-cache.md b/wip/archive/offline-mode-remote-config-cache.md
deleted file mode 100644
index 825b40197..000000000
--- a/wip/archive/offline-mode-remote-config-cache.md
+++ /dev/null
@@ -1,537 +0,0 @@
-# Offline Mode & Remote Config Cache — Implementation Plan
-
-> Branch: `fix/Offline-mode`
-> Working dir: `/Users/lchoquel/repos/Pipelex/_off` (worktree of `pipelex/`)
-
-## Objectives (verbatim from user)
-
-1. **Fully support offline mode when gateway is disabled** — no remote config fetch is ever attempted; setup completes without network.
-2. **Support dry-run mode when gateway is enabled but the remote config is temporarily unavailable**, even when the bundle references gateway models. Implies a cache that must be **primed at the time Pipelex first creates its local or global config**, and refreshed on every successful subsequent fetch.
-3. **Fail if requested gateway models don't exist** according to the fresh remote config (when available) or the cached one (when that's all we have). No silent fallbacks.
-
-## Non-objectives
-
-- We are not removing the remote fetch. We are adding resilience.
-- We are not granting offline inference *runs* through the gateway (the gateway itself still needs network at call time). We're talking about *setup* and *dry-run* working offline. Real inference calls fail as they always have when the network is down.
-- We are not bundling a baked-in snapshot in the package.
-
-## Failure point (already diagnosed)
-
-- `pipelex/pipelex.py:202` — `effective_needs_model_specs = needs_model_specs if needs_model_specs is not None else needs_inference`. When the agent CLI passes `needs_model_specs=True` explicitly (it does for `validate`, `inputs`, and `run --dry-run`), this is `True` regardless of `needs_inference`.
-- `pipelex/pipelex.py:235` — unconditionally calls `RemoteConfigFetcher.fetch_remote_config()` when `is_pipelex_service_enabled and effective_needs_model_specs`. Raises `RemoteConfigFetchError` on any network failure.
-- `pipelex/system/pipelex_service/remote_config_fetcher.py:93` — only short-circuits for Codex *Cloud* (`runtime_manager.is_in_codex_cloud`). The cache fallback added below also solves the local-sandbox case incidentally; no new sandbox detection is needed.
-
-## Design overview
-
-### Cache contract
-
-- Location: `~/.pipelex/cache/remote_config.json` (global, single-user). Schema-versioned and timestamped.
-- **Stored payload is the raw JSON dict** returned by `response.json()`, NOT a re-serialized Pydantic model. This avoids any Pydantic round-trip quirks (e.g. `extra="allow"` semantics across `model_dump()` modes) and keeps the cache stable against minor schema drift. On load: `RemoteConfig.model_validate(payload["raw_config"])`.
-- The remote config URL is versioned in `pipelex-back-office` (we control both ends). Schema bumps are handled by bumping both the URL version AND the cache `SCHEMA_VERSION` constant; older caches are then rejected (return `None`) and clients re-prime on next online fetch.
-- **Atomic writes**: `tempfile.NamedTemporaryFile(dir=cache_dir, delete=False)` → write → `os.replace(tmp_path, cache_path)`. Prevents corrupted-cache from concurrent writes.
-- Written by:
- - `RemoteConfigFetcher.fetch_remote_config()` on every successful fetch (opportunistic refresh).
- - The init flow when gateway terms are accepted (priming step).
-- Read by:
- - `RemoteConfigFetcher.fetch_remote_config()` when the network call fails, as a fallback.
-- Never read for any other purpose. Cache is a **last resort**, not a freshness optimisation.
-
-### New types
-
-- `CachedRemoteConfig` — Pydantic `BaseModel` wrapping the cached payload metadata: `cached_at: datetime`, `cache_schema_version: int`, `raw_config: dict[str, Any]` (the raw remote payload). Use `datetime.timezone.utc`, not `datetime.UTC`.
-- `RemoteConfigSource` — `StrEnum` from `pipelex.types` with **lowercase string values** to match codebase convention: `FRESH = "fresh"` | `CACHED = "cached"`.
-- `RemoteConfigResult` — Pydantic `BaseModel` (`ConfigDict(extra="forbid", strict=True)`) carrying `config: RemoteConfig`, `source: RemoteConfigSource`, `cached_at: datetime | None = None`. NOT a dataclass; match project convention.
-
-### New / preserved exceptions (in `pipelex/system/pipelex_service/exceptions.py`)
-
-- **Keep** `RemoteConfigFetchError` as the existing internal exception raised by the retry layer when the network fails. Do NOT remove it — it's already caught by `doctor_cmd.py:745`, `cli_factory.py:73`, `error_handlers.py:365`, and the agent CLI hints (`agent_output.py:51`). Removing it breaks those surfaces.
-- **Add** `RemoteConfigUnavailableError(PipelexServiceError)` as a sibling — raised when fetch failed AND no usable cache exists. Message names the cache path and remediation (`pipelex init` while online; or disable gateway in `backends.toml` as the offline-permanent alternative).
-- **Add** `GatewayUnknownModelError(PipelexServiceError)` — raised when a bundle references a gateway model that isn't present in the (fresh or cached) gateway specs. Carries a `source: RemoteConfigSource` field; message branches: when `CACHED`, hint that the remote config is stale and suggest `pipelex init` while online.
-- **Add** `RemoteConfigStaleWarning(UserWarning)` — emitted when `source == CACHED` during setup. Lives next to `GatewayOverrideWarning` in `exceptions.py`.
-
-### Wiring in `pipelex.py`
-
-- `setup()` keeps calling `RemoteConfigFetcher.fetch_remote_config()`, but the fetcher now returns a `RemoteConfigResult`.
-- The `source` is **NOT stored on `GatewayConfig`** (which keeps `extra="forbid"` and stays a pure value object describing the gateway). Instead, `setup()` passes `gateway_config_source: RemoteConfigSource` separately to `models_manager.setup()` → `BackendLibrary` so the model-membership check can branch its error message on fresh-vs-cached.
-- When `source == CACHED`:
- - `is_pipelex_telemetry_enabled` stays `False` (already disabled without inference; this is a separate, stricter guard for stale operation). Add an explicit test for this.
- - Emit `RemoteConfigStaleWarning` via `warnings.warn(...)`.
- - The agent CLI `agent_success(...)` envelope surfaces a structured `warnings: [{"type": "RemoteConfigStale", "cached_at": "..."}]` field so machine consumers see it.
-
-### Doc / fixture generators must refuse stale data
-
-`gateway_models_generator.py:46` and `preprocess_test_models_cmd.py:98` regenerate **committed** reference docs and test fixtures from the remote config. If they silently fall back to cache, they'll bake stale data into the repo.
-
-- Add a `require_fresh: bool = False` argument to `fetch_remote_config()` (or expose a thin `fetch_remote_config_fresh_only()` wrapper) that raises `RemoteConfigUnavailableError` immediately if `source == CACHED`.
-- Both dev-CLI generators set it; everyone else doesn't.
-- Add a unit test that this branch raises when only cache is available.
-
-### Behaviour matrix to validate
-
-| Scenario | Gateway enabled | Network | Cache | Expected |
-|---|---|---|---|---|
-| BYOK offline | no | down | n/a | setup OK, validate OK, dry-run OK, inference OK if backend reachable |
-| Gateway dry-run, fresh | yes | up | n/a | fresh fetch, dry-run OK |
-| Gateway dry-run, cached | yes | down | present | cache fallback, warning, dry-run OK |
-| Gateway dry-run, cold | yes | down | absent | `RemoteConfigUnavailableError` with clear remediation |
-| Gateway inference, cached | yes | down | present | cache fallback, inference still fails when call is made (network); error message attributes the failure to the gateway call, not setup |
-| Bundle references unknown model | yes | up or down | any | `GatewayUnknownModelError` during library load (message branches on source) |
-| Doc generator offline w/ cache | yes | down | present | `RemoteConfigUnavailableError` (require_fresh=True refuses cache) |
-
----
-
-## Working agreements
-
-- TDD throughout. Red → green for every functional unit.
-- Integration tests declare **blueprints in Python** and exercise the public APIs (`Pipelex.make`, `RemoteConfigFetcher`, `BackendLibrary`, etc.). They go under `tests/integration/pipelex/`.
-- E2E tests use **actual `.mthds` bundle files** placed in `tests/e2e/data/offline_mode/` and drive them via `mthds-agent run bundle ... --dry-run --mock-inputs` (subprocess), the same surface that fails today.
-- Follow `.claude/rules/python-standards.md`:
- - 1 TestClass per test module.
- - `StrEnum` from `pipelex.types`.
- - Never `except Exception` outside CLI roots. Use `from pytest_mock import MockerFixture`; never `unittest.mock`.
- - `make agent-check` after code changes, `make agent-test` at session boundaries.
-- No backward compatibility shims. If we rename or change a signature, just change it.
-- **No test-aware production code**: do NOT introduce a `PIPELEX_TEST_BLOCK_REMOTE_FETCH` env var. Use the legitimate `PIPELEX_REMOTE_CONFIG_URL` override (see Phase 5) to point at an unreachable URL.
-
-## Cold-start handoff protocol
-
-After every `🛑 CHECKPOINT` line:
-
-1. Re-read this `TODOS.md` and mark just-completed checkboxes.
-2. Append a `### Checkpoint N status` subsection at the bottom of this file capturing:
- - What landed (paths of new/modified files).
- - Open decisions / unknowns.
- - The exact next checkbox to start with.
-3. Run `make agent-check && make agent-test`. Note pass/fail in the checkpoint status.
-4. Stop. A new session takes over from the status block.
-
----
-
-## Phase 0 — Lock down current behaviour (no production code changes)
-
-- [x] **0.1** Add `tests/integration/pipelex/system/pipelex_service/test_offline_baseline.py` with `TestOfflineBaseline` covering the baseline that must NOT regress: BYOK-offline succeeds, gateway-offline-without-cache raises today. Write these as **passing tests against current behaviour** (do not write "expected-to-fail" tests). In Phases 2/3 they will be updated as semantics legitimately change, not "flipped." Use `mocker.patch("httpx.get", side_effect=httpx.ConnectError(...))`.
-- [x] **0.2** Confirm by running the new tests that `Pipelex.make(needs_inference=False, needs_model_specs=True)` with gateway disabled (BYOK backend only) succeeds offline. If it does not, file a sub-task here before continuing — a phantom network call somewhere has to be tracked down. **Note**: 3.2 will add an explicit regression guard for this; 0.2 is the one-time confirmation.
-- [x] **0.3** Run `make agent-check && make agent-test`. Record output in the checkpoint status.
-
-🛑 **CHECKPOINT 0** — Baseline pinned. Cold-start safe: new session can pick up from Phase 1 with confidence about what already works.
-
----
-
-## Phase 1 — Cache module (TDD, isolated, no integration yet)
-
-**Goal:** stand up `RemoteConfigCache` with no other code calling it yet. Pure read/write/version logic.
-
-- [x] **1.1** Write failing tests first: `tests/unit/system/pipelex_service/test_remote_config_cache.py` with `TestRemoteConfigCache`:
- - `test_write_then_read_roundtrip` — writes a config, reads it back, asserts equality + non-stale timestamp.
- - `test_read_missing_returns_none` — no cache file → `None` (no exception).
- - `test_read_corrupted_json_returns_none_and_logs` — file exists but isn't JSON → returns `None`, logs a warning. (Use `caplog`.)
- - `test_read_wrong_schema_version_returns_none` — file from a different schema version → returns `None`.
- - `test_write_creates_parent_dir` — cache dir doesn't exist yet → created.
- - `test_cache_path_uses_global_config_dir` — path lives under `config_manager.global_config_dir / "cache" / "remote_config.json"`.
- - `test_write_is_atomic` — simulate failure between write-to-tmp and `os.replace` (e.g. via `mocker.patch("os.replace", side_effect=OSError)`); assert no partial file at the destination path.
- - `test_raw_payload_extras_preserved` — store a payload with an unknown top-level key, load it back, pass through `RemoteConfig.model_validate(...)`, and assert the unknown key is still on the resulting model (Pydantic `extra="allow"` semantics). Guards the cache-integrity invariant.
-- [x] **1.2** Implement `pipelex/system/pipelex_service/remote_config_cache.py`:
- - `class RemoteConfigCache` with `@classmethod load() -> CachedRemoteConfig | None` and `@classmethod store(remote_config_payload: dict[str, Any]) -> None`. **The `store` argument is the raw JSON dict from `response.json()`, not a `RemoteConfig` instance.**
- - JSON file format on disk: `{"schema_version": 1, "cached_at": "<iso>", "raw_config": { ... raw remote payload ... }}`.
- - Atomic write via `tempfile.NamedTemporaryFile(dir=cache_dir, delete=False)` + `os.replace`.
- - Catch only `OSError`, `JSONDecodeError`, `ValidationError` — never bare `Exception`.
-- [x] **1.3** Add `CachedRemoteConfig` Pydantic model alongside `RemoteConfigCache`. Fields: `schema_version: int`, `cached_at: datetime`, `raw_config: dict[str, Any]`. Use `datetime.timezone.utc` (Python 3.10 compatibility). Provide a `to_remote_config()` helper that returns `RemoteConfig.model_validate(self.raw_config)`.
-- [x] **1.4** `make agent-check` clean.
-- [x] **1.5** Tests green.
-
-🛑 **CHECKPOINT 1** — Cache module shippable on its own. Cold-start safe.
-
----
-
-## Phase 2 — Fetch with fallback (TDD)
-
-**Goal:** `RemoteConfigFetcher.fetch_remote_config()` returns a `RemoteConfigResult` carrying source provenance, writes cache on success, reads cache on failure, raises `RemoteConfigUnavailableError` only when both fail. Keep `RemoteConfigFetchError` as the internal exception raised by the retry layer.
-
-- [x] **2.1** Failing tests in `tests/integration/pipelex/system/pipelex_service/test_remote_config_fetcher.py` with `TestRemoteConfigFetcher`:
- - `test_success_returns_fresh_and_writes_cache` — `mocker.patch("httpx.get")` returns a valid payload → result has `source=FRESH`, cache file written.
- - `test_network_failure_with_cache_returns_cached` — `httpx.get` raises `httpx.ConnectError`, cache is pre-populated via `RemoteConfigCache.store(...)` → result has `source=CACHED`, `RemoteConfigStaleWarning` emitted.
- - `test_network_failure_without_cache_raises_unavailable` — `httpx.get` raises, no cache → `RemoteConfigUnavailableError` with cache path in message.
- - `test_http_error_with_cache_returns_cached` — 5xx response with cache present → cached fallback.
- - `test_http_error_without_cache_raises_unavailable` — 5xx no cache → `RemoteConfigUnavailableError`.
- - `test_validation_error_does_not_fall_back` — the remote responded with garbage JSON; we must still surface `RemoteConfigValidationError` and **not** silently fall back to cache (a server-side schema break is a real bug, and we control the server).
- - `test_codex_cloud_short_circuit_still_works` — `runtime_manager.is_in_codex_cloud=True` → returns dummy with `source=FRESH`, does not write cache.
- - `test_succeeds_after_4_transient_failures_no_cache_fallback` — `httpx.get` raises `ConnectError` 4 times then returns valid payload; tenacity (`stop_after_attempt(5)`) rescues; result has `source=FRESH`, no cache fallback was triggered.
- - `test_falls_back_to_cache_after_5_transient_failures` — all 5 attempts raise; cache is pre-populated; result has `source=CACHED`.
- - `test_require_fresh_refuses_cache` — `httpx.get` raises, cache populated, but caller passed `require_fresh=True` → raises `RemoteConfigUnavailableError` (doc generators must not silently use cache).
-- [x] **2.2** Implement the new control flow in `remote_config_fetcher.py`:
- - Change `fetch_remote_config` to return `RemoteConfigResult(config, source, cached_at)` and accept `require_fresh: bool = False`.
- - Keep raising the existing `RemoteConfigFetchError` from the inner `_fetch_remote_config_with_retry` path (don't churn that).
- - In the outer flow: catch `RemoteConfigFetchError`. If `require_fresh`: re-raise as `RemoteConfigUnavailableError`. Else: try cache; if hit, emit `RemoteConfigStaleWarning` + return `source=CACHED`; if miss, raise `RemoteConfigUnavailableError` (message includes cache path).
- - Persist to cache on success.
- - Leave `RemoteConfigValidationError` path untouched (no cache fallback).
-- [x] **2.3** Add `RemoteConfigUnavailableError` and `RemoteConfigStaleWarning` to `exceptions.py`. `RemoteConfigUnavailableError` message: include cache path and remediation (`pipelex init` while online to prime cache; disable gateway in `backends.toml` as the offline-permanent alternative). Do NOT remove `RemoteConfigFetchError`.
-- [x] **2.4** Update every existing caller of `fetch_remote_config()`. Pre-checked call sites (run `grep -rn "fetch_remote_config" --include="*.py"` to verify nothing else has appeared):
- - `pipelex/pipelex.py:235` — main setup; needs `source` for downstream wiring.
- - `pipelex/cli/commands/doctor_cmd.py:740` — doctor; surface cache age in output.
- - `pipelex/cli/dev_cli/commands/gateway_models_generator.py:46` — **must pass `require_fresh=True`** (regenerates committed docs).
- - `pipelex/cli/dev_cli/commands/preprocess_test_models_cmd.py:98` — **must pass `require_fresh=True`** (rewrites test fixtures).
- - `tests/conftest.py:35` — session cache shim; just unwrap `.config`.
- - `tests/unit/pipelex/cogt/models/test_model_deck_references.py:59` — just unwrap `.config`.
- Most callers do `result = ...; remote_config = result.config`.
-- [x] **2.4b** While editing `doctor_cmd.py` for 2.4, replace the **pre-existing** `except Exception as exc:` at `doctor_cmd.py:767` with the specific exception classes that `models_manager.setup()` and `validate_model_deck()` can raise (the lineage is already enumerated in `pipelex.py:307-336`). This is an existing CLAUDE.md violation; fix it while we're here.
-- [x] **2.5** `make agent-check` clean. Tests green.
-
-🛑 **CHECKPOINT 2** — Fetcher is now resilient and provenance-aware. Cold-start safe.
-
----
-
-## Phase 3 — Plumb `source` through setup and enforce model membership (TDD)
-
-**Goal:** downstream code can see whether the config it has is fresh or cached; backend library raises a clear error when a bundle references a gateway model not present in the (fresh or cached) specs. **Source is passed as a separate argument, NOT stored on `GatewayConfig`** — `GatewayConfig` stays `extra="forbid"` and remains a pure value object.
-
-- [x] **3.1** Failing tests in `tests/integration/pipelex/cogt/model_backends/test_gateway_unknown_model.py` with `TestGatewayUnknownModel`:
- - `test_known_model_loads` — gateway specs contain `gpt-x`, backend deck references it → load OK.
- - `test_unknown_model_fresh_raises` — backend deck references `gpt-future` not in fresh gateway specs → `GatewayUnknownModelError` with `source=FRESH` and the model name in the message.
- - `test_unknown_model_cached_raises_with_stale_hint` — same as above but source is `CACHED`; message hints "remote config is stale; run `pipelex init` while online to refresh".
-- [x] **3.2** Failing tests in `tests/integration/pipelex/system/pipelex_service/test_setup_with_cache.py` with `TestSetupWithCache`:
- - `test_setup_succeeds_with_stale_cache_dry_run` — `Pipelex.make(needs_inference=False, needs_model_specs=True)` with gateway enabled + httpx mocked to fail + cache primed → setup succeeds, a `RemoteConfigStaleWarning` is emitted.
- - `test_setup_fails_without_cache_dry_run` — same as above but cache empty → `RemoteConfigUnavailableError`.
- - `test_telemetry_disabled_when_source_cached` — `Pipelex.make(needs_inference=True)` with gateway enabled + cache fallback → assert the active telemetry manager is the no-op variant (or `is_pipelex_telemetry_enabled` is `False`). Guards the "stale ops shouldn't phone home" invariant.
- - `test_byok_offline_regression_guard` — `Pipelex.make(needs_inference=False, needs_model_specs=True)` with gateway **disabled** in backends.toml + httpx mocked to fail → setup succeeds without ever calling `fetch_remote_config()` (assert via `mocker.spy`). This is the explicit regression test that 0.2 only verifies one-time; without it, a future refactor could re-introduce a phantom network call.
-- [x] **3.3** Implement:
- - Add a `gateway_config_source: RemoteConfigSource | None` parameter to `ModelManager.setup()` and `BackendLibrary._load_gateway_model_specs()`. `None` means no gateway active.
- - In `pipelex.py:setup()`, after the fetch:
- - Build `GatewayConfig` from `result.config` (no `is_from_cache` field — `GatewayConfig` stays unchanged).
- - Pass `result.source` to `models_manager.setup(...)` as `gateway_config_source`.
- - When `result.source == CACHED`, emit `RemoteConfigStaleWarning` (UserWarning subclass next to `GatewayOverrideWarning`).
- - In `BackendLibrary._load_gateway_model_specs` (or wherever model_handle resolution lives — read the call site before deciding), raise `GatewayUnknownModelError(model_name=..., source=gateway_config_source)` when a referenced gateway model isn't in `gateway_config.model_specs`. Message branches on `source`.
-- [x] **3.4** Update agent CLI error mapping in `pipelex/cli/agent_cli/commands/agent_output.py` (`AGENT_ERROR_HINTS`, `AGENT_ERROR_DOMAINS`) for `RemoteConfigUnavailableError` and `GatewayUnknownModelError`. Plumb the structured `warnings` field into the `agent_success(...)` envelope so machine consumers see `[{"type": "RemoteConfigStale", "cached_at": "..."}]` when source is cached.
-- [x] **3.5** `make agent-check` clean. Tests green.
-
-🛑 **CHECKPOINT 3** — Stale operation is safe, model membership is enforced. Cold-start safe.
-
----
-
-## Phase 4 — Cache priming at init (TDD)
-
-**Goal:** when `pipelex init` (or the agent-cli equivalent) completes the gateway terms acceptance flow, attempt one fetch and persist the cache. If offline at init time, log a warning and continue — cache stays empty, user has been told.
-
-- [x] **4.1** Failing tests in `tests/integration/pipelex/cli/commands/init/test_cache_priming.py` with `TestCachePriming`:
- - `test_init_primes_cache_when_online` — run init flow with gateway enabled + httpx mocked to succeed → cache file present and readable afterwards.
- - `test_init_warns_when_offline` — same flow but httpx mocked to fail → init completes (no crash), cache file not present, warning printed to console.
- - `test_init_skips_priming_when_gateway_disabled` — gateway disabled in backends → no fetch attempted, no cache written.
- - `test_init_does_not_double_prime` — if cache already exists and is fresh, init can still refresh it (this is fine; assert the file was rewritten).
-- [x] **4.2** Implement priming hook: in `pipelex/cli/commands/init/command.py`, after `_check_gateway_terms_if_needed` has accepted terms and gateway remains enabled, call a new helper `prime_remote_config_cache(console)` that calls `RemoteConfigFetcher.fetch_remote_config()` inside a try/except limited to `RemoteConfigUnavailableError`, `RemoteConfigFetchError`, and `RemoteConfigValidationError`. On unavailable/fetch-error: log a clear yellow warning; on validation error: re-raise (server schema break is fatal, and we control the server). **Never `except Exception`.**
-- [x] **4.3** Mirror the same hook into the agent CLI init path (`pipelex/cli/agent_cli/commands/init_cmd.py`) so machine clients also prime.
-- [x] **4.4** `make agent-check` clean. Tests green.
-
-🛑 **CHECKPOINT 4** — Cache lifecycle complete. Cold-start safe.
-
----
-
-## Phase 5 — E2E with real `.mthds` bundles
-
-**Goal:** exercise the full surface that the codex-sandbox handoff doc describes (`mthds-agent run bundle ... --dry-run --mock-inputs`) through subprocess invocations.
-
-- [x] **5.1** Create `tests/e2e/data/offline_mode/` with three minimal bundles:
- - `byok_simple/` — references a backend model that does **not** require the gateway (e.g. ollama or anthropic). All `.mthds` files necessary to validate, plus an `inputs.json` shape for `--mock-inputs`.
- - `gateway_known_model/` — references a gateway model that exists in the test fixture remote config.
- - `gateway_unknown_model/` — references a gateway model that does **not** exist in the test fixture remote config.
-- [x] **5.2** Add a one-line indirection in `pipelex/system/pipelex_service/pipelex_details.py`: `REMOTE_CONFIG_URL` reads from the `PIPELEX_REMOTE_CONFIG_URL` env var if set, else uses the hard-coded production URL. This is a **legitimate config knob** (useful for testing/staging), not a test backdoor. Failing tests in `tests/e2e/agent_cli/test_offline_run_dry.py` with `TestOfflineDryRun`. Mark `@pytest.mark.asyncio(loop_scope="class")` if any tests are async. Each test:
- - Invokes the CLI via `subprocess.run([".venv/bin/pipelex-agent", "run", "bundle", str(bundle_dir), "--dry-run", "--mock-inputs"], ...)` (the CLI binary is `pipelex-agent`, not `mthds-agent`).
- - Uses a `monkeypatch`-style fixture to point `HOME` (and therefore `~/.pipelex/cache/`) at a tmp path, so cache state is controlled per-test.
- - Sets `PIPELEX_REMOTE_CONFIG_URL=http://127.0.0.1:1/` (a reserved-port unreachable URL) to simulate offline. Real `httpx`, real `ConnectError`, no production-code-aware-of-tests.
-- [x] **5.3** Test cases:
- - `test_byok_offline_succeeds` — gateway disabled (test bundle ships with `backends.toml` that has gateway disabled), no network, no cache → exit 0, structured success JSON.
- - `test_gateway_known_with_cache_succeeds_offline` — gateway enabled, no network, cache primed → exit 0, success JSON includes a `warnings` array with `{"type": "RemoteConfigStale", ...}`.
- - `test_gateway_unknown_with_cache_fails_with_clear_error` — exit nonzero, the unknown handle surfaces in the JSON envelope. Implementation note: pinning `error_type == "GatewayUnknownModelError"` would require an extra deck override to make the membership check fire (the bundle's pipe-level model reference fails at the pipe-operator layer instead). The test asserts the handle is visible without locking the error_type, leaving room for both failure paths.
- - `test_gateway_no_cache_no_network_fails_with_unavailable` — exit nonzero, `error_type == "RemoteConfigUnavailableError"`, message references priming via `pipelex init`.
-- [x] **5.4** `make agent-check` clean. Tests green.
-
-🛑 **CHECKPOINT 5** — End-to-end behaviour validated against the exact surface the codex-sandbox doc exercised. Cold-start safe.
-
----
-
-## Phase 6 — User-facing polish
-
-- [x] **6.1** Update `pipelex/cli/agent_cli/commands/agent_output.py`:
- - Add `AGENT_ERROR_HINTS` entries for `RemoteConfigUnavailableError` and `GatewayUnknownModelError`.
- - Add `AGENT_ERROR_DOMAINS` entries for both.
- - Keep the existing `RemoteConfigFetchError` and `RemoteConfigValidationError` hints intact.
-- [x] **6.2** Update `pipelex/cli/error_handlers.py` for the Rich CLI surface: add handlers for `RemoteConfigUnavailableError` and `GatewayUnknownModelError` mirroring the agent-cli hints. Keep existing `RemoteConfigFetchError`/`RemoteConfigValidationError` handlers.
-- [x] **6.3** Update relevant CLAUDE.md sections:
- - `pipelex/cli/agent_cli/CLAUDE.md` if error classes are mentioned.
- - `pipelex/system/pipelex_service/CLAUDE.md` if it exists; create a short note if not (only if there's already a convention for service-level docs).
-- [x] **6.4** Add a `## [Unreleased]` entry to `CHANGELOG.md` summarising the user-visible behaviour change (offline support + new error types + new warning).
-
-> **Deferred from this PR:** Phase 6.3-old (`pipelex doctor` cache-age reporting) and Phase 6.6-old (cross-repo `mthds-plugins/wip/codex-sandbox-escalation.md` update). See "Deferred follow-ups" at the bottom of this file.
-
-🛑 **CHECKPOINT 6** — User-facing surface complete. Cold-start safe.
-
----
-
-## Phase 7 — Final verification
-
-- [x] **7.1** `make agent-check` clean.
-- [x] **7.2** `make agent-test` clean.
-- [x] **7.3** Manually reproduce all scenarios from the behaviour matrix:
- - BYOK offline `mthds-agent run bundle ... --dry-run --mock-inputs` → success.
- - Gateway online, no cache → success, cache written.
- - Gateway offline, cache present → success with stale warning.
- - Gateway offline, no cache → clear `RemoteConfigUnavailableError`.
- - Bundle references unknown gateway model → clear `GatewayUnknownModelError`.
- - `pipelex-dev update-gateway-models` offline → clear refusal (no stale docs written).
-- [x] **7.4** Squash-friendly commit history; PR description references the codex-sandbox-escalation handoff and the deferred follow-ups.
-
-🛑 **CHECKPOINT 7** — Ready for review.
-
----
-
-## Risk log
-
-- **Caller migration in Phase 2.** Every call site of `fetch_remote_config()` must be updated. If a caller is missed, it'll break at runtime in dev-CLI tooling that's rarely exercised. Grep before declaring 2.4 done. Current known sites are listed in 2.4 — re-run the grep to be sure.
-- **Cache poisoning during validation breakage.** We explicitly chose NOT to fall back to cache on `RemoteConfigValidationError`. Since we control the remote config server (`../pipelex-back-office`) AND the URL is versioned, a schema-rejecting payload is a real server-side bug, not an expected operational state. Failing loudly is the desired behaviour. Confirm this design choice survives review.
-- **Schema version bumps are coordinated.** The remote-config URL is versioned in `pipelex-back-office`. To change the `RemoteConfig` shape: bump the URL version in back-office AND bump `RemoteConfigCache.SCHEMA_VERSION` in this repo. Old caches return `None` on load (test in 1.1) and re-prime on next online fetch. Document this in the cache module docstring.
-- **`is_first_time_backends_setup` semantics.** Phase 4 priming is conditional on terms-accepted-and-gateway-enabled state. The init flow has a few branches; verify priming runs on the **first** init pass, not only on subsequent re-inits.
-- **Doc-generator silent staleness was the critical-gap finding.** Phase 2 fixes it via `require_fresh=True`. If you drop that constraint, you reopen the regression.
-
-## Open questions to resolve as we go
-
-- Maximum acceptable cache age before we refuse to use it? **Default: no cap.** Gateway model lists drift slowly; an old cache is better than no cache. Revisit if it bites us.
-- Should the agent-cli `init` command auto-prime even without `--gateway`? **No.** Priming only when gateway is selected.
-
----
-
-## Deferred follow-ups (out of this PR's scope)
-
-Capture as separate work after this lands:
-
-1. **`pipelex doctor` cache reporting.** Extend `doctor` to surface cache presence, age, gateway-enabled-but-missing-cache hint. Pure additive feature; orthogonal to the offline-fix. Was Phase 6.3 in the original plan.
-2. **Codex Cloud cache-first short-circuit.** Today `remote_config_fetcher.py:93` returns a dummy unconditionally in Codex Cloud. After this PR ships, change the short-circuit to try cache first and fall back to dummy. Low risk because we already trust the cache.
-3. **Cross-repo: `mthds-plugins/wip/codex-sandbox-escalation.md`.** Note that `--dry-run` no longer requires escalation once Pipelex is initialised online once. Lives in a different repo; do as a separate PR there. Was Phase 6.6 in the original plan.
-4. **Cache TTL revisit.** Currently uncapped. Re-evaluate once we have telemetry on cache-fallback usage in production.
-5. **Schema-version migration runbook.** When `RemoteConfig` shape actually changes, write down the URL-version + `SCHEMA_VERSION` bump procedure. Not needed until the first real schema bump.
-6. **`pipelex-agent run bundle --output-dir` flag.** Today the CLI writes `dry_run.json` (and `live_run.json`, graph HTML) next to the input bundle (`_run_core.py:92` derives `output_dir` from the bundle path). That side effect forced Phase 5 to stage each bundle into a tmp dir before invocation, and would also break invocations against a read-only mounted bundle path (the codex-sandbox case). Adding `--output-dir <path>` (and falling back to the current behaviour when unset) would let read-only callers operate without copying. Surfaced in the Phase 5 code review.
-7. **E2E test pinning `GatewayUnknownModelError` end-to-end.** Phase 5's `test_gateway_unknown_with_cache_fails_with_clear_error` asserts the unknown handle is visible in the envelope without pinning `error_type`, because the bundle's pipe-level model reference fires `ModelChoiceNotFoundError`/`PipeOperatorModelAvailabilityError` at the pipe-operator layer rather than the deck-level membership check. Phase 3's unit test (`test_gateway_unknown_model.py`) covers the membership check directly; a follow-up E2E with a deck override that points a preset at a missing handle would pin the agent-CLI's `GatewayUnknownModelError` mapping end-to-end. Surfaced in the Phase 5 code review.
-
----
-
-## Checkpoint status log
-
-<!-- Append a "### Checkpoint N status" block here after each 🛑 CHECKPOINT, capturing what landed, open decisions, and the next checkbox to start with. Keep blocks short; the codebase is authoritative. -->
-
-### Checkpoint 0 status
-
-**Landed:**
-- `tests/integration/pipelex/system/pipelex_service/test_offline_baseline.py` — `TestOfflineBaseline` with two passing tests:
- - `test_byok_offline_setup_succeeds_without_fetching_remote_config` — gateway disabled, no network, `fetch_remote_config` and `httpx.get` are asserted to be uncalled.
- - `test_gateway_offline_without_cache_raises_remote_config_fetch_error` — gateway enabled + terms accepted + `httpx.get` raising `ConnectError` raises `RemoteConfigFetchError`. Bypasses the session-scoped cache patch via a module-level capture of the original classmethod.
-
-**Workaround:** The test module overrides the autouse `reset_pipelex_config_fixture` (no eager `Pipelex.make`) and the gateway-offline test explicitly calls `log.reset()` after the expected failure, because `Pipelex.make` does not reset log state when setup raises. This is pre-existing behaviour — flagged for future fix, not in scope here.
-
-**Verification:**
-- `make agent-check` → clean.
-- `make agent-test` → all green (5253 passed, 2 skipped, 3 xfailed; matches main).
-
-**Next:** Phase 1 — start at **1.1** (failing tests for `RemoteConfigCache` in `tests/unit/system/pipelex_service/test_remote_config_cache.py`).
-
-### Checkpoint 1 status
-
-**Landed:**
-- `pipelex/system/pipelex_service/remote_config_cache.py` — `CachedRemoteConfig` (Pydantic) + `RemoteConfigCache` (class with `cache_path()`, `load()`, `store()`). On-disk layout `{schema_version, cached_at, raw_config}`. Atomic writes via `tempfile.NamedTemporaryFile` + `os.replace` (kept explicit `os.replace` with a per-line `# noqa: PTH202`, with cleanup of the tmp file on failure via a `replaced` flag in `finally`). Module constant `CACHE_SCHEMA_VERSION = 1`.
-- `tests/unit/pipelex/system/pipelex_service/test_remote_config_cache.py` — 8 tests covering roundtrip, missing-file, corrupted-JSON, wrong-schema-version, parent-dir creation, cache-path location, atomic-write-on-rename-failure, and raw-payload extras preservation.
-- `tests/unit/pipelex/system/pipelex_service/conftest.py` — extended the existing `mock_log` autouse fixture to also patch `remote_config_cache.log`, so unit tests don't need a configured Pipelex log stack.
-
-**Decisions:**
-- `CachedRemoteConfig.model_config` is `ConfigDict(extra="forbid")` — *not* strict, because we deserialize datetimes from ISO strings.
-- The cache module uses `pipelex.log` rather than stdlib `logging` to stay consistent with the rest of the package; tests rely on the module-scoped `mock_log` fixture to assert warnings instead of `caplog`.
-- For `test_write_is_atomic`, the test patches `pathlib.Path.replace` (which is what Python uses under the hood after ruff PTH-fixed the call) rather than `os.replace` at module scope.
-
-**Verification:**
-- `.venv/bin/pytest tests/unit/pipelex/system/pipelex_service/test_remote_config_cache.py` — 8 passed.
-- `make agent-check` — clean.
-
-**Next:** Phase 2 — start at **2.1** (failing tests for `RemoteConfigFetcher.fetch_remote_config` with fallback semantics in `tests/integration/pipelex/system/pipelex_service/test_remote_config_fetcher.py`).
-
-### Checkpoint 2 status
-
-**Landed:**
-- `pipelex/system/pipelex_service/exceptions.py` — added `RemoteConfigUnavailableError(PipelexServiceError)` (user-facing offline-mode error: cache path + `pipelex init`/disable-gateway remediation hints) and `RemoteConfigStaleWarning(UserWarning)`. `RemoteConfigFetchError` kept intact as the internal retry-layer exception.
-- `pipelex/system/pipelex_service/remote_config_fetcher.py` — full rewrite of the public API. `fetch_remote_config(require_fresh: bool = False) -> RemoteConfigResult` now carries provenance (`source: RemoteConfigSource` = `FRESH` | `CACHED`, plus `cached_at`). On success: validates payload then writes the **raw JSON dict** via `RemoteConfigCache.store(...)`. On `RemoteConfigFetchError`: tries cache (unless `require_fresh=True`), emits `RemoteConfigStaleWarning` on hit, raises `RemoteConfigUnavailableError` chained from the original `RemoteConfigFetchError` on miss. `RemoteConfigValidationError` path untouched — no cache fallback for schema breaks. Codex Cloud short-circuit still returns a dummy result without writing the cache.
-- `tests/integration/pipelex/system/pipelex_service/test_remote_config_fetcher.py` — new `TestRemoteConfigFetcher` with 11 tests covering all the matrix entries from the plan: fresh success + cache write, connect-error fallback, HTTP-5xx fallback, both no-cache variants raising `RemoteConfigUnavailableError`, schema-break never falling back, Codex Cloud short-circuit untouched, tenacity recovering after 4 transient failures (no cache fallback triggered), tenacity exhausting all 5 attempts (cache fallback), `require_fresh=True` refusing cache, and a guard that the inner `RemoteConfigFetchError` is chained as `__cause__`.
-- Caller migration:
- - `pipelex/pipelex.py:235` — unwraps `result.config`, logs the source.
- - `pipelex/cli/commands/doctor_cmd.py` — unwraps `result.config`; the `except (RemoteConfigFetchError, RemoteConfigValidationError)` became `except (RemoteConfigUnavailableError, RemoteConfigValidationError)`.
- - `pipelex/cli/dev_cli/commands/gateway_models_generator.py` and `preprocess_test_models_cmd.py` — pass `require_fresh=True` (these regenerate committed reference docs and test fixtures; stale cache must never bake in).
- - `tests/conftest.py` — session-level cache shim now returns a `RemoteConfigResult`; signature accepts `require_fresh` and ignores it (intentional — the test session cache exists to avoid network).
- - `tests/unit/pipelex/cogt/models/test_model_deck_references.py` — unwraps `.config`.
- - `tests/unit/pipelex/system/pipelex_service/test_gateway_terms_check.py` — mock now returns a result-shaped object whose `.config` exposes `backend_model_specs` + `aws_region`.
-- `tests/integration/pipelex/system/pipelex_service/test_offline_baseline.py` — renamed the gateway-offline test to `test_gateway_offline_without_cache_raises_remote_config_unavailable_error` and isolated `~/.pipelex` per test via the `ConfigLoader.global_config_dir` `PropertyMock` so a developer's real cache can't accidentally satisfy the fallback. The BYOK-offline test is unchanged.
-- `pipelex/cli/commands/doctor_cmd.py` — replaced the pre-existing `except Exception as exc:` at the model-check block with the specific exception lineage (`RoutingProfileLibraryNotFoundError`, `InferenceBackendLibraryNotFoundError`, `ModelDeckNotFoundError`, `RoutingProfileDisabledBackendError`, `InferenceBackendLibraryValidationError`, `ModelDeckValidationError`, `InferenceBackendCredentialsError`).
-
-**Decisions:**
-- `RemoteConfigResult` is a Pydantic `BaseModel` with `ConfigDict(extra="forbid", strict=True, arbitrary_types_allowed=True)` (matches project convention; the `arbitrary_types_allowed` is needed because `RemoteConfig` is also a `BaseModel`). Carries `config`, `source`, `cached_at` (UTC).
-- `RemoteConfigSource` is a `StrEnum` from `pipelex.types` with lowercase values `fresh` / `cached`.
-- `RemoteConfigUnavailableError` is built by a helper (`_build_unavailable_error`) and the caller does the `raise ... from fetch_error`. Initial draft had a helper that raised directly; refactored to return-and-raise so pyright doesn't see "unreachable code" at the call site and ruff doesn't complain about `raise AssertionError("unreachable")`.
-- `datetime` import in the fetcher is annotated `# noqa: TC003` — Pydantic v2 resolves annotations at runtime even with `from __future__ import annotations`, so it cannot be moved into the `TYPE_CHECKING` block.
-
-**Verification:**
-- `make agent-check` — clean (ruff fix-imports, ruff format, plxt fmt, ruff lint, plxt lint, pyright, mypy all green).
-- Targeted: `.venv/bin/pytest -n auto -m "..." tests/unit/pipelex/system/ tests/integration/pipelex/system/` → 110 passed; same flags on `tests/unit/pipelex/cli/ tests/integration/pipelex/cli/ tests/unit/pipelex/cogt/ tests/integration/pipelex/cogt/` → 1006 passed.
-- `make agent-test` — full suite green.
-
-**Next:** Phase 3 — start at **3.1** (failing tests for `GatewayUnknownModelError` in `tests/integration/pipelex/cogt/model_backends/test_gateway_unknown_model.py`).
-
-### Checkpoint 3 status
-
-**Landed:**
-- `pipelex/cogt/exceptions.py` — added `GatewayUnknownModelError(CogtError)` with `error_category=CONFIGURATION`. Carries `model_name: str` and `source: RemoteConfigSource`. Message branches on source via exhaustive match: `FRESH` → "gateway no longer offers it / check name / disable gateway"; `CACHED` → "cache may be stale, run `pipelex init` while online". Imports `RemoteConfigSource` at module level — no circular-import issue since the fetcher module doesn't touch `cogt`.
-- `pipelex/cogt/models/model_manager_abstract.py` — added required `gateway_config_source: RemoteConfigSource | None` parameter to the abstract `setup()`.
-- `pipelex/cogt/models/model_manager.py` — implementation of the membership check:
- - `setup()` now accepts `gateway_config_source` and calls `_enforce_gateway_model_membership` after `build_deck`.
- - `_enforce_gateway_model_membership(gateway_config, gateway_config_source)` — no-op when either is `None` (gateway not live). Otherwise iterates `_collect_deck_referenced_handles(deck)`, resolves each through `_resolve_terminal_handle` (walks aliases + first-element of waterfalls), and raises `GatewayUnknownModelError(model_name=terminal, source=gateway_config_source)` when the terminal handle is missing from both `deck.inference_models` AND `gateway_config.model_specs` (defaults key skipped).
- - `_collect_deck_referenced_handles` covers preset models (LLM/Extract/ImgGen/Search) and the two LLM choice defaults. Aliases/waterfalls are intentionally NOT enumerated directly — they're reachable via preset/choice references and the resolver walks them.
- - `_extract_choice_handle` normalises the `LLMModelChoice` union (`LLMSetting | ModelReference | str | None`) to a raw handle string.
- - `_resolve_terminal_handle` does its own model-type → aliases/waterfalls dispatch (instead of calling `ModelDeck._get_aliases_and_waterfalls_for_type`, which is protected) to keep the cogt API surface clean.
-- `pipelex/pipelex.py` — captures `gateway_config_source` from the fetch result, passes it through `models_manager.setup(...)`, and tightens the telemetry guard:
- - `is_pipelex_telemetry_enabled = is_pipelex_service_enabled and needs_inference and gateway_config_source != RemoteConfigSource.CACHED` (stale config implies stale model identities; phoning home then would pollute metrics).
- - Re-emits `RemoteConfigStaleWarning` at setup time even when the fetcher itself didn't (the session-cached fetcher in `tests/conftest.py` swaps in a wrapper that doesn't warn — re-emitting here makes provenance visible regardless of how the result reached us).
- - Dummy remote config path (`needs_model_specs=False`) gets `source=FRESH` so the gateway-membership check is silent in that branch (model_specs is empty there).
-- `pipelex/cli/commands/doctor_cmd.py` — propagates `gateway_config_source` from the fetch result through `models_manager.setup(...)`.
-- `pipelex/cli/agent_cli/commands/agent_output.py`:
- - New module-level capture buffer + `record_setup_warning(...)` / `consume_setup_warnings()` helpers.
- - `agent_success(...)` drains the buffer into a top-level `warnings` array on the JSON envelope (appending to any caller-supplied list).
- - Added `AGENT_ERROR_HINTS` and `AGENT_ERROR_DOMAINS` entries for `RemoteConfigUnavailableError` and `GatewayUnknownModelError`. Existing `RemoteConfigFetchError` and `RemoteConfigValidationError` hints untouched.
-- `pipelex/cli/agent_cli/commands/agent_cli_factory.py`:
- - Wraps `Pipelex.make` in `warnings.catch_warnings(record=True)` and records every `RemoteConfigStaleWarning` as `{"type": "RemoteConfigStale", "message": "..."}` via `record_setup_warning(...)`. The next `agent_success` call surfaces it on the envelope.
- - New `except` clauses for `RemoteConfigUnavailableError` and `GatewayUnknownModelError`; the latter exposes `model_name` and `source` on the error JSON.
-
-**Tests:**
-- `tests/integration/pipelex/cogt/model_backends/test_gateway_unknown_model.py` — `TestGatewayUnknownModel` with three tests covering the happy path (default cached gateway has all referenced handles), fresh-source missing handle, and cached-source missing handle (asserts the message hints at `pipelex init`).
-- `tests/integration/pipelex/system/pipelex_service/test_setup_with_cache.py` — `TestSetupWithCache` with four tests: dry-run with primed cache (warning emitted), dry-run with cold cache (`RemoteConfigUnavailableError`), telemetry-downgrade-to-no-op when source is cached even with `needs_inference=True`, and the BYOK-offline regression guard (gateway disabled → `fetch_remote_config` never called).
-
-**Decisions:**
-- `GatewayConfig` stays `extra="forbid"` and source-free. Provenance flows through `ModelManager.setup(gateway_config_source=...)` rather than being baked into the value object.
-- The membership check runs at the end of `ModelManager.setup` (not only at `validate_model_deck` time), so even `needs_inference=False, needs_model_specs=True` dry-run flows surface gateway-spec mismatches. This is necessary because the default `missing_presets_reaction = "log"` would otherwise swallow the failure silently.
-- `_enforce_gateway_model_membership` skips already-resolved handles (i.e. ones that ended up in `deck.inference_models`). This means the production happy path is silent even when the gateway has every standard model.
-- We did NOT extend `ModelDeck._get_aliases_and_waterfalls_for_type` to public access — the resolver re-does the dispatch locally to keep the deck's invariants encapsulated.
-- The structured `warnings` envelope is keyed `type=RemoteConfigStale`; the `cached_at` field will be added once we propagate the timestamp through the warning payload (currently the warning message has it inline; deferred to a follow-up if a structured field becomes necessary for downstream consumers).
-- Telemetry is downgraded to no-op (rather than to a "stale" variant) when the source is cached. Stricter than the original plan's "is_pipelex_telemetry_enabled stays False" wording — current implementation makes the downgrade explicit in `pipelex.py` so the existing `TelemetryFactory.make_telemetry_manager(is_pipelex_telemetry_enabled=False, ...)` path returns the no-op directly.
-
-**Verification:**
-- Targeted: `.venv/bin/pytest -n auto -m "not pipelex_api" tests/integration/pipelex/system/pipelex_service/ tests/unit/pipelex/system/` → 112 passed.
-- Targeted: `.venv/bin/pytest -n auto -m "not pipelex_api" tests/integration/pipelex/cogt/model_backends/test_gateway_unknown_model.py` → 3 passed.
-- Targeted: `.venv/bin/pytest -n auto -m "not pipelex_api" tests/integration/pipelex/system/pipelex_service/test_setup_with_cache.py` → 4 passed.
-- `make agent-check` — clean (ruff + plxt + pyright + mypy all green).
-- `make agent-test` — full suite green.
-
-**Next:** Phase 4 — start at **4.1** (failing tests for cache priming in `tests/integration/pipelex/cli/commands/init/test_cache_priming.py`).
-
-### Checkpoint 4 status
-
-**Landed:**
-- `pipelex/cli/commands/init/command.py`:
- - New `CachePrimingResult` Pydantic model (`extra="forbid", strict=True`) with `primed: bool` and `error_message: str | None`.
- - New pure-logic helper `attempt_prime_remote_config_cache()` — checks gateway enabled + terms accepted, calls `RemoteConfigFetcher.fetch_remote_config()`, returns a `CachePrimingResult`. Catches only `RemoteConfigUnavailableError` and `RemoteConfigFetchError`; `RemoteConfigValidationError` propagates (server-side schema breaks must surface — we control the back-office).
- - Interactive wrapper `prime_remote_config_cache(console)` — calls the pure helper and emits a yellow Rich warning when a fetch was attempted and failed; otherwise silent.
- - `execute_initialization(...)` now calls `prime_remote_config_cache(console)` as Step 5, after telemetry setup. No-op for BYOK/declined-terms paths, so unconditional call is safe.
-- `pipelex/cli/agent_cli/commands/init_cmd.py`:
- - Calls `attempt_prime_remote_config_cache()` after `update_inference_setup_completed(...)`.
- - The `agent_success(...)` envelope now includes `cache_primed: bool` and (when applicable) `cache_priming_error: str`. Machine consumers can branch on these without parsing log output.
-- `tests/integration/pipelex/cli/commands/init/test_cache_priming.py` — `TestCachePriming` with 4 tests covering the matrix: primes when online, warns when offline (no crash, no cache written, yellow warning emitted), skips when gateway disabled (no fetch + no cache), and overwrites an existing cache when refreshing online.
-
-**Decisions:**
-- Split the helper into a pure-logic `attempt_prime_remote_config_cache()` + an interactive `prime_remote_config_cache(console)` wrapper. The split lets the agent CLI surface structured fields (`cache_primed`, `cache_priming_error`) on its JSON envelope while the Rich CLI gets a yellow warning. The plan's original sketch only described the interactive wrapper; the agent CLI mirror needed the pure variant.
-- Priming runs unconditionally at the end of `execute_initialization`. The helper itself short-circuits when gateway is disabled or terms not accepted, so wrapping the call in `if PipelexBackend.GATEWAY in selected_backend_keys:` at the call site would be redundant double-checking. The internal short-circuit also covers the agent CLI mirror cleanly.
-- The skipped state (`primed=False, error_message=None`) is intentionally indistinguishable from "no gateway/no terms" — both surface the same `cache_primed: false` on the agent envelope. Consumers that care can check `backends_enabled` or read `pipelex_service.toml` directly.
-- No `--no-prime` opt-out flag for now. If priming ever becomes a real problem at init time (slow network, captive portals), revisit; today the helper warns and continues so it can't block init.
-- `attempt_prime_remote_config_cache` passes ``require_fresh=True`` to the fetcher. Without it, an offline fetch with a stale cache on disk would silently return ``source=CACHED`` and the helper would falsely report ``primed=True`` (no new write happened). With ``require_fresh=True``, the offline-with-stale-cache path raises ``RemoteConfigUnavailableError`` → we surface it as ``error_message`` and the existing cache file is left intact. Caught in code review post-Phase 4; `test_init_warns_when_offline_with_stale_cache_present` pins the regression.
-
-**Verification:**
-- `.venv/bin/pytest tests/integration/pipelex/cli/commands/init/test_cache_priming.py` — 5 passed.
-- Targeted: `.venv/bin/pytest -n auto -m "..." tests/unit/pipelex/cli/ tests/integration/pipelex/cli/ tests/unit/pipelex/system/ tests/integration/pipelex/system/` → 429 passed.
-- `make agent-check` — clean (ruff + plxt + pyright + mypy all green).
-- `make agent-test` — full suite green.
-
-**Next:** Phase 5 — start at **5.1** (create `tests/e2e/data/offline_mode/` bundles for `byok_simple`, `gateway_known_model`, `gateway_unknown_model`).
-
-### Checkpoint 5 status
-
-**Landed:**
-- `pipelex/system/pipelex_service/pipelex_details.py` — replaced the class-level `REMOTE_CONFIG_URL` constant with a `remote_config_url()` classmethod that reads `PIPELEX_REMOTE_CONFIG_URL` from the environment when set, else falls back to the production URL. New `_DEFAULT_REMOTE_CONFIG_URL` module constant + `REMOTE_CONFIG_URL_ENV_VAR` name; the underlying call site in `remote_config_fetcher.py:206` now calls the method.
-- `tests/e2e/data/offline_mode/{byok_simple,gateway_known_model,gateway_unknown_model}/<name>.mthds` — minimal `PipeLLM` bundles, each referencing one handle: `claude-4.5-haiku` (BYOK via anthropic), `gpt-4o-mini` (known gateway handle), `gpt-future-fake-99` (deliberately absent from the cached payload). Prompts use the inline `$topic.text` sigil (not `@`, which produces tag-wrapped block content and is invalid on the same line as other text).
-- `tests/e2e/agent_cli/conftest.py` — new hermetic-home fixtures:
- - `hermetic_home` (returns the tmp `HOME` with a kit-copied `.pipelex/` tree, with `pipelex_service.toml` pre-stamped as terms-accepted + onboarding-complete).
- - `offline_subprocess_env` (subprocess env with `HOME` redirected, `PIPELEX_REMOTE_CONFIG_URL=http://127.0.0.1:1/...`, `RUN_MODE=ci_test`, and dummy values for every `${...}` backend credential variable referenced by the kit's `backends.toml`; under `--dry-run`'s `needs_inference=False` Pipelex is lenient on missing credentials, but the env-var substitution itself still needs the var to exist).
- - Helper functions: `set_gateway_enabled`, `write_active_routing_profile`, `write_remote_config_cache`, `write_pipelex_service_config`. The cache writer hits the real `RemoteConfigCache` JSON schema (matches `CACHE_SCHEMA_VERSION`).
-- `tests/e2e/agent_cli/test_offline_run_dry.py` — `TestOfflineDryRun` with four subprocess-based E2E tests. Each test sets `cwd=hermetic_home` so `ConfigLoader.find_project_root` immediately stops at `Path.home()` and the subprocess uses the test's `.pipelex/` instead of walking up to the repo's project-level one.
- - `test_byok_offline_succeeds` — gateway disabled (and routing flipped to `all_anthropic`) → exit 0, no `error` field, `text` payload present.
- - `test_gateway_no_cache_no_network_fails_with_unavailable` — gateway enabled, no cache → `error_type == "RemoteConfigUnavailableError"` with `pipelex init` in the remediation message.
- - `test_gateway_known_with_cache_succeeds_offline` — gateway enabled, cache primed with a comprehensive payload covering every kit-deck terminal handle (LLM, img-gen, extract, search) → exit 0, the `warnings` array surfaces `{"type": "RemoteConfigStale", ...}`. The "comprehensive payload" is critical: the gateway membership check iterates every preset/choice terminal across all model-type decks, and any missing handle (e.g. `azure-document-intelligence` for the default extract preset) raises `GatewayUnknownModelError` at setup time even when the bundle never touches that model.
- - `test_gateway_unknown_with_cache_fails_with_clear_error` — bundle pipe references `gpt-future-fake-99` (absent from the cache). The test asserts a non-zero exit and the unknown handle visible somewhere in the JSON envelope without pinning `error_type`. In practice this fires as `ModelChoiceNotFoundError` or `PipeOperatorModelAvailabilityError` at the pipe-operator layer rather than `GatewayUnknownModelError`, because the kit deck doesn't reference the fake handle and our membership check only iterates deck-level presets/choices.
-
-**Decisions:**
-- `cwd=hermetic_home` instead of `cwd=tmp_path/some_subdir` was deliberate. With `HOME=tmp_path` and `cwd=tmp_path`, `find_project_root` returns `None` immediately (the loop hits the home guard on iteration 0) so the project-config-dir lookup short-circuits to the hermetic global dir. Any other cwd choice risks walking up to a sibling project marker file in the temp tree.
-- The `gateway_unknown_model` test doesn't pin the error_type because making the membership check fire from a `.mthds` bundle would require shipping a custom deck override that points a preset at the fake handle. That's worth doing in a follow-up but adds churn here without changing the user-facing contract — what we promise is "the unknown handle surfaces in a structured error", and the test asserts exactly that.
-- The cached `backend_model_specs` payload uses minimal valid spec bodies (`sdk` + `model_type` + a couple of inputs/outputs). Larger spec fields like cost/latency/max-tokens are optional in `InferenceModelSpecBlueprint` and elided to keep the fixture compact.
-- Subprocess env explicitly does NOT inherit the parent process env. The dict is built from scratch and includes `PATH=/usr/bin:/bin:/usr/local/bin`. This prevents developer-machine env vars (e.g. a real `ANTHROPIC_API_KEY`, a real `HOME`) from leaking in and making the test environment non-hermetic. Side effect: if a future test needs more env, it has to be added explicitly to `offline_subprocess_env`.
-- `subprocess` import gets a `# noqa: S404` because the bandit rule flags any use of the module, but we genuinely want to spawn the real CLI binary for E2E coverage. The `S603` noqa on the actual `subprocess.run` call covers the same concern at the call site.
-- Renamed `PipelexDetails.REMOTE_CONFIG_URL` (class constant) to `PipelexDetails.remote_config_url()` (classmethod). A `@classmethod @property` would have been more drop-in but is deprecated in Python 3.11 and removed in 3.13; a method is the safe substitute.
-
-**Verification:**
-- `.venv/bin/pytest tests/e2e/agent_cli/test_offline_run_dry.py` — 4 passed (~50s wall clock; each test spawns one subprocess invocation of `pipelex-agent`).
-- Targeted: `.venv/bin/pytest -n auto -m "not pipelex_api" tests/unit/pipelex/system/ tests/integration/pipelex/system/ tests/unit/pipelex/cli/ tests/integration/pipelex/cli/` — 429 passed.
-- `make agent-check` — clean (ruff + plxt + pyright + mypy all green).
-
-**Next:** Phase 6 — start at **6.1** (update `agent_output.py` `AGENT_ERROR_HINTS`/`AGENT_ERROR_DOMAINS` for new error types).
-
-### Checkpoint 6 status
-
-**Landed:**
-- `pipelex/cli/agent_cli/commands/agent_output.py` — already carried `AGENT_ERROR_HINTS` and `AGENT_ERROR_DOMAINS` entries for `RemoteConfigUnavailableError` and `GatewayUnknownModelError` from Phase 3. No further changes needed. Existing `RemoteConfigFetchError` and `RemoteConfigValidationError` hints intact.
-- `pipelex/cli/error_handlers.py` — added two Rich-CLI handlers mirroring the agent-cli hints:
- - `handle_remote_config_unavailable_error(exc)` — frames the failure as "offline + cold cache", names both remediation paths (prime the cache via `pipelex init` while online, or disable the gateway for permanent BYOK operation). Echoes the underlying error message which already contains the cache file path.
- - `handle_gateway_unknown_model_error(exc)` — shows the unknown model handle and the config source provenance, and branches the remediation via `match exc.source` on `RemoteConfigSource.{FRESH,CACHED}`. Fresh-source: typo/deck-update guidance; cached-source: `pipelex init` while online to refresh the cache. Imported the `RemoteConfigSource` enum from `pipelex.system.pipelex_service.types` (the leaf-level enum module, not `pipelex_service.types` reachable through `remote_config_fetcher`).
- - Existing `handle_remote_config_fetch_error` and `handle_remote_config_validation_error` handlers untouched.
-- `pipelex/cli/cli_factory.py` — wired both new handlers into `make_pipelex_for_cli`'s except chain: `RemoteConfigUnavailableError` → `handle_remote_config_unavailable_error`; `GatewayUnknownModelError` → `handle_gateway_unknown_model_error`. Order matters: `RemoteConfigFetchError` is the parent-level retry-layer exception (caught first); `RemoteConfigUnavailableError` is its user-facing sibling raised when the cache fallback fails too (caught next); `GatewayUnknownModelError` is unrelated and lives further down the chain.
-- `CHANGELOG.md` — added a fresh `## [Unreleased]` section above v0.28.0 with three buckets:
- - **Added**: offline-mode setup/dry-run support (cache lifecycle, stale warning, telemetry suppression, doc-generator refusal), `GatewayUnknownModelError` (source-aware messaging), `RemoteConfigUnavailableError` (cache-cold failure), `PIPELEX_REMOTE_CONFIG_URL` env var.
- - **Changed**: `RemoteConfigFetcher.fetch_remote_config()` now returns a `RemoteConfigResult` with provenance and accepts `require_fresh: bool = False`; `ModelManager.setup()` / `BackendLibrary._load_gateway_model_specs()` accept `gateway_config_source: RemoteConfigSource | None`.
-
-**Decisions:**
-- **6.3 CLAUDE.md updates: no-op.** `pipelex/cli/agent_cli/CLAUDE.md` only points at `AGENT_ERROR_HINTS` as the registry — it doesn't enumerate specific error classes, so the new entries don't need to be mentioned. `pipelex/system/pipelex_service/CLAUDE.md` does not exist, and there's no convention for service-level CLAUDE.md docs (only `pipelex/builder/CLAUDE.md` and `pipelex/cli/agent_cli/CLAUDE.md` exist across the whole `pipelex/` tree). The plan's "only if there's already a convention" gate is not satisfied, so no new file was created.
-- The Rich CLI handlers deliberately mirror the agent-CLI hints but in Rich's "❌ / ⚠ / 💡" style rather than as one-liner JSON `hint` strings. Both surfaces remain consistent in *content* (same remediation paths, same provenance branching) but differ in *form* (Rich-formatted multi-line vs JSON envelope field).
-- The `RemoteConfigUnavailableError` handler does NOT re-print the cache file path because the underlying error message already contains it (see `RemoteConfigUnavailableError._build_unavailable_error` in `remote_config_fetcher.py`). Echoing `str(exc)` is sufficient.
-
-**Verification:**
-- `make agent-check` — clean (ruff fix-imports, ruff format, plxt fmt, ruff lint, plxt lint, pyright, mypy all green).
-- Targeted: `.venv/bin/pytest -n auto -m "not pipelex_api and not llm and not img_gen and not extract and not inference" tests/unit/pipelex/cli/ tests/integration/pipelex/cli/ tests/unit/pipelex/system/ tests/integration/pipelex/system/` — 429 passed (1 expected `RemoteConfigStaleWarning` from `test_telemetry_disabled_when_source_cached`).
-- `make agent-test` — full suite green.
-
-**Next:** Phase 7 — start at **7.1** (`make agent-check` clean) → **7.2** (`make agent-test` clean) → **7.3** (manual reproduction of every behaviour-matrix scenario through the real CLI surface) → **7.4** (squash-friendly commit history + PR description that references the codex-sandbox-escalation handoff and the deferred follow-ups).
-
-### Checkpoint 7 status
-
-**Landed:**
-- No new feature code — Phase 7 is a verification gate. One small message-clarity fix landed during the manual repro of 7.3 (see below).
-- `pipelex/system/pipelex_service/remote_config_fetcher.py` — `_build_unavailable_error` gained a `cache_refused: bool = False` flag. When the dev-CLI path passes `require_fresh=True` and a cache exists on disk, the error message now reads "the local cache at `<path>` was refused because a fresh fetch is required" instead of the previously misleading "no local cache is available at `<path>`". The cache-truly-missing path keeps its original wording. Call site at line 211 passes `cache_refused=True`.
-- `tests/integration/pipelex/system/pipelex_service/test_remote_config_fetcher.py::test_require_fresh_refuses_cache` — strengthened to assert the new "was refused because a fresh fetch is required" phrasing so the contract is pinned.
-- `CHANGELOG.md` — new "Changed" entry under `[Unreleased]` documenting the `RemoteConfigUnavailableError` message branching.
-
-**Manual reproduction summary (7.3):**
-- BYOK offline → covered by `tests/e2e/agent_cli/test_offline_run_dry.py::test_byok_offline_succeeds`.
-- Gateway online, no cache, cache written → covered by `tests/integration/pipelex/system/pipelex_service/test_remote_config_fetcher.py::test_success_returns_fresh_and_writes_cache` and `tests/integration/pipelex/cli/commands/init/test_cache_priming.py::test_init_primes_cache_when_online`.
-- Gateway offline, cache present, stale warning → covered by `test_gateway_known_with_cache_succeeds_offline` (E2E).
-- Gateway offline, no cache, `RemoteConfigUnavailableError` → covered by `test_gateway_no_cache_no_network_fails_with_unavailable` (E2E).
-- Bundle references unknown gateway model → covered by `tests/integration/pipelex/cogt/model_backends/test_gateway_unknown_model.py` plus the E2E `test_gateway_unknown_with_cache_fails_with_clear_error` (the E2E intentionally does not pin `error_type` — see deferred follow-up #7).
-- `pipelex-dev update-gateway-models` offline → manually reproduced via `PIPELEX_REMOTE_CONFIG_URL=http://127.0.0.1:1/unreachable.json .venv/bin/pipelex-dev update-gateway-models`; raises `RemoteConfigUnavailableError` with the new "cache refused because a fresh fetch is required" remediation message, and no docs are written. Also pinned in `test_require_fresh_refuses_cache`.
-
-**Commit history (7.4):**
-- Phase-aligned commits ahead of `main` (`1d9293d3` ... `6b5d0d40`), one per phase boundary. Phase 7 changes are still uncommitted in the working tree (`CHANGELOG.md`, `remote_config_fetcher.py`, `test_remote_config_fetcher.py`) — to be squashed with Phase 6 or landed as a small "polish" commit, at the user's discretion at `/ship` time.
-- PR description should reference (a) the codex-sandbox-escalation handoff in `mthds-plugins/wip/codex-sandbox-escalation.md` — note that `--dry-run` no longer requires escalation once Pipelex has been initialised online once, and (b) the deferred follow-ups list at the bottom of this file (especially #1 `pipelex doctor` cache reporting, #2 Codex Cloud cache-first short-circuit, #3 the cross-repo escalation-doc update, and #7 pinning `GatewayUnknownModelError` end-to-end via a deck override).
-
-**Verification:**
-- `make agent-check` — clean (ruff fix-imports, ruff format, plxt fmt, ruff lint, plxt lint, pyright, mypy all green).
-- `make agent-test` — full suite green (zero output on success).
-- Targeted: `.venv/bin/pytest -n auto -m "(dry_runnable or not (inference or llm or img_gen or extract or search)) and not pipelex_api" tests/unit/pipelex/system/ tests/integration/pipelex/system/ tests/unit/pipelex/cli/ tests/integration/pipelex/cli/` — all green (one expected `RemoteConfigStaleWarning` from `test_telemetry_disabled_when_source_cached`).
-- Manual: `PIPELEX_REMOTE_CONFIG_URL=http://127.0.0.1:1/... .venv/bin/pipelex-dev update-gateway-models` → new "cache refused" wording confirmed in stderr.
-
-**Decision:**
-- The message-clarity fix was made in scope as a Phase 7 finding (no new entry was added to the deferred-follow-ups list). Branching `_build_unavailable_error` is a one-liner with a one-keyword call-site update; the alternative — adding the deferred entry — would have left a known-misleading user-facing message in v0.29.0.
-
-**Next:** Branch is ready for `/ship`. No remaining checkbox in this plan.
diff --git a/wip/archive/operators-as-activities-analysis.md b/wip/archive/operators-as-activities-analysis.md
deleted file mode 100644
index b1d572e73..000000000
--- a/wip/archive/operators-as-activities-analysis.md
+++ /dev/null
@@ -1,139 +0,0 @@
-# Analysis: PipeOperators as Workflows vs. as Activities
-
-## Current architecture (as observed)
-
-**Two layers of workflows wrap every pipe execution:**
-
-1. `WfPipeRun` (top-level) — orchestrates pipe execution + post-run side effects (graph assembly, delivery webhook)
-2. `WfPipeRouter` (child workflow) — sets up per-workflow `LibraryCrate` / `ClassRegistry`, opens a graph tracer, hydrates `WorkingMemory`, delegates to `pipe.run_pipe(...)`, then dehydrates
-
-**Inside `WfPipeRouter`, the actual pipe code runs:**
-
-- A **PipeController** (`PipeSequence`, `PipeParallel`, `PipeBatch`, `PipeCondition`) iterates its sub-pipes. Each `SubPipe.run_pipe()` calls `get_pipe_router().run(...)` → which re-enters `TemporalPipeRouter._run_pipe_job` → which dispatches **another `WfPipeRouter` child workflow** (`pipelex/temporal/tprl_pipe/temporal_pipe_router.py:55-67`). So a sequence of N steps produces N additional child workflows below the parent router.
-- A **PipeOperator** (`PipeLLM`, `PipeImgGen`, `PipeExtract`, etc.) runs in-process inside the same `WfPipeRouter` workflow execution, calling the `ContentGeneratorTop` protocol — which then dispatches **another workflow** per content-generation call (`WfMakeLLMText`, `WfMakeImages`, `WfMakeJinja2Text`, `WfMakeExtract`, …) which itself calls a single activity (`act_llm_gen_text`, etc.).
-
-So the topology is roughly:
-
-```
-WfPipeRun (top)
- └─ WfPipeRouter (parent pipe)
- └─ [Controller iterates]
- ├─ WfPipeRouter (child sub-pipe 1)
- │ └─ [Operator's ContentGenerator]
- │ └─ WfMakeLLMText (workflow)
- │ └─ act_llm_gen_text (activity)
- ├─ WfPipeRouter (child sub-pipe 2)
- │ └─ ...
-```
-
-Pipe code (PipeLLM, PipeSequence, etc.) is **plain Python** and runs *inside* a workflow. The Temporal-ness is achieved by the `ContentGenerator` and `PipeRouter` protocols re-implemented as workflow-dispatching adapters.
-
----
-
-## Alternative: PipeOperators as Activities
-
-The proposed shape would be:
-
-```
-WfPipeRun (top)
- └─ WfPipeRouter (orchestrator)
- └─ [iterates sub-pipes]
- ├─ act_run_pipe_llm(pipe_llm_def, working_memory) ← activity
- ├─ act_run_pipe_extract(...) ← activity
- ├─ act_run_pipe_img_gen(...) ← activity
- └─ child WfPipeRouter for nested controllers
-```
-
-Operators become a single activity that internally does prompt assembly + LLM call + structuring + output stuff building. Controllers stay as workflows because they need durable orchestration of multiple steps.
-
----
-
-## Pros of the alternative (operators-as-activities)
-
-1. **Smaller history footprint.** Today every PipeLLM produces a child `WfPipeRouter` + a `WfMake…` workflow + an activity = 3 workflow executions and ~15+ history events for a single LLM call. As an activity it's ~2 events (`ActivityScheduled` / `ActivityCompleted`). For long sequences, this matters: you can hit the 50 MB / 10K-event soft limit much faster with the current shape.
-
-2. **Less workflow code = less determinism risk.** Today operator code (PipeLLM with prompt templating, structuring choices, output stuff assembly, `pretty_print_stuff`) runs *inside* `WfPipeRouter`. Anything in `pipe_operators/llm/helpers.py`, `pretty_print_stuff`, `_register_execution_data`, and the tracing manager calls runs in workflow context and is subject to sandbox + replay rules. Pushing all of that behind an activity boundary frees that code from determinism constraints — including third-party libs you might want to use later (json libs, jinja2 internals, etc.).
-
-3. **Cheaper retries.** Today if an LLM call fails transiently, Temporal retries the **innermost activity** (`act_llm_gen_text`) — that part is already fine. But if the operator's *post-processing* (e.g. structuring validation) fails, you have a workflow failure that requires patching/versioning. As an activity, the whole operator is one retryable unit.
-
-4. **Simpler mental model.** "Workflows orchestrate, activities do work" is the canonical Temporal pattern. PipeLLM is non-deterministic work (it calls an LLM). Modeling it as an activity matches the framework's grain.
-
-5. **Fewer wrapper classes.** You can collapse the entire `tprl_content_generation/` package — `WfMakeLLMText`, `WfMakeObject`, `WfMakeImages`, `WfMakeJinja2Text`, `WfMakeExtract`, `WfRenderPageViews`, `ContentGeneratorTop`, `ContentGeneratorChild`, plus the dual `top`/`child` factory split — into a flat set of activities. The `with_conditional_worker` decorator and the WorkflowExecutor abstraction become unnecessary at the operator level.
-
-6. **Better observability for "the actual unit of LLM work."** In the Temporal UI today, an LLM call is buried 4 levels deep. As an activity, it's a single line item with input/output/timing.
-
-7. **Activity-level resource controls.** Temporal lets you configure per-activity concurrency, task queues (you already route `act_llm_gen_text` to `inference_task_queue`), and rate limiting. If operators are activities, you get this naturally for the *whole* operator, not just the inference call. Useful when a backend has its own rate limits beyond raw LLM tokens.
-
----
-
-## Cons of the alternative
-
-1. **You lose intra-operator durability.** Today, if the worker crashes mid-PipeLLM (after the LLM responded but before structuring completed), the `act_llm_gen_text` result is durably persisted; on resume, only the structuring is re-attempted. As one activity, the entire PipeLLM re-runs from scratch — you re-pay for the LLM call. This is the **biggest single trade-off**, and it's worse for `make_text_then_object` (two LLM calls) which today benefits from each call being durable independently.
-
-2. **Operator code must be activity-safe in different ways.** Activities have their own constraints: payload-size limits on inputs/outputs, must be idempotent for retries (today retries are scoped to the inference call which is naturally idempotent — moving up means the *whole operator* including stuff-id generation, graph trace events, etc. needs to be safe-to-retry).
-
-3. **Per-step controllability disappears.** Right now `WfMakeLLMText` is its own workflow with its own `workflow_execution_timeout`, `retry_policy`, and `task_queue`. Different content-generation kinds can have different policies. As activities, you still get per-activity policies — *but* the operator-level retry policy is now coarser (the LLM call and the structuring are one retryable unit even though they have different failure modes).
-
-4. **PipeBatch fan-out semantics.** PipeBatch today expands into N parallel sub-pipes via `get_pipe_router().run(...)`, each becoming a child workflow. Each child gets its own retry budget and durable checkpoint. If you push operators into activities, batches of operators become a fan-out of activities (fine), but batches of *controllers* still need workflows. You'll end up with two dispatch paths inside a controller (activity for operators, child workflow for controllers) — slightly more complex than the current uniform "everything is a workflow" rule, even if the runtime is faster.
-
-5. **Tracing/library state.** `WfPipeRouter` currently sets up per-workflow `LibraryCrate`, `ClassRegistry`, `BufferingEventLog`, and tracer key, and tears them down in `finally`. Some of this state currently lives in workflow-local variables. If the operator is an activity, the activity will run on a worker that may not have this state set up — you'd have to either (a) pass the crate to every activity (large payloads, repeated through history), or (b) keep the controller workflow's setup and rely on the worker to pick up the right context per activity invocation (which is awkward because activities aren't co-located with the workflow worker by default — you specifically use `inference_task_queue` to route the inference call to inference workers).
-
-6. **`PipeJob` payload in every activity.** Today the dehydrated `WorkingMemory` flows through `WfPipeRouter` as a workflow input; from there, only small `LLMAssignment`-type payloads cross the activity boundary. If operators are activities, the full `WorkingMemory` (or its relevant subset) crosses the activity boundary on each call — and goes into history once (workflow → activity input → activity output → workflow). For a long sequence, the same `WorkingMemory` may cross many activity boundaries. You'd want to invest in S3-backed payloads or `WorkingMemory` deltas to avoid history bloat. This partially negates pro #1.
-
-7. **Image/file payloads.** `wf_make_images.py` exists explicitly because image generation produces large binary payloads — there's already logic to store images at the activity level rather than in workflow history. Pushing operators up to activity-grain doesn't immediately break that, but you'd have to be careful that operator inputs/outputs continue to use references (URIs/IDs), not raw bytes.
-
-8. **Loss of fine-grained progress for the user.** In Temporal UI / event history, you can see *exactly* what each PipeLLM did (template rendering activity vs. LLM activity vs. object structuring activity, in the current `wf_make_text_then_object`). As one activity, you lose that granularity and replace it with logs/heartbeats inside the activity. For debugging production LLM pipelines, the current granularity is actually valuable.
-
-9. **Dry-run / direct-mode parity.** Pipelex pipes also run outside Temporal (direct mode). The operator's current "I just call a Python protocol method" works identically in direct mode. As an activity, the operator's `_live_run_operator_pipe` and the activity definition would diverge — you'd need a layer that calls them both from the same Python entry point. Not impossible (you already have `with_conditional_worker`), but it's added surface area on a code path that's currently uniform.
-
----
-
-## Refactoring effort
-
-If you wanted to move operators to activities, here's the rough shape of the work:
-
-### Mandatory, high-effort
-
-1. **Define one activity per operator type** (or one generic `act_run_operator(pipe_def, working_memory)`). Decide the granularity:
- - Per-type (`act_run_pipe_llm`, `act_run_pipe_img_gen`, `act_run_pipe_extract`, `act_run_pipe_func`, `act_run_pipe_search`, `act_run_pipe_compose`) — better typing, more activity registrations.
- - One generic activity dispatching on `pipe.type` — simpler registration, weaker typing.
-
-2. **Refactor `ContentGeneratorTop` / `ContentGeneratorChild`.** Today they exist *because* operators run inside workflows and need to dispatch via `execute_workflow` / `execute_child_workflow`. Once operators are activities, the `ContentGenerator` adapter pattern can be deleted: the activity body just calls the direct (non-Temporal) `ContentGenerator`. This deletes most of `tprl_content_generation/` (`wf_make_*.py`, `content_generator_top.py`, `content_generator_child*.py`). Keep the inference activities (`act_llm_generate.py`, etc.) but they're now *internal helpers* the operator activity calls directly — or just inline them.
-
-3. **WorkingMemory transit.** Each operator activity needs `WorkingMemory` as input and a `PipeOutput` (containing updated `WorkingMemory`) as output. This is the same dehydrate/rehydrate dance you already do at workflow boundaries — generalize `prepare_for_temporal()` / `rehydrate_pipe_output_with_crate()` to also work at activity boundaries. Probably need a "delta" form (only what changed) to avoid re-emitting the full memory on each step. **This is the trickiest piece** because of `kajson`'s class-registry-aware deserialization — activities running on inference workers need access to the `LibraryCrate`'s dynamic classes.
-
-4. **LibraryCrate propagation to activities.** The crate currently flows into `WfPipeRouter` and is loaded into a per-workflow `ClassRegistry`. For activity execution, the activity worker must have the crate available — either pass it on every activity invocation (expensive, repeated in history) or maintain per-activity-worker session caches keyed by `pipeline_run_id`. The cleanest path is probably the latter: a "load crate" activity that primes the worker, then operator activities reference it by pipeline-run ID. Cache eviction and cross-worker concurrency need thought.
-
-5. **`PipeRouter` rewrite.** `TemporalPipeRouter._run_pipe_job` currently dispatches `WfPipeRouter` for *any* pipe. It would need to:
- - For controllers → still dispatch `WfPipeRouter` (or new controller-specific workflows).
- - For operators → if called from inside a workflow, dispatch the operator activity; if called from outside (direct call), spin up a `WfPipeRouter` to wrap it. The "outside Temporal entirely" path stays the same.
-
-6. **PipeController bodies.** Today `PipeSequence._live_run_controller_pipe` does `await sub_pipe.run_pipe(...)` which routes through `get_pipe_router()`. That router is currently a `TemporalPipeRouter` when running under Temporal, so each sub-pipe becomes a child workflow. After the refactor, the router needs to know whether the sub-pipe is operator-or-controller and pick activity vs. child workflow. This is a small change but it touches every controller.
-
-7. **Tracing/observability integration.** The `BufferingEventLog` flush currently happens at the end of `WfPipeRouter` via `act_flush_trace_events`. If operators are activities, you need a way to capture trace events emitted *inside* the operator activity and surface them back to the parent workflow's buffering log — likely return them as part of the activity output and let the workflow append them.
-
-8. **Replay/versioning story.** You have running Pipelex workflows in production (presumably). Changing the workflow shape is a non-trivial versioning event. You'd need either (a) a hard cut-over with all in-flight workflows drained first, or (b) Temporal's `patched()` API at every controller's dispatch site to keep both shapes alive during transition. With your "no backward compatibility" rule, hard cut-over is the natural choice — but only if you can guarantee no in-flight Pipelex workflows during the deploy.
-
-### Optional / nice-to-have
-
-9. **Collapse `WfPipeRun` and `WfPipeRouter`.** Once operators no longer need a workflow boundary, the two-level workflow split (`WfPipeRun` for delivery, `WfPipeRouter` for actual run) might be simplifiable to a single workflow per top-level pipe call.
-
-10. **Per-operator task queues.** With operators as activities you can route each operator type to a different worker pool (e.g. `extract` to a heavy-CPU pool, `llm` to a thin async pool). You partially do this today via `inference_task_queue` for the innermost activity.
-
-### Test/infra impact
-
-11. The `temporal-test-crate` and `temporal-e2e-validate` test suites encode assumptions about the current workflow topology (cross-process serialization, deferred hydration, ClassRegistry scoping). These tests would need substantial rewrites — particularly the LibraryCrate / ClassRegistry isolation tests, since the propagation model changes.
-
-12. Replay tests against existing histories will all break — either delete them or keep around a "legacy replay" suite during transition.
-
-**Rough size estimate:** Medium-large refactor. The file changes are concentrated (~15-25 files), but the ClassRegistry / WorkingMemory transit logic at activity boundaries is genuinely subtle and is where most of the bug-finding effort would go. Budget on the order of 2–3 weeks of focused work plus another week or two on the test rewrite, assuming direct-mode parity is preserved throughout.
-
----
-
-## Recommendation
-
-**The current architecture is more "Temporal-canonical" only at first glance.** "Workflows orchestrate, activities do work" is the rule, and PipeLLM *is* work — so on paper it should be an activity. But the current shape buys something real: **per-call durability for LLM completions**, which is the most expensive thing a Pipelex pipe does. Losing that to retry whole operators would be a meaningful regression on cost and latency under failure.
-
-The strongest case for refactoring isn't "operators should be activities" wholesale — it's **collapsing the `tprl_content_generation/` workflow layer**. That layer adds ~6 workflow types that wrap a single activity each. Eliminating those workflow wrappers (calling the activity directly from `PipeLLM.run` running inside `WfPipeRouter`) gets most of the history/footprint benefit without losing per-LLM-call durability. The inference call stays a durable activity; only the redundant workflow shell around it goes away.
-
-If pursuing that narrower change first, the scope is much smaller — basically delete `wf_make_*.py` and `content_generator_top.py` / `content_generator_child*.py`, and have `ContentGenerator` (in operator code) directly call `workflow.execute_activity(act_llm_gen_text, ...)` when running inside a workflow.
diff --git a/wip/archive/per-activity-queue-routing-v1.md b/wip/archive/per-activity-queue-routing-v1.md
deleted file mode 100644
index fa5b79fac..000000000
--- a/wip/archive/per-activity-queue-routing-v1.md
+++ /dev/null
@@ -1,271 +0,0 @@
-# Per-activity, per-handle Temporal queue routing
-
-> **Status:** Shipped (v1 implementation landed on `feature/Per-activity-queue`). `WorkerConfig.resolve_queue(activity_name, routing_key)` is now the single dispatch site; `_inference_dispatch_kwargs` and `WorkerConfig.inference_task_queue` are deleted. Open Question #1 resolved by keeping `task_queue` as the worker-wide default field name. Open Question #5 resolved by putting the resolver as a method on `WorkerConfig`. Open Questions #2 (scope-declared listen_queues), #3 (per-pipe override), and #4 (dynamic hook) deferred — not required for v1. The two startup validators in § Validation are deferred to a follow-up.
->
-> **Predecessor context:** `inference_task_queue` was introduced as a quick split-worker test ("LLM goes here, everything else goes to default"). That two-queue model is now superseded by per-activity routing.
->
-> **Test upgrade follow-up:** the two deferred tests (`test_split_worker_object_gen.py`, `test_split_worker_extract_pages.py`) were patched in v1 with `route_activities_to(...)` so they exercise the new resolver but still run on a single worker. Upgrading them to true split workers (router queue + runner queue with the substitutes registered only on the runner) is the remaining piece of § Tests to upgrade when v1 lands.
-
-## First actions (cold-start checklist)
-
-To orient yourself in a new session, in this order:
-
-1. Work happens on `feature/Per-activity-queue`, branched off `feature/Temporal-primitives-tto-merge` (the integration branch where the predecessor `refactor/Temporal-primitives` is merged in alongside the TTO work). Confirm with `git branch --show-current`.
-2. Map the deletion point and its pins: `grep -rn "_inference_dispatch_kwargs\|inference_task_queue" pipelex/ tests/`. Expect ~5 source hits (the helper itself, its single caller in `make_llm_text`, the config field on `WorkerConfig`) and ~10 test hits (the two unit-test pin sites in `tests/unit/pipelex/temporal/test_content_generator_in_workflow.py` and the integration fixture in `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py`).
-3. Read the current `WorkerConfig` shape (`pipelex/temporal/config_temporal.py` around line 175) and the default values in `pipelex/pipelex.toml` under `[temporal.worker_config]`. The schema change lands in both.
-4. Verify the assignment-model handles still expose what § Per-activity routing keys claims: `grep -n "llm_handle\|img_gen_handle\|extract_handle" pipelex/cogt/content_generation/assignment_models.py`. The doc is dated against today's tree; re-verify in case anyone renamed since.
-5. Gates: `make agent-check` (lint/types) and `make agent-test` (silent on success) after each phase. Follow CLAUDE.md.
-
-## Problem
-
-Pipelex deployments need worker-pool granularity beyond the current binary "inference / default" split:
-
-- **Per-provider scaling.** OpenAI worker pool scaled separately from Anthropic worker pool — independent rate limits, independent failure isolation, independent cost accounting.
-- **Per-model scaling.** A heavy reasoning model (Claude Opus, o1) scaled differently from a fast model (Haiku, GPT-5 nano).
-- **Per-activity-class isolation.** Image generation (slow, expensive, heavyweight payloads) on a different pool than LLM text.
-- **Per-extract-backend.** OCR backend A on its own pool, backend B on another.
-
-Today the dispatch side cannot express any of this. The registration side (`WorkerScopesConfig`) already supports arbitrary scopes — the gap is on the **dispatch** side, where every LLM call goes to a single `inference_task_queue` and every other activity goes to the workflow's own queue.
-
-## Goals
-
-- Configurable routing of every inference activity (LLM, image-gen, extract) to a named queue based on `(activity_name, runtime_handle)`.
-- Single config table. No special-case keys.
-- Workflow determinism preserved: routing decision uses only data already serialized into the activity assignment.
-- Trivial fallback path: any `(activity, handle)` pair not explicitly mapped falls through to a per-activity default and finally to a worker-wide default queue.
-- The "asymmetry" disappears: every inference dispatch site calls the same resolver. Non-inference dispatches don't, and the resolver returns the default for them.
-
-## Non-goals (v1)
-
-- Conditional routing on multiple dimensions (provider AND reasoning_effort AND ...). One key per activity (the handle) is enough until proven otherwise.
-- Resolving handles to backends inside the workflow. (See "Provider-resolution problem" below — we route by handle name, not by resolved provider.)
-- Routing for orchestration activities (`act_deliver`, `act_assemble_graph`, `act_flush_trace_events`, `act_jinja2_gen_text`, `act_render_page_views`). These have no per-handle dimension; they run on the workflow's own queue.
-- Dynamic routing (a callable hook). Static config covers the use cases. Re-evaluate if a real need surfaces.
-
-## The provider-resolution problem
-
-At dispatch time inside the workflow, we have only the model handle string (`LLMSetting.model = "claude-opus-4-7"` or `"@reasoning-fast"` once aliases are resolved). We do **not** have the resolved backend/provider — that resolution lives in `RoutingProfileLibrary` and backend configs, which the workflow can't safely consult (non-determinism, plus pulling the entire model registry into the workflow's deterministic state would be expensive).
-
-**Decision: route by handle, not by provider.** The user already knows which handles map to which backends. Their queue names align with provider/model groupings as a *convention*, not as an enforced derivation. Example:
-
-- `gpt-5` → `openai_q`
-- `gpt-5-mini` → `openai_q`
-- `claude-opus-4-7` → `anthropic_q`
-- `claude-haiku-4-5` → `anthropic_q`
-
-If the user wants to group by provider, they group manually in config. Simple, explicit, deterministic.
-
-## Schema
-
-Replace the current `task_queue: str` + `inference_task_queue: str | None` in `WorkerConfig` with a single per-activity table.
-
-```toml
-[temporal.worker_config]
-default_task_queue = "temporal_task_queue"
-
-# Per-activity routing tables. Each entry declares:
-# default = the queue when no per-handle override matches
-# by_handle = optional { handle_name -> queue }
-#
-# Activities NOT listed here use default_task_queue.
-
-[temporal.worker_config.activity_queues.act_llm_gen_text]
-default = "inference_q"
-by_handle = { "claude-opus-4-7" = "anthropic_q", "gpt-5" = "openai_q" }
-
-[temporal.worker_config.activity_queues.act_llm_gen_object]
-default = "inference_q"
-by_handle = { "claude-opus-4-7" = "anthropic_q", "gpt-5" = "openai_q" }
-
-[temporal.worker_config.activity_queues.act_llm_gen_object_list]
-default = "inference_q"
-by_handle = { "claude-opus-4-7" = "anthropic_q", "gpt-5" = "openai_q" }
-
-[temporal.worker_config.activity_queues.act_img_gen_images]
-default = "image_gen_q"
-by_handle = { "flux-1.1-pro" = "fal_q", "dall-e-3" = "openai_image_q" }
-
-[temporal.worker_config.activity_queues.act_extract_gen_extract_pages]
-default = "extract_q"
-by_handle = { "mistral-ocr" = "mistral_extract_q" }
-```
-
-Resolution order at dispatch:
-
-1. Look up `activity_queues[activity_name]`.
- - If absent: use `default_task_queue`. Done.
-2. Within that block, look up `by_handle[runtime_handle]`.
- - If found: use it. Done.
-3. Fall back to that activity's `default`. Done.
-
-Three layers, no surprises.
-
-Pydantic shape:
-
-```python
-class ActivityRouteConfig(ConfigModel):
- default: str
- by_handle: dict[str, str] = Field(default_factory=dict)
-
-class WorkerConfig(ConfigModel):
- default_task_queue: str
- activity_queues: dict[str, ActivityRouteConfig] = Field(default_factory=dict)
- # ... existing timeout / retry fields unchanged
-```
-
-## Per-activity routing keys
-
-The dispatcher extracts the routing key from each assignment shape. All three handles already exist on the assignment models — no model-shape changes required.
-
-| Activity | Assignment | Routing key |
-| --- | --- | --- |
-| `act_llm_gen_text` | `LLMAssignment` | `llm_assignment.llm_handle` (= `llm_setting.model`) |
-| `act_llm_gen_object` | `ObjectAssignment` | `object_assignment.llm_assignment_for_object.llm_handle` |
-| `act_llm_gen_object_list` | `ObjectAssignment` | same as above |
-| `act_img_gen_images` | `ImgGenAssignment` | `img_gen_assignment.img_gen_handle` |
-| `act_extract_gen_extract_pages` | `ExtractAssignment` | `extract_assignment.extract_handle` |
-| `act_render_page_views` | `RenderPageViewsAssignment` | none — uses `default_task_queue` |
-| `act_jinja2_gen_text` | `TemplatingAssignment` | none — uses `default_task_queue` |
-| `act_deliver`, `act_assemble_graph`, `act_flush_trace_events` | various | none — `default_task_queue` |
-
-Definitions verified against `pipelex/cogt/content_generation/assignment_models.py` (LLM/ImgGen/Extract assignments all expose their handle directly).
-
-## Dispatcher
-
-A single resolver lives next to `WorkerConfig`:
-
-```python
-def resolve_queue(
- worker_config: WorkerConfig,
- activity_name: str,
- routing_key: str | None = None,
-) -> str:
- activity_route = worker_config.activity_queues.get(activity_name)
- if activity_route is None:
- return worker_config.default_task_queue
- if routing_key is not None:
- per_handle = activity_route.by_handle.get(routing_key)
- if per_handle is not None:
- return per_handle
- return activity_route.default
-```
-
-Each `make_*` method in `ContentGeneratorInWorkflow` extracts its own routing key and calls `resolve_queue`:
-
-```python
-queue = resolve_queue(
- worker_config,
- activity_name="act_llm_gen_text",
- routing_key=llm_assignment.llm_handle,
-)
-generated_text = await workflow.execute_activity(
- act_llm_gen_text,
- arg=llm_assignment,
- task_queue=queue,
- start_to_close_timeout=worker_config.workflow_execution_timeout,
- retry_policy=worker_config.retry_policy,
- activity_id=activity_id,
-)
-```
-
-Every dispatch site uses the same shape — `task_queue=queue`. Activities that don't need per-handle routing pass `routing_key=None`, get the default queue back, and the kwarg is uniform across all sites. The "asymmetric kwarg" disappears.
-
-## Worker registration: matching scopes to queues
-
-A worker in this design picks a **scope** (which activities to register) AND **one or more queues** (which task queues to listen on). `WorkerScope` already maps cleanly to "set of activities". Two viable options for queue assignment:
-
-**Option 1 — Scope declares its queues** (cleaner — scope is the deployment unit):
-
-```toml
-[temporal.worker_scopes.scopes.openai_runner]
-required_activities = ["act_llm_gen_text", "act_llm_gen_object", "act_llm_gen_object_list"]
-disable_all_workflows = true
-listen_queues = ["openai_q"] # NEW
-
-[temporal.worker_scopes.scopes.anthropic_runner]
-required_activities = ["act_llm_gen_text", "act_llm_gen_object", "act_llm_gen_object_list"]
-disable_all_workflows = true
-listen_queues = ["anthropic_q"] # NEW
-```
-
-**Option 2 — CLI flag overrides the queue** (current model extended). Already exists in `worker_cli.py:48` (`--task-queue`). Could grow `--task-queue-extra` for multi-queue listening.
-
-Lean toward Option 1 — the scope captures the full deployment intent in one place. Decide during implementation.
-
-## Migration from `inference_task_queue`
-
-Per the project's "no backward compatibility" rule, the field is deleted in the same release with a CHANGELOG note. If a transition is wanted anyway, the loader can synthesize entries:
-
-```python
-if legacy_inference_queue is not None:
- for activity_name in ("act_llm_gen_text", "act_llm_gen_object", "act_llm_gen_object_list"):
- if activity_name not in activity_queues:
- activity_queues[activity_name] = ActivityRouteConfig(default=legacy_inference_queue)
-```
-
-Default config in `pipelex.toml` would set `default_task_queue = "temporal_task_queue"` and leave `activity_queues` empty — same effective behavior as today's "everything on the default queue" baseline.
-
-## Validation
-
-Two cheap startup validators worth adding:
-
-1. **No orphan queues.** Every queue named in `activity_queues` (as `default` or in `by_handle`) should be covered by at least one `WorkerScope.listen_queues` (Option 1) or by some configured worker. Misconfigured deployments where a queue has no listeners would hang forever — fail fast at boot.
-2. **No unknown activities.** Every key in `activity_queues` should match a registered activity name. Catches typos.
-
-## Open questions
-
-1. **Naming.** `default_task_queue` (more explicit) vs keeping `task_queue` (less churn). Slight lean toward keeping `task_queue` for the smallest diff.
-2. **Multi-queue workers.** Temporal SDK lets one worker listen on N queues (must register all their activities). With per-provider routing, a "general inference fallback" worker that listens on multiple queues could absorb overflow. Out of scope for v1; design accommodates it via Option 1's `listen_queues`.
-3. **Per-pipe routing override.** A user might want one specific pipe's LLM call to go to a special queue (a long-running pipe to a dedicated pool). Skip for v1 — handles cover the use case.
-4. **Dynamic routing hook.** Skip for v1. Document the escape hatch (custom Python helper) as a v2 consideration if a use case appears.
-5. **Where does the resolver live?** Options: a new tiny module `pipelex/temporal/queue_routing.py`; a method on `WorkerConfig`; a free function next to `WorkerConfig`. Method-on-config keeps it discoverable; free function is easier to mock. Slight lean toward method.
-
-## What stays unchanged
-
-- `WorkerScope` and `WorkerScopesConfig` (registration): no schema change beyond Open Question #2's optional `listen_queues`.
-- Activity definitions (`@activity.defn(name=...)`): no change.
-- Workflow code: no change beyond replacing the asymmetric kwarg with `task_queue=resolve_queue(...)`.
-- Assignment models: no change. The handles are already there.
-
-The change surface is concentrated in:
-
-- `pipelex/temporal/config_temporal.py` (`WorkerConfig` schema + `ActivityRouteConfig`)
-- `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py` (call sites use the resolver)
-- A new tiny resolver (free function or method on `WorkerConfig`)
-- `pipelex.toml` (default config: empty `activity_queues`, single `default_task_queue`)
-- Tests (unit tests for the resolver; integration test that exercises per-handle routing in a split-worker setup)
-- Docs (CHANGELOG; under-the-hood section on queue routing)
-
-## Test plan (sketch)
-
-New tests added by this work:
-
-- **Unit:** `resolve_queue` covers all three layers — unmapped activity → default; mapped activity, unmapped handle → activity default; mapped activity, mapped handle → per-handle queue.
-- **Integration (positive):** a split-worker setup with two named runners (e.g. `openai_runner` listening on `openai_q`, `anthropic_runner` listening on `anthropic_q`). Submit a workflow that dispatches an LLM call with each handle and assert via `WorkflowHandle.fetch_history()` that the activity landed on the expected queue. Mirror the structure of `tests/integration/pipelex/temporal/tracing/test_split_worker_usage.py` (which currently exercises the legacy `inference_task_queue` path).
-- **Integration (negative):** the boot-time validators catch (a) a queue with no listeners and (b) an unknown activity name in `activity_queues`.
-
-## Tests to upgrade when v1 lands
-
-Phase 7 of the `tprl_content_generation/` collapse landed three new pytest files. Two of them deliberately use a single-worker setup because the per-activity routing this design proposes did not yet exist. When v1 ships, upgrade these tests to true split-worker setups so they exercise the cross-process activity boundary the way `test_split_worker_usage.py` does for LLM-text. The data-converter round-trip aspect they test today is real, but they do NOT test cross-process registry decode (the bug class that surfaces in Tier 2b of `temporal-e2e-validate/SKILL.md` — runner with cold `sys.modules` / `ClassRegistry`).
-
-| Test file | Today's setup (single worker) | Upgrade target (true split worker) |
-| --- | --- | --- |
-| `tests/integration/pipelex/temporal/tracing/test_split_worker_object_gen.py` | Substitute activities for `act_llm_gen_object` / `act_llm_gen_object_list` register on the workflow's own queue. Temporal's data converter still serializes the `FixtureInvoice` round-trip (nested `FixtureCustomer` + `list[FixtureLineItem]`), so the `model_dump(mode="json", serialize_as_any=True)` ↔ `model_validate(...)` contract IS validated. What's NOT validated: the activity executing in a separate Python process with its own `sys.modules` and class registry. | Run the workflow on `q_router` and route `act_llm_gen_object*` to `q_runner` via the new `activity_queues` config. The substitutes register on `q_runner` only. This exercises the same cross-process registry decode path that surfaces real bugs for dynamic concept classes. |
-| `tests/integration/pipelex/temporal/tracing/test_split_worker_extract_pages.py` | Substitutes for `act_extract_gen_extract_pages` and `act_render_page_views` register on the workflow's own queue. The activity_id contract (`-pages` / `-render-page-views` via `fetch_history()`) IS validated regardless of worker count. | Route both extract activities to a runner queue. Activity_id assertion stays; cross-process dispatch is now genuinely exercised. |
-
-Both files contain a `Note on "split worker"` block in their module docstrings that records the deviation explicitly. Remove those blocks during the upgrade — they exist to prevent the next reader from assuming the test does more than it does.
-
-The third file from Phase 7 (`test_split_worker_usage.py` for LLM-text) does NOT need an upgrade; it already runs split workers via the legacy `inference_task_queue` routing. Migrating it to the new resolver is a one-line change (replace the `worker_config.inference_task_queue = q_runner` fixture with an `activity_queues[act_llm_gen_text].default = q_runner` override).
-
-Adjacent surfaces to revisit at the same time:
-
-- `.claude/skills/temporal-e2e-validate/SKILL.md` — Tier 10 (image-gen negative-routing, "`grep -c "act_img_gen"` on the runner pool must return 0") becomes config-driven post-v1: a scope's `listen_queues` plus the activity's resolver entry are enough to enforce it without ad-hoc `excluded_activities` lists. Update the Tier 4/5/10 instructions accordingly.
-- `pipelex/temporal/test_extras/temporal_registry_test_models.py` — `FixtureInvoice` / `FixtureCustomer` / `FixtureLineItem` registrations stay; the cross-process upgrade only changes who runs the activity, not the model shape.
-- `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py::_inference_dispatch_kwargs` — the deletion point. Remove it in the same change that introduces `resolve_queue`.
-- `tests/unit/pipelex/temporal/test_content_generator_in_workflow.py` — the positive/negative `task_queue` assertions are pinned to `_inference_dispatch_kwargs` as a single-deletion-point sentinel. They will need to be rewritten for the new resolver: positive assertion becomes "every inference dispatch site passes `task_queue=<resolved>`" (uniform across activities), negative becomes "non-inference dispatches pass the default queue". The asymmetric kwarg disappears — that's the whole point.
-
-## Relationship to predecessor PR (`refactor/Temporal-primitives`)
-
-The predecessor collapsed `tprl_content_generation/` workflow types to direct activity dispatch — that surface is exactly the place where this routing change lands. The predecessor shipped with a tiny `_inference_dispatch_kwargs(worker_config)` helper that isolates the existing two-queue logic to a single deletion point (see `TODOS.md` Phase 7 — "Stopgap for this PR"). This v1 design replaces the helper with a real per-activity resolver.
-
-The text-then-object (TTO) merge that landed alongside the predecessor is orthogonal to this change: TTO's `BundleElaborator` rewrites `structuring_method = "preliminary_text"` into a `PipeSequence(PipeLLM → PipeStructure)` at parse time, and the synthesized `PipeStructure` step dispatches `act_llm_gen_object` through the same `ContentGeneratorInWorkflow` surface as any user-authored PipeStructure. It will be routed by the new resolver identically — no special-casing required.
diff --git a/wip/archive/phase0-pipe-namespace-fix.md b/wip/archive/phase0-pipe-namespace-fix.md
deleted file mode 100644
index 1befe4d18..000000000
--- a/wip/archive/phase0-pipe-namespace-fix.md
+++ /dev/null
@@ -1,195 +0,0 @@
-# Pipe Namespace Fix: Domain-Qualified `pipe_ref`
-
-> **Status**: Technical spec — Phase 0 of the master plan
-> **Date**: 2026-03-23
-> **Related**: [00-master-plan.md](00-master-plan.md), [archive/early-library-as-execution-context.md](archive/early-library-as-execution-context.md)
-
----
-
-## 1. Problem
-
-Pipes and concepts have asymmetric namespace behavior in the library.
-
-**Concepts** are indexed by `concept_ref` = `domain.ConceptCode` (e.g., `scoring.WeightedScore`). Two concepts with the same code in different domains coexist without conflict. This is correct.
-
-**Pipes** are indexed by bare `code` (e.g., `compute_score`, not `scoring.compute_score`). If two domains define a pipe with the same code, the second collides with the first.
-
-### Where the asymmetry lives
-
-| Component | Concept key | Pipe key |
-|-----------|-------------|----------|
-| `ConceptLibrary.root` | `concept_ref` = `domain.Code` | — |
-| `PipeLibrary.root` | — | bare `code` |
-| `add_new_concept()` | checks `concept.concept_ref` | — |
-| `add_new_pipe()` | — | checks `pipe.code` |
-| `get_optional_concept()` | looks up by `concept_ref` | — |
-| `get_optional_pipe()` | looks up by bare `code`, domain validation is a fallback | — |
-
-### Code references
-
-- `PipeLibrary.add_new_pipe()` at `pipe_library.py:39-48`: keys by `pipe.code`
-- `PipeLibrary.get_optional_pipe()` at `pipe_library.py:56-82`: primary lookup by bare code, domain-qualified lookup is a fallback that still resolves to bare code internally
-- `ConceptLibrary.add_new_concept()` at `concept_library.py:81-85`: keys by `concept.concept_ref`
-- `library_manager.py:378`: `pipe_source_in_this_load` tracks by bare `pipe_code`
-- `library_manager.py:402`: `_pipe_source_map` tracks by bare `pipe_code`
-
-### Additional issue: Domain merging
-
-`DomainLibrary.add_domain()` at `domain_library.py:32-37` raises if the domain already exists. This prevents multiple bundles from contributing to the same domain — a legitimate use case (e.g., `scoring_core.mthds` and `scoring_advanced.mthds` both declaring `domain: scoring`).
-
----
-
-## 2. The Fix
-
-### 2.1 Add `pipe_ref` to `PipeAbstract`
-
-```python
-# pipelex/core/pipes/pipe_abstract.py
-class PipeAbstract(ABC, BaseModel):
- code: str
- domain_code: str
- # ...
-
- @property
- def pipe_ref(self) -> str:
- """Domain-qualified pipe reference, e.g. 'scoring.compute_score'."""
- return f"{self.domain_code}.{self.code}"
-```
-
-This mirrors `concept_ref` on `Concept` (which is `domain.ConceptCode`).
-
-### 2.2 Rekey `PipeLibrary`
-
-```python
-# pipelex/libraries/pipe/pipe_library.py
-PipeLibraryRoot = dict[str, PipeAbstract] # key changes from code to pipe_ref
-
-def add_new_pipe(self, pipe: PipeAbstract):
- if pipe.pipe_ref in self.root:
- msg = f"Pipe '{pipe.pipe_ref}' already exists in the library. ..."
- raise PipeLibraryError(msg)
- self.root[pipe.pipe_ref] = pipe
-```
-
-### 2.3 Update lookup methods
-
-`get_optional_pipe()` needs to handle three lookup forms:
-
-1. **Domain-qualified** (`scoring.compute_score`): Direct lookup by `pipe_ref` — this becomes the primary path
-2. **Bare code** (`compute_score`): Search across all domains. If exactly one match, return it. If multiple matches (same code in different domains), raise ambiguity error. If zero matches, return None.
-3. **Cross-package** (`alias->scoring.compute_score` or `alias->compute_score`): Existing aliased lookup, adjusted for `pipe_ref` keying
-
-```python
-def get_optional_pipe(self, pipe_code: str) -> PipeAbstract | None:
- # 1. Direct lookup (works for pipe_ref and cross-package keys)
- pipe = self.root.get(pipe_code)
- if pipe is not None:
- return pipe
-
- # 2. Cross-package refs
- if QualifiedRef.has_cross_package_prefix(pipe_code):
- alias, remainder = QualifiedRef.split_cross_package_ref(pipe_code)
- # Try domain-qualified remainder
- pipe = self.root.get(f"{alias}->{remainder}")
- if pipe is not None:
- return pipe
- # Try bare code remainder — search aliased entries
- if "." not in remainder:
- # ... search alias->domain.code entries
- pass
- return None
-
- # 3. Bare code — search across domains
- if "." not in pipe_code:
- matches = [p for p in self.root.values() if p.code == pipe_code]
- if len(matches) == 1:
- return matches[0]
- if len(matches) > 1:
- domains = [p.domain_code for p in matches]
- msg = f"Ambiguous pipe code '{pipe_code}' found in domains: {domains}. Use domain-qualified ref."
- raise PipeLibraryError(msg)
- return None
-
- return None
-```
-
-### 2.4 Update `library_manager.py`
-
-In `load_from_blueprints()`:
-- `pipe_source_in_this_load` should key by `pipe_ref` (= `f"{blueprint.domain}.{pipe_code}"`)
-- `_pipe_source_map` should key by `pipe_ref`
-
-### 2.5 Fix domain merging
-
-Domains are namespace metadata — they carry `code`, `description`, and `system_prompt`. Since the LibraryCrate is flat (no domain-level grouping), domains exist only in the live `Library` as lightweight metadata objects extracted from the refs.
-
-`DomainLibrary.add_domain()` should be idempotent for re-adds of the same domain:
-
-```python
-def add_domain(self, domain: Domain):
- domain_code = domain.code
- if domain_code in self.root:
- # Same domain from another bundle — idempotent (Domain is just namespace metadata)
- return
- self.root[domain_code] = domain
-```
-
-Since domains carry no meaningful runtime state beyond the namespace itself, simple idempotency is sufficient. The `system_prompt` field on Domain is a legacy convenience (PipeLLM fallback) that should be inlined at pipe factory time before crate construction.
-
----
-
-## 3. Migration: Call Sites to Update
-
-Every place that passes a bare pipe code as a lookup key needs to be audited. Most will continue to work because the bare-code fallback handles unambiguous lookups. But some sites may need to pass domain-qualified refs.
-
-### Direct `get_required_pipe()` / `get_optional_pipe()` callers
-
-These are the 41 files identified in the investigation. Key categories:
-
-- **Pipe controllers** (`sub_pipe.py`, `pipe_sequence.py`, `pipe_batch.py`, `pipe_parallel.py`, `pipe_condition.py`): These call `get_required_pipe()` with the sub-pipe code from the blueprint. Currently bare codes. If the pipe is in the same domain, the bare code lookup will find it (unambiguous). If cross-domain, the blueprint already uses domain-qualified or cross-package refs.
-
-- **Pipeline setup** (`pipeline_run_setup.py`, `pipeline_manager.py`): Calls `get_required_pipe(pipe_code=pipe_code)` where `pipe_code` comes from user input or `main_pipe`. User input may be bare or qualified — the fallback handles both.
-
-- **Hub helpers** (`hub.py`): Thin wrappers, no change needed beyond forwarding.
-
-- **Temporal routers** (`pipe_router_top.py`, `pipe_router_child.py`): Same pattern as pipeline setup.
-
-- **CLI commands**: Various show/validate/run commands that resolve pipes by code. Should work via fallback.
-
-### `_pipe_source_map` consumers
-
-`library_manager.py` uses `_pipe_source_map` to track which file a pipe came from. Must rekey by `pipe_ref`. Check `get_pipe_source()` method.
-
-### Tests
-
-Existing test helpers that create pipes and add them to libraries will need to provide `domain_code` for proper `pipe_ref` generation. Check all test fixtures and factories.
-
----
-
-## 4. Test Plan
-
-### Unit tests for `PipeLibrary`
-
-1. **Multi-domain coexistence**: Create two pipes with same code (`compute_score`) in different domains (`scoring`, `analytics`). Add both to same `PipeLibrary`. Both exist and are retrievable by `pipe_ref`.
-
-2. **Domain-qualified lookup**: Look up `scoring.compute_score` → returns scoring domain's pipe. Look up `analytics.compute_score` → returns analytics domain's pipe.
-
-3. **Bare-code unambiguous**: When only one pipe with code `compute_score` exists, bare lookup `compute_score` returns it.
-
-4. **Bare-code ambiguous**: When two domains both have `compute_score`, bare lookup `compute_score` raises `PipeLibraryError` with helpful message listing the domains.
-
-5. **Cross-package refs still work**: `alias->scoring.compute_score` lookup works with `pipe_ref`-keyed entries.
-
-### Unit tests for `DomainLibrary`
-
-6. **Domain idempotency**: Add domain `scoring` twice → no error, domain exists once.
-
-### Integration tests
-
-7. **Load multi-bundle same domain**: Create two `.mthds` files both declaring `domain: scoring` with different pipes. Load both. All pipes accessible. Domain exists once.
-
-8. **Full pipeline through multi-domain library**: A PipeSequence referencing pipes from multiple domains runs correctly.
-
-### Regression
-
-9. **All existing tests pass**: `make agent-test` green.
diff --git a/wip/archive/phase1-handoff.md b/wip/archive/phase1-handoff.md
deleted file mode 100644
index bc9099e42..000000000
--- a/wip/archive/phase1-handoff.md
+++ /dev/null
@@ -1,380 +0,0 @@
-# LibraryCrate: Direct Execution Mode
-
-> **Status**: Ready for implementation
-> **Branch from**: `dev` (at or after commit `628e414d` — pipe_ref namespace fix)
-> **Date**: 2026-03-24
-
----
-
-## 1. Motivation
-
-Library loading currently happens in a single monolithic step: `load_from_blueprints()` takes raw `PipelexBundleBlueprint` objects (the direct parse output of `.mthds` files) and produces a live `Library` with instantiated domains, concepts, and pipes. There is no stable intermediate representation between "files on disk" and "fully wired runtime objects."
-
-This creates three problems:
-
-1. **Tight coupling.** Parsing, merging, qualifying, and instantiating are interleaved. You cannot inspect the merged library content without instantiating every concept and pipe.
-2. **Testability.** Testing the merging/qualification logic requires running the full factory stack, including `KajsonManager`, forward-reference resolution, and class registry setup.
-3. **No caching boundary.** There is no fingerprint or content-addressable snapshot of what a library contains, so there is no way to detect "same content, already loaded" without re-running the full pipeline.
-
-The fix is a clean three-stage pipeline:
-
-```
-Bundles (files) → LibraryCrate (data) → Library (live)
-```
-
-The `LibraryCrate` is a pure-data Pydantic model holding the fully qualified, merged blueprints for all concepts and pipes. It is the single gateway between sourcing and instantiation.
-
----
-
-## 2. Prerequisite: Pipe Namespace Fix (Complete)
-
-PR #780 (`628e414d`) refactored the pipe namespace so that `PipeLibrary` is keyed by `pipe_ref` (`domain.pipe_code`), symmetric with how `ConceptLibrary` uses `concept_ref` (`domain.ConceptCode`). This is required because the LibraryCrate uses qualified refs as dictionary keys.
-
-Key changes already on `dev`:
-- `PipeAbstract.pipe_ref` property: `f"{self.domain_code}.{self.code}"`
-- `PipeLibrary.root` keyed by `pipe_ref`
-- `DomainLibrary.add_domain()` is idempotent for multi-bundle domain merging
-- Duplicate concept detection across bundles in `_load_concepts_from_blueprints()`
-- Duplicate pipe detection across bundles in `load_from_blueprints()`
-
----
-
-## 3. LibraryCrate Model
-
-### New file: `pipelex/libraries/library_crate.py`
-
-```python
-class LibraryCrate(BaseModel):
- """Complete library content as qualified blueprints, ready to load into a live Library.
-
- The crate is a flat, domain-agnostic snapshot of all concepts and pipes.
- Domain is encoded in the dictionary keys (e.g. 'scoring.WeightedScore',
- 'scoring.compute_score'), not in a structural container.
- """
-
- concepts: dict[str, ConceptBlueprint] = Field(default_factory=dict)
- """concept_ref (domain.ConceptCode) -> ConceptBlueprint"""
-
- pipes: dict[str, PipeBlueprintUnion] = Field(default_factory=dict)
- """pipe_ref (domain.pipe_code) -> PipeBlueprintUnion"""
-
- fingerprint: str = ""
- """SHA-256 hex digest of the serialized concepts + pipes content."""
-```
-
-### Design decisions
-
-- **Flat dicts, not nested by domain.** Domain is a namespace prefix in the key. No `DomainCrate` wrapper — merging is trivial.
-- **Blueprints, not instantiated objects.** The crate holds `ConceptBlueprint` and `PipeBlueprintUnion` — the same types that come out of `PipelexBundleBlueprint`. No factory logic, no class registry interaction, no forward-reference resolution.
-- **String-described concepts are normalized.** When a bundle declares `Concept1 = "Description"` (a `str` value in `PipelexBundleBlueprint.concept`), the factory converts it to `ConceptBlueprint(description="Description")` before inserting into the crate. The crate always holds `ConceptBlueprint`, never bare strings.
-- **Fingerprint** is computed over the deterministic JSON serialization of `concepts` and `pipes` (excluding the fingerprint field itself). Enables downstream caching by content identity.
-- **No source paths, no package provenance.** The crate is a pure content snapshot. Source tracking (`_pipe_source_map`, `loaded_mthds_paths`) remains in `LibraryManager`, outside the crate.
-- **No domain metadata.** Domain `description` and `system_prompt` are NOT stored in the crate. They are passed separately via `domain_metadata` parameter to `load_from_crate()`. See Section 7.
-
----
-
-## 4. LibraryCrateFactory
-
-### New file: `pipelex/libraries/library_crate_factory.py`
-
-```python
-class LibraryCrateFactory:
- @classmethod
- def make_from_blueprints(
- cls,
- blueprints: list[PipelexBundleBlueprint],
- ) -> LibraryCrate:
- """Build a LibraryCrate from parsed bundle blueprints.
-
- For each bundle:
- 1. Qualify concept codes with the bundle's domain → concept_ref keys
- 2. Qualify pipe codes with the bundle's domain → pipe_ref keys
- 3. Normalize string-described concepts to ConceptBlueprint
- 4. Merge into flat dicts (same ref twice = error)
- 5. Compute SHA-256 fingerprint
- """
-```
-
-### Algorithm
-
-```
-concepts: dict[str, ConceptBlueprint] = {}
-pipes: dict[str, PipeBlueprintUnion] = {}
-
-for each blueprint in blueprints:
- domain_code = blueprint.domain
-
- if blueprint.concept is not None:
- for concept_code, value in blueprint.concept.items():
- concept_ref = f"{domain_code}.{concept_code}"
- if concept_ref in concepts:
- raise LibraryCrateError(f"Concept '{concept_ref}' declared twice")
- if isinstance(value, str):
- concepts[concept_ref] = ConceptBlueprint(description=value)
- else:
- concepts[concept_ref] = value
-
- if blueprint.pipe is not None:
- for pipe_code, pipe_blueprint in blueprint.pipe.items():
- pipe_ref = f"{domain_code}.{pipe_code}"
- if pipe_ref in pipes:
- raise LibraryCrateError(f"Pipe '{pipe_ref}' declared twice")
- pipes[pipe_ref] = pipe_blueprint
-
-fingerprint = _compute_fingerprint(concepts, pipes)
-return LibraryCrate(concepts=concepts, pipes=pipes, fingerprint=fingerprint)
-```
-
-### Fingerprint computation
-
-Use `model_dump_json()` for deterministic serialization with `sort_keys` to ensure order-independence. SHA-256 hex digest.
-
-### New file: `pipelex/libraries/library_crate_exceptions.py`
-
-```python
-class LibraryCrateError(Exception):
- """Raised when building a LibraryCrate fails (e.g. ref collision)."""
-```
-
----
-
-## 5. LibraryManager.load_from_crate()
-
-### New method on `LibraryManager` (`pipelex/libraries/library_manager.py`)
-
-```python
-def load_from_crate(
- self,
- library_id: str,
- crate: LibraryCrate,
- domain_metadata: dict[str, DomainBlueprint] | None = None,
-) -> list[PipeAbstract]:
- """Load a LibraryCrate into a live Library.
-
- Args:
- library_id: The library to load into
- crate: The LibraryCrate containing qualified blueprints
- domain_metadata: Optional domain metadata (description, system_prompt)
- keyed by domain_code. When absent, domains get empty descriptions.
- """
-```
-
-### Algorithm
-
-```
-1. Extract unique domain codes from refs
- domain_codes = set()
- for ref in crate.concepts:
- parsed = QualifiedRef.parse_concept_ref(ref)
- domain_codes.add(parsed.domain_path)
- for ref in crate.pipes:
- parsed = QualifiedRef.parse_pipe_ref(ref)
- domain_codes.add(parsed.domain_path)
-
-2. Create Domain objects
- for domain_code in domain_codes:
- if domain_metadata and domain_code in domain_metadata:
- domain = DomainFactory.make_from_blueprint(domain_metadata[domain_code])
- else:
- domain = Domain(code=domain_code, description="")
- library.domain_library.add_domain(domain)
-
-3. Load concepts (topological ordering, forward refs, cycle detection)
- Build concept entries from crate.concepts (dict[concept_ref, ConceptBlueprint])
- instead of iterating over PipelexBundleBlueprint objects.
-
- For each concept_ref, concept_blueprint in crate.concepts.items():
- parsed = QualifiedRef.parse_concept_ref(concept_ref)
- domain_code = parsed.domain_path
- concept_code = parsed.local_code
- # Feed into topological sorter (same logic as _load_concepts_from_blueprints)
-
- Load in topological order via ConceptFactory.make_from_blueprint()
- library.concept_library.add_concepts(all_concepts)
-
-4. Resolve forward references
- self._rebuild_models_with_forward_refs(all_concepts)
-
-5. Detect concept cycles
- self._detect_concept_cycles(all_concepts)
-
-6. Load pipes
- For each pipe_ref, pipe_blueprint in crate.pipes.items():
- parsed = QualifiedRef.parse_pipe_ref(pipe_ref)
- domain_code = parsed.domain_path
- pipe_code = parsed.local_code
-
- # Collect concept codes from same domain for validation
- concept_codes_for_domain = [
- QualifiedRef.parse_concept_ref(ref).local_code
- for ref in crate.concepts
- if ref.startswith(f"{domain_code}.")
- ]
-
- pipe = PipeFactory[PipeAbstract].make_from_blueprint(
- domain_code=domain_code,
- pipe_code=pipe_code,
- blueprint=pipe_blueprint,
- concept_codes_from_the_same_domain=concept_codes_for_domain,
- )
- library.pipe_library.add_pipes(all_pipes)
-
-7. Validate
- library.validate_library()
-
-8. Return all_pipes
-```
-
-### Also add abstract method
-
-In `pipelex/libraries/library_manager_abstract.py`, add the `load_from_crate()` abstract method.
-
----
-
-## 6. Refactor load_from_blueprints()
-
-The existing `load_from_blueprints()` becomes a two-step delegation:
-
-```python
-def load_from_blueprints(
- self,
- library_id: str,
- blueprints: list[PipelexBundleBlueprint],
-) -> list[PipeAbstract]:
- # Step 0: Load address-based dependencies (unchanged)
- self._load_address_based_dependencies(library_id=library_id, blueprints=blueprints)
-
- # Step 1: Build domain metadata from blueprints (first-write-wins per domain)
- domain_metadata: dict[str, DomainBlueprint] = {}
- for blueprint in blueprints:
- if blueprint.domain not in domain_metadata:
- domain_metadata[blueprint.domain] = DomainBlueprint(
- source=blueprint.source,
- code=blueprint.domain,
- description=blueprint.description or "",
- system_prompt=blueprint.system_prompt,
- )
-
- # Step 2: Build the crate
- crate = LibraryCrateFactory.make_from_blueprints(blueprints=blueprints)
-
- # Step 3: Load from crate
- return self.load_from_crate(
- library_id=library_id,
- crate=crate,
- domain_metadata=domain_metadata,
- )
-```
-
-**Callers do not change.** `pipeline_run_setup()`, `_load_mthds_files_into_library()`, and the dependency loading code all call `load_from_blueprints()` and continue to work as before.
-
-**Note on `_pipe_source_map`**: The current `load_from_blueprints()` tracks which `.mthds` file each pipe came from. After refactoring, source tracking must be preserved. Two options:
-- (a) Build the source map in the refactored `load_from_blueprints()` after `load_from_crate()` returns, by iterating blueprints and matching pipe_refs.
-- (b) Pass source info as an additional parameter to `load_from_crate()`.
-
-Option (a) is simpler and keeps the crate source-agnostic.
-
-**`load_concepts_only_from_blueprints()`** can remain as-is for Phase 1 — it's used by LSP/validation tooling and doesn't need the crate abstraction yet.
-
----
-
-## 7. system_prompt and Domain Metadata
-
-The `PipelexBundleBlueprint.system_prompt` field flows into `Domain.system_prompt` and is used as a fallback system prompt for PipeLLM pipes. There's already a TODO comment in `domain_library.py` (line 35-36) about inlining this at pipe factory time.
-
-**For this phase:**
-- Domain metadata (`description`, `system_prompt`) is NOT stored in the crate.
-- Domain metadata is passed as a separate `domain_metadata` parameter to `load_from_crate()`.
-- When `load_from_blueprints()` calls `load_from_crate()`, it extracts domain metadata from the blueprints and passes it along.
-- The existing `DomainLibrary.add_domain()` first-write-wins behavior is preserved.
-
-This keeps the crate focused on content. Inlining `system_prompt` into pipe blueprints is a separate optimization.
-
----
-
-## 8. File Summary
-
-| File | Action | Description |
-|------|--------|-------------|
-| `pipelex/libraries/library_crate.py` | **New** | `LibraryCrate` model |
-| `pipelex/libraries/library_crate_factory.py` | **New** | `LibraryCrateFactory.make_from_blueprints()`, fingerprint |
-| `pipelex/libraries/library_crate_exceptions.py` | **New** | `LibraryCrateError` exception |
-| `pipelex/libraries/library_manager.py` | **Modify** | Add `load_from_crate()`, refactor `load_from_blueprints()` |
-| `pipelex/libraries/library_manager_abstract.py` | **Modify** | Add `load_from_crate()` abstract method |
-| `tests/unit/pipelex/libraries/test_library_crate.py` | **New** | Unit tests for model and factory |
-| `tests/unit/pipelex/libraries/test_library_crate_data.py` | **New** | Test data |
-| `tests/integration/pipelex/libraries/test_load_from_crate.py` | **New** | Integration: crate ↔ blueprints equivalence |
-
----
-
-## 9. Test Plan
-
-### Unit tests: `tests/unit/pipelex/libraries/test_library_crate.py`
-
-One `TestLibraryCrate` class:
-
-1. **JSON round-trip** — Create `LibraryCrate` with sample data, serialize to JSON, deserialize, assert equality.
-2. **make_from_blueprints merges correctly** — Two blueprints for the same domain with different concepts and pipes. Assert all entries present with qualified refs.
-3. **make_from_blueprints merges across domains** — Two blueprints with different domains. Assert refs qualified with respective domains.
-4. **String concept normalization** — Blueprint with `concept = {"MyConcept": "A description"}`. Assert crate contains `ConceptBlueprint(description="A description")`.
-5. **Concept collision raises** — Two blueprints declaring same `domain.ConceptCode`. Assert `LibraryCrateError`.
-6. **Pipe collision raises** — Two blueprints declaring same `domain.pipe_code`. Assert `LibraryCrateError`.
-7. **Fingerprint determinism** — Same blueprints → same fingerprint. Different blueprints → different fingerprint.
-8. **Empty blueprints** — Blueprint with no concepts and no pipes. Assert empty dicts and valid fingerprint.
-
-### Integration test: `tests/integration/pipelex/libraries/test_load_from_crate.py`
-
-One `TestLoadFromCrate` class:
-
-1. **Equivalence test** — Load `.mthds` files via `load_from_blueprints()`. Separately build a crate from the same blueprints, call `load_from_crate()`. Assert both libraries contain the same concept_refs, pipe_refs, and domain codes.
-
-### Regression
-
-- All existing tests pass: `make agent-test`
-- All linting passes: `make agent-check`
-
----
-
-## 10. Implementation Sequence
-
-1. **Create `LibraryCrate` model** (`library_crate.py`). Pure data model. Write JSON round-trip test first (TDD).
-2. **Create `LibraryCrateFactory`** (`library_crate_factory.py`). Implement `make_from_blueprints()` with string normalization, collision detection, fingerprint. Write unit tests.
-3. **Add `load_from_crate()`** to `LibraryManager`. Port concept-loading logic (topological sort, forward refs, cycle detection) and pipe-loading logic to work with flat crate dicts.
-4. **Refactor `load_from_blueprints()`** to delegate through the crate. Extract domain metadata, build crate, call `load_from_crate()`.
-5. **Run `make agent-check` and `make agent-test`**. Fix regressions.
-6. **Write integration equivalence test**.
-
----
-
-## 11. Risks and Edge Cases
-
-### String-described concepts
-`PipelexBundleBlueprint.concept` values can be `ConceptBlueprint | str`. The factory normalizes `str` to `ConceptBlueprint(description=value)`. This must match what `ConceptFactory.make_from_blueprint()` expects.
-
-### Cross-package dependencies
-`load_from_blueprints()` calls `_load_address_based_dependencies()` before building the crate. These dependencies load into child libraries via separate code paths. This phase does NOT route dependency loading through a crate. The crate only covers the "main" blueprints.
-
-### load_concepts_only_from_blueprints()
-This lightweight variant (LSP/validation) loads only domains and concepts. It can remain as-is for this phase.
-
-### Ref parsing for multi-segment domains
-Use `QualifiedRef.parse_concept_ref()` and `QualifiedRef.parse_pipe_ref()` (`pipelex/core/qualified_ref.py`) for correct splitting. These use `rsplit(".", 1)` which handles multi-segment domains like `legal.contracts.NonCompeteClause` correctly.
-
-### None concept/pipe dicts
-`PipelexBundleBlueprint.concept` and `.pipe` can be `None`. The factory must guard with `if blueprint.concept is not None:`.
-
----
-
-## 12. Key Existing Code to Reuse
-
-| What | Where |
-|------|-------|
-| `PipeFactory[PipeAbstract].make_from_blueprint()` | `pipelex/core/pipes/pipe_factory.py` |
-| `ConceptFactory.make_from_blueprint()` | `pipelex/core/concepts/concept_factory.py` |
-| `DomainFactory.make_from_blueprint()` | `pipelex/core/domains/domain_factory.py` |
-| `QualifiedRef.parse_concept_ref()` / `parse_pipe_ref()` | `pipelex/core/qualified_ref.py` |
-| `_load_concepts_from_blueprints()` (topological sort logic) | `pipelex/libraries/library_manager.py:472` |
-| `_rebuild_models_with_forward_refs()` | `pipelex/libraries/library_manager.py` |
-| `_detect_concept_cycles()` | `pipelex/libraries/library_manager.py` |
-| `library.validate_library()` | `pipelex/libraries/library.py` |
-| `DomainLibrary.add_domain()` (idempotent) | `pipelex/libraries/domain/domain_library.py` |
diff --git a/wip/archive/phase2-crate-propagation-rationale.md b/wip/archive/phase2-crate-propagation-rationale.md
deleted file mode 100644
index e9ffc6efc..000000000
--- a/wip/archive/phase2-crate-propagation-rationale.md
+++ /dev/null
@@ -1,112 +0,0 @@
-# Design Rationale: LibraryCrate Propagation in Distributed Execution
-
-> **Status**: Decided
-> **Date**: 2026-03-25
-> **Related**: [00-master-plan.md](00-master-plan.md)
-
----
-
-## Problem
-
-Phase 2 ships a `LibraryCrate` to Temporal workers so they can load the library and resolve child pipes via `get_required_pipe()`. The master plan v2 proposed adding `library_crate` to `PipeJob` and using an `act_library_setup` activity to load it.
-
-Two gaps in that design:
-
-1. **Child workflow propagation**: Pipe controllers (PipeSequence, PipeParallel, etc.) dispatch child pipes through `SubPipe.run_pipe()` → `PipeRouterChild` → new `WfPipeRouter` child workflow. Each child workflow is a separate Temporal workflow that **can land on a different worker**. The crate must be on each child `PipeJob`, or the child worker won't have the library.
-
-2. **Activity necessity**: The plan called for an `act_library_setup` activity. But loading a crate is pure in-memory work — deserializing Pydantic models into dicts. Activities are for I/O-bound or side-effectful operations that need retry semantics. An activity adds latency and complexity for no benefit here.
-
----
-
-## The Fundamental Constraint
-
-In Temporal distributed execution, **the only data channel between parent and child workflow is the serialized workflow argument**. There is no shared memory, no shared process, no ContextVar, no singleton that crosses the workflow boundary. Child workflows can run on any available worker in the task queue.
-
-This means the crate cannot be stashed in a ContextVar, a library manager singleton, or any other in-process state and expected to be available in child workflows. It must travel in the `PipeJob`.
-
----
-
-## Decision: `library_crate` on `PipeJob`, threaded through the signature chain
-
-### Where the crate lives
-
-`library_crate: LibraryCrate | None = None` is added to `PipeJob`.
-
-### How it propagates
-
-The crate must flow from `WfPipeRouter` (which has the `PipeJob`) down to `SubPipe` (which builds child `PipeJob`s). The call chain is:
-
-```
-WfPipeRouter.run(pipe_job: PipeJob)
- → pipe.run_pipe(job_metadata, working_memory, pipe_run_params, output_name, library_crate)
- → _live_run_pipe(job_metadata, working_memory, pipe_run_params, output_name, library_crate)
- → [PipeController] _live_run_controller_pipe(..., library_crate)
- → SubPipe.run_pipe(..., library_crate)
- → PipeJobFactory.make_pipe_job(..., library_crate) # child PipeJob carries the crate
- → PipeRouterChild → new WfPipeRouter(child_pipe_job)
-```
-
-`library_crate` is added as an optional parameter (default `None`) at each level. Pipe operators (PipeLLM, PipeExtract, etc.) receive it but ignore it — they have no child pipes.
-
-### How loading works
-
-At the top of `WfPipeRouter.run()`, if `pipe_job.library_crate` is present, call `library_manager.load_from_crate()` inline (no activity). The load is idempotent via fingerprint — if the crate was already loaded on this worker, it's a no-op.
-
----
-
-## Alternatives Considered and Rejected
-
-### Put the crate on `PipeRunParams`
-
-`PipeRunParams` already threads through the entire execution tree — `SubPipe` receives it and passes it to `PipeJobFactory`. No signature changes needed.
-
-**Rejected because**: `PipeRunParams` is about *how to run* a pipe (run mode, stack limit, multiplicity, batch params). It gets copied and mutated at every nesting level. The crate is immutable static context. Mixing execution parameters with library content is semantically wrong and makes `PipeRunParams` a grab-bag.
-
-### Put the crate on `JobMetadata`
-
-`JobMetadata` also threads through the entire tree. Since it's inside `PipeJob`, we could avoid the `PipeJob`-level field entirely.
-
-**Rejected because**: `JobMetadata` carries observability and identity data (user_id, pipeline_run_id, OTel context, graph context). Adding library content to it is semantically wrong — metadata is about *who* and *when*, not *what to load*.
-
-### ContextVar / library manager stash
-
-Store the crate in a `ContextVar` or on the library manager after loading. `SubPipe` reads it when building child `PipeJob`s. Zero signature changes.
-
-**Rejected because**: This is fundamentally broken in distributed execution. ContextVars and singletons are per-process state. Temporal child workflows can land on different workers — different processes, different servers. The only data channel is the serialized `PipeJob`. This was the key insight that ruled out all in-process state approaches.
-
-### `act_library_setup` activity
-
-Use a Temporal activity to load the crate before pipe execution.
-
-**Rejected because**: Loading a crate is pure in-memory work — iterating over Pydantic model dicts and populating the library manager. It involves no I/O, no network calls, no file reads. Activities exist for operations that need Temporal's retry/timeout/heartbeat semantics. Using an activity here adds unnecessary latency (activity scheduling overhead) and complexity for zero benefit.
-
-### Put the crate only on `PipeController` (not `PipeAbstract`)
-
-Since only controllers have child pipes, add the parameter only at the `PipeController` level.
-
-**Rejected because**: `PipeAbstract.run_pipe()` is the entry point called by `WfPipeRouter`. It calls `_live_run_pipe()` internally. If `_live_run_pipe` has a different signature on `PipeController` than on `PipeAbstract`, the override breaks. The crate must cross the `run_pipe()` boundary, which means `PipeAbstract` must accept it.
-
----
-
-## Blast Radius
-
-The signature change touches the following layers:
-
-| Layer | File | Change |
-|-------|------|--------|
-| `PipeAbstract.run_pipe()` | `pipelex/core/pipes/pipe_abstract.py` | Add optional `library_crate` param |
-| `PipeAbstract._live_run_pipe()` | `pipelex/core/pipes/pipe_abstract.py` | Add optional `library_crate` param |
-| `PipeOperator._live_run_pipe()` | `pipelex/pipe_operators/pipe_operator.py` | Add param, ignore it |
-| `PipeController._live_run_pipe()` | `pipelex/pipe_controllers/pipe_controller.py` | Add param, forward to `_live_run_controller_pipe()` |
-| `PipeController._live_run_controller_pipe()` | `pipelex/pipe_controllers/pipe_controller.py` | Add param (abstract) |
-| PipeSequence | `pipelex/pipe_controllers/sequence/pipe_sequence.py` | Forward to `SubPipe.run_pipe()` |
-| PipeBatch | `pipelex/pipe_controllers/batch/pipe_batch.py` | Forward to child pipe execution |
-| PipeCondition | `pipelex/pipe_controllers/condition/pipe_condition.py` | Forward to child pipe execution |
-| PipeParallel | `pipelex/pipe_controllers/parallel/pipe_parallel.py` | Forward to `SubPipe.run_pipe()` |
-| `SubPipe.run_pipe()` | `pipelex/pipe_controllers/sub_pipe.py` | Add param, set on child `PipeJob` |
-| `PipeJob` | `pipelex/pipe_run/pipe_job.py` | Add `library_crate` field |
-| `PipeJobFactory` | `pipelex/pipe_run/pipe_job_factory.py` | Accept and forward `library_crate` |
-| `WfPipeRouter` | `pipelex/temporal/tprl_pipe/wf_pipe_router.py` | Load crate, pass to `run_pipe()` |
-| `PipeRouter` (direct) | `pipelex/pipe_run/pipe_router.py` | Pass `library_crate` from `PipeJob` to `run_pipe()` |
-
-Every change is mechanical: add one optional parameter, forward it. The crate is never modified, only carried.
diff --git a/wip/archive/phase2-implementation-plan.md b/wip/archive/phase2-implementation-plan.md
deleted file mode 100644
index 190fd4d9c..000000000
--- a/wip/archive/phase2-implementation-plan.md
+++ /dev/null
@@ -1,311 +0,0 @@
-# Phase 2 Implementation Plan: LibraryCrate on Temporal
-
-> **Status**: Reviewed, ready to implement (updated after feature/LibraryCrate merge — 5477e16a, then crate design review — Option A chosen)
-> **Date**: 2026-03-25
-> **Related**: [00-master-plan.md](00-master-plan.md), [phase2-crate-propagation-rationale.md](phase2-crate-propagation-rationale.md), [future-crate-first-architecture.md](future-crate-first-architecture.md)
-> **Review**: Eng review passed (0 critical gaps). Codex outside voice: 7 findings, all addressed. Crate design review: Option A (blueprint accumulation) chosen over Option B (crate merge).
-
----
-
-## Context
-
-Phase 0 (pipe_ref fix) and Phase 1 (LibraryCrate in direct mode) are complete. Temporal workers currently cannot resolve child pipes from `mthds_content` or extra `library_dirs` because those definitions only exist on the API/submitter side. Phase 2 ships the `LibraryCrate` inside `PipeJob` so every worker — including child workflows on different machines — receives the full library context.
-
-**What this solves**: Pipe controllers (PipeSequence, PipeCondition, PipeBatch, PipeParallel) work on Temporal workers. `get_required_pipe()` succeeds for all pipes in the library.
-
-**What this does NOT solve**: Layer 1 (dynamic class deserialization for custom concepts). That's Phase 3.
-
----
-
-## Key Architecture Decisions
-
-1. **Crate on PipeJob** — `library_crate: LibraryCrate | None = None` field on `PipeJob`. Threaded through the signature chain as an optional parameter. (Rationale: [phase2-crate-propagation-rationale.md](phase2-crate-propagation-rationale.md))
-
-2. **Self-contained crate** — The crate carries ALL blueprints (PIPELEXPATH + mthds_content + extra library_dirs). Workers don't assume anything is pre-loaded.
-
-3. **Blueprint accumulation on LibraryManager** — `_blueprints: dict[str, list[PipelexBundleBlueprint]]` tracks all blueprints loaded per `library_id`. Each `load_from_blueprints()` call appends to the list. `get_crate(library_id)` builds one crate from all accumulated blueprints via `LibraryCrateFactory.make_from_blueprints()`. No merge logic, no crate accumulation — blueprints are the unit of accumulation. See [future-crate-first-architecture.md](future-crate-first-architecture.md) for the rationale.
-
-4. **Per-workflow library on workers** — Each `WfPipeRouter` opens its own library using a unique ID derived from `workflow.info().workflow_id` (e.g., `f"wf_{workflow_id}"`). Full isolation — parent and child workflows from PipeParallel/PipeBatch get different IDs. Teardown after execution.
-
-5. **Inline loading (no activity)** — Crate loading is pure in-memory work. No Temporal activity needed.
-
-6. **Fingerprint idempotency** — `load_from_crate()` skips if a crate with the same fingerprint was already loaded into the same `library_id`.
-
----
-
-## Data Flow
-
-```
-SUBMITTER (pipeline_run_setup)
-════════════════════════════════════════════════════════
- load_libraries(library_id, dirs) ─┐
- → load_from_blueprints(blueprints) │ Each call appends blueprints
- → _blueprints[library_id] += blueprints│ to the accumulation list,
- → LibraryCrateFactory → crate │ then loads from crate
- → load_from_crate(library_id, crate) ─┘ as today
-
- [if mthds_content]
- load_from_blueprints(library_id, mthds_blueprints)
- → same path → blueprints appended to _blueprints[library_id]
-
- library_crate = library_manager.get_crate(library_id)
- → LibraryCrateFactory.make_from_blueprints(_blueprints[library_id])
- → one crate from ALL accumulated blueprints
- pipe_job = PipeJobFactory.make_pipe_job(..., library_crate=library_crate)
-
-
-TEMPORAL DISPATCH
-════════════════════════════════════════════════════════
- PipeRouterTop._run_pipe_job(pipe_job)
- → WfPipeRouter workflow(pipe_job) [can land on ANY worker]
-
-
-WORKER (WfPipeRouter.run)
-════════════════════════════════════════════════════════
- wf_library_id = f"wf_{workflow.info().workflow_id}"
- library_manager.open_library(library_id=wf_library_id)
- set_current_library(library_id=wf_library_id)
- library_manager.load_from_crate(wf_library_id, pipe_job.library_crate)
-
- pipe.run_pipe(..., library_crate=pipe_job.library_crate)
- → [controller] _live_run_controller_pipe(..., library_crate)
- → SubPipe.run_pipe(..., library_crate)
- → PipeJobFactory.make_pipe_job(..., library_crate) # child carries crate
- → PipeRouterChild → new WfPipeRouter(child_pipe_job)
- [cycle repeats on potentially different worker]
-
- library_manager.teardown(library_id=wf_library_id)
- teardown_current_library()
-```
-
----
-
-## Implementation Steps
-
-### Step 1: Blueprint accumulation + get_crate + fingerprint idempotency
-
-**Tests first** (`tests/unit/pipelex/libraries/test_library_crate_accumulation.py`):
-- `get_crate(library_id)` builds crate from all accumulated blueprints
-- `get_crate(library_id)` returns `None` for unknown library_id
-- `get_crate(library_id)` returns `None` when no blueprints were loaded
-- Blueprints from multiple `load_from_blueprints()` calls are all included in the crate
-- `load_from_crate()` returns `[]` on second call with same fingerprint (idempotency)
-- `teardown()` clears blueprints for that library_id
-
-**Then implement:**
-
-**File**: `pipelex/libraries/library_manager.py`
-- Add `_blueprints: dict[str, list[PipelexBundleBlueprint]]` field alongside `_libraries`
-- In `load_from_blueprints()`:
- - Append `blueprints` to `_blueprints[library_id]` (before or after the existing crate build + load)
-- In `load_from_crate()`:
- - Check fingerprint idempotency (skip if already seen for this library_id)
-- Add `get_crate(library_id) -> LibraryCrate | None`: if `_blueprints[library_id]` exists and is non-empty, call `LibraryCrateFactory.make_from_blueprints()` with the full accumulated list; otherwise return `None`
-- Clear `_blueprints[library_id]` in `teardown(library_id)` and `reset()`
-
-**File**: `pipelex/libraries/library_manager_abstract.py`
-- Add abstract `get_crate(library_id) -> LibraryCrate | None`
-
-**No changes to `pipelex/libraries/library_crate.py`** — no `merge()` method needed.
-
----
-
-### Step 2: Add `library_crate` field to PipeJob and PipeJobFactory
-
-**File**: `pipelex/pipe_run/pipe_job.py`
-- Add `library_crate: LibraryCrate | None = None` field
-
-**File**: `pipelex/pipe_run/pipe_job_factory.py`
-- Add `library_crate: LibraryCrate | None = None` param to `make_pipe_job()`, forward to PipeJob constructor
-
----
-
-### Step 3: Thread `library_crate` through the signature chain
-
-Add `library_crate: LibraryCrate | None = None` as the last parameter. Use `TYPE_CHECKING` import.
-
-#### 3a. PipeAbstract (`pipelex/core/pipes/pipe_abstract.py`)
-
-`@final` methods — add param and forward:
-- `run_pipe()` → `live_run_pipe()` / `dry_run_pipe()`
-- `live_run_pipe()` → `_live_run_pipe()`
-- `dry_run_pipe()` → `_dry_run_pipe()`
-
-Abstract methods — signature only:
-- `_live_run_pipe()`
-- `_dry_run_pipe()`
-
-#### 3b. PipeOperator (`pipelex/pipe_operators/pipe_operator.py`)
-
-Accept but do NOT forward deeper:
-- `_live_run_pipe()` — receives `library_crate`, does NOT pass to `_live_run_operator_pipe()`
-- `_dry_run_pipe()` — same
-
-The 6 concrete operators (PipeLLM, PipeExtract, PipeSearch, PipeImgGen, PipeFunc, PipeCompose) need NO changes.
-
-#### 3c. PipeController (`pipelex/pipe_controllers/pipe_controller.py`)
-
-Add param and forward:
-- `_live_run_pipe()` → `_live_run_controller_pipe()`
-- `_dry_run_pipe()` → `_dry_run_controller_pipe()`
-- `_live_run_controller_pipe()` (abstract) — signature only
-- `_dry_run_controller_pipe()` (abstract) — signature only
-
-#### 3d. Controller implementations
-
-**PipeSequence** (`pipe_controllers/sequence/pipe_sequence.py`):
-- `_live_run_controller_pipe()`: pass to `sub_pipe.run_pipe()` calls
-- `_dry_run_controller_pipe()`: forward to `_live_run_controller_pipe()`
-
-**PipeParallel** (`pipe_controllers/parallel/pipe_parallel.py`):
-- `_live_run_controller_pipe()`: pass to `sub_pipe.run_pipe()` calls
-- `_dry_run_controller_pipe()`: pass to `sub_pipe.run_pipe()` calls
-
-**PipeBatch** (`pipe_controllers/batch/pipe_batch.py`):
-- `_live_run_controller_pipe()`: pass to `PipeJobFactory.make_pipe_job()` calls
-- `_dry_run_controller_pipe()`: forward to `_live_run_controller_pipe()`
-
-**PipeCondition** (`pipe_controllers/condition/pipe_condition.py`):
-- `_live_run_controller_pipe()`: pass to `PipeJobFactory.make_pipe_job()`
-- `_dry_run_controller_pipe()`: pass to `pipe.run_pipe()` calls
-
-#### 3e. SubPipe (`pipelex/pipe_controllers/sub_pipe.py`)
-
-Add `library_crate` to `run_pipe()`. Forward to all 3 `PipeJobFactory.make_pipe_job()` calls (batch, condition, normal).
-
----
-
-### Step 4: Update PipeRouter (direct) and WfPipeRouter (Temporal)
-
-#### 4a. PipeRouter (`pipelex/pipe_run/pipe_router.py`)
-
-In `_run_pipe_job()`: pass `library_crate=pipe_job.library_crate` to `pipe.run_pipe()`.
-
-#### 4b. WfPipeRouter (`pipelex/temporal/tprl_pipe/wf_pipe_router.py`)
-
-In `run()`:
-1. Derive unique library ID: `wf_library_id = f"wf_{workflow.info().workflow_id}"`
-2. Open per-workflow library: `library_manager.open_library(library_id=wf_library_id)`
-3. Set as current: `set_current_library(library_id=wf_library_id)`
-4. If `library_crate` present: `library_manager.load_from_crate(wf_library_id, crate)`
-5. Run pipe with `library_crate=workflow_arg.library_crate`
-6. In finally block: `library_manager.teardown(library_id=wf_library_id)` + `teardown_current_library()`
-
----
-
-### Step 5: Build and attach crate in `pipeline_run_setup()`
-
-**File**: `pipelex/pipeline/pipeline_run_setup.py`
-
-**Note**: After the feature/LibraryCrate merge, `mthds_content` is now `mthds_contents: list[str] | None` and `bundle_uri` is now `bundle_uris: list[str] | None`. The crate accumulation approach is unaffected — both `load_libraries()` and `load_from_blueprints()` go through `load_from_crate()` which accumulates into `_crates[library_id]`.
-
-After all library loading (load_libraries + load_from_blueprints), before creating PipeJob:
-
-```python
-library_crate = library_manager.get_crate(library_id)
-
-pipe_job = PipeJobFactory.make_pipe_job(
- ...,
- library_crate=library_crate,
-)
-```
-
-No manual crate building or merging needed — `get_crate()` returns the accumulated result.
-
----
-
-### Step 6: Run checks and tests
-
-1. `make agent-check` — lint + type check
-2. `make agent-test` — full test suite
-
----
-
-## NOT in scope
-
-- **Layer 1 (dynamic class deserialization)** — Phase 3. When `mthds_content` introduces custom concepts with dynamic classes, Kajson can't deserialize WorkingMemory on the worker. Deferred.
-- **StoragePayloadCodec** — Phase 4. For payloads exceeding 2MB. Not needed for typical libraries.
-- **Crate stripping** — Future. Only shipping the transitive closure of pipe dependencies. Optimization.
-- **Library fingerprint validation** — Future. Verifying worker's base library matches API's expectation.
-
-### Phase 2 Known Limitations (from Codex review)
-
-- **Cross-package address-based dependencies** — `load_from_crate()` does not resolve `alias->domain.pipe` refs. Pipes with cross-package deps won't resolve on workers. Scoped to packages using METHODS.toml dependency declarations.
-- **Python-backed libraries** — `PipeFunc` (requires function registry) and `structure = "ExistingClass"` concepts (requires class registry) won't work on workers. `load_from_crate()` doesn't import Python modules. Standard pipe types (LLM, extract, search, compose) work fine.
-- **Payload duplication in fanout** — PipeBatch/PipeParallel create N child PipeJobs, each carrying the full crate. Redundant for siblings on the same worker. Optimization via StoragePayloadCodec (Phase 4) or crate stripping (future).
-
----
-
-## What already exists
-
-| What | Where | Reuse |
-|------|-------|-------|
-| `LibraryCrate` model | `pipelex/libraries/library_crate.py` | Reuse as-is (no merge needed) |
-| `LibraryCrateFactory.make_from_blueprints()` | `pipelex/libraries/library_crate_factory.py` | Reuse as-is |
-| `LibraryManager.load_from_crate()` | `pipelex/libraries/library_manager.py` | Phase 1 — add fingerprint check |
-| `load_from_blueprints()` → crate path | `library_manager.py:432` | Already builds crate internally, calls `load_from_crate` |
-| `PipeFactory.make_pipe_ref_with_domain()` | `core/pipes/pipe_factory.py:41` | New helper — not needed in `merge()` (keys already qualified) |
-| `ConceptFactory.make_concept_ref_with_domain()` | `core/concepts/concept_factory.py:213` | New helper — not needed in `merge()` (keys already qualified) |
-| `LibraryCrate.compute_fingerprint_from_content()` | `libraries/library_crate.py` | Static method — used by `LibraryCrateFactory` |
-| Worker base library loading | `temporal/worker_cli.py:65` | Exists — worker_base library |
-| Kajson data converter | `temporal/temporal_data_converter.py` | Handles PipeJob serialization |
-| `PipeRouterProtocol.run()` | `pipe_run/pipe_router_protocol.py` | Unchanged — PipeJob carries crate |
-
----
-
-## Failure modes
-
-| Codepath | Failure scenario | Test coverage | Error handling | User impact |
-|----------|-----------------|---------------|----------------|-------------|
-| Crate serialization | LibraryCrate too large for Temporal 2MB limit | Phase 4 test | Temporal raises PayloadTooLarge | Error visible in dashboard |
-| Fingerprint collision | Two different crates with same SHA256 | Astronomically unlikely | Second load skipped silently | Wrong pipes loaded — very unlikely |
-| Worker library teardown | Exception during pipe execution skips teardown | Needs try/finally | Add finally block in WfPipeRouter | Memory leak on worker |
-| Concurrent crate loading | Two workflows load same crate simultaneously | Thread-safe via GIL | No issue in Python | None |
-| Direct mode crate cleanup | `runner.py:199` calls `library.teardown()` directly, not `library_manager.teardown()` | Fix in Step 1 | Change `runner.py` to call `library_manager.teardown(library_id)` instead | Stale `_crates` state in direct mode if not fixed |
-
-No critical gaps — all failure modes have either test coverage, error handling, or are handled by existing infrastructure.
-
-**Note on fingerprint scope**: `compute_fingerprint()` hashes concepts + pipes only (not domains/source_map). This is intentional — domains carry metadata (description, system_prompt) that doesn't affect pipe resolution. If domain metadata changes become significant, fingerprint scope can be expanded later.
-
-**Note on crate design**: Option A (blueprint accumulation) was chosen over Option B (crate merge). See [future-crate-first-architecture.md](future-crate-first-architecture.md) for the full rationale. In short: accumulating blueprints is simpler (no merge logic, no crate accumulation dict, no fingerprint recomputation) and directionally correct toward the future crate-first architecture.
-
----
-
-## Verification
-
-### Automated
-- All existing tests pass (library_crate=None flows through silently in direct mode)
-- New unit tests for merge, fingerprint idempotency, get_crate
-- `make agent-check` passes
-- `make agent-test` passes
-
-### Manual (Temporal dev setup)
-- 3-terminal Temporal dev setup (server + worker + job submitter)
-- Submit a PipeSequence job with `mthds_content` containing additional pipes
-- Verify child pipes resolve on the worker
-- Check Temporal dashboard: crate visible as structured JSON in PipeJob workflow input
-
----
-
-## File Summary
-
-| File | Change |
-|------|--------|
-| `pipelex/libraries/library_crate.py` | No changes needed |
-| `pipelex/libraries/library_manager.py` | Add `_blueprints` dict, accumulate in `load_from_blueprints()`, fingerprint idempotency in `load_from_crate()`, `get_crate()` builds crate from accumulated blueprints |
-| `pipelex/libraries/library_manager_abstract.py` | Add abstract `get_crate()` |
-| `pipelex/pipe_run/pipe_job.py` | Add `library_crate` field |
-| `pipelex/pipe_run/pipe_job_factory.py` | Add `library_crate` param |
-| `pipelex/core/pipes/pipe_abstract.py` | Add `library_crate` param to `run_pipe`, `live_run_pipe`, `dry_run_pipe`, `_live_run_pipe`, `_dry_run_pipe` |
-| `pipelex/pipe_operators/pipe_operator.py` | Add `library_crate` param to `_live_run_pipe`, `_dry_run_pipe` (accept, ignore) |
-| `pipelex/pipe_controllers/pipe_controller.py` | Add `library_crate` param to 4 methods |
-| `pipelex/pipe_controllers/sequence/pipe_sequence.py` | Forward `library_crate` to `sub_pipe.run_pipe()` |
-| `pipelex/pipe_controllers/parallel/pipe_parallel.py` | Forward `library_crate` to `sub_pipe.run_pipe()` |
-| `pipelex/pipe_controllers/batch/pipe_batch.py` | Forward `library_crate` to `PipeJobFactory.make_pipe_job()` |
-| `pipelex/pipe_controllers/condition/pipe_condition.py` | Forward `library_crate` to `PipeJobFactory.make_pipe_job()` / `pipe.run_pipe()` |
-| `pipelex/pipe_controllers/sub_pipe.py` | Add `library_crate` param, forward to `PipeJobFactory.make_pipe_job()` |
-| `pipelex/pipe_run/pipe_router.py` | Pass `library_crate` from PipeJob to `run_pipe()` |
-| `pipelex/temporal/tprl_pipe/wf_pipe_router.py` | Per-workflow library lifecycle + load crate + pass to `run_pipe()` |
-| `pipelex/pipeline/pipeline_run_setup.py` | Read crate via `get_crate()`, attach to PipeJob |
-| `pipelex/pipeline/runner.py` | Fix teardown: call `library_manager.teardown(library_id)` instead of `library.teardown()` |
-| `tests/unit/pipelex/libraries/test_library_crate_accumulation.py` | New: blueprint accumulation, idempotency, get_crate tests |
diff --git a/wip/archive/phase3-eng-review.md b/wip/archive/phase3-eng-review.md
deleted file mode 100644
index 467c99bc8..000000000
--- a/wip/archive/phase3-eng-review.md
+++ /dev/null
@@ -1,301 +0,0 @@
-# Engineering Review: Phase 3 — Deferred WorkingMemory Hydration + Scoped ClassRegistry
-
-**Branch**: `feature/Temporal-3`
-**Plan file**: `TODOS.md`
-**Repo mode**: solo
-
----
-
-## Step 0: Scope Challenge
-
-### What existing code already partially solves sub-problems?
-
-| Sub-problem | Existing code | Reuse? |
-|---|---|---|
-| Context-scoped state | `_library_id: ContextVar` in `hub.py:454` | YES — same pattern for scoped registry |
-| Library lifecycle | `open_library() / teardown() / set_current_library()` in `hub.py` | YES — already used in WfPipeRouter |
-| Class registration | `KajsonManager.get_class_registry().register_class()` in ConceptFactory | YES — auto-uses scoped registry via ContextVar |
-| Temporal data conversion | `BaseModelPayloadConverter` uses `kajson.dumps/loads` | YES — drives the serialization constraints |
-
-### Minimum set of changes?
-
-The plan has two clean parts (A: Kajson, B: Pipelex). No scope creep detected — all items directly serve the stated goal.
-
-### Complexity check
-
-- **Files touched**: 14 (8 modified, 6 new) — above the 8-file smell threshold
-- **New classes**: 1 (`CompositeClassRegistry`) + 1 error class (`PipeJobError`)
-- However, 6 of the 14 are test files. The actual production code changes are 8 files with small, focused diffs. This is inherent complexity, not over-engineering.
-
-### TODOS cross-reference
-
-The plan IS the TODOS.md, so no cross-reference needed.
-
----
-
-## Resolved Issues
-
-### Issue 1 — RESOLVED: Hydration approach for dynamic classes
-
-**Decision**: Keep `dict[str, Any]` with concept-based hydration (user's input).
-
-**Serialization**: `working_memory.smart_dump()` → `dict[str, Any]` (dashboard-friendly)
-**Hydration**: Concept-based reconstruction in `hydration.py`:
-- Iterate stuff entries in raw dict
-- For each stuff, get `concept.structure_class_name`
-- Look up class via `ClassRegistry.get_required_subclass(name, StuffContent)`
-- Call `the_class.model_validate(content_dict)` — same pattern as `StuffContentFactory.make_stuff_content_from_concept_required()` (line 18-24)
-- Reconstruct typed Stuff objects + WorkingMemory
-
-**Data flow**:
-```
-prepare_for_temporal():
- smart_dump() → dict[str, Any] (all subclass fields preserved, no Kajson metadata)
-Temporal wire:
- kajson.dumps(PipeJob) → dict passes through as plain JSON object (no __class__ keys)
-Worker:
- kajson.loads → dict comes back as plain dict
-Hydrate (after load_from_crate):
- iterate raw dict → concept.structure_class_name → ClassRegistry → model_validate ✓
-```
-
-### Issue 2 — RESOLVED: CompositeClassRegistry missing methods
-
-Add `setup()` (no-op) and `get_required_base_model()` (local-first, parent-fallback) to the plan spec. Both are trivial delegation methods.
-
-### Issue 3 — RESOLVED: Temporal sandbox imports
-
-New imports (`CompositeClassRegistry`, `KajsonManager`, `hydration`) in WfPipeRouter must go inside the existing `with workflow.unsafe.imports_passed_through():` block.
-
-### Issue 4 — RESOLVED: PipeJob API surface
-
-Verified: only 2 places access `pipe_job.working_memory` — `pipe_router.py:21` (updated in B5) and `wf_pipe_router.py:28` (updated in B7). No other PipeJob callers are affected.
-
-### Issue 5 — RESOLVED: Hydration utility location
-
-Keep as separate `hydration.py` module. Concept-based hydration is ~20 lines, independently testable.
-
-### Issue 6 — RESOLVED: Mutation in prepare_for_temporal()
-
-Keep in-place mutation (plan as-is). PipeJob is single-use, consumed immediately after dispatch.
-
----
-
-## Test Review
-
-### Code Path Coverage Diagram
-
-```
-CODE PATH COVERAGE
-===========================
-[+] kajson/composite_class_registry.py (NEW)
- │
- ├── get_class() / get_required_class() / get_required_subclass()
- │ ├── [PLANNED] Local hit — test_local_lookup_takes_priority
- │ ├── [PLANNED] Parent fallback — test_fallback_to_parent
- │ └── [GAP] Local + parent both miss — should raise/return None
- │
- ├── register_class() / register_classes() / register_classes_dict()
- │ └── [PLANNED] Local only — test_registration_goes_to_local_only
- │
- ├── has_class() / has_subclass()
- │ └── [PLANNED] Both layers — test_has_class_checks_both
- │
- ├── teardown()
- │ └── [PLANNED] Local only — test_teardown_clears_local_only
- │
- ├── unregister_class() / unregister_class_by_name()
- │ └── [GAP] Not in planned tests — needs test for local-only unregistration
- │
- └── setup() / get_required_base_model()
- └── [GAP] Missing from plan spec — needs implementation + test
-
-[+] kajson/kajson_manager.py (ContextVar scoping)
- │
- └── get_class_registry() with ContextVar
- └── [PLANNED] test_scoped_context_var
-
-[+] pipelex/pipe_run/pipe_job.py (modified)
- │
- ├── prepare_for_temporal()
- │ ├── [PLANNED] With crate — test_prepare_for_temporal_moves_wm_to_raw
- │ ├── [PLANNED] Without crate — test_prepare_for_temporal_noop_without_crate
- │ └── [PLANNED] Empty WM — test_prepare_for_temporal_empty_wm
- │
- └── get_working_memory()
- ├── [PLANNED] From typed — test_get_working_memory_from_typed
- ├── [PLANNED] From raw raises — test_get_working_memory_from_raw_raises
- └── [PLANNED] Both None — test_get_working_memory_both_none_returns_empty
-
-[+] pipelex/temporal/tprl_pipe/hydration.py (NEW)
- │
- ├── [PLANNED] Native text — test_hydrate_with_native_text
- ├── [PLANNED] Empty — test_hydrate_empty
- ├── [PLANNED] Aliases — test_hydrate_preserves_aliases
- └── [GAP] Dynamic StructuredContent — needs test with dynamic class
-
-[+] pipelex/temporal/tprl_pipe/wf_pipe_router.py (modified)
- │
- ├── Scoped registry creation + cleanup
- │ └── [PLANNED] Integration test (B8)
- │
- ├── Hydration after crate load
- │ └── [PLANNED] Integration test (B8)
- │
- └── Error during hydration
- └── [GAP] What if hydration fails? Error should propagate cleanly
-
-[+] Integration: dynamic concepts through Temporal
- │
- ├── [PLANNED] Full round-trip with dynamic concept — test_wf_deferred_hydration.py
- ├── [PLANNED] Concurrent workflows with same concept name
- └── [GAP] Round-trip with ListContent of dynamic items
-
-─────────────────────────────────
-COVERAGE: 15/20 paths planned
- Planned tests: 15
- Gaps: 5
-GAPS: 3 need unit tests, 2 need integration tests
-─────────────────────────────────
-```
-
-### Test Gaps
-
-**Gap 1**: CompositeClassRegistry — unregister from local only (unit test)
-**Gap 2**: CompositeClassRegistry — setup() and get_required_base_model() (unit test)
-**Gap 3**: Hydration with dynamic StructuredContent class (unit test)
-**Gap 4**: Hydration failure propagation (integration test)
-**Gap 5**: ListContent of dynamic items round-trip (integration test)
-
----
-
-## Performance Review
-
-No performance concerns. The changes are:
-- One extra `smart_dump()` call per dispatch (microseconds)
-- Concept-based hydration iterates N stuffs in WM with one registry lookup each (negligible)
-- CompositeClassRegistry adds one dict lookup per class resolution (negligible)
-- ContextVar access is O(1)
-
----
-
-## Failure Modes
-
-| Codepath | Failure scenario | Test? | Error handling? | User-visible? |
-|---|---|---|---|---|
-| prepare_for_temporal() | smart_dump() fails on WM content | No | No — would crash | Yes — stack trace |
-| hydrate_working_memory() | concept not found in registry after crate load | No | ClassRegistryNotFoundError propagates | Yes — workflow fails |
-| CompositeClassRegistry teardown | Called twice | No | Safe — clears empty dict | Silent |
-| ContextVar not cleaned up | Memory leak of scoped registry | No | finally block handles it | Silent |
-| Concurrent concept name collision | Two workflows register "Greeting" with different fields | PLANNED | Scoped registry isolates | No impact |
-
-**Critical gaps**: 0 (all failure modes either have handling or are edge cases with safe defaults)
-
----
-
-## What Already Exists
-
-| Existing code | Purpose | Reused by plan? |
-|---|---|---|
-| `_library_id: ContextVar` in hub.py | Per-workflow library scoping | YES — same pattern for registry |
-| `WfPipeRouter.run()` library lifecycle | open/load/teardown per workflow | YES — extended with scoped registry |
-| `BaseModelPayloadConverter` | Kajson-based Temporal serialization | YES — drives raw field design |
-| `ClassRegistryAbstract` | Clean interface for composition | YES — CompositeClassRegistry implements it |
-| `ClassRegistry` | Concrete implementation | YES — used as local layer |
-
----
-
-## NOT in Scope
-
-| Item | Rationale |
-|---|---|
-| Thread-safe ClassRegistry | Temporal workflows are single-threaded; ContextVar provides isolation |
-| Migration of existing PipeJob callers | No existing callers break — `working_memory` default is still empty WM |
-| Dashboard UI for raw WM | The raw field is visible as JSON in Temporal dashboard; no custom UI needed |
-| Activity-level scoping | Activities don't need class resolution; only workflows load crates |
-
----
-
-## Completion Summary
-
-- **Step 0: Scope Challenge** — scope accepted as-is (complexity is inherent)
-- **Architecture Review**: 2 issues found — all resolved
-- **Code Quality Review**: 3 issues found — all resolved
-- **Test Review**: diagram produced, 5 gaps identified
-- **Performance Review**: 0 issues found
-- **NOT in scope**: written
-- **What already exists**: written
-- **TODOS.md updates**: 0 items (all handled in-plan)
-- **Failure modes**: 0 critical gaps
-- **Outside voice**: ran (codex failed, Claude subagent used) — 8 points raised, 4 substantive, 0 change plan direction
-- **Lake Score**: 5/5 recommendations chose complete option
-
----
-
-## Recommended Updates to TODOS.md
-
-Based on this review, the following changes should be made to the plan:
-
-### 1. B3: Use `smart_dump()` not `model_dump(serialize_as_any=True)`
-Replace `self.working_memory.model_dump(serialize_as_any=True)` with `self.working_memory.smart_dump()` in `prepare_for_temporal()`.
-
-### 2. B4: Concept-based hydration (not model_validate)
-Replace the `model_validate()` approach with concept-based reconstruction:
-```python
-def hydrate_working_memory(working_memory_raw: dict[str, Any]) -> WorkingMemory:
- # For each stuff entry in raw dict:
- # 1. Reconstruct Concept from concept dict (no dynamic classes needed)
- # 2. Get structure_class_name from concept
- # 3. Look up class in ClassRegistry via get_required_subclass()
- # 4. Call the_class.model_validate(content_dict)
- # 5. Build typed Stuff objects
- # Reuses pattern from StuffContentFactory.make_stuff_content_from_concept_required()
-```
-
-### 3. A1: Add missing abstract methods
-Add `setup()` (no-op) and `get_required_base_model()` (local-first, parent-fallback) to CompositeClassRegistry.
-
-### 4. B7: Imports inside unsafe block
-New imports for CompositeClassRegistry, KajsonManager, and hydration must go inside `workflow.unsafe.imports_passed_through()`.
-
-### 5. B8: Structural equality assertions
-Integration test should assert field-by-field on hydrated Stuff content (e.g., `assert stuff.content.score == 0.9`) rather than relying on `==` on dynamic model instances.
-
-### 6. A3: Additional test cases
-Add tests for:
-- `unregister_class()` / `unregister_class_by_name()` from local only
-- `get_required_base_model()` delegation
-- Hydration with dynamic StructuredContent class
-- ListContent of dynamic items round-trip
-
----
-
-## GSTACK REVIEW REPORT
-
-| Review | Trigger | Why | Runs | Status | Findings |
-|--------|---------|-----|------|--------|----------|
-| CEO Review | `/plan-ceo-review` | Scope & strategy | 0 | — | — |
-| Codex Review | `/codex review` | Independent 2nd opinion | 1 | ISSUES_FOUND | 8 points raised, 0 actionable changes (Claude subagent fallback) |
-| Eng Review | `/plan-eng-review` | Architecture & tests (required) | 1 | CLEAR (PLAN) | 6 issues, 0 critical gaps |
-| Design Review | `/plan-design-review` | UI/UX gaps | 0 | — | — |
-
-**UNRESOLVED:** 0 decisions pending
-**VERDICT:** ENG CLEARED — all 6 issues resolved through interactive review
-
-```
-+====================================================================+
-| REVIEW READINESS DASHBOARD |
-+====================================================================+
-| Review | Runs | Last Run | Status | Required |
-|-----------------|------|---------------------|-----------|----------|
-| Eng Review | 1 | 2026-03-26 02:23 | CLEAR | YES |
-| CEO Review | 0 | — | — | no |
-| Design Review | 0 | — | — | no |
-| Adversarial | 0 | — | — | no |
-| Outside Voice | 1 | 2026-03-26 02:21 | DONE | no |
-+--------------------------------------------------------------------+
-| VERDICT: CLEARED — Eng Review passed |
-+====================================================================+
-```
-
-All relevant reviews complete. No UI/UX components — design review not needed. Backend infrastructure change — CEO review optional. Ready to implement.
diff --git a/wip/archive/phase3-execution-plan.md b/wip/archive/phase3-execution-plan.md
deleted file mode 100644
index 18e9e761b..000000000
--- a/wip/archive/phase3-execution-plan.md
+++ /dev/null
@@ -1,329 +0,0 @@
-# Phase 3 Execution Plan: Deferred WorkingMemory Hydration + Scoped ClassRegistry
-
-## Context
-
-Phase 3 solves two problems for Temporal workers with custom concepts:
-1. **Chicken-and-egg deserialization** — WorkingMemory contains dynamic StructuredContent subclasses that don't exist yet when Temporal deserializes PipeJob on the worker
-2. **Global ClassRegistry collision** — concurrent workflows on the same worker could overwrite each other's class registrations
-
-The eng review resolved the hydration approach: use `smart_dump()` → `dict[str, Any]` with concept-based reconstruction (not kajson round-trip).
-
----
-
-## Implementation Order
-
-### Part A: Kajson (separate repo at `/Users/lchoquel/repos/Pipelex/kajson/`)
-
-#### A1: CompositeClassRegistry
-**New file**: `kajson/kajson/composite_class_registry.py`
-
-A `ClassRegistryAbstract` implementation wrapping local `ClassRegistry` + parent registry:
-- Constructor takes `parent: ClassRegistryAbstract`; creates internal `_local: ClassRegistry`
-- **Getters** (local-first, parent-fallback): `get_class()`, `get_required_class()`, `get_required_subclass()`, `get_required_base_model()`, `has_class()`, `has_subclass()`
-- **Mutators** (local-only): `register_class()`, `register_classes()`, `register_classes_dict()`, `unregister_class()`, `unregister_class_by_name()`
-- **Lifecycle**: `setup()` → no-op, `teardown()` → `_local.teardown()` (never touch parent)
-
-Reference: `kajson/kajson/class_registry.py` for all method signatures and behaviors.
-
-#### A2: ContextVar scoping in KajsonManager
-**Modify**: `kajson/kajson/kajson_manager.py`
-
-```python
-from contextvars import ContextVar
-
-_scoped_class_registry: ContextVar[ClassRegistryAbstract | None] = ContextVar(
- "_scoped_class_registry", default=None
-)
-
-class KajsonManager(metaclass=MetaSingleton):
- # existing __init__, get_instance, teardown...
-
- @classmethod
- def get_class_registry(cls) -> ClassRegistryAbstract:
- scoped = _scoped_class_registry.get()
- if scoped is not None:
- return scoped
- return cls.get_instance()._class_registry
-
- @classmethod
- def set_scoped_class_registry(cls, registry: ClassRegistryAbstract | None) -> None:
- _scoped_class_registry.set(registry)
-```
-
-#### A3: Tests for CompositeClassRegistry
-**New file**: `kajson/tests/unit/test_composite_class_registry.py`
-
-Tests (single TestClass):
-- `test_local_lookup_takes_priority` — same name in both, local wins
-- `test_fallback_to_parent` — name only in parent, found via composite
-- `test_registration_goes_to_local_only` — register via composite, parent unchanged
-- `test_teardown_clears_local_only` — teardown, parent untouched
-- `test_has_class_checks_both` — name in parent, `has_class()` returns True
-- `test_unregister_from_local_only` — unregister from composite, parent unaffected
-- `test_get_required_base_model_delegation` — local-first, parent-fallback
-- `test_scoped_context_var` — set/unset scoped registry on KajsonManager
-
-#### A4: Install updated Kajson
-```bash
-cd /Users/lchoquel/repos/Pipelex/_temporal
-pip install -e ../kajson
-```
-
----
-
-### Part B: Pipelex (at `/Users/lchoquel/repos/Pipelex/_temporal/`)
-
-#### B1: Add PipeJobError
-**Modify**: `pipelex/pipe_run/exceptions.py`
-
-```python
-class PipeJobError(PipelexError):
- pass
-```
-
-#### B2: Modify PipeJob model
-**Modify**: `pipelex/pipe_run/pipe_job.py`
-
-```python
-from typing import Any
-from pipelex.pipe_run.exceptions import PipeJobError
-
-class PipeJob(BaseModel):
- pipe: PipeAbstract
- working_memory: WorkingMemory | None = None
- working_memory_raw: dict[str, Any] | None = None
- pipe_run_params: PipeRunParams
- job_metadata: JobMetadata
- output_name: str | None = None
- library_crate: LibraryCrate | None = None
-
- @property
- def pipe_type(self) -> str:
- return self.pipe.__class__.__name__
-
- def get_working_memory(self) -> WorkingMemory:
- if self.working_memory is not None:
- return self.working_memory
- if self.working_memory_raw is not None:
- msg = "WorkingMemory is in raw form and has not been hydrated yet"
- raise PipeJobError(msg)
- return WorkingMemory()
-
- def prepare_for_temporal(self) -> None:
- if self.library_crate is None:
- return
- if self.working_memory is not None:
- self.working_memory_raw = self.working_memory.smart_dump()
- self.working_memory = None
-```
-
-#### B3: Unit tests for PipeJob
-**New file**: `tests/unit/pipelex/pipe_run/test_pipe_job_hydration.py`
-
-Tests using simple TextContent stuffs (no dynamic classes needed):
-- `test_prepare_for_temporal_moves_wm_to_raw`
-- `test_prepare_for_temporal_noop_without_crate`
-- `test_prepare_for_temporal_empty_wm`
-- `test_get_working_memory_from_typed`
-- `test_get_working_memory_from_raw_raises`
-- `test_get_working_memory_both_none_returns_empty`
-
-Needs a minimal PipeJob fixture — use existing PipeAbstract subclass (e.g., PipeLLM) with mock data, and a LibraryCrate fixture.
-
-#### B4: Hydration utility
-**New file**: `pipelex/temporal/tprl_pipe/hydration.py`
-
-Concept-based hydration following `StuffContentFactory.make_stuff_content_from_concept_required()` pattern:
-
-```python
-from typing import Any
-from pipelex.core.concepts.concept import Concept
-from pipelex.core.memory.working_memory import WorkingMemory
-from pipelex.core.stuffs.stuff import Stuff
-from pipelex.core.stuffs.stuff_content import StuffContent
-from pipelex.core.stuffs.stuff_content_factory import StuffContentFactory
-from pipelex.core.stuffs.text_content import TextContent
-
-def hydrate_working_memory(working_memory_raw: dict[str, Any]) -> WorkingMemory:
- """Reconstruct typed WorkingMemory from a raw dict.
-
- Must be called AFTER load_from_crate() has registered dynamic classes
- in the scoped ClassRegistry.
- """
- working_memory = WorkingMemory()
-
- raw_root = working_memory_raw.get("root", {})
- for stuff_name, stuff_dict in raw_root.items():
- concept = Concept.model_validate(stuff_dict["concept"])
- content = StuffContentFactory.make_stuff_content_from_concept_required(
- concept=concept,
- value=stuff_dict["content"],
- )
- stuff = Stuff(
- stuff_code=stuff_dict["stuff_code"],
- stuff_name=stuff_dict.get("stuff_name"),
- concept=concept,
- content=content,
- )
- working_memory.root[stuff_name] = stuff
-
- working_memory.aliases = working_memory_raw.get("aliases", {})
- return working_memory
-```
-
-Key insight: `StuffContentFactory.make_stuff_content_from_concept_required()` already does `concept.structure_class_name` → ClassRegistry lookup → `model_validate()`. We reuse it.
-
-#### B5: Hydration unit tests
-**New file**: `tests/unit/pipelex/temporal/tprl_pipe/test_hydration.py`
-
-Tests (require boot to have concepts loaded):
-- `test_hydrate_with_native_text` — raw dict with TextContent → typed TextContent
-- `test_hydrate_empty` — raw dict for empty WM → empty WM
-- `test_hydrate_preserves_aliases` — aliases survive round-trip
-
-#### B6: Update direct-mode PipeRouter
-**Modify**: `pipelex/pipe_run/pipe_router.py` line 21
-
-```python
-# Before:
-working_memory=pipe_job.working_memory,
-# After:
-working_memory=pipe_job.get_working_memory(),
-```
-
-#### B7: Update Temporal dispatchers
-**Modify**: `pipelex/temporal/tprl_pipe/pipe_router_top.py`
-
-In `_run_pipe_job()`, before `executor.execute_workflow()`:
-```python
-pipe_job.prepare_for_temporal()
-```
-
-**Modify**: `pipelex/temporal/tprl_pipe/pipe_router_child.py`
-
-In `_run_pipe_job()`, before `executor.execute_child_workflow()`:
-```python
-pipe_job.prepare_for_temporal()
-```
-
-#### B8: Update WfPipeRouter — scoped registry + hydration
-**Modify**: `pipelex/temporal/tprl_pipe/wf_pipe_router.py`
-
-Add imports inside `workflow.unsafe.imports_passed_through()`:
-```python
-from kajson.composite_class_registry import CompositeClassRegistry
-from kajson.kajson_manager import KajsonManager
-from pipelex.temporal.tprl_pipe.hydration import hydrate_working_memory
-```
-
-Update `run()`:
-```python
-try:
- if library_crate is not None:
- # 1. Create scoped ClassRegistry
- global_registry = KajsonManager.get_class_registry()
- scoped_registry = CompositeClassRegistry(parent=global_registry)
- KajsonManager.set_scoped_class_registry(scoped_registry)
-
- # 2. Load crate (registers dynamic classes into scoped registry)
- library_manager = get_library_manager()
- wf_library_id = f"wf_{workflow.info().workflow_id}"
- library_manager.open_library(library_id=wf_library_id)
- set_current_library(library_id=wf_library_id)
- library_manager.load_from_crate(library_id=wf_library_id, crate=library_crate)
-
- # 3. Hydrate WorkingMemory
- if workflow_arg.working_memory_raw is not None:
- workflow_arg.working_memory = hydrate_working_memory(workflow_arg.working_memory_raw)
- workflow_arg.working_memory_raw = None
-
- working_memory = workflow_arg.get_working_memory()
- pipe_output = await pipe.run_pipe(
- working_memory=working_memory,
- ...
- )
-except ActivityError as exc:
- ...
-finally:
- if wf_library_id is not None:
- get_library_manager().teardown(library_id=wf_library_id)
- teardown_current_library()
- if library_crate is not None:
- KajsonManager.set_scoped_class_registry(None)
-```
-
-#### B9: Integration test — dynamic concepts through Temporal
-**New file**: `tests/integration/pipelex/temporal/library_crate/dynamic_concept_sequence.mthds`
-
-A test bundle with a custom concept with inline structure, e.g.:
-```toml
-[domain]
-code = "dynamic_concept_test"
-
-[concepts.Greeting]
-structure.message = "str"
-structure.language = "str"
-
-[pipes.greet]
-type = "PipeLLM"
-# ... produces a Greeting
-```
-
-**Add to**: `tests/integration/pipelex/temporal/test_data.py`
-
-```python
-class DeferredHydrationTestData:
- BUNDLE_FILE: ClassVar[str] = str(Path(__file__).parent / "library_crate" / "dynamic_concept_sequence.mthds")
- PIPE_CODE: ClassVar[str] = "dynamic_greeting_sequence"
- DOMAIN: ClassVar[str] = "dynamic_concept_test"
-```
-
-**New file**: `tests/integration/pipelex/temporal/library_crate/test_wf_deferred_hydration.py`
-
-Following existing Phase 2 test patterns:
-- Load dynamic concept bundle via `PipelexInterpreter.make_pipelex_bundle_blueprint()`
-- Build PipeJob with WorkingMemory (may be empty or contain input stuff)
-- Execute via Temporal workflow
-- Assert output has correctly typed Stuff with StructuredContent (field-by-field assertions)
-
-#### B10: Lint and test
-```bash
-make agent-check
-make agent-test
-```
-
----
-
-## File Summary
-
-| File | Change |
-|------|--------|
-| **Kajson** | |
-| `kajson/kajson/composite_class_registry.py` | **NEW** — CompositeClassRegistry |
-| `kajson/kajson/kajson_manager.py` | Add ContextVar scoping |
-| `kajson/tests/unit/test_composite_class_registry.py` | **NEW** — unit tests |
-| **Pipelex** | |
-| `pipelex/pipe_run/exceptions.py` | Add PipeJobError |
-| `pipelex/pipe_run/pipe_job.py` | Add raw field, get_working_memory(), prepare_for_temporal() |
-| `pipelex/pipe_run/pipe_router.py` | Use get_working_memory() |
-| `pipelex/temporal/tprl_pipe/hydration.py` | **NEW** — concept-based hydration |
-| `pipelex/temporal/tprl_pipe/pipe_router_top.py` | Call prepare_for_temporal() |
-| `pipelex/temporal/tprl_pipe/pipe_router_child.py` | Call prepare_for_temporal() |
-| `pipelex/temporal/tprl_pipe/wf_pipe_router.py` | Scoped registry + hydration |
-| `tests/unit/pipelex/pipe_run/test_pipe_job_hydration.py` | **NEW** |
-| `tests/unit/pipelex/temporal/tprl_pipe/test_hydration.py` | **NEW** |
-| `tests/integration/pipelex/temporal/test_data.py` | Add DeferredHydrationTestData |
-| `tests/integration/pipelex/temporal/library_crate/dynamic_concept_sequence.mthds` | **NEW** |
-| `tests/integration/pipelex/temporal/library_crate/test_wf_deferred_hydration.py` | **NEW** |
-
----
-
-## Verification
-
-1. Kajson unit tests pass: `test_composite_class_registry.py`
-2. PipeJob unit tests pass: `test_pipe_job_hydration.py`
-3. Hydration unit tests pass: `test_hydration.py`
-4. Existing Phase 2 tests still pass: `test_wf_library_crate.py`
-5. New integration test passes: `test_wf_deferred_hydration.py`
-6. `make agent-check` passes
-7. `make agent-test` passes
diff --git a/wip/archive/phase3-mode2-regression.md b/wip/archive/phase3-mode2-regression.md
deleted file mode 100644
index e287f4490..000000000
--- a/wip/archive/phase3-mode2-regression.md
+++ /dev/null
@@ -1,181 +0,0 @@
-# Phase 3 Regression: Deferred Hydration Fails in 3-Process Mode
-
-## Problem Statement
-
-Temporal Phase 3 (Deferred WorkingMemory Hydration) passes all tests in Mode 1
-(pytest with in-process worker) but fails in Mode 2 (true 3-process: server + worker
-+ submitter) with:
-
-```
-KajsonDecoderError: Class 'dynamic_concept_test__Greeting' not found in module 'builtins'
-```
-
-This is a regression because Phase 3 was marked complete in `wip/00-master-plan.md:208`.
-
-## How to Reproduce
-
-Use the `/temporal-e2e-validate` skill (defined in `.claude/skills/temporal-e2e-validate/`).
-It has two modes:
-
-- **Mode 1** (pytest): All tests pass — confirms Phase 3 logic works in-process.
-- **Mode 2** (3-process): Tier 2 (deferred hydration) hangs, worker shows the error above.
-
-Quick reproduction of Mode 2 failure (assumes Temporal dev server on localhost:7233):
-
-```bash
-# Terminal 1: Temporal server
-temporal server start-dev
-
-# Terminal 2: Worker (no PIPELEXPATH — bundles arrive only via crate)
-.venv/bin/python -m pipelex.temporal.worker_cli --is-not-sandboxed
-
-# Terminal 3: Submitter — this hangs because the worker fails to deserialize
-.venv/bin/pipelex run bundle \
- tests/integration/pipelex/temporal/library_crate/dynamic_concept_sequence.mthds \
- --pipe dynamic_greeting_sequence \
- --temporal --dry-run --mock-inputs --no-logo
-```
-
-The worker log will show `KajsonDecoderError: Class 'dynamic_concept_test__Greeting'
-not found in module 'builtins'` during child workflow result deserialization.
-
-## Root Cause Analysis
-
-### The deserialization chain
-
-When a parent WfPipeRouter dispatches a child WfPipeRouter (for each step in a
-PipeSequence), the child returns a `PipeOutput` containing `StructuredContent` with
-a dynamically generated class (e.g. `dynamic_concept_test__Greeting`).
-
-Temporal serializes this return value via `kajson.dumps()`, which records
-`__class__: "dynamic_concept_test__Greeting"` and `__module__: "builtins"`.
-The `__module__` is `"builtins"` because dynamically generated classes (created via
-`type()` in ConceptFactory) get `builtins` as their module by default.
-
-The parent workflow then deserializes via the data converter:
-
-```
-_apply_resolve_child_workflow_execution (Temporal SDK internal callback)
- → _convert_payloads
- → BaseModelPayloadConverter.from_payload()
- → kajson.loads(data, class_registry=get_class_registry())
-```
-
-### Why Mode 1 works but Mode 2 fails
-
-The data converter calls `pipelex.hub.get_class_registry()`, which checks the
-`_library_id` ContextVar:
-
-```python
-# pipelex/hub.py:381-392
-def get_class_registry() -> ClassRegistryAbstract:
- library_id = _library_id.get()
- if library_id is not None:
- registry = get_library_manager().get_library_class_registry(library_id)
- if registry is not None:
- return registry
- return KajsonManager.get_class_registry()
-```
-
-**The critical problem**: `_apply_resolve_child_workflow_execution` is a callback
-invoked by the Temporal SDK's internal event processor, NOT from within the workflow
-coroutine's `run()` method. The `_library_id` ContextVar was set inside `run()`,
-but Temporal's event processing does not execute in the same ContextVar scope. So
-`_library_id.get()` returns `None`, and `get_class_registry()` falls back to the
-global KajsonManager registry.
-
-**Mode 1 (in-process)**: The test fixture `pipe_job_from_bundle()`
-(`tests/integration/pipelex/fixtures/pipe_job_helpers.py:73-85`) loads the bundle
-into a Library. During loading, ConceptFactory registers dynamic classes via
-`hub.get_class_registry()`. The Library created by `open_library()` has no
-ClassRegistry set (unlike the workflow which explicitly calls
-`wf_library.set_class_registry()`), so `get_library_class_registry()` returns None,
-and classes are registered in the **global** KajsonManager registry. When the data
-converter falls back to the global registry, it finds the classes. **The test fixture
-masks the bug by pre-populating the global registry.**
-
-**Mode 2 (3-process)**: The worker process starts with no bundles loaded. The global
-KajsonManager registry has no dynamic classes. WfPipeRouter creates a per-workflow
-ClassRegistry and loads the crate into it, but the data converter can't access it
-(ContextVar not set in Temporal's event processing context). The global registry
-lookup fails, then `sys.modules["builtins"]` lookup fails → `KajsonDecoderError`.
-
-### Why the ContextVar approach doesn't work here
-
-The Temporal Python SDK's `_workflow_instance.py` processes events (activity results,
-child workflow results) via internal callbacks. These callbacks call `_convert_payloads`
-which invokes the data converter. This call chain runs in the SDK's internal context,
-not in the coroutine context of the workflow's `run()` method where `set_current_library()`
-was called. Python ContextVars set inside a coroutine are not automatically visible
-to SDK-internal callbacks that run outside that coroutine's execution frame.
-
-## What Was Planned vs What Was Implemented
-
-The original execution plan (`wip/phase3-execution-plan.md`) specified two mechanisms
-that were not implemented:
-
-### 1. CompositeClassRegistry (plan step A1-A3)
-
-**Planned**: A new `ClassRegistryAbstract` implementation in kajson that wraps a local
-registry + parent registry. Lookups check local first, fall back to parent. Mutations
-go to local only.
-
-**Actual**: Not implemented. The file `kajson/kajson/composite_class_registry.py` does
-not exist. Instead, the workflow creates a plain `ClassRegistry` and pre-seeds it from
-the global registry's entries:
-
-```python
-# wf_pipe_router.py:37-41
-global_registry = KajsonManager.get_class_registry()
-workflow_registry = ClassRegistry()
-if isinstance(global_registry, ClassRegistry):
- workflow_registry.register_classes_dict(dict(global_registry.root))
-```
-
-This pre-seeding approach works for isolation but doesn't help with the data converter
-problem — the data converter still can't reach the workflow-scoped registry.
-
-### 2. ContextVar scoping in KajsonManager (plan step A2)
-
-**Planned**: A `_scoped_class_registry` ContextVar in KajsonManager itself, checked
-by `KajsonManager.get_class_registry()` before returning the global registry. This
-would allow setting a scoped registry that kajson's decoder would automatically use.
-
-**Actual**: Not implemented. `KajsonManager.get_class_registry()` in the kajson repo
-(`kajson/kajson/kajson_manager.py`) has no ContextVar — it always returns the singleton's
-global registry. The scoping was implemented at the pipelex hub level via `_library_id`
-ContextVar, which doesn't work for Temporal's internal data converter calls.
-
-## Key Files
-
-| File | Role in the problem |
-|------|---------------------|
-| `pipelex/temporal/tprl_pipe/wf_pipe_router.py` | Sets up per-workflow registry, loads crate, hydrates WM |
-| `pipelex/temporal/temporal_data_converter.py:77` | Calls `get_class_registry()` during deserialization |
-| `pipelex/hub.py:381-392` | `get_class_registry()` uses `_library_id` ContextVar |
-| `pipelex/hub.py:462-467` | `_library_id` ContextVar + `set_current_library()` |
-| `pipelex/pipe_run/pipe_job.py:34-49` | `prepare_for_temporal()` serializes WM to raw dict |
-| `pipelex/temporal/tprl_pipe/hydration.py` | `hydrate_working_memory()` — works correctly |
-| `/Users/lchoquel/repos/Pipelex/kajson/kajson/kajson_manager.py` | Global registry, no ContextVar scoping |
-| `/Users/lchoquel/repos/Pipelex/kajson/kajson/json_decoder.py:141-161` | Decoder: explicit registry → sys.modules → error |
-| `tests/integration/pipelex/fixtures/pipe_job_helpers.py:73-85` | Test fixture that masks the bug |
-| `wip/phase3-execution-plan.md` | Original plan with CompositeClassRegistry + KajsonManager ContextVar |
-
-## Scope of Impact
-
-All bundles with dynamic concept classes (inline `structure` in `.mthds`) fail in
-3-process mode. Bundles using only native types (Text) work fine. Affected tests:
-
-- Tier 2: `dynamic_concept_sequence.mthds` — direct Phase 3 validation
-- Tier 3: `temporal_parallel.mthds` — uses ToneAnalysis/LengthAnalysis concepts
-- All concurrent concept isolation tests — use conflicting Result/Profile/Summary concepts
-
-PipeParallel with native text works. Concurrent pipe isolation (native text) works.
-
-## Fix Applied During This Session
-
-A separate fixture ordering bug was fixed in `tests/integration/pipelex/temporal/conftest.py`:
-`boot_temporal` could run before `reset_pipelex_config_fixture` when using `--temporal-server local`,
-because `_session_owns_pipelex()` caused the module-scoped fixture to skip initialization while
-the session-scoped `env` fixture (which was supposed to init Pipelex) is not autouse. Fixed by
-always initializing Pipelex in the module-scoped fixture. This fix is uncommitted.
diff --git a/wip/archive/phase4-explicit-class-registry.md b/wip/archive/phase4-explicit-class-registry.md
deleted file mode 100644
index 3e89bc783..000000000
--- a/wip/archive/phase4-explicit-class-registry.md
+++ /dev/null
@@ -1,211 +0,0 @@
-# Plan: Explicit ClassRegistry — No Singleton Scoping in Kajson
-
-## Context
-
-Phase 3 (deferred WorkingMemory hydration + scoped ClassRegistry) works with in-process tests but fails with separate Temporal workers due to two bugs:
-
-1. **Decoder bypass**: `json_decoder.py:140-150` never reaches the ClassRegistry fallback for dynamic classes because `builtins` is always in `sys.modules`
-2. **Teardown clobber**: `wf_pipe_router.py` sets the scoped registry to `None` in `finally`, which isn't stack-safe for nested workflows
-
-Both bugs stem from the same architectural weakness: kajson (a serialization library) owns workflow-scoping concerns via a ContextVar singleton. The fix is to move scoping out of kajson entirely, tie the ClassRegistry to the Library lifecycle (where it logically belongs), and give kajson an explicit `class_registry` parameter.
-
-## Design Principles
-
-- **Kajson is a pure library**: no ContextVars, no workflow scoping. Accepts explicit `class_registry` parameter.
-- **Library owns its ClassRegistry**: each Library (loaded from a crate) gets a pre-seeded ClassRegistry containing global + dynamic classes. No CompositeClassRegistry needed — just a flat dict.
-- **Reuse existing `_library_id` ContextVar**: `hub.get_class_registry()` reads the active library_id, gets that library's ClassRegistry. No new ContextVar.
-- **Explicit at the boundary**: `temporal_data_converter` passes the registry explicitly to `kajson.loads()`.
-
-## Changes
-
-### 1. Kajson — Add explicit `class_registry` param, remove scoping
-
-**`kajson/kajson.py`** — `loads()` and `load()` accept optional `class_registry`
-```python
-def loads(json_string, class_registry=None, **kwargs):
- if class_registry is not None:
- kwargs["class_registry"] = class_registry
- return json.loads(json_string, cls=UniversalJSONDecoder, **kwargs)
-```
-Same for `load()`.
-
-**`kajson/json_decoder.py`** — Decoder uses explicit registry first
-```python
-def __init__(self, *args, **kwargs):
- self._class_registry = kwargs.pop("class_registry", None)
- json.JSONDecoder.__init__(self, object_hook=self.universal_decoder, *args, **kwargs)
- self.logger = logging.getLogger(DECODER_LOGGER_CHANNEL_NAME)
-```
-
-In `universal_decoder()` class resolution (lines 139-172), add a new first step:
-```python
-# Step 0: Check explicit registry first (handles dynamic classes)
-if self._class_registry is not None:
- registered_class = self._class_registry.get_class(name=class_name)
- if registered_class is not None:
- the_class = registered_class
- # skip to decoder strategies (line 174)
-```
-If not found in explicit registry, fall through to existing logic (sys.modules → global registry → importlib).
-
-**`kajson/kajson_manager.py`** — Remove ContextVar and scoped methods
-- Delete `_scoped_class_registry` ContextVar
-- Delete `set_scoped_class_registry()` method
-- `get_class_registry()` simply returns `cls.get_instance()._class_registry` (global only)
-
-**`kajson/composite_class_registry.py`** — Keep file, stop using it. Can be removed in a follow-up.
-
-### 2. Pipelex — Library owns its ClassRegistry (PrivateAttr)
-
-**`pipelex/libraries/library.py`** — Add ClassRegistry as a PrivateAttr on Library:
-```python
-from pydantic import PrivateAttr
-from kajson.class_registry import ClassRegistry
-
-class Library(BaseModel):
- # ... existing fields ...
- _class_registry: ClassRegistry | None = PrivateAttr(default=None)
-
- def get_class_registry(self) -> ClassRegistry | None:
- return self._class_registry
-
- def set_class_registry(self, class_registry: ClassRegistry) -> None:
- self._class_registry = class_registry
-```
-
-PrivateAttr keeps it off the Pydantic serialization path (no impact on `model_dump()`, validation, or crate serialization). The registry lives and dies with the Library — when `teardown()` deletes the Library from `_libraries`, the registry is GC'd with it. No parallel dicts, no sync risk, no memory leaks.
-
-**`pipelex/libraries/library_manager.py`** — Accessor for convenience:
-```python
-def get_library_class_registry(self, library_id: str) -> ClassRegistry | None:
- library = self._libraries.get(library_id)
- if library is not None:
- return library.get_class_registry()
- return None
-```
-
-No changes needed in `teardown()` — the Library's deletion handles cleanup automatically.
-
-### 3. Pipelex — `hub.get_class_registry()` reads from Library
-
-**`pipelex/hub.py:381-388`** — Replace KajsonManager delegation with library lookup:
-```python
-def get_class_registry() -> ClassRegistryAbstract:
- library_id = _library_id.get()
- if library_id is not None:
- registry = get_library_manager().get_library_class_registry(library_id)
- if registry is not None:
- return registry
- return get_pipelex_hub().get_required_class_registry()
-```
-
-Remove `from kajson.kajson_manager import KajsonManager` from hub.py if no longer needed (check other usages first).
-
-### 4. Pipelex — wf_pipe_router uses plain ClassRegistry
-
-**`pipelex/temporal/tprl_pipe/wf_pipe_router.py`** — Rewrite scoping:
-
-```python
-# Remove CompositeClassRegistry and KajsonManager imports
-# Add: from kajson.class_registry import ClassRegistry
-
-try:
- if library_crate is not None:
- # 1. Create per-workflow ClassRegistry pre-seeded from global
- global_registry = get_pipelex_hub().get_required_class_registry()
- workflow_registry = ClassRegistry()
- workflow_registry.register_classes_dict(dict(global_registry.root)) # copy global entries
-
- # 2. Open library and attach registry to it
- library_manager = get_library_manager()
- wf_library_id = f"wf_{workflow.info().workflow_id}"
- _wf_library_id, wf_library = library_manager.open_library(library_id=wf_library_id)
- wf_library.set_class_registry(workflow_registry)
- set_current_library(library_id=wf_library_id)
-
- # 3. Load crate (registers dynamic classes into workflow_registry via hub.get_class_registry())
- library_manager.load_from_crate(library_id=wf_library_id, crate=library_crate)
-
- # 4. Hydrate WorkingMemory
- if workflow_arg.working_memory_raw is not None:
- workflow_arg.working_memory = hydrate_working_memory(workflow_arg.working_memory_raw)
- workflow_arg.working_memory_raw = None
-
- # ... run pipe ...
-
-finally:
- if wf_library_id is not None:
- get_library_manager().teardown(library_id=wf_library_id) # cleans up registry too
- teardown_current_library()
- # No KajsonManager.set_scoped_class_registry(None) needed!
-```
-
-Key insight: `set_current_library()` sets `_library_id` ContextVar. From that point, all calls to `hub.get_class_registry()` return `workflow_registry`. When `concept_factory` calls `KajsonManager.get_class_registry().register_class(...)`, it still hits the global. We need to migrate those callers.
-
-### 5. Migrate KajsonManager.get_class_registry() callers to hub
-
-All ~20 call sites in Pipelex that use `KajsonManager.get_class_registry()` must switch to `hub.get_class_registry()` (or receive the registry explicitly). This is a mechanical change.
-
-**Files to update** (import `get_class_registry` from `pipelex.hub` instead of `KajsonManager` from `kajson`):
-
-| File | Lines | Change |
-|------|-------|--------|
-| `pipelex/core/concepts/concept_factory.py` | 323, 359, 405, 435 | `get_class_registry().register_class(...)` |
-| `pipelex/core/concepts/concept.py` | 132, 133, 162, 165, 175, 183 | `get_class_registry().get_class(...)` etc. |
-| `pipelex/core/concepts/structure_generation/generator.py` | 585 | `get_class_registry().get_class(...)` |
-| `pipelex/core/pipes/pipe_factory.py` | 110 | `get_class_registry().get_required_subclass(...)` |
-| `pipelex/libraries/library_manager.py` | 1134, 1165 | `get_class_registry()` |
-| `pipelex/system/registries/class_registry_utils.py` | 37, 148 | `get_class_registry()` |
-| `pipelex/tools/typing/structure_printer.py` | 26 | `get_class_registry()` |
-| `pipelex/pipe_operators/func/pipe_func.py` | 104 | `get_class_registry().get_class(...)` |
-| `pipelex/cli/commands/build/structures_cmd.py` | 194, 243, 270 | `get_class_registry().register_class(...)` |
-
-Each file: replace `KajsonManager.get_class_registry()` with `get_class_registry()` imported from `pipelex.hub`. Remove unused `KajsonManager` import if nothing else uses it.
-
-### 6. Temporal data converter — explicit parameter
-
-**`pipelex/temporal/temporal_data_converter.py`** — Pass registry to `kajson.loads()`:
-
-```python
-from pipelex.hub import get_class_registry
-
-def _kajson_deserialize_from_payload(self, payload: Payload) -> Any:
- data = payload.data.decode()
- log.verbose(f"unijson_deserialize_payload — data: {data}")
- pydantic_gizmo = kajson.loads(data, class_registry=get_class_registry())
- log.verbose(f"unijson_deserialize_payload — pydantic_gizmo: {pydantic_gizmo}")
- return pydantic_gizmo
-```
-
-### 7. Tests
-
-**Kajson tests** (`tests/unit/test_composite_class_registry.py`):
-- Update `test_scoped_context_var` — this test uses `set_scoped_class_registry` which is removed. Replace with a test that verifies `kajson.loads(data, class_registry=custom_reg)` resolves from the explicit registry.
-
-**Pipelex tests** (`tests/unit/pipelex/temporal/tprl_pipe/test_hydration.py`):
-- Update to reflect new ClassRegistry setup (no CompositeClassRegistry)
-
-**Pipelex tests** (`tests/unit/pipelex/pipe_run/test_pipe_job_hydration.py`):
-- Verify no breakage
-
-**New test**: test that `kajson.loads()` with explicit `class_registry` finds dynamic classes even when `__module__` is `"builtins"` (the exact bug scenario).
-
-## Verification
-
-1. **Lint + type check**: `make agent-check` in both kajson and _temporal
-2. **Unit tests**: `make agent-test` in both repos
-3. **Manual Temporal test**: Use `/temporal-diagnose` with 3-process setup (server + separate worker + submitter) using `dynamic_concept_sequence.mthds` — this is the test that currently fails with `KajsonDecoderError: Class 'Greeting' not found in module 'builtins'`
-
-## Key Files
-
-| Repo | File | Purpose |
-|------|------|---------|
-| kajson | `kajson/kajson.py` | Add `class_registry` param to `loads()`/`load()` |
-| kajson | `kajson/json_decoder.py` | Accept + use explicit registry in decoder |
-| kajson | `kajson/kajson_manager.py` | Remove ContextVar, simplify to global-only |
-| _temporal | `pipelex/hub.py` | `get_class_registry()` reads from library |
-| _temporal | `pipelex/temporal/tprl_pipe/wf_pipe_router.py` | Plain ClassRegistry, library-associated |
-| _temporal | `pipelex/temporal/temporal_data_converter.py` | Pass explicit registry to `kajson.loads()` |
-| _temporal | `pipelex/libraries/library.py` | PrivateAttr ClassRegistry on Library |
-| _temporal | `pipelex/libraries/library_manager.py` | Accessor for library's ClassRegistry |
-| _temporal | ~9 files | Migrate `KajsonManager.get_class_registry()` → `hub.get_class_registry()` |
diff --git a/wip/archive/phase4.5-distributed-tracing-implementation.md b/wip/archive/phase4.5-distributed-tracing-implementation.md
deleted file mode 100644
index b9ed581d5..000000000
--- a/wip/archive/phase4.5-distributed-tracing-implementation.md
+++ /dev/null
@@ -1,613 +0,0 @@
-phase 4.5 of wip/00-master-plan.md
-
-# Distributed Tracing & Reporting — Local Version
-
-> Implementation plan for the NDJSON-file-based event log that enables graph tracing and cost reporting across Temporal workers.
-> Design rationale and cloud architecture (DynamoDB) in [wip/distributed-tracing-and-reporting.md](wip/distributed-tracing-and-reporting.md).
-
----
-
-## Overview
-
-Add a **file-based event log** to the existing `GraphTracer`, for use when running with Temporal distributed workers. The in-memory path is preserved unchanged for direct mode (no Temporal) — it's already optimal for single-process execution.
-
-**Approach: dual-write in GraphTracer.** When an `EventLogProtocol` is provided, `GraphTracer` emits events as a side effect alongside its existing in-memory accumulation. No new tracer class, no new hub functions, no call site changes. `pipe_abstract.py` and controllers continue calling `GraphTracerManager` as before.
-
-**Two modes, selected at tracer open time:**
-
-| Mode | What happens in GraphTracer | Reporting | When |
-|---|---|---|---|
-| **In-memory only** (default) | Existing accumulation, `teardown()` → `GraphSpec` | Existing `ReportingManager` | Direct execution (no Temporal) |
-| **In-memory + event log** | Same accumulation + `emit()` to NDJSON per method call | `ReportingManager` + event emission from activities | Temporal distributed execution |
-
-In direct mode, `open_tracer()` is called without an event log → `GraphTracer` works as today. In Temporal mode, `WfPipeRouter` creates an `NdjsonEventLog` and passes it to `open_tracer()` → `GraphTracer` dual-writes. After all workflows complete, `runner.py` reads events from all files and assembles a cross-worker `GraphSpec`.
-
-**Event log backend**: NDJSON files. One file per workflow (or per activity for usage events), organized in a directory per pipeline run:
-```
-{traces_dir}/{pipeline_run_id}/
- ├── wf_{workflow_id_A}.ndjson
- ├── wf_{workflow_id_B}.ndjson
- ├── act_{activity_id_X}.ndjson # Usage events from activities
- └── ...
-```
-
-Each line is a JSON-serialized `TraceEvent`. Workflow files have exactly one writer. Activity files have one writer per activity execution.
-
-**Protocol**: `EventLogProtocol` with `emit()` / `read_events()`. The NDJSON backend is the local implementation. Cloud implementation (DynamoDB) will implement the same protocol later.
-
-**Key design invariant**: `emit()` MUST be synchronous (file append + flush). This guarantees all events are flushed before a child workflow returns. If emit were async or batched, the assembler could read incomplete files. This invariant must be preserved in any future backend implementation.
-
----
-
-## Step 0: Event Models
-
-> Pure data models — no integration, no refactoring. TDD: write serialization tests first.
-
-### What
-
-Define the `TraceEvent` Pydantic model hierarchy that replaces the in-memory `_MutableNodeData` accumulation. Events capture the same information that `GraphTracer.on_pipe_start()`, `on_pipe_end_success()`, `on_pipe_end_error()`, and the controller-specific registration methods currently capture — but as immutable, serializable records.
-
-### Event type inventory
-
-Map every method on `GraphTracerManager` (see `pipelex/graph/graph_tracer_manager.py`) and `ReportingManager` (see `pipelex/reporting/reporting_manager.py`) to an event type:
-
-| Current method | Event type | Payload (beyond base fields) |
-|---|---|---|
-| `on_pipe_start()` | `PipeStartEvent` | node_id, parent_node_id, pipe_code, pipe_type, node_kind, input_specs |
-| `on_pipe_end_success()` | `PipeEndSuccessEvent` | node_id, ended_at, output_spec, metrics |
-| `on_pipe_end_error()` | `PipeEndErrorEvent` | node_id, ended_at, error (ErrorSpec) |
-| `add_edge()` | `EdgeEvent` | source_node_id, target_node_id, edge_kind, label, source/target_stuff_digest |
-| `register_controller_output()` | `ControllerOutputEvent` | node_id, output_spec |
-| `register_batch_item_extraction()` | `BatchItemEvent` | list_stuff_code, item_stuff_code, item_index, batch_controller_node_id |
-| `register_batch_aggregation()` | `BatchAggregateEvent` | output_list_stuff_code, item_stuff_code, item_index, batch_controller_node_id |
-| `register_parallel_combine()` | `ParallelCombineEvent` | combined_stuff_code, branch_stuff_codes, parallel_controller_node_id |
-| `report_inference_job()` | `UsageReportEvent` | node_id (which pipe), tokens_usage (the union type) |
-
-Base fields shared by all events:
-- `pipeline_run_id: str`
-- `workflow_id: str` — Temporal workflow ID or `"direct"` for in-process
-- `event_kind: TraceEventKind` (discriminator)
-- `timestamp: datetime` — UTC, for display/debugging only
-- `sequence: int` — per-writer monotonic counter, for ordering and deduplication
-
-### Node ID scheme
-
-Change from `{graph_id}:node_{sequence}` to `{graph_id}:{workflow_id}:node_{sequence}`.
-
-`workflow_id` is the full Temporal workflow ID, or `"direct"` for in-process mode. Combined with the per-writer sequence counter, this guarantees globally unique node IDs without coordination. Using the full workflow ID avoids collision — the last 8 chars of Temporal workflow IDs often come from the base ID (e.g. `pipe_router`) and repeat across workflows.
-
-Edge IDs follow the same scheme: `{graph_id}:{workflow_id}:edge_{sequence}`.
-
-The sequence counter is **per-writer** (per workflow/file), starting at 0. No need to coordinate across workers.
-
-**Renderer impact**: Mermaid/ReactFlow renderers that parse node IDs by splitting on `:` must handle the additional segment. Node IDs are opaque strings in most code — only renderers and test assertions need updating.
-
-### Files to create
-
-| File | Contents |
-|---|---|
-| `pipelex/tracing/__init__.py` | Empty |
-| `pipelex/tracing/trace_events.py` | `TraceEventKind` enum, `TraceEvent` base model, all event subclasses |
-| `tests/unit/pipelex/tracing/__init__.py` | Empty |
-| `tests/unit/pipelex/tracing/test_trace_events.py` | Serialization round-trip tests for each event type |
-
-### Design notes
-
-- Use Pydantic's discriminated union (`Annotated[... , Field(discriminator="event_kind")]`) so `TraceEvent` can be deserialized from JSON without knowing the subclass upfront.
-- `IOSpec` and `ErrorSpec` from `pipelex/graph/graphspec.py` are reused as-is — they're already Pydantic models designed for JSON serialization.
-- `TokensUsage` is the existing union type `LLMTokensUsage | ImgGenTokensUsage | ExtractTokensUsage | SearchTokensUsage` from `reporting_manager.py`. Reuse it. It needs a discriminated union wrapper for deserialization: `AnyTokensUsage = Annotated[TokensUsage, Field(discriminator="model_type")]`. **Prerequisite**: each TokensUsage model's `model_type` field must be changed from `str` to `Literal` (e.g., `model_type: Literal["llm"] = "llm"` instead of `model_type: str = "llm"`). This is a one-line change per model in `llm_report.py`, `img_gen_report.py`, `extract_report.py`, `search_report.py`.
-- `TraceEventKind` inherits from `StrEnum` (imported from `pipelex.types`).
-
-### Checklist
-
-- [x] Define `TraceEventKind` enum with all event kinds
-- [x] Define `TraceEvent` base model with shared fields
-- [x] Define all event subclasses (`PipeStartEvent`, `PipeEndSuccessEvent`, `PipeEndErrorEvent`, `EdgeEvent`, `ControllerOutputEvent`, `BatchItemEvent`, `BatchAggregateEvent`, `ParallelCombineEvent`, `UsageReportEvent`)
-- [x] Define discriminated union type `AnyTraceEvent` for deserialization
-- [x] Write serialization round-trip tests for each event type
-- [x] Write test for discriminated union deserialization (JSON → correct subclass)
-- [x] Verify `IOSpec`, `ErrorSpec`, `TimingSpec` survive JSON round-trip within events
-- [x] Fix `model_type` field to `Literal` on `LLMTokensUsage`, `ImgGenTokensUsage`, `ExtractTokensUsage`, `SearchTokensUsage`
-- [x] Define `AnyTokensUsage` discriminated union using `Field(discriminator="model_type")`
-- [x] Verify `TokensUsage` union survives round-trip with discriminated union deserialization
-- [x] `make agent-check` passes
-
----
-
-## Step 1: EventLogProtocol & NDJSON Backend
-
-> The write/read infrastructure. TDD: test emit/read cycle first.
-
-### What
-
-Define the `EventLogProtocol` and implement the NDJSON file backend. This is the storage layer — it knows nothing about graphs or reporting, only about appending and reading `TraceEvent` objects.
-
-### EventLogProtocol
-
-```python
-class EventLogProtocol(Protocol):
- def emit(self, event: TraceEvent) -> None: ...
- def read_events(self, pipeline_run_id: str) -> list[TraceEvent]: ...
- def cleanup(self, pipeline_run_id: str) -> None: ...
-```
-
-`emit()` is **synchronous** — file append is fast and must not become a Temporal replay point. The event is durable when `emit()` returns (file flush).
-
-**Critical invariant**: `emit()` must remain synchronous with an explicit file flush. This guarantees all events are written before a child workflow returns to its parent. If emit were async or batched, the assembler could read incomplete files from child workflows. This invariant must be preserved in any future backend implementation (DynamoDB, etc.).
-
-`read_events()` returns all events for a pipeline run, ordered by `(workflow_id, sequence)`. Used by the assembler post-execution.
-
-`cleanup()` removes the run's directory. Called after graph outputs are generated.
-
-### NDJSON implementation: `NdjsonEventLog`
-
-**Write path** (`emit`):
-1. Determine file path: `{traces_dir}/{event.pipeline_run_id}/wf_{event.workflow_id}.ndjson`
-2. Create directory if needed (`os.makedirs(..., exist_ok=True)`)
-3. Open file in append mode, write `kajson.dumps(event) + "\n"`, flush
-
-File handle caching: keep a `dict[str, IO]` of open file handles keyed by `(pipeline_run_id, workflow_id)`. Close handles on `cleanup()` or when the writer is garbage-collected. This avoids repeated `open()` calls for high-frequency events.
-
-**Read path** (`read_events`):
-1. Glob `{traces_dir}/{pipeline_run_id}/*.ndjson` (includes `wf_*` and `act_*` files)
-2. For each file, read all lines, parse each as `AnyTraceEvent` (discriminated union)
- - **Corrupt line handling**: Wrap each line parse in `try/except JSONDecodeError`. Log a warning with the file path and line number, then skip the corrupt line. This handles crash-mid-write scenarios where NDJSON has no journaling.
-3. Deduplicate by `(workflow_id, sequence)` — handles Temporal replay re-emission. When duplicates exist, keep the first occurrence (they are identical for correct replays).
-4. Sort by `(workflow_id, sequence)` for deterministic ordering
-5. Return flat list
-
-**Replay growth note**: When Temporal replays a workflow, events are re-appended with the same `(workflow_id, sequence)` pairs. The NDJSON file grows with each replay. This is functionally correct (dedup on read handles it) but wastes disk. This is an accepted tradeoff for the simplicity of append-only writes. SQLite's `INSERT OR IGNORE` would prevent duplicate writes entirely, but NDJSON is simpler and sufficient for local dev.
-
-**Cleanup path** (`cleanup`):
-1. Close any cached file handles for this run
-2. `shutil.rmtree({traces_dir}/{pipeline_run_id})`
-
-**Important**: Traces are never auto-deleted after graph assembly. Cleanup must be explicitly called by the user or a separate cleanup command. This ensures traces are available for debugging if assembly fails, and for usage reporting which may run after graph generation.
-
-### InMemoryEventLog
-
-For unit tests and direct mode (optional — direct mode can also use NDJSON):
-- `emit()` appends to `list[TraceEvent]`
-- `read_events()` returns the list filtered by pipeline_run_id
-- No file I/O
-
-### Files to create
-
-| File | Contents |
-|---|---|
-| `pipelex/tracing/event_log_protocol.py` | `EventLogProtocol` |
-| `pipelex/tracing/ndjson_event_log.py` | `NdjsonEventLog` implementation |
-| `pipelex/tracing/in_memory_event_log.py` | `InMemoryEventLog` for tests |
-| `tests/unit/pipelex/tracing/test_ndjson_event_log.py` | Emit/read/cleanup/dedup tests |
-
-### Checklist
-
-- [x] Define `EventLogProtocol`
-- [x] Implement `NdjsonEventLog` write path (emit with file handle caching)
-- [x] Implement `NdjsonEventLog` read path (glob, parse, deduplicate, sort)
-- [x] Implement `NdjsonEventLog` cleanup
-- [x] Implement `InMemoryEventLog`
-- [x] Test: emit events, read them back, verify order and content
-- [x] Test: emit duplicate events (same workflow_id + sequence), verify deduplication
-- [x] Test: emit from "multiple workers" (different workflow_ids), verify all events returned
-- [x] Test: cleanup removes directory
-- [x] Test: read from nonexistent run returns empty list
-- [x] Test: corrupt NDJSON line (truncated JSON) is skipped with warning
-- [x] Test: multiprocess concurrent writes — spawn workers writing to the same traces_dir (different files), verify no corruption or directory race conditions
-- [x] `make agent-check` passes
-- [x] `make agent-test` passes (existing tests unaffected)
-
----
-
-## Step 2: GraphSpec Assembler
-
-> Reconstructs a `GraphSpec` from trace events. This is the core algorithm — equivalent to `GraphTracer.teardown()` but working from events instead of in-memory state.
-
-### What
-
-The assembler reads a flat list of `TraceEvent` objects and produces a `GraphSpec`. It must reproduce the same graph that the current `GraphTracer` produces for identical executions. This is the correctness benchmark.
-
-### Algorithm outline
-
-The assembler uses a **two-pass** approach, mirroring `GraphTracer.teardown()` which builds all nodes first, then generates edges. This is critical for cross-worker correctness: events from different workflows arrive in arbitrary order (sorted by `(workflow_id, sequence)` which is alphabetical, not causal). The two-pass approach ensures the complete producer map is built before any edge generation, regardless of which workflow produced or consumed a given stuff.
-
-**Pass 1 — Build nodes and producer map** (process all events):
-
-1. **Build nodes** from `PipeStartEvent` + `PipeEndSuccessEvent`/`PipeEndErrorEvent`:
- - `PipeStartEvent` → create `NodeSpec` with status=RUNNING, record input_specs
- - `PipeEndSuccessEvent` → update status=SUCCEEDED, set timing, record output_spec
- - `PipeEndErrorEvent` → update status=FAILED, set timing and error
- - Unmatched `PipeStartEvent` (no end event) → status=CANCELED (same as current `teardown()`)
-
-2. **Collect explicit edges** from `EdgeEvent`:
- - CONTAINS edges (parent → child) are emitted at pipe start time
- - SELECTED_OUTCOME edges from PipeCondition
-
-3. **Build producer map** from `PipeEndSuccessEvent` + `ControllerOutputEvent`:
- - Track `stuff_code → node_id` (same as `_stuff_producer_map` in current tracer)
- - `ControllerOutputEvent` overrides the producer (same as `register_controller_output()`)
- - Pass-through detection: skip if output digest matches an input digest (must mirror `GraphTracer.on_pipe_end_success()` lines 477-488 exactly)
-
-4. **Collect batch/parallel metadata** from `BatchItemEvent`, `BatchAggregateEvent`, `ParallelCombineEvent`:
- - Store for edge generation in Pass 2
-
-**Pass 2 — Generate all edges** (using the complete producer map):
-
-5. **Generate DATA edges** from producer map + node inputs:
- - Same algorithm as `GraphTracer._generate_data_edges()` — for each node's inputs, find the producer by digest, create DATA edge
-
-6. **Generate BATCH_ITEM edges** from `BatchItemEvent`:
- - Same algorithm as `GraphTracer._generate_batch_item_edges()`
-
-7. **Generate BATCH_AGGREGATE edges** from `BatchAggregateEvent`:
- - Same algorithm as `GraphTracer._generate_batch_aggregate_edges()`
-
-8. **Generate PARALLEL_COMBINE edges** from `ParallelCombineEvent`:
- - `ParallelCombineEvent` carries the snapshotted branch producer node IDs (same as `register_parallel_combine()` snapshots `_stuff_producer_map` before override)
- - Same algorithm as `GraphTracer._generate_parallel_combine_edges()`
-
-### Usage aggregator
-
-Simpler — just collects `UsageReportEvent` objects:
-
-```python
-class UsageAggregator:
- @staticmethod
- def aggregate(events: list[TraceEvent]) -> list[TokensUsage]:
- return [e.tokens_usage for e in events if isinstance(e, UsageReportEvent)]
-```
-
-Per-step attribution is already available since `UsageReportEvent` carries `node_id`.
-
-### Correctness strategy
-
-The assembler must produce a `GraphSpec` that is **structurally identical** to what the current `GraphTracer` produces. To verify:
-
-1. Existing unit tests for graph tracing (`tests/unit/pipelex/graph/`) produce known-good GraphSpecs
-2. Write a test adapter that runs the same scenario through both paths:
- - Path A: current `GraphTracer` (in-memory only, no event log)
- - Path B: `GraphTracer` with event log enabled → emit events → assembler → GraphSpec
-3. Compare the two GraphSpecs using **structural equivalence**:
- - Same number of nodes, same `NodeStatus` per node, same `pipe_code` per node
- - Same number of edges, same `EdgeKind` between corresponding nodes
- - Same `IOSpec` digests on inputs/outputs
- - **Normalize IDs**: Strip the workflow_id segment from node/edge IDs (e.g., `graph_1:wf_abc:node_0` → `graph_1:node_0`) for comparison
- - **Ignore `TimingSpec`**: Timestamps will differ between the two paths
- - **Ignore edge ordering**: Compare edges as sets (by kind + source + target after ID normalization)
-
-This is the **most important testing step** — it catches any divergence between the event-based and in-memory paths.
-
-### Files to create
-
-| File | Contents |
-|---|---|
-| `pipelex/tracing/graphspec_assembler.py` | `GraphSpecAssembler.assemble(events) -> GraphSpec` |
-| `pipelex/tracing/usage_aggregator.py` | `UsageAggregator.aggregate(events) -> list[TokensUsage]` |
-| `tests/unit/pipelex/tracing/test_graphspec_assembler.py` | Hand-crafted event sequences → expected GraphSpec |
-| `tests/unit/pipelex/tracing/test_usage_aggregator.py` | Usage event aggregation tests |
-
-### Checklist
-
-- [x] Implement `GraphSpecAssembler.assemble()` — node construction from start/end events
-- [x] Implement CONTAINS edge reconstruction (from EdgeEvent with CONTAINS kind)
-- [x] Implement producer map construction (from PipeEndSuccessEvent + ControllerOutputEvent)
-- [x] Implement pass-through detection (output digest in input digests → skip producer registration)
-- [x] Implement DATA edge generation (digest correlation, same algorithm as `GraphTracer._generate_data_edges()`)
-- [x] Implement BATCH_ITEM edge generation from `BatchItemEvent`
-- [x] Implement BATCH_AGGREGATE edge generation from `BatchAggregateEvent`
-- [x] Implement PARALLEL_COMBINE edge generation from `ParallelCombineEvent`
-- [x] Handle CANCELED nodes (PipeStartEvent without matching end event)
-- [x] Implement `UsageAggregator`
-- [x] Test: simple sequence (3 pipes in order) → correct nodes, CONTAINS edges, DATA edges
-- [x] Test: parallel branches → correct PARALLEL_COMBINE edges
-- [x] Test: batch fan-out/fan-in → correct BATCH_ITEM + BATCH_AGGREGATE edges
-- [x] Test: condition with selected outcome → correct SELECTED_OUTCOME edge
-- [x] Test: partial failure (PipeStartEvent + PipeEndErrorEvent, no end for parent) → FAILED + CANCELED nodes
-- [x] Test: events from multiple workflows (different workflow_id prefixes) assemble correctly
-- [x] Test: cross-workflow producer map — producer in alphabetically-later workflow_id, consumer in earlier one (validates two-pass assembly ordering)
-- [x] Test: usage aggregation collects all UsageReportEvent records
-- [x] Equivalence test: compare assembler output with current GraphTracer output using structural equivalence (normalized IDs, ignored TimingSpec)
-- [x] `make agent-check` passes
-
----
-
-## Step 3: Emit Integration (Dual-Write in GraphTracer)
-
-> Add event emission to the existing GraphTracer. Zero changes to call sites.
-
-### What
-
-Add an optional `EventLogProtocol` to `GraphTracer`. When set, every tracing method (`on_pipe_start`, `on_pipe_end_success`, etc.) emits a `TraceEvent` as a side effect **in addition to** the existing in-memory accumulation. No new tracer class, no new hub functions, no call site changes.
-
-### Why this approach (not a separate EventLogTracerManager)
-
-The original plan proposed a parallel `EventLogTracerManager` class matching `GraphTracerManager`'s interface. The engineering review identified that this was overbuilt:
-- `GraphTracer` already maintains `_stuff_producer_map` — the `ParallelCombineEvent` snapshotting comes for free
-- `GraphTracer` already has the pass-through detection logic — no risk of drift
-- No need for a `TracerManagerProtocol` — `GraphTracerManager` is the only manager
-- No need for `get_tracer_manager()` hub function — `GraphTracerManager.get_instance()` works as before
-- `pipe_abstract.py` and all controllers: **zero changes**
-
-### Changes to `GraphTracer`
-
-Add two new fields:
-```python
-class GraphTracer(GraphTracerProtocol):
- _event_log: EventLogProtocol | None # None = no event emission (direct mode)
- _workflow_id: str # "direct" for direct mode, full Temporal workflow ID otherwise
-```
-
-In `setup()`: accept optional `event_log` and `workflow_id` params. Store them.
-
-In each tracing method, add event emission **after** the existing in-memory logic:
-
-| Method | Existing logic (unchanged) | Event emission (new, when `_event_log is not None`) |
-|---|---|---|
-| `on_pipe_start()` | Create `_MutableNodeData`, add CONTAINS edge, return `(node_id, child_context)` | Emit `PipeStartEvent` + `EdgeEvent(CONTAINS)` if parent |
-| `on_pipe_end_success()` | Update node status/timing, register producer, pass-through detection | Emit `PipeEndSuccessEvent` |
-| `on_pipe_end_error()` | Update node status/timing/error | Emit `PipeEndErrorEvent` |
-| `add_edge()` | Create `EdgeSpec`, append to `_edges` | Emit `EdgeEvent` |
-| `register_controller_output()` | Append output_spec, update `_stuff_producer_map` | Emit `ControllerOutputEvent` |
-| `register_batch_item_extraction()` | Update `_batch_item_map` | Emit `BatchItemEvent` |
-| `register_batch_aggregation()` | Update `_batch_aggregate_map` | Emit `BatchAggregateEvent` |
-| `register_parallel_combine()` | Snapshot producers, update `_parallel_combine_map` | Emit `ParallelCombineEvent` with snapshotted branch producer IDs |
-
-The `ParallelCombineEvent` carries the snapshotted branch producer node IDs directly from `_stuff_producer_map`, which `GraphTracer` already maintains. No additional state needed.
-
-### Node ID generation in Temporal mode
-
-When `_workflow_id` is not `"direct"`, node IDs are generated as `{graph_id}:{workflow_id}:node_{seq}` instead of `{graph_id}:node_{seq}`. The `_node_sequence` counter is per-tracer (per-workflow), starting at 0. Combined with the full `workflow_id`, this guarantees globally unique node IDs without coordination.
-
-Edge IDs follow the same scheme.
-
-### Changes to `GraphTracerManager`
-
-`open_tracer()` gains two optional params:
-```python
-def open_tracer(
- self,
- graph_id: str,
- data_inclusion: DataInclusionConfig,
- pipeline_ref_domain: str | None = None,
- pipeline_ref_main_pipe: str | None = None,
- event_log: EventLogProtocol | None = None, # NEW
- workflow_id: str = "direct", # NEW
-) -> GraphContext:
-```
-
-These are passed through to `GraphTracer.setup()`. In direct mode, callers omit them (defaults apply). In Temporal mode, `WfPipeRouter` provides them.
-
-### How pipe_abstract.py changes
-
-**It doesn't.** The existing code continues to call `GraphTracerManager.get_instance()`, which routes to the `GraphTracer` for the current `graph_id`. The `GraphTracer` internally decides whether to emit events based on `_event_log`. Call sites are completely unaware of event emission.
-
-### Reporting integration (usage events from activities)
-
-Usage events (`UsageReportEvent`) are emitted from inference workers (e.g., `llm_worker_abstract.py:334`), which run as Temporal **activities**, not inside the workflow. Activities run on specific worker processes and do NOT share the workflow's async context or ContextVars.
-
-**Approach for local filesystem**: Activities receive the event_log config (`traces_dir`, `pipeline_run_id`) as part of their input. Each activity creates its own `NdjsonEventLog` instance and emits `UsageReportEvent` to its own file (keyed by a unique activity identifier, e.g., `act_{activity_id}.ndjson`). The assembler reads all `*.ndjson` files in the pipeline run directory, including activity files.
-
-**Changes to ReportingManager**: Add an optional `event_log` field. When set, `report_inference_job()` emits a `UsageReportEvent` in addition to the existing local accumulation. For activities, the `event_log` is set from the activity input config.
-
-### Files to modify
-
-| File | Change |
-|---|---|
-| `pipelex/graph/graph_tracer.py` | Add `_event_log`, `_workflow_id` fields; emit events in all tracing methods |
-| `pipelex/graph/graph_tracer_manager.py` | Add `event_log`, `workflow_id` params to `open_tracer()` |
-| `pipelex/reporting/reporting_manager.py` | Add optional `event_log` field, emit `UsageReportEvent` in `report_inference_job()` |
-
-**What does NOT change**:
-- `pipelex/core/pipes/pipe_abstract.py` — zero changes
-- `pipelex/pipe_controllers/parallel/pipe_parallel.py` — zero changes
-- `pipelex/pipe_controllers/batch/pipe_batch.py` — zero changes
-- `pipelex/hub.py` — no new ContextVars needed
-
-### Checklist
-
-- [x] Add `_event_log` and `_workflow_id` fields to `GraphTracer`
-- [x] Update `GraphTracer.setup()` to accept `event_log` and `workflow_id` params
-- [x] Add event emission to `on_pipe_start()` (PipeStartEvent + EdgeEvent for CONTAINS)
-- [x] Add event emission to `on_pipe_end_success()` (PipeEndSuccessEvent)
-- [x] Add event emission to `on_pipe_end_error()` (PipeEndErrorEvent)
-- [x] Add event emission to `add_edge()` (EdgeEvent)
-- [x] Add event emission to `register_controller_output()` (ControllerOutputEvent)
-- [x] Add event emission to `register_batch_item_extraction()` (BatchItemEvent)
-- [x] Add event emission to `register_batch_aggregation()` (BatchAggregateEvent)
-- [x] Add event emission to `register_parallel_combine()` (ParallelCombineEvent with snapshotted producers)
-- [x] Update node ID generation when `_workflow_id != "direct"` to include workflow_id segment
-- [x] Update edge ID generation similarly
-- [x] Update `GraphTracerManager.open_tracer()` to accept and pass through `event_log`, `workflow_id`
-- [x] Add optional `event_log` to `ReportingManager`, emit `UsageReportEvent` in `report_inference_job()`
-- [x] Test: GraphTracer with event_log emits correct events for a pipe start/end cycle
-- [x] Test: CONTAINS edge event emitted when parent_node_id is present
-- [x] Test: GraphTracer without event_log (direct mode) works exactly as before
-- [x] Test: controller output registration emits `ControllerOutputEvent`
-- [x] Test: parallel combine emits `ParallelCombineEvent` with correct snapshotted producer IDs
-- [x] Test: ReportingManager emits `UsageReportEvent` when event_log is set
-- [x] `make agent-check` passes
-
----
-
-## Step 4: Wire into Pipeline Lifecycle
-
-> Connect event log initialization/finalization to the pipeline run lifecycle and Temporal workflow lifecycle.
-
-### What
-
-The event log must be created at the start of a Temporal pipeline run and read/assembled at the end. In direct mode, nothing changes — `GraphTracer` works without an event log as before.
-
-### Direct mode flow — UNCHANGED
-
-**No event log is initialized in direct mode.** The existing code path is preserved exactly:
-- `pipeline_run_setup.py` calls `GraphTracerManager.open_tracer()` as today (no `event_log` param → defaults to None)
-- `pipe_abstract.py` calls `GraphTracerManager.get_instance()` as today
-- `runner.py` calls `GraphTracerManager.close_tracer()` in the `finally` block as today
-- `ReportingManager` accumulates in memory as today (no `event_log` set → no emission)
-
-All existing tests pass without modification because the direct mode code path is identical.
-
-### Temporal mode flow
-
-**API process** (`pipeline_run_setup.py`):
-- When Temporal mode + graph enabled: create `NdjsonEventLog(traces_dir=tracing_config.traces_dir)`
-- Pass to `GraphTracerManager.open_tracer(event_log=event_log, workflow_id=...)`
-- The API process itself doesn't need the event_log on a ContextVar — it doesn't execute pipes
-
-**Worker process** (`WfPipeRouter.run()`):
-- Create `NdjsonEventLog` from tracing config (read from `pipelex.toml`, same pattern as other config)
-- Call `GraphTracerManager.get_or_create_instance()` then `open_tracer(event_log=event_log, workflow_id=workflow.info().workflow_id)`
-- Pipe execution proceeds as normal — `GraphTracer` dual-writes (in-memory + events)
-- No assembly on the worker — that's the API process's job
-
-**Assembly** (`runner.py` finally block):
-- After the Temporal workflow completes (or fails), the runner reads events and assembles:
-
-```python
-# runner.py finally block
-if graph_tracer_manager is not None:
- graph_spec_result = graph_tracer_manager.close_tracer(pipeline_run_id)
-
-if is_temporal_mode and event_log is not None:
- try:
- events = event_log.read_events(pipeline_run_id)
- graph_spec_result = GraphSpecAssembler.assemble(events)
- usage_data = UsageAggregator.aggregate(events)
- except Exception as exc:
- log.error(f"Failed to assemble graph from events: {exc}")
- # graph_spec_result stays as whatever close_tracer returned (local worker graph, or None)
-```
-
-**Key**: Both API and workers point to the same `traces_dir`. For local dev (same machine), this is a local filesystem path. For cloud, this would be replaced by DynamoDB (different backend, same protocol).
-
-### How `WfPipeRouter.run()` changes
-
-Current code opens a per-workflow library. Add event log setup in the same block:
-
-```python
-# After library crate setup, before pipe execution:
-if workflow_arg.job_metadata.graph_context is not None:
- try:
- event_log = NdjsonEventLog(traces_dir=tracing_config.traces_dir)
- graph_tracer_manager = GraphTracerManager.get_or_create_instance()
- graph_tracer_manager.open_tracer(
- graph_id=workflow_arg.job_metadata.graph_context.graph_id,
- data_inclusion=...,
- event_log=event_log,
- workflow_id=workflow.info().workflow_id,
- )
- except Exception as exc:
- log.warning(f"Failed to initialize event log tracing: {exc}")
- # Continue without event emission — tracing is a diagnostic tool,
- # it should not crash the workflow
-```
-
-**Important**: This must happen before `pipe.run_pipe()` but within the `workflow.unsafe.imports_passed_through()` block. Library setup must complete first (to have config available), then event log setup. The event log writes are side effects that happen during execution — Temporal replay will re-execute them, but the deduplication in `read_events()` handles this.
-
-### Usage events from activities
-
-Activities receive event_log config (`traces_dir`, `pipeline_run_id`) as part of their input (e.g., in `JobMetadata` or a dedicated config field). Each activity:
-1. Creates its own `NdjsonEventLog` instance
-2. Emits `UsageReportEvent` to its own file (e.g., `act_{activity_id}.ndjson`)
-3. The assembler reads all `*.ndjson` files in the pipeline run directory
-
-### Tracing config propagation
-
-Workers read `traces_dir` from `pipelex.toml` config (already loaded at worker startup). Same pattern as other config. The `pipeline_run_id` comes from `JobMetadata` (already available).
-
-### Graph output generation
-
-After assembly, the existing graph output pipeline (`graph_factory.py`, `generate_graph_outputs()`) works unchanged — it takes a `GraphSpec` and produces Mermaid/ReactFlow files. Renderers that parse node IDs must be updated to handle the `{graph_id}:{workflow_id}:node_{seq}` format (additional colon-separated segment).
-
-### Traces are never auto-deleted
-
-Traces persist on disk until explicitly removed by the user or a cleanup command. This ensures:
-- Traces are available for debugging if assembly fails
-- Usage reporting can run after graph generation (both read from the same event files)
-- No risk of deleting the only durable source of cross-worker data
-
-### Files to modify
-
-| File | Change |
-|---|---|
-| `pipelex/temporal/tprl_pipe/wf_pipe_router.py` | Create NdjsonEventLog, call `open_tracer(event_log=..., workflow_id=...)` |
-| `pipelex/pipeline/runner.py` | After Temporal workflow completes/fails: read events, assemble, defensive try/except |
-| `pipelex/pipeline/pipeline_run_setup.py` | Create NdjsonEventLog when Temporal mode + graph enabled, pass to `open_tracer()` |
-| `pipelex/system/configuration/configs.py` | Add `TracingConfig` with `traces_dir`, `enabled` |
-| `pipelex/pipelex.toml` | Add `[pipelex.tracing]` section |
-| Mermaid/ReactFlow renderers | Handle `{graph_id}:{workflow_id}:node_{seq}` node ID format |
-
-### Checklist
-
-- [x] Define `TracingConfig` and wire into main config
-- [x] Add `[pipelex.tracing_config]` to `pipelex.toml`
-- [x] Create NdjsonEventLog in `pipeline_run_setup.py` when Temporal mode + graph enabled
-- [x] Pass `event_log` and `workflow_id` to `GraphTracerManager.open_tracer()` in `pipeline_run_setup.py`
-- [x] Create NdjsonEventLog in `WfPipeRouter.run()`, call `open_tracer()` with event_log + workflow_id
-- [x] Defensive try/except around event log init in `WfPipeRouter` — continue without tracing on failure
-- [x] Read events + assemble GraphSpec in `runner.py` after Temporal workflow completes (or fails)
-- [x] Defensive try/except around assembly in `runner.py` — don't mask pipeline errors
-- [x] Feed assembled GraphSpec into existing graph output generation (`generate_graph_outputs()`)
-- [x] Read events + aggregate usage via `UsageAggregator` — in `runner.py`, calls `UsageAggregator.aggregate()` and `ReportingManager.inject_tokens_usages()` to feed cross-worker usage into the cost report
-- [x] ~~Wire activity-level usage event emission~~ → moved to Step 6
-- [x] Update Mermaid/ReactFlow renderers to handle new node ID format — NOT NEEDED (ReactFlow `.pop()` already handles extra segment, Mermaid uses IDs opaquely)
-- [x] Verify direct mode is completely unchanged — no event log initialized, `GraphTracer` works as today
-- [x] ~~Test (Temporal): graph via event log~~ → moved to Step 5
-- [x] ~~Test: usage report from events~~ → moved to Step 5
-- [x] Test: assembly failure is caught and logged, does not mask pipeline result — defensive try/except in runner.py:225 verified by code inspection + existing tests pass
-- [x] Test: event log init failure in WfPipeRouter does not crash the workflow — defensive try/except in wf_pipe_router.py:93-96 verified by code inspection
-- [x] `make agent-check` passes (1 pre-existing pyright error on `pipe_job.pipe.pipe_type` in runner.py, unrelated to tracing)
-- [x] `make agent-test` passes — all existing tests pass unchanged (direct mode untouched)
-
----
-
-## Step 5: Temporal Integration Tests
-
-> Validate that tracing works across Temporal workers. This is the end-to-end proof.
-
-### What
-
-Integration tests that run pipe controllers on Temporal workers and verify the assembled GraphSpec is complete and correct. These extend the existing Temporal integration tests in `tests/integration/pipelex/temporal/`.
-
-### Test scenarios
-
-Each test submits a pipeline to Temporal, waits for completion (or failure), reads events from the NDJSON event log, assembles a GraphSpec, and asserts on its structure.
-
-| Scenario | What it validates |
-|---|---|
-| PipeSequence (LLM steps via Temporal) | Nodes from multiple workers, CONTAINS edges, DATA edges across workers |
-| PipeParallel (branches on different workers) | PARALLEL_COMBINE edges, concurrent worker event files |
-| PipeBatch (fan-out to workers) | BATCH_ITEM + BATCH_AGGREGATE edges across workers |
-| Pipeline failure (LLM step fails) | Partial graph: FAILED node, CANCELED parent, usage still captured |
-| Usage reporting | Token costs aggregated across workers (via activity-emitted events) |
-| Two-pass assembly ordering | Producer in alphabetically-later workflow, consumer in earlier one — validates the assembler doesn't depend on event file ordering |
-| Dry-run with graph | Same structure but with StuffArtefact (if fixed) or xfail |
-
-### Reuse existing test infrastructure
-
-The `tests/integration/pipelex/temporal/library_crate/` directory already has `.mthds` bundles and test infrastructure for Temporal integration tests. Extend with graph tracing assertions.
-
-### Checklist
-
-- [x] Test: PipeSequence through Temporal produces correct GraphSpec (nodes, CONTAINS, DATA edges) — `test_wf_graph_tracing_sequence.py`
-- [x] Test: PipeParallel through Temporal produces correct CONTAINS and DATA edges — `test_wf_graph_tracing_parallel.py`
-- [x] Test: PipeBatch through Temporal produces BATCH_ITEM and BATCH_AGGREGATE edges — `test_wf_graph_tracing_batch.py`
-- [x] Test: events from multiple workers are in separate NDJSON files — `test_parallel_produces_multiple_ndjson_files`
-- [x] Test: deduplication handles Temporal replay (emit same events twice, assembler produces correct graph) — `test_ndjson_dedup_assembly.py`
-- [x] Test: pipeline failure produces partial graph with FAILED/CANCELED nodes — `test_partial_failure` in `test_graphspec_assembler.py`
-- [x] ~~Test: usage reporting works across Temporal workers~~ → moved to Step 6 (requires activity-level event emission)
-- [x] ~~Test: usage aggregation matches expected token counts~~ → moved to Step 6
-- [x] Test: graph output files (Mermaid, ReactFlow) generated correctly from assembled GraphSpec — `test_graph_output_generation.py`
-- [x] Test: two-pass assembly handles cross-workflow producer/consumer in arbitrary workflow_id order — `test_cross_workflow_producer_map` in `test_graphspec_assembler.py`
-- [x] Test: event log init failure in WfPipeRouter does not crash the workflow — defensive try/except verified in Step 4
-- [x] Test: assembly failure in runner.py is caught and logged — defensive try/except verified in Step 4
-- [x] `make agent-check` passes
-- [x] `make agent-test` passes (unit + non-Temporal integration tests)
-
----
-
-**Next steps**: See [wip/01-master-plan.md](wip/01-master-plan.md) for Step 6 (Standalone Activity Tracing), Phase 6 (Cross-Package Dependencies), and Future Phases.
-
-**Deferred items**: See [wip/deferred-items.md](wip/deferred-items.md).
-
-Implementation plan will be detailed when work begins. Key prerequisite: Phase 2 (crate propagation) is complete.
diff --git a/wip/archive/phase5-payload-codec-DONE.md b/wip/archive/phase5-payload-codec-DONE.md
deleted file mode 100644
index f3b55f959..000000000
--- a/wip/archive/phase5-payload-codec-DONE.md
+++ /dev/null
@@ -1,177 +0,0 @@
-# Phase 5: StoragePayloadCodec — Implementation Plan
-
-**Goal**: Remove the 2MB payload size limit for production workloads with large libraries or WorkingMemory containing images/documents.
-
-**Reference**: `wip/00-master-plan.md` lines 311-355, `wip/phase5-payload-codec-strategy.md`
-
----
-
-## Step 1: Add payload codec config to `config_temporal.py` + `pipelex.toml`
-
-**What**: Add a `PayloadCodecConfig` model to `config_temporal.py` and wire it into the `Temporal` config model. Add the corresponding TOML section.
-
-**Details**:
-
-- [x] Create `PayloadCodecConfig(ConfigModel)` with fields:
- - `is_enabled: bool` (default `false` in TOML)
- - `size_threshold: int` (default `1000000` = 1MB, well under the 2MB hard limit)
- - `storage_prefix: str` (default `"temporal-payloads/"`)
- - `storage_provider: str` (default `"local"` — matches existing `StorageProviderAbstract` implementations)
- - `storage_root_path: str` (default `".pipelex/temporal-payload-store"` — for `LocalStorageProvider`)
-- [x] Add `payload_codec_config: PayloadCodecConfig` field to `Temporal` config model
-- [x] Add `[temporal.payload_codec_config]` section to `pipelex/pipelex.toml` with defaults
-- [x] Run `make tb` to verify config loading doesn't break
-
-**Files**:
-- `pipelex/temporal/config_temporal.py` — add `PayloadCodecConfig`, add field to `Temporal`
-- `pipelex/pipelex.toml` — add `[temporal.payload_codec_config]` section
-
----
-
-## Step 2: Write unit tests for `StoragePayloadCodec` (RED)
-
-**What**: Write the unit tests *before* implementing the codec. These tests define the contract. They will fail (RED) until Step 3.
-
-**Details**:
-
-- [x] Create `tests/unit/pipelex/temporal/test_storage_payload_codec.py`
-- [x] One `TestStoragePayloadCodec` class with test cases:
- - [x] **Below threshold**: payload smaller than threshold passes through `encode()` unchanged. Verify `decode()` also passes it through.
- - [x] **Above threshold**: payload larger than threshold is replaced with a storage reference in `encode()`. Verify the reference payload has the correct encoding metadata (`b"binary/storage-ref"`). Verify `decode()` reconstructs the original payload exactly.
- - [x] **Content-addressed deduplication**: encoding the same large payload twice produces the same storage key. The storage provider should contain only one entry.
- - [x] **Mixed payloads**: a batch with both small and large payloads — small ones pass through, large ones are offloaded.
- - [x] **Round-trip fidelity**: `decode(encode(payloads))` returns identical payloads for various sizes.
-- Use `InMemoryStorageProvider` for unit tests (no filesystem needed)
-- Markers: no special markers needed (no LLM, no inference)
-- [x] Run tests — confirm they **fail** (import errors or assertion failures)
-
-**Files**:
-- `tests/unit/pipelex/temporal/test_storage_payload_codec.py` — **New**
-
----
-
-## Step 3: Implement `StoragePayloadCodec` (GREEN)
-
-**What**: Create the codec class that extends `temporalio.converter.PayloadCodec`. Implement until all unit tests from Step 2 pass.
-
-**Details**:
-
-- [x] Create `pipelex/temporal/storage_payload_codec.py`
-- [x] Implement `StoragePayloadCodec(PayloadCodec)` class:
- - Constructor takes a `StorageProviderAbstract` and config (threshold, prefix)
- - `async def encode(self, payloads: Sequence[Payload]) -> list[Payload]`:
- - For each payload, serialize to bytes via `payload.SerializeToString()`
- - If size < threshold, pass through unchanged
- - If size >= threshold: compute SHA256 of serialized bytes, use `prefix + hexdigest` as key, store via `storage_provider.store()` (note: `StorageProviderAbstract.store()` takes `data: bytes, key: str`), replace payload with a lightweight reference payload (metadata encoding = `b"binary/storage-ref"`, data = key bytes)
- - `async def decode(self, payloads: Sequence[Payload]) -> list[Payload]`:
- - For each payload, check if metadata encoding == `b"binary/storage-ref"`
- - If not, pass through unchanged
- - If yes, extract key from `payload.data.decode()`, download via `storage_provider.load()` (returns `bytes` via the URI scheme), reconstruct original `Payload` via `ParseFromString`
-- [x] Verify codec operates on raw protobuf `Payload` objects, *before* Kajson deserialization — no interaction with the deterministic layer
-- Note the existing `StorageProviderAbstract` uses a `pipelex-storage://` URI scheme for `store()`/`load()`. The codec should call `_store()` and `_load_with_metadata()` directly, or use the public `store()`/`load()` methods and handle the scheme accordingly. The simplest approach: use `store(data, key)` which returns a URI, and `load(uri)` which takes a URI. Store the URI (not just the key) in the reference payload.
-- [x] Run unit tests from Step 2 — confirm they **pass** (GREEN)
-
-**Files**:
-- `pipelex/temporal/storage_payload_codec.py` — **New**
-
----
-
-## Step 4: Write integration test for large payload round-trip (RED)
-
-**What**: Write the integration test *before* wiring the codec into the DataConverter/client/worker. This test defines the end-to-end contract. It will fail (RED) until Steps 5–7 complete the wiring.
-
-**Details**:
-
-- [x] Create `tests/integration/pipelex/temporal/test_payload_codec_roundtrip.py`
-- [x] Implement `TestPayloadCodecRoundTrip` class with test workflow:
- - [x] Workflow accepts a large Pydantic model (e.g., a WorkingMemory-like object with a large bytes field > 1MB), passes it to an activity, returns it
- - [x] Verify the output matches the input exactly
-- Tests the full chain: client encode -> server stores ref -> worker decode -> activity processes -> worker encode -> server stores ref -> client decode
-- Use the in-process test server (`--temporal-server none`) for CI compatibility
-- Use `LocalStorageProvider` with a `tmp_path` fixture for the storage root
-- Markers: `@pytest.mark.asyncio(loop_scope="class")`
-- [x] Run test — confirm it **passes** (GREEN, wired simultaneously with Steps 5-7)
-
-**Files**:
-- `tests/integration/pipelex/temporal/test_payload_codec_roundtrip.py` — **New**
-
----
-
-## Step 5: Wire codec into `DataConverter`
-
-**What**: Modify `temporal_data_converter.py` to optionally attach the `StoragePayloadCodec` to the `DataConverter`.
-
-**Details**:
-
-- [x] Add a factory function `make_data_converter(payload_codec: PayloadCodec | None = None) -> DataConverter` that creates the converter with the optional codec
-- [x] Wire `DataConverter` constructor to accept `payload_codec` parameter — passed directly to `DataConverter(payload_codec=...)`
-- [x] Keep the existing module-level `data_converter` for backward compatibility (no codec) — now uses `make_data_converter()` with no args
-- The current module-level `data_converter` uses `DataConverter(payload_converter_class=PydanticCompositePayloadConverter)` but no `payload_codec`
-- The same data converter (with same codec) must be used on both client and worker sides
-
-**Files**:
-- `pipelex/temporal/temporal_data_converter.py` — add factory function
-
----
-
-## Step 6: Wire codec into client connection (`temporal_connect.py`)
-
-**What**: Pass the codec-enabled `DataConverter` to `TemporalClient.connect()`.
-
-**Details**:
-
-- [x] In `connect_to_temporal_server()`, read `PayloadCodecConfig` from config
-- [x] If `payload_codec_config.is_enabled`:
- - Instantiate the appropriate `StorageProviderAbstract` based on config (V1: `LocalStorageProvider`)
- - Create `StoragePayloadCodec` with the provider and config
- - Create `DataConverter` via the new factory with the codec
-- [x] If not enabled, use the existing codec-free converter
-- [x] Pass the converter to `TemporalClient.connect(data_converter=...)`
-
-**Files**:
-- `pipelex/temporal/temporal_connect.py` — conditional codec instantiation
-
----
-
-## Step 7: Wire codec into worker + verify integration test (GREEN)
-
-**What**: Ensure the worker uses the same codec-enabled `DataConverter`, then confirm the integration test from Step 4 passes.
-
-**Details**:
-
-- [x] Verify worker gets codec-enabled converter from `connect_to_temporal()` (already passes data converter to client)
-- [x] Check if `Worker` constructor in `make_worker()` needs explicit `data_converter` — confirmed: `Worker` inherits from the client automatically, no explicit passing needed
-- [x] Run integration test from Step 4 — confirmed **passes** (GREEN)
-
-**Files**:
-- `pipelex/temporal/temporal_task_manager.py` — potentially pass `data_converter` to `Worker`
-- `pipelex/temporal/worker_cli.py` — no changes expected if client handles it
-
----
-
-## Step 8: Lint and full test suite
-
-**What**: Run `make agent-check` and `make agent-test` to verify everything passes.
-
-- [x] `make agent-check` passes
-- [x] `make agent-test` — all non-temporal-integration tests pass; temporal integration tests have pre-existing singleton crash (unrelated to Phase 5)
-
----
-
-## Done Criteria
-
-- [x] `PayloadCodecConfig` in config model and `pipelex.toml`
-- [x] `StoragePayloadCodec` class with `encode()`/`decode()`
-- [x] Codec wired into `DataConverter`, client, and worker
-- [x] Unit test: payloads above threshold are stored externally, below threshold pass through
-- [x] Unit test: content-addressed deduplication works
-- [x] Integration test: large payload survives Temporal round-trip
-- [x] `make agent-check` passes
-- [x] `make agent-test` — passes (pre-existing singleton crash in other temporal integration tests is unrelated)
-
-## Dependencies / Risks
-
-- **StorageProviderAbstract is async**: The `PayloadCodec.encode()`/`decode()` methods are also async, so this is compatible.
-- **Protobuf serialization**: `Payload.SerializeToString()` / `ParseFromString()` are standard protobuf operations — well-tested.
-- **Codec + Kajson ordering**: The codec operates on raw protobuf before Kajson deserialization. The existing deferred deserialization (Layer 1 timing) is unaffected. No ordering issues expected.
-- **Future migration**: When Temporal ships native `ExternalStorage`/`StorageDriver`, we swap the custom codec for the built-in. Minimal changes since the storage interface is similar.
diff --git a/wip/archive/phase5-payload-codec-strategy.md b/wip/archive/phase5-payload-codec-strategy.md
deleted file mode 100644
index b727f85b5..000000000
--- a/wip/archive/phase5-payload-codec-strategy.md
+++ /dev/null
@@ -1,230 +0,0 @@
-# Temporal Payload Codec Strategy: Transparent Large Payload Offloading
-
-> **Status**: Draft
-> **Date**: 2026-03-23
-> **Related**: [archive/early-temporal-library-fix-proposals.md](archive/early-temporal-library-fix-proposals.md), [archive/early-library-as-execution-context.md](archive/early-library-as-execution-context.md)
-
----
-
-## 1. The Payload Size Problem
-
-Temporal imposes a **2MB limit per individual payload** (each argument and return value) and a 4MB gRPC message limit. Two things in our architecture can exceed this:
-
-- **Library context**: The collection of concepts and pipes needed for execution. Can be arbitrarily large depending on the library.
-- **Working memory**: Runtime data being processed. Can include images, documents, and other large payloads.
-
-This limit applies **equally to workflows and activities** — every individual input argument and output return value is capped. Moving data into activities does not escape the limit; it just relocates it.
-
----
-
-## 2. Why Activities for Upload/Download Don't Work
-
-The naive approach:
-
-> "Put the large data in external storage. Use an activity to upload before dispatching, and another activity to download on the worker."
-
-This fails for two reasons:
-
-1. **Activities have the same 2MB per-payload limit.** An activity that returns the library context as its output hits the same cap. You've moved the problem back one step without solving it.
-
-2. **Workflow code must be deterministic.** You can't do storage I/O directly in workflow `run()` methods. So you're forced into activities, which circles back to problem 1.
-
----
-
-## 3. The Solution: PayloadCodec
-
-Temporal's `PayloadCodec` operates at the **wire boundary** — outside the workflow sandbox, outside determinism rules, outside the payload size problem entirely.
-
-### How it works
-
-`PayloadCodec` intercepts every payload going to and from the Temporal server. It sits between your application code and the gRPC transport:
-
-```
-Application code PayloadCodec Temporal Server
-─────────────── ──────────── ───────────────
-pass WorkingMemory (50MB) ──► encode(): upload to S3, ──► stores small S3 ref
- replace with S3 key ref in Event History
-
-receive S3 ref ◄── decode(): download from S3, ◄── reads S3 ref from
-return WorkingMemory (50MB) reconstruct original payload Event History
-```
-
-The codec has two methods:
-
-- **`encode(payloads)`**: Called on every outbound payload. If a payload exceeds a size threshold, upload it to external storage and replace it with a lightweight reference.
-- **`decode(payloads)`**: Called on every inbound payload. If a payload is a storage reference, download the real data and reconstruct the original payload.
-
-### Why it's transparent
-
-Application code never changes. Workflows and activities pass `PipeJob`, `WorkingMemory`, `LibraryContext` — whatever size — as normal arguments. The codec handles offloading invisibly. No explicit upload/download logic anywhere in the business layer.
-
-### Why it doesn't violate determinism
-
-The codec runs **outside the workflow sandbox**. It is not subject to deterministic replay rules. Temporal's documentation and community discussions confirm:
-
-- `PayloadCodec` does **not** need to be deterministic (unlike `PayloadConverter`, which runs inside the sandbox).
-- The **encoded** form (the storage reference) is what gets stored in Event History.
-- During **replay**, the worker receives encoded payloads from history and calls `decode()` again — so downloads happen during replay too.
-- This is safe because the codec operates before/after the deterministic layer, and content-addressed storage (SHA256 key) guarantees the same key always returns the same data.
-
-### Retention requirement
-
-Since `decode()` is called during replay, the external storage must **retain offloaded payloads for the workflow's retention period**. If a workflow has a 30-day retention, the S3 objects must live at least 30 days.
-
----
-
-## 4. Implementation Sketch (Python SDK)
-
-```python
-from typing import Sequence
-
-from temporalio.api.common.v1 import Payload
-from temporalio.converter import PayloadCodec
-
-ENCODING_STORAGE_REF = b"binary/storage-ref"
-SIZE_THRESHOLD = 1_000_000 # 1 MB — well under the 2 MB hard limit
-
-class StoragePayloadCodec(PayloadCodec):
- """Offloads large payloads to external storage, replacing them with references."""
-
- def __init__(self, storage_provider: StorageProvider, prefix: str = "temporal-payloads/") -> None:
- self._storage = storage_provider
- self._prefix = prefix
-
- async def encode(self, payloads: Sequence[Payload]) -> list[Payload]:
- result: list[Payload] = []
- for payload in payloads:
- serialized = payload.SerializeToString()
- if len(serialized) < SIZE_THRESHOLD:
- result.append(payload)
- continue
- # Content-addressed: same data → same key → natural dedup
- key = self._prefix + sha256(serialized).hexdigest()
- await self._storage.upload(key, serialized)
- result.append(
- Payload(
- metadata={"encoding": ENCODING_STORAGE_REF},
- data=key.encode(),
- )
- )
- return result
-
- async def decode(self, payloads: Sequence[Payload]) -> list[Payload]:
- result: list[Payload] = []
- for payload in payloads:
- if payload.metadata.get("encoding") != ENCODING_STORAGE_REF:
- result.append(payload)
- continue
- key = payload.data.decode()
- original_bytes = await self._storage.download(key)
- original_payload = Payload()
- original_payload.ParseFromString(original_bytes)
- result.append(original_payload)
- return result
-```
-
-Registration on both client and worker:
-
-```python
-import dataclasses
-import temporalio.converter
-
-codec = StoragePayloadCodec(storage_provider=my_storage_provider)
-
-data_converter = dataclasses.replace(
- temporalio.converter.default(),
- payload_codec=codec,
-)
-
-# Client side
-client = await Client.connect("temporal-host:7233", data_converter=data_converter)
-
-# Worker side — same data_converter
-worker = Worker(client, task_queue="pipelex", data_converter=data_converter, ...)
-```
-
-The same `data_converter` (with the same codec) must be used on both the client and the worker. This is how `encode()` on the client side and `decode()` on the worker side stay in sync.
-
----
-
-## 5. How This Simplifies the v2 Architecture
-
-The v2 proposals ([archive/early-temporal-library-fix-proposals.md](archive/early-temporal-library-fix-proposals.md)) identified several concerns around payload size. Here's how the codec approach resolves them:
-
-| v2 concern | Without codec | With codec |
-|---|---|---|
-| `LibraryContext` too large for workflow input | Must chunk, compress, or externalize manually | Transparent — pass it as a normal field |
-| `WorkingMemory` with images exceeding 2MB | Explicit upload/download activities needed | Transparent — pass it as a normal argument |
-| `raw_pipe_job_payload` size in `TemporalPipeJobEnvelope` | Must manage size carefully | Size is irrelevant — codec handles it |
-| Need for explicit storage upload/download activities | Yes — adds complexity and latency | **No** — codec handles all byte-moving |
-| Storage provider integration | Activity-level, per-workflow | Codec-level, once, for all workflows |
-
-### What remains from v2
-
-The codec solves the **payload size** problem. It does **not** solve the **library loading** problem. These are distinct:
-
-- **Payload size**: "How do we get large data through Temporal's wire protocol?" → Codec.
-- **Library loading**: "How do we get concepts and pipes registered in the worker's Python process before deserialization?" → Still needs the v2 approach (worker startup loading + deferred deserialization + `act_library_setup` activity).
-
-The v2's `act_library_setup` activity is still required, but its job simplifies:
-
-- **Before codec**: Responsible for both fetching library data AND loading it into the process.
-- **After codec**: Only responsible for **loading the library into the process** (generating dynamic classes, populating the registry). The data arrives transparently through the codec.
-
-The `TemporalPipeJobEnvelope` with deferred deserialization (v2 Option D) is still needed for the Layer 1 timing problem — dynamic classes must be registered before Kajson can deserialize the `PipeJob`. But the envelope's `library_context` field can now be arbitrarily large without concern.
-
----
-
-## 6. Codec Server (for Observability)
-
-Separately from the SDK-level `PayloadCodec`, Temporal supports a **Codec Server** — a standalone HTTP service that enables the Web UI and CLI to decode payloads for display.
-
-| Aspect | SDK PayloadCodec | Codec Server |
-|---|---|---|
-| What it is | Class in your application code | Standalone HTTP service |
-| Where it runs | Embedded in client and worker processes | Separate infrastructure |
-| Purpose | Transparent encode/decode for all payloads | Enable Web UI and CLI to display decoded data |
-| Endpoints | N/A (in-process) | `POST /encode` and `POST /decode` |
-| Required? | Yes — for transparent offloading | Optional — for observability only |
-
-The Codec Server typically runs the same codec logic. If we offload to S3, the Codec Server needs S3 access to decode payloads for display in the Temporal Web UI. This is a nice-to-have, not a blocker.
-
----
-
-## 7. Future: Temporal's Native ExternalStorage
-
-Temporal has an `ExternalStorage` / `StorageDriver` API in development that formalizes exactly this pattern:
-
-```python
-# NOT YET RELEASED — seen in API docs but not in temporalio 1.23.0
-ExternalStorage(
- drivers=[my_s3_driver],
- payload_size_threshold=256 * 1024, # default 256 KiB
- driver_selector=my_selector_fn,
-)
-```
-
-The `StorageDriver` interface requires `store()` and `retrieve()` methods — essentially what our custom codec does. When this ships, we migrate from our custom `PayloadCodec` to the built-in `ExternalStorage` with minimal changes.
-
-**Action**: Monitor `temporalio` releases for `ExternalStorage` availability. Until then, the custom `PayloadCodec` approach is the officially recommended pattern.
-
----
-
-## 8. Integration with Pipelex Storage Providers
-
-Our `StoragePayloadCodec` should use Pipelex's existing storage provider system rather than hardcoding S3. This means:
-
-- The codec's storage backend is configured through Pipelex's standard configuration
-- The same storage provider that handles other Pipelex storage needs handles temporal payload offloading
-- Switching from S3 to GCS or another backend requires no codec changes
-
-The codec is instantiated during Temporal client/worker setup, reading the storage provider configuration from Pipelex's config system.
-
----
-
-## 9. Open Questions
-
-- **Content-addressed dedup**: Using SHA256 of the payload as the storage key gives us natural deduplication — if the same library context is sent across multiple workflow runs, it's stored once. Is this sufficient, or do we need explicit cache management?
-- **Cleanup policy**: S3 objects must outlive the workflow retention period. Should we use S3 lifecycle rules, or implement explicit garbage collection tied to workflow completion?
-- **Threshold tuning**: 1MB is a safe default (well under the 2MB hard limit, leaving room for metadata). Should this be configurable per deployment?
-- **Codec + Kajson interaction**: The codec operates on raw `Payload` protobuf objects, before Kajson deserialization. This means the Layer 1 timing problem (dynamic class registration) is unaffected by the codec — deferred deserialization is still needed. Confirm this doesn't introduce any ordering issues.
diff --git a/wip/archive/pr-943-review-agents-triage.md b/wip/archive/pr-943-review-agents-triage.md
deleted file mode 100644
index 683136ecd..000000000
--- a/wip/archive/pr-943-review-agents-triage.md
+++ /dev/null
@@ -1,97 +0,0 @@
-# PR #943 — review-agent comment triage and fixes
-
-**Status:** code complete, uncommitted, **PR-thread replies/resolves not posted yet** (user-directed hold).
-
-**PR:** <https://github.com/Pipelex/pipelex/pull/943>
-**Branch:** `feature/API-readiness-2` (post-merge-from-`dev` state, merge commit `8a1dd8cc`).
-**Date:** 2026-05-27.
-
-## Why this work happened
-
-Three unresolved review-agent threads on PR #943:
-
-| # | File:line | Reporter | Severity |
-|---|---|---|---|
-| 1 | `pipelex/temporal/tprl/temporal_error.py:15` | chatgpt-codex-connector | P2 |
-| 2 | `pipelex/pipeline/validate_bundle.py:203` | greptile-apps | P1 |
-| 3 | `pipelex/temporal/tprl_pipe/act_deliver.py:19` | greptile-apps | P2 |
-
-The user invoked `/review-pr-agents` with the explicit instruction: *no backward compatibility, especially for Temporal* — which directly governs the verdict on #1.
-
-## Verdicts
-
-### #1 — Codex: "Restore recovery of old Temporal error reports"
-
-**False positive (by policy).** Codex flagged that `_ERROR_REPORT_REQUIRED_KEYS` (the marker set in `error_report_dict_from_details`) now requires `title` and `type_uri` alongside `error_type` and `message`, which would break recovery of in-flight workflows produced by a previous pipelex release during a rolling deploy.
-
-This is exactly the backward-compatibility shape the user rejects, and the branch's own ground rules already document this stance — `_for_api/TODOS.md` "Ground rules" says: *"No backward-compat shims. The Temporal integration has never shipped — there is no prior on-wire schema to preserve."* Memory entry `[[project_temporal_not_shipped]]` reinforces it.
-
-No code change. Will reply with rationale + resolve.
-
-### #2 — Greptile: "Current library lost"
-
-**Confirmed (P1).** When a validation entry point runs inside a caller's outer current-library scope and then fails, the `finally` block calls `teardown_current_library()`, which **clears** the ContextVar entirely — clobbering the outer scope. The next `get_current_library()` in the same async context raises `RuntimeError: No current library set`.
-
-The bug is at four sites in `pipelex/pipeline/validate_bundle.py`: `validate_bundle`, `validate_bundles_from_directory`, `load_concepts_only`, `load_concepts_only_from_directory`. A 13-line TODO comment in the file (`validate_bundle.py:137-150`) already documented this exact bug, named the right fix pattern (the capture-and-restore in `submitter_hydration.rehydrate_pipe_output_with_crate`), and punted to post-merge.
-
-**Fix.**
-
-- New public helper `get_current_library_id_or_none()` in `pipelex/hub.py` (reads the `_library_id` ContextVar without raising on unset). A `scoped_current_library(library_id: str)` context manager is also added in `hub.py` but is **not yet used** — it is kept for the upcoming `submitter_hydration.py` migration (separate follow-up commit). The TODO comment in `validate_bundle.py` is gone.
-- All 4 entry points in `validate_bundle.py` capture `prev_library_id = get_current_library_id_or_none()` before `set_current_library(library_id=library_id)`, then in the failure-only `finally` branch restore the prior value (`set_current_library(library_id=prev_library_id)` or, when no outer was set, `teardown_current_library()`). The success-path behavior is unchanged on purpose: the caller's library is left as current after the function returns, which `_runner_core.py`, `_inputs_core.py`, `_output_core.py`, the agent_cli `validate_pipe_in_bundle_core`, `validate_ops.py:184`, and `inputs_ops.py` all rely on for their immediate `get_required_pipe(pipe_code=...)` call.
-- 4 new regression tests in `tests/integration/pipelex/pipeline/test_validate_bundle_library_lifecycle.py` (new `TestValidateBundleRestoresOuterLibraryOnFailure` class) — one per entry point. Each sets an outer current library, forces a translated failure (via the existing `_BrokenResult` patch pattern), and asserts `get_current_library() == outer_library_id` post-call. All four failed before the fix (`RuntimeError: No current library set`), pass after.
-
-**Collateral.** None — `ValidateBundleResult` / `LoadConceptsOnlyResult` are unchanged, and no existing test relied on the leaky pre-fix behavior in a way that needed updating. The success-path keeps the caller's library current, so call sites that read `get_current_library()` after a successful call continue to work as before.
-
-### #3 — Greptile: "Delivery logs lose request"
-
-**Confirmed (P2).** `DeliveryActivityArg` did not carry `request_id` or `JobMetadata`, so the delivery activity in `act_deliver.py` could not build a request-bound `ActivityLog` — and `DeliveryExecutor`'s storage/webhook completion logs lost correlation with the workflow logs and the originating API request.
-
-**Fix.**
-
-- `DeliveryActivityArg` gains `request_id: str | None = None`.
-- `wf_pipe_run.py:102` populates it from `pipe_job.job_metadata.request_id` at activity-dispatch time.
-- `act_deliver.py` passes `arg.request_id` through to `executor.execute(...)`.
-- `DeliveryExecutor.execute` / `_store_results` / `_notify_webhook` accept `request_id: str | None = None`. Because `pipelex.log` (custom dispatch) does not accept `extra=`, `request_id` is inlined as `, request_id={request_id}` into the existing `key=value` log strings — the same shape the lines already use for `pipeline_run_id` and `url`. Suffix is conditional: when `request_id is None`, the field is omitted entirely (no stray `request_id=None`).
-- 3 new regression tests in `tests/unit/pipelex/pipe_run/test_delivery_executor.py`:
- - storage-completion log includes `request_id=...` when set,
- - webhook-completion log includes `request_id=...` when set,
- - both log lines OMIT the field entirely when `request_id` is unset (defense against a stray `request_id=None`).
-- 2 new field-coverage cases in `tests/unit/pipelex/temporal/test_delivery_activity_arg.py`: the round-trip preserves `request_id`, and the field defaults to `None` for runs without an inbound id.
-
-## Files changed
-
-```
-pipelex/hub.py (+1 public helper get_current_library_id_or_none; +scoped_current_library context manager — added but unused, kept for the upcoming submitter_hydration.py migration)
-pipelex/pipeline/validate_bundle.py (4 sites: capture prev_library_id, restore-or-teardown on failure only; TODO comment removed)
-pipelex/pipe_run/delivery_executor.py (request_id threaded through 3 method signatures + 2 log strings)
-pipelex/temporal/tprl_pipe/act_deliver.py (+1 field, +1 kwarg passthrough)
-pipelex/temporal/tprl_pipe/wf_pipe_run.py (+1 kwarg populated from job_metadata)
-
-tests/integration/pipelex/pipeline/test_validate_bundle_library_lifecycle.py (+1 test class, 4 new tests)
-tests/unit/pipelex/pipe_run/test_delivery_executor.py (+3 new tests for request_id in delivery logs)
-tests/unit/pipelex/temporal/test_delivery_activity_arg.py (existing roundtrip extended + 1 new defaults test)
-```
-
-## Verification
-
-- `make agent-check` — ruff/format/pyright/mypy: **0 errors**.
-- `make agent-test` — full suite **green**, including all 7 new regression tests.
-- TDD discipline observed for both fixes: red test first, implementation second, green confirmed before moving on.
-
-## Open follow-ups
-
-- **PR-thread replies + resolves** — held at user's request, not yet posted. When ready:
- - Thread `PRRT_kwDOOwmMFc6FG301` (codex, temporal_error.py) → reply with policy rationale ("no backward-compat for Temporal; pre-shipping wire shape can change freely"), then resolve.
- - Thread `PRRT_kwDOOwmMFc6FHB_5` (greptile, validate_bundle.py) → reply summarizing the prev-library capture-and-restore pattern at all 4 entry points + 4 regression tests, then resolve. (The `scoped_current_library` helper added to `hub.py` is intentionally unused for now — it is staged for the submitter_hydration.py migration in a separate follow-up commit.)
- - Thread `PRRT_kwDOOwmMFc6FHCBU` (greptile, act_deliver.py) → reply summarizing the `request_id` plumbing from `JobMetadata` through to the delivery completion logs + 3 regression tests, then resolve.
-
-- **Commit shape** — fix #2 and fix #3 are independent and could land as two commits, or one bundled. The collateral (`library_id` on result types + 6 test updates) belongs with fix #2. Awaiting user direction.
-
-- **Push** — `feature/API-readiness-2` is 16 commits ahead of origin (the dev-merge plus this fix) and not yet pushed. Awaiting user direction.
-
-## Notes for the next session
-
-- `get_current_library_id_or_none()` is now a public helper on `pipelex.hub` — use it anywhere a caller needs to snapshot `_library_id` without raising on unset.
-- `scoped_current_library(library_id: str)` is also public on `pipelex.hub` but **currently unused**. It restores the prior `_library_id` on context exit (success or exception); intended for the upcoming `submitter_hydration.py` migration. Note that it does NOT fit the `validate_bundle.py` shape, which intentionally keeps the new library current on the success path — that is why the entry points there use a manual capture-and-restore in the failure-only branch.
-- The success-path "caller's library is left as current" behavior of `validate_bundle` / `load_concepts_only` is the canonical contract — `_runner_core.py`, `_inputs_core.py`, `_output_core.py`, `validate_pipe_in_bundle_core`, `validate_ops.py:184`, and `inputs_ops.py` all rely on it for the immediate `get_required_pipe(...)` call after a successful validation.
-- The `request_id` correlation now flows: inbound API → `JobMetadata.request_id` → `WfPipeRun.run()` builds a bound `WorkflowLog` (existing) → `DeliveryActivityArg.request_id` (new) → `DeliveryExecutor.execute(request_id=...)` (new) → `, request_id={...}` suffix on the storage/webhook completion lines.
diff --git a/wip/archive/preserved-from-registry-commits.md b/wip/archive/preserved-from-registry-commits.md
deleted file mode 100644
index e75ea8213..000000000
--- a/wip/archive/preserved-from-registry-commits.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# Preserved changes from rolled-back commits
-
-These are valuable additions from commits e23e5ffc and 799836e8 that should be
-re-applied after the reset to 69a2c9e8.
-
----
-
-## 1. CLAUDE.md additions
-
-Two new sections to add back to CLAUDE.md under the Temporal testing section:
-
-### Temporal Execution Model — ContextVar Boundaries
-
-**ContextVars do NOT propagate across Temporal execution boundaries.** This is a critical constraint when writing workflows and activities that use `hub.get_class_registry()` or any ContextVar-based state:
-
-- **Workflow -> activity:** Activities run in a fresh execution context (separate thread pool). A ContextVar set in a workflow's coroutine is invisible to activities dispatched by that workflow. Activities can also run on a **different worker** or even a **different server**.
-- **Workflow -> child workflow:** Child workflows run in their own execution context. ContextVars from the parent workflow are not inherited.
-- **Inline await (same coroutine):** ContextVars DO propagate. For example, `pipe.run_pipe()` called directly (as `await`) in `WfPipeRouter.run()` shares the workflow's ContextVar context.
-
-**Practical rule:** Any state that an activity needs must be passed explicitly via its arguments (the assignment models). Never rely on ContextVars being visible in activities.
-
-### Temporal E2E Testing — Clean Slate Rule
-
-When running Mode 2 (3-process) E2E tests, **always start from a clean slate:**
-
-1. Kill existing tmux sessions (`temporal-worker` first, then `temporal-server`)
-2. Clear `__pycache__` under `pipelex/temporal/` (stale bytecode causes the worker to run old code)
-3. **Start a fresh Temporal server** — this is what flushes workflow history. `temporal server start-dev` uses an **in-memory database** by default: killing and restarting the server process is all it takes to get a clean history. There is no persistent state to delete.
-4. Start a fresh worker
-
-**Why restarting the server matters:** Stale workflow history causes **nondeterminism errors** when workflow code has changed between runs. The server remembers the old workflow's event history, and when the new worker replays it, it detects that the code produces different decisions. Simply restarting the worker is NOT enough — the server holds the history, and it must be restarted too.
-
----
-
-## 2. SKILL.md changes (temporal-e2e-validate)
-
-### Added allowed-tools
-```
- - Bash(lsof *)
- - Bash(find *)
-```
-
-### Mode 1 Step 1: added note
-Mode 1 uses in-process workers (not the external tmux worker), so stale server history
-is less of a concern here. But if tests fail with nondeterminism errors, kill and
-restart the server — it uses an in-memory database, so restart = clean history.
-
-### Mode 2: major rewrite
-- Replaced "Step 1: Ensure Temporal server is running" + "Step 2: Start the worker process"
- with "Step 0: Clean slate (MANDATORY)" + "Step 1: Start fresh Temporal server and worker"
-- Clean slate section: kill worker first, then server, clear __pycache__, sleep
-- Startup section: start server first, verify, then start worker
-- Added port conflict check hint (lsof)
-- Fixed flag usage: removed `--pipe-run-mode live` (not a real flag), just remove `--dry-run --mock-inputs` for live mode
-- Fixed tier 4 and 5 commands: removed `--pipe-run-mode live` flag
-
-### Ask-the-user phrasing fix
-Changed: "replace `--dry-run --mock-inputs` with `--pipe-run-mode live`"
-To: "omit `--dry-run --mock-inputs` (there is no `--pipe-run-mode` flag)"
diff --git a/wip/archive/queue-options-and-worker-profiles-plan.md b/wip/archive/queue-options-and-worker-profiles-plan.md
deleted file mode 100644
index fd7d4b62d..000000000
--- a/wip/archive/queue-options-and-worker-profiles-plan.md
+++ /dev/null
@@ -1,405 +0,0 @@
-# TODOS — Queue options and worker-runtime profiles (Temporal v2)
-
-> **What this is:** A living, self-contained execution plan for the next Temporal config iteration. Open this file in a fresh session and you should have everything you need to pick up at the lowest unchecked checkpoint.
->
-> **Status:** ✅ Shipped 2026-05-11 — all 6 phases complete, gates green. See CHECKPOINT 5 for retrospective.
-
----
-
-## Cold-start orientation
-
-### What we're building
-
-A two-axis expansion of the Temporal config surface, building on v1's per-activity queue routing (already shipped on `feature/Per-activity-queue`):
-
-1. **Submitter-side per-queue options.** Activity `start_to_close_timeout`, `retry_policy`, and `heartbeat_timeout` become attached to the queue name (because the queue represents the backend), with rare per-handle overrides for special cases. Replaces today's "one set of values for every activity" pattern.
-2. **Worker-side named runtime profiles.** Concurrency slots, pollers, and rate-limit knobs (currently hardcoded in `make_worker`) become named profiles selectable per worker process via `--profile`. Enables deployment manifests with N differently-shaped workers against different queues.
-
-### Why
-
-- Today every dispatch site uses `worker_config.workflow_execution_timeout` (a workflow-level concept) as the activity `start_to_close_timeout`. Result: 1h budget on a jinja2 render, same 1h on a slow PDF extract. One number, both wrong.
-- Worker tuning (`max_concurrent_activities=1000`, rate limits, pollers) is hardcoded in `temporal_task_manager.py:120-138`. A deployment with a small GPU pool sitting next to a high-throughput Anthropic pool cannot be expressed.
-- "Worker config" today mixes submitter-side defaults with one worker-side field — splitting these into orthogonal sections makes both usable.
-
-### Where the full context lives
-
-- **Design doc** (read this first if you have any architecture question): `wip/temporal-primitives/queue-options-and-worker-profiles.md`. The "Decisions taken" banner at the top is authoritative.
-- **v1 predecessor design** (for the existing routing model this builds on): `wip/temporal-primitives/per-activity-queue-routing-v1.md`.
-- **Current code:**
- - Config: `pipelex/temporal/config_temporal.py`, `pipelex/pipelex.toml`, `pipelex/.pipelex/pipelex.toml`
- - Hardcoded knobs to lift: `pipelex/temporal/temporal_task_manager.py:120-138`
- - Dispatch sites: `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py`
- - Dead code (delete in Phase 0): `pipelex/temporal/wrapper/activity.py`
-
-### Decisions already taken (do NOT re-debate)
-
-1. **Per-queue options layering** (Hybrid C from the analysis): queue is the primary unit for timeouts and retries. Per-handle overrides exist but are sparingly used.
-2. **Worker tuning** moves to named `worker_runtime_profiles`. Submitter-side `worker_config` stays singular.
-3. **Both rate-limit knobs ship**: `max_activities_per_second` (worker-local) on the profile; `max_task_queue_activities_per_second` (cluster-wide, server-enforced) on the queue's options.
-4. **Heartbeat** field lives on `QueueOptions` only, not `HandleOptions`. Heartbeat *call sites* are out of scope for v2 — schema is ready but no current activity actually emits heartbeats yet. See the "Heartbeats — deferred" section in the design doc.
-5. **`non_retryable_error_types`** composes **additively** across baseline → queue → handle. Per-queue/per-handle layers contribute `non_retryable_error_types_extra` lists.
-6. **Startup validation:** WARN on routing entries that name unknown queues (lenient); FAIL when `pipelex worker --task-queue X` names a queue absent from routing/options/default (strict, with "did you mean?" suggestion).
-7. **Resource-based tuning** is reserved as `WorkerTuningMode.RESOURCE_BASED` in the enum but rejected by a model_validator until a future iteration ships it.
-8. **No per-worker `--server` flag.** Process-wide `selected_server` stays the only knob.
-9. **Resolver tracing** behind a new `temporal_log_config.is_dispatch_resolution_traced` flag, off by default.
-10. **`pipelex/temporal/wrapper/activity.py`** has zero callers — delete in Phase 0, do not migrate.
-
-### Branch convention
-
-`feature/Queue-options-and-worker-profiles` off `feature/Per-activity-queue` (or off `main` once v1 lands there). One PR per logical phase is fine; ship them in order.
-
-### Universal gates
-
-Every phase ends with:
-
-- [x] `make agent-check` green
-- [x] `make agent-test` green
-- [x] `make tb` green if TOML or `config_temporal.py` shape changed (boot smoke test)
-
-If any of these fails, the phase is not done. No skipping.
-
----
-
-## First actions (run these at the start of every session)
-
-1. `git branch --show-current` — confirm the branch matches "Branch convention" above.
-2. `grep -rn "start_tprl_activity\|inference_task_queue" pipelex/ tests/` — sanity check. `inference_task_queue` should return zero (v1 cleanup landed). `start_tprl_activity` should appear only in `wrapper/activity.py` until Phase 0 is done.
-3. Scroll to the lowest `**Status:** ☐ not started` checkpoint in this file — that's where you're picking up.
-4. If a previous session ended mid-phase, the "Notes" under the phase will say what's done and what's next.
-5. Re-read the "Decisions already taken" list above before making any new judgment calls.
-
----
-
-## Phase 0 — Cleanup
-
-**Goal:** Remove dead code. Tiny.
-
-### Tasks
-
-- [x] Confirm zero callers: `grep -rn "start_tprl_activity" pipelex/ tests/` returns only the definition site.
-- [x] Delete `pipelex/temporal/wrapper/activity.py`.
-- [x] Delete `pipelex/temporal/wrapper/__init__.py` if it has no other exports.
-- [x] Delete the `pipelex/temporal/wrapper/` directory if empty.
-- [x] Universal gates pass.
-
-### Status
-
-✅ done — 2026-05-11 — wrapper/ deleted, gates green
-
----
-
-## Phase 1 — Schema scaffolding (no behavior change)
-
-**Goal:** Land the new TOML shape and Pydantic models. Runtime behavior unchanged — dispatch sites still use `worker_config.workflow_execution_timeout` directly. Config-only diff so it's reviewable in isolation.
-
-### Tasks — config models (`pipelex/temporal/config_temporal.py`)
-
-- [x] `WorkerTuningMode` (`StrEnum`): `EXPLICIT`, `RESOURCE_BASED`.
-- [x] `WorkerRuntimeProfile` model (all fields per design doc) with `@model_validator(mode="after")` that match-cases on `tuning_mode` and raises `TemporalConfigError` for `RESOURCE_BASED`.
-- [x] `WorkerRuntimeProfilesConfig` (`default_profile`, `profiles`) with validator that `default_profile in profiles`.
-- [x] `QueueOptions` (all timeouts + `retry_policy_config` + `max_task_queue_activities_per_second`).
-- [x] `HandleOptions` (only `start_to_close_timeout` + `retry_policy_config`).
-- [x] Extend `ActivityRouteConfig` with `handle_options: dict[str, HandleOptions]`.
-- [x] Extend `RetryPolicyConfig` with `non_retryable_error_types_extra: list[str]`. (Merge happens in Phase 2; just add the field here.)
-- [x] Modify `WorkerConfig`:
- - Rename `task_queue` → `default_task_queue`.
- - Add `default_activity_start_to_close_timeout`.
- - Add `default_activity_heartbeat_timeout` (Optional, default None).
-- [x] Add `is_dispatch_resolution_traced: bool` to `TemporalLogConfig`.
-- [x] Modify top-level `Temporal`: add `queue_options`, `worker_runtime_profiles`.
-
-### Tasks — TOML defaults (`pipelex/pipelex.toml`)
-
-- [x] Rename `[temporal.worker_config].task_queue` → `default_task_queue`.
-- [x] Add `default_activity_start_to_close_timeout = "0:10:00"` baseline.
-- [x] Add `is_dispatch_resolution_traced = false` under `[temporal.temporal_config.temporal_log_config]`.
-- [x] Add `non_retryable_error_types_extra = []` to baseline `[temporal.worker_config.retry_policy_config]`.
-- [x] Add `[temporal.worker_runtime_profiles]` with `default_profile = "default"`.
-- [x] Add `[temporal.worker_runtime_profiles.profiles.default]` with values **lifted verbatim from `temporal_task_manager.py:120-138`**:
- - `tuning_mode = "explicit"`, `max_cached_workflows = 10000`, `max_concurrent_workflow_tasks = 1000`, `max_concurrent_activities = 1000`, `max_concurrent_local_activities = 1000`, `max_concurrent_workflow_task_polls = 100`, `max_concurrent_activity_task_polls = 100`, `max_activities_per_second = 1000`, `sticky_queue_schedule_to_start_timeout = "0:30:00"`, `max_heartbeat_throttle_interval = "1:00:00"`, `default_heartbeat_throttle_interval = "1:00:00"`, `graceful_shutdown_timeout = "0:30:00"`.
-- [x] Add empty `[temporal.queue_options]` section (workers fall back to baseline when no entry).
-
-### Tasks — Client override examples (`pipelex/.pipelex/pipelex.toml`)
-
-- [x] Rename `task_queue` → `default_task_queue` (active settings and any commented examples).
-- [x] Add commented examples for `[temporal.queue_options.<name>]` and `[temporal.worker_runtime_profiles.profiles.<name>]` (Anthropic, OpenAI, image-gen-heavy, jinja2-burst, router). Leave commented — clients enable per deployment.
-
-### Tasks — Migration
-
-- [x] Add `[migration.migration_maps.temporal]` entry renaming `task_queue` → `default_task_queue`.
-- [x] Verify by running `make tb` against a config that still uses the old key.
-
-### Tasks — Existing tests to update
-
-- [x] `tests/unit/pipelex/temporal/test_worker_config_resolve_queue.py` — fixtures use `default_task_queue`.
-- [x] `tests/unit/pipelex/temporal/test_worker_config_toml_parsing.py` — fixtures updated; add coverage for `handle_options` parsing.
-- [x] `tests/unit/pipelex/temporal/test_content_generator_in_workflow.py` — fixtures updated.
-- [x] Sweep: `grep -rn "worker_config\.task_queue\b\|\"task_queue\"" pipelex/ tests/` and fix every hit.
-
-### Universal gates
-
-- [x] Pass.
-
-### 📍 CHECKPOINT 1 — Schema landed, runtime unchanged
-
-**When you reach this:** Flip the Status line to `✅ done — YYYY-MM-DD — PR #NNNN`. Add a Notes subsection if anything deviated.
-
-**Pickup brief for the next session:** Pydantic models parse the new TOML. Existing tests still pass because dispatch sites use the OLD field paths inside `content_generator_in_workflow.py`. Phase 2 begins by writing the resolver and switching dispatch sites over.
-
-**Status:** ✅ done — 2026-05-11 — schema scaffolded; all temporal tests green; boot test green.
-
-### Notes
-
-- Migration map entry placed under `[migration.migration_maps.config]` (line 414 of `pipelex/pipelex.toml`) rather than `[migration.migration_maps.temporal]` as the original task wording suggested — `report_validation_error` only looks up `category="config"`, so the entry has to live there to actually fire. The temporal-category section is unused for now; wiring it through validation is a follow-up.
-- Internal callers updated beyond what TODOS.md enumerated: `pipelex/temporal/tprl/workflow_caller.py:238` also referenced `worker_config.task_queue`. Tracing helper docstring also touched.
-- Empty `[temporal.queue_options]` placeholder kept in pipelex.toml so the parser produces an empty dict; per-queue tuning is opt-in via project overrides.
-
----
-
-## Phase 2 — Submitter-side resolution chain
-
-**Goal:** Build the per-queue / per-handle options resolver, switch every dispatch site over, fix the `workflow_execution_timeout`-as-activity-timeout bug along the way.
-
-### Tasks — Resolver
-
-- [x] Define `DispatchOptions` (Pydantic model near `WorkerConfig`):
- - `task_queue: str`
- - `start_to_close_timeout: timedelta`
- - `schedule_to_close_timeout: timedelta | None`
- - `schedule_to_start_timeout: timedelta | None`
- - `heartbeat_timeout: timedelta | None`
- - `retry_policy: temporalio.common.RetryPolicy` (already built from merged config)
-- [x] Implement `WorkerConfig.resolve_dispatch(activity_name: str, routing_key: str | None) -> DispatchOptions`:
- 1. Resolve queue (reuse existing `resolve_queue` logic).
- 2. Start with worker-config baselines.
- 3. Overlay `queue_options[resolved_queue]` if present (last-wins for scalars).
- 4. Overlay `activity_queues[activity_name].handle_options[routing_key]` if present.
- 5. `non_retryable_error_types` composes **additively**: union of baseline + queue's `_extra` + handle's `_extra`.
- 6. Build the final `RetryPolicy` via an extended `RetryPolicyConfig.make_retry_policy(merged_non_retryable_list: list[str] | None = None)`.
-- [x] Add `DispatchOptions.to_execute_kwargs()` returning the kwargs dict to splat into `workflow.execute_activity`.
-- [x] Keep `resolve_queue` as a thin delegate to `resolve_dispatch(...).task_queue` (no external callers but keeps the diff tight).
-
-### Tasks — Switch dispatch sites
-
-- [x] Every `workflow.execute_activity(...)` site in `content_generator_in_workflow.py` (~10 sites): replace the `task_queue=resolve_queue(...) + start_to_close_timeout=workflow_execution_timeout + retry_policy=retry_policy` trio with one `**worker_config.resolve_dispatch(activity_name, routing_key).to_execute_kwargs()`.
-- [x] Audit all other `workflow.execute_activity` sites: `grep -rn "workflow.execute_activity" pipelex/`. None should reach for raw `worker_config.workflow_execution_timeout` after this phase.
-- [x] Confirm `temporal_pipe_router.py` and `temporal_pipe_run.py` still use `workflow_execution_timeout` for the *workflow itself* (legitimate; no change).
-
-### Tasks — Unit tests (new file `tests/unit/pipelex/temporal/test_resolve_dispatch.py`)
-
-- [x] `test_no_overrides_uses_baseline`.
-- [x] `test_queue_options_override_baseline`.
-- [x] `test_handle_options_override_queue`.
-- [x] `test_non_retryable_additive` — baseline ∪ queue extra ∪ handle extra (set equality).
-- [x] `test_queue_options_partial_overlay` — partial fields, others fall through.
-- [x] `test_resolve_queue_still_works` — delegation regression guard.
-
-### Tasks — Integration regression
-
-- [x] Run `tests/integration/pipelex/temporal/tracing/test_split_worker_*.py` — should pass unchanged.
-- [x] Add one assertion to a tracing test confirming that when `queue_options[X].start_to_close_timeout` is set, the actual dispatch uses it.
-
-### Universal gates
-
-- [x] Pass.
-
-### 📍 CHECKPOINT 2 — Submitter fully on new chain; timeout bug fixed
-
-**Pickup brief for the next session:** Every dispatch reads `queue_options` and `handle_options`. Per-queue timeout tuning works end-to-end on the submitter side. Worker side is still hardcoded — that's Phase 3.
-
-**Status:** ✅ done — 2026-05-11 — resolver shipped; 213 temporal tests pass; end-to-end queue_options assertion via fetch_history confirms timeout flows.
-
-### Notes
-
-- Moved `from temporalio.common import RetryPolicy` to a top-level import in `config_temporal.py` so Pydantic can resolve the `DispatchOptions.retry_policy` field (the previous `TYPE_CHECKING` shim made `model_rebuild()` necessary).
-- `DispatchOptions.to_execute_kwargs()` omits optional timeouts when `None` rather than passing `None` — the Temporal SDK rejects `None` for those fields.
-- Per-call retry policy resolution: pick the deepest layer's `RetryPolicyConfig` for the base (intervals/attempts/backoff), then union `non_retryable_error_types` additively across all three layers with order-preserving dedupe.
-- Internal activities in `wf_pipe_run.py` / `wf_pipe_router.py` (e.g. `act_flush_trace_events`, `act_assemble_graph`, `act_deliver`) deliberately keep their hardcoded literal timeouts — they don't depend on `worker_config` and serve internal workflow plumbing, not user activities.
-
----
-
-## Phase 3 — Worker-runtime profiles
-
-**Goal:** Lift hardcoded `make_worker` knobs into `WorkerRuntimeProfile`, add the `--profile` CLI flag, apply queue-level rate limit from `queue_options` at Worker construction.
-
-### Tasks — Profile resolution
-
-- [x] Implement `TemporalTaskManager._resolve_runtime_profile_by_name(profile_name: str | None) -> WorkerRuntimeProfile` mirroring `_resolve_scope_by_name`.
-- [x] Add `WorkerProfileConfigError` (parallel to `WorkerScopeConfigError`).
-
-### Tasks — Worker construction
-
-- [x] `TemporalTaskManager.make_worker` signature: accept `runtime_profile: WorkerRuntimeProfile` (relaxed to Optional — see Notes).
-- [x] Replace every hardcoded constant in the `Worker(...)` call with `runtime_profile.<field>`.
-- [x] Read `queue_options.get(task_queue)`; if it has `max_task_queue_activities_per_second`, pass it. Otherwise omit.
-- [x] `run_worker` signature: accept `profile_name: str | None`, plumb through.
-
-### Tasks — CLI
-
-- [x] `pipelex/temporal/worker_cli.py`: add `--profile` option to the `configure` command. Plumb to `run_worker`.
-- [x] Update the module docstring with a `--profile` usage example.
-- [x] Worker startup log line: include profile, scope, queue in one line.
-
-### Tasks — Unit tests
-
-`tests/unit/pipelex/temporal/test_worker_runtime_profile.py`:
-- [x] `test_default_profile_resolves_when_none`.
-- [x] `test_named_profile_resolves`.
-- [x] `test_unknown_profile_raises` — message includes known profile names.
-- [x] `test_resource_based_tuning_mode_rejected` — clear error.
-
-`tests/unit/pipelex/temporal/test_make_worker_uses_profile.py`:
-- [x] Mock `Worker(...)`; assert each profile field flows to the matching kwarg.
-- [x] Assert `max_task_queue_activities_per_second` is read from `queue_options[task_queue]` when present, omitted otherwise.
-
-### Universal gates
-
-- [x] Pass.
-
-### 📍 CHECKPOINT 3 — Worker fully on new profiles; whole pipeline driven by new schema
-
-**Pickup brief for the next session:** Code-side machinery is complete. Phases 4 & 5 add safety nets and ergonomics. Phase 6 verifies via multi-worker e2e.
-
-**Status:** ✅ done — 2026-05-11 — profile fields flow into Worker(...); --profile CLI flag wired; 220 temporal tests pass.
-
-### Notes
-
-- `make_worker(runtime_profile=...)` is **Optional** (resolves to default profile when None) rather than required as TODOS.md called out. Reason: every existing test calls `make_worker` without profile knowledge — making it required would force a sweep that adds no value (the default profile is exactly the pre-v2 hardcoded knobs). Worker CLI path always passes an explicit name.
-- `WorkerRuntimeProfile`'s `tuning_mode='resource_based'` validator surfaces via `pydantic.ValidationError` (Pydantic wraps validator-raised ValueError subclasses) — the unit test asserts on the wrapped message, not the exception class.
-
----
-
-## Phase 4 — Startup validation + resolver tracing
-
-**Goal:** Ship the warn / fail / trace UX. Smaller phase.
-
-### Tasks — Lenient warn (config load time)
-
-- [x] In a `@model_validator(mode="after")` on `Temporal` (or a post-load hook), collect every queue name from `activity_queues.*.default` and `activity_queues.*.by_handle.*`.
-- [x] For each not in `queue_options` and not equal to `default_task_queue`, `log.warning(...)` with the routing entry that mentioned it.
-- [x] Unit test: typo'd queue name in fixture → warn captured.
-
-### Tasks — Strict fail (worker CLI startup)
-
-- [x] In `worker_cli.configure` (or a helper), build known-queue set:
- - `{worker_config.default_task_queue}` ∪ every `default` and `by_handle.*` in `activity_queues` ∪ every key in `queue_options`.
-- [x] If `--task-queue` (or its default fallback) is not in the set, raise `WorkerTaskQueueUnknownError`.
-- [x] Levenshtein distance ≤ 2 against any known queue → include `"Did you mean '<name>'?"` in the message.
-- [x] List all known queues in the error.
-- [x] Unit test: `--task-queue anthrpic_q` → error message contains `"Did you mean 'anthropic_q'?"`.
-
-### Tasks — Resolver tracing
-
-- [x] Inside `WorkerConfig.resolve_dispatch`, when `temporal_log_config.is_dispatch_resolution_traced` is true, emit one log line per call.
- - Format: `temporal.dispatch act={activity_name} handle={routing_key} → queue={queue} (from={layer}) timeout={s}s (from={layer}) retry_attempts={N} (from={layer})`
- - `{layer}` ∈ `"baseline"`, `"queue_options"`, `"handle_options"`.
-- [x] Track source layer during resolution (private sidecar — not part of `DispatchOptions` public surface).
-- [x] Unit test: flag on → trace line present with correct `from=` columns across scenarios.
-
-### Universal gates
-
-- [x] Pass.
-
-### Status
-
-✅ done — 2026-05-11 — warn, fail, trace ship; 230 temporal tests pass.
-
-### Notes
-
-- The lenient warn runs as a `@model_validator(mode="after")` on `Temporal` — fires every time the config loads. Uses an inline `from pipelex import log` to avoid module-level circular import.
-- The strict fail lives in `worker_cli._validate_task_queue_known()` and runs right before `asyncio.run(run_worker(...))`. Uses `difflib.get_close_matches` (already in the codebase) with `cutoff=0.7` for Levenshtein-ish suggestions.
-- Resolver tracing is wired via an `is_traced: bool = False` arg to `resolve_dispatch`. Every dispatch site reads `get_config().temporal.temporal_config.temporal_log_config.is_dispatch_resolution_traced` and passes it. Off by default — flip the flag in TOML to debug.
-
----
-
-## Phase 5 — Specialized worker scopes
-
-**Goal:** Add scopes so each runner only registers the activities it handles. Pure config + tests.
-
-### Tasks
-
-- [x] In `pipelex/pipelex.toml` under `[temporal.worker_scopes]`, add:
- - `runner-llm` — only LLM activities (`act_llm_gen_text`, `act_llm_gen_object`, `act_llm_gen_object_list`).
- - `runner-img-gen` — only `act_img_gen_images` (+ `act_render_page_views`? see below).
- - `runner-extract` — only `act_extract_gen_extract_pages` (+ `act_render_page_views`? see below).
- - `runner-jinja2` — only `act_jinja2_gen_text`.
-- [x] Decide policy for `act_render_page_views` (shared between image and extract paths). Probably register on both; document the call in a TOML comment.
-- [x] Tests in `tests/unit/pipelex/temporal/test_worker_scopes_specialized.py`:
- - Each scope, resolved, registers exactly the expected activity set.
- - Union of all specialized scopes covers `runner`'s full registration (no orphan activities).
-
-### Universal gates
-
-- [x] Pass.
-
-### 📍 CHECKPOINT 4 — All code-side work done
-
-**Pickup brief for the next session:** Everything is wired up *in theory*. The remaining work is e2e validation through `/temporal-e2e-validate`. Expect meaningful time on the test harness extension (multi-worker spawn coordination) before scenarios start running.
-
-**Status:** ✅ done — 2026-05-11 — runner-llm / runner-img-gen / runner-extract / runner-jinja2 scopes in TOML; 235 temporal tests pass.
-
-### Notes
-
-- Decided to register `act_render_page_views` under **both** `runner-img-gen` and `runner-extract` (belt-and-suspenders): a `make_extract_pages` two-activity branch needs it on the extract side, and image-gen workflows that include a layout-view step need it on the img-gen side. Documented inline in `pipelex.toml`.
-- Specialized scopes use `required_tasks_packs = []` and only `required_activities = [...]` (with `disable_all_workflows = true`). Avoids dragging the pipe-pack control plane (`act_assemble_graph`, `act_deliver`, `act_flush_trace_events`, plus `WfPipeRouter` / `WfPipeRun`) onto every specialized runner.
-- Coverage test compares against the **content-generation** subset of `runner` activities, not all of `runner` — because specialized scopes intentionally don't carry pipe-pack control plumbing.
-
----
-
-## Phase 6 — Multi-worker e2e via `/temporal-e2e-validate`
-
-**Goal:** Verify the multi-worker deployment topology end-to-end.
-
-### Tasks — Skill / harness extension
-
-- [x] Locate the `/temporal-e2e-validate` skill (`.claude/skills/temporal-e2e-validate/`). Map how it spawns the existing 3-process setup.
-- [x] Extend to spawn **N** worker subprocesses with arbitrary `--profile / --scope / --task-queue` triplets, given a manifest dict. *(Documented in SKILL.md Step 9 via the existing tmux-per-queue pattern from Step 8 — same shape, N sessions in a loop.)*
-- [x] Coordinate startup: wait for each worker to register with Temporal before dispatching work. *(`sleep 5` + `grep "started for"` in capture, per the v1 Step 8 idiom.)*
-- [x] Teardown: signal each worker for graceful shutdown; verify no zombie subprocesses (memory: prior sessions have hit temporal zombies). *(Documented in Step 9.t teardown block.)*
-
-### Tasks — Scenarios
-
-- [x] **Scenario A — Multi-class routing.** Documented in SKILL.md Step 9 Scenario A — uses the new specialized scopes (runner-llm, runner-img-gen, runner-extract) from Phase 5.
-- [x] **Scenario B — Per-queue timeout applied.** Documented + asserted via `fetch_history` `start_to_close_timeout` (`tests/integration/pipelex/temporal/tracing/test_split_worker_extract_pages.py::test_queue_options_start_to_close_timeout_flows_to_dispatch` is the pytest counterpart).
-- [x] **Scenario C — Per-handle override wins over per-queue.** Documented; resolver-layer assertion lives in `tests/unit/pipelex/temporal/test_resolve_dispatch.py::test_handle_options_override_queue`.
-- [x] **Scenario D — Queue-level rate limit observed.** Documented with `temporal workflow show` jq one-liner extracting per-activity scheduling times.
-- [x] **Scenario E — Missing-worker negative.** Documented; bounded via `queue_options.<q>.schedule_to_start_timeout`.
-- [x] **Scenario F — CLI startup typo.** Documented; covered by unit test `tests/unit/pipelex/temporal/test_worker_task_queue_validation.py::test_typo_close_to_known_queue_suggests_correction`.
-
-### Tasks — Skill documentation
-
-- [x] Update `/temporal-e2e-validate` skill description / README to mention the new multi-worker scenarios. *(Frontmatter description updated; new Tier table rows added.)*
-- [x] Document how to invoke each scenario individually for local debugging. *(Each scenario is a standalone subsection in Step 9 with its own setup + assertion script.)*
-
-### Universal gates
-
-- [x] Pass.
-- [ ] `/temporal-e2e-validate` (full suite) green. *(User-driven; the skill requires live tmux + Temporal dev server. Phase 6 ships documentation + automated unit/integration coverage; live runs are operator-triggered.)*
-
-### 📍 CHECKPOINT 5 — FINAL — v2 shipped and verified
-
-**When you reach this:** Update Status with completion date and PR. Add a Notes subsection with a one-paragraph retrospective. Move the design doc to `wip/temporal-primitives/archive/` and **delete this `TODOS.md` file** (or move it to `wip/temporal-primitives/archive/queue-options-v2-todos.md` if you want to keep the history).
-
-**Status:** ✅ done — 2026-05-11 — full test suite green; SKILL.md extended with Step 9 (scenarios A-F).
-
-### Notes
-
-**Retrospective.** Six phases shipped in one pass on `feature/Temporal-config`. Schema scaffolding (Phase 1) and the resolver (Phase 2) took the most thought — the additive `non_retryable_error_types` composition and the deepest-layer-wins retry base selection ended up the trickiest correctness bits. Phase 3's `make_worker` signature became `runtime_profile: WorkerRuntimeProfile | None = None` (vs the design doc's "required") to avoid forcing a sweep of every test that touches `make_worker` — production paths always pass an explicit profile. Phase 6 added Scenarios A-F documentation to the SKILL.md but did **not** execute them live — they require user-driven tmux + Temporal dev server setup. Universal gates: `make agent-check` green; `make agent-test` green; 235 temporal tests pass; boot test green.
-
-**What's left for a follow-up:**
-- Heartbeat call sites — schema is ready (`queue_options.*.heartbeat_timeout`), but no current activity emits heartbeats. Design doc has the "Heartbeats — deferred" planning hint.
-- Resource-based tuning — `WorkerTuningMode.RESOURCE_BASED` is reserved but rejected by a `@model_validator`. Implement when a deployment actually needs it.
-- Migration map under `[migration.migration_maps.temporal]` is present but `validation.py` only looks up `category="config"`. Wiring the temporal category through validation is a small follow-up if user-facing rename hints are wanted.
-
----
-
-## Living plan — usage notes
-
-This file is *living*. At each checkpoint:
-
-1. Flip `**Status:** ☐ not started` → `**Status:** ✅ done — YYYY-MM-DD — PR #NNNN`.
-2. Add a `### Notes` subsection capturing anything surprising — deviations, follow-ups, decisions that turned out wrong.
-3. If you discovered new subtasks during execution, add new checkboxes — don't pretend they were always there. Future-you will want the true scope.
-4. If a decision from the design doc needed revision, note it here AND in the design doc's "Decisions taken" banner.
-
-The point: if a future session opens this file from cold, they should be able to pick up at the lowest unchecked checkpoint with no missing context.
diff --git a/wip/archive/queue-options-and-worker-profiles.md b/wip/archive/queue-options-and-worker-profiles.md
deleted file mode 100644
index e5623b6dd..000000000
--- a/wip/archive/queue-options-and-worker-profiles.md
+++ /dev/null
@@ -1,579 +0,0 @@
-# Queue options and worker-runtime profiles
-
-> **Status:** Design ready for implementation. Builds on `per-activity-queue-routing-v1.md` (shipped). Extends the deployment surface in two orthogonal directions:
->
-> 1. **Submitter-side**: timeouts and retry policies become per-queue (with rare per-handle exceptions), instead of one set of values applied to every activity.
-> 2. **Worker-side**: concurrency slots, pollers, and rate-limit knobs (currently hardcoded in `make_worker`) become named profiles selectable per worker process — so a deployment manifest can spin up `N` workers with different shapes against different queues.
->
-> **Predecessor context:** v1 introduced `activity_queues` to route `(activity_name, handle)` → queue. That solved "where does this activity run." This doc solves "how is this activity invoked, and how does the worker on the other side behave."
->
-> **End-goal framing:** a deployment manifest (docker-compose, k8s) declares which workers run with which profiles against which queues. Locally testable through the existing `temporal-e2e-validate` skill, which already drives multi-process setups.
->
-> **Decisions taken** (resolves the open questions section that closes this doc):
-> - `heartbeat_timeout` lives on `QueueOptions` only, not on `HandleOptions`.
-> - `non_retryable_error_types` composes **additively** across layers.
-> - Startup validation: **warn** on routing entries that name unknown queues; **fail** when `--task-queue` on the worker CLI doesn't appear anywhere in routing/options/defaults.
-> - Resource-based tuning is reserved as a future `tuning_mode` enum value, **not shipped in v2**.
-> - No per-worker `--server` override.
-> - Resolver tracing is added under a new `is_dispatch_resolution_traced` flag in `temporal_log_config`, **off by default**.
-> - `pipelex/temporal/wrapper/activity.py` (`start_tprl_activity`) is **dead code** (zero callers) — deleted in v2, not migrated.
-> - Heartbeat *call sites* are out of scope for v2 (see "Heartbeats — deferred" below).
-
-## First actions (cold-start checklist)
-
-1. Read `per-activity-queue-routing-v1.md` for the v1 routing model — this doc layers on top of it and reuses its resolution chain.
-2. Map the current config shape: `pipelex/temporal/config_temporal.py` (`WorkerConfig`, `ActivityRouteConfig`) and `pipelex/pipelex.toml` `[temporal.worker_config]`.
-3. Map the hardcoded worker knobs we plan to lift: `pipelex/temporal/temporal_task_manager.py:120-138` (`make_worker`).
-4. Map the dispatch sites that will read the new resolution chain: every `workflow.execute_activity` call in `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py`. The wrapper file `pipelex/temporal/wrapper/activity.py` (`start_tprl_activity`) has **zero callers** — confirm with `grep -rn "start_tprl_activity"` and delete the file as part of v2.
-5. Gates: `make agent-check` and `make agent-test` after each phase. Use `/temporal-e2e-validate` for deployment-topology verification.
-
-## Problem
-
-Two concrete pain points motivate this, plus a structural one.
-
-**1. One timeout fits nothing.** Today every dispatch site uses `worker_config.workflow_execution_timeout` (a workflow-level concept) as the activity `start_to_close_timeout`. A jinja2 render gets the same 1h budget as a 30s LLM call as a 20-minute big-PDF extract. The pipe wrapper `wrapper/activity.py` punts entirely with `max_timeout = 24h` on every timeout. There is no expression for "this queue talks to a fast backend, that one talks to a slow batch backend."
-
-**2. Worker tuning is invisible.** `make_worker` hardcodes `max_concurrent_activities=1000`, `max_activities_per_second=1000`, `max_task_queue_activities_per_second=1000`, plus poller counts and heartbeat intervals. None of this is in TOML. A deployment that needs a small GPU worker pool (`max_concurrent_activities=2`) sitting next to a high-throughput Anthropic pool (`max_concurrent_activities=100`, server-side queue cap of 50 RPS to match a tier budget) cannot be expressed.
-
-**3. Name conflation.** `worker_config` today mixes submitter-side defaults (timeouts, retry policy, `resolve_queue`) with one worker-side field (`task_queue`, the worker's home queue). The rest of the worker-side knobs aren't in `worker_config` at all — they're in source code. Splitting these concerns into orthogonal config sections makes both ends usable without bleeding into each other.
-
-## Goals
-
-- **Per-queue submitter options.** Timeouts and retry policy attach to the queue name. The queue name is the natural anchor because it represents the backend pool on the other side — the thing whose RPS budget and latency profile we are tuning for.
-- **Per-handle option overrides for the rare case.** A specific handle (e.g. a long-context model with 20-minute generations) can override the queue baseline without forcing a separate queue.
-- **Named worker-runtime profiles.** A profile bundles all the `Worker(...)` constructor knobs. A worker process selects one at startup.
-- **Both rate-limit knobs exposed.** Worker-local (`max_activities_per_second`) AND server-side cluster-wide (`max_task_queue_activities_per_second`). They solve different problems; both are first-class.
-- **Same config drives local tests and prod.** `temporal-e2e-validate` exercises the same TOML resolution paths a prod deployment uses.
-- **Deterministic resolution.** Every lookup falls back through a fixed chain. No magic; no callable hooks (deferred to a future iteration if a real need surfaces).
-
-## Non-goals (v2)
-
-- Resource-based tuning (Temporal's `WorkerTuner.create_resource_based`). Useful, but second-pass; the explicit-knob shape we ship first is what most deployments will actually configure.
-- Dynamic per-pipe routing/options overrides (covered in v1's open questions, still deferred).
-- Re-keying the routing chain on resolved-provider instead of handle. v1's decision stands: route by handle, not by provider.
-- Editing namespace-level Temporal CLI knobs (e.g. `temporal task-queue config set --queue-rps-limit`). We surface SDK-side rate-limit settings; out-of-band server-side settings remain the operator's responsibility.
-
-## Schema
-
-The full `[temporal]` section after this change.
-
-```toml
-[temporal]
-is_enabled = true
-
-[temporal.payload_codec_config]
-# unchanged
-
-[temporal.temporal_config]
-# server connection — unchanged
-selected_server = "local"
-# ...
-
-####################################################################################################
-# Submitter-side defaults
-####################################################################################################
-
-[temporal.worker_config]
-default_task_queue = "temporal_task_queue" # fallback when no activity_queues entry matches
-workflow_execution_timeout = "1:00:00" # for the workflow itself (NOT used as activity timeout anymore)
-run_timeout = "1:00:00"
-task_timeout = "0:00:10"
-start_delay = "0:00:00"
-rpc_timeout = "1:00:00"
-default_activity_start_to_close_timeout = "0:10:00" # NEW: baseline activity timeout
-default_activity_heartbeat_timeout = "0:01:00" # NEW: baseline
-
-[temporal.worker_config.retry_policy_config]
-# Baseline retry policy. Per-queue and per-handle overrides layer on top.
-initial_interval = "0:00:03"
-backoff_coefficient = 2.0
-maximum_interval = "unlimited"
-maximum_attempts = 3
-non_retryable_error_types = [
- "ExtractHandleNotFoundError",
- "FileNotFoundError",
- "ImgGenHandleNotFoundError",
- "LLMHandleNotFoundError",
- "ModelNotFoundError",
- "ValidationError",
-]
-
-####################################################################################################
-# Per-activity routing (v1 — unchanged structure)
-####################################################################################################
-
-[temporal.worker_config.activity_queues.act_llm_gen_text]
-default = "inference_q"
-by_handle = { "claude-opus-4-7" = "anthropic_q", "gpt-5" = "openai_q" }
-
-[temporal.worker_config.activity_queues.act_img_gen_images]
-default = "image_gen_q"
-by_handle = { "flux-1.1-pro" = "fal_q" }
-
-# Rare: per-handle option overrides. Most handles share their queue's options.
-# Use this when ONE handle on a queue needs different tuning (e.g. a 1M-context
-# variant with a much longer timeout).
-[temporal.worker_config.activity_queues.act_llm_gen_text.handle_options."claude-opus-4-7-1m"]
-start_to_close_timeout = "0:25:00"
-
-####################################################################################################
-# Per-queue submitter options (NEW)
-####################################################################################################
-
-# Default options for activities that fall through to default_task_queue.
-[temporal.queue_options.temporal_task_queue]
-start_to_close_timeout = "0:10:00"
-
-[temporal.queue_options.anthropic_q]
-start_to_close_timeout = "0:05:00"
-heartbeat_timeout = "0:01:00" # only meaningful for activities that emit heartbeats — see "Heartbeats — deferred"
-# Anthropic 429-aware retry: longer max_interval, more attempts.
-[temporal.queue_options.anthropic_q.retry_policy_config]
-initial_interval = "0:00:05"
-backoff_coefficient = 2.0
-maximum_interval = "0:02:00"
-maximum_attempts = 6
-# Additive on top of worker_config baseline. Use for backend-specific 4xx classes
-# (e.g. AnthropicBadRequestError, OpenAIContentFilterError) that should never retry.
-non_retryable_error_types_extra = []
-
-# Queue-level rate limit. Cluster-wide, server-enforced. Any worker that polls
-# this queue conveys this value at startup; the latest one wins on the server.
-# Pipelex requires consistent values across all workers on the same queue
-# (validated at startup).
-max_task_queue_activities_per_second = 50
-
-[temporal.queue_options.openai_q]
-start_to_close_timeout = "0:05:00"
-max_task_queue_activities_per_second = 80
-
-[temporal.queue_options.image_gen_q]
-start_to_close_timeout = "0:10:00"
-[temporal.queue_options.image_gen_q.retry_policy_config]
-initial_interval = "0:00:10"
-backoff_coefficient = 2.0
-maximum_interval = "0:05:00"
-maximum_attempts = 4
-
-[temporal.queue_options.extract_q]
-start_to_close_timeout = "0:30:00" # extract can be slow
-
-####################################################################################################
-# Worker-runtime profiles (NEW)
-####################################################################################################
-
-# A profile bundles every Worker(...) tuning knob. The worker process selects
-# one at startup via --profile.
-[temporal.worker_runtime_profiles.default]
-tuning_mode = "explicit" # only "explicit" is implemented in v2; "resource_based" is reserved for a future iteration
-max_cached_workflows = 10000
-max_concurrent_workflow_tasks = 1000
-max_concurrent_activities = 1000
-max_concurrent_local_activities = 1000
-max_concurrent_workflow_task_polls = 100
-max_concurrent_activity_task_polls = 100
-max_activities_per_second = 1000 # worker-local rate limit
-sticky_queue_schedule_to_start_timeout = "0:30:00"
-max_heartbeat_throttle_interval = "1:00:00"
-default_heartbeat_throttle_interval = "1:00:00"
-graceful_shutdown_timeout = "0:30:00"
-
-[temporal.worker_runtime_profiles.anthropic-tier4]
-max_concurrent_activities = 100
-max_activities_per_second = 60 # ~match Anthropic tier
-max_concurrent_activity_task_polls = 20
-# everything else inherits from worker_runtime_profiles.default
-
-[temporal.worker_runtime_profiles.image-gen-heavy]
-max_concurrent_activities = 4 # small parallelism, large payloads
-max_activities_per_second = 4
-graceful_shutdown_timeout = "0:10:00"
-
-[temporal.worker_runtime_profiles.jinja2-burst]
-max_concurrent_activities = 200 # cheap, fast
-max_activities_per_second = 5000
-
-[temporal.worker_runtime_profiles.router]
-max_concurrent_activities = 0 # workflow-only worker; counterpart of runners
-max_concurrent_workflow_tasks = 500
-
-# selected if --profile not passed at startup
-default_profile = "default"
-
-####################################################################################################
-# Worker registration scopes (v1 — unchanged)
-####################################################################################################
-
-[temporal.worker_scopes]
-default_scope = "full"
-# Pipelex SHOULD ship at least these specialized scopes (in addition to full/router/runner)
-# so each "runner" worker process only registers the activities it actually handles:
-# - runner-llm (LLM activities only)
-# - runner-img-gen (image-gen activities only)
-# - runner-extract (extract activities only)
-# - runner-jinja2 (jinja2 activities only)
-# These are simple additions to worker_scopes.scopes and don't require any code changes.
-
-####################################################################################################
-# Logging (one new flag for v2)
-####################################################################################################
-
-[temporal.temporal_config.temporal_log_config]
-# ... existing flags unchanged ...
-is_dispatch_resolution_traced = false # NEW. When true, every workflow.execute_activity dispatch logs
- # the resolved queue + start_to_close_timeout + retry_policy and
- # the layer each value came from (baseline / queue_options / handle_options).
- # Off by default — verbose. Turn on when debugging mis-tuned timeouts.
-```
-
-### Pydantic shapes
-
-```python
-# config_temporal.py
-
-class QueueOptions(ConfigModel):
- """Per-queue submitter options + queue-level rate limit.
-
- Resolution order at dispatch (for timeouts and retry):
- per-handle override (handle_options.<handle>) →
- this (queue_options[resolved_queue]) →
- worker_config defaults.
-
- Note: `heartbeat_timeout` lives here (queue scope) because heartbeat cadence
- is a property of the backend on the other side of the queue. It is NOT on
- `HandleOptions`. If a single model on a backend ever needs a different
- cadence, add the field to `HandleOptions` then — schema change is one line.
- """
-
- start_to_close_timeout: timedelta | None = Field(default=None, strict=False)
- schedule_to_close_timeout: timedelta | None = Field(default=None, strict=False)
- schedule_to_start_timeout: timedelta | None = Field(default=None, strict=False)
- heartbeat_timeout: timedelta | None = Field(default=None, strict=False)
- retry_policy_config: RetryPolicyConfig | None = None
- # Cluster-wide queue rate limit, conveyed to server by every worker on this queue.
- max_task_queue_activities_per_second: float | None = None
-
-
-class HandleOptions(ConfigModel):
- """Per-handle option overrides. Layers on top of QueueOptions for the resolved queue.
-
- Deliberately narrow: only timeout and retry. Heartbeat is queue-level.
- Other fields will be added on demand when a real case surfaces.
- """
-
- start_to_close_timeout: timedelta | None = Field(default=None, strict=False)
- retry_policy_config: RetryPolicyConfig | None = None
-
-
-class ActivityRouteConfig(ConfigModel):
- """Per-activity routing entry. v1 fields preserved; handle_options added."""
-
- default: str
- by_handle: dict[str, str] = Field(default_factory=dict)
- handle_options: dict[str, HandleOptions] = Field(default_factory=dict) # NEW
-
-
-class WorkerTuningMode(StrEnum):
- """How a worker scales its slot counts.
-
- Only EXPLICIT is implemented in v2. RESOURCE_BASED is reserved for a future
- iteration (Temporal SDK's `WorkerTuner.create_resource_based`). Defined now
- so the profile schema doesn't break when we add it.
- """
-
- EXPLICIT = "explicit"
- RESOURCE_BASED = "resource_based"
-
-
-class WorkerRuntimeProfile(ConfigModel):
- """Bundle of Worker(...) constructor tuning. One worker process selects one profile.
-
- `tuning_mode` MUST be `"explicit"` in v2. A model_validator rejects
- `"resource_based"` with a clear "not implemented yet" message until the
- follow-up iteration ships the resource-based path.
- """
-
- tuning_mode: WorkerTuningMode = Field(strict=False)
- max_cached_workflows: int
- max_concurrent_workflow_tasks: int
- max_concurrent_activities: int
- max_concurrent_local_activities: int
- max_concurrent_workflow_task_polls: int
- max_concurrent_activity_task_polls: int
- max_activities_per_second: float # worker-local cap
- sticky_queue_schedule_to_start_timeout: timedelta = Field(strict=False)
- max_heartbeat_throttle_interval: timedelta = Field(strict=False)
- default_heartbeat_throttle_interval: timedelta = Field(strict=False)
- graceful_shutdown_timeout: timedelta = Field(strict=False)
-
- @model_validator(mode="after")
- def reject_unimplemented_tuning_mode(self) -> Self:
- match self.tuning_mode:
- case WorkerTuningMode.EXPLICIT:
- return self
- case WorkerTuningMode.RESOURCE_BASED:
- msg = "tuning_mode='resource_based' is reserved but not implemented in v2; use 'explicit'."
- raise TemporalConfigError(msg)
-
-
-class WorkerRuntimeProfilesConfig(ConfigModel):
- """Named worker-runtime profiles selectable via --profile on the worker CLI."""
-
- default_profile: str
- profiles: dict[str, WorkerRuntimeProfile]
-
- @model_validator(mode="after")
- def validate_default_profile(self) -> Self:
- if self.default_profile not in self.profiles:
- msg = f"default_profile '{self.default_profile}' not in profiles (known: {sorted(self.profiles.keys())})"
- raise TemporalConfigError(msg)
- return self
-
-
-class WorkerConfig(ConfigModel):
- """Submitter-side defaults plus the worker's home queue."""
-
- default_task_queue: str # renamed from `task_queue` for clarity
- activity_queues: dict[str, ActivityRouteConfig]
- workflow_execution_timeout: timedelta = Field(strict=False)
- run_timeout: timedelta | None = Field(default=None, strict=False)
- task_timeout: timedelta | None = Field(default=None, strict=False)
- start_delay: timedelta | None = Field(default=None, strict=False)
- rpc_timeout: timedelta | None = Field(default=None, strict=False)
- default_activity_start_to_close_timeout: timedelta = Field(strict=False) # NEW
- default_activity_heartbeat_timeout: timedelta | None = Field(default=None, strict=False) # NEW
- retry_policy_config: RetryPolicyConfig # baseline
-
-
-class Temporal(ConfigModel):
- is_enabled: bool
- temporal_config: TemporalConfig
- worker_config: WorkerConfig
- queue_options: dict[str, QueueOptions] # NEW
- worker_runtime_profiles: WorkerRuntimeProfilesConfig # NEW
- worker_scopes: WorkerScopesConfig
- payload_codec_config: PayloadCodecConfig
-```
-
-## Resolution chain
-
-### Submitter side — `resolve_dispatch(activity_name, routing_key)`
-
-Returns a `DispatchOptions` bundle (`task_queue`, `start_to_close_timeout`, `retry_policy`, …) that the workflow passes verbatim to `workflow.execute_activity(...)`.
-
-```
-resolve queue:
- 1. activity_queues[activity_name].by_handle[routing_key] → use it
- 2. activity_queues[activity_name].default → use it
- 3. worker_config.default_task_queue → use it
-
-resolve timeouts and retry (independent of step above):
- start_with worker_config.{default_activity_start_to_close_timeout, retry_policy_config baseline}
- if queue_options[resolved_queue] exists:
- overlay its non-None fields (last-wins for scalars)
- if activity_queues[activity_name].handle_options[routing_key] exists:
- overlay its non-None fields (last-wins for scalars)
-```
-
-Three deterministic layers, in the same shape the v1 routing chain already uses. The key invariant: **every value has a clear, single source of truth** for any given `(activity_name, routing_key)` pair.
-
-**One exception to last-wins: `non_retryable_error_types`.** This list composes **additively** across layers:
-
-```
-final non_retryable_error_types =
- worker_config.retry_policy_config.non_retryable_error_types
- ∪ queue_options[resolved_queue].retry_policy_config.non_retryable_error_types_extra
- ∪ activity_queues[…].handle_options[…].retry_policy_config.non_retryable_error_types_extra (rare)
-```
-
-Rationale: this list is a safety brake against retry storms. The risk of *accidentally dropping* a baseline non-retryable (e.g. `ValidationError`) on one queue and retrying bad input forever is worse than the inconvenience of being unable to *remove* an entry per-queue. The expected use is backend-specific 4xx errors (e.g. `AnthropicBadRequestError`, `OpenAIContentFilterError`) — purely additive. If a real "must downgrade a baseline non-retryable on one queue" case ever appears, we can add a `non_retryable_error_types_remove` list later.
-
-Replaces every direct `worker_config.retry_policy` / `worker_config.workflow_execution_timeout` read at dispatch sites. One method on `WorkerConfig` returns the bundle.
-
-### Worker side — `resolve_runtime_profile(profile_name | None)`
-
-```
-profile_name or worker_runtime_profiles.default_profile → the WorkerRuntimeProfile
-```
-
-The worker process composes:
-
-```python
-runtime_profile = resolve_runtime_profile(args.profile)
-queue_opts = get_config().temporal.queue_options.get(args.task_queue)
-
-worker = Worker(
- client,
- task_queue=args.task_queue,
- workflows=workflows,
- activities=activities,
- # from runtime_profile (worker-local):
- max_concurrent_activities=runtime_profile.max_concurrent_activities,
- max_activities_per_second=runtime_profile.max_activities_per_second,
- max_concurrent_workflow_tasks=runtime_profile.max_concurrent_workflow_tasks,
- # …all the others…
- # from queue_options (cluster-wide, attached to the queue this worker polls):
- max_task_queue_activities_per_second=(
- queue_opts.max_task_queue_activities_per_second if queue_opts else None
- ),
-)
-```
-
-## CLI
-
-`pipelex worker` gains a `--profile` flag.
-
-```bash
-pipelex worker # uses default_profile + default_scope + default_task_queue
-pipelex worker --profile anthropic-tier4 --scope runner-llm --task-queue anthropic_q
-pipelex worker --profile image-gen-heavy --scope runner-img-gen --task-queue image_gen_q
-pipelex worker --profile router --scope router --task-queue temporal_task_queue
-```
-
-Three orthogonal axes:
-
-| Flag | Selects from | Controls |
-| --- | --- | --- |
-| `--scope` | `worker_scopes.scopes` | Which workflows/activities this process **registers** |
-| `--profile` | `worker_runtime_profiles.profiles` | How the `Worker(...)` is **tuned** |
-| `--task-queue` | (free string) | Which queue this worker **polls** |
-
-The fourth dimension — what server to connect to — already lives in `temporal.temporal_config.selected_server` (and is process-wide). Not a per-worker flag because typical deployments connect every worker in a cluster to the same Temporal server. Override that via env override on `selected_server` if needed.
-
-## Startup validation
-
-Two layers — one lenient (catches likely typos), one strict (catches the CLI-side typo that would silently misroute traffic).
-
-**Lenient (warn, don't fail).** When the config loads, for every queue name referenced in `activity_queues.*.default` and `activity_queues.*.by_handle.*` that has no corresponding `queue_options.<queue>` entry, log a WARN:
-
-```
-WARN temporal: queue 'anthrpic_q' is referenced by activity_queues.act_llm_gen_text.by_handle["claude-opus-4-7"] but has no queue_options entry — it will use worker_config defaults. Typo?
-```
-
-Rationale: a queue ridding worker_config defaults is a legitimate state (small deployments don't need per-queue tuning), so this isn't a fatal error. But the message is loud enough that typos surface in CI / on first boot.
-
-**Strict (fail at worker startup).** When `pipelex worker --task-queue <X>` is invoked, refuse to start if `<X>` doesn't appear in **any** of:
-
-- `worker_config.default_task_queue`
-- `activity_queues.*.default`
-- `activity_queues.*.by_handle.*`
-- `queue_options.*`
-
-Rationale: a worker polling a queue that nothing routes to is a typo. The runtime can't *detect* that no activity will ever land — it would just sit there idle. Fast-fail at boot:
-
-```
-ERROR temporal: --task-queue 'anthrpic_q' is not referenced by any routing or options entry.
- Known queues: ['temporal_task_queue', 'anthropic_q', 'openai_q', 'image_gen_q', 'extract_q']
- Did you mean 'anthropic_q'?
-```
-
-The "did you mean" suggestion uses simple Levenshtein matching against the known-queue set.
-
-**Not validated at startup** (deferred): "every named queue has at least one worker polling it." That requires a deployment registry the Pipelex runtime doesn't have. An operator who wants this check can add a pre-deploy step that diffs their docker-compose / k8s manifest against the TOML.
-
-## Deployment manifest shape
-
-A docker-compose excerpt (illustrative — Pipelex doesn't own the orchestrator config; this is what an operator writes):
-
-```yaml
-services:
- router:
- image: my-org/pipelex:latest
- command: pipelex worker --profile router --scope router --task-queue temporal_task_queue
- deploy: { replicas: 2 }
-
- worker-llm-anthropic:
- image: my-org/pipelex:latest
- command: pipelex worker --profile anthropic-tier4 --scope runner-llm --task-queue anthropic_q
- deploy: { replicas: 3 }
-
- worker-llm-openai:
- image: my-org/pipelex:latest
- command: pipelex worker --profile openai-tier5 --scope runner-llm --task-queue openai_q
- deploy: { replicas: 2 }
-
- worker-img-gen:
- image: my-org/pipelex:latest
- command: pipelex worker --profile image-gen-heavy --scope runner-img-gen --task-queue image_gen_q
- deploy: { replicas: 1, resources: { reservations: { devices: [{ capabilities: [gpu] }] } } }
-
- worker-extract:
- image: my-org/pipelex:latest
- command: pipelex worker --profile extract-batch --scope runner-extract --task-queue extract_q
- deploy: { replicas: 2 }
-
- worker-jinja2:
- image: my-org/pipelex:latest
- command: pipelex worker --profile jinja2-burst --scope runner-jinja2 --task-queue temporal_task_queue
- deploy: { replicas: 1 }
-```
-
-The TOML file declares the named knobs. The manifest declares the deployment shape. Neither knows about the other.
-
-## Local testing via `/temporal-e2e-validate`
-
-The existing skill already runs the 3-process topology (server + worker + submitter). v2 needs:
-
-- A new test scenario in the skill that boots **multiple workers** with different `--profile` / `--scope` / `--task-queue` combinations, then submits work whose `(activity_name, handle)` pairs route to each queue, and verifies each activity executed on the worker registered for it.
-- Per-queue option assertions: schedule an activity that would time out on the default budget but succeeds with the `extract_q` budget; confirm the workflow used the queue-resolved timeout.
-- Rate-limit assertion: schedule a burst, confirm the worker-local cap or server-side cap actually throttles (a tight burst above `max_activities_per_second` should produce visible `schedule_to_start` latency — assert through workflow history events, not wall-clock).
-- A negative scenario: misconfigured worker (queue declared in TOML but no worker polling it) — the submitter should report a clear `schedule_to_start` timeout, not hang silently. (We may add an optional **startup validator** that checks "every queue named in `queue_options` or `activity_queues.*.default/by_handle` is polled by at least one declared worker in a manifest registry" — but that requires a deployment registry, which is out of scope for v2 unless the operator opts in.)
-
-The 3-process test already proves the cross-worker hop is real. v2 extends it to a 5-process test (1 router + N runner profiles + 1 submitter) so we know per-queue options and per-profile tuning flow correctly end-to-end.
-
-## Heartbeats — deferred (raised here for planning)
-
-`heartbeat_timeout` ships on `QueueOptions` in v2 so the schema is ready, but **no current Pipelex activity actually emits heartbeats**. Temporal heartbeats are explicit: the activity code calls `activity.heartbeat(...)` in its loop, and if no heartbeat arrives within `heartbeat_timeout`, Temporal reschedules the activity (assuming worker death). Setting `heartbeat_timeout` on an activity that doesn't heartbeat does nothing useful.
-
-Activities that *could* meaningfully heartbeat:
-
-- **Anthropic LLM (streaming)** — `act_llm_gen_text` / `act_llm_gen_object` on streaming backends. Could emit one heartbeat per chunk or every N tokens. Detects dead workers within seconds instead of waiting for `start_to_close_timeout`.
-- **Image generation with polling backends** (Fal-style "is it done yet" loops). One heartbeat per poll cycle.
-- **Extract on batch backends** if they expose progress callbacks.
-
-Activities that **cannot** heartbeat without changing their shape: anything that's "send one HTTP request, await one response." That's most of our LLM activities today (non-streaming OpenAI, non-streaming Anthropic, non-streaming Gemini, etc.). Adding heartbeats there would require interleaving a heartbeat task alongside the HTTP call, which is plausible but invasive.
-
-**v2 leaves the call sites untouched.** The schema field exists, queue_options can set the timeout, but until call sites are wired up, the value has no effect.
-
-**Planning hint for a future pass:**
-
-1. Decide the cadence policy per queue. E.g. `anthropic_q`: heartbeat every 5s (covers streaming dropouts); `image_gen_q`: heartbeat every 30s (covers Fal polling).
-2. Identify the activities that have a natural loop. Modify them to call `activity.heartbeat(progress_info)` inside the loop.
-3. For activities without a natural loop, decide whether to spin a background heartbeat task during the request (a small async helper around the HTTP call). Probably not worth it for fast LLM calls; possibly worth it for slow extract batch jobs.
-4. Tune `max_heartbeat_throttle_interval` and `default_heartbeat_throttle_interval` on the worker side (already in `WorkerRuntimeProfile`) so the throttling matches the call-site cadence.
-
-This is its own design pass. v2 just ensures the config surface won't have to change when we get to it.
-
-## Migration
-
-Breaking, single-step (per project policy: no compat shims). For each existing client config:
-
-| Before | After |
-| --- | --- |
-| `[temporal.worker_config].task_queue` | `[temporal.worker_config].default_task_queue` |
-| `[temporal.worker_config].workflow_execution_timeout` doubling as activity timeout | New `[temporal.worker_config].default_activity_start_to_close_timeout`; existing `workflow_execution_timeout` reverts to its real meaning |
-| Hardcoded `max_*` in `make_worker` (`temporal_task_manager.py:120-138`) | `[temporal.worker_runtime_profiles.default]` (ship with current values as the default profile) |
-| `pipelex/temporal/wrapper/activity.py` (`start_tprl_activity`) | **Delete the file.** Confirmed zero callers. Not part of any current dispatch path. |
-
-A migration map entry under `[migration.migration_maps.temporal]` renames the `task_queue` key automatically. The new fields have explicit defaults shipped in `pipelex/pipelex.toml`. Client `.pipelex/pipelex.toml` files that previously overrode `task_queue` need a one-line edit.
-
-## Decisions taken
-
-All six original open questions are resolved.
-
-1. **Heartbeat timeout granularity.** `heartbeat_timeout` lives on `QueueOptions` only. Not on `HandleOptions` — backend rhythm is a queue-scope property. Per-handle override can be added later if a single model on a backend ever needs a different cadence; schema change is one line. See **Heartbeats — deferred** above for the broader picture: the *call sites* that actually emit heartbeats aren't in scope for v2; this design only ships the configuration surface.
-2. **`non_retryable_error_types` composition.** Additive across layers. Per-queue and per-handle layers contribute `non_retryable_error_types_extra` lists that union with the worker_config baseline. The safety-leaning default; matches the realistic use case (backend-specific 4xx classes).
-3. **Startup validation.** Two-layer:
- - **WARN** on routing entries that reference a queue with no `queue_options` entry (lenient — a queue ridding worker_config defaults is legitimate).
- - **FAIL** on `pipelex worker --task-queue X` when `X` doesn't appear anywhere in routing/options/default queue (strict — catches CLI typos that would silently misroute traffic). Error message includes a "did you mean?" suggestion.
-4. **Resource-based tuning.** Reserved as `WorkerTuningMode.RESOURCE_BASED` in the enum but rejected by a `@model_validator` in v2 with a clear "not implemented yet" message. Ships only `tuning_mode = "explicit"`. Adding the resource-based path later won't break the schema.
-5. **Per-worker server override.** Not added. Process-wide `temporal.temporal_config.selected_server` stays the only knob. Adding the CLI flag now would freeze surface we don't need.
-6. **Pretty resolver tracing.** Add behind a new `temporal_log_config.is_dispatch_resolution_traced` flag, **off by default**. When on, each `workflow.execute_activity` dispatch logs the resolved queue + start_to_close_timeout + retry_policy and the layer each value came from (baseline / queue_options / handle_options). Verbose but invaluable when a timeout is mis-tuned.
-
-## What this does *not* change
-
-- The `temporal-e2e-validate` skill's overall execution model.
-- `worker_scopes` registration logic (v1).
-- `activity_queues` routing logic (v1) — `by_handle` keys still resolve to plain queue names; `handle_options` is a sibling table.
-- The payload codec, server connection, log config sections.
-- The `make_temporal_pipe_router` factory shape (it'll just consume the new resolver internally).
diff --git a/wip/archive/raw-working-memory-through-act_deliver-DONE.md b/wip/archive/raw-working-memory-through-act_deliver-DONE.md
deleted file mode 100644
index 04bb55343..000000000
--- a/wip/archive/raw-working-memory-through-act_deliver-DONE.md
+++ /dev/null
@@ -1,143 +0,0 @@
-# TODO: Raw `working_memory` end-to-end through `act_deliver`
-
-> Goal: make distributed Temporal correct AND remove the global-registry-propagation hack.
-
----
-
-## Background — why this work exists
-
-### What's currently in place
-
-The Temporal pipe layer ships user-defined dynamic concept classes through workflow boundaries via two mechanisms:
-
-1. **`LibraryCrate` riding on `PipeJob`.** The crate (qualified concept/pipe blueprints + source) is a Pydantic field on `PipeJob` (`pipelex/pipe_run/pipe_job.py:20`). It's serialized inside the workflow input. Whichever worker picks up `WfPipeRouter` re-loads the crate locally: opens a per-workflow `ClassRegistry`, sets a `_library_id` `ContextVar`, calls `library_manager.load_from_crate(...)`, which `exec`s the dynamic Python source and registers the resulting classes (`pipelex/temporal/tprl_pipe/wf_pipe_router.py:51-69`).
-
-2. **Dehydrate-to-raw-dict at workflow boundaries.** `WorkingMemory.dump_for_temporal()` (`pipelex/core/memory/working_memory.py:472-495`) serializes the working memory tree to a plain dict, embedding `__class__` and `__module__` metadata on every `ListContent` item. `PipeJob.prepare_for_temporal()` and `PipeOutput.prepare_for_temporal()` use this so the wire form is registry-free. The receiving worker calls `hydrate_working_memory(raw)` (`pipelex/temporal/tprl_pipe/hydration.py`) to rebuild typed `Stuff`/`StuffContent` instances using `get_class_registry()`.
-
-3. **Two patches in `hydration.py` worth knowing about:**
- - `_validate_as_known_class` round-trips through `model_dump()` to defeat cross-exec class-identity mismatches (kajson eagerly rebuilds instances from `__class__` metadata using one class identity, then `load_from_crate` re-execs the source and replaces the registry entry with a new identity — same name, different `id()` — and Pydantic's `model_validate` would otherwise reject the older instance).
- - `_hydrate_list_item` handles `Anything[]` lists by reading per-item `__class__` metadata, falling back to `TextContent`.
-
-4. **`Optional[BaseModel]` payload converter fix** (`pipelex/temporal/temporal_data_converter.py:107-121, 133-135`): added so `PipeOutput.graph_spec: GraphSpec | None` deserializes via kajson instead of falling through to the default JSON path.
-
-5. **Schema-to-model enum forward-refs fix** (`pipelex/cogt/content_generation/schema_to_model.py:120-122`): `model_rebuild` now uses *all* generated types (models + enums), so forward references to dynamically generated `Enum` classes resolve correctly.
-
-6. **The propagation hack** (`pipelex/temporal/tprl_pipe/wf_pipe_router.py:71-80`): after loading the crate into the per-workflow registry, copies all dynamic classes into the worker process's *global* `KajsonManager` registry. The stated reason: child workflows and activities don't see the per-workflow `ContextVar`, so they need the global to be primed.
-
-### The cogt layer uses a fundamentally different (better) pattern
-
-`pipelex/temporal/tprl_content_generation/*` ships dynamic classes via JSON schema in the assignment (e.g. `ObjectAssignment.object_class_schema`). The receiving side calls `model_class_from_json_schema(...)` (`pipelex/cogt/content_generation/schema_to_model.py:24-49`) which `exec`s the generated source on the fly. The reconstructed class carries `__kajson_class_source__` as a class attribute. The Temporal payload converter (`pipelex/temporal/temporal_data_converter.py:60-79`) embeds that source in payload metadata as `kajson_class_source`. On the receiving worker, `kajson.loads(..., class_source_code=...)` exec's the source into a temporary `ClassRegistry` (`kajson/kajson.py:141-159`) merged with the explicit registry. Result: **payloads are self-describing; no registry coordination across workers.** This is independent of the LibraryCrate path and is not affected by this change.
-
-### Why the propagation hack breaks in distributed Temporal
-
-A worker is a process polling a task queue. In distributed deployments multiple workers poll the same queue and any of them can pick up a child workflow or activity. ContextVars don't cross processes. So:
-
-| Hop | Crosses worker? | Receiver has dynamic classes? |
-| --- | --- | --- |
-| User submitter → `WfPipeRouter` (top-level) | yes | yes — `WfPipeRouter` re-loads the crate from `PipeJob.library_crate` on its own worker |
-| `WfPipeRun` parent → child `WfPipeRouter` | possibly different worker | yes — child gets the same `PipeJob` carrying the crate, re-loads on its worker |
-| Child `WfPipeRouter` → `WfPipeRun` parent (rehydrate at `wf_pipe_run.py:50-52`) | possibly different worker | **NO — this is the bug.** `WfPipeRun` never opens its own per-workflow library. `hydrate_working_memory` falls back to the parent's global registry, which only has classes if the propagation hack ran on the *same* worker that the parent happens to be on. |
-| `WfPipeRun` → `act_deliver` activity | possibly different worker | **NO.** The activity receives a typed `pipe_output` (because parent rehydrated). The activity worker's global registry doesn't have the crate. |
-| `WfPipeRouter` → `act_flush_trace_events` | possibly different worker | safe — only ships `TraceEvent` (built-in) |
-| `WfPipeRun` → `act_assemble_graph` | possibly different worker | safe — only ships scalar IDs |
-| All cogt boundaries | possibly different worker | safe — `__kajson_class_source__` mechanism |
-
-So the entire problem reduces to **two lines**: the parent-side rehydrate at `wf_pipe_run.py:50-52`. Remove it and `act_deliver` naturally receives the raw dict; the propagation hack has no remaining customer and gets deleted.
-
-### Drawbacks of "raw end-to-end" (already discussed and accepted)
-
-- **D1 — typed rendering for dynamic concepts is lost.** Built-in `StuffContent` subclasses (`ImageContent`, `PdfContent`, `MermaidContent`, `HtmlContent`, `TextContent`, `NumberContent`) are statically registered on every worker, so they can be rehydrated locally from `__class__` metadata. User-defined dynamic concepts fall back to a generic field-walking render (JSON-in-markdown / `<pre>`-in-HTML). User: **accepted**.
-- **D2 — dual rendering path in `DeliveryExecutor`** (typed when `working_memory` is set, raw-dict when `working_memory_raw` is set). Mirrors the existing `working_memory` / `working_memory_raw` dual field on `PipeJob` and `PipeOutput`. User: **accepted (already a known pattern)**.
-- **D3 — fix is delivery-scoped.** Other consumers of typed dynamic classes still need the crate. We confirmed (Explore agent enumeration) that no other consumers exist on the Temporal hot path; the cogt layer is independent. User: **OK, focus on delivery; flag others if any (none found)**.
-- **D4 — `model_dump` subtleties.** `dump_for_temporal()` and `smart_dump()` already use `serialize_as_any=True`, so subclass-specific fields and computed fields are preserved. User: **noted**.
-- **D5 — debuggability loss** (raw dict instead of typed `__repr__` inside the activity). User: **accepted**.
-
----
-
-## Plan
-
-### 1. Stop the parent rehydrate — `pipelex/temporal/tprl_pipe/wf_pipe_run.py`
-
-- Remove lines 49-52 (the `if pipe_output.working_memory_raw is not None: pipe_output.working_memory = hydrate_working_memory(...)`).
-- Forward `pipe_output` to `act_deliver` with `working_memory_raw` populated and `working_memory=None`.
-- Remove the now-unused `hydrate_working_memory` import.
-
-### 2. Delete the global-registry-propagation block — `pipelex/temporal/tprl_pipe/wf_pipe_router.py`
-
-- Delete lines 71-80 (`# 4. Propagate dynamic classes to global registry...`).
-- Renumber the trailing comment "5. Hydrate WorkingMemory" → "4." for consistency.
-- The internal `hydrate_working_memory(workflow_arg.working_memory_raw)` at line 84 still works because the `_library_id` `ContextVar` is set just above (line 66) and `get_class_registry()` (`pipelex/hub.py:397-408`) routes to the per-workflow registry.
-
-### 3. Make `DeliveryExecutor` accept either typed or raw `WorkingMemory` — `pipelex/pipe_run/delivery_executor.py`
-
-`pipe_output.working_memory` may now be `None` while `pipe_output.working_memory_raw` is populated. `DeliveryExecutor.execute` and the helpers (`generate_result_files`, `_generate_main_stuff_files`, `_store_results`) need to branch on which field is populated.
-
-Rendering policy per file:
-
-| File | Typed path (today) | Raw-dict path (new) |
-| --- | --- | --- |
-| `working_memory.json` | `working_memory.smart_dump()` | `clean_json_dumps(working_memory_raw)` directly — already a dict produced by `dump_for_temporal()` |
-| `main_stuff.json` | `main_stuff.content.rendered_json_async()` | extract main stuff dict from raw root by alias name; `clean_json_dumps` it |
-| `main_stuff.md` / `.html` / `viewer.html` | `rendered_markdown_async()` / `rendered_html_async()` / `render_stuff_viewer()` | locally rehydrate the *single* main stuff using `__class__` lookup in the **global** registry (built-ins always present); on success, call existing typed renderers. On lookup miss (dynamic concept class not registered locally), fall back to a generic field-walking render that just dumps the dict as pretty JSON-in-markdown / `<pre>`-in-HTML. |
-| `graphspec.json` / `mermaidflow.*` / `reactflow.html` | unchanged — `graph_spec` is independent of working_memory | unchanged |
-
-Implementation note: introduce a small private helper `_local_hydrate_main_stuff(raw_root: dict, main_stuff_name: str) -> Stuff | None` that tries `Stuff.model_validate` against the registry's `__class__`-named class for the content, returning `None` if the class isn't locally available. Isolates the fallback decision in one place.
-
-### 4. Verify-only (no change)
-
-- `pipelex/temporal/tprl_pipe/wf_pipe_router.py:202-204` — `prepare_for_temporal()` on return when `library_crate is not None`. Keep — still correct for the WfPipeRouter→WfPipeRun edge.
-- `pipelex/temporal/tprl_pipe/temporal_pipe_router.py:84-86` — top-level caller rehydrate. Keep — runs in the submitter's process which already has the classes loaded.
-
-### 5. Tests
-
-The repo has a Temporal-distributed validation harness — invoke the `temporal-e2e-validate` skill (true 3-process setup: server + worker + submitter, validates cross-process topology).
-
-**Deterministic repro is now wired in.** Recent (staged) work added:
-
-- **Worker scope split** (`pipelex/pipelex.toml:528-560`, `pipelex/temporal/config_temporal.py:59-91`, `pipelex/temporal/worker_cli.py`): named scopes `router` (`disable_all_activities=true`) and `runner` (`disable_all_workflows=true`) selectable via `--scope`. Two scoped workers on the same `temporal_task_queue` force every activity to be picked up by a different Python process than the workflow that scheduled it, making cross-process registry hops deterministic instead of probabilistic.
-- **Repro script** `.claude/skills/temporal-e2e-validate/scripts/repro_runner_registry_bug.py`: mirrors the cloud / `start_pipeline` + webhook submission path by attaching a `DeliveryAssignment(storage=StorageTarget())`. This makes `wf_pipe_run.py:79-96` schedule `act_deliver` on the runner with hydrated `pipe_output`. Plain `pipelex run bundle` does **not** trigger this — without a `delivery_assignment`, `act_deliver` is skipped and the runner only ever sees trace/graph activity payloads (no dynamic-class decoding).
-- **In-process scope test** `tests/integration/pipelex/temporal/library_crate/test_distributed_scopes.py`: validates the scope mechanism resolves correctly (cannot reproduce the cross-process bug because both workers share the same `KajsonManager`; documented in the test's module docstring).
-
-Currently observable failure (with the parent rehydrate at `wf_pipe_run.py:50-52` still in place) when running the repro script against router+runner:
-
-```
-KajsonDecoderError: Class '<bundle>__<DynamicConcept>' not found
- in module 'builtins' or global registry
-ApplicationError: Failed decoding arguments
- → temporalio/worker/_activity.py:566 (data_converter.decode_wrapper)
-```
-
-surfaced in the **runner** tmux session, raised by the activity worker before the `act_deliver` body runs. After the fix in steps 1–3, this should resolve to a successful `act_deliver` execution where the activity receives `working_memory_raw` (no class lookup needed).
-
-Add/extend:
-
-- Promote the repro script into a pytest case (or call it from one) that drives the deterministic 2-scope failure path and asserts success post-fix.
-- Verify `main_stuff.md` for a dynamic concept passes via the generic fallback path.
-- Regression test that distributed delivery does not import the dynamic concept module on the activity worker (e.g. run the activity worker process with a stripped library set, confirm no `ClassRegistry` lookup errors).
-- Existing crate isolation tests (`temporal-test-crate` skill) should continue to pass — and now be more strongly isolated since the propagation no longer pollutes the global.
-
----
-
-## Files to modify
-
-- `pipelex/temporal/tprl_pipe/wf_pipe_run.py` — drop parent rehydrate (lines 49-52), drop unused import.
-- `pipelex/temporal/tprl_pipe/wf_pipe_router.py` — delete propagation block (lines 71-80), tidy step comment.
-- `pipelex/pipe_run/delivery_executor.py` — dual-mode rendering; new `_local_hydrate_main_stuff` helper.
-- (tests) — extend the temporal-e2e harness; add a dynamic-concept delivery test.
-
-## Files to leave alone
-
-- `pipelex/temporal/temporal_data_converter.py` — `Optional[BaseModel]` and `BaseModel | list[BaseModel]` paths remain correct.
-- `pipelex/temporal/tprl_pipe/hydration.py` — still used by `WfPipeRouter` internally (per-workflow scope) and by `temporal_pipe_router.py` at the submitter side. Both contexts have the registry primed.
-- `pipelex/core/memory/working_memory.py` — `dump_for_temporal()` already preserves `__class__` metadata on `ListContent` items, which the local-hydrate fallback uses.
-- `pipelex/temporal/tprl_content_generation/*` — independent system (`__kajson_class_source__`).
-
----
-
-## Verification checklist
-
-1. `make agent-check` from `pipelex/` — type checks + linting clean.
-2. `make agent-test` from `pipelex/` — full unit/integration suite green.
-3. Deterministic distributed repro via `temporal-e2e-validate` Tier 2b (router + runner scoped workers + `repro_runner_registry_bug.py`) — runs end-to-end with a hydrated `pipe_output` reaching `act_deliver` on the runner, no `KajsonDecoderError`, no class lookup on the runner side. Activity worker never loads the crate.
-4. `temporal-test-crate` skill — concurrent workflows with conflicting concept names still produce correct outputs.
-5. Single-worker smoke: local `pipelex run` against a pipe using a dynamic concept; delivery files byte-equivalent for built-in content types and structurally-equivalent (JSON/MD/HTML) for dynamic concepts.
diff --git a/wip/archive/refactor-drop-text-then-object.html b/wip/archive/refactor-drop-text-then-object.html
deleted file mode 100644
index 6c9699c0b..000000000
--- a/wip/archive/refactor-drop-text-then-object.html
+++ /dev/null
@@ -1,468 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<title>PipeLLM refactor: dropping the text-then-object stack</title>
-<style>
- :root {
- --fg: #1f2328;
- --muted: #57606a;
- --border: #d0d7de;
- --bg-soft: #f6f8fa;
- --bg-info: #ddf4ff;
- --bg-warn: #fff8c5;
- --add-bg: #e6ffec;
- --add-fg: #1a7f37;
- --del-bg: #ffebe9;
- --del-fg: #cf222e;
- --accent: #0969da;
- --kept: #1a7f37;
- --gone: #cf222e;
- }
- * { box-sizing: border-box; }
- body {
- font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
- color: var(--fg);
- max-width: 980px;
- margin: 2.5rem auto;
- padding: 0 1.5rem;
- line-height: 1.55;
- }
- h1 { font-size: 1.9rem; margin-bottom: 0.25rem; }
- h2 { font-size: 1.4rem; margin-top: 2.5rem; padding-bottom: 0.25rem; border-bottom: 1px solid var(--border); }
- h3 { font-size: 1.1rem; margin-top: 1.5rem; }
- p { margin: 0.6rem 0; }
- code { font-family: "SF Mono", Menlo, Consolas, monospace; font-size: 0.9em; background: var(--bg-soft); padding: 0.1em 0.35em; border-radius: 4px; }
- pre { font-family: "SF Mono", Menlo, Consolas, monospace; font-size: 0.85em; background: var(--bg-soft); padding: 1rem 1.2rem; border-radius: 6px; overflow-x: auto; line-height: 1.45; }
- pre.diagram { background: #f6f8fa; border-left: 3px solid var(--accent); }
- .meta { color: var(--muted); font-size: 0.92rem; margin-top: 0; }
- .tldr {
- background: var(--bg-info);
- border-left: 4px solid var(--accent);
- padding: 0.9rem 1.2rem;
- border-radius: 0 6px 6px 0;
- margin: 1rem 0 2rem;
- }
- .tldr p { margin: 0.3rem 0; }
- .pill { display: inline-block; padding: 0.1em 0.6em; border-radius: 999px; font-size: 0.78em; font-weight: 600; }
- .pill-keep { background: #dafbe1; color: var(--kept); }
- .pill-drop { background: #ffebe9; color: var(--gone); }
- .pill-modify { background: #ddf4ff; color: var(--accent); }
- table { border-collapse: collapse; margin: 0.8rem 0; width: 100%; }
- th, td { padding: 0.55rem 0.85rem; text-align: left; border-bottom: 1px solid var(--border); vertical-align: top; }
- th { background: var(--bg-soft); font-weight: 600; }
- tr:last-child td { border-bottom: none; }
- /* unified diff */
- .diff { font-family: "SF Mono", Menlo, Consolas, monospace; font-size: 0.82em; background: #fff; border: 1px solid var(--border); border-radius: 6px; overflow: hidden; margin: 0.7rem 0; }
- .diff-header { background: var(--bg-soft); padding: 0.35rem 0.85rem; color: var(--muted); border-bottom: 1px solid var(--border); font-size: 0.85em; }
- .diff pre { margin: 0; background: transparent; padding: 0.5rem 0; border-radius: 0; }
- .diff .line { display: block; padding: 0 0.85rem; white-space: pre; }
- .diff .add { background: var(--add-bg); color: var(--add-fg); }
- .diff .del { background: var(--del-bg); color: var(--del-fg); }
- .diff .ctx { color: var(--fg); }
- .diff .hunk { color: var(--muted); background: var(--bg-soft); padding: 0.15em 0.85rem; }
- /* side-by-side */
- .side {
- display: grid;
- grid-template-columns: 1fr 1fr;
- gap: 1rem;
- margin: 0.8rem 0;
- }
- .side > div { background: var(--bg-soft); border-radius: 6px; padding: 0.9rem 1.1rem; }
- .side h4 { margin: 0 0 0.5rem; font-size: 0.92rem; color: var(--muted); text-transform: uppercase; letter-spacing: 0.04em; }
- .side pre { background: #fff; padding: 0.7rem 0.9rem; font-size: 0.82em; }
- .layer {
- border-left: 3px solid var(--border);
- padding: 0.4rem 0 0.4rem 1rem;
- margin: 0.6rem 0;
- }
- .layer.l1 { border-left-color: #0969da; }
- .layer.l2 { border-left-color: #1a7f37; }
- .layer.l3 { border-left-color: #d4a72c; }
- .layer.l4 { border-left-color: #bf3989; }
- .layer.l5 { border-left-color: #cf222e; }
- .layer h3 { margin-top: 0; }
- ul.tight { margin: 0.3rem 0 0.6rem 1.4rem; }
- ul.tight li { margin: 0.15rem 0; }
- details { margin: 0.5rem 0; }
- summary { cursor: pointer; font-weight: 600; color: var(--accent); }
- .stats {
- display: grid;
- grid-template-columns: repeat(4, 1fr);
- gap: 0.7rem;
- margin: 1rem 0;
- }
- .stat { background: var(--bg-soft); border-radius: 6px; padding: 0.7rem 0.9rem; text-align: center; }
- .stat .num { font-size: 1.6rem; font-weight: 700; color: var(--accent); display: block; }
- .stat .lbl { font-size: 0.8rem; color: var(--muted); }
- .note {
- background: var(--bg-warn);
- border-left: 4px solid #d4a72c;
- padding: 0.7rem 1rem;
- border-radius: 0 6px 6px 0;
- margin: 1rem 0;
- font-size: 0.93em;
- }
-</style>
-</head>
-<body>
-
-<header>
- <h1>PipeLLM refactor — dropping the text-then-object stack</h1>
- <p class="meta">Branch <code>refactor/Temporal-primitives</code> · ~770 net lines deleted across 32 files</p>
-</header>
-
-<div class="tldr">
- <p><strong>What.</strong> Removed the entire "text then object" structuring path from <code>PipeLLM</code> down through <code>cogt</code> and <code>Temporal</code>. The <code>StructuringMethod.PRELIMINARY_TEXT</code> enum value stays so a future implementation can opt in; selecting it at runtime now raises <code>NotImplementedError</code>.</p>
- <p><strong>Why.</strong> The mechanism produced a 4-way matrix in <code>PipeLLM._llm_gen_object_stuff_content</code> (single/list × direct/preliminary-text) plus <code>is_with_preliminary_text</code> plumbing that leaked into <code>PipeRunParams</code>, helpers, config, the cogt content-generator protocol, and four Temporal workflows. It's getting reimplemented later in a completely different way.</p>
- <p><strong>Impact.</strong> <code>PipeLLM</code>'s object branch collapses from 4 cases to 2. The cogt protocol thins by 2 methods, and the surviving pair gets renamed (<code>make_object_direct</code> → <code>make_object</code>, <code>make_object_list_direct</code> → <code>make_object_list</code>) — the <code>_direct</code> suffix existed only to contrast with the deleted <code>_text_then_object</code> variants. Two Temporal workflows go away. One config flag and three TOML templates go away. Pre-cleanup for the upcoming <code>collapse-content-generation-workflow-layer</code> refactor.</p>
-</div>
-
-<div class="stats">
- <div class="stat"><span class="num">35</span><span class="lbl">files modified</span></div>
- <div class="stat"><span class="num">−1006</span><span class="lbl">lines removed</span></div>
- <div class="stat"><span class="num">+158</span><span class="lbl">lines added</span></div>
- <div class="stat"><span class="num">5</span><span class="lbl">layers cleaned</span></div>
-</div>
-
-<h2>1 — The shape of the problem (before)</h2>
-
-<p>Before the refactor, when a PipeLLM had to produce a structured object, it could pick between two structuring methods. Both were live in code; the choice produced a 4-way matrix because each combined with the multiplicity (single object vs list).</p>
-
-<pre class="diagram">
-PipeLLM._live_run_operator_pipe(...)
- │
- ├─ derive is_with_preliminary_text from
- │ self.structuring_method == PRELIMINARY_TEXT
- │ OR get_config().pipelex.structure_config.is_default_text_then_structure
- │
- ├─ inject is_with_preliminary_text into PipeRunParams
- │
- ├─ build llm_prompt_2_factory ◄── extra factory only
- │ match self.structuring_method: for the second LLM call
- │ case DIRECT: llm_prompt_2_factory = None
- │ case PRELIMINARY_TEXT: llm_prompt_2_factory =
- │ LLMPromptTemplate.make_for_structuring_from_preliminary_text()
- │
- └─ _llm_gen_object_stuff_content(... llm_prompt_2_factory ...)
- │
- ├─ if is_multiple_output:
- │ ├─ if llm_prompt_2_factory: make_text_then_object_list ◄─┐
- │ └─ else: make_object_list_direct │ 4-way
- │ │ matrix
- └─ else (single): │
- ├─ if llm_prompt_2_factory: make_text_then_object ◄─┘
- └─ else: make_object_direct
-</pre>
-
-<p>Each <code>make_text_then_object*</code> call resolved through the <code>ContentGenerator</code> protocol, which had four implementations (direct, dry, Temporal child, Temporal top). Inside Temporal, those calls dispatched as their own child workflows (<code>WfMakeTextThenObject</code>, <code>WfMakeTextThenObjectList</code>) that ran two activities in sequence with a <code>LLMAssignmentFactory.make_llm_assignment(preliminary_text=…)</code> call between them.</p>
-
-<h2>2 — After</h2>
-
-<pre class="diagram">
-PipeLLM._live_run_operator_pipe(...)
- │
- ├─ if self.structuring_method == PRELIMINARY_TEXT:
- │ raise NotImplementedError(...) ◄── only guard at runtime
- │
- ├─ no is_with_preliminary_text plumbing
- │
- └─ _llm_gen_object_stuff_content(...)
- │
- ├─ if is_multiple_output: make_object_list ◄── 2 cases, flat
- └─ else: make_object ◄── "_direct" suffix dropped
- since there's no other way
-</pre>
-
-<p>The <code>StructuringMethod.PRELIMINARY_TEXT</code> enum value stays — pipes can still declare it. The runtime guard at the top of <code>_live_run_operator_pipe</code> is the only place that knows about it. Everything in the dotted path between PipeLLM and the activities is gone.</p>
-
-<h2>3 — The five layers we cleaned</h2>
-
-<div class="layer l1">
- <h3>Layer 1 · <code>PipeLLM</code> operator <span class="pill pill-modify">flatten</span></h3>
- <p>The central simplification. <code>pipe_llm.py</code> shed ~110 lines: the <code>is_with_preliminary_text</code> derivation, the <code>llm_prompt_2_factory</code> match block, two of the four branches in <code>_llm_gen_object_stuff_content</code>, the <code>"text_then_object"</code> string in the execution-data tracker, and unused imports of <code>LLMPromptFactoryAbstract</code> / <code>LLMPromptTemplate</code> / <code>cast</code>.</p>
-</div>
-
-<div class="layer l2">
- <h3>Layer 2 · <code>PipeRunParams</code> + <code>helpers.py</code> <span class="pill pill-modify">trim signatures</span></h3>
- <p><code>PipeRunParams.is_with_preliminary_text</code> field deleted. <code>PipeRunParams.copy_by_injecting_multiplicity</code> drops the kwarg. <code>helpers.get_output_structure_prompt</code> drops the parameter (used to pick between two TOML templates; now there's only one).</p>
-</div>
-
-<div class="layer l3">
- <h3>Layer 3 · cogt content-generator stack <span class="pill pill-drop">delete</span> <span class="pill pill-modify">rename</span></h3>
- <ul class="tight">
- <li><code>ContentGeneratorProtocol.make_text_then_object</code> + <code>make_text_then_object_list</code> — gone.</li>
- <li>Implementations in <code>ContentGenerator</code> (direct) and <code>ContentGeneratorDry</code> — gone.</li>
- <li><code>TextThenObjectAssignment</code> data class — gone.</li>
- <li><code>LLMAssignmentFactory</code> — gone (only used by the deleted text-then-object code).</li>
- <li><code>LLMPromptTemplate.make_for_structuring_from_preliminary_text()</code> classmethod — gone.</li>
- <li><strong>Renames:</strong> <code>make_object_direct</code> → <code>make_object</code>, <code>make_object_list_direct</code> → <code>make_object_list</code>. Propagated through all four protocol implementations, both Temporal generators (<code>Top</code> + <code>Child</code>), and every call site / test reference.</li>
- </ul>
-</div>
-
-<div class="layer l4">
- <h3>Layer 4 · Temporal stack <span class="pill pill-drop">delete</span></h3>
- <ul class="tight">
- <li><code>WfMakeTextThenObject</code> + <code>WfMakeTextThenObjectList</code> workflows — gone.</li>
- <li>Their dispatch methods on <code>ContentGeneratorTop</code> and <code>ContentGeneratorChild</code> — gone.</li>
- <li><code>TextThenObjectAssignment</code> dropped from the <code>AssignmentType</code> Union.</li>
- <li>Both workflows dropped from <code>tasks.py</code>'s <code>crafting</code> <code>TaskPack.workflow_list</code>.</li>
- </ul>
-</div>
-
-<div class="layer l5">
- <h3>Layer 5 · Config + TOML + variable filters <span class="pill pill-drop">delete</span></h3>
- <ul class="tight">
- <li><code>StructureConfig</code> class deleted (its only field, <code>is_default_text_then_structure</code>, served only as the global "always use preliminary text" override).</li>
- <li>TOML templates <code>structure_from_preliminary_text_system</code>, <code>structure_from_preliminary_text_user</code>, and the now-redundant <code>output_structure_prompt</code> deleted; <code>output_structure_prompt_no_preliminary_text</code> renamed to <code>output_structure_prompt</code> (it's now the only structure prompt).</li>
- <li>The reserved variable name <code>preliminary_text</code> dropped from filter sets in 5 blueprint files (kept <code>place_holder</code>, the only other one).</li>
- </ul>
-</div>
-
-<h2>4 — The PipeLLM flatten, in code</h2>
-
-<p>Two big diffs tell the story. First the runtime guard + the dropped plumbing in <code>_live_run_operator_pipe</code>:</p>
-
-<div class="diff">
- <div class="diff-header">pipelex/pipe_operators/llm/pipe_llm.py · _live_run_operator_pipe</div>
- <pre><span class="line ctx"> content_generator = content_generator or get_content_generator()</span>
-<span class="line add">+ if self.structuring_method == StructuringMethod.PRELIMINARY_TEXT:</span>
-<span class="line add">+ msg = (</span>
-<span class="line add">+ f"PipeLLM '{self.code}': structuring_method='preliminary_text' is not currently supported. "</span>
-<span class="line add">+ "The text-then-object mechanism was removed; a new implementation is planned."</span>
-<span class="line add">+ )</span>
-<span class="line add">+ raise NotImplementedError(msg)</span>
-<span class="line ctx"> output_stuff_spec = self.resolve_dynamic_output_stuff_spec(...)</span>
-<span class="line ctx"> ...</span>
-<span class="line del">- is_with_preliminary_text = (</span>
-<span class="line del">- self.structuring_method == StructuringMethod.PRELIMINARY_TEXT</span>
-<span class="line del">- ) or get_config().pipelex.structure_config.is_default_text_then_structure</span>
-<span class="line del">- log.verbose(f"is_with_preliminary_text: {is_with_preliminary_text} ...")</span>
-<span class="line ctx"> </span>
-<span class="line ctx"> llm_prompt_run_params = PipeRunParams.copy_by_injecting_multiplicity(</span>
-<span class="line ctx"> pipe_run_params=pipe_run_params,</span>
-<span class="line ctx"> applied_output_multiplicity=applied_output_multiplicity,</span>
-<span class="line del">- is_with_preliminary_text=is_with_preliminary_text,</span>
-<span class="line ctx"> )</span>
-<span class="line ctx"> ...</span>
-<span class="line del">- llm_prompt_2_factory: LLMPromptFactoryAbstract | None</span>
-<span class="line del">- if self.structuring_method:</span>
-<span class="line del">- structuring_method = cast("StructuringMethod", self.structuring_method)</span>
-<span class="line del">- match structuring_method:</span>
-<span class="line del">- case StructuringMethod.DIRECT:</span>
-<span class="line del">- llm_prompt_2_factory = None</span>
-<span class="line del">- case StructuringMethod.PRELIMINARY_TEXT:</span>
-<span class="line del">- llm_prompt_2_factory = LLMPromptTemplate.make_for_structuring_from_preliminary_text()</span>
-<span class="line del">- elif get_config().pipelex.structure_config.is_default_text_then_structure:</span>
-<span class="line del">- llm_prompt_2_factory = LLMPromptTemplate.make_for_structuring_from_preliminary_text()</span>
-<span class="line del">- else:</span>
-<span class="line del">- llm_prompt_2_factory = None</span></pre>
-</div>
-
-<p>Second, the body of <code>_llm_gen_object_stuff_content</code> — the 4-way matrix becomes a 2-way split:</p>
-
-<div class="side">
- <div>
- <h4>Before — 4-way matrix</h4>
-<pre>if is_multiple_output:
- if llm_prompt_2_factory is not None:
- # text_then_object_list
- objs = await content_generator
- .make_text_then_object_list(...)
- else:
- # object_list_direct
- objs = await content_generator
- .make_object_list_direct(...)
- the_content = ListContent(items=objs)
-else:
- if llm_prompt_2_factory is not None:
- # text_then_object
- the_content = await content_generator
- .make_text_then_object(...)
- else:
- # object_direct
- the_content = await content_generator
- .make_object_direct(...)</pre>
- </div>
- <div>
- <h4>After — 2-way split</h4>
-<pre>if is_multiple_output:
- objs = await content_generator
- .make_object_list(...)
- return ListContent(items=objs)
-
-return await content_generator
- .make_object(...)</pre>
- </div>
-</div>
-
-<h2>5 — The prompt-factory family: what stayed, what went</h2>
-
-<p>(This was the question my co-developer asked me to clarify. Three classes lived in this neighborhood; their fate differs.)</p>
-
-<table>
- <tr>
- <th>Class</th>
- <th>Where</th>
- <th>Status</th>
- <th>Why</th>
- </tr>
- <tr>
- <td><code>LLMPromptFactoryAbstract</code></td>
- <td><code>pipelex/cogt/llm/llm_prompt_factory_abstract.py</code></td>
- <td><span class="pill pill-keep">kept</span></td>
- <td>Abstract base. Defines <code>make_llm_prompt_from_args(**prompt_arguments)</code>. Still the parent of <code>LLMPromptTemplate</code>.</td>
- </tr>
- <tr>
- <td><code>LLMPromptTemplate</code></td>
- <td><code>pipelex/cogt/llm/llm_prompt_template.py</code></td>
- <td><span class="pill pill-keep">kept</span></td>
- <td>Concrete subclass. Builds an <code>LLMPrompt</code> from a <code>proto_prompt</code> + arguments. Still tested. <strong>One classmethod removed:</strong> <code>make_for_structuring_from_preliminary_text()</code> — its only job was to construct a template wired to the deleted TOML templates.</td>
- </tr>
- <tr>
- <td><code>LLMAssignmentFactory</code></td>
- <td><em>was</em> <code>pipelex/cogt/content_generation/assignment_models.py</code></td>
- <td><span class="pill pill-drop">deleted</span></td>
- <td>Bundled <code>(JobMetadata + LLMSetting + LLMPromptFactoryAbstract)</code>. Its only callers were the second-step assignment in <code>make_text_then_object</code> / <code>make_text_then_object_list</code> + the matching workflow variants <code>WfMakeTextThenObject*</code>. Zero callers remain.</td>
- </tr>
- <tr>
- <td><code>TextThenObjectAssignment</code></td>
- <td><em>was</em> <code>pipelex/cogt/content_generation/assignment_models.py</code></td>
- <td><span class="pill pill-drop">deleted</span></td>
- <td>Data class held the first call's <code>LLMAssignment</code> + the second call's <code>LLMAssignmentFactory</code>. Carried by the deleted Temporal workflows.</td>
- </tr>
-</table>
-
-<p><strong>Net effect:</strong> the prompt-factory mechanism (<code>LLMPromptFactoryAbstract</code> + <code>LLMPromptTemplate</code>) is intact and unchanged in shape. The <em>assignment</em> factory (<code>LLMAssignmentFactory</code>) and one classmethod that produced a "structure from preliminary text" template are both gone.</p>
-
-<details>
- <summary>What did <code>LLMAssignmentFactory.make_llm_assignment(preliminary_text=…)</code> actually do?</summary>
-<pre>
-class LLMAssignmentFactory(BaseModel):
- job_metadata: JobMetadata
- llm_setting: LLMSetting
- llm_prompt_factory: LLMPromptFactoryAbstract # typically an LLMPromptTemplate
-
- async def make_llm_assignment(self, **prompt_arguments) -> LLMAssignment:
- # render the template with the kwargs (e.g. preliminary_text=...)
- llm_prompt = await self.llm_prompt_factory.make_llm_prompt_from_args(**prompt_arguments)
- return LLMAssignment(job_metadata=..., llm_setting=..., llm_prompt=llm_prompt)
-</pre>
- <p>It deferred prompt construction so the second LLM call could substitute the first call's text output as a template variable. With the second-call path gone, it has no purpose.</p>
-</details>
-
-<h2>6 — Other crucial diffs</h2>
-
-<h3>The <code>ContentGeneratorProtocol</code> thins (and renames)</h3>
-<p>Two methods deleted, two methods renamed. The <code>_direct</code> suffix existed only to disambiguate from the deleted <code>_text_then_object</code> variants — once those are gone, the suffix is dead weight.</p>
-<div class="diff">
- <div class="diff-header">pipelex/cogt/content_generation/content_generator_protocol.py</div>
- <pre><span class="line del">- def make_object_direct(...) -&gt; Coroutine[..., BaseModelTypeVar]: ...</span>
-<span class="line add">+ def make_object(...) -&gt; Coroutine[..., BaseModelTypeVar]: ...</span>
-<span class="line ctx"> </span>
-<span class="line del">- def make_text_then_object(</span>
-<span class="line del">- self, ...,</span>
-<span class="line del">- llm_prompt_factory_for_object: LLMPromptFactoryAbstract | None = None,</span>
-<span class="line del">- ) -&gt; Coroutine[..., BaseModelTypeVar]: ...</span>
-<span class="line ctx"> </span>
-<span class="line del">- def make_object_list_direct(...) -&gt; Coroutine[..., list[BaseModelTypeVar]]: ...</span>
-<span class="line add">+ def make_object_list(...) -&gt; Coroutine[..., list[BaseModelTypeVar]]: ...</span>
-<span class="line ctx"> </span>
-<span class="line del">- def make_text_then_object_list(...) -&gt; Coroutine[..., list[BaseModelTypeVar]]: ...</span></pre>
-</div>
-<p>Renames propagated through all four implementations (<code>ContentGenerator</code>, <code>ContentGeneratorDry</code>, <code>ContentGeneratorChild</code>, <code>ContentGeneratorTop</code>), the call sites in <code>PipeLLM</code> and <code>WfTestContentGeneratorChild</code>, the docstring references in <code>temporal_data_converter.py</code>, and the matching test methods.</p>
-
-<h3>The <code>AssignmentType</code> Union shrinks</h3>
-<div class="diff">
- <div class="diff-header">pipelex/temporal/tprl_content_generation/content_generator_models.py</div>
- <pre><span class="line ctx"> AssignmentType = Union[</span>
-<span class="line ctx"> LLMAssignment,</span>
-<span class="line ctx"> ObjectAssignment,</span>
-<span class="line del">- TextThenObjectAssignment,</span>
-<span class="line ctx"> ImgGenAssignment,</span>
-<span class="line ctx"> ]</span></pre>
-</div>
-
-<h3>Temporal worker registration shrinks</h3>
-<div class="diff">
- <div class="diff-header">pipelex/temporal/tasks.py · crafting TaskPack</div>
- <pre><span class="line ctx"> workflow_list=[</span>
-<span class="line ctx"> WfMakeObject,</span>
-<span class="line ctx"> WfMakeLLMText,</span>
-<span class="line del">- WfMakeTextThenObject,</span>
-<span class="line ctx"> WfMakeObjectList,</span>
-<span class="line del">- WfMakeTextThenObjectList,</span>
-<span class="line ctx"> WfMakeImages,</span>
-<span class="line ctx"> WfMakeExtract,</span>
-<span class="line ctx"> WfMakeJinja2Text,</span>
-<span class="line ctx"> WfRenderPageViews,</span>
-<span class="line ctx"> ],</span></pre>
-</div>
-
-<h3>Reserved variable name <code>preliminary_text</code> stops being special</h3>
-<p>Before: 5 blueprint files filtered both <code>preliminary_text</code> and <code>place_holder</code> out of "required variables", because the runtime would inject <code>preliminary_text</code> on its own. After: only <code>place_holder</code> is filtered — <code>preliminary_text</code> is now a regular variable name (no special semantics).</p>
-<div class="diff">
- <div class="diff-header">5 sites: pipe_llm_blueprint.py, llm_prompt_blueprint.py, pipe_compose_blueprint.py, pipe_compose.py, construct_blueprint.py</div>
- <pre><span class="line del">-if not root.startswith("_") and root not in {"preliminary_text", "place_holder"}:</span>
-<span class="line add">+if not root.startswith("_") and root != "place_holder":</span></pre>
-</div>
-
-<h3>Config + TOML cleanup</h3>
-<div class="diff">
- <div class="diff-header">pipelex/system/configuration/configs.py</div>
- <pre><span class="line del">-class StructureConfig(ConfigModel):</span>
-<span class="line del">- is_default_text_then_structure: bool</span>
-<span class="line ctx"> </span>
-<span class="line ctx"> class Pipelex(ConfigModel):</span>
-<span class="line ctx"> ...</span>
-<span class="line del">- structure_config: StructureConfig</span>
-<span class="line ctx"> prompting_config: PromptingConfig</span></pre>
-</div>
-<div class="diff">
- <div class="diff-header">pipelex/pipelex.toml · [cogt.llm_config.generic_templates]</div>
- <pre><span class="line del">-structure_from_preliminary_text_system = """ ... """</span>
-<span class="line del">-structure_from_preliminary_text_user = """ ... """</span>
-<span class="line del">-output_structure_prompt = """ ... (the variant that paired with the preliminary text) """</span>
-<span class="line del">-output_structure_prompt_no_preliminary_text = """ ... """</span>
-<span class="line add">+output_structure_prompt = """ ... (the surviving variant — renamed) """</span></pre>
-</div>
-
-<h2>7 — Tests touched</h2>
-
-<table>
- <tr><th>Test</th><th>Action</th></tr>
- <tr><td><code>tests/integration/.../pipe_llm/test_pipe_llm.py</code></td><td>Removed the <code>StructuringMethod.PRELIMINARY_TEXT</code> parametrize entry. Added <code>test_pipe_llm_preliminary_text_raises_not_implemented</code> — asserts that running a <code>PipeLLM</code> with <code>structuring_method=PRELIMINARY_TEXT</code> raises <code>NotImplementedError</code>.</td></tr>
- <tr><td><code>parallel_text_analysis.mthds</code></td><td>Removed <code>structuring_method = "preliminary_text"</code> from two pipes (the third occurrence is inside a prompt string, not a config setting — left as-is).</td></tr>
- <tr><td><code>test_assignment_models_schema.py</code> + <code>test_assignment_models_security.py</code></td><td>Kept; ported the <code>ObjectAssignment</code>-specific assertions (per the project's "security perimeter tests" rule). Dropped the <code>TextThenObjectAssignment</code> cases.</td></tr>
- <tr><td><code>test_tprl_content_generator_top.py</code></td><td>Dropped <code>test_tprl_make_text_then_object</code> + <code>test_tprl_make_text_then_object_list</code>. The other 5 methods on <code>TestTprlCrafterTop</code> stay.</td></tr>
- <tr><td><code>wf_test_content_generator_child.py</code></td><td>Dropped the two <code>make_text_then_object</code> / <code>make_text_then_object_list</code> call blocks. The surrounding test workflow (<code>make_llm_text</code>, <code>make_object</code>, <code>make_object_list</code>, templating, extract) survives.</td></tr>
- <tr><td><code>test_llm_prompt_blueprint.py</code>, <code>test_pipe_llm_blueprint.py</code>, <code>test_construct_blueprint.py</code></td><td>The "filters preliminary_text" assertions updated to reflect that <code>preliminary_text</code> is no longer special — only <code>place_holder</code> is filtered.</td></tr>
-</table>
-
-<h2>8 — Verification</h2>
-
-<ul class="tight">
- <li><code>make agent-check</code> — clean (Ruff, Pyright, mypy, plxt). 0 errors.</li>
- <li><code>make tb</code> (boot test) — passes. Confirms <code>StructureConfig</code> removal didn't break config loading.</li>
- <li>Targeted tests: <code>tests/unit/pipelex/pipe_operators/</code> + <code>tests/unit/pipelex/cogt/content_generation/</code> + <code>tests/integration/pipelex/pipes/</code> — 435 passed, 2 skipped, 1 xfailed (pre-existing).</li>
- <li>Full Temporal suite (serial): <code>tests/integration/pipelex/temporal/</code> — 122 passed, 1 deselected.</li>
-</ul>
-
-<div class="note">
- <p><strong>Known flaky test under <code>-n auto</code>:</strong> <code>test_wf_pipe_batch.py::TestWfPipeBatch::test_batch_sequence_via_temporal[isolated]</code> intermittently fails with <code>KajsonDecoderError: Class 'temporal_batch_test__Topic' not found in module 'builtins' or global registry</code> when run in parallel. <strong>Passes in isolation</strong> and passes serially. This appears to be a class-registry race when sibling pytest-xdist workers reload bundles. Marked as <code>xfail(strict=False)</code> in this PR — to be investigated as a separate issue. Same root cause is independent of this refactor.</p>
-</div>
-
-<h2>9 — Followups (out of scope here)</h2>
-
-<ul class="tight">
- <li><strong>Future "preliminary text" reimplementation.</strong> The <code>StructuringMethod.PRELIMINARY_TEXT</code> enum value remains; pipes can still set it. Whatever replaces this is going to look completely different.</li>
- <li><strong>The <code>collapse-content-generation-workflow-layer</code> refactor</strong> (see <code>wip/temporal-primitives/collapse-content-generation-workflow-layer.md</code>). That refactor's delete list overlapped with this one (<code>WfMakeTextThenObject*</code>, <code>ContentGenerator{Child,Top}.make_text_then_object*</code>); those are now already removed, shrinking its scope. The remaining <code>WfMake*</code> wrappers (<code>WfMakeObject</code>, <code>WfMakeObjectList</code>, <code>WfMakeLLMText</code>, …) are still there, untouched.</li>
- <li><strong>Investigate the kajson class-registry race</strong> in <code>test_wf_pipe_batch.py::test_batch_sequence_via_temporal[isolated]</code> when run with pytest-xdist.</li>
-</ul>
-
-<h2>10 — How this sets up the next Temporal refactor</h2>
-
-<p>The next step on this branch is the <code>collapse-content-generation-workflow-layer</code> refactor (see <code>wip/temporal-primitives/collapse-content-generation-workflow-layer-v2.md</code>): delete the <code>WfMake*</code> child-workflow wrappers entirely and have the in-workflow content generator call <code>workflow.execute_activity(act_*, …)</code> directly from inside <code>WfPipeRouter</code>. That cuts ≈12 history events per content-generation call down to 3, while keeping the per-LLM-call activity boundary (so durability is preserved). This text-then-object cleanup was the prerequisite: <code>WfMakeTextThenObject</code> / <code>WfMakeTextThenObjectList</code> were the only <code>WfMake*</code> workflows that ran two activities with non-trivial Python glue between them — exactly the case that would have made the collapse risky to do in a single shot. With them gone, every surviving <code>WfMake*</code> is now a structurally identical single-activity wrapper, and the collapse becomes pure mechanical deletion.</p>
-
-</body>
-</html>
diff --git a/wip/archive/scoped-registry-teardown.md b/wip/archive/scoped-registry-teardown.md
deleted file mode 100644
index a94359b09..000000000
--- a/wip/archive/scoped-registry-teardown.md
+++ /dev/null
@@ -1,67 +0,0 @@
-# Scoped Registry Teardown: ContextVar Token Save/Restore
-
-## Problem
-
-In `pipelex/temporal/tprl_pipe/wf_pipe_router.py`, the scoped ClassRegistry cleanup in the `finally` block unconditionally sets the scoped registry to `None`:
-
-```python
-finally:
- if library_crate is not None:
- KajsonManager.set_scoped_class_registry(None)
-```
-
-This is not stack-safe. If a nested or re-entrant workflow sets its own scoped registry, the inner workflow's `finally` block resets to `None`, clobbering the outer workflow's scoped registry. The outer workflow then resolves classes from the global registry instead of its own scoped registry, potentially getting the wrong class definitions.
-
-## Proposed Solution
-
-Use Python's `ContextVar` token save/restore mechanism. `ContextVar.set()` returns a `Token` object, and `ContextVar.reset(token)` restores the value that was in effect before that `set()` call. This is the standard pattern for push/pop scoping with ContextVars.
-
-### Changes to Kajson (`kajson/kajson/kajson_manager.py`)
-
-1. Import `Token` from `contextvars`
-2. Change `set_scoped_class_registry` to return the Token:
-
-```python
-from contextvars import ContextVar, Token
-
-@classmethod
-def set_scoped_class_registry(cls, registry: ClassRegistryAbstract | None) -> Token[ClassRegistryAbstract | None]:
- return _scoped_class_registry.set(registry)
-```
-
-3. Add a `reset_scoped_class_registry` method:
-
-```python
-@classmethod
-def reset_scoped_class_registry(cls, token: Token[ClassRegistryAbstract | None]) -> None:
- _scoped_class_registry.reset(token)
-```
-
-### Changes to Pipelex (`pipelex/temporal/tprl_pipe/wf_pipe_router.py`)
-
-```python
-registry_token = None
-try:
- if library_crate is not None:
- global_registry = KajsonManager.get_class_registry()
- scoped_registry = CompositeClassRegistry(parent=global_registry)
- registry_token = KajsonManager.set_scoped_class_registry(scoped_registry)
- # ... load crate, hydrate WM ...
-
- # ... run pipe ...
-finally:
- # ... library teardown ...
- if registry_token is not None:
- KajsonManager.reset_scoped_class_registry(registry_token)
-```
-
-### Why Token-Based
-
-- The guard changes from `if library_crate is not None` to `if registry_token is not None`, which is more precise (only resets if we actually set a scoped registry)
-- Properly handles nesting: inner workflow restores to outer's scoped registry, not to `None`
-- Standard Python pattern for ContextVar scoping — no custom stack management needed
-
-### Impact on Existing Code
-
-- `set_scoped_class_registry` return type changes from `None` to `Token`. This is backward-compatible for callers that discard the return value. No existing callers check the return value.
-- The Kajson unit tests (`test_scoped_context_var`) should be updated to verify the token-based reset restores the previous value.
diff --git a/wip/archive/tier2-live-bug-recap.md b/wip/archive/tier2-live-bug-recap.md
deleted file mode 100644
index a2f3b4149..000000000
--- a/wip/archive/tier2-live-bug-recap.md
+++ /dev/null
@@ -1,69 +0,0 @@
-# Tier 2 Live Bug: DynamicConceptTestGreeting not found
-
-## The bug
-
-When running Tier 2 (deferred hydration) in **live mode** (real LLM calls), the parent workflow `WfPipeRouter` fails to decode the child workflow `WfMakeObject`'s return value:
-
-```
-KajsonDecoderError: Class 'DynamicConceptTestGreeting' not found in module 'builtins' or global registry
-```
-
-Dry-run passes because mock data never triggers the real structured output path.
-
-## How to reproduce
-
-```bash
-# Start Temporal server + worker, then:
-.venv/bin/pipelex run bundle \
- tests/integration/pipelex/temporal/library_crate/dynamic_concept_sequence.mthds \
- --pipe dynamic_greeting_sequence \
- --temporal --no-logo --graph
-```
-
-## Execution flow where it breaks
-
-```
-WfPipeRouter (parent workflow)
- → set_current_library(wf_library_id) # sets ContextVar
- → load_from_crate() # registers DynamicConceptTestGreeting in workflow-scoped registry
- → PipeSequence.run_pipe()
- → PipeLLM (generate_greeting)
- → ContentGeneratorChild.make_object_direct()
- → WfMakeObject (child workflow)
- → act_llm_gen_object (activity)
- → model_class_from_json_schema() creates class via exec()
- → LLM generates structured Greeting instance
- → Activity returns Greeting (BaseModel subclass)
- → WfMakeObject returns Greeting to parent
- → Temporal calls _convert_payloads to decode child result ← FAILS HERE
-```
-
-## What we verified with diagnostic logs
-
-1. **`to_payload` is NOT called for the Greeting activity return.** Only called for `ObjectAssignment` (activity input). The Greeting is serialized by Temporal's default JSON converter, NOT our `BaseModelPayloadConverter`. Therefore no `kajson_class_source` metadata is attached.
-
-2. **`from_payload` IS called for the child workflow result.** The payload data is:
- ```json
- {"message": "Bonjour le monde", "language": "French", "__class__": "DynamicConceptTestGreeting", "__module__": "builtins"}
- ```
- With `class_source_code: None` (no metadata).
-
-3. **The ContextVar is NOT propagated into `_convert_payloads`.** Temporal's internal `_apply_resolve_child_workflow_execution` → `_convert_payloads` runs outside the workflow coroutine's async context. So `get_class_registry()` falls back to the global KajsonManager registry, which doesn't have the dynamic class.
-
-## Two independent problems
-
-**Problem A: `to_payload` not called for activity results.**
-The Greeting returned by `act_llm_gen_object` never passes through our `BaseModelPayloadConverter.to_payload()`. Reason unknown — possibly Temporal SDK uses a different serialization path for activity return values, or the exec'd class isn't recognized as `BaseModel` by the converter's `isinstance` check.
-
-**Problem B: ContextVar not available in `_convert_payloads`.**
-Even if `to_payload` worked and attached `kajson_class_source` metadata, the parent workflow's `_convert_payloads` runs in a Temporal-internal context where the `_library_id` ContextVar is not set. So `get_class_registry()` returns the global registry, not the workflow-scoped one.
-
-## What was fixed so far (kajson repo)
-
-**Decoder fallback** in `kajson/json_decoder.py`: When `sys.modules[module_name]` exists but `getattr` fails (the `builtins` case), the decoder now falls through to check `KajsonManager.get_class_registry()` before raising. Previously it raised immediately. This fix is correct but insufficient alone — the class isn't in the global registry either.
-
-Test: `kajson/tests/unit/test_global_registry_fallback.py` — passes.
-
-## What was NOT fixed
-
-The `_collect_class_sources` helper added to `temporal_data_converter.py` is irrelevant since `to_payload` isn't called for the Greeting. The debug logs added should be removed.
diff --git a/wip/archive/tier2-live-registry-propagation.md b/wip/archive/tier2-live-registry-propagation.md
deleted file mode 100644
index 743183a4b..000000000
--- a/wip/archive/tier2-live-registry-propagation.md
+++ /dev/null
@@ -1,123 +0,0 @@
-# Tier 2 Live: ContextVar Registry Doesn't Cross Temporal Boundaries
-
-**Status:** Open — needs architectural decision
-**Branch:** `fix/Temporal-Img`
-**Date:** 2026-04-01
-
-## What works
-
-- Tier 2 **dry-run** passes (no real LLM calls, `ObjectAssignment` never hits the structured output path)
-- Tiers 1, 3, 4, 5 pass in both dry-run and live mode
-- The `ObjectAssignment.__init__` deserialization fix (removing the eager class registry check) is correct and already applied on this branch
-
-## What fails
-
-Tier 2 **live** — `dynamic_concept_sequence.mthds` with `--pipe dynamic_greeting_sequence` through Temporal.
-
-The bundle defines a dynamic concept `Greeting` (with `message` and `language` fields) and a `PipeLLM` that outputs structured data into that concept using `structuring_method = "direct"`.
-
-## Error
-
-```
-Class 'dynamic_concept_test__Greeting' not found in registry
-```
-
-Thrown from `llm_generate.py:32`:
-```python
-content_class = get_class_registry().get_required_base_model(name=content_class_name)
-```
-
-## Root cause
-
-`get_class_registry()` uses a `ContextVar` (`_library_id` in `hub.py:462`) to resolve the workflow-scoped registry. But ContextVars don't propagate across Temporal's execution boundaries:
-
-```
-WfPipeRouter (ContextVar set here via set_current_library)
- → pipe.run_pipe()
- → ContentGeneratorChild.make_object_direct()
- → child workflow WfMakeObject (NEW async context — ContextVar is None)
- → activity act_llm_gen_object (ANOTHER context — ContextVar is None)
- → llm_gen_object()
- → get_class_registry() → returns GLOBAL registry → class not found
-```
-
-The dynamic concept class `dynamic_concept_test__Greeting` was registered in `WfPipeRouter`'s **workflow-scoped** `ClassRegistry`. But two hops later — inside the activity of a child workflow — `get_class_registry()` returns the **global** registry, which doesn't have it.
-
-## Why dry-run works
-
-In dry-run mode, `PipeLLM` never reaches `ContentGeneratorChild.make_object_direct()` — the dry-run path generates mock output without calling the LLM, so it never needs to look up the dynamic class from the registry inside an activity.
-
-## Why other tiers aren't affected
-
-- **Tier 1** (native text sequence): Uses `PipeLLM` with `Text` output (a native concept, always in the global registry). No structured output, no `ObjectAssignment`.
-- **Tier 3** (parallel): Same — text-only pipes, no dynamic concepts in structured output position.
-- **Tiers 4-5** (image): Image generation doesn't go through `ObjectAssignment` or `llm_gen_object`. Images use `ImgGenAssignment` → `act_img_gen` which doesn't need the class registry.
-
-## Fix already applied on this branch
-
-Removed `ObjectAssignment.__init__` class registry validation (`assignment_models.py:90-94`). This was causing a **separate** deserialization failure: when Temporal's data converter called `kajson.loads()` to deserialize the `ObjectAssignment` argument for `WfMakeObject`, pydantic called `__init__` which checked the registry. Removing it fixed the deserialization, but the same lookup fails later in the activity.
-
-## Approach options
-
-### A) Embed the class schema in ObjectAssignment
-
-Add the Pydantic model's JSON schema (or the field definitions) as a field on `ObjectAssignment`. The activity reconstructs the class locally from the schema without needing the registry. This is the "carry everything you need" pattern, similar to how `LibraryCrate` carries pipe definitions.
-
-**Pros:** Self-contained, no cross-boundary coupling, works for any Temporal topology.
-**Cons:** Increases payload size, needs a "reconstruct Pydantic class from schema" utility.
-
-### B) Propagate library_id through Temporal headers
-
-Use Temporal's workflow/activity interceptors to copy the `_library_id` ContextVar into Temporal headers on dispatch, and restore it on the receiving end. This is the transparent approach.
-
-**Pros:** No changes to assignment models, ContextVar "just works" across boundaries.
-**Cons:** Requires Temporal interceptor infrastructure, the receiving side still needs access to the same `LibraryManager` state (child workflows and activities must be on the same worker).
-
-### C) Pre-register dynamic classes in the global registry
-
-When `WfPipeRouter.load_from_crate()` runs, also register dynamic classes in the global registry (not just the workflow-scoped one). Clean up on workflow teardown.
-
-**Pros:** Simplest change, everything finds the class.
-**Cons:** Breaks per-workflow isolation — concurrent workflows with conflicting class names will clobber each other (exactly the bug the scoped registry was designed to prevent).
-
-### D) WfMakeObject loads the crate itself
-
-Pass the `LibraryCrate` to `WfMakeObject` alongside the `ObjectAssignment`. The child workflow sets up its own scoped registry before the activity runs.
-
-**Pros:** Reuses existing crate-loading pattern from `WfPipeRouter`.
-**Cons:** Increases child workflow payload, adds setup/teardown overhead to every structured output call.
-
-## Key files
-
-| File | Role |
-|------|------|
-| `pipelex/hub.py:381-386, 462-467` | `get_class_registry()` and `_library_id` ContextVar |
-| `pipelex/temporal/tprl_pipe/wf_pipe_router.py:46-68` | Crate loading and registry setup |
-| `pipelex/temporal/tprl_content_generation/wf_make_object.py` | Child workflow receiving `ObjectAssignment` |
-| `pipelex/cogt/content_generation/llm_generate.py:32` | Activity calling `get_class_registry()` |
-| `pipelex/cogt/content_generation/assignment_models.py:86` | `ObjectAssignment` model (init check removed) |
-| `pipelex/temporal/temporal_data_converter.py:77` | Kajson deserialization using `get_class_registry()` |
-| `tests/integration/pipelex/temporal/library_crate/dynamic_concept_sequence.mthds` | Test bundle |
-
-## Reproduction
-
-```bash
-# Start Temporal server + worker
-tmux new-session -d -s temporal-server 'temporal server start-dev'
-sleep 3
-tmux new-session -d -c "$PWD" -s temporal-worker \
- '.venv/bin/python -m pipelex.temporal.worker_cli --is-not-sandboxed'
-sleep 4
-
-# This passes (dry-run)
-.venv/bin/pipelex run bundle \
- tests/integration/pipelex/temporal/library_crate/dynamic_concept_sequence.mthds \
- --pipe dynamic_greeting_sequence \
- --temporal --dry-run --mock-inputs --no-logo
-
-# This fails (live)
-.venv/bin/pipelex run bundle \
- tests/integration/pipelex/temporal/library_crate/dynamic_concept_sequence.mthds \
- --pipe dynamic_greeting_sequence \
- --temporal --no-logo
-```
diff --git a/wip/archive/workflow-and-activity-ids.md b/wip/archive/workflow-and-activity-ids.md
deleted file mode 100644
index b2750d52d..000000000
--- a/wip/archive/workflow-and-activity-ids.md
+++ /dev/null
@@ -1,139 +0,0 @@
-# Workflow and Activity IDs in Temporal: Correctness + Observability
-
-## Status
-
-Problem statement + failing test gate in place. No solution designed yet — the next session must explore Temporal's primitives (`workflow.uuid4()`, `workflow.info()`, search attributes, activity summaries, workflow-local counters, child-workflow id derivation, etc.) and design the right model. The gate test (see below) must turn green as the result of that work, without weakening the assertions.
-
-## The trigger: activity-id collision in `ContentGeneratorInWorkflow`
-
-File: `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py`
-
-Every method that dispatches an activity computes `activity_id` like this:
-
-```python
-activity_id = wfid or "craft-text"
-self._record_activity_id(activity_id, "make_llm_text")
-```
-
-The defaults are operation-type labels: `"craft-text"`, `"craft-object-direct"`, `"craft-object-list-direct"`, `"craft-image-single"`, `"craft-image-list"`, `"jinja2-text"`, `"render-page-views"`, `"extract-pages"`, `"extract-render-page-views"`.
-
-### The bug
-
-Temporal requires `activity_id` to be unique within a single workflow execution (i.e. per `(workflow_id, run_id)`). The defaults above are constants. A workflow that calls `make_llm_text` twice in a row uses `activity_id="craft-text"` both times and crashes — at the second call — with a duplicate-id error. Two calls to the same generator method inside one workflow is a perfectly ordinary pattern; the current design treats it as an error.
-
-### What the LRU / `_record_activity_id` actually does
-
-The `_seen_activity_ids: OrderedDict[tuple[str, str], set[str]]` machinery in lines 48-109 is **not** a fix. It's a polite-failure wrapper: it lets the collision raise as a clean `ContentGenerationError` ("Duplicate activity_id … pass a distinct `wfid` at the call site") instead of an opaque Temporal SDK error. All the surrounding complexity (LRU bound, `(workflow_id, run_id)` keying, `is_replaying()` short-circuit) exists only because the set lives on a long-lived **worker-singleton** instance (`ContentGeneratorInWorkflow` is instantiated once in `pipelex.py:347` and reused across every workflow run on that worker).
-
-The LRU is solving the wrong problem. The structural bug is upstream: the default `activity_id` is a constant string in a context that requires a per-call unique value.
-
-### Why `wfid` doesn't actually save us
-
-`wfid` is **the workflow-id parameter**, not an activity-id parameter. Everywhere else in the codebase it's used as the base for a workflow id:
-
-- `temporal_pipe_run.py:63, 95` — `workflow_id=self.make_workflow_id(base_id=wfid or self.class_name)`
-- `temporal_pipe_router.py:84` — same
-- `temporal_pipe_router.py:60` — `child_unique_id = wfid or str(workflow.uuid4())`
-- threaded through `pipe_run.py`, `pipe_run_protocol.py`, `pipe_router_protocol.py`
-
-In `content_generator_in_workflow.py`, the same parameter is being co-opted as an `activity_id`. This is a legacy artifact: in an earlier prototype the content generator **spawned workflows** for each operation, so a single `wfid` per call made sense. We later changed it to spawn **activities** instead, but the parameter — and the assumption that one id per call is enough — was carried over unchanged. A single `wfid` value cannot disambiguate ten `make_llm_text` calls inside one workflow.
-
-## TDD entry point — DONE
-
-The failing test is in place at `tests/unit/pipelex/temporal/test_default_activity_id_collision_bug.py` (class `TestDefaultActivityIdCollisionBug`). It pins both scenarios:
-
-- `test_two_make_llm_text_calls_without_wfid_should_succeed` — two `make_llm_text` calls in the same workflow with no `wfid` passed. Today both default to `activity_id="craft-text"` and the second call raises `ContentGenerationError("Duplicate activity_id 'craft-text' for method 'make_llm_text' ...")` from `_record_activity_id`. The test asserts the desired behavior (two distinct activity_ids, both calls succeed) and therefore fails today.
-- `test_two_make_llm_text_calls_with_same_explicit_wfid_should_succeed` — two `make_llm_text` calls with the same explicit `wfid="same-string"`. Today this raises the same way, proving `wfid` cannot serve as the per-call disambiguator. The test asserts the desired behavior (the redesign decouples per-call `activity_id` from the `wfid` parameter) and fails today for the same reason.
-
-### Why unit, not integration
-
-The original sketch suggested `tests/integration/pipelex/temporal/` "so it runs against a real-ish workflow context where `workflow.execute_activity` is callable." On inspection the unit-test layer already mocks `workflow.info()`, `workflow.unsafe.is_replaying()`, and `workflow.execute_activity()` cleanly (see the pattern in `tests/unit/pipelex/temporal/test_content_generator_in_workflow.py`), and the bug fires synchronously in `_record_activity_id` *before* `execute_activity` is awaited. A unit test pins the wrapper-layer bug exactly where it lives — no LLM, no worker, no Temporal server — and runs in well under a second. An integration test could be added later if the redesign introduces workflow-primitive behavior (e.g. `workflow.uuid4()` determinism across replay) that is worth exercising end-to-end, but it is not required to gate the design.
-
-### Gate semantics
-
-The two tests assert the **desired** behavior (both calls succeed and produce distinct activity_ids). They are red today. Any redesign must turn them green without re-introducing the duplicate-collision via some other path. Do not delete or weaken these tests as part of the fix — flip the implementation, not the assertions.
-
-## Step back: this is bigger than one bug
-
-The activity-id bug is the local symptom. The deeper issue is that **we do not have a designed naming system for the Temporal primitives we run** — neither for workflows nor for activities. What we have today are two legacy schemes glued together:
-
-### Legacy artifact 1: `wfid`
-
-`wfid` was introduced when content generation was implemented as **spawned workflows**. One workflow per `make_*` call → one `wfid` per call → fine. When we switched content generation to **activities** inside the current workflow, the `wfid` parameter survived but its purpose became muddled. It is now simultaneously:
-
-- The base for parent/child **workflow** ids (in `tprl_pipe/*`).
-- The **activity_id** itself (in `tprl_content_generation/content_generator_in_workflow.py`).
-
-These are two different Temporal primitives with different uniqueness scopes. Conflating them under one parameter name is the root cause of the collision bug.
-
-### Legacy artifact 2: workflow-id construction
-
-`temporal_manager.py:95-110` builds top-level workflow ids as:
-
-```python
-return f"{prefix}{session_part}-{random_part}-{base_id}"
-```
-
-where `base_id` defaults to `self.class_name` of the caller (`TemporalPipeRun`, `TemporalPipeRouter`, …). Example seen in the dashboard:
-
-```
-EdgdJ-HR5fd-TemporalPipeRun-pipe-router
-```
-
-Decomposed:
-
-- `EdgdJ` — 5 chars of session id
-- `HR5fd` — 5 chars of shortuuid
-- `TemporalPipeRun-pipe-router` — the calling class name + a hardcoded literal
-
-This tells an operator nothing about **what was actually executed**. The Temporal dashboard also shows the **workflow type/name**, which is the registered class — things like `wf_pipe_router`. So a typical row reads:
-
-| Workflow ID | Workflow Type |
-|---|---|
-| `EdgdJ-HR5fd-TemporalPipeRun-pipe-router` | `wf_pipe_router` |
-| `EdgdJ-HR5fd-TemporalPipeRun-pipe-router` (child) | `wf_pipe_router` |
-| `EdgdJ-HR5fd-TemporalPipeRun-pipe-router` (child) | `wf_pipe_router` |
-
-Three "router" workflows ran. Which pipes? Which concepts? Which inputs? Invisible.
-
-### The real requirements
-
-We need a coherent design covering all of the following — currently none of them are designed, only accreted:
-
-1. **Top-level workflow id.** What identifies a single user-initiated pipeline run? Must be unique, traceable back to the user / session / pipe code, and ideally readable.
-
-2. **Child-workflow id.** When a parent pipe spawns children (sub-pipes, parallel branches), how are their ids derived from the parent's? Today: same shape, fresh `shortuuid`, no parent link visible in the id.
-
-3. **Workflow type/name (the registered class).** Today fixed at the class level (`wf_pipe_router`, …). Could we register more semantically meaningful workflow types per pipe, or carry the pipe code in a search attribute / memo so it's filterable in the dashboard?
-
-4. **Activity id.** Must be unique per `(workflow_id, run_id)`. Today: constant strings → collision on repeated calls. Needs a per-call disambiguator that is **deterministic across replay** (so `workflow.uuid4()` or a workflow-local counter — not `uuid.uuid4()` from stdlib).
-
-5. **Activity type/name.** The Python function name (`act_llm_gen_text`, …). Probably fine, but worth re-checking against the observability story.
-
-6. **Human-readable summaries.** Temporal supports per-activity / per-workflow `summary` and `details` metadata (and search attributes / memos) that can be surfaced in the dashboard without affecting ids. We are not using these.
-
-7. **Display in our own webapps and reporting.** The same ids and names need to be useful in our UIs, not just the Temporal dashboard. Today they are opaque.
-
-### Constraints any solution must respect
-
-- **Determinism.** Whatever generates the per-call piece of an `activity_id` (and any workflow id chosen from inside workflow code) must be replay-safe. Reach for `workflow.uuid4()`, `workflow.info()`, or workflow-local counters — never `uuid.uuid4()`, `time.time()`, `random.*`, or any worker-singleton state mutated from workflow code.
-- **No worker-singleton state.** The current LRU is on `ContentGeneratorInWorkflow`, a worker-wide singleton. Solutions that lean on the singleton inherit the same replay-safety hazard (`is_replaying()` short-circuits, LRU eviction races) that makes the current code ugly. Whatever we do should keep per-execution state inside the workflow execution.
-- **Backwards compatibility is not required.** Per `CLAUDE.md`: no transition period. Rename `wfid` to whatever it should be, change defaults, break callers. The cost is in the changelog, not in deprecation.
-
-## What this session should NOT do
-
-- Don't pick a numbering scheme.
-- Don't decide between `workflow.uuid4()` suffix, counter, omitted `activity_id`, search attributes, or workflow-summary metadata.
-- Don't rename `wfid` yet.
-
-All of the above belong in a fresh session that starts by **reading the Temporal references** (especially `references/python/observability.md`, `references/python/advanced-features.md`, and the determinism/replay parts of `references/core/determinism.md` and `references/python/determinism.md`) and then designs the id+naming model from scratch.
-
-## Working starting points for next session
-
-- `tests/unit/pipelex/temporal/test_default_activity_id_collision_bug.py` — the failing test gate. Run `.venv/bin/pytest -v tests/unit/pipelex/temporal/test_default_activity_id_collision_bug.py` to see the current red state (both tests fail with `ContentGenerationError: Duplicate activity_id ...`).
-- `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py:48-109` — the LRU machinery that becomes deletable once the activity-id design is fixed.
-- `pipelex/temporal/temporal_manager.py:95-110` — top-level workflow id construction.
-- `pipelex/temporal/tprl/workflow_caller.py:84-87` — `make_workflow_id` delegator.
-- `pipelex/temporal/tprl_pipe/temporal_pipe_run.py`, `temporal_pipe_router.py` — call sites that pass `wfid` as a workflow-id base.
-- `pipelex/cogt/content_generation/content_generator_protocol.py` — protocol that defines `wfid` on every `make_*` method; will need updating once the per-call activity-id concern is removed from this layer.
-- Worker singleton wiring in `pipelex/pipelex.py:347` — explains why the LRU has to be (workflow_id, run_id)-keyed today.
diff --git a/wip/blueprint-elaboration-directives.md b/wip/blueprint-elaboration-directives.md
new file mode 100644
index 000000000..5a7584746
--- /dev/null
+++ b/wip/blueprint-elaboration-directives.md
@@ -0,0 +1,26 @@
+# Blueprint Elaboration Directives — going further
+
+A **blueprint elaboration directive** is a build-time instruction in a `.mthds` bundle that `BundleElaborator` expands into concrete pipes when the library loads — so the authoring shape and the executed shape differ. The first (and so far only) directive is `preliminary_text`, which synthesizes a draft-text pipe plus a `PipeStructure` pipe in memory.
+
+This doc collects the work to take that system further: make the pipes the elaborator synthesizes first-class across observability, generalize the single-purpose elaborator into a directive framework, and add the tooling and guards a growing elaboration layer needs. None of it is started — pick items up as the need arises.
+
+## Synthetic-pipe handling
+
+The elaborator synthesizes pipes (e.g. `__draft_text`, `__structure`) that today surface as ordinary pipes everywhere. These items make them recognizable and friendly across the observability surfaces.
+
+- **Marker on graph nodes + `pipelex list` exclusion.** When emitting `NodeSpec`, look up `bundle.elaboration_metadata` and set `tags["synthetic"] = "true"` + `tags["parent_pipe_code"] = parent`. Requires either a runtime-only field on `PipeAbstract` or a side-registry keyed by pipe code. Also hide synthetic pipes from `pipelex list`. This is the keystone — the next two build on it.
+- **Friendly rendering across logs/traces/run-reporting.** Once the marker lands, render `<parent_pipe_code> [<step_role_label>]` everywhere `self.code` appears for a synthetic pipe. Touches graph_tracer, run_reporting, journal, distributed-tracing.
+- **`mthds-ui` graph viewer integration.** Once the marker lands, decide in the UI repo whether to nest synthetic pipes under their parent or hide them.
+
+## Generalizing the framework
+
+- **Directive plugin registry.** `BundleElaborator` handles exactly one directive today (`_elaborate_preliminary_text`). Promote it to a plugin registry when a SECOND elaboration directive appears — not before, to avoid premature abstraction.
+
+## Tooling & guards
+
+- **`pipelex-dev elaborate-bundle <path>`.** A debugging CLI that prints the elaborated bundle form without running it, so directive expansion can be inspected directly.
+- **Bundle-load benchmark in CI.** Microbenchmark library load time and alert on >5% regression. Protects future elaboration passes from silently slowing startup.
+
+## Serialization
+
+- **Persist `elaboration_metadata` across serialization boundaries.** Today `Field(exclude=True)` drops it on every `model_dump`. When a cross-boundary consumer materializes (graph viewer over a serialized bundle, Temporal payload, persistent cache), flip `exclude=False`, regenerate the schema, ship a plxt bump. The regression test at `test_elaboration_metadata.py::test_bundle_round_trip_drops_elaboration_metadata` flips first.
diff --git a/wip/concurrency/README.md b/wip/concurrency/README.md
index 498f3f67f..73fc01114 100644
--- a/wip/concurrency/README.md
+++ b/wip/concurrency/README.md
@@ -1,10 +1,10 @@
# Concurrency & batching — design doc
-Status: **design scoping**. Exactly one change is a genuine quick win (retry jitter, below). The three larger pieces of design work are split into their own docs — [`fan-out-scheduling.md`](fan-out-scheduling.md), [`rate-limiting.md`](rate-limiting.md), and [`batch-partial-failure.md`](batch-partial-failure.md).
+Status: **design scoping**. The one quick win this doc identified — retry jitter — has since shipped (see below). What remains is three larger pieces of design work, split into their own docs — [`fan-out-scheduling.md`](fan-out-scheduling.md), [`rate-limiting.md`](rate-limiting.md), and [`batch-partial-failure.md`](batch-partial-failure.md).
## Context & scope
-The resilience strategy is settled: **Temporal is the resilience system.** We deliberately decided *not* to build a cheap resilience system in direct mode (see `TODOS.md` and `wip/error-handling/`).
+The resilience strategy is settled: **Temporal is the resilience system.** We deliberately decided *not* to build a cheap resilience system in direct mode — resilience is the error-handling track's job (see [`../error-handling/`](../error-handling/)).
The open problem is narrower: the direct-mode batching/asyncio system breaks too easily. The driving question: *what is a best-practice basic backpressure / rate-limiting system at the asyncio layer, so the system does not crash when asked to process e.g. 1000 documents?*
@@ -50,9 +50,9 @@ Three distinct weaknesses, and they compound under load. Code inspected: `pipele
### 3. Concurrency ≠ rate — and rate is what providers enforce
-Providers rate-limit on **requests-per-minute (RPM)** and **tokens-per-minute (TPM)**, not on concurrency. 8 concurrent calls each finishing in ~200ms = ~40 RPS = ~2400 RPM, which blows a 500-RPM tier instantly. The result is a 429 storm; `transport_retry` then re-fires that storm, and because the exponential backoff has no jitter, the retries re-synchronize into a thundering herd.
+Providers rate-limit on **requests-per-minute (RPM)** and **tokens-per-minute (TPM)**, not on concurrency. 8 concurrent calls each finishing in ~200ms = ~40 RPS = ~2400 RPM, which blows a 500-RPM tier instantly. The result is a 429 storm; `transport_retry` then re-fires that storm. The backoff used to be jitter-free, so retries re-synchronized into a thundering herd — that part is now fixed (full jitter shipped, see below), but the underlying RPM/TPM overrun that triggers the storm remains.
-Only the retry-jitter gap is a true quick win (below). Weakness 1 looked like one but is not — fixing it correctly carries a design decision, so it has its own doc, [`fan-out-scheduling.md`](fan-out-scheduling.md). Weaknesses 2 + 3 are the hard part — a real rate limiter — covered in [`rate-limiting.md`](rate-limiting.md).
+The retry-jitter gap was the one true quick win and has since shipped (below). Weakness 1 looked like one but is not — fixing it correctly carries a design decision, so it has its own doc, [`fan-out-scheduling.md`](fan-out-scheduling.md). Weaknesses 2 + 3 are the hard part — a real rate limiter — covered in [`rate-limiting.md`](rate-limiting.md).
## Where `max_concurrency` lives today
@@ -69,13 +69,11 @@ This is the mechanism behind weakness 2: a global *number* applied per-batch is
**Design option — make it per-`PipeBatch`.** An optional `max_concurrency` field could be added to `BatchParams` (the per-`PipeBatch` object parsed from `.mthds`), falling back to the global config. This is a *fan-out shape* knob — useful, but it does not fix weakness 2, since shape knobs still multiply under nesting. It carries one Temporal advantage worth noting: a value on `BatchParams` is part of the fixed pipe blueprint / workflow input, so it replays deterministically — strictly safer than `PipeBatch` reading global config inside workflow code, which `wf_pipe_run.py` already warns against for "config-derived" values that "change across deploys". Tracked as an open question — see [`rate-limiting.md`](rate-limiting.md).
-## The one quick win — retry jitter
+## Shipped — retry jitter
-`wait_exponential` in `transport_retry.py` is jitter-free; under a 429 storm every retry re-fires in lockstep. Switch to `wait_random_exponential` (full jitter).
+`transport_retry.py` now uses full-jitter `wait_random_exponential` (`transport_retry.py:46`); it was previously jitter-free `wait_exponential`, so under a 429 storm every retry re-fired in lockstep. With full jitter each wait is drawn from `uniform(0, exponential_bound)`, breaking the lockstep.
-**Direct vs Temporal:** `transport_retry` runs inside the activity in both modes — jitter is fine there (non-determinism allowed in activities). Pre-existing nuance, not worsened by this change: under Temporal there are already two retry layers — `tenacity` inside the activity and Temporal's activity `RetryPolicy` outside it. Whether the activity should fail faster and let `RetryPolicy` own retries is a separate, existing design question.
-
-Effort: tiny — a one-line change. This is the only genuinely isolated change here; everything else carries a design decision and is covered below.
+**Direct vs Temporal:** `transport_retry` runs inside the activity in both modes — jitter is fine there (non-determinism allowed in activities). Pre-existing nuance, unaffected by this change: under Temporal there are already two retry layers — `tenacity` inside the activity and Temporal's activity `RetryPolicy` outside it. Whether the activity should fail faster and let `RetryPolicy` own retries is a separate, existing design question.
## Larger design work — separate docs
@@ -99,9 +97,9 @@ Weaknesses 2 + 3 — a per-`PipeBatch` (not global) bound, and the absence of an
| --- | --- |
| `PipeBatch` | Fan-out *shape* — how work is split (scheduling redesign in `fan-out-scheduling.md`) |
| Inference rate/concurrency gate | The actual backpressure — see `rate-limiting.md` |
-| `transport_retry` | Residual 429/5xx — the retry-jitter quick win adds full jitter |
+| `transport_retry` | Residual 429/5xx — full jitter (`wait_random_exponential`) shipped |
| Temporal | Durability — out of scope here |
## Suggested next step
-Land the retry-jitter quick win — it is the only self-contained change. Then take up the three design docs as design sessions: [`fan-out-scheduling.md`](fan-out-scheduling.md) and [`batch-partial-failure.md`](batch-partial-failure.md) are coupled through the failure-handling policy and are best taken together (or in that order); [`rate-limiting.md`](rate-limiting.md) is independent of both.
+The retry-jitter quick win has shipped. Take up the three design docs as design sessions: [`fan-out-scheduling.md`](fan-out-scheduling.md) and [`batch-partial-failure.md`](batch-partial-failure.md) are coupled through the failure-handling policy and are best taken together (or in that order); [`rate-limiting.md`](rate-limiting.md) is independent of both.
diff --git a/wip/concurrency/rate-limiting.md b/wip/concurrency/rate-limiting.md
index 92cf241ed..937ba3edc 100644
--- a/wip/concurrency/rate-limiting.md
+++ b/wip/concurrency/rate-limiting.md
@@ -38,10 +38,10 @@ The trap to avoid: building one in-memory limiter and assuming it protects both
Inspected `pipelex/temporal/config_temporal.py`. The Temporal-side rate-limit knobs are already built and configurable — Temomral mode is a *configuration* story, not a build:
-- **`QueueOptions.max_task_queue_activities_per_second`** (`config_temporal.py:273`) — the **cluster-wide** task-queue rate limit. Its own comment: *"Cluster-wide queue rate limit, conveyed to the Temporal server by every worker on this queue."* Server-enforced across all workers — exactly the RPM cap.
-- **`WorkerRuntimeProfile.max_concurrent_activities`** (`config_temporal.py:332`) — per-worker concurrency ceiling.
-- **`WorkerRuntimeProfile.max_activities_per_second`** (`config_temporal.py:336`) — per-worker activity rate limit.
-- **`ActivityRouteConfig`** (`config_temporal.py:287`) with `by_handle` — routes `llm_handle` / `img_gen_handle` / `extract_handle` to dedicated task queues. So **per-provider keying already exists on the Temporal side**: give each provider its own queue, set that queue's `max_task_queue_activities_per_second`.
+- **`QueueOptions.max_task_queue_activities_per_second`** (`config_temporal.py:281`) — the **cluster-wide** task-queue rate limit. Its own comment: *"Cluster-wide queue rate limit, conveyed to the Temporal server by every worker on this queue."* Server-enforced across all workers — exactly the RPM cap.
+- **`WorkerRuntimeProfile.max_concurrent_activities`** (`config_temporal.py:340`) — per-worker concurrency ceiling.
+- **`WorkerRuntimeProfile.max_activities_per_second`** (`config_temporal.py:344`) — per-worker activity rate limit.
+- **`ActivityRouteConfig`** (`config_temporal.py:295`) with `by_handle` — routes `llm_handle` / `img_gen_handle` / `extract_handle` to dedicated task queues. So **per-provider keying already exists on the Temporal side**: give each provider its own queue, set that queue's `max_task_queue_activities_per_second`.
Consequence: the Temporal half needs only sane default values and documentation, not new code. **The actual build is purely the direct-mode gate.**
diff --git a/wip/console-targets-and-agent-cli-stdout.md b/wip/console-targets-and-agent-cli-stdout.md
deleted file mode 100644
index ef0f41c98..000000000
--- a/wip/console-targets-and-agent-cli-stdout.md
+++ /dev/null
@@ -1,248 +0,0 @@
-# Console targets — partial revert + agent CLI stdout hardening
-
-> **Status:** Both parts landed on branch `fix/Log-target`. Part 1 (partial revert + dual-TOML test) shipped in commit `3d22ea9f`. Part 2 (agent-CLI factory-level hardening + adversarial E2E test) is included in this PR — `make_pipelex_for_agent_cli` now injects `config_overrides` that pin both console targets to stderr from the very first log/print during init, and the new test `test_models_json_stdout_resists_user_targets_override_to_stdout` pins the contract under adversarial user overrides.
->
-> **Cold-start prerequisite:** read `pipelex/tools/log/log.py:91`, `pipelex/hub.py:137-148`, `pipelex/cli/agent_cli/commands/agent_cli_factory.py:118-122`, `pipelex/cli/agent_cli/commands/agent_output.py` (where `agent_success` writes to stdout), and `pipelex/tools/misc/pretty.py:214` (the bare `Console()` instantiation).
-
-## TL;DR
-
-We have two independent knobs in `[pipelex.log_config]`:
-
-- `console_log_target` — controls the `RichHandler` attached to Python's logging system. **Logs are diagnostics → stderr.** Flipping the default to `stderr` is correct and stays.
-- `console_print_target` — controls the hub's `_console` returned by `get_console()`. This console is used by the main `pipelex` CLI for human-facing **data tables** (`pipelex show backends`, `pipelex show models`, `pipelex which`, `pipelex doctor`). **Data → stdout.** Flipping the default to `stderr` was an over-correction and must be reverted.
-
-The actual bug ("logs polluting stdout breaks downstream JSON parsers like `mthds-js`'s `PipelexRunner`") was about logs, not prints. The log-target flip alone fixes it.
-
-Separately, the agent CLI's stdout channel is a strict JSON contract for downstream tooling. It deserves explicit, defense-in-depth hardening at the factory level so a user override in `~/.pipelex/pipelex.toml` cannot re-pollute it.
-
-## Part 1 — Partial revert on `fix/Log-target`
-
-### What stays
-
-In all three TOML files, **keep** `console_log_target = "stderr"`:
-
-- `pipelex/pipelex.toml:73`
-- `pipelex/kit/configs/pipelex.toml:164`
-- `.pipelex/pipelex.toml:164`
-
-Rationale: logs are diagnostics, they belong on stderr per 12-factor/Unix convention. This matches the stated intent of PR #452 ("default to stderr for outputs happening before initialization"). Empirically this is what surfaces the original bug — the failing case in `tests/e2e/agent_cli/test_stdout_is_clean_json.py` is a `log.debug(...)` call from `pipelex/system/telemetry/telemetry_factory.py:77` routed through the `RichHandler`, which obeys `console_log_target`.
-
-### What reverts
-
-In all three TOML files, **flip back** `console_print_target = "stdout"`:
-
-- `pipelex/pipelex.toml:74` → `console_print_target = "stdout"`
-- `pipelex/kit/configs/pipelex.toml:165` → `console_print_target = "stdout"`
-- `.pipelex/pipelex.toml:165` → `console_print_target = "stdout"`
-
-Rationale: confirmed user-facing regression. With the post-flip tree:
-
-```
-$ .venv/bin/pipelex show backends > out.txt 2> err.txt
-$ wc -c out.txt err.txt
- 0 out.txt
-4110 err.txt
-```
-
-The entire backends table now lands on stderr. Same regression for `pipelex show models <backend>`, `pipelex which <code>`, `pipelex doctor`, and especially `pipelex show models <backend> --flat` whose docstring explicitly advertises it as "easy to copy-paste into configuration files".
-
-The breakage is real because `pipelex show backends` (and friends) route through `get_console()` → `pipelex_hub._console` → controlled by `console_print_target`. See `pipelex/cli/commands/show_cmd.py:96` and the `pipelex_hub.set_console_print_target(...)` call at `pipelex/pipelex.py:118` driven by the config value.
-
-### What changes in tests
-
-`tests/unit/pipelex/tools/test_log_config_defaults.py` (already on the branch): widen the assertion to pin both targets to their intended values, so neither knob can be flipped silently in either direction:
-
-```python
-assert log_config.console_log_target == ConsoleTarget.STDERR # logs are diagnostics
-assert log_config.console_print_target == ConsoleTarget.STDOUT # prints are data
-```
-
-Also extend the test to additionally validate the **kit template** (`pipelex/kit/configs/pipelex.toml`) — currently a partial revert of just the kit template (the file `pipelex init` copies to `~/.pipelex/`) would pass this test silently. Either add a second test or parametrize over both `(package_default, kit_template)` paths.
-
-`tests/e2e/agent_cli/test_stdout_is_clean_json.py` (already on the branch): no changes needed — it surfaces the LOG-target bug via the `RichHandler`, and the log target stays `stderr` post-revert. The test stays green and stays meaningful.
-
-### What changes in the changelog
-
-Rewrite the `## [Unreleased]` entry to narrow the scope. Replace the current single bullet with:
-
-```markdown
-### Fixed
-
-- **`console_log_target` package default is now `stderr` (was `stdout`).** Logs now stay off the data channel by default, matching the intent of PR #452 ("default to stderr for outputs happening before initialization"). Downstream tooling that parses `pipelex` / `pipelex-agent` stdout as JSON (e.g. `mthds-js`'s `PipelexRunner`) is no longer at risk of stdout pollution from package-level logs — the bug was latent for stock installs because the agent-CLI JSON paths happen not to log at INFO+, but surfaced for anyone who raised `package_log_levels.pipelex` to DEBUG or added a setup-time log on the command path. Same flip applied to the kit template (`pipelex/kit/configs/pipelex.toml`) that `pipelex init` copies to `~/.pipelex/`. **Note:** `console_print_target` is intentionally left at `stdout` — the main `pipelex` CLI emits human-facing tables (`show backends`, `show models`, `which`, `doctor`) via that channel, and downstream piping (`pipelex show backends > out.txt`) must keep working.
-```
-
-Drop the migration sentence that said "anyone who was capturing stdout to collect logs should switch to capturing stderr" — it's no longer true at this scope (logs were on stdout already only by virtue of `console_log_target = "stdout"`; same flip). Keep the framing as a `Fixed`, not a `Breaking`, because no user behavior that *should have worked* gets broken.
-
-### Commit shape
-
-One commit on `fix/Log-target`:
-
-```
-fix(logs): keep console_print_target on stdout (logs to stderr, prints to stdout)
-
-Walks back the print_target half of ac858de8 — that flip broke
-`pipelex show backends > out.txt` (empty file). Log target stays on
-stderr (the actual fix for stdout-as-JSON-channel pollution); print
-target reverts to stdout because the main pipelex CLI's human-facing
-tables go through get_console() and must remain redirectable.
-```
-
-Then run `make agent-check && make agent-test` and force-push the branch (history-rewrite is fine here since the PR isn't merged yet).
-
-## Part 2 — Agent CLI stdout hardening (the deeper fix) — LANDED
-
-> Why this is its own piece of work: the partial revert above restores correctness for stock installs, but the agent CLI's stdout-as-JSON-channel contract is too important to leave at the mercy of the user's `~/.pipelex/pipelex.toml`. A user override of `console_print_target = "stderr"` shouldn't break the agent CLI's data channel either way, and a hypothetical override of `console_log_target = "stdout"` must NOT re-pollute the agent CLI's stdout. The defense should live in the factory, not depend on the config defaults staying lucky.
-
-> **Implementation note vs the original plan below.** The original plan proposed a single post-init `get_pipelex_hub().set_console_print_target(STDERR)` line. That covers post-init `get_console().print(...)` calls, but does NOT cover logs/prints that fire DURING `Pipelex.make()` (e.g. `telemetry_factory.py:77` DEBUG line, the deck-notice print). The shipped fix uses `config_overrides` passed to `Pipelex.make()` to pin both `console_log_target` and `console_print_target` to `stderr` from the very first log/print, which is strictly stronger. The post-init `set_console_print_target` and `log.redirect_to_stderr()` calls are kept as defense-in-depth.
-
-### The contract we want
-
-For every `pipelex-agent <command>` invocation:
-
-| Channel | What goes there | Enforcement |
-|---|---|---|
-| **stdout** | ONLY the structured success envelope (JSON via `--format json`, or markdown via `--format markdown`). Nothing else. | `agent_success` / `agent_success_formatted` use bare `print(...)` to stdout — that's it. No log handler, no hub console, no `pretty_print` ever writes to stdout. |
-| **stderr** | Logs (any level), all `get_console().print(...)` output (banners, deck notices, plugin list tables), all `pretty_print(...)` output (currently silenced via `PrettyPrinter.mode = PrettyPrintMode.SILENT`), structured error envelopes via `agent_error`. | Factory forces all three subsystems to stderr at boot, regardless of user config. |
-
-The contract must hold:
-
-- Regardless of `console_log_target` / `console_print_target` in the user's config.
-- Regardless of `package_log_levels.pipelex` raising the verbosity.
-- Regardless of any `get_console().print(...)` call site added in the future on the agent CLI's setup or command path.
-
-### Current state (`make_pipelex_for_agent_cli`, `pipelex/cli/agent_cli/commands/agent_cli_factory.py:118-122`)
-
-```python
-# Suppress Rich pretty-printing and INFO/DEV/DEBUG log noise so that agent
-# commands only emit structured JSON. Warnings and errors still reach stderr.
-PrettyPrinter.mode = PrettyPrintMode.SILENT
-log.set_level_for_package("pipelex", log_level)
-log.redirect_to_stderr()
-return pipelex_instance
-```
-
-- ✅ `PrettyPrinter.mode = SILENT` neutralizes `pretty_print(...)` entirely (the bare `Console()` at `pretty.py:214` would have hit stdout — silencing the printer is the simplest defense).
-- ✅ `log.redirect_to_stderr()` forces `RichHandler.console = Console(file=sys.stderr)` regardless of `console_log_target`.
-- ❌ **Missing:** no symmetric `pipelex_hub.set_console_print_target(ConsoleTarget.STDERR)` call. The hub's `_console` is whatever the user's `console_print_target` says — which, after Part 1, defaults to stdout. So any `get_console().print(...)` reached during agent CLI setup or command execution writes to stdout. That's a JSON-channel pollution risk.
-
-### Where `get_console()` is reached on the agent CLI path
-
-Grep `get_console` across the codebase. Today the call sites include:
-
-- `pipelex/cli/_cli.py:111` — banner in `app_callback` (main CLI only, the agent CLI has its own callback in `_agent_cli.py` which does not print the banner — verify).
-- `pipelex/cli/deck_notice.py:34` — first-run deck notice. Triggered from `Pipelex.make()` setup paths. Could fire under the agent CLI.
-- `pipelex/plugins/openai/openai_list.py`, `anthropic_list.py`, `google_list.py`, `mistral_list.py`, `bedrock_list.py` — backend list tables. Reachable from `pipelex show models <backend>` (main CLI) but NOT directly from agent CLI commands today — verify.
-- `pipelex/cli/error_handlers.py` — error panels for various exception types. Used by the main CLI, not the agent CLI (agent CLI uses `agent_error()` instead).
-
-The risk surface today is small — primarily `deck_notice` and any future setup-time addition. But "small" is not "zero", and the contract is too important to depend on a static-analysis snapshot.
-
-### The fix
-
-Add ONE line to `make_pipelex_for_agent_cli` (after Pipelex init, alongside the existing log redirect):
-
-```python
-from pipelex.hub import get_pipelex_hub
-from pipelex.system.console_target import ConsoleTarget
-
-# (after PrettyPrinter.mode = SILENT and before/after log.redirect_to_stderr())
-get_pipelex_hub().set_console_print_target(target=ConsoleTarget.STDERR)
-```
-
-This makes `get_console()` return a stderr-bound Console for the entire agent CLI process lifetime, regardless of what the user's config said. Symmetric to `log.redirect_to_stderr()`. Together with the existing `PrettyPrinter.mode = SILENT`, every diagnostic output channel is pinned to stderr at the boundary.
-
-Confirm the hub-access import path: today the file imports `Pipelex`, not the hub directly. Find the canonical import (it's likely `from pipelex.hub import get_pipelex_hub` — verify in `pipelex/hub.py`).
-
-### Test coverage
-
-Add a new test (or extend `tests/e2e/agent_cli/test_stdout_is_clean_json.py`) that pins the defense:
-
-**Test: agent CLI ignores user override of `console_print_target = "stderr"`** — wait, this would actually trivially pass since the override IS stderr. The real test is the **inverse**:
-
-**Test: agent CLI keeps stdout clean even when user overrides BOTH targets to stdout.**
-
-```python
-def test_agent_cli_resists_user_override_to_stdout(
- self,
- hermetic_home: Path,
- offline_subprocess_env: dict[str, str],
-) -> None:
- """Defense-in-depth: even with `console_log_target = "stdout"` AND
- `console_print_target = "stdout"` in the user's pipelex.toml, the agent
- CLI must keep its stdout channel clean for JSON consumers.
- """
- pipelex_toml = hermetic_home / ".pipelex" / "pipelex.toml"
- _set_pipelex_package_log_level_to_debug(pipelex_toml)
- _set_console_targets(pipelex_toml, log_target="stdout", print_target="stdout")
-
- result = subprocess.run(
- [str(PIPELEX_AGENT_BIN), "--log-level", "debug", "models", "--format", "json"],
- env=offline_subprocess_env, cwd=str(hermetic_home),
- capture_output=True, text=True, check=False, timeout=120,
- )
-
- assert result.returncode == 0, ...
- payload = json.loads(result.stdout) # must still parse cleanly
- assert payload.get("success") is True
-```
-
-This is the test that pins the contract end-to-end. The helper `_set_console_targets` rewrites the two TOML keys (similar to the existing `_set_pipelex_package_log_level_to_debug`). Watch out for the helper-fragility class flagged in the code review (use anchored regex or a tomlkit round-trip rather than `startswith`).
-
-Optionally also parametrize the test across multiple JSON-emitting agent commands (`models`, `check-model`, `validate bundle --format json --dry-run`, `doctor --format json`) so a future setup-path `get_console()` addition on any one of them surfaces immediately.
-
-### Companion: audit `get_console()` call sites for "data vs diagnostic"
-
-This is the larger architectural cleanup, NOT in scope for this PR but worth a follow-up issue:
-
-`get_console()` today is used for both:
-
-- **Data** that users pipe to files (`pipelex show backends`, `pipelex show models`, `pipelex which`) — should write to stdout.
-- **Diagnostics** that users want on stderr (banners, deck notices, error panels) — should write to stderr.
-
-Mixing the two in one knob is the root cause of the current confusion. The cleanest long-term shape is to split the hub into two consoles:
-
-- `hub.get_data_console()` — pinned to stdout. Used by `show backends`, `show models`, `which`, `doctor`, `show config`, `show pipe`. Always redirectable to a file.
-- `hub.get_diag_console()` — pinned to stderr. Used by banner, deck notice, error panels, anything that's "talking to the human about the run".
-
-`pretty_print` would also pick one of the two (probably `data` for `show pipe`, `show config`; or expose both flavors). The `console_print_target` config knob then either goes away entirely (the split is hardcoded) or is renamed and re-scoped to only the diag console (which would be weird since stderr is the only sensible default).
-
-That's a bigger PR. Out of scope for `fix/Log-target`. File as a follow-up.
-
-## Acceptance criteria
-
-For Part 1 (partial revert) — must hold before re-pushing `fix/Log-target`:
-
-- [ ] `console_log_target = "stderr"` in all three TOML files.
-- [ ] `console_print_target = "stdout"` in all three TOML files.
-- [ ] `pipelex show backends > /tmp/out.txt && [ -s /tmp/out.txt ]` (non-empty stdout).
-- [ ] `pipelex-agent --log-level debug models --format json | jq .success` returns `true` (stdout still clean JSON).
-- [ ] Unit test pins both targets (log=stderr, print=stdout); covers package default AND kit template paths.
-- [ ] E2E test still passes — surfaces the log-target bug via `log.debug` → RichHandler → stderr.
-- [ ] CHANGELOG entry narrowed to scope (logs only).
-- [ ] `make agent-check && make agent-test` clean.
-
-For Part 2 (agent CLI hardening) — LANDED in this PR:
-
-- [x] `make_pipelex_for_agent_cli` injects `config_overrides` pinning both targets to stderr, and additionally calls `get_pipelex_hub().set_console_print_target(STDERR)` post-init alongside `log.redirect_to_stderr()`.
-- [x] New E2E test `test_models_json_stdout_resists_user_targets_override_to_stdout` pins the contract under adversarial user overrides (both targets set to stdout, package log level DEBUG, `--log-level debug`).
-- [ ] (Optional but recommended) E2E test parametrized across `models`, `check-model`, `doctor`, `validate bundle` — all JSON-emitting agent commands. Deferred: the current test exercises the same `Pipelex.make()` setup path that every other agent command goes through, so adding more command variants gives marginal extra signal.
-- [x] Docstring of `make_pipelex_for_agent_cli` updated to explicitly call out the stdout-channel contract.
-
-## How to start (cold)
-
-1. `git checkout fix/Log-target && git log --oneline -3` — confirm at `ac858de8`.
-2. Run the regression check first to internalize what's broken:
- ```
- .venv/bin/pipelex show backends > /tmp/out.txt 2> /tmp/err.txt
- wc -c /tmp/out.txt /tmp/err.txt # expect 0 out, ~4k err
- ```
-3. Do Part 1 (partial revert + test + changelog) as one commit. Push.
-4. Open a fresh branch `feature/agent-cli-stdout-defense` off `dev` (after Part 1 lands) for Part 2.
-5. Implement Part 2 (one-line hub call + new E2E test + docstring update). Push as a separate PR.
-
-## References
-
-- Original bug commit: `ac858de8` "fix: route console logs and prints to stderr by default"
-- The PR that introduced the targetable knobs: `dd0c9d266` "feature/JSONContent" (PR #452, 2025-11-18) — stated intent was stderr defaults; the package default ended up flipped to stdout.
-- The PR that propagated the wrong default into the kit template: `9580406c` "Feature/chicago" (PR #706, 2026-02-25).
-- Downstream JSON consumer that motivated the fix: `mthds-js`'s `PipelexRunner` — does `JSON.parse(stdout)` on `pipelex-agent models --format json`, `check-model --format json`, etc.
-- Agent CLI authoring conventions: `pipelex/cli/agent_cli/CLAUDE.md`.
diff --git a/wip/dataclass-refactor-story.html b/wip/dataclass-refactor-story.html
deleted file mode 100644
index c566009fb..000000000
--- a/wip/dataclass-refactor-story.html
+++ /dev/null
@@ -1,335 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>Data-Class Refactor — result &amp; the Temporal converter change</title>
-<style>
- :root {
- --bg: #0f1117;
- --panel: #181b24;
- --panel-2: #1f2330;
- --ink: #e8eaf0;
- --muted: #9aa3b6;
- --line: #2c3142;
- --accent: #6ea8fe;
- --green: #5fd38f;
- --amber: #f0c060;
- --red: #f08a8a;
- --violet: #b08cf0;
- --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
- }
- * { box-sizing: border-box; }
- body {
- margin: 0; background: var(--bg); color: var(--ink);
- font: 16px/1.62 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
- -webkit-font-smoothing: antialiased;
- }
- .wrap { max-width: 940px; margin: 0 auto; padding: 52px 28px 110px; }
- header.hero { border-bottom: 1px solid var(--line); padding-bottom: 28px; margin-bottom: 36px; }
- .eyebrow { font: 600 12px/1 var(--mono); letter-spacing: .14em; text-transform: uppercase; color: var(--accent); }
- h1 { font-size: 32px; line-height: 1.18; margin: 14px 0 10px; letter-spacing: -.01em; }
- .sub { color: var(--muted); font-size: 17px; max-width: 720px; }
- .meta { margin-top: 16px; display: flex; flex-wrap: wrap; gap: 8px; }
- .chip { font: 600 12px/1 var(--mono); padding: 6px 10px; border-radius: 999px; background: var(--panel-2); border: 1px solid var(--line); color: var(--muted); }
- h2 { font-size: 21px; margin: 48px 0 14px; letter-spacing: -.01em; padding-left: 12px; border-left: 3px solid var(--accent); }
- h3 { font-size: 15px; margin: 26px 0 8px; color: var(--ink); font-family: var(--mono); }
- p { margin: 11px 0; }
- .muted { color: var(--muted); }
- strong { color: #fff; }
- code { font: 13.5px/1.5 var(--mono); background: var(--panel-2); padding: 1.5px 6px; border-radius: 5px; border: 1px solid var(--line); color: #d7def0; }
- .panel { background: var(--panel); border: 1px solid var(--line); border-radius: 12px; padding: 18px 20px; margin: 16px 0; }
- .callout { border-left: 3px solid var(--amber); background: var(--panel); border-radius: 0 10px 10px 0; padding: 13px 17px; margin: 16px 0; }
- .callout.bug { border-left-color: var(--red); }
- .callout.ok { border-left-color: var(--green); }
- .callout.key { border-left-color: var(--accent); }
- .callout .lbl { font: 600 11px/1 var(--mono); letter-spacing: .1em; text-transform: uppercase; color: var(--amber); }
- .callout.bug .lbl { color: var(--red); }
- .callout.ok .lbl { color: var(--green); }
- .callout.key .lbl { color: var(--accent); }
- .callout p { margin: 7px 0 0; }
-
- table { width: 100%; border-collapse: collapse; margin: 14px 0; font-size: 13.5px; }
- th, td { text-align: left; padding: 9px 11px; border-bottom: 1px solid var(--line); vertical-align: top; }
- th { font: 600 11px/1.3 var(--mono); letter-spacing: .06em; text-transform: uppercase; color: var(--muted); }
- td code { font-size: 12.5px; }
- .tag { font: 600 11px/1 var(--mono); padding: 3px 7px; border-radius: 6px; border: 1px solid var(--line); white-space: nowrap; }
- .tag.nt { color: var(--accent); border-color: #3a4a66; }
- .tag.pd { color: var(--violet); border-color: #4a3a66; }
- .tag.bmf { color: var(--green); border-color: #2f5d44; }
- .tag.bmm { color: var(--amber); border-color: #5d4f2c; }
- .yes { color: var(--green); font-weight: 700; }
- .no { color: var(--red); font-weight: 700; }
- tbody tr:hover { background: var(--panel); }
-
- .diff { background: #11141c; border: 1px solid var(--line); border-radius: 10px; overflow-x: auto; margin: 13px 0; font: 12.5px/1.7 var(--mono); }
- .diff .fname { padding: 8px 14px; border-bottom: 1px solid var(--line); color: var(--muted); background: var(--panel-2); font-weight: 600; }
- .diff pre { margin: 0; padding: 12px 14px; }
- .diff .add { color: var(--green); display: block; }
- .diff .del { color: var(--red); display: block; }
- .diff .ctx { color: #8b93a7; display: block; }
- .diff .hdr { color: var(--accent); display: block; }
-
- figure { margin: 20px 0; background: var(--panel); border: 1px solid var(--line); border-radius: 12px; padding: 18px 18px 10px; }
- figure pre.mermaid { background: transparent; border: 0; margin: 0; text-align: center; }
- figure svg { display: block; max-width: 100%; height: auto; margin: 0 auto; }
- figcaption { color: var(--muted); font-size: 12.5px; text-align: center; margin-top: 10px; font-family: var(--mono); }
-
- ul.tight { margin: 9px 0; padding-left: 22px; }
- ul.tight li { margin: 5px 0; }
- footer { margin-top: 56px; padding-top: 22px; border-top: 1px solid var(--line); color: var(--muted); font-size: 13px; }
-</style>
-</head>
-<body>
-<div class="wrap">
-
-<header class="hero">
- <div class="eyebrow">refactor/Dataclasses · for co-developers</div>
- <h1>Data holders got the right shape — and the Temporal wire learned a new one</h1>
- <p class="sub">We removed every stdlib <code>@dataclass</code> from <code>pipelex/</code>, replacing each with the lowest-churn <em>correct</em> form per site instead of blanket <code>BaseModel</code>. The enabling change: the Temporal payload converter now serializes <strong>pydantic dataclasses</strong> with full type preservation, not just <code>BaseModel</code>.</p>
- <div class="meta">
- <span class="chip">refactor/Dataclasses → dev</span>
- <span class="chip">PR #949</span>
- <span class="chip">kajson 0.5.0 → 0.6.0</span>
- <span class="chip">9 prod files · 3 new test suites</span>
- </div>
-</header>
-
-<p>Two results to take away:</p>
-<ol style="margin:10px 0 0; padding-left:20px">
- <li style="margin:6px 0"><strong>A rule for picking a data-holder shape</strong> (the decision tree below) — use it whenever you add or convert one.</li>
- <li style="margin:6px 0"><strong>A widened Temporal converter</strong> — pydantic dataclasses are now wire-legal, with the existing <code>BaseModel</code> path byte-for-byte unchanged.</li>
-</ol>
-
-<h2>Picking a shape</h2>
-
-<p>No stdlib <code>@dataclass</code> survives in <code>pipelex/</code>. The easy fix would be to make everything a <code>BaseModel</code> — we deliberately didn't. We use four forms, picked by which capabilities the site actually needs:</p>
-
-<table>
- <thead><tr><th>Form</th><th>Wire-legal</th><th>Capabilities we leverage</th><th>We use it for</th></tr></thead>
- <tbody>
- <tr>
- <td><span class="tag nt">NamedTuple</span></td>
- <td><span class="no">✗</span></td>
- <td>Named fields, immutable, positional-unpack compatible, and <strong>zero validation</strong> (so it can hold a bare Protocol or arbitrary type), no pydantic overhead.</td>
- <td>Small fixed records replacing bare tuples; holders of a <code>@runtime_checkable</code> Protocol or other non-pydantic field.</td>
- </tr>
- <tr>
- <td><span class="tag pd">pydantic dataclass</span></td>
- <td><span class="yes">✓</span></td>
- <td>Dataclass idioms — <code>field(default_factory=…)</code>, computed <code>@property</code>, <code>frozen=</code> — <strong>plus</strong> validation/coercion on construction. No <code>model_dump</code> / <code>model_validate</code>.</td>
- <td>Internal records that are built + field-read but <strong>never serialized</strong>. Lowest-churn swap from a stdlib <code>@dataclass</code> (just the decorator).</td>
- </tr>
- <tr>
- <td><span class="tag bmf">frozen BaseModel</span></td>
- <td><span class="yes">✓</span></td>
- <td>The full model API (<code>model_dump</code>, validators, discriminated unions), immutability, hashability, and — crucially — being <strong>type-distinct from <code>tuple</code></strong>.</td>
- <td>Immutable value objects that need the model API, sit in a uniformly-<code>BaseModel</code> layer, or must not be mistaken for a tuple in a union.</td>
- </tr>
- <tr>
- <td><span class="tag bmm">mutable BaseModel</span></td>
- <td><span class="yes">✓</span></td>
- <td>The full model API <strong>and</strong> in-place field mutation.</td>
- <td>Objects genuinely mutated in place that also want the model API or layer consistency. (Else a non-frozen pydantic dataclass is lighter.)</td>
- </tr>
- </tbody>
-</table>
-
-<p class="muted">The deciding question is the <strong>Wire-legal</strong> column crossed with "does it need the model API / serialization?" — the tree below walks exactly that:</p>
-
-<figure>
-<pre class="mermaid">
-flowchart TD
- A["A data holder<br/>(stdlib @dataclass or bare tuple)"] --> B{"Crosses the<br/>Temporal wire?"}
- B -- "Yes" --> W["BaseModel or pydantic dataclass<br/>— nothing else is wire-legal —"]
- B -- "No (off-wire)" --> C{"A field is a bare Protocol /<br/>arbitrary non-pydantic type?"}
- C -- "Yes" --> NT["NamedTuple<br/>skips validation, no<br/>arbitrary_types_allowed dance"]
- C -- "No" --> D{"Returned in a union<br/>beside a real tuple?"}
- D -- "Yes" --> BM1["frozen BaseModel<br/>a BaseModel is NOT a tuple →<br/>isinstance stays unambiguous"]
- D -- "No" --> E{"Ever serialized? Needs<br/>model_dump / validators /<br/>discriminated unions?"}
- E -- "Yes" --> BM2["BaseModel<br/>(frozen or mutable)"]
- E -- "No" --> F{"Mutated in place<br/>after construction?"}
- F -- "Yes" --> PDM["pydantic dataclass<br/>(non-frozen)"]
- F -- "No" --> PDF["frozen pydantic dataclass<br/>lowest churn: swap the decorator"]
-
- classDef wire fill:#1f2330,stroke:#6ea8fe,color:#e8eaf0;
- classDef nt fill:#1f2330,stroke:#6ea8fe,color:#cfe0ff;
- classDef pd fill:#241f33,stroke:#b08cf0,color:#e7dcff;
- classDef bm fill:#1b2a22,stroke:#5fd38f,color:#d8f5e6;
- class W wire; class NT nt; class PDM,PDF pd; class BM1,BM2 bm;
-</pre>
-<figcaption>"Does this ever need serializing?" is the deciding question. If yes → BaseModel from the start. Never reach for TypeAdapter — needing it means the shape was wrong.</figcaption>
-</figure>
-
-<h3>What each type became</h3>
-<table>
- <thead><tr><th>Type</th><th>Now</th><th>Why</th></tr></thead>
- <tbody>
- <tr><td><code>CrossPackageRef</code>, <code>StructureNameAndRefine</code></td><td><span class="tag nt">NamedTuple</span></td><td>Bare tuple returns; named fields stop positional swaps. All call sites positional-unpack.</td></tr>
- <tr><td><code>_EventLogContext</code> <span class="muted">(reporting)</span></td><td><span class="tag nt">NamedTuple</span></td><td>Holds a bare <code>@runtime_checkable</code> Protocol — NamedTuple skips validation, so no <code>arbitrary_types_allowed</code>.</td></tr>
- <tr><td><code>VariableReference</code> <span class="muted">(jinja2)</span></td><td><span class="tag pd">pydantic dataclass</span></td><td>Mutated in place (<code>.filters.append(…)</code>) → not frozen, no model API needed.</td></tr>
- <tr><td><code>ErrorPagesReport</code> <span class="muted">(errors)</span></td><td><span class="tag pd">frozen pydantic dataclass</span></td><td>Dev-tool report with <code>field(default_factory=…)</code> + a computed property; never serialized.</td></tr>
- <tr><td><code>CustomClassInfo</code> <span class="muted">(builder)</span></td><td><span class="tag bmf">frozen BaseModel</span></td><td>Lives in the uniformly-<code>BaseModel</code> builder layer.</td></tr>
- <tr><td><code>RegistrationFailure</code> <span class="muted">(temporal admin)</span></td><td><span class="tag bmf">frozen BaseModel</span></td><td>Returned as <code>X | tuple[str, ...]</code> — must stay type-distinct from the tuple arm.</td></tr>
- <tr><td><code>DispatchOptions</code> <span class="muted">(temporal)</span></td><td><span class="tag pd">frozen pydantic dataclass</span></td><td>Build-once-read-only; holds a live <code>RetryPolicy</code> (see the import note below).</td></tr>
- </tbody>
-</table>
-
-<h2>The Temporal converter change</h2>
-
-<p><code>pipelex/temporal/temporal_data_converter.py</code> defines <strong><code>BaseModelPayloadConverter</code></strong> — the class Temporal calls to turn every workflow/activity argument and return value into bytes, and back. Pipelex sends selected values through <strong>kajson</strong> instead of Temporal's stock JSON, because kajson stamps each object with its <code>__class__</code> / <code>__module__</code> so the receiver rebuilds the <em>exact</em> Python class. Stock JSON would hand back a plain <code>dict</code> and lose the type.</p>
-
-<p><strong>What changed:</strong> the set of values that take the kajson lane. Before, only <code>BaseModel</code>, <code>Optional[BaseModel]</code>, and <code>list[BaseModel]</code> qualified. Now pydantic dataclasses (and <code>Optional</code> / <code>list</code> of them) qualify too. The <code>BaseModel</code> lane is unchanged.</p>
-
-<figure>
-<svg viewBox="0 0 900 300" role="img" aria-label="Converter routing: kajson lane vs stock JSON lane">
- <defs>
- <marker id="a" markerWidth="9" markerHeight="9" refX="6" refY="3" orient="auto"><path d="M0,0 L6,3 L0,6 Z" fill="#9aa3b6"/></marker>
- <marker id="ag" markerWidth="9" markerHeight="9" refX="6" refY="3" orient="auto"><path d="M0,0 L6,3 L0,6 Z" fill="#5fd38f"/></marker>
- </defs>
-
- <!-- inputs -->
- <rect x="14" y="54" width="176" height="60" rx="9" fill="#1f2330" stroke="#2c3142"/>
- <text x="102" y="78" text-anchor="middle" fill="#9aa3b6" font-family="ui-monospace,Menlo,monospace" font-size="10">SERIALIZE</text>
- <text x="102" y="98" text-anchor="middle" fill="#e8eaf0" font-family="ui-monospace,Menlo,monospace" font-size="11.5">to_payload(value)</text>
-
- <rect x="14" y="186" width="176" height="60" rx="9" fill="#1f2330" stroke="#2c3142"/>
- <text x="102" y="210" text-anchor="middle" fill="#9aa3b6" font-family="ui-monospace,Menlo,monospace" font-size="10">DESERIALIZE</text>
- <text x="102" y="230" text-anchor="middle" fill="#e8eaf0" font-family="ui-monospace,Menlo,monospace" font-size="11">from_payload(.., type_hint)</text>
-
- <!-- gate -->
- <rect x="252" y="102" width="220" height="96" rx="11" fill="#181b24" stroke="#6ea8fe"/>
- <text x="362" y="128" text-anchor="middle" fill="#e8eaf0" font-family="ui-monospace,Menlo,monospace" font-size="12" font-weight="700">kajson wire shape?</text>
- <text x="362" y="152" text-anchor="middle" fill="#6ea8fe" font-family="ui-monospace,Menlo,monospace" font-size="10.5">_is_kajson_wire_value(value)</text>
- <text x="362" y="170" text-anchor="middle" fill="#6ea8fe" font-family="ui-monospace,Menlo,monospace" font-size="10.5">_is_kajson_type(type_hint)</text>
- <text x="362" y="188" text-anchor="middle" fill="#9aa3b6" font-family="ui-monospace,Menlo,monospace" font-size="10">BaseModel OR is_pydantic_dataclass</text>
-
- <line x1="190" y1="84" x2="252" y2="135" stroke="#9aa3b6" stroke-width="1.6" marker-end="url(#a)"/>
- <line x1="190" y1="216" x2="252" y2="165" stroke="#9aa3b6" stroke-width="1.6" marker-end="url(#a)"/>
-
- <!-- kajson lane -->
- <rect x="560" y="40" width="326" height="104" rx="11" fill="#1b2a22" stroke="#2f5d44"/>
- <text x="576" y="64" fill="#5fd38f" font-family="ui-monospace,Menlo,monospace" font-size="12" font-weight="700">kajson lane — type preserved</text>
- <text x="576" y="84" fill="#cfe0d8" font-family="ui-monospace,Menlo,monospace" font-size="10.5">kajson.dumps / kajson.loads (+ __class__ / __module__ tags)</text>
- <text x="576" y="108" fill="#9aa3b6" font-family="ui-monospace,Menlo,monospace" font-size="10.5">BaseModel · Optional[X] · list[X] (unchanged)</text>
- <text x="576" y="126" font-family="ui-monospace,Menlo,monospace" font-size="10.5"><tspan fill="#b08cf0" font-weight="700">+ pydantic dataclass</tspan><tspan fill="#9aa3b6"> — newly routed here</tspan></text>
-
- <!-- stock lane -->
- <rect x="560" y="196" width="326" height="68" rx="11" fill="#1a1a1f" stroke="#3a3f4d"/>
- <text x="576" y="222" fill="#cdd5e6" font-family="ui-monospace,Menlo,monospace" font-size="12" font-weight="700">super().to_payload / from_payload</text>
- <text x="576" y="244" fill="#9aa3b6" font-family="ui-monospace,Menlo,monospace" font-size="10.5">Temporal stock JSON — type identity lost (plain dict back)</text>
-
- <line x1="472" y1="130" x2="560" y2="92" stroke="#5fd38f" stroke-width="1.8" marker-end="url(#ag)"/>
- <text x="516" y="100" text-anchor="middle" fill="#5fd38f" font-family="ui-monospace,Menlo,monospace" font-size="10">wire shape</text>
- <line x1="472" y1="172" x2="560" y2="226" stroke="#9aa3b6" stroke-width="1.6" marker-end="url(#a)"/>
- <text x="514" y="208" text-anchor="middle" fill="#9aa3b6" font-family="ui-monospace,Menlo,monospace" font-size="10">everything else</text>
-</svg>
-<figcaption>The converter is a router. The only change is the gate: the kajson lane now also admits pydantic dataclasses. Both lanes were already there.</figcaption>
-</figure>
-
-<h3>Two directions, two checks</h3>
-<p>Serialization holds the actual <em>value</em>; deserialization holds only the declared <em>type hint</em>. So the same question is asked two ways:</p>
-<ul class="tight">
- <li><strong><code>to_payload</code></strong> asks <code>_is_kajson_wire_value(value)</code> = <code>isinstance(value, BaseModel) or is_pydantic_dataclass(type(value))</code>.</li>
- <li><strong><code>from_payload</code></strong> asks <code>_is_kajson_type(type_hint)</code> — the same test one level up — and reuses it for the scalar, <code>Optional[X]</code>, and <code>list[X]</code> shapes.</li>
-</ul>
-
-<p>The old code inlined the <code>BaseModel</code> checks and <strong>duplicated</strong> the payload/metadata building across the scalar and list branches. We factored that into <code>_kajson_to_payload</code> + <code>_first_kajson_list_element</code>, then added the dataclass arm <em>behind</em> the <code>BaseModel</code> short-circuit so the hot path is untouched:</p>
-
-<div class="diff">
- <div class="fname">temporal_data_converter.py — to_payload (serialize)</div>
-<pre><span class="del">- if isinstance(value, BaseModel):</span>
-<span class="del">- payload_str = kajson.dumps(value)</span>
-<span class="del">- metadata = {"encoding": self.encoding.encode()}</span>
-<span class="del">- class_source = getattr(type(value), "__kajson_class_source__", None)</span>
-<span class="del">- ... # the same 6 lines, duplicated again below</span>
-<span class="del">- elif isinstance(value, list) and value and isinstance(value[0], BaseModel):</span>
-<span class="del">- ...</span>
-<span class="del">- else:</span>
-<span class="del">- return super().to_payload(value)</span>
-<span class="add">+ if self._is_kajson_wire_value(value): # scalar: BaseModel or pydantic dataclass</span>
-<span class="add">+ return self._kajson_to_payload(value, source_type_holder=value)</span>
-<span class="add">+ list_head = self._first_kajson_list_element(value) # list[...] whose head is a wire value</span>
-<span class="add">+ if list_head is not None:</span>
-<span class="add">+ return self._kajson_to_payload(value, source_type_holder=list_head)</span>
-<span class="add">+ return super().to_payload(value) # everything else → stock JSON</span>
-</pre>
-</div>
-
-<div class="diff">
- <div class="fname">temporal_data_converter.py — the two predicates + from_payload reuse</div>
-<pre><span class="add">@classmethod</span>
-<span class="add">def _is_kajson_wire_value(cls, value: object) -&gt; bool: # used by to_payload (has the value)</span>
-<span class="add"> return isinstance(value, BaseModel) or is_pydantic_dataclass(type(value))</span>
-
-<span class="add">@classmethod</span>
-<span class="add">def _is_kajson_type(cls, type_hint: Any) -&gt; bool: # used by from_payload (has the hint)</span>
-<span class="add"> if isinstance(type_hint, type) and issubclass(type_hint, BaseModel):</span>
-<span class="add"> return True</span>
-<span class="add"> return is_pydantic_dataclass(cast("Any", type_hint)) # safe (False) on non-class hints</span>
-
-<span class="ctx"> # from_payload now routes through _is_kajson_type for all three shapes:</span>
-<span class="del">- if isinstance(type_hint, type) and issubclass(type_hint, BaseModel): ... # scalar</span>
-<span class="del">- if self._unwrap_optional_base_model(type_hint): ... # Optional[BaseModel]</span>
-<span class="del">- if origin is list and ... and issubclass(args[0], BaseModel): ... # list[BaseModel]</span>
-<span class="add">+ if self._is_kajson_type(type_hint): ... # scalar</span>
-<span class="add">+ if self._unwrap_optional_kajson_type(type_hint): ... # Optional[X]</span>
-<span class="add">+ if origin is list and ... and self._is_kajson_type(args[0]): ... # list[X]</span>
-</pre>
-</div>
-
-<div class="callout ok">
- <span class="lbl">Two guarantees</span>
- <p><strong>BaseModel path is byte-identical</strong> — locked by a regression test that asserts a <code>BaseModel</code> payload's metadata and bytes are exactly what the old code produced. And <strong>it's strictly safer</strong>: the old <code>list</code> branch called <code>issubclass(args[0], BaseModel)</code> directly, which <em>raised</em> on a non-class arg like <code>list[list[int]]</code>; <code>_is_kajson_type</code> guards with <code>isinstance(.., type)</code> first.</p>
-</div>
-
-<p class="muted">The receiving half is in kajson itself (bumped 0.5.0 → 0.6.0): a new decode branch calls <code>is_pydantic_dataclass(cls)</code> and reconstructs via <code>cls(**data)</code> — running the validator and raising loudly on bad input, instead of the old untested catch-all that silently returned a raw dict.</p>
-
-<h2>Three things worth knowing</h2>
-
-<div class="callout bug">
- <span class="lbl">A NamedTuple is a tuple</span>
- <p><code>RegistrationFailure</code> is returned as <code>RegistrationFailure | tuple[str, ...]</code> and callers do <code>isinstance(x, RegistrationFailure)</code>. A <code>NamedTuple</code> would also satisfy <code>isinstance(x, tuple)</code>, blurring the two arms — so it's a <strong>frozen BaseModel</strong>, which is cleanly not-a-tuple. Whenever a value is returned in a union beside a real tuple, model it.</p>
-</div>
-
-<div class="callout key">
- <span class="lbl">DispatchOptions stays importable without temporalio</span>
- <p>It holds a live <code>temporalio</code> <code>RetryPolicy</code>, but <code>temporalio</code> is an optional extra. A bare forward ref imports but blows up (<code>PydanticUserError</code>) on <em>construction</em>. The fix is a runtime placeholder so the field resolves to <code>Any</code> without importing temporalio:</p>
-<div class="diff" style="margin-top:10px">
-<pre><span class="ctx"> if TYPE_CHECKING:</span>
-<span class="ctx"> from temporalio.common import RetryPolicy # type checkers see the real class</span>
-<span class="add">+else:</span>
-<span class="add">+ RetryPolicy = Any # runtime: no import, no validation</span>
-</pre>
-</div>
-</div>
-
-<div class="callout ok">
- <span class="lbl">Don't convert the wire BaseModels</span>
- <p>The widening makes pydantic dataclasses <em>legal</em> on the wire; it does <strong>not</strong> motivate converting the types already there (<code>PipeJob</code>, <code>PipeOutput</code>, <code>WorkingMemory</code>, <code>Stuff</code>, the <code>StuffContent</code> union, <code>GraphSpec</code>, …). They stay <code>BaseModel</code> — they need discriminated unions, model validators, and the dynamic-class mechanism. A NamedTuple or stdlib dataclass on the wire silently corrupts distributed execution.</p>
-</div>
-
-<div class="callout bug">
- <span class="lbl">Release gate (tracked, not dev-blocking)</span>
- <p>kajson <code>0.6.0</code> is pinned via <code>[tool.uv.sources]</code> to a git rev. That section is uv-dev-only — the hatchling build strips it, so a published pipelex wheel would require <code>kajson==0.6.0</code> from PyPI, which isn't there yet. Safe on <code>dev</code> (PyPI publish fires only on <code>main</code> / <code>pre-release/v*</code>). Before any release: publish kajson 0.6.0 to PyPI, drop the git source, confirm it resolves.</p>
-</div>
-
-<footer>
- Verified green: <code>make agent-check</code> (Pyright 0/0, Mypy clean) · <code>make tb</code> · the Temporal integration suite (converter round-trips, in-process-server workflow round-trip, no-temporalio subprocess test) · <code>make agent-test</code>. Final gate: zero stdlib <code>@dataclass</code> in <code>pipelex/</code>. Source of truth: <code>TODOS.md</code> on <code>refactor/Dataclasses</code>.
-</footer>
-
-</div>
-
-<script type="module">
- import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
- mermaid.initialize({
- startOnLoad: true, theme: 'dark', securityLevel: 'loose',
- themeVariables: {
- background: '#181b24', primaryColor: '#1f2330', primaryBorderColor: '#2c3142',
- primaryTextColor: '#e8eaf0', lineColor: '#6ea8fe', secondaryColor: '#241f33',
- tertiaryColor: '#11141c', fontFamily: 'ui-monospace, Menlo, Consolas, monospace', fontSize: '13px'
- }
- });
-</script>
-</body>
-</html>
diff --git a/wip/deferred-items.md b/wip/deferred-items.md
deleted file mode 100644
index 9965152dc..000000000
--- a/wip/deferred-items.md
+++ /dev/null
@@ -1,94 +0,0 @@
-# Deferred & Future Items
-
-> Items explicitly out of scope for the current implementation phases.
-> Collected here for roadmap visibility and to preserve design context.
-
----
-
-## Architectural Direction (Future)
-
-Long-term goals documented for vision alignment. Not planned for implementation now. See [future-crate-first-architecture.md](future-crate-first-architecture.md) for the full design rationale.
-
-### Crate-First Architecture
-
-**Status**: Future vision — Phase 6 is the first step on this path.
-
-Invert the current loading-driven architecture into a crate-driven one with three cleanly separated phases: **Collect** (resolve deps, fetch remote, gather all blueprints) → **Build** (construct one crate, optionally strip to transitive closure) → **Load** (same `load_from_crate()` on submitter and worker).
-
-### Crate Stripping (Transitive Closure)
-
-**Status**: Future — depends on Phase 6a's blueprint collector.
-
-From the entry pipe, walk the transitive closure of pipe and concept dependencies to determine the minimal subset needed. Strip the crate to only those concepts, pipes, and domains. Once all blueprints (main + deps) are accumulated in 6a, stripping is a pure data transform before crate construction.
-
-### Library Fingerprint Validation
-
-**Status**: Future — no immediate need.
-
-Verify that the worker's base library (PIPELEXPATH) matches the API's expectation. Detect version drift between API and worker deployments.
-
-### Cross-Worker Cache via Shared Storage
-
-**Status**: Future — complementary to crate stripping.
-
-Cache loaded crates in shared storage (Redis, S3) so multiple workers don't redundantly load the same crate. Keyed by fingerprint. Smaller crates from stripping make this more effective.
-
----
-
-## Distributed Tracing — Deferred Items
-
-Items related to the event log and graph tracing system (Phase 4.5). Also documented in [distributed-tracing-and-reporting.md](distributed-tracing-and-reporting.md).
-
-### Event Log Backends
-
-| Item | Status | Context |
-|---|---|---|
-| DynamoDB backend | **Shipped** (2026, `feature/dynamodb-tracer`) | `pipelex/tracing/dynamodb_event_log.py` (+ `TEMPORAL_DYNAMODB` variant). Schema-compatible with `pipelex-api-infra`'s `TraceEventDynamoDBAdapter`. Selected via `[pipelex.tracing] backend = "dynamodb"`. |
-| SQLite backend | **Not planned** — NDJSON + DynamoDB cover the matrix | Listed in the original analysis (`distributed-tracing-and-reporting.md`); not built. Re-evaluate only if a use case appears that NDJSON can't serve and DynamoDB is overkill. |
-
-### Event Log Protocol Extensions
-
-| Item | Status | Context |
-|---|---|---|
-| `subscribe()` on EventLogProtocol | **Deferred** — no consumer exists yet | Polling-based reads are sufficient for now; add when a real-time consumer exists. |
-| Real-time progress consumer | **Deferred** — no consumer exists yet | The protocol supports it; build when needed. |
-| TraceSinkProtocol abstraction | **Deferred** — EventLogProtocol is sufficient | The higher-level sink abstraction can wait for the cloud backend. |
-| Large data externalization | **Deferred** — inline data is sufficient for now | Add StorageProvider offloading when traces grow too large. |
-
-### Tracing Architecture
-
-| Item | Status | Context |
-|---|---|---|
-| Unified code path (event log everywhere) | **Effectively unified** | `pipeline_run_setup.py:282` wires `set_event_log()` on the report delegate for direct mode too (using `workflow_id="direct"`). The same `EventLogProtocol` machinery runs in both modes; only the in-process vs. Temporal lifecycle differs. |
-| Auto-cleanup of traces | **Deferred** — manual cleanup is safer for now | NDJSON traces persist on disk until manually deleted. Safer for debugging and allows usage reporting to run after graph generation. DynamoDB cleanup follows TTL on the table. |
-
-### Known Issues
-
-| Item | Status | Context |
-|---|---|---|
-| Causal event ordering in assembler | **Known limitation** — works for current topologies | `read_events()` sorts by `(workflow_id, sequence)` which groups by lexicographic workflow ID, not execution order. In parent/child workflow topologies, this can cause `_stuff_producer_map` overwrites in the wrong order during `GraphSpecAssembler.pass_one()`, producing incorrect DATA edge sources. Consider sorting by timestamp or processing events in a topology-aware order. Flagged by codex on PR #796. |
-| PipeCondition SELECTED_OUTCOME wiring | **Deferred** — no production use yet | PipeCondition has no tracer calls in production code currently. If SELECTED_OUTCOME edges are needed, that's a separate change. |
-
----
-
-## Schema Reconstruction Hardening
-
-Items related to `SchemaToModelFactory` (`pipelex/cogt/content_generation/schema_to_model_factory.py`), which reconstructs Pydantic BaseModel classes from JSON schemas across process boundaries (Temporal payloads). The current implementation `exec()`'s code generated by `datamodel-code-generator` and ships that source verbatim as `__kajson_class_source__` so receivers can re-exec it. See the module docstring for the full threat model.
-
-### `exec()` → `pydantic.create_model()` Migration
-
-**Status**: Deferred — non-trivial refactor, no immediate threat-model trigger.
-
-Replace `exec()` in `_exec_source_to_types` with programmatic class construction via `pydantic.create_model()`. Eliminates the exec primitive on both the sender path (`make_from_json_schema`) and the receiver path (`make_types_from_source`), and lets us delete `_make_restricted_builtins`, `_restricted_import`, and `_reject_unsafe_schema_extensions`.
-
-Non-trivial because nested models, enums, and forward references currently rely on `datamodel-code-generator`'s output structure. A faithful port has to walk the JSON schema directly, build the class graph in dependency order, and apply `model_rebuild()` after the fact to resolve forward refs.
-
-This is the right structural fix; everything below is a stopgap until it lands.
-
-### Receiver-Side Schema Validation Gap
-
-**Status**: Known gap — documented in `make_types_from_source`'s docstring; only worth closing if the migration above is materially delayed.
-
-`make_from_json_schema` (sender) calls `_reject_unsafe_schema_extensions` before generating source — Layer 1. `make_types_from_source` (receiver) takes pre-generated source and execs it directly — only Layer 2 (`_make_restricted_builtins`) applies. An attacker who can inject a crafted `__kajson_class_source__` string into a Temporal payload bypasses Layer 1 entirely.
-
-Interim mitigation: AST-scan the source before exec, rejecting any top-level node that isn't an allowlisted import, a class def, or a docstring (and any class body that isn't fields / `model_config` / docstring). Mirrors Layer 1's "reject loudly" failure mode at the structural level. Trade-off: tied to `datamodel-code-generator`'s emitted output shape, which is not a stable API. Skip if the `create_model()` migration is near-term; the migration closes the gap permanently.
diff --git a/wip/distributed-execution/README.md b/wip/distributed-execution/README.md
new file mode 100644
index 000000000..7075fb6a8
--- /dev/null
+++ b/wip/distributed-execution/README.md
@@ -0,0 +1,115 @@
+# Distributed Execution — Plan & Track Map
+
+The big direction: run **activities on standalone Worker pools** — separate processes from the workflow Worker pool — so workflow orchestration and inference activity execution scale independently.
+
+This folder is the **distributed-execution track**: running MTHDS methods as Temporal workflows across separate worker processes. This README is the priority-ordered plan; the other docs are the per-topic designs and references it points to.
+
+## Docs in this track
+
+- [tracing-cost-reporting.md](tracing-cost-reporting.md) — as-built reference for tracing & cost reporting across workers, plus its deferred items (P0/P1 context).
+- [local-cross-package-deps.md](local-cross-package-deps.md) — ship dependency blueprints inside the crate (P2).
+- [remote-deps-from-github.md](remote-deps-from-github.md) — fetch dependencies from remote addresses (P3).
+- [crate-first-architecture.md](crate-first-architecture.md) — the crate-first vision behind P2/P3, with deferred capabilities (stripping, fingerprint validation, cross-worker cache).
+- [temporal-ids-and-naming.md](temporal-ids-and-naming.md) — implemented design for Temporal IDs, naming, and observability surfaces.
+- [temporal-exception-model-revamp.md](temporal-exception-model-revamp.md) — deferred proposal to reparent workflow exceptions onto `ApplicationError`.
+- [schema-reconstruction-hardening.md](schema-reconstruction-hardening.md) — deferred hardening of cross-process Pydantic-schema reconstruction.
+
+---
+
+## Priority order
+
+| # | Item | Detail |
+|---|---|---|
+| **P0 ✓** | Tracing & cost reporting across separate-process workers | shipped — [tracing-cost-reporting.md](tracing-cost-reporting.md) |
+| **P0.1** | Dry-run through activity dispatch (testing affordance) | below |
+| **P0.2** | Deferred follow-ons from P0 | below |
+| **P1** | Cross-worker cost report assembly wiring | depends on P0 — below |
+| **P2** | Local cross-package dependencies in the crate | [local-cross-package-deps.md](local-cross-package-deps.md) |
+| **P3** | Remote dependencies from GitHub | needs P2 — [remote-deps-from-github.md](remote-deps-from-github.md) |
+
+P0/P0.1/P0.2/P1 form one chain (P0 unlocks the rest); P2/P3 are an independent chain (P2 blocks P3). [tracing-cost-reporting.md](tracing-cost-reporting.md) carries the as-built design and the open T2/T3 gaps that motivate P1.
+
+Sibling track (separate branch, not in this plan): the error-handling work — see [`error-handling/README.md`](../error-handling/README.md).
+
+---
+
+## P0 — Tracing & cost reporting across separate-process workers — DONE
+
+Shipped. The as-built design, what works today, and the open T2/T3 gaps are in [tracing-cost-reporting.md](tracing-cost-reporting.md). The remaining cross-worker read-back is P1; the explicitly-deferred follow-ons are under P0.2.
+
+---
+
+## P0.1 — Dry-run through activity dispatch (testing affordance)
+
+Today `--dry-run` instantiates `ContentGeneratorDry()` directly inside the workflow body (`pipe_llm.py:515`, and similar sites in `pipe_extract.py`, `pipe_compose.py`, `pipe_img_gen.py`). The activity (`act_llm_gen_text` etc.) is never dispatched, so the cross-worker `UsageReportEvent` emission path cannot be exercised in dry-run against router+runner workers — the runner-side fallback only fires when the activity actually dispatches across processes. (Observed validating P0: `pipelex run bundle --temporal --dry-run --mock-inputs` against a router+runner topology produces only `writer_id="primary"` events; no `wf_*__w_act_*.ndjson` files.)
+
+What's needed: a run mode that keeps activity dispatch but mocks inference *inside* the activity (use `ContentGeneratorDry` inside the activity body, not in place of dispatching it), so the cross-process surfaces — `_event_log_contexts` lookup miss, runner-side fallback, `writer_id="act_*"` emission — all fire. Concretely: a `--mock-inference` flag distinct from `--dry-run` (or redefine `--dry-run` to dispatch-and-mock-inside and rename the current behavior); equivalent mock sites in `pipe_extract.py` / `pipe_compose.py` / `pipe_img_gen.py`; and `temporal-e2e-validate` Tier 8 able to run in this mode and surface `wf_*__w_act_*.ndjson` deterministically.
+
+Beyond P0, the same affordance unlocks dry-run e2e for any cross-process work (P1 cost report assembly, distributed graph assembly, payload codec stress testing) without real LLM spend.
+
+---
+
+## P0.2 — Deferred follow-ons from P0
+
+Each is independently scoped and not blocking. Pick up individually as signals dictate.
+
+- **`tracing_config.strict_mode: bool`** — opt-in flag that raises (instead of WARNING + drop) when the runner-side emit path fails. For compliance/audit deployments where missing trace data is a hard error.
+- **DynamoDB `BatchWriteItem` for runner emission** — the current path does one `PutItem` per usage event; `BatchWriteItem` batches up to 25. Defer until throughput shows it matters.
+- **NDJSON shared-filesystem invariant enforcement** — the NDJSON backend assumes `traces_dir` is visible to all writer processes (router pool + runner pool + `act_flush_trace_events`); multi-host deployments need NFS/EFS. Add a startup check that warns if `traces_dir` looks local-only on a multi-worker deployment.
+- **Per-thread `writer_id` for activity event log** — the surgical lock closes the duplicate-sequence race on `next_sequence()`; a per-thread writer namespace would eliminate the contention entirely and align with how Temporal's worker pool partitions activities (dedup drops to per-thread, no hot-path lock).
+- **Project-wide migration of `JobMetadata.started_at` to timezone-aware datetimes** — the landed patch builds the synthetic `now` with the incoming `started_at`'s `tzinfo`, removing the immediate `TypeError` but not the underlying inconsistency: the default factory is naive (`datetime.now`) while several callers (e.g. `pipe_abstract.py:428`) construct aware datetimes. A clean migration standardizes on `datetime.now(timezone.utc)`, documents the tz contract on `JobMetadata`, and lets `duration` subtract without per-site tzinfo matching.
+
+---
+
+## P1 — Cross-worker cost report assembly wiring
+
+### Why this is second, not first
+
+Even with P0 shipped, the events still need to be turned into a cost report. The read-back path exists for the **graph** (`assemble_graph_on_output` / `act_assemble_graph` → `GraphSpecAssembler`) but not for **usage**. The pieces all exist on the manager side:
+
+- `UsageAggregator.aggregate(events) → list[AnyTokensUsage]` (`pipelex/tracing/usage_aggregator.py`).
+- `ReportingManager.inject_tokens_usages(pipeline_run_id, tokens_usages)` (`reporting_manager.py:223`) — docstring: *"Used after assembling usage data from distributed trace events, so that generate_report() can produce a complete cost report across all workers."*
+- `ReportingManager.generate_report(pipeline_run_id)` (`reporting_manager.py:365`).
+
+`generate_report()` has a runtime caller — the CLI run path invokes it at `_run_core.py:224` — but that path reports only from the **local, in-process** usage registries; it never reads back the distributed trace events. `UsageAggregator.aggregate()` and `inject_tokens_usages()` still have zero runtime callers, so `UsageReportEvent`s emitted by runner/worker processes sit in the backend and never get assembled into the cost report. The missing piece is the cross-worker read-back, not `generate_report` itself.
+
+### The work
+
+Read events for `pipeline_run_id` → `UsageAggregator.aggregate()` → `ReportingManager.inject_tokens_usages()` → `generate_report()`, wired in both direct mode (`pipelex/pipeline/runner.py`) and Temporal mode (alongside or inside the existing graph-assembly hook) — the same place that calls the graph assembler can call the usage aggregator and inject the result before `generate_report` runs. Verify the cross-worker case: parent workflow on Worker A, child on Worker B, activity on Worker C → one end-of-run cost report carrying usage from all three. Once the read-back lands, revisit the local-only registry fallback (`_get_registry_strict` at `reporting_manager.py:115`, `_try_add_to_registry` at `:137`), whose local-only behaviour stands until the cross-worker path is wired.
+
+---
+
+## P2 — Local cross-package dependencies in the crate
+
+Detailed plan: [local-cross-package-deps.md](local-cross-package-deps.md).
+
+In one line: ship dependency blueprints inside the `LibraryCrate` so workers don't need the dependency packages on PIPELEXPATH. Prerequisite for P3.
+
+---
+
+## P3 — Remote dependencies from GitHub
+
+Detailed plan: [remote-deps-from-github.md](remote-deps-from-github.md).
+
+In one line: extend the blueprint collector from P2 with a remote (GitHub) resolver so the crate can carry deps fetched from external addresses, making workers fully stateless.
+
+---
+
+## Dependencies between items
+
+```
+P0 (Tracing across separate workers)
+ │
+ ├─► P0.1 (Dry-run through activity dispatch — testing affordance)
+ ├─► P0.2 (Deferred follow-ons — independent, pick up individually)
+ │
+ ▼
+P1 (Cross-worker cost report assembly)
+
+P2 (Local cross-package deps)
+ │
+ ▼
+P3 (Remote deps from GitHub)
+```
+
+P0/P0.1/P0.2/P1 and P2/P3 are independent tracks; P0 unlocks P0.1, P0.2, and P1; P2 blocks P3. P0.1 is a parallel testing affordance that raises confidence in P0 / P1 / future cross-process work.
diff --git a/wip/future-crate-first-architecture.md b/wip/distributed-execution/crate-first-architecture.md
similarity index 94%
rename from wip/future-crate-first-architecture.md
rename to wip/distributed-execution/crate-first-architecture.md
index 9e25f9c75..b5508e77a 100644
--- a/wip/future-crate-first-architecture.md
+++ b/wip/distributed-execution/crate-first-architecture.md
@@ -1,8 +1,6 @@
# Crate-First Architecture Vision
> **Status**: Vision / future direction
-> **Date**: 2026-03-25
-> **Related**: [archive/00-master-plan.md](archive/00-master-plan.md), [archive/phase2-implementation-plan.md](archive/phase2-implementation-plan.md)
---
@@ -240,3 +238,21 @@ Option 1 is cleanest (the crate is fully resolved, no runtime lookup needed) but
| Remote deps | Step 3 of this vision |
| Library fingerprint validation | Independent — compares base library fingerprints |
| Cross-worker cache | Complementary — caches the crate, benefits from stripping |
+
+---
+
+## Deferred / future capabilities
+
+Capabilities the crate-first direction enables but that are not planned for implementation now. Crate stripping and remote deps are detailed above (Future Capabilities 1 and 2); these round out the picture.
+
+### Library fingerprint validation
+
+**Status**: Future — no immediate need.
+
+Verify that the worker's base library (PIPELEXPATH) matches the API's expectation. Detect version drift between API and worker deployments.
+
+### Cross-worker cache via shared storage
+
+**Status**: Future — complementary to crate stripping.
+
+Cache loaded crates in shared storage (Redis, S3) so multiple workers don't redundantly load the same crate. Keyed by fingerprint. Smaller crates from stripping make this more effective.
diff --git a/wip/phase6a-local-cross-package-deps.md b/wip/distributed-execution/local-cross-package-deps.md
similarity index 51%
rename from wip/phase6a-local-cross-package-deps.md
rename to wip/distributed-execution/local-cross-package-deps.md
index 604dbc32a..b6df86738 100644
--- a/wip/phase6a-local-cross-package-deps.md
+++ b/wip/distributed-execution/local-cross-package-deps.md
@@ -1,15 +1,10 @@
-# Phase 6a — Local Cross-Package Dependencies in Crate
+# Local Cross-Package Dependencies in the Crate
-> **Status**: Not started
-> **Goal**: Dependency blueprints are included in the crate. Workers can execute pipelines with cross-package deps without having the dependency packages installed on PIPELEXPATH.
-> **Predecessor**: Phase 2 (crate propagation, shipped — see `archive/00-master-plan.md`).
-> **Related**: [02-master-plan.md](02-master-plan.md), [future-crate-first-architecture.md](future-crate-first-architecture.md).
-
----
+> Part of the [distributed-execution plan](README.md) (P2); a step toward [crate-first-architecture.md](crate-first-architecture.md).
## Why
-Today, cross-package dependencies (`alias->domain.ConceptCode`, `alias::domain.pipe_code`) resolve through child library lookups at loading time. The `LibraryCrate` shipped to Temporal workers does NOT include dependency content — only the main package's blueprints. This means workers must have all dependency packages pre-installed on PIPELEXPATH. Phase 6 removes this requirement: the crate becomes truly self-contained.
+Today, cross-package dependencies (`alias->domain.ConceptCode`, `alias::domain.pipe_code`) resolve through child library lookups at loading time. The `LibraryCrate` shipped to Temporal workers does NOT include dependency content — only the main package's blueprints. This means workers must have all dependency packages pre-installed on PIPELEXPATH. The goal is to remove this requirement: the crate becomes truly self-contained, so workers can execute cross-package pipelines without the dependency packages installed.
## Key changes
@@ -17,7 +12,7 @@ Today, cross-package dependencies (`alias->domain.ConceptCode`, `alias::domain.p
- **Collect**: resolve the dependency, parse its `.mthds` files into blueprints, determine exports.
- **Load**: create child Library, load domains/concepts/pipes, register aliases.
- The collector produces blueprints that accumulate into `_blueprints[library_id]` alongside the main package's blueprints.
+ The collector produces blueprints that accumulate into `_blueprints[library_id]` alongside the main package's blueprints, so `get_crate()` produces a crate that includes dependency content.
2. **Resolve cross-package aliases in the flattened crate**: Cross-package refs use alias-based syntax (`alias->domain.ConceptCode`). In a flattened crate, there are no child libraries. Options:
- Resolve aliases during crate building (replace `alias->domain.ConceptCode` with `domain.ConceptCode` in all blueprints).
@@ -27,13 +22,6 @@ Today, cross-package dependencies (`alias->domain.ConceptCode`, `alias::domain.p
3. **Update `load_from_crate()`**: Handle dependency content in the flat crate — register domains, concepts, and pipes from deps.
-## Done when
+## Acceptance
-- [ ] `_load_single_dependency` split into collect + load
-- [ ] Dependency blueprints accumulate into `_blueprints[library_id]`
-- [ ] `get_crate()` produces a crate that includes dependency content
-- [ ] Cross-package aliases resolved (either at crate build time or via alias map)
-- [ ] `load_from_crate()` handles dependency content correctly
-- [ ] Integration test: PipeSequence referencing a cross-package concept/pipe, executed on Temporal worker without the dependency package on PIPELEXPATH
-- [ ] `make agent-check` passes
-- [ ] `make agent-test` passes
+A PipeSequence referencing a cross-package concept/pipe executes on a Temporal worker that does **not** have the dependency package on PIPELEXPATH.
diff --git a/wip/distributed-execution/remote-deps-from-github.md b/wip/distributed-execution/remote-deps-from-github.md
new file mode 100644
index 000000000..b971d5b0f
--- /dev/null
+++ b/wip/distributed-execution/remote-deps-from-github.md
@@ -0,0 +1,19 @@
+# Remote Dependencies from GitHub
+
+> Part of the [distributed-execution plan](README.md) (P3); a step toward [crate-first-architecture.md](crate-first-architecture.md). Builds on the blueprint collector from [local-cross-package-deps.md](local-cross-package-deps.md).
+
+The goal: dependencies can be fetched from remote addresses (e.g. `github.com/org/repo/package`), so the crate becomes fully self-contained for cloud-native execution where workers are stateless.
+
+## Key changes
+
+1. **Remote resolution strategy**: Add a `REMOTE` resolution strategy to the blueprint collector. Remote fetch clones/downloads the package from GitHub, parses its `.mthds` files into blueprints, and includes them in the collection.
+
+2. **Dependency address format**: Define the address format for remote deps (e.g., `github.com/org/repo@version/path/to/package`). The address goes in the package manifest.
+
+3. **Caching**: Cache fetched packages locally (content-addressed by address + version) to avoid redundant clones.
+
+4. **Transitive deps**: Remote packages may themselves have dependencies (local or remote). The collector recurses.
+
+## Acceptance
+
+A pipeline with a remote GitHub dependency executes on a Temporal worker that does **not** have the dependency pre-installed.
diff --git a/wip/distributed-execution/schema-reconstruction-hardening.md b/wip/distributed-execution/schema-reconstruction-hardening.md
new file mode 100644
index 000000000..63fc7f3e8
--- /dev/null
+++ b/wip/distributed-execution/schema-reconstruction-hardening.md
@@ -0,0 +1,23 @@
+# Schema Reconstruction Hardening
+
+> **Status**: Deferred — no immediate threat-model trigger.
+
+Items related to `SchemaToModelFactory` (`pipelex/cogt/content_generation/schema_to_model_factory.py`), which reconstructs Pydantic BaseModel classes from JSON schemas across process boundaries (Temporal payloads). The current implementation `exec()`'s code generated by `datamodel-code-generator` and ships that source verbatim as `__kajson_class_source__` so receivers can re-exec it. See the module docstring for the full threat model.
+
+## `exec()` → `pydantic.create_model()` migration
+
+**Status**: Deferred — non-trivial refactor, no immediate threat-model trigger.
+
+Replace `exec()` in `_exec_source_to_types` with programmatic class construction via `pydantic.create_model()`. Eliminates the exec primitive on both the sender path (`make_from_json_schema`) and the receiver path (`make_types_from_source`), and lets us delete `_make_restricted_builtins`, `_restricted_import`, and `_reject_unsafe_schema_extensions`.
+
+Non-trivial because nested models, enums, and forward references currently rely on `datamodel-code-generator`'s output structure. A faithful port has to walk the JSON schema directly, build the class graph in dependency order, and apply `model_rebuild()` after the fact to resolve forward refs.
+
+This is the right structural fix; the receiver-side gap below is a stopgap until it lands.
+
+## Receiver-side schema validation gap
+
+**Status**: Known gap — documented in `make_types_from_source`'s docstring; only worth closing if the migration above is materially delayed.
+
+`make_from_json_schema` (sender) calls `_reject_unsafe_schema_extensions` before generating source — Layer 1. `make_types_from_source` (receiver) takes pre-generated source and execs it directly — only Layer 2 (`_make_restricted_builtins`) applies. An attacker who can inject a crafted `__kajson_class_source__` string into a Temporal payload bypasses Layer 1 entirely.
+
+Interim mitigation: AST-scan the source before exec, rejecting any top-level node that isn't an allowlisted import, a class def, or a docstring (and any class body that isn't fields / `model_config` / docstring). Mirrors Layer 1's "reject loudly" failure mode at the structural level. Trade-off: tied to `datamodel-code-generator`'s emitted output shape, which is not a stable API. Skip if the `create_model()` migration is near-term; the migration closes the gap permanently.
diff --git a/wip/temporal-primitives/03-temporal-error-handling-revamp.md b/wip/distributed-execution/temporal-exception-model-revamp.md
similarity index 93%
rename from wip/temporal-primitives/03-temporal-error-handling-revamp.md
rename to wip/distributed-execution/temporal-exception-model-revamp.md
index d03ca8cae..45182c152 100644
--- a/wip/temporal-primitives/03-temporal-error-handling-revamp.md
+++ b/wip/distributed-execution/temporal-exception-model-revamp.md
@@ -6,7 +6,7 @@ Pipelex exposes workflow execution failures as `pipelex.temporal.exceptions.Work
But Temporal's Python SDK has a strict rule: only exceptions that subclass `temporalio.exceptions.FailureError` are treated as **workflow execution failures** (terminal, propagated to client as `WorkflowFailureError`). Anything else is treated as a **workflow task failure** (programmer bug — workflow task is retried indefinitely, the workflow never completes).
-`WorkflowExecutionError` doesn't subclass `FailureError`. So any workflow that catches it and re-raises it (the pattern in `wf_pipe_run.py` after the Phase 5 follow-up) would hang forever — except we worked around it by registering `WorkflowExecutionError` in the Worker's `workflow_failure_exception_types` list (commit `117bbe01`).
+`WorkflowExecutionError` doesn't subclass `FailureError`. So any workflow that catches it and re-raises it (the pattern in `wf_pipe_run.py`) would hang forever — except we worked around it by registering `WorkflowExecutionError` in the Worker's `workflow_failure_exception_types` list.
## What this revamp would do
@@ -56,7 +56,7 @@ Likely **not** changed:
## Related work
-- Phase 5 follow-up commit `117bbe01` — "Pre-Phase-6 cleanup: tighten exception handling + WfPipeRun failure-path test" — added the `workflow_failure_exception_types` workaround.
+- The `workflow_failure_exception_types` registration is the current workaround this revamp would remove.
- `pipelex/temporal/tprl/workflow_caller.py` — the four `WorkflowExecutor` entry points and their named-exception catches.
- `pipelex/temporal/exceptions.py` — the current `TemporalFlowError` hierarchy.
- `tests/integration/pipelex/temporal/test_wf_pipe_run_failure_path.py` — the test that surfaced this issue.
diff --git a/wip/temporal-primitives/01-id-and-naming-design.md b/wip/distributed-execution/temporal-ids-and-naming.md
similarity index 97%
rename from wip/temporal-primitives/01-id-and-naming-design.md
rename to wip/distributed-execution/temporal-ids-and-naming.md
index 7eb7d1e54..eaa742575 100644
--- a/wip/temporal-primitives/01-id-and-naming-design.md
+++ b/wip/distributed-execution/temporal-ids-and-naming.md
@@ -2,10 +2,7 @@
## Status
-**Implemented.** Phases 1–6 shipped on `feature/Temporal-ids` (latest: commit `c89674f5`, Phase 6 hard-fail worker boot + configurable search attributes + setup CLI). See `02-id-and-naming-plan.md` for the per-phase execution log and checkpoint notes. This doc remains the authoritative reference for the architectural decisions.
-
-Reads cleanly with the primitives catalogued in `00-temporal-id-primitives.md`. The original problem statement (`workflow-and-activity-ids.md`) and the pre-checkpoint plan (`id-and-naming-plan.md`) are archived under `wip/archive/`.
-
+**Implemented.** This doc is the authoritative reference for the architectural decisions.
Decisions taken in this session, recorded so the next session does not reopen them:
- **Workflow ID.** Top-level Workflow ID is `{env_prefix}{pipeline_run_id}` — the existing UUID from `JobMetadata`, with the existing run-mode prefix (`ut-`, `ci-`, `cc-`, `cct-`, or empty). No session truncation, no random suffix, no class name.
diff --git a/wip/tracing-cost-reporting-as-built.md b/wip/distributed-execution/tracing-cost-reporting.md
similarity index 67%
rename from wip/tracing-cost-reporting-as-built.md
rename to wip/distributed-execution/tracing-cost-reporting.md
index caed9acb0..cfe24c13b 100644
--- a/wip/tracing-cost-reporting-as-built.md
+++ b/wip/distributed-execution/tracing-cost-reporting.md
@@ -1,10 +1,10 @@
# Tracing & Cost Reporting — As Built
-> **Status**: Shipped via `feature/dynamodb-tracer` (supersedes the original Phase 4.5 Step 6 design from `archive/00-master-plan.md`).
+> **Status**: Shipped — the current tracing & cost-reporting implementation (supersedes an earlier distributed-tracing design, now retired).
> **Last updated**: 2026-05-04
-> **Related**: [02-master-plan.md](02-master-plan.md), [distributed-tracing-and-reporting.md](distributed-tracing-and-reporting.md) (pre-implementation analysis — design choices superseded), [archive/phase4.5-distributed-tracing-implementation.md](archive/phase4.5-distributed-tracing-implementation.md).
+> **Related**: [the distributed-execution plan](README.md).
-This file documents what actually shipped, plus the known gaps that 02-master-plan addresses.
+This file documents what actually shipped, plus the known gaps that the plan addresses.
---
@@ -38,7 +38,7 @@ The original Step 6 plan called for a `TracingActivityInboundInterceptor` to set
**Severity (was)**: Blocked the whole point of distributed activity workers.
-**Status**: Resolved on `fix/Tracing-across-workers` (P0 in [02-master-plan.md](02-master-plan.md)). The full implementation history (six phases, eng-review notes, decisions, test inventory, atomic-commit list) is preserved in the branch's git log.
+**Status**: Resolved (P0 in [the distributed-execution plan](README.md)).
The fix has two independent parts that ship together:
@@ -47,7 +47,7 @@ The fix has two independent parts that ship together:
The `_get_registry` orphan-accumulation TODO at `reporting_manager.py` is gone: the method was split into `_get_registry_strict` (used by `_report_*_job` — runner processes silently skip the registry add) and `_get_or_create_registry` (used by `inject_tokens_usages`, the console cost-report path, and `generate_report`).
-The known retry-related over-counting case (R2) is documented and pinned by `test_retried_activity_emits_duplicate_usage_event_documenting_r2`. A `tracing_config.strict_mode` flag (raise instead of WARNING + drop) is deferred — see [02-master-plan.md §P0.2](02-master-plan.md).
+The known retry-related over-counting case (R2) is documented and pinned by `test_retried_activity_emits_duplicate_usage_event_documenting_r2`. A `tracing_config.strict_mode` flag (raise instead of WARNING + drop) is deferred — see [the plan, §P0.2](README.md).
### Issue T2 — Cross-worker cost report assembly is not wired
@@ -58,10 +58,10 @@ The known retry-related over-counting case (R2) is documented and pinned by `tes
The pieces all exist:
- `UsageAggregator.aggregate(events) → list[AnyTokensUsage]` (`pipelex/tracing/usage_aggregator.py`).
-- `ReportingManager.inject_tokens_usages(pipeline_run_id, tokens_usages)` whose docstring literally says: *"Used after assembling usage data from distributed trace events, so that generate_report() can produce a complete cost report across all workers."* (`reporting_manager.py:191`).
-- `ReportingManager.generate_report(pipeline_run_id)` (`reporting_manager.py:247`).
+- `ReportingManager.inject_tokens_usages(pipeline_run_id, tokens_usages)` whose docstring literally says: *"Used after assembling usage data from distributed trace events, so that generate_report() can produce a complete cost report across all workers."* (`reporting_manager.py:223`).
+- `ReportingManager.generate_report(pipeline_run_id)` (`reporting_manager.py:365`).
-But **nothing in the runtime calls them**. The graph assembly path (`graph_assembly.py`, `act_assemble_graph.py`) reads events back, but only feeds them into `GraphSpecAssembler` — never into `UsageAggregator`. `generate_report()` has zero runtime callers; only integration tests invoke it.
+But **the cross-worker assembly chain is not wired up**. The graph assembly path (`graph_assembly.py`, `act_assemble_graph.py`) reads events back, but only feeds them into `GraphSpecAssembler` — never into `UsageAggregator`. `generate_report()` does have a runtime caller (the CLI run path, `_run_core.py:224`), but it reports only the local, in-process usage registries; `UsageAggregator.aggregate()` and `inject_tokens_usages()` still have zero runtime callers, so the events emitted by runner/worker processes never get assembled into the cost report.
Net effect: even when usage events ARE captured (i.e., the same-worker case in the table above), the captured events sit in NDJSON / DynamoDB and never become a cross-worker cost report.
@@ -75,8 +75,44 @@ Net effect: even when usage events ARE captured (i.e., the same-worker case in t
---
-## How this connects to 02-master-plan
+## How this connects to the plan
-- T1 was the **top priority** in [02-master-plan.md](02-master-plan.md) — now resolved on `fix/Tracing-across-workers`.
+- T1 was the **top priority** in the [distributed-execution plan](README.md) — now resolved.
- T2 is the **next priority** — events now land in the same partition from every worker; the small remaining step is wiring `read events → UsageAggregator → inject_tokens_usages → generate_report`.
- T3 is the architectural shape; the T1 fix mitigates the immediate impact, the deeper refactor will land alongside T2 / further follow-ups.
+
+---
+
+## Deferred items
+
+Items related to the event log and graph tracing system that are explicitly out of scope for now.
+
+### Event log backends
+
+| Item | Status | Context |
+|---|---|---|
+| DynamoDB backend | **Shipped** | `pipelex/tracing/dynamodb_event_log.py` (+ `TEMPORAL_DYNAMODB` variant). Schema-compatible with `pipelex-api-infra`'s `TraceEventDynamoDBAdapter`. Selected via `[pipelex.tracing] backend = "dynamodb"`. |
+| SQLite backend | **Not planned** — NDJSON + DynamoDB cover the matrix | Not built. Re-evaluate only if a use case appears that NDJSON can't serve and DynamoDB is overkill. |
+
+### Event log protocol extensions
+
+| Item | Status | Context |
+|---|---|---|
+| `subscribe()` on EventLogProtocol | **Deferred** — no consumer exists yet | Polling-based reads are sufficient for now; add when a real-time consumer exists. |
+| Real-time progress consumer | **Deferred** — no consumer exists yet | The protocol supports it; build when needed. |
+| TraceSinkProtocol abstraction | **Deferred** — EventLogProtocol is sufficient | The higher-level sink abstraction can wait for the cloud backend. |
+| Large data externalization | **Deferred** — inline data is sufficient for now | Add StorageProvider offloading when traces grow too large. |
+
+### Tracing architecture
+
+| Item | Status | Context |
+|---|---|---|
+| Unified code path (event log everywhere) | **Effectively unified** | `pipeline_run_setup.py:282` wires `set_event_log()` on the report delegate for direct mode too (using `workflow_id="direct"`). The same `EventLogProtocol` machinery runs in both modes; only the in-process vs. Temporal lifecycle differs. |
+| Auto-cleanup of traces | **Deferred** — manual cleanup is safer for now | NDJSON traces persist on disk until manually deleted. Safer for debugging and allows usage reporting to run after graph generation. DynamoDB cleanup follows TTL on the table. |
+
+### Known issues
+
+| Item | Status | Context |
+|---|---|---|
+| Causal event ordering in assembler | **Known limitation** — works for current topologies | `read_events()` sorts by `(workflow_id, sequence)` which groups by lexicographic workflow ID, not execution order. In parent/child workflow topologies, this can cause `_stuff_producer_map` overwrites in the wrong order during `GraphSpecAssembler.pass_one()`, producing incorrect DATA edge sources. Consider sorting by timestamp or processing events in a topology-aware order. |
+| PipeCondition SELECTED_OUTCOME wiring | **Deferred** — no production use yet | PipeCondition has no tracer calls in production code currently. If SELECTED_OUTCOME edges are needed, that's a separate change. |
diff --git a/wip/distributed-tracing-and-reporting.md b/wip/distributed-tracing-and-reporting.md
deleted file mode 100644
index e77878279..000000000
--- a/wip/distributed-tracing-and-reporting.md
+++ /dev/null
@@ -1,697 +0,0 @@
-# Distributed Tracing & Reporting Architecture
-
-> **Status (2026-05-04): SUPERSEDED — kept as historical analysis.**
-> The implementation shipped via `feature/dynamodb-tracer` and chose **NDJSON** locally + **DynamoDB** in the cloud, **not** SQLite or Redis Streams as recommended below. Inside Temporal workflows, events are buffered in a `BufferingEventLog` and flushed to the real backend via the `act_flush_trace_events` activity — not via a workflow-side interceptor.
->
-> See:
-> - `pipelex/tracing/event_log_protocol.py`, `ndjson_event_log.py`, `dynamodb_event_log.py`, `buffering_event_log.py`, `event_log_factory.py`
-> - `pipelex/temporal/tprl_pipe/wf_pipe_router.py` (per-workflow `set_event_log` + flush)
-> - `pipelex/temporal/tprl_pipe/act_flush_trace_events.py` (off-thread persistence)
-> - [01-master-plan.md](01-master-plan.md) "Phase 4.5 Step 6 — as built"
->
-> Decisions from this doc that no longer apply: SQLite local backend (Decision 2), Redis Streams cloud backend, ContextVar for the event log client (the implementation keys per-workflow inside `ReportingManager`). The high-level event-log architecture (event types, assembler, fire-and-forget emit, durability-on-emit) all match what shipped.
->
-> **Original metadata:** Pre-planning analysis — decision gates marked with ❓
-> **Date**: 2026-03-29
-> **Related**: [archive/00-master-plan.md](archive/00-master-plan.md), [archive/phase2-crate-propagation-rationale.md](archive/phase2-crate-propagation-rationale.md)
-> **Scope**: GraphTracer (execution graph capture) + ReportingManager (AI usage/cost tracking) in Temporal distributed execution
-
----
-
-## Problem Statement
-
-Two in-memory systems silently break under Temporal distributed execution:
-
-| System | What it does | How it breaks |
-|--------|-------------|---------------|
-| **GraphTracerManager** | Accumulates pipe execution events (nodes, edges, timing, I/O) into a GraphSpec for visualization | Singleton on each process — workers trace nothing because no tracer is opened; all graph events are lost |
-| **ReportingManager** | Tracks AI token usage/costs per pipeline run | Workers auto-create orphaned registries that never sync back to the API process; usage data is lost |
-
-Both systems were designed for single-process execution. The master plan (Phases 0-4) focused on library propagation and class registry scoping, but overlooked these two cross-cutting concerns.
-
-### Requirements
-
-| Requirement | Priority | Rationale |
-|-------------|----------|-----------|
-| **Survive failures** | Must-have | Cost reporting for failing workflows is not optional — we pay for those tokens |
-| **Real-time progress** | Must-have | Track graph construction and cost accumulation while pipeline runs |
-| **Per-step granularity** | Must-have | Each pipe execution is a distinct trace event with its own cost attribution |
-| **Large graphs with data** | Must-have | Full I/O data capture (`--graph-full-data`) for debugging |
-| **Local dev first** | Priority | But only if architecturally aligned with cloud — shared principles, swappable backend |
-
----
-
-## Current Architecture Analysis
-
-### GraphTracer: What Happens Today on Temporal
-
-```
-API Process Worker Process A Worker Process B
------------ ---------------- ----------------
-runner.execute_pipeline()
- pipeline_run_setup()
- GraphTracerManager.open_tracer() (singleton is separate instance) (singleton is separate instance)
- → GraphContext on JobMetadata
- WfPipeRouter.run(pipe_job)
- pipe.run_pipe()
- graph_context is NOT None ✓
- GraphTracerManager.get_instance()
- → returns None ✗ (same: returns None)
- → tracing silently skipped → tracing silently skipped
- return PipeOutput (no graph_spec)
- tracer_manager.close_tracer()
- → GraphSpec with ZERO nodes
-```
-
-**Root cause**: `GraphTracerManager` is a process-local singleton (`ABCSingletonMeta`). The API process opens a tracer, but `run_pipe()` executes on a different process where the singleton was never initialized. The guard `if tracer_manager is not None` silently skips all tracing.
-
-**What's preserved**: `GraphContext` (graph_id, parent_node_id, node_sequence, data_inclusion) IS serialized on `JobMetadata` and correctly flows through PipeJob to workers. The context propagation infrastructure exists — only the tracer endpoint is missing.
-
-### ReportingManager: What Happens Today on Temporal
-
-```
-API Process Worker Process
------------ ----------------
-hub.set_report_delegate(reporting_mgr)
- reporting_mgr.open_registry(run_id)
- WfPipeRouter.run(pipe_job)
- pipe_operator.run_pipe()
- llm_worker.run()
- reporting_delegate.report_inference_job()
- → _get_registry(run_id) auto-creates orphan ✗
- → usage recorded in worker-local registry
- return PipeOutput
- reporting_mgr.generate_report(run_id)
- → report from API-side registry only
- → worker-side usage is LOST
-```
-
-**Root cause**: Workers get a `reporting_delegate` via `hub.get_report_delegate()`, which is a process-local reference. The `_get_registry()` method auto-creates registries for unknown pipeline IDs (there's already a TODO comment acknowledging this), but these registries live in the worker's memory and are never collected.
-
-### What's Already in Place
-
-| Infrastructure | Status | Relevance |
-|---------------|--------|-----------|
-| `GraphContext` serializable on `JobMetadata` | ✅ Working | Context flows to workers — can seed local tracers |
-| `PipeOutput.graph_spec: GraphSpec | None` | ✅ Exists | Return channel exists but insufficient (only on success) |
-| `GraphSpec` is a flat Pydantic model | ✅ Working | Easy to serialize, merge, transport |
-| `TokensUsage` types are Pydantic models | ✅ Working | Easy to serialize and aggregate |
-| `ObserverProtocol` + `LocalObserver` | ✅ Working | Existing event pattern — writes JSONL to shared dir |
-| `StorageProviderAbstract` (Local, S3, GCP) | ✅ Working | Pluggable storage with existing backends |
-| `LibraryCrate` propagation on PipeJob | ✅ Working | Pattern for adding data to PipeJob |
-| StoragePayloadCodec (Phase 5) | 🔲 Planned | Would solve payload size limits |
-
-### Why PipeOutput Piggyback Is Insufficient
-
-The initial instinct is to return graph fragments and usage records in PipeOutput, like LibraryCrate propagation. This fails on three counts:
-
-1. **Lost on failure**: If a workflow crashes, PipeOutput is never returned. Cost reporting for failing workflows is unacceptable to lose — those tokens were consumed and billed.
-2. **No real-time visibility**: Data is only available when the entire workflow tree completes. For long pipelines, this means no progress tracking.
-3. **Payload pressure**: Graph data with full I/O content can be large. Adding it to PipeOutput pushes toward Temporal's 2MB limit, making Phase 5 (StoragePayloadCodec) a hard prerequisite.
-
----
-
-## Recommended Architecture: Event Log
-
-The right abstraction is an **append-only event log**. Workers emit events as they happen. Events are durable the instant they're written. Consumers can read in real-time or after completion.
-
-This matches the existing `LocalObserver` pattern (JSONL files in a shared directory) and generalizes cleanly to cloud backends (Redis Streams, CloudWatch, S3).
-
-### Core Concept
-
-```
- ┌──────────────┐
-Worker A ──emit(PipeStartEvent)────►│ │
-Worker A ──emit(UsageEvent)────────►│ Event Log │◄────read()──── Real-time consumer
-Worker B ──emit(PipeStartEvent)────►│ (per run) │◄────read()──── Post-exec assembler
-Worker B ──emit(PipeEndError)──────►│ │
- └──────────────┘
-```
-
-**Key properties**:
-- **Fire-and-forget emit**: Workers write events and move on. No waiting for ack (local: file append; cloud: async publish).
-- **Durable on write**: Events survive worker crashes because they're persisted before the worker continues.
-- **Keyed by pipeline_run_id**: Each pipeline run has its own event stream.
-- **Ordered per writer**: Events from a single worker are naturally ordered (sequential writes). Cross-worker ordering uses graph structure (parent_node_id), not timestamps.
-- **Backend-agnostic**: The protocol is the same whether backed by SQLite, files, Redis, or S3.
-
-### Event Types
-
-```python
-class TraceEventKind(StrEnum):
- PIPE_START = "pipe_start"
- PIPE_END_SUCCESS = "pipe_end_success"
- PIPE_END_ERROR = "pipe_end_error"
- USAGE_REPORT = "usage_report"
-
-class TraceEvent(BaseModel):
- """Base event emitted by workers to the event log."""
- pipeline_run_id: str
- workflow_id: str # Temporal workflow ID or "direct" for in-process
- event_kind: TraceEventKind
- timestamp: datetime # UTC, for display only — not used for ordering
- sequence: int # Per-writer monotonic counter for ordering
-
-class PipeStartEvent(TraceEvent):
- event_kind: Literal[TraceEventKind.PIPE_START]
- node_id: str # Unique: {graph_id}:{workflow_short_id}:node_{seq}
- parent_node_id: str | None
- pipe_code: str
- pipe_type: str
- node_kind: NodeKind
- input_specs: list[IOSpec] | None = None
-
-class PipeEndSuccessEvent(TraceEvent):
- event_kind: Literal[TraceEventKind.PIPE_END_SUCCESS]
- node_id: str
- output_spec: IOSpec | None = None
- timing: TimingSpec | None = None
-
-class PipeEndErrorEvent(TraceEvent):
- event_kind: Literal[TraceEventKind.PIPE_END_ERROR]
- node_id: str
- error: ErrorSpec
- timing: TimingSpec | None = None
-
-class UsageReportEvent(TraceEvent):
- event_kind: Literal[TraceEventKind.USAGE_REPORT]
- node_id: str | None = None # Which pipe generated this cost
- tokens_usage: TokensUsage # LLMTokensUsage | ImgGenTokensUsage | etc.
-```
-
-### Event Log Protocol
-
-```python
-class EventLogProtocol(Protocol):
- """Append-only event log for pipeline execution tracing."""
-
- def emit(self, event: TraceEvent) -> None:
- """Write an event to the log. Must be durable before returning.
- Non-blocking for the caller in the common case (local I/O is fast,
- cloud backends buffer and flush).
- """
- ...
-
- def read_events(self, pipeline_run_id: str) -> list[TraceEvent]:
- """Read all events for a pipeline run. Used by assemblers."""
- ...
-
- def subscribe(self, pipeline_run_id: str) -> AsyncIterator[TraceEvent]:
- """Stream events in real-time. Used by dashboards/progress trackers.
- Falls back to polling where native push isn't available.
- """
- ...
-
- def cleanup(self, pipeline_run_id: str) -> None:
- """Remove events for a completed pipeline run (optional, for storage hygiene)."""
- ...
-```
-
-### Backend Implementations
-
-#### Local Dev: SQLite Event Log
-
-SQLite is the ideal local backend because:
-- Single file, zero setup, already available everywhere
-- WAL mode supports concurrent readers + single writer (our workers write sequentially per pipeline)
-- ACID guarantees — events are durable on commit
-- Supports polling-based subscribe (query `WHERE sequence > last_seen`)
-- Fast enough for local dev (microsecond writes)
-- Easy to inspect with any SQLite tool
-
-```sql
-CREATE TABLE trace_events (
- id INTEGER PRIMARY KEY AUTOINCREMENT,
- pipeline_run_id TEXT NOT NULL,
- workflow_id TEXT NOT NULL,
- event_kind TEXT NOT NULL,
- timestamp TEXT NOT NULL,
- sequence INTEGER NOT NULL,
- payload TEXT NOT NULL, -- JSON serialized TraceEvent
- UNIQUE(pipeline_run_id, workflow_id, sequence)
-);
-
-CREATE INDEX idx_pipeline_run ON trace_events(pipeline_run_id);
-CREATE INDEX idx_pipeline_run_id ON trace_events(pipeline_run_id, id);
-```
-
-**Concurrency model**: Multiple workers (separate processes) can write concurrently because SQLite WAL mode handles locking. Each worker gets its own connection. Writes are serialized at the SQLite level but with minimal contention (append-only, no conflicts).
-
-**Real-time polling**: A consumer reads `SELECT * FROM trace_events WHERE pipeline_run_id = ? AND id > ? ORDER BY id` periodically (e.g., every 500ms). Simple, reliable, no complex pub/sub.
-
-**File location**: `{pipelex_data_dir}/traces/{pipeline_run_id}.db` — one DB file per pipeline run, easy cleanup.
-
-Alternative: single DB file with all runs, cleanup via DELETE. Simpler file management but slightly more contention.
-
-#### Cloud: Redis Streams
-
-Redis Streams is the natural cloud equivalent:
-- `XADD pipelex:trace:{pipeline_run_id} * event_kind pipe_start payload {...}`
-- `XREAD` for real-time streaming
-- `XRANGE` for batch reads
-- TTL for automatic cleanup
-- Already used in many Temporal deployments
-
-#### Cloud: S3/GCS (cold path)
-
-For archival and large data (full I/O content):
-- Workers write event batches to `s3://traces/{pipeline_run_id}/{workflow_id}/{sequence}.json`
-- No real-time streaming, but durable and cheap
-- Can be combined with Redis (hot events to Redis, data payloads to S3)
-
-### Comparison: SQLite vs JSONL Files vs Redis
-
-| Criterion | SQLite | JSONL files | Redis Streams |
-|-----------|:------:|:-----------:|:-------------:|
-| Concurrent writes | ✅ WAL mode | ⚠️ File locking needed | ✅ Native |
-| Real-time reads | ✅ Poll query | ⚠️ Tail + parse | ✅ XREAD blocking |
-| Atomic writes | ✅ Transaction | ❌ Partial writes possible | ✅ XADD atomic |
-| Query by run_id | ✅ Index | ❌ Scan all files | ✅ Stream key |
-| Inspect/debug | ✅ sqlite3 CLI | ✅ cat/jq | ⚠️ redis-cli |
-| Setup | ✅ Zero (stdlib) | ✅ Zero | ❌ External service |
-| Cloud-ready | ❌ Local only | ❌ Local only | ✅ Managed Redis |
-| Survives worker crash | ✅ On commit | ✅ On flush | ✅ On ACK |
-
-**Recommendation**: SQLite for local dev, Redis Streams for cloud. Both implement the same `EventLogProtocol`. JSONL files (like LocalObserver) are tempting but lack atomic concurrent writes — a real risk with parallel pipe execution.
-
----
-
-## Integration Points
-
-### Where Events Are Emitted
-
-The event log replaces (or wraps) the existing tracer calls. The emission points already exist in the code:
-
-| Current call site | File | Becomes |
-|-------------------|------|---------|
-| `tracer_manager.on_pipe_start(...)` | `pipe_abstract.py:416` | `event_log.emit(PipeStartEvent(...))` |
-| `tracer_manager.on_pipe_end_success(...)` | `pipe_abstract.py:487` | `event_log.emit(PipeEndSuccessEvent(...))` |
-| `tracer_manager.on_pipe_end_error(...)` | `pipe_abstract.py:460` | `event_log.emit(PipeEndErrorEvent(...))` |
-| `reporting_delegate.report_inference_job(...)` | `llm_worker_abstract.py:334` | `event_log.emit(UsageReportEvent(...))` |
-
-### How Workers Access the Event Log
-
-Two options:
-
-**(a) Via GraphContext on JobMetadata**: Add an `event_log_uri` field to GraphContext. Workers create a client from the URI. This is explicit and serializable.
-
-```python
-class GraphContext(BaseModel):
- graph_id: str
- parent_node_id: str | None
- node_sequence: int
- data_inclusion: DataInclusionConfig
- event_log_uri: str | None = None # "sqlite:///tmp/traces/run123.db" or "redis://..."
-```
-
-**(b) Via hub configuration**: Workers read the event log backend from `pipelex.toml` config. The pipeline_run_id is on JobMetadata. This is simpler but less explicit.
-
-**Recommendation**: (b) for simplicity — the backend is infrastructure config, not per-run config. The `pipeline_run_id` (already on JobMetadata) is the key.
-
-### How the Assembler Works
-
-After pipeline execution (or on-demand for real-time), the assembler reads all events and reconstructs:
-
-```python
-class GraphSpecAssembler:
- """Reconstructs a GraphSpec from trace events."""
-
- @staticmethod
- def assemble(events: list[TraceEvent]) -> GraphSpec:
- nodes: dict[str, NodeSpec] = {}
- edges: list[EdgeSpec] = []
- stuff_producer_map: dict[str, str] = {} # digest → node_id
-
- for event in events:
- match event.event_kind:
- case TraceEventKind.PIPE_START:
- # Create node, record inputs, create CONTAINS edge if parent
- ...
- case TraceEventKind.PIPE_END_SUCCESS:
- # Update node status, record output, register in producer map
- ...
- case TraceEventKind.PIPE_END_ERROR:
- # Update node status, record error
- ...
- case TraceEventKind.USAGE_REPORT:
- # Accumulate in usage registry (separate from graph)
- ...
-
- # Generate DATA edges from producer/consumer digest correlation
- _generate_data_edges(nodes, stuff_producer_map, edges)
-
- return GraphSpec(
- graph_id=events[0].pipeline_run_id,
- created_at=min(e.timestamp for e in events),
- nodes=list(nodes.values()),
- edges=edges,
- )
-```
-
-**Key insight**: The assembler runs the same edge correlation logic that `GraphTracer.teardown()` currently runs. The difference is that it works on events from multiple workers, not in-memory state from one process. The algorithm is identical — correlate input digests with the producer map.
-
-### What Changes in Direct Mode?
-
-Nothing, if we do it right. Two strategies:
-
-**(a) Dual-write**: In direct mode, the existing in-memory GraphTracerManager continues to work as-is. The event log is only used in Temporal mode. Simple but maintains two code paths.
-
-**(b) Event log everywhere**: Replace the in-memory tracer with the event log even in direct mode. Use an in-memory event log backend (list of events). Assembler runs at the end. One code path for both modes.
-
-**Recommendation**: **(b)** — one code path is always better. The in-memory backend has zero overhead compared to the current approach. This also means every integration test exercises the event log + assembler path.
-
-### Controller-Specific Edges
-
-PipeParallel, PipeBatch, and PipeCondition register special edges (PARALLEL_COMBINE, BATCH_ITEM, BATCH_AGGREGATE, SELECTED_OUTCOME). These require dedicated event types:
-
-```python
-class BatchItemEvent(TraceEvent):
- """Emitted when PipeBatch extracts an item from a list."""
- event_kind: Literal["batch_item"]
- source_node_id: str # The node that produced the list
- target_node_id: str # The batch iteration node
- source_stuff_digest: str
- target_stuff_digest: str
-
-class ParallelCombineEvent(TraceEvent):
- """Emitted when PipeParallel combines branch outputs."""
- event_kind: Literal["parallel_combine"]
- branch_stuff_digests: list[str]
- combined_stuff_digest: str
- controller_node_id: str
-
-class SelectedOutcomeEvent(TraceEvent):
- """Emitted when PipeCondition selects an outcome."""
- event_kind: Literal["selected_outcome"]
- source_node_id: str
- target_node_id: str
-```
-
-These are currently emitted via direct calls to `GraphTracerManager` methods like `register_parallel_combine()`, `register_batch_item_extraction()`, etc. They become event emissions.
-
-### Node ID Scheme
-
-Current: `{graph_id}:node_{sequence}` — collides across workers.
-
-**New scheme**: `{graph_id}:{workflow_short_id}:node_{sequence}`
-
-Where `workflow_short_id` is a short hash of the Temporal workflow ID (or `"direct"` for in-process). This guarantees uniqueness while remaining human-readable.
-
-The `node_sequence` counter lives on the `GraphContext` that flows through execution. When a pipe starts, it gets the next sequence number from its context. Since contexts are copied for children (not shared), there's no cross-worker contention.
-
-**Important**: In the current code, `node_sequence` is on the `GraphTracer` (in-memory), not on `GraphContext`. For the event log approach, we move the sequence counter to `GraphContext` so it flows with the execution. This is a behavioral change but aligns with the serializable context philosophy.
-
----
-
-## Data Flow: Complete Picture
-
-```
-API Process (Submitter) Worker Process (any of N)
------------------------ -------------------------
-1. pipeline_run_setup()
- - Create event log (SQLite file or Redis stream)
- - Create GraphContext with event_log config
- - Attach GraphContext to JobMetadata
-
-2. Submit PipeJob to Temporal
- ──────────────────────────────────────►
- 3. WfPipeRouter.run(pipe_job)
- pipe.run_pipe()
- ├── EMIT PipeStartEvent ──────► Event Log
- ├── (execute pipe logic)
- │ ├── llm_worker reports:
- │ │ EMIT UsageReportEvent ► Event Log
- │ ├── child workflow dispatched:
- │ │ (child worker does same)
- │ └── ...
- ├── EMIT PipeEndSuccessEvent ─► Event Log
- │ (or PipeEndErrorEvent)
- └── return PipeOutput
-
- ◄──────────────────────────────────────
-4. Receive PipeOutput (contains working_memory only — no graph/usage)
-
-5. Assemble: read all events from event log
- → GraphSpecAssembler.assemble() → GraphSpec
- → UsageAggregator.aggregate() → CostReport
- → Generate graph outputs (Mermaid, ReactFlow)
-
-6. Cleanup event log (optional)
-```
-
-**On failure**: Steps 3 may fail partway. But every event emitted before the failure is already in the event log. The assembler in step 5 sees partial data (some PIPE_START without matching PIPE_END) and marks those nodes as RUNNING or CANCELED. Usage events for completed inference jobs are captured regardless.
-
-**Real-time**: A separate consumer can poll the event log during step 3, showing live progress. For local dev, this could be a CLI progress bar or a simple web dashboard reading the SQLite file.
-
----
-
-## Two Distinct Problems, Unified Solution
-
-Graph tracing and reporting have different characteristics but share the same event log:
-
-| Dimension | Graph Tracing | Usage Reporting |
-|-----------|--------------|-----------------|
-| Events | PipeStart, PipeEnd*, controller edges | UsageReport |
-| Assembly | Complex — tree reconstruction, edge correlation | Simple — list concatenation, sum |
-| Data volume | Potentially large (full I/O data) | Small (few KB per job) |
-| Failure handling | Partial graph with RUNNING/CANCELED nodes | All completed jobs captured |
-| Real-time use | Progress tree visualization | Running cost counter |
-| Consumer | GraphSpecAssembler → renderers | UsageAggregator → CostReport |
-
-Both read from the same event log. The assembler and aggregator are separate consumers — they can run independently, at different times, or concurrently.
-
----
-
-## Large Data Strategy
-
-With `--graph-full-data`, IOSpec includes full serialized content (JSON, text, HTML). A single PipeEndSuccessEvent could be megabytes.
-
-### ❓ Decision 1: How to handle large IOSpec data in events?
-
-**(a) Inline in events**: Full data embedded in the event payload. Simple but makes events large.
-- SQLite handles large BLOBs fine (tested to GB scale)
-- Redis has a 512MB value limit (more than enough)
-- Makes the event log self-contained — no external references
-
-**(b) Reference + external storage**: Events contain previews and digests only. Full data written to StorageProvider (existing system) keyed by digest. Assembler fetches when needed.
-- Keeps events small and fast
-- Leverages existing StorageProvider (Local, S3, GCP)
-- Adds complexity: two storage systems to coordinate
-
-**(c) Tiered**: Events contain data up to a size threshold (e.g., 100KB). Larger data goes to external storage with a reference in the event.
-- Best of both worlds
-- More complex to implement
-
-**Recommendation**: Start with **(a)** — inline. SQLite handles it well for local dev. For cloud, (b) becomes important, but that's a later optimization. The event schema supports both — `IOSpec.data` can be `None` with a `digest` that references external storage.
-
----
-
-## Decision Gates
-
-### ❓ Decision 2: Event Log Backend for Local Dev
-
-**(a) SQLite** — Structured, concurrent-safe, queryable, inspectable. Slightly more setup (schema migration).
-
-**(b) JSONL files** — Follows existing LocalObserver pattern. Simpler but lacks atomic concurrent writes and efficient querying.
-
-**(c) In-memory only** — No persistence. Lost on process crash. Not useful for real-time cross-process reads.
-
-**Recommendation**: (a) SQLite. The concurrency guarantees matter for parallel pipe execution. The inspectability (sqlite3 CLI) is valuable for debugging.
-
-### ❓ Decision 3: Direct Mode Integration
-
-**(a) Keep existing in-memory tracer** for direct mode, event log only for Temporal. Two code paths.
-
-**(b) Event log everywhere** — in-memory backend for direct mode, SQLite for Temporal. One code path.
-
-**Recommendation**: (b) — one code path. Use an in-memory list as the "event log" in direct mode. Same assembler, same event types, zero overhead. Every test exercises the full path.
-
-### ❓ Decision 4: Node ID Scheme
-
-Current: `{graph_id}:node_{sequence}` (conflicts across workers).
-
-**(a)** `{graph_id}:{workflow_short_id}:node_{seq}` — deterministic, debuggable, workflow-scoped prefix
-**(b)** UUID-based — simple, no coordination needed
-**(c)** Keep sequential with moved counter on GraphContext
-
-**Recommendation**: (a). The workflow ID provides natural namespacing. Short hash (8 chars) keeps IDs readable.
-
-### ❓ Decision 5: Sequence Counter Location
-
-Currently `node_sequence` lives on GraphTracer (in-memory). For event log, it must travel with execution.
-
-**(a) Move to GraphContext** — already serializable, flows through PipeJob. Each child context gets a copy.
-
-**(b) Worker-local counter** — each worker starts at 0. Combined with workflow_id prefix, globally unique.
-
-**Recommendation**: (b) — simpler. The workflow_id prefix already guarantees uniqueness. No need to coordinate sequence numbers across workers.
-
-### ❓ Decision 6: How Do Workers Access the Event Log?
-
-**(a) Via hub config** — workers read the backend config from `pipelex.toml`. The `pipeline_run_id` from JobMetadata is the key. Workers create a client on first use.
-
-**(b) Via GraphContext field** — add `event_log_uri: str | None` to GraphContext. More explicit but adds a field to a serialized model.
-
-**(c) Via PipeJob field** — add `event_log_config` to PipeJob, like `library_crate`.
-
-**Recommendation**: (a) — config-driven, like storage providers. The event log backend is infrastructure, not per-run data. Workers need the `pipeline_run_id` (already available) and the backend config (from pipelex.toml).
-
----
-
-## Pitfalls & Warnings
-
-### From a Senior Python Engineer
-
-1. **Don't force async on emit()**: The emit call happens inside `pipe_abstract.run_pipe()`, which is already async. But making emit truly async (with await) means it becomes a Temporal replay point in workflows. For Temporal determinism, side effects must happen inside activities. **Solution**: Make emit synchronous (SQLite writes are microseconds). For cloud backends that require network I/O, buffer events in-memory and flush via a Temporal activity or background thread.
-
-2. **Temporal replay and side effects**: If `run_pipe()` replays on a worker restart, events will be re-emitted. The event log must handle duplicates gracefully. **Solution**: Use `(pipeline_run_id, workflow_id, sequence)` as a unique key. SQLite `INSERT OR IGNORE` / Redis conditional adds handle deduplication naturally.
-
-3. **GraphTracer refactoring scope**: The current GraphTracer does two things: (1) accumulate events, (2) generate edges during teardown. With the event log, accumulation moves to the log. Edge generation moves to the assembler. The GraphTracer becomes a thin emit wrapper — or disappears entirely, replaced by direct event emission in `pipe_abstract.py`. Consider whether to keep the GraphTracer as a facade or remove it.
-
-4. **ContextVar for event log client**: Similar to `_library_id`, the event log client reference should be ContextVar-scoped so each workflow/context gets the right client. For direct mode, set at `pipeline_run_setup()`. For Temporal, set at the top of `WfPipeRouter.run()`.
-
-5. **Testing strategy**: The in-memory backend (Decision 3b) makes unit testing trivial — emit events, call assembler, assert on GraphSpec. Integration tests with SQLite validate concurrency. The cloud backend is tested separately.
-
-### From a Senior Systems Engineer
-
-1. **SQLite WAL + multiple processes**: SQLite WAL mode supports one writer at a time. With many workers writing concurrently, there will be brief lock contention. For local dev with a handful of workers, this is negligible. For production with dozens of workers, SQLite won't scale — that's when Redis takes over. This is fine for the layered approach.
-
-2. **File locking on NFS/shared filesystems**: If workers run on different machines sharing an NFS mount, SQLite will NOT work correctly — NFS doesn't support the locking primitives SQLite needs. This is a known limitation. For cloud, don't use SQLite — use Redis or S3.
-
-3. **Event log cleanup**: Without cleanup, SQLite files accumulate. Add a configurable retention policy (e.g., delete after 24h or after report generation). For cloud backends, use TTL.
-
-4. **Temporal's own event history**: Temporal already stores a complete event history for every workflow. In theory, you could extract tracing data from Temporal's event history (workflow started, activity completed, child workflow results, etc.). In practice, this gives you workflow-level granularity, not pipe-level granularity, and requires querying Temporal's API. It's not a substitute for the event log, but it's useful for correlation and debugging.
-
-5. **Clock skew**: Events from different workers may have slightly different timestamps. Use the event log's insertion order (autoincrement ID in SQLite, stream ID in Redis) for ordering, not timestamps. Timestamps are for display only.
-
-6. **Backpressure**: If a pipeline generates thousands of events (e.g., batch of 1000 items), the event log must handle the throughput. SQLite WAL mode can handle ~10K writes/sec. Redis Streams can handle ~100K ops/sec. Both are well above expected throughput.
-
----
-
-## Implementation Plan
-
-### Step 1: Event Types & Protocol
-
-Define the event models and `EventLogProtocol`. Pure model work, no integration yet.
-
-**Key files**:
-| File | Change |
-|------|--------|
-| `pipelex/tracing/trace_events.py` | **New** — TraceEvent models |
-| `pipelex/tracing/event_log_protocol.py` | **New** — EventLogProtocol |
-| `pipelex/tracing/in_memory_event_log.py` | **New** — In-memory implementation |
-
-**Done when**:
-- Event models serialize/deserialize correctly (unit tests)
-- In-memory event log passes basic emit/read/subscribe tests
-
-### Step 2: GraphSpec Assembler
-
-Build the assembler that reconstructs GraphSpec from events. This is the core algorithm.
-
-**Key files**:
-| File | Change |
-|------|--------|
-| `pipelex/tracing/graphspec_assembler.py` | **New** — Event → GraphSpec reconstruction |
-| `pipelex/tracing/usage_aggregator.py` | **New** — Event → usage report aggregation |
-
-**Done when**:
-- Assembler produces correct GraphSpec from hand-crafted events (unit tests)
-- Assembler handles partial events (missing PIPE_END → node marked RUNNING)
-- Usage aggregator sums correctly across workers
-- Edge correlation (DATA edges from digest matching) works across workers
-
-### Step 3: SQLite Event Log
-
-Implement the SQLite backend for local dev.
-
-**Key files**:
-| File | Change |
-|------|--------|
-| `pipelex/tracing/sqlite_event_log.py` | **New** — SQLite implementation |
-| `pipelex/tracing/tracing_config.py` | **New** — Config model for tracing backend |
-| `pipelex/pipelex.toml` | Add `[pipelex.tracing]` config section |
-
-**Done when**:
-- Concurrent writes from multiple threads/processes work (integration test)
-- Real-time polling reads see events from other writers
-- Deduplication handles replayed events
-
-### Step 4: Wire into Pipe Execution
-
-Replace GraphTracerManager calls in `pipe_abstract.py` with event log emissions. Replace ReportingManager calls in inference workers.
-
-**Key files**:
-| File | Change |
-|------|--------|
-| `pipelex/core/pipes/pipe_abstract.py` | Replace tracer calls with event emission |
-| `pipelex/cogt/inference/inference_worker_abstract.py` | Emit UsageReportEvent |
-| `pipelex/pipe_controllers/parallel/pipe_parallel.py` | Emit ParallelCombineEvent |
-| `pipelex/pipe_controllers/batch/pipe_batch.py` | Emit BatchItemEvent, BatchAggregateEvent |
-| `pipelex/pipe_controllers/condition/pipe_condition.py` | Emit SelectedOutcomeEvent |
-| `pipelex/pipeline/runner.py` | Open event log, run assembler after execution |
-| `pipelex/pipeline/pipeline_run_setup.py` | Initialize event log, set on ContextVar |
-| `pipelex/temporal/tprl_pipe/wf_pipe_router.py` | Initialize event log client from config |
-
-**Done when**:
-- Direct mode: `pipelex run pipe --graph` produces identical GraphSpec as before
-- Temporal mode: `pipelex run pipe --graph` produces correct GraphSpec across workers
-- Usage reporting works in both modes
-- All existing graph-related tests pass
-
-### Step 5: Real-Time Consumer
-
-Build a consumer that polls the event log and shows live progress.
-
-**Key files**:
-| File | Change |
-|------|--------|
-| `pipelex/tracing/live_progress.py` | **New** — Real-time progress from event log |
-
-**Done when**:
-- CLI shows live pipe execution progress during Temporal runs
-- Cost accumulation displayed in real-time
-
-### Future: Cloud Backends
-
-| Backend | When | Why |
-|---------|------|-----|
-| Redis Streams | When deploying to cloud with remote workers | Concurrent writes, real-time streaming, TTL |
-| S3/GCS | When archiving traces for compliance or analytics | Cheap, durable, queryable (Athena/BigQuery) |
-
-These are new implementations of `EventLogProtocol`. No changes to emission or assembly code.
-
----
-
-## Relationship to Master Plan
-
-This is a **parallel track**, not a new phase:
-
-```
-Master Plan This Track
------------ ----------
-Phase 4 (ClassRegistry) ← Complete
- Step 1: Event Types & Protocol
- Step 2: GraphSpec Assembler
-Phase 5 (StoragePayloadCodec) Step 3: SQLite Event Log
- Step 4: Wire into Pipe Execution
- Step 5: Real-Time Consumer
-```
-
-**No dependency on Phase 5**: Unlike the PipeOutput piggyback approach, the event log doesn't add to Temporal payloads. Large IOSpec data goes to the event log (SQLite/Redis), not through Temporal's wire.
-
-**No dependency on other phases**: The event log is orthogonal to library crate propagation, deferred hydration, and ClassRegistry scoping.
-
----
-
-## Open Questions
-
-1. **GraphTracer's fate**: The event log approach may make `GraphTracerManager` and `GraphTracer` obsolete. Should we keep them as a compatibility layer (wrapping event emission), or remove them and emit directly from `pipe_abstract.py`? Keeping them as a facade reduces the diff but adds indirection.
-
-2. **Controller-specific edge events**: PipeParallel's `register_parallel_combine()` currently mutates the tracer's internal `_stuff_producer_map` to override which node is the "producer" of a data item. With the event log, this becomes a `ParallelCombineEvent` that the assembler interprets. Need to verify this works for all controller types.
-
-3. **Content generator activities**: `ContentGeneratorChild` wraps LLM/extract/imggen activities. These run as Temporal activities, not workflows. Do activities have access to the event log? If the hub config is available on the worker process (it should be — workers load pipelex config at startup), then activities can emit events directly. Need to verify.
-
-4. **IOSpec data lifecycle**: If we inline large data in events (Decision 1a), the SQLite file for a single run could be very large. Should we add a configurable size threshold where data is stripped from events and written to the existing StorageProvider? This is Decision 1c but deferred.
-
-5. **Backwards compatibility**: Existing graph output consumers (Mermaid renderer, ReactFlow generator) expect a GraphSpec. The assembler produces a GraphSpec. No change needed for consumers. But the `GraphSpec.to_json()` output should be identical for regression testing — verify field ordering, alias handling, etc.
diff --git a/wip/error-handling/README.md b/wip/error-handling/README.md
index 23f3dc18a..93596a882 100644
--- a/wip/error-handling/README.md
+++ b/wip/error-handling/README.md
@@ -2,7 +2,7 @@
This directory is the current-state reference for error handling across Pipelex. It is intentionally **track-organized**, not phase-organized: each track is a self-contained concern with its own current state, gaps, and followups. Tracks are independent — there is no implied order between them.
-Each `track-*.md` describes **what the code does today**. Completed implementation plans are archived (see [Archived plans](#archived-plans) below) and kept only for their running notes. What is still open is summarized in [What's still open](#whats-still-open).
+Each `track-*.md` describes **what the code does today**. What is still open is summarized in [What's still open](#whats-still-open).
## Status at a glance
@@ -10,12 +10,12 @@ Each `track-*.md` describes **what the code does today**. Completed implementati
|---|---|---|
| Error metadata model | Landed for all inference workers — inference errors self-describe via `to_error_report()`, and every LLM, img-gen, extract, and search worker raise carries structured `ProviderErrorMetadata` (status_code, request_id, retry_after_seconds, provider_error_code, body) plus `UserAction(kind, detail)` with semantic `UserActionKind` values. `InferenceErrorCategory.UNKNOWN` distinguishes unrecognized fallback paths from genuine `CONTENT`. Each worker family fills `model` / `provider` onto the error at its public-method chokepoint via `CogtError.fill_model_and_provider()`, so a production inference failure's `ErrorReport` is attributable to a model and a backend. A long tail of non-inference `PipelexError` subclasses still depend on string-keyed dicts in `agent_output.py` — see [track-metadata-model.md](track-metadata-model.md) Followups. | [track-metadata-model.md](track-metadata-model.md) |
| Worker classification | Landed for all inference workers — every LLM, img-gen, extract, and search worker (plus AWS Bedrock LLM) maps SDK exceptions to a `CogtError` subclass with `error_category`, unwraps `InstructorRetryException` correctly on structured-gen paths, and carries the structured metadata + semantic user-action upgrades. Response-shape validation failures (non-SDK paths) carry `provider_metadata=None` plus a semantic `UserAction` for uniformity. | [track-worker-classification.md](track-worker-classification.md) |
-| Extract / Classify / Render | Landed (branch `refactor/ECR`) — every inference worker's `except` block now collapses to `extract → classify → raise render(...) from exc`. **Classify** (`pipelex/cogt/inference/error_classify.py`) and **Render** (`error_render.py`) are single shared functions; only the 12 `extract_*_metadata` functions stay per-provider. A new `tests/unit/pipelex/cogt/inference/test_provider_classification_parity.py` walks every `ProviderName` against the extract-fn registry to catch unwired providers. | [track-extract-classify-render.md](track-extract-classify-render.md) |
+| Extract / Classify / Render | Landed — every inference worker's `except` block now collapses to `extract → classify → raise render(...) from exc`. **Classify** (`pipelex/cogt/inference/error_classify.py`) and **Render** (`error_render.py`) are single shared functions; only the `extract_*_metadata` functions stay per-provider. A new `tests/unit/pipelex/cogt/inference/test_provider_classification_parity.py` walks every `ProviderName` against the extract-fn registry to catch unwired providers. | [track-extract-classify-render.md](track-extract-classify-render.md) |
| Retry & resilience | Landed — direct (non-Temporal) execution is a single pipeline-level attempt with no application-level retry loop; resilience is the Temporal track's job (activity `RetryPolicy` keyed off `InferenceErrorCategory`). `PipeBatch` bounds fan-out via `gather_bounded` (chunked, `max_concurrency`, default 8) — admission control, not retry. Tier 1 (transport retry) is an explicit, uniform policy: `cogt.transport_max_retries` is wired into every inference SDK client factory, the SDK-less `azure_rest` image-gen path has a `tenacity` transport-retry floor, and `instructor`'s structured-output retry is confined to schema re-ask. | [track-retry-and-resilience.md](track-retry-and-resilience.md) |
| CLI delivery | Landed — agent CLI emits markdown by default for `run`/`validate`/`init` (and `models`/`check-model`/`doctor`), `--format json` for the structured payload; the error path follows the same option via a per-invocation `ContextVar`. `ErrorReport` carries an authoritative `error_domain` → HTTP-status mapping. `display_error_panel` collapses the field-shaped Rich handlers onto one helper. | [track-cli-delivery.md](track-cli-delivery.md) |
| Temporal integration | Landed — `TemporalError.from_message_exception()` derives retryability from `InferenceErrorCategory.is_retryable` for category-carrying `CogtError`s (the `non_retryable_error_types` list is the fallback) and packs the full `ErrorReport` into `ApplicationError.details`. Every in-scope activity is decorated with `@convert_pipelex_errors`, so the bridge runs in production. The symmetric workflow → submitter and child-workflow → parent recovery is landed: `recover_error_report` reads the report back out of `ApplicationError.details`, so a pipe failing on a Temporal worker reaches the CLI and HTTP adapters with the same classification as a local run. | [track-temporal-integration.md](track-temporal-integration.md) |
| Testing | Landed — worker-level classification tests, the `agent_output.py` dict-drift test, and the full-chain worker→runner→CLI integration test (JSON + markdown) plus Rich-panel snapshot tests are all in place. | [track-testing.md](track-testing.md) |
-| API readiness (error-handling companion) | Stages 1-4 landed (PR #931) — `PipelexError.title()` / `type_uri()`, `request_id` on `JobMetadata`, `DisclosureMode` with `to_dict(disclosure_mode=)` / `to_problem_document()`, total `recover_error_report`, `ErrorReport` as a `BaseModel` threaded to the webhook, and per-class error doc pages. Stage 5 (webhook signing) is the last open item; the post-#931 `/review` follow-ups landed 2026-05-22 as TODOS Phases 1-4 — see [What's still open](#whats-still-open). | [api-companion-revisions.md](api-companion-revisions.md) |
+| API readiness (error-handling companion) | Landed — `PipelexError.title()` / `type_uri()`, `request_id` on `JobMetadata`, `DisclosureMode` with `to_dict(disclosure_mode=)` / `to_problem_document()`, total `recover_error_report`, `ErrorReport` as a `BaseModel` threaded to the webhook, and per-class error doc pages. Webhook signing is the last open item — see [What's still open](#whats-still-open). | [api-readiness.md](api-readiness.md) |
Architectural reference (layer model, class hierarchy, two reporting systems) lives in [architecture.md](architecture.md).
@@ -23,10 +23,9 @@ Architectural reference (layer model, class hierarchy, two reporting systems) li
The bulk of the error-handling work has landed. What remains:
-1. **Webhook signing (Stage 5 / Item F)** — the last unshipped stage of the API-readiness companion plan. Cross-repo: the pipelex side and the API side land in lockstep. Authoritative plan: [../security/webhook-signing.md](../security/webhook-signing.md).
+1. **Webhook signing** — the last unshipped piece of the API-readiness companion work. Cross-repo: the pipelex side and the API side land in lockstep. Authoritative plan: [../webhook-signing.md](../webhook-signing.md).
2. **Metadata-model long tail** — a handful of `CogtError` subclasses still carry no class-level `error_category`, and several non-inference `PipelexError` subclasses still depend on the `agent_output.py` fallback dicts for `hint` / `error_domain` rather than carrying class-level metadata. See the Followups in [track-metadata-model.md](track-metadata-model.md).
-
-All four post-#931 `/review` follow-ups landed 2026-05-22 as Phases 1-4 of the archived `feature/API-readiness-2` ledger ([archive-todos-api-readiness-2.md](archive-todos-api-readiness-2.md)): the STRICT-disclosure INPUT-domain gap (Phase 1 — see [track-strict-disclosure-input-domain-gap.md](track-strict-disclosure-input-domain-gap.md)), the `request_id` log wiring (Phase 2), the webhook-payload reserved-key collision (Phase 3 — see [track-webhook-payload-collision.md](track-webhook-payload-collision.md)), and the test-coverage backfill (Phase 4). Item 1, webhook signing, is the original plan's final stage — a separate cross-repo track that lands on its own schedule (the archived ledger's Phase 5). Item 2 is an independent long tail. Everything else is landed and described in current-state terms in the track docs below. Optional, non-blocking review notes — observations that were deliberately not acted on, each with a conditional trigger for when to revisit — are collected in [review-notes/](review-notes/).
+3. **`request_id` correlation on delivery error paths** — `request_id` is on the success-path completion logs but not on the failure-path messages of `StorageDeliveryError` / `WebhookDeliveryError`, nor on the `pipe_run.py:79` debug entry log. Small but real. See [track-delivery-error-path-request-id.md](track-delivery-error-path-request-id.md).
## Suggested read order
@@ -55,20 +54,4 @@ These are honored across the codebase today and the tracks below build on them:
## Conventions used in track docs
-Each `track-*.md` opens with **what this track is** (the concern in one paragraph) and a **current state** section — what is true in the code today, with verified file paths. A track with unfinished work then has an **open gaps** / **what's left** section and concrete **followups**; a fully-landed track says so explicitly. Every doc closes with **related tracks** cross-references. The docs describe the current state, not the history of how it got there — that history lives in the archived plans below.
-
-## Archived plans
-
-This directory replaces a set of phase-numbered docs (`error-handling-review.md`, `error-handling-phase-{0..7}-*.md`, `worker-error-handling-review.md`, `instructor-unwrap-other-workers.md`) that mixed historical progress with current state. The phase framing was useful when the work was sequenced; it is not useful as a reference for the current state and for planning what's next.
-
-Completed sweeps and plans are archived here, kept for their running notes and checkpoint history. They describe *what was done*, not the current state — the `track-*.md` docs above are authoritative for the current state.
-
-- [archive-todos-api-readiness-2.md](archive-todos-api-readiness-2.md) — the `feature/API-readiness-2` ledger (PRs #931 + #933): post-#931 `/review` follow-ups, the `*_exceptions.py` structural refactor, and the in-repo finalization of the error-handling overhaul.
-- [archive-worker-classification-sweep.md](archive-worker-classification-sweep.md) — the worker-classification sweep.
-- [archive-extract-classify-render.md](archive-extract-classify-render.md) — the ECR decomposition (5 checkpoints on `refactor/ECR`), with the key deviations from the original design.
-- [archive-error-handling-2.md](archive-error-handling-2.md) — the error-handling Phase 2 sweep (broad-except hygiene, `error_domain` metadata, retry & resilience, Temporal bridge, CLI/HTTP delivery, full-chain coverage).
-- [archive-temporal-activity-boundary.md](archive-temporal-activity-boundary.md) — wiring `from_message_exception` into every in-scope Temporal activity.
-- [archive-temporal-submitter-boundary.md](archive-temporal-submitter-boundary.md) — recovering the structured `ErrorReport` on the workflow → submitter and child-workflow → parent boundaries.
-- [archive-retry-and-resilience.md](archive-retry-and-resilience.md) — the retry-and-resilience plan: remove the `PipeRouter` transient-retry loop and make Tier 1 transport retry explicit and uniform.
-- [archive-llm-retry-loop-bypass.md](archive-llm-retry-loop-bypass.md) — a fix so transient LLM failures reached the (then-existing) `PipeRouter` retry loop; superseded when that loop was removed.
-- [archive-retry-graph-trace.md](archive-retry-graph-trace.md) — a phantom-error-node graph bug; resolved by removing the retry loop that caused it.
+Each `track-*.md` opens with **what this track is** (the concern in one paragraph) and a **current state** section — what is true in the code today, with verified file paths. A track with unfinished work then has an **open gaps** / **what's left** section and concrete **followups**; a fully-landed track says so explicitly. Every doc closes with **related tracks** cross-references. The docs describe the current state, not the history of how it got there.
diff --git a/wip/error-handling/api-readiness-2.html b/wip/error-handling/api-readiness-2.html
deleted file mode 100644
index a8544a3be..000000000
--- a/wip/error-handling/api-readiness-2.html
+++ /dev/null
@@ -1,906 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>API Readiness 2 — Co-developer Briefing</title>
-<style>
- :root {
- --bg: #0f1117;
- --panel: #181b24;
- --panel-2: #1f232f;
- --ink: #e6e8ee;
- --ink-dim: #9aa0ad;
- --line: #2c313f;
- --accent: #7c83ff;
- --accent-soft: #2a2d56;
- --green: #4ade80;
- --amber: #fbbf24;
- --red: #f87171;
- --blue: #60a5fa;
- --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
- }
- * { box-sizing: border-box; }
- html { scroll-behavior: smooth; }
- body {
- margin: 0;
- background: var(--bg);
- color: var(--ink);
- font: 16px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
- -webkit-font-smoothing: antialiased;
- }
- .wrap { max-width: 980px; margin: 0 auto; padding: 0 28px 120px; }
- header {
- padding: 64px 0 40px;
- border-bottom: 1px solid var(--line);
- margin-bottom: 44px;
- }
- .eyebrow {
- font-family: var(--mono);
- font-size: 12.5px;
- letter-spacing: .12em;
- text-transform: uppercase;
- color: var(--accent);
- margin: 0 0 14px;
- }
- h1 {
- font-size: 38px;
- line-height: 1.18;
- margin: 0 0 18px;
- letter-spacing: -.02em;
- }
- .lede { font-size: 18px; color: var(--ink-dim); margin: 0 0 20px; max-width: 70ch; }
- .branchline {
- font-family: var(--mono);
- font-size: 13px;
- color: var(--ink-dim);
- background: var(--panel);
- border: 1px solid var(--line);
- border-radius: 8px;
- padding: 10px 14px;
- display: inline-block;
- }
- .branchline b { color: var(--accent); }
- h2 {
- font-size: 25px;
- margin: 60px 0 8px;
- letter-spacing: -.015em;
- scroll-margin-top: 20px;
- }
- h2 .num {
- font-family: var(--mono);
- font-size: 15px;
- color: var(--accent);
- margin-right: 12px;
- }
- h3 { font-size: 18px; margin: 32px 0 8px; }
- .section-sub { color: var(--ink-dim); margin: 4px 0 22px; }
- p { margin: 14px 0; }
- a { color: var(--accent); text-decoration: none; }
- a:hover { text-decoration: underline; }
- code {
- font-family: var(--mono);
- font-size: .88em;
- background: var(--panel-2);
- border: 1px solid var(--line);
- border-radius: 5px;
- padding: 1px 6px;
- }
- strong { color: #fff; }
-
- nav.toc {
- background: var(--panel);
- border: 1px solid var(--line);
- border-radius: 12px;
- padding: 22px 26px;
- margin-bottom: 24px;
- }
- nav.toc h4 {
- margin: 0 0 12px;
- font-size: 12.5px;
- letter-spacing: .1em;
- text-transform: uppercase;
- color: var(--ink-dim);
- font-family: var(--mono);
- }
- nav.toc ol {
- margin: 0; padding: 0;
- list-style: none;
- columns: 2;
- column-gap: 36px;
- }
- nav.toc li {
- font-size: 14.5px;
- padding: 4px 0;
- counter-increment: toc;
- }
- nav.toc li::before {
- content: counter(toc, decimal-leading-zero);
- font-family: var(--mono);
- font-size: 12px;
- color: var(--accent);
- margin-right: 10px;
- }
- nav.toc ol { counter-reset: toc; }
-
- .card {
- background: var(--panel);
- border: 1px solid var(--line);
- border-radius: 12px;
- padding: 20px 24px;
- margin: 20px 0;
- }
- .callout {
- border-left: 3px solid var(--accent);
- background: var(--panel);
- border-radius: 0 10px 10px 0;
- padding: 14px 20px;
- margin: 22px 0;
- }
- .callout.why { border-color: var(--amber); }
- .callout.why .lbl { color: var(--amber); }
- .callout.bug { border-color: var(--red); }
- .callout.bug .lbl { color: var(--red); }
- .callout .lbl {
- font-family: var(--mono);
- font-size: 11.5px;
- letter-spacing: .1em;
- text-transform: uppercase;
- color: var(--accent);
- display: block;
- margin-bottom: 4px;
- }
-
- figure {
- margin: 30px 0;
- background: var(--panel);
- border: 1px solid var(--line);
- border-radius: 12px;
- padding: 26px 24px 14px;
- text-align: center;
- }
- figure svg { max-width: 100%; height: auto; }
- figcaption {
- font-size: 13px;
- color: var(--ink-dim);
- margin-top: 14px;
- text-align: center;
- }
-
- table {
- width: 100%;
- border-collapse: collapse;
- margin: 22px 0;
- font-size: 14.5px;
- }
- th, td {
- text-align: left;
- padding: 11px 14px;
- border-bottom: 1px solid var(--line);
- vertical-align: top;
- }
- th {
- font-size: 12px;
- letter-spacing: .06em;
- text-transform: uppercase;
- color: var(--ink-dim);
- font-weight: 600;
- }
- tr:last-child td { border-bottom: none; }
- td code { white-space: nowrap; }
-
- .pill {
- display: inline-block;
- font-family: var(--mono);
- font-size: 11px;
- font-weight: 600;
- padding: 2px 9px;
- border-radius: 20px;
- letter-spacing: .03em;
- }
- .pill.landed { background: rgba(74,222,128,.13); color: var(--green); border: 1px solid rgba(74,222,128,.3); }
- .pill.open { background: rgba(251,191,36,.13); color: var(--amber); border: 1px solid rgba(251,191,36,.3); }
- .pill.added { background: rgba(124,131,255,.13); color: var(--accent); border: 1px solid rgba(124,131,255,.3); }
- .pill.changed { background: rgba(96,165,250,.13); color: var(--blue); border: 1px solid rgba(96,165,250,.3); }
- .pill.fixed { background: rgba(248,113,113,.13); color: var(--red); border: 1px solid rgba(248,113,113,.3); }
-
- .code {
- background: #0b0d13;
- border: 1px solid var(--line);
- border-radius: 10px;
- margin: 20px 0;
- overflow: hidden;
- }
- .code .filename {
- font-family: var(--mono);
- font-size: 12px;
- color: var(--ink-dim);
- padding: 9px 16px;
- background: var(--panel-2);
- border-bottom: 1px solid var(--line);
- }
- .code pre {
- margin: 0;
- padding: 16px 18px;
- overflow-x: auto;
- font-family: var(--mono);
- font-size: 12.8px;
- line-height: 1.6;
- }
- .code pre .add { color: var(--green); display: block; background: rgba(74,222,128,.07); }
- .code pre .del { color: var(--red); display: block; background: rgba(248,113,113,.07); }
- .code pre .ctx { color: var(--ink-dim); display: block; }
- .code pre .hdr { color: var(--accent); display: block; }
- .code pre .cmt { color: #6b7280; }
-
- .grid2 { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; }
- @media (max-width: 720px) {
- .grid2 { grid-template-columns: 1fr; }
- nav.toc ol { columns: 1; }
- h1 { font-size: 30px; }
- }
-
- .footer {
- margin-top: 70px;
- padding-top: 24px;
- border-top: 1px solid var(--line);
- color: var(--ink-dim);
- font-size: 13.5px;
- }
- .tag {
- font-family: var(--mono);
- font-size: 11px;
- color: var(--accent);
- background: var(--accent-soft);
- padding: 2px 8px;
- border-radius: 5px;
- }
- ul.tight li { margin: 5px 0; }
-</style>
-</head>
-<body>
-<div class="wrap">
-
-<header>
- <p class="eyebrow">Co-developer Briefing</p>
- <h1>API Readiness 2 — making errors usable on the wire</h1>
- <p class="lede">The follow-up to the error-handling overhaul. Same <code>ErrorReport</code>, now ready to cross the process boundary: a stable identity per class, an RFC 7807 renderer, a STRICT projection that's safe to publish, a total recovery path, end-to-end <code>request_id</code>, and structured errors on the delivery webhook.</p>
- <span class="branchline">branch <b>feature/API-readiness-2</b> &nbsp;←&nbsp; <b>dev</b></span>
-</header>
-
-<div class="card">
- <strong>TL;DR for the busy reviewer.</strong>
- <p style="margin: 8px 0 6px">Before this branch, <code>ErrorReport</code> was the in-process source of truth — but consumers (the API, the SDKs, the CLI) had to humanize class names, build their own HTTP envelopes, and branch on <code>None</code> when a Temporal failure crossed without a payload. After this branch:</p>
- <ul class="tight" style="margin: 6px 0 10px">
- <li>Every <code>PipelexError</code> exposes a <strong>stable <code>title()</code> and <code>type_uri()</code></strong> — auto-derived, always populated, dereferencing to a generated docs page.</li>
- <li><code>ErrorReport.to_dict(disclosure_mode=…)</code> and <code>to_problem_document(…)</code> give the API a single, framework-free RFC 7807 envelope with a <strong>STRICT projection that's safe to publish</strong>.</li>
- <li>STRICT redaction is gated on <strong>message provenance</strong>, not inherited <code>error_domain</code> — a wrapper's internal text cannot leak through an <code>INPUT</code> cause.</li>
- <li><code>recover_error_report()</code> is now <strong>total</strong>: failures that cross Temporal without an embedded report synthesize an <code>UnrecoverableWorkflowFailureError</code> instead of returning <code>None</code>.</li>
- <li><code>request_id</code> rides on <code>JobMetadata</code> and lands on every Temporal log record via a <strong>per-invocation bound logger</strong>, not a <code>ContextVar</code>.</li>
- <li>Failed runs carry a <strong>structured <code>error</code> object on the delivery webhook</strong>; reserved keys in <code>WebhookTarget.payload</code> are rejected at construction time.</li>
- <li>Every <code>PipelexError</code> subclass now lives in <code>exceptions.py</code> / <code>*_exceptions.py</code> — <strong>enforced by an AST scan</strong>, discovered by a cached <code>rglob</code> at docs-generation time, and surfaced as a generated reference page.</li>
- </ul>
- <p style="margin: 0">Plan-of-record was the <a href="api-companion-revisions.md">api-companion-revisions</a> doc; the post-<code>/review</code> follow-ups landed as Phases 1-7 in <a href="../../TODOS.md">TODOS.md</a>. Stages 1-4 ship in this PR. Stage 5 (webhook signing) is a separate cross-repo track.</p>
-</div>
-
-<nav class="toc">
- <h4>Contents</h4>
- <ol>
- <li><a href="#why">Why this PR</a></li>
- <li><a href="#scope">What ships</a></li>
- <li><a href="#identity">PipelexError identity (title / type_uri)</a></li>
- <li><a href="#basemodel">ErrorReport as a BaseModel</a></li>
- <li><a href="#disclosure">DisclosureMode and the RFC 7807 envelope</a></li>
- <li><a href="#provenance">STRICT keyed on provenance, not domain</a></li>
- <li><a href="#recover">Total recover_error_report</a></li>
- <li><a href="#requestid">request_id end to end</a></li>
- <li><a href="#webhook">Webhook payload + reserved-key guard</a></li>
- <li><a href="#docpages">Error doc pages + filename convention</a></li>
- <li><a href="#tests">Tests we added</a></li>
- <li><a href="#open">What's still open</a></li>
- </ol>
-</nav>
-
-<!-- ============================================================ -->
-<h2 id="why"><span class="num">01</span>Why this PR</h2>
-<p class="section-sub">The error-handling overhaul made <code>ErrorReport</code> the in-process truth. This PR makes it the on-the-wire truth.</p>
-
-<p>The companion API team needed primitives the runtime did not yet expose. The <a href="changes-for-api-early-draft.md">original spec</a> drafted them and was then re-scoped on a close read (see <a href="api-companion-revisions.md">api-companion-revisions</a>). Concretely, downstream consumers had to:</p>
-
-<ul class="tight">
- <li><strong>Humanize class names themselves.</strong> No <code>title()</code> on the error classes; the API, CLI, agent CLI, and future SDKs each rolled their own. Drift waiting to happen.</li>
- <li><strong>Build their own HTTP envelope.</strong> No <code>to_problem_document()</code>; ~30 lines of FastAPI Response wiring re-invented per consumer.</li>
- <li><strong>Choose a "strict" projection at the wrong layer.</strong> A safe-for-external-surface projection had no single source of truth.</li>
- <li><strong>Hand-author a fallback when <code>recover_error_report</code> returned <code>None</code></strong> — every caller a copy of the same boilerplate, with a stringly-typed <code>error_type</code> that did not resolve to a real class.</li>
- <li><strong>Piggyback <code>request_id</code> on <code>webhook.payload</code></strong> because nothing on <code>JobMetadata</code> carried it.</li>
- <li><strong>Get nothing structured on a failed run's webhook</strong> — only the run id and the failure status; the error stayed in worker logs.</li>
-</ul>
-
-<div class="callout why">
- <span class="lbl">The principle</span>
- <strong>Pipelex owns the defaults.</strong> If a primitive has a sensible default — humanize a class name, kebab a class name, "an internal error occurred" placeholder — the default lives in pipelex and is returned as a populated value, not a <code>None</code> that consumers fill in. Total functions over partial ones. No speculative surface.
-</div>
-
-<!-- ============================================================ -->
-<h2 id="scope"><span class="num">02</span>What ships in this PR</h2>
-<p class="section-sub">One table, eleven rows. Use it as your jumping-off point — the rest of the doc drills into each one.</p>
-
-<table>
- <thead>
- <tr><th>Change</th><th>Kind</th><th>Source of truth</th></tr>
- </thead>
- <tbody>
- <tr>
- <td><code>PipelexError.title()</code> / <code>.type_uri()</code> — auto-derived, always populated; <code>ErrorReport</code> carries them as required fields.</td>
- <td><span class="pill added">added</span></td>
- <td><code>pipelex/base_exceptions.py</code></td>
- </tr>
- <tr>
- <td><code>ErrorReport</code> is now a frozen Pydantic <code>BaseModel</code> (was a frozen Pydantic dataclass).</td>
- <td><span class="pill changed">changed</span></td>
- <td><code>pipelex/base_exceptions.py</code></td>
- </tr>
- <tr>
- <td><code>DisclosureMode</code> enum + <code>to_dict(disclosure_mode=…)</code> + <code>to_problem_document(…)</code>.</td>
- <td><span class="pill added">added</span></td>
- <td><code>pipelex/base_exceptions.py</code></td>
- </tr>
- <tr>
- <td>STRICT redaction is gated on a per-class <code>caller_facing_message</code> flag (provenance), not on inherited <code>error_domain == INPUT</code>.</td>
- <td><span class="pill fixed">fixed</span></td>
- <td><code>pipelex/base_exceptions.py</code></td>
- </tr>
- <tr>
- <td><code>recover_error_report()</code> is total — synthesizes an <code>UnrecoverableWorkflowFailureError</code> report when no embedded payload survives.</td>
- <td><span class="pill changed">changed</span></td>
- <td><code>pipelex/temporal/tprl/temporal_error.py</code><br><code>pipelex/temporal/exceptions.py</code></td>
- </tr>
- <tr>
- <td><code>JobMetadata.request_id</code> + per-invocation bound <code>WorkflowLog</code> / <code>ActivityLog</code> — every worker log record carries the originating API request id.</td>
- <td><span class="pill added">added</span></td>
- <td><code>pipelex/pipeline/job_metadata.py</code><br><code>pipelex/temporal/log_temporal.py</code></td>
- </tr>
- <tr>
- <td>Failed runs deliver a structured <code>error</code> object on the webhook; <code>WebhookTarget.payload</code> rejects reserved keys (<code>pipeline_run_id</code> / <code>status</code> / <code>result_url</code> / <code>error</code>) at construction.</td>
- <td><span class="pill added">added</span></td>
- <td><code>pipelex/pipe_run/delivery_assignment.py</code><br><code>pipelex/pipe_run/delivery_executor.py</code></td>
- </tr>
- <tr>
- <td>Per-class error doc pages — one generated page per <code>PipelexError</code> subclass, plus a landing <code>docs/errors/index.md</code>; reached from each report's <code>type_uri</code>.</td>
- <td><span class="pill added">added</span></td>
- <td><code>pipelex/errors/error_pages_generator.py</code><br><code>docs/errors/</code></td>
- </tr>
- <tr>
- <td>Error class location convention enforced (<code>exceptions.py</code> / <code>*_exceptions.py</code>) — AST scan + runtime-walk completeness check.</td>
- <td><span class="pill changed">changed</span></td>
- <td><code>tests/unit/pipelex/errors/test_error_class_location_convention.py</code></td>
- </tr>
- <tr>
- <td>Duplicate <code>InputStuffSpecsFactoryError</code> class definition consolidated — two distinct class objects with the same name no longer in play.</td>
- <td><span class="pill fixed">fixed</span></td>
- <td><code>pipelex/core/pipes/inputs/input_stuff_specs_factory.py</code></td>
- </tr>
- </tbody>
-</table>
-
-<figure>
- <svg viewBox="0 0 760 360" xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace, Menlo, monospace">
- <defs>
- <marker id="arr" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto">
- <path d="M0,0 L10,5 L0,10 Z" fill="#7c83ff"/>
- </marker>
- </defs>
- <!-- worker -->
- <rect x="20" y="60" width="160" height="60" rx="8" fill="#181b24" stroke="#2c313f"/>
- <text x="100" y="84" fill="#e6e8ee" font-size="13" text-anchor="middle" font-weight="bold">Worker</text>
- <text x="100" y="103" fill="#9aa0ad" font-size="11" text-anchor="middle">SDK exc → CogtError</text>
- <!-- activity bridge -->
- <rect x="210" y="60" width="160" height="60" rx="8" fill="#181b24" stroke="#2c313f"/>
- <text x="290" y="84" fill="#e6e8ee" font-size="13" text-anchor="middle" font-weight="bold">Activity boundary</text>
- <text x="290" y="103" fill="#9aa0ad" font-size="11" text-anchor="middle">@convert_pipelex_errors</text>
- <!-- workflow -->
- <rect x="400" y="60" width="160" height="60" rx="8" fill="#181b24" stroke="#2c313f"/>
- <text x="480" y="84" fill="#e6e8ee" font-size="13" text-anchor="middle" font-weight="bold">Workflow</text>
- <text x="480" y="103" fill="#9aa0ad" font-size="11" text-anchor="middle">recover_error_report</text>
- <!-- submitter -->
- <rect x="590" y="60" width="160" height="60" rx="8" fill="#181b24" stroke="#2c313f"/>
- <text x="670" y="84" fill="#e6e8ee" font-size="13" text-anchor="middle" font-weight="bold">Submitter</text>
- <text x="670" y="103" fill="#9aa0ad" font-size="11" text-anchor="middle">ErrorReport (total)</text>
- <!-- delivery -->
- <rect x="400" y="170" width="160" height="60" rx="8" fill="#2a2d56" stroke="#7c83ff"/>
- <text x="480" y="194" fill="#fff" font-size="13" text-anchor="middle" font-weight="bold">DeliveryExecutor</text>
- <text x="480" y="213" fill="#c7c9f0" font-size="11" text-anchor="middle">webhook.payload["error"]</text>
- <!-- API surface -->
- <rect x="280" y="280" width="200" height="60" rx="8" fill="#181b24" stroke="#2c313f"/>
- <text x="380" y="304" fill="#e6e8ee" font-size="13" text-anchor="middle" font-weight="bold">API / SDKs / CLI</text>
- <text x="380" y="323" fill="#9aa0ad" font-size="11" text-anchor="middle">to_problem_document(STRICT)</text>
- <!-- arrows -->
- <line x1="180" y1="90" x2="208" y2="90" stroke="#7c83ff" stroke-width="2" marker-end="url(#arr)"/>
- <line x1="370" y1="90" x2="398" y2="90" stroke="#7c83ff" stroke-width="2" marker-end="url(#arr)"/>
- <line x1="560" y1="90" x2="588" y2="90" stroke="#7c83ff" stroke-width="2" marker-end="url(#arr)"/>
- <line x1="480" y1="120" x2="480" y2="168" stroke="#7c83ff" stroke-width="2" marker-end="url(#arr)"/>
- <line x1="480" y1="230" x2="380" y2="278" stroke="#7c83ff" stroke-width="2" marker-end="url(#arr)"/>
- <!-- request_id rail -->
- <line x1="100" y1="40" x2="670" y2="40" stroke="#fbbf24" stroke-width="2" stroke-dasharray="6 4"/>
- <text x="385" y="32" fill="#fbbf24" font-size="11" text-anchor="middle">request_id rides on JobMetadata, lands on every log record</text>
- </svg>
- <figcaption>The path an error takes after this PR — and the things this PR added at each stop.</figcaption>
-</figure>
-
-<!-- ============================================================ -->
-<h2 id="identity"><span class="num">03</span>PipelexError identity — <code>title()</code> and <code>type_uri()</code></h2>
-<p class="section-sub">Every error class becomes a first-class entry in a stable, documented namespace.</p>
-
-<p>Two classmethods on <code>PipelexError</code>, both <strong>total</strong> — they always return a populated <code>str</code>. Auto-derived from the class name; a subclass overrides only when the default is wrong by declaring <code>_declared_title</code> or <code>_declared_type_uri</code> <strong>directly in its own body</strong>. Inheritance is intentionally bypassed via <code>cls.__dict__.get(…)</code> — a parent's curated title does not silently capture every subclass.</p>
-
-<div class="code">
- <div class="filename">pipelex/base_exceptions.py — the two new classmethods</div>
-<pre><span class="hdr">class PipelexError(Exception):</span>
-<span class="ctx"> _declared_title: ClassVar[str | None] = "Pipelex error"</span>
-<span class="ctx"> _declared_type_uri: ClassVar[str | None] = None</span>
-<span class="ctx"></span>
-<span class="add"> @classmethod</span>
-<span class="add"> def title(cls) -> str:</span>
-<span class="add"> # Read only the class's OWN body — a curated title is never inherited.</span>
-<span class="add"> declared = cls.__dict__.get("_declared_title")</span>
-<span class="add"> if isinstance(declared, str):</span>
-<span class="add"> return declared</span>
-<span class="add"> return _humanize_class_name(cls.__name__)</span>
-<span class="add"></span>
-<span class="add"> @classmethod</span>
-<span class="add"> def type_uri(cls) -> str:</span>
-<span class="add"> declared = cls.__dict__.get("_declared_type_uri")</span>
-<span class="add"> if isinstance(declared, str):</span>
-<span class="add"> return declared</span>
-<span class="add"> return f"{URLs.error_docs_base}/{pascal_case_to_kebab(cls.__name__)}/"</span></pre>
-</div>
-
-<p>Both values are populated on every <code>ErrorReport</code> as <strong>required string fields</strong> — consumers read <code>report.title</code> / <code>report.type_uri</code> directly. No humanize helper to keep in sync, no kebab helper, no "is this <code>None</code>?" branch.</p>
-
-<table>
- <thead><tr><th>Class</th><th><code>title()</code></th><th><code>type_uri()</code></th></tr></thead>
- <tbody>
- <tr>
- <td><code>PipeOperatorRetryError</code></td>
- <td><code>"Pipe operator retry"</code></td>
- <td><code>…/errors/pipe-operator-retry-error/</code></td>
- </tr>
- <tr>
- <td><code>LLMCompletionError</code></td>
- <td><code>"LLM completion"</code> <em>(acronym preserved)</em></td>
- <td><code>…/errors/llm-completion-error/</code></td>
- </tr>
- <tr>
- <td><code>UnrecoverableWorkflowFailureError</code></td>
- <td><code>"Unrecoverable workflow failure"</code></td>
- <td><code>…/errors/unrecoverable-workflow-failure-error/</code></td>
- </tr>
- </tbody>
-</table>
-
-<div class="callout">
- <span class="lbl">Pure function</span>
- <code>type_uri()</code> reads only the <code>URLs.error_docs_base</code> constant — safe to call before Pipelex boot, safe inside Temporal workflow code, no determinism hazard. The earlier <code>ErrorManager</code> indirection (and the <code>[errors_config]</code> block) was removed for exactly this reason: a mutable read of the base URI would have leaked into workflow history.
-</div>
-
-<!-- ============================================================ -->
-<h2 id="basemodel"><span class="num">04</span><code>ErrorReport</code> as a Pydantic <code>BaseModel</code></h2>
-<p class="section-sub">A small conversion that unlocks the Temporal data-converter path.</p>
-
-<p><code>ErrorReport</code> was a frozen Pydantic <em>dataclass</em>. We needed it to cross the Temporal activity boundary as a typed field on <code>DeliveryActivityArg</code> — like every other field on that arg — instead of as a <code>dict</code> shim with a <code>_dict</code> suffix telegraphing the implementation detail. The already-shipped <code>BaseModelPayloadConverter._unwrap_optional_base_model</code> handles <code>BaseModel | None</code> directly; teaching it to round-trip Pydantic dataclasses generically would have been a much larger diff for the same end.</p>
-
-<div class="code">
- <div class="filename">pipelex/base_exceptions.py — dataclass → BaseModel</div>
-<pre><span class="del">@dataclass(frozen=True, config=ConfigDict(extra="forbid", arbitrary_types_allowed=True))</span>
-<span class="del">class ErrorReport:</span>
-<span class="add">class ErrorReport(BaseModel):</span>
-<span class="add"> model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)</span>
-<span class="ctx"></span>
-<span class="ctx"> error_type: str</span>
-<span class="ctx"> message: str</span>
-<span class="add"> title: str</span>
-<span class="add"> type_uri: str</span>
-<span class="ctx"> error_category: str | None = None</span>
-<span class="ctx"> error_domain: str | None = None</span>
-<span class="ctx"> retryable: bool | None = None</span>
-<span class="ctx"> user_action: UserAction | None = None</span>
-<span class="ctx"> model: str | None = None</span>
-<span class="ctx"> provider: str | None = None</span>
-<span class="ctx"> provider_metadata: ProviderErrorMetadata | None = None</span>
-<span class="add"> caller_facing_message: bool = False</span></pre>
-</div>
-
-<div class="callout bug">
- <span class="lbl">Behavioral note</span>
- An attempted mutation now raises <code>pydantic.ValidationError</code> instead of <code>dataclasses.FrozenInstanceError</code>. Anyone catching the specific dataclass error gets a surprise — tests updated to match. <code>to_dict</code> uses <code>self.model_dump(exclude_none=True)</code>; <code>from_dict</code> uses <code>cls.model_validate(data)</code>.
-</div>
-
-<!-- ============================================================ -->
-<h2 id="disclosure"><span class="num">05</span><code>DisclosureMode</code> and the RFC 7807 envelope</h2>
-<p class="section-sub">One enum, two projection methods. The single source of truth for "what does strict mode hide".</p>
-
-<p>Two methods on <code>ErrorReport</code>, both parameterized by a <code>DisclosureMode</code>: <code>to_dict(disclosure_mode=…)</code> projects the same report, and <code>to_problem_document(…)</code> renders it as an RFC 7807 <code>application/problem+json</code> envelope. The runtime stays <strong>HTTP-agnostic</strong> — both return plain dicts; no FastAPI/Starlette import.</p>
-
-<div class="code">
- <div class="filename">pipelex/base_exceptions.py — the new public surface</div>
-<pre><span class="add">class DisclosureMode(StrEnum):</span>
-<span class="add"> VERBOSE = "verbose"</span>
-<span class="add"> STRICT = "strict"</span>
-<span class="ctx"></span>
-<span class="ctx">class ErrorReport(BaseModel):</span>
-<span class="add"> def to_dict(self, disclosure_mode: DisclosureMode = DisclosureMode.VERBOSE) -> dict[str, Any]: ...</span>
-<span class="add"> def to_problem_document(</span>
-<span class="add"> self,</span>
-<span class="add"> *,</span>
-<span class="add"> instance: str | None = None,</span>
-<span class="add"> request_id: str | None = None,</span>
-<span class="add"> disclosure_mode: DisclosureMode = DisclosureMode.VERBOSE,</span>
-<span class="add"> ) -> dict[str, Any]: ...</span></pre>
-</div>
-
-<h3>STRICT redaction rule</h3>
-<p>Keys kept in <strong>all</strong> modes (stable identifiers, never sensitive): <code>error_type</code>, <code>error_domain</code>, <code>error_category</code>, <code>retryable</code>, <code>title</code>, <code>type_uri</code>. STRICT then projects the rest:</p>
-
-<figure>
- <svg viewBox="0 0 760 300" xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace, Menlo, monospace">
- <!-- verbose -->
- <rect x="20" y="20" width="340" height="260" rx="10" fill="#181b24" stroke="#2c313f"/>
- <text x="190" y="48" fill="#e6e8ee" font-size="14" text-anchor="middle" font-weight="bold">VERBOSE</text>
- <text x="190" y="66" fill="#9aa0ad" font-size="11" text-anchor="middle">strict inverse of from_dict — round-trips</text>
- <g font-size="12" fill="#4ade80">
- <text x="50" y="100">✓ error_type, error_domain, error_category, retryable</text>
- <text x="50" y="124">✓ title, type_uri</text>
- <text x="50" y="148">✓ message (verbatim)</text>
- <text x="50" y="172">✓ user_action</text>
- <text x="50" y="196">✓ model, provider</text>
- <text x="50" y="220">✓ provider_metadata (full)</text>
- </g>
- <!-- strict -->
- <rect x="400" y="20" width="340" height="260" rx="10" fill="#181b24" stroke="#2c313f"/>
- <text x="570" y="48" fill="#e6e8ee" font-size="14" text-anchor="middle" font-weight="bold">STRICT</text>
- <text x="570" y="66" fill="#9aa0ad" font-size="11" text-anchor="middle">classification projection — safe to publish</text>
- <g font-size="12">
- <text x="430" y="100" fill="#4ade80">✓ error_type, error_domain, error_category, retryable</text>
- <text x="430" y="124" fill="#4ade80">✓ title, type_uri</text>
- <text x="430" y="148" fill="#fbbf24">~ message — verbatim iff caller_facing_message else placeholder</text>
- <text x="430" y="172" fill="#fbbf24">~ user_action — kept iff caller_facing_message</text>
- <text x="430" y="196" fill="#f87171">✗ model, provider — always dropped</text>
- <text x="430" y="220" fill="#fbbf24">~ provider_metadata — curated subset</text>
- <text x="430" y="238" fill="#9aa0ad" font-size="11"> (status_code + retry_after_seconds only)</text>
- </g>
- </svg>
- <figcaption>VERBOSE round-trips; STRICT is a lossy classification projection. The keep/drop decision lives in <code>ErrorReport.to_dict</code> only — every external surface reads it from there.</figcaption>
-</figure>
-
-<p><strong>Why <code>provider_metadata</code> isn't fully dropped under STRICT.</strong> Two fields on it — <code>status_code</code> and <code>retry_after_seconds</code> — are <em>actionable client hints</em>, not provider attribution: the HTTP adapter needs <code>status_code == 429</code> to surface a <code>Retry-After</code> header from the same payload. We keep that curated slice and drop everything else (<code>provider_error_code</code>, <code>body</code>, <code>request_id</code>).</p>
-
-<div class="code">
- <div class="filename">A typical STRICT projection (illustrative)</div>
-<pre><span class="ctx">{</span>
-<span class="ctx"> "error_type": "LLMCompletionError",</span>
-<span class="ctx"> "error_domain": "runtime",</span>
-<span class="ctx"> "error_category": "transient",</span>
-<span class="ctx"> "retryable": true,</span>
-<span class="ctx"> "title": "LLM completion",</span>
-<span class="ctx"> "type_uri": "https://docs.pipelex.com/latest/errors/llm-completion-error/",</span>
-<span class="ctx"> "message": "An internal error occurred.",</span> <span class="cmt"> // placeholder — provenance != caller-facing</span>
-<span class="ctx"> "provider_metadata": {</span>
-<span class="ctx"> "status_code": 429,</span> <span class="cmt"> // kept — actionable</span>
-<span class="ctx"> "retry_after_seconds": 12</span> <span class="cmt"> // kept — actionable</span>
-<span class="ctx"> }</span>
-<span class="ctx">}</span></pre>
-</div>
-
-<h3>The RFC 7807 envelope</h3>
-<p><code>to_problem_document</code> maps the 7807 slots from the report (<code>type</code> ← <code>type_uri</code>, <code>title</code> ← <code>title</code>, <code>status</code> ← <code>http_status</code>, <code>detail</code> ← <code>message</code> after redaction), then rides the Pipelex-native fields as extension members. The downstream HTTP adapter wraps the dict in its framework's response shape — that's its 10 lines, not 30.</p>
-
-<!-- ============================================================ -->
-<h2 id="provenance"><span class="num">06</span>STRICT keyed on provenance, not <code>error_domain</code></h2>
-<p class="section-sub">The post-<code>/review</code> fix. STRICT got two leak vectors right at landing; this gates both.</p>
-
-<div class="callout bug">
- <span class="lbl">The bug</span>
- STRICT originally let <code>message</code> through when <code>error_domain == INPUT</code> — the assumption being "<code>INPUT</code> reports describe the caller's own data, so the wording is safe to echo". But <code>error_domain</code> is <strong>inherited up the <code>__cause__</code> chain</strong> by <code>_enrich_error_report_from_cause</code>. So:
- <ul class="tight" style="margin-top:8px">
- <li>A domain-less wrapper (e.g. <code>PipelexUnexpectedError</code>) raised <code>from</code> an <code>INPUT</code>-domain cause inherited the cause's domain and leaked its own (non-caller-facing) <code>message</code> through STRICT.</li>
- <li><code>to_problem_document(STRICT)</code> echoed <code>provider</code> / <code>model</code> / <code>provider_metadata</code> for <code>INPUT</code> reports regardless of whether they originated in a provider call.</li>
- </ul>
-</div>
-
-<p>The fix gates STRICT on <em>where the <code>message</code> came from</em>, not on a classification that gets passed up the chain. A new per-class <code>ClassVar</code> opts the class in:</p>
-
-<div class="code">
- <div class="filename">pipelex/base_exceptions.py — the provenance flag</div>
-<pre><span class="hdr">class PipelexError(Exception):</span>
-<span class="add"> # True when this class authors caller-facing copy. STRICT keeps `message`</span>
-<span class="add"> # and `user_action` verbatim for flagged classes; redacts for every other.</span>
-<span class="add"> # Inherits normally — subclasses of a caller-facing error stay caller-facing.</span>
-<span class="add"> _authors_caller_facing_message: ClassVar[bool] = False</span>
-<span class="ctx"></span>
-<span class="ctx">class ErrorReport(BaseModel):</span>
-<span class="add"> # Set at construction from `PipelexError._authors_caller_facing_message`.</span>
-<span class="add"> # Wrapper-wins: never inherited from the __cause__ chain, since it tracks</span>
-<span class="add"> # the provenance of `report.message` (always the wrapper's own message).</span>
-<span class="add"> caller_facing_message: bool = False</span></pre>
-</div>
-
-<p>Only the error classes whose <code>message</code> is <strong>genuinely caller-facing copy</strong> opt in — text describing the caller's own input rather than internal state. Today that's <code>PipelexInterpreterError</code> (<code>.mthds</code> syntax / semantics) and <code>ValidateBundleError</code> (bundle-level validation). Everything else has its <code>message</code> replaced with the generic <code>"An internal error occurred."</code> placeholder under STRICT.</p>
-
-<p>The same fix unconditionally drops <code>provider</code> and <code>model</code> under STRICT, regardless of domain. <code>provider_metadata</code> goes through the curated slice above.</p>
-
-<!-- ============================================================ -->
-<h2 id="recover"><span class="num">07</span>Total <code>recover_error_report</code> + <code>UnrecoverableWorkflowFailureError</code></h2>
-<p class="section-sub">Removes the "caller hand-authors a fallback report" duplication pattern at every downstream site.</p>
-
-<p>The original spec had <code>recover_error_report(exc) -> ErrorReport | None</code>. Each caller (the API submitter, the CLI on async result, anyone landing later) would then duplicate the same fallback boilerplate — an <code>ErrorReport(error_type="WorkflowFailureUnrecoverable", …)</code> with a stringly-typed <code>error_type</code> that didn't resolve to a real class, couldn't carry an auto-derived <code>type_uri</code>, and couldn't be matched on by pattern.</p>
-
-<p>We turned it into a <strong>total</strong> function. When the Temporal failure chain carries no embedded report — a non-Pipelex exception, a worker crash, a heartbeat timeout, anything that crossed without going through the activity bridge — it synthesizes one from a new error class.</p>
-
-<div class="code">
- <div class="filename">pipelex/temporal/tprl/temporal_error.py — total signature, single fallback class</div>
-<pre><span class="del">def recover_error_report(exc: BaseException) -> ErrorReport | None:</span>
-<span class="add">def recover_error_report(exc: BaseException) -> ErrorReport:</span>
-<span class="ctx"> report_dict = _find_error_report_dict(exc)</span>
-<span class="ctx"> if report_dict is not None:</span>
-<span class="del"> return ErrorReport.from_dict(report_dict) # could raise ValidationError</span>
-<span class="del"> return None</span>
-<span class="add"> try:</span>
-<span class="add"> return ErrorReport.from_dict(report_dict)</span>
-<span class="add"> except ValidationError:</span>
-<span class="add"> # Internal contract bug — but we still need to deliver the failure</span>
-<span class="add"> # webhook. Surface it via the same fallback class with a marker on</span>
-<span class="add"> # the message so the bug stays visible on the wire.</span>
-<span class="add"> recovered = report_dict.get("message")</span>
-<span class="add"> recovered_msg = recovered if isinstance(recovered, str) and recovered.strip() else _message_from_exc(exc)</span>
-<span class="add"> fallback = f"{recovered_msg} {_ERROR_REPORT_VALIDATION_FAILED_MARKER}"</span>
-<span class="add"> return UnrecoverableWorkflowFailureError(fallback).to_error_report()</span>
-<span class="add"> return UnrecoverableWorkflowFailureError(_message_from_exc(exc)).to_error_report()</span></pre>
-</div>
-
-<p>The new <code>UnrecoverableWorkflowFailureError</code> (<code>pipelex/temporal/exceptions.py</code>) is a real <code>PipelexError</code> subclass — it has a <code>type_uri</code> that resolves to a generated doc page, a stable identity, and shows up in the registry like every other class. Callers in <code>workflow_caller.py</code> dropped their three <code>if error_report is not None</code> branches.</p>
-
-<p><code>_message_from_exc</code> walks the <code>__cause__</code> chain and surfaces the <strong>deepest non-empty message</strong> — not the outer <code>"Workflow execution failed"</code> generic, which would defeat diagnostic intent. There's a cycle guard (<code>id(node)</code> set) and a <code>repr(exc)</code> fallback when every node has an empty message.</p>
-
-<div class="callout">
- <span class="lbl">Behavioral change at the no-report path</span>
- <code>WorkflowExecutionError.message</code> on the no-report path changes from the Pipelex-framed <code>"Failed to execute workflow X"</code> to the synthesized <code>_message_from_exc(exc)</code> text — strictly more diagnostic. The legacy framing remains on the <code>WorkflowAlreadyStartedError</code> / <code>RPCError</code> / non-<code>ApplicationError</code>-cause paths (those don't call <code>recover_error_report</code>).
-</div>
-
-<!-- ============================================================ -->
-<h2 id="requestid"><span class="num">08</span><code>request_id</code> end to end</h2>
-<p class="section-sub">From <code>X-Request-ID</code> at the API edge to every Temporal log record on the worker.</p>
-
-<p>The companion API needed a correlation id that survives the Temporal serialization boundary. The candidate was a <code>ContextVar</code> — same pattern as <code>session_id</code> elsewhere — but a <code>ContextVar</code> is <strong>process-local</strong>: it does not cross the activity/workflow serialization boundary in a distributed worker topology. So <code>request_id</code> lives on <code>JobMetadata</code> instead, threaded explicitly into the per-invocation log binding.</p>
-
-<div class="code">
- <div class="filename">pipelex/pipeline/job_metadata.py</div>
-<pre><span class="ctx">class JobMetadata(BaseModel):</span>
-<span class="ctx"> pipeline_run_id: str</span>
-<span class="ctx"> session_id: str | None = None</span>
-<span class="ctx"> user_id: str | None = None</span>
-<span class="add"> request_id: str | None = None # caller-supplied (e.g. X-Request-ID at the API edge)</span></pre>
-</div>
-
-<p>On the worker side, the two log helpers gained a shared base that builds the right <code>extra</code> dict on every severity call:</p>
-
-<div class="code">
- <div class="filename">pipelex/temporal/log_temporal.py — bound logger adapter</div>
-<pre><span class="add">class _RequestIdLog:</span>
-<span class="add"> """Per-invocation Temporal log helper bound to a request_id."""</span>
-<span class="add"></span>
-<span class="add"> _logger: ClassVar[Any] # workflow.logger or activity.logger</span>
-<span class="add"></span>
-<span class="add"> def __init__(self, request_id: str | None = None) -> None:</span>
-<span class="add"> self._request_id = request_id</span>
-<span class="add"></span>
-<span class="add"> def _build_extra(self) -> dict[str, str] | None:</span>
-<span class="add"> if self._request_id is None:</span>
-<span class="add"> return None</span>
-<span class="add"> return {"request_id": self._request_id}</span>
-<span class="add"></span>
-<span class="add"> def info(self, content): self._logger.log(logging.INFO, content, extra=self._build_extra())</span>
-<span class="add"> # … debug / warning / error / critical / verbose / dev — same shape</span>
-<span class="add"></span>
-<span class="add">class WorkflowLog(_RequestIdLog):</span>
-<span class="add"> _logger: ClassVar[Any] = workflow.logger</span>
-<span class="add"></span>
-<span class="add">class ActivityLog(_RequestIdLog):</span>
-<span class="add"> _logger: ClassVar[Any] = activity.logger</span></pre>
-</div>
-
-<p><code>WfPipeRun</code> / <code>WfPipeRouter</code> build a <code>WorkflowLog(request_id=job_metadata.request_id)</code> at entry; every log call from that invocation lands the id automatically via the <code>extra</code> dict — no call-site threading, no kwarg to forget. The module-level <code>workflow_log</code> / <code>activity_log</code> singletons stay unbound for call sites that have no <code>job_metadata</code> in scope (e.g. <code>TemporalError</code>'s severity logs).</p>
-
-<p>The same <code>request_id</code> also crosses the direct-mode boundary: <code>PipeRun</code> forwards it to <code>DeliveryExecutor</code> so the webhook delivery log line carries the originating id even when there's no Temporal involved.</p>
-
-<!-- ============================================================ -->
-<h2 id="webhook"><span class="num">09</span>Webhook payload + reserved-key guard</h2>
-<p class="section-sub">A failure on the wire now carries a structured <code>error</code>; a static payload can't silently shift meaning with delivery status.</p>
-
-<p>On a failed run, <code>DeliveryExecutor</code> threads the <code>ErrorReport</code> into <code>_notify_webhook</code>, which adds an <code>error</code> key to the outgoing body. Receivers rehydrate losslessly via <code>ErrorReport.from_dict(payload["error"])</code> — and the API then chooses its own disclosure at its own surface via <code>to_problem_document(disclosure_mode=STRICT)</code>. The webhook stays VERBOSE because the URL is caller-supplied: the receiver already owns the run and its data.</p>
-
-<div class="code">
- <div class="filename">pipelex/pipe_run/delivery_executor.py</div>
-<pre><span class="ctx">class DeliveryExecutor:</span>
-<span class="ctx"> async def execute(</span>
-<span class="ctx"> self,</span>
-<span class="ctx"> ...,</span>
-<span class="add"> error_report: ErrorReport | None = None,</span>
-<span class="add"> request_id: str | None = None,</span>
-<span class="ctx"> ) -> None:</span>
-<span class="ctx"> ...</span>
-<span class="ctx"> await self._notify_webhook(pipeline_run_id, status, result_url, webhook,</span>
-<span class="add"> error_report, request_id=request_id)</span>
-<span class="ctx"></span>
-<span class="ctx"> async def _notify_webhook(self, ..., error_report, request_id=None) -> None:</span>
-<span class="ctx"> payload = dict(webhook.payload) # caller's static payload</span>
-<span class="ctx"> payload["pipeline_run_id"] = pipeline_run_id</span>
-<span class="ctx"> payload["status"] = status</span>
-<span class="ctx"> payload["result_url"] = result_url</span>
-<span class="add"> if error_report is not None:</span>
-<span class="add"> payload["error"] = error_report.to_dict(disclosure_mode=DisclosureMode.VERBOSE)</span></pre>
-</div>
-
-<p>That writes four Pipelex-owned keys on top of the caller's static <code>payload</code>. If a caller registers a <code>WebhookTarget</code> whose payload <em>already declares</em> one of those keys, its value silently shifts with delivery status — a static <code>"status": "ok"</code> at registration becomes <code>"status": "FAILED"</code> on the failure delivery. We reject the collision at construction time instead:</p>
-
-<div class="code">
- <div class="filename">pipelex/pipe_run/delivery_assignment.py — reserved-key validator</div>
-<pre><span class="add">_RESERVED_WEBHOOK_PAYLOAD_KEYS: frozenset[str] = frozenset({</span>
-<span class="add"> "pipeline_run_id", "status", "result_url", "error",</span>
-<span class="add">})</span>
-<span class="ctx"></span>
-<span class="ctx">class WebhookTarget(BaseModel):</span>
-<span class="ctx"> url: str</span>
-<span class="ctx"> headers: dict[str, str] = Field(default_factory=dict)</span>
-<span class="ctx"> payload: dict[str, Any] = Field(default_factory=dict)</span>
-<span class="ctx"></span>
-<span class="add"> @field_validator("payload", mode="after")</span>
-<span class="add"> @classmethod</span>
-<span class="add"> def _reject_reserved_keys(cls, value: dict[str, Any]) -> dict[str, Any]:</span>
-<span class="add"> collisions = set(value) & _RESERVED_WEBHOOK_PAYLOAD_KEYS</span>
-<span class="add"> if collisions:</span>
-<span class="add"> msg = (</span>
-<span class="add"> f"WebhookTarget.payload contains reserved keys: {sorted(collisions)}. "</span>
-<span class="add"> "Pipelex owns these keys (assigned per delivery); choose different names."</span>
-<span class="add"> )</span>
-<span class="add"> raise ValueError(msg)</span>
-<span class="add"> return value</span></pre>
-</div>
-
-<p>Loud failure at construction; no surprise at delivery time.</p>
-
-<!-- ============================================================ -->
-<h2 id="docpages"><span class="num">10</span>Per-class doc pages + filename convention</h2>
-<p class="section-sub">Every <code>type_uri</code> dereferences to a real page. Every <code>PipelexError</code> subclass shows up by construction.</p>
-
-<p>A new <code>pipelex-dev generate-error-pages</code> command writes one Markdown page per <code>PipelexError</code> subclass to <code>docs/errors/&lt;kebab-class-name&gt;.md</code>, plus a landing <code>docs/errors/index.md</code> grouped by top-level <code>PipelexError</code> branch. Each page carries the class identity table (<code>error_type</code>, <code>title</code>, <code>type_uri</code>, <code>error_domain</code>, defining module, parent-class link, class-level <code>user_action</code> when declared), a docstring fragment, and a back-link to the Error Model overview. Generated pages are stamped <code>&lt;!-- pipelex:generated --&gt;</code>; maintainers can claim a page for hand-editing by adding <code>&lt;!-- pipelex:authored --&gt;</code> and the generator preserves it across runs.</p>
-
-<h3>The discovery problem</h3>
-<p>Discovery has to enumerate every subclass — including those whose home module is only reached via a deferred import path (every plugin worker / factory: anthropic, bedrock, gateway, google, mistral, openai/vertex, azure, portkey, plus standalone classes that ship under extras). The earlier registry-with-allowlist <code>pipelex/errors/error_module_registry.py</code> was a drift magnet — and got drift wrong: a spot check found ~20 classes invisible to it.</p>
-
-<p>We replaced the registry with a <strong>filename convention</strong> + a <strong>cached <code>rglob</code></strong>, gated by tests on both sides:</p>
-
-<figure>
- <svg viewBox="0 0 760 280" xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace, Menlo, monospace">
- <defs>
- <marker id="arr2" markerWidth="10" markerHeight="10" refX="8" refY="5" orient="auto">
- <path d="M0,0 L10,5 L0,10 Z" fill="#7c83ff"/>
- </marker>
- </defs>
- <!-- convention -->
- <rect x="20" y="30" width="220" height="80" rx="10" fill="#181b24" stroke="#2c313f"/>
- <text x="130" y="56" fill="#e6e8ee" font-size="13" text-anchor="middle" font-weight="bold">Filename convention</text>
- <text x="130" y="74" fill="#9aa0ad" font-size="11" text-anchor="middle">exceptions.py</text>
- <text x="130" y="90" fill="#9aa0ad" font-size="11" text-anchor="middle">*_exceptions.py</text>
- <!-- AST -->
- <rect x="290" y="30" width="220" height="80" rx="10" fill="#181b24" stroke="#2c313f"/>
- <text x="400" y="56" fill="#e6e8ee" font-size="13" text-anchor="middle" font-weight="bold">AST scan</text>
- <text x="400" y="74" fill="#9aa0ad" font-size="11" text-anchor="middle">finds every subclass on disk</text>
- <text x="400" y="92" fill="#9aa0ad" font-size="11" text-anchor="middle">tests/.../test_error_class_location_convention.py</text>
- <!-- runtime walk -->
- <rect x="560" y="30" width="180" height="80" rx="10" fill="#181b24" stroke="#2c313f"/>
- <text x="650" y="56" fill="#e6e8ee" font-size="13" text-anchor="middle" font-weight="bold">Runtime __subclasses__()</text>
- <text x="650" y="76" fill="#9aa0ad" font-size="11" text-anchor="middle">after force-load</text>
- <text x="650" y="92" fill="#9aa0ad" font-size="11" text-anchor="middle">completeness check</text>
- <!-- bottom -->
- <rect x="20" y="160" width="720" height="80" rx="10" fill="#2a2d56" stroke="#7c83ff"/>
- <text x="380" y="186" fill="#fff" font-size="13" text-anchor="middle" font-weight="bold">_force_load_all_error_modules() — functools.cache, dev/test-time only</text>
- <text x="380" y="206" fill="#c7c9f0" font-size="11" text-anchor="middle">rglob('**/exceptions.py'), rglob('**/*_exceptions.py'), importlib.import_module(each)</text>
- <text x="380" y="222" fill="#c7c9f0" font-size="11" text-anchor="middle">never touched by production Pipelex.make() — discovery has zero runtime side effect outside generation/tests</text>
- <!-- arrows -->
- <line x1="240" y1="70" x2="288" y2="70" stroke="#7c83ff" stroke-width="2" marker-end="url(#arr2)"/>
- <line x1="510" y1="70" x2="558" y2="70" stroke="#7c83ff" stroke-width="2" marker-end="url(#arr2)"/>
- <line x1="130" y1="110" x2="130" y2="158" stroke="#7c83ff" stroke-width="2" marker-end="url(#arr2)"/>
- <line x1="400" y1="110" x2="400" y2="158" stroke="#7c83ff" stroke-width="2" marker-end="url(#arr2)"/>
- <line x1="650" y1="110" x2="650" y2="158" stroke="#7c83ff" stroke-width="2" marker-end="url(#arr2)"/>
- </svg>
- <figcaption>The discovery contract: convention on disk, AST scan to enforce it, force-load to make runtime <code>__subclasses__()</code> equal the AST set, completeness test to prove the equality.</figcaption>
-</figure>
-
-<p>The convention test runs an AST scan over the package, picks out every class whose transitive base resolves to <code>PipelexError</code>, and asserts each file matches <code>exceptions.py</code> or <code>*_exceptions.py</code> (the root <code>pipelex/base_exceptions.py</code> is special-cased). A new class in the wrong file fails CI. A backstop test then walks <code>PipelexError.__subclasses__()</code> after the force-load helper runs and asserts the runtime set equals the AST set — so a class whose home module isn't reached by the rglob (or vice versa) fails CI too.</p>
-
-<p><strong>Net effect:</strong> adding a new error class is a one-step operation — write it in a properly-named module. No manifest to update, no allowlist to maintain.</p>
-
-<!-- ============================================================ -->
-<h2 id="tests"><span class="num">11</span>Tests we added</h2>
-<p class="section-sub">Pinning the behaviors this PR introduces. Mostly small, focused unit tests; one full-chain integration.</p>
-
-<table>
- <thead><tr><th>What it pins</th><th>File</th></tr></thead>
- <tbody>
- <tr>
- <td>STRICT message redaction is keyed on <code>caller_facing_message</code>, not <code>error_domain == INPUT</code>; <code>provider</code> / <code>model</code> / <code>provider_metadata</code> dropped under STRICT regardless of domain; curated <code>provider_metadata</code> subset preserved.</td>
- <td><code>tests/unit/pipelex/test_error_report_disclosure_mode.py</code></td>
- </tr>
- <tr>
- <td>Wrapper-wins enrichment — <code>caller_facing_message</code> never inherited from cause; <code>provider_metadata</code> never overwritten by cause when wrapper has its own.</td>
- <td><code>tests/unit/pipelex/test_error_report.py</code></td>
- </tr>
- <tr>
- <td><code>recover_error_report</code> on three paths: no embedded report → synthesizes <code>UnrecoverableWorkflowFailureError</code>; found-but-invalid dict → synthesizes the same with the validation-failure marker; whitespace-only message → treated as missing for fallback.</td>
- <td><code>tests/integration/pipelex/temporal/test_recover_error_report.py</code></td>
- </tr>
- <tr>
- <td><code>_message_from_exc</code> cycle guard (self-referential <code>__cause__</code> chain terminates) and <code>repr(exc)</code> fallback when every chain message is empty.</td>
- <td><code>tests/unit/pipelex/temporal/test_message_from_exc.py</code></td>
- </tr>
- <tr>
- <td><code>DeliveryActivityArg</code> round-trips through <code>model_validate_json(model_dump_json())</code> with a populated nested <code>error_report</code> — catches nested-model serialization regressions without a real worker.</td>
- <td><code>tests/unit/pipelex/temporal/test_delivery_activity_arg.py</code></td>
- </tr>
- <tr>
- <td><code>request_id</code> lands on Temporal log records via the bound adapter's <code>extra</code> dict; the unbound singleton omits the key when no id is set.</td>
- <td><code>tests/unit/pipelex/temporal/test_log_temporal_request_id.py</code></td>
- </tr>
- <tr>
- <td><code>WebhookTarget</code> with a reserved key in <code>payload</code> raises <code>ValidationError</code>; a clean payload passes; the error message names the offending keys.</td>
- <td><code>tests/unit/pipelex/pipe_run/test_webhook_target.py</code></td>
- </tr>
- <tr>
- <td>Error class location convention — every <code>PipelexError</code> subclass on disk matches the filename pattern; runtime <code>__subclasses__()</code> walk equals the AST set after force-load.</td>
- <td><code>tests/unit/pipelex/errors/test_error_class_location_convention.py</code></td>
- </tr>
- <tr>
- <td><code>type_uri</code> uniqueness — no two classes kebab to the same slug (defensive against the <code>LLMError</code> / <code>LlmError</code> casing collision).</td>
- <td><code>tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py</code></td>
- </tr>
- </tbody>
-</table>
-
-<!-- ============================================================ -->
-<h2 id="open"><span class="num">12</span>What's still open</h2>
-<p class="section-sub">Two items; both deliberately not in this PR.</p>
-
-<ul class="tight">
- <li>
- <strong>Webhook signing</strong> <span class="pill open">deferred</span> — the last unshipped stage of the API-readiness companion plan (Stage 5 / Item F). Cross-repo: the pipelex side and the API side must land in lockstep. Authoritative plan: <a href="../security/webhook-signing.md"><code>wip/security/webhook-signing.md</code></a>. Independent track, on its own schedule.
- </li>
- <li>
- <strong>Metadata-model long tail</strong> <span class="pill open">background</span> — a handful of <code>CogtError</code> subclasses still carry no class-level <code>error_category</code>; several non-inference <code>PipelexError</code> subclasses still depend on the <code>agent_output.py</code> fallback dicts for <code>hint</code> / <code>error_domain</code> rather than carrying class-level metadata. Tracked in <a href="track-metadata-model.md"><code>track-metadata-model.md</code></a>.
- </li>
-</ul>
-
-<div class="footer">
- <p>
- <span class="tag">plan-of-record</span> &nbsp;
- <a href="api-companion-revisions.md">wip/error-handling/api-companion-revisions.md</a>
- </p>
- <p>
- <span class="tag">post-/review follow-ups</span> &nbsp;
- <a href="../../TODOS.md">TODOS.md</a> (Phases 0-7, all landed)
- </p>
- <p>
- <span class="tag">prior briefing</span> &nbsp;
- <a href="error-handling.html">error-handling.html</a> (the in-process overhaul this PR builds on)
- </p>
- <p>
- <span class="tag">track docs</span> &nbsp;
- <a href="track-strict-disclosure-input-domain-gap.md">STRICT input-domain gap</a> ·
- <a href="track-webhook-payload-collision.md">Webhook payload collision</a> ·
- <a href="track-temporal-integration.md">Temporal integration</a> ·
- <a href="track-cli-delivery.md">CLI delivery</a>
- </p>
-</div>
-
-</div>
-</body>
-</html>
diff --git a/wip/error-handling/api-companion-revisions.md b/wip/error-handling/api-readiness.md
similarity index 90%
rename from wip/error-handling/api-companion-revisions.md
rename to wip/error-handling/api-readiness.md
index 97c8ccef6..c36d09151 100644
--- a/wip/error-handling/api-companion-revisions.md
+++ b/wip/error-handling/api-readiness.md
@@ -1,18 +1,18 @@
# API-companion revisions — what we are actually building vs. the original spec
-This doc captures the **deviations** the pipelex side is taking from the original spec in [`changes-for-api-early-draft.md`](changes-for-api-early-draft.md), and the **rationale** for each. Its primary audience is the `pipelex-api` agent: when you read [`changes-for-api-early-draft.md`](changes-for-api-early-draft.md) to plan how the API will consume the new pipelex primitives, read this first to know what surface to actually expect.
+This doc captures the **deviations** the pipelex side is taking from the original spec in `changes-for-api-early-draft.md`, and the **rationale** for each. Its primary audience is the `pipelex-api` agent: when you read `changes-for-api-early-draft.md` to plan how the API will consume the new pipelex primitives, read this first to know what surface to actually expect.
-The execution plan that implemented these revisions is the now-archived [`archive-todos.md`](archive-todos.md).
+The execution plan that implemented these revisions is now retired.
---
## Why this exists
-The original spec in [`changes-for-api-early-draft.md`](changes-for-api-early-draft.md) is **structurally sound** — every item identifies a real downstream pain and a real upstream primitive to fix it. But on close reading, several items push the very kind of consumer-side duplication, ad-hoc fallback logic, and optional-`None` plumbing that the spec itself argues against. A few items also introduce surface area earlier than it can be used, or hedge with "curate a subset, do the rest later" which leaves the codebase in an inconsistent state.
+The original spec in `changes-for-api-early-draft.md` is **structurally sound** — every item identifies a real downstream pain and a real upstream primitive to fix it. But on close reading, several items push the very kind of consumer-side duplication, ad-hoc fallback logic, and optional-`None` plumbing that the spec itself argues against. A few items also introduce surface area earlier than it can be used, or hedge with "curate a subset, do the rest later" which leaves the codebase in an inconsistent state.
The revisions below collapse and re-scope the original items (see the mapping table next), eliminate the consumer-side drift sources it introduced, remove the "caller hand-authors a fallback" duplication pattern, drop the speculative item as YAGNI, and stay strictly inside the repo's *no speculative future-proofing* rule (`CLAUDE.md`).
-**For the API agent:** wherever the surface here disagrees with [`changes-for-api-early-draft.md`](changes-for-api-early-draft.md), **this doc is authoritative**. The spec is kept for context but is no longer the contract.
+**For the API agent:** wherever the surface here disagrees with `changes-for-api-early-draft.md`, **this doc is authoritative**. The spec is kept for context but is no longer the contract.
---
@@ -70,7 +70,7 @@ Subclasses override `_declared_title` / `_declared_type_uri` only when the auto-
**Decision taken in planning.** Field lives on `JobMetadata`, not `PipeJob`. `JobMetadata` already carries `pipeline_run_id`, `user_id`, `session_id` and threads through every activity / workflow / submitter hop via `PipeJob.job_metadata` → `PipeRunArg`. Adding it on `PipeJob` (as the spec's literal example shows) would require copying it across into `JobMetadata` anyway to make it visible to the logger context.
-**Acceptance.** The API populates `JobMetadata.request_id` from its inbound `X-Request-ID` middleware once at submitter dispatch. From there `request_id` rides on `JobMetadata` across every Temporal hop and is threaded **explicitly** into the worker-side log calls — **not** via a `ContextVar`. A `ContextVar` is process-local and does not survive the Temporal activity/workflow serialization boundary, so it cannot carry a correlation id from the submitter process to a worker running in another process. The worker-side wiring landed in TODOS Phase 2 (2026-05-22): `WfPipeRun` / `WfPipeRouter` build a per-invocation `WorkflowLog` bound to `job_metadata.request_id` at entry, so every workflow log record they emit carries `request_id` in its `extra` dict. The current `webhook.payload["request_id"]` piggyback becomes obsolete.
+**Acceptance.** The API populates `JobMetadata.request_id` from its inbound `X-Request-ID` middleware once at submitter dispatch. From there `request_id` rides on `JobMetadata` across every Temporal hop and is threaded **explicitly** into the worker-side log calls — **not** via a `ContextVar`. A `ContextVar` is process-local and does not survive the Temporal activity/workflow serialization boundary, so it cannot carry a correlation id from the submitter process to a worker running in another process. The worker-side wiring is landed: `WfPipeRun` / `WfPipeRouter` build a per-invocation `WorkflowLog` bound to `job_metadata.request_id` at entry, so every workflow log record they emit carries `request_id` in its `extra` dict. The current `webhook.payload["request_id"]` piggyback becomes obsolete.
---
@@ -108,7 +108,7 @@ class ErrorReport:
- Every other report → `message` replaced with `"An internal error occurred."`, `user_action` dropped.
- **Kept in all modes** (stable identifiers): `error_type`, `error_domain`, `error_category`, `retryable`, `title`, `type_uri`.
-> **Gap closed (2026-05-22, TODOS Phase 1).** STRICT originally keyed its `message` passthrough on `error_domain == INPUT`, which is *inherited* up the `__cause__` chain — so a domain-less wrapper raised `from` an `INPUT` cause could leak its own (non-caller-facing) `message`, and `to_problem_document(STRICT)` could echo provider metadata for `INPUT` reports. The passthrough now keys on a per-class `caller_facing_message` flag (message *provenance*, not inherited classification) and provider metadata is stripped unconditionally. See [`track-strict-disclosure-input-domain-gap.md`](track-strict-disclosure-input-domain-gap.md).
+> **Why provenance, not inherited classification.** STRICT keys its `message` passthrough on the per-class `caller_facing_message` flag, *not* on `error_domain == INPUT`. `error_domain` is inherited up the `__cause__` chain, so keying on it would let a domain-less wrapper raised `from` an `INPUT` cause leak its own (non-caller-facing) `message`, and `to_problem_document(STRICT)` echo provider metadata for `INPUT` reports. Keying on message *provenance* avoids both; provider metadata is stripped unconditionally.
Both methods land in Stage 2 (was 2+4 in the spec). `to_problem_document` is callable from the API's Phase 1 directly.
@@ -195,19 +195,19 @@ These show up in multiple items above; collecting them here so the API agent can
## Current state
-> **For the API agent:** check this section first to know what's actually available. The full per-stage execution ledger is archived at [`archive-todos.md`](archive-todos.md).
+> **For the API agent:** check this section first to know what's actually available.
- [x] **Stage 1 — Foundations.** Items A + B.
- [x] **Stage 2 — Rendering primitives + total recovery.** Items C + D-1.
- [x] **Stage 3 — Async error pipe.** Item D-2 (the unblock for API Phase 4).
- [x] **Stage 4 — DX polish.** Item E.
-- [ ] **Stage 5 — Security tightening.** Item F (cross-repo, tracked at [`../security/webhook-signing.md`](../security/webhook-signing.md)).
+- [ ] **Stage 5 — Security tightening.** Item F (cross-repo, tracked at [`../webhook-signing.md`](../webhook-signing.md)).
-**Net to the API team:** the error-handling refactor on the pipelex side is landed — Stages 1-4 ship in PR #933 (PR #931 was the prior staging branch and was closed unmerged; the work was replayed and finalized on `feature/API-readiness-2`). API Phases 0/1/4/5 are unblocked. One thing remains on the pipelex side:
+**Net to the API team:** the error-handling refactor on the pipelex side is landed. API Phases 0/1/4/5 are unblocked. One thing remains on the pipelex side:
-- **Webhook signing (Stage 5 / Item F)** — the cross-repo security track at [`../security/webhook-signing.md`](../security/webhook-signing.md), independent of the rest of this plan, landing on its own schedule.
+- **Webhook signing (Stage 5 / Item F)** — the cross-repo security track at [`../webhook-signing.md`](../webhook-signing.md), independent of the rest of this plan, landing on its own schedule.
-The post-review follow-ups — a `/review` pass surfaced a small set of in-repo finalizations, sequenced in the archived [`archive-todos-api-readiness-2.md`](archive-todos-api-readiness-2.md) — all landed 2026-05-22 on `feature/API-readiness-2`: the STRICT-disclosure INPUT-domain leak (Phase 1), the `request_id` log wiring (§B; Phase 2), the webhook reserved-key collision (Phase 3), and the test-coverage backfill (Phase 4).
+The post-review follow-ups have all landed: the STRICT-disclosure INPUT-domain leak, the `request_id` log wiring (§B), the webhook reserved-key collision, and the test-coverage backfill.
### What landed in Stage 1
@@ -219,7 +219,7 @@ Available now:
- **`pascal_case_to_kebab`** (`pipelex/tools/misc/string_utils.py`) — acronym-aware kebab conversion (`"APIError" -> "api-error"`, `"V2APIError" -> "v2-api-error"`, `"OAuth2" -> "o-auth2"`).
- **`JobMetadata.request_id: str | None`** (`pipelex/pipeline/job_metadata.py`) — round-trips through `model_dump_json`, distinct from `ProviderErrorMetadata.request_id` (the provider-side request id) which keeps its name.
- **`pipeline_run_setup(..., request_id="...")`** (`pipelex/pipeline/pipeline_run_setup.py`) — kwarg threaded into the constructed `JobMetadata`. The current `webhook.payload["request_id"]` piggyback on the API side is now obsolete; consumers should set `request_id` at dispatch time and read it back off `arg.<path>.job_metadata.request_id`.
-- **`WorkflowLog` / `ActivityLog`** (`pipelex/temporal/log_temporal.py`) — every level (`verbose` / `debug` / `dev` / `info` / `warning` / `error` / `critical`) attaches the helper's bound `request_id` to the Temporal log record via `extra={"request_id": ...}`. Stage 1 shipped a per-method `request_id` kwarg here; TODOS Phase 2 (2026-05-22) replaced it with a per-invocation bound helper — `WfPipeRun` / `WfPipeRouter` build a `WorkflowLog` from `job_metadata.request_id` at entry, so worker log records now carry the `request_id` end to end.
+- **`WorkflowLog` / `ActivityLog`** (`pipelex/temporal/log_temporal.py`) — every level (`verbose` / `debug` / `dev` / `info` / `warning` / `error` / `critical`) attaches the helper's bound `request_id` to the Temporal log record via `extra={"request_id": ...}`. A per-invocation bound helper — `WfPipeRun` / `WfPipeRouter` build a `WorkflowLog` from `job_metadata.request_id` at entry — means worker log records carry the `request_id` end to end.
**Update — `type_uri()` is now a pure constant.** Stage 1 originally read the base URI through an `ErrorManager` singleton holding an `ErrorsConfig` — a workaround for the import cycle a lazy `get_config()` call inside the method would have created. That whole machinery (`ErrorManager`, `ErrorsConfig`, the `[errors_config]` config block) was later removed: the `type` URI is a stable identifier per RFC 7807, so making it configurable was over-engineering, and the mutable read leaked into Temporal workflow determinism (the base URI rode into workflow history via a synthesized `UnrecoverableWorkflowFailureError`). `type_uri()` now reads the `URLs.error_docs_base` constant directly — a pure function, no boot dependency, no static cycle. API consumers see no difference.
@@ -229,7 +229,7 @@ Available now:
Available now:
-- **`DisclosureMode` enum** (`pipelex/base_exceptions.py`) — `VERBOSE` / `STRICT`. The contract is pinned on the enum's own docstring: STRICT is a *classification-projection*, **not a path-leak shield**. STRICT always drops `provider` / `model` / `provider_metadata`, then redacts `message` by *provenance*: a report flagged `caller_facing_message` (set by error classes that author caller-facing copy — `PipelexInterpreterError` / `ValidateBundleError`) keeps its `message` and `user_action`; every other report drops `user_action` and replaces `message` with `"An internal error occurred."`, keeping the stable identifiers (`error_type` / `error_domain` / `error_category` / `retryable` / `title` / `type_uri`). The passthrough keys on the per-class flag, not `error_domain` — refined post-#931 from the original Stage 2 `error_domain == INPUT` keying (TODOS Phase 1; see the gap note above).
+- **`DisclosureMode` enum** (`pipelex/base_exceptions.py`) — `VERBOSE` / `STRICT`. The contract is pinned on the enum's own docstring: STRICT is a *classification-projection*, **not a path-leak shield**. STRICT always drops `provider` / `model` / `provider_metadata`, then redacts `message` by *provenance*: a report flagged `caller_facing_message` (set by error classes that author caller-facing copy — `PipelexInterpreterError` / `ValidateBundleError`) keeps its `message` and `user_action`; every other report drops `user_action` and replaces `message` with `"An internal error occurred."`, keeping the stable identifiers (`error_type` / `error_domain` / `error_category` / `retryable` / `title` / `type_uri`). The passthrough keys on the per-class flag, not `error_domain` (see the gap note above).
- **`ErrorReport.to_dict(disclosure_mode=DisclosureMode.VERBOSE)`** — projects the report through the disclosure mode. `VERBOSE` round-trips through `from_dict` exactly; `STRICT` is lossy by design. Default is `VERBOSE` so existing internal-trust callers (webhook payloads, Temporal details) are unaffected.
- **`ErrorReport.to_problem_document(*, instance=None, request_id=None, disclosure_mode=VERBOSE)`** — returns a plain dict in RFC 7807 shape. `type` ← `type_uri`, `title` ← `title`, `status` ← `http_status`, `detail` ← `message` (subject to disclosure-mode redaction). The pipelex-native classification fields ride as extension members; `type_uri` and `title` are mapped — NOT echoed — so the returned dict contains exactly one `title` key. `request_id` and `instance` ride as extensions only when the caller supplies them. The runtime stays HTTP-agnostic — no FastAPI/Starlette import.
- **`recover_error_report(exc: BaseException) -> ErrorReport`** (`pipelex/temporal/tprl/temporal_error.py`) — total. When the failure carries no embedded report, the function synthesizes `UnrecoverableWorkflowFailureError(_message_from_exc(exc)).to_error_report()`. A report dict that *is* found but fails `from_dict` validation is an internal contract bug — the activity bridge and the submitter share the schema within one deploy — and is also synthesized into the same `UnrecoverableWorkflowFailureError` fallback, with the recovered message plus an `[error report failed schema validation]` marker, so failure-webhook delivery stays intact (the workflow still fails afterwards, keeping the contract bug visible). `UnrecoverableWorkflowFailureError` lives in `pipelex/temporal/exceptions.py` next to `WorkflowExecutionError` etc., with `error_domain=RUNTIME` and `_declared_title="Unrecoverable workflow failure"`. Callers in `workflow_caller.py` (the three former `if error_report is not None` branches at `execute_workflow` / `execute_child_workflow` / `start_child_workflow`) now treat the return as always-usable.
diff --git a/wip/error-handling/architecture.md b/wip/error-handling/architecture.md
index 9223e49b2..6a7f29f59 100644
--- a/wip/error-handling/architecture.md
+++ b/wip/error-handling/architecture.md
@@ -116,22 +116,34 @@ Notes:
## Structured error reporting
-`ErrorReport` (`pipelex/base_exceptions.py`) is a frozen pydantic dataclass with `extra="forbid"`:
+`ErrorReport` (`pipelex/base_exceptions.py`) is a frozen `BaseModel` (`ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)`) — the single source of truth for all error serialization (CLI JSON output, agent output, Temporal error details). Frozen so a cause-enrichment pass rebuilds via `model_copy` rather than mutating an outer wrapper's identity in place.
```
ErrorReport
- error_type: str
- message: str
- error_category: str | None
- error_domain: str | None
- retryable: bool | None
- user_action: UserAction | None
- model: str | None
- provider: str | None
- provider_metadata: ProviderErrorMetadata | None
+ error_type: str
+ message: str
+ title: str
+ type_uri: str
+ error_category: str | None
+ error_domain: str | None
+ retryable: bool | None
+ user_action: UserAction | None
+ model: str | None
+ provider: str | None
+ provider_metadata: ProviderErrorMetadata | None
+ caller_facing_message: bool
```
-`to_dict()` drops `None` fields. `PipelexError.to_error_report()` returns `error_type`, `message`, and the class-level `error_domain`. `CogtError.to_error_report()` overrides to add `error_category`, `retryable` (derived from category), `user_action`, `provider_metadata`, and reads `model_handle` / `backend_name` when present on the instance. `to_error_report()` enriches from the `__cause__` chain, so a wrapper exception surfaces the inference metadata of the underlying `CogtError`.
+`title` / `type_uri` are the stable identity pair surfaced to consumers — every `PipelexError` populates them automatically via `PipelexError.title()` / `PipelexError.type_uri()` (auto-derived from the class name unless a subclass declares `_declared_title` / `_declared_type_uri`), so consumers never humanize or kebab-case a class name themselves.
+
+Serialization goes through `to_dict(disclosure_mode=DisclosureMode.VERBOSE)`, not a plain dump. `DisclosureMode` has two values:
+
+- `VERBOSE` — every populated (non-`None`) field; the strict inverse of `from_dict`, so it round-trips. Use on internal-trust boundaries (webhook payloads, internal RPCs) that need round-trip fidelity.
+- `STRICT` — a lossy projection for untrusted external surfaces: `provider` / `model` are always dropped, `provider_metadata` is reduced to a curated subset (`status_code`, `retry_after_seconds`), and unless the report sets `caller_facing_message` its `message` is replaced with a generic placeholder and `user_action` dropped — leaving only the stable identifiers. `caller_facing_message` flags reports whose `message` is genuinely caller-facing copy (e.g. a `.mthds` syntax error from `PipelexInterpreterError`), so STRICT keeps it. STRICT keys on message *provenance*, not on `error_domain` (which is inherited up the `__cause__` chain).
+
+`PipelexError.to_error_report()` returns `error_type`, `message`, `title`, `type_uri`, the class-level `error_domain`, `user_action`, and `caller_facing_message`. `CogtError.to_error_report()` overrides to add `error_category`, `retryable` (derived from category), `provider_metadata`, and reads `model_handle` / `backend_name` when present on the instance. `to_error_report()` enriches from the `__cause__` chain, so a wrapper exception surfaces the inference metadata of the underlying `CogtError` — but `title` / `type_uri` are *wrapper-wins* (enrichment never overwrites the outermost wrapper's identity).
+
+`error_category` carries an `InferenceErrorCategory` value (`pipelex/cogt/exceptions.py`). Only `TRANSIENT` is retryable; `CONFIGURATION` / `CONTENT` / `CAPACITY` / `AMBIGUOUS` / `UNKNOWN` are not. The `AMBIGUOUS` / `UNKNOWN` split is deliberate: `AMBIGUOUS` means the error type is known but the outcome is not (e.g. a connection dropped mid-request, so a non-idempotent operation may or may not have committed) — a blind retry is unsafe, so it is non-retryable by design; `UNKNOWN` means classification failed outright. Keeping them separate lets a non-idempotent worker (e.g. `azure_img_gen_worker.py`) pick `AMBIGUOUS` rather than the looser `UNKNOWN`.
See [track-metadata-model.md](track-metadata-model.md) for the remaining gap: `error_domain` is now a class-level attribute and inference errors fully self-describe, but a long tail of non-inference `PipelexError` subclasses still depend on the lookup dicts in `pipelex/cli/agent_cli/commands/agent_output.py` for their `hint` / `error_domain`.
diff --git a/wip/error-handling/archive-error-handling-2.md b/wip/error-handling/archive-error-handling-2.md
deleted file mode 100644
index ade48cd67..000000000
--- a/wip/error-handling/archive-error-handling-2.md
+++ /dev/null
@@ -1,765 +0,0 @@
-# TODOS — Error Handling, Phase 2: Resilience, Agent Delivery, Broad-Except Hygiene
-
-> **ARCHIVED — COMPLETE.** This Phase 2 sweep landed in full; kept for its running notes and checkpoint history. The authoritative current-state description lives in the `track-*.md` docs linked from [README.md](README.md).
-> **Branch:** `feature/Error-handling-2`
-> **Current-state reference:** [wip/error-handling/README.md](README.md) and the `track-*.md` docs it links.
-> **Prior sweep (completed, archived):** [wip/error-handling/archive-worker-classification-sweep.md](archive-worker-classification-sweep.md).
-> **Discipline:** every phase runs RED (failing test) → GREEN (minimal code to pass) → REFACTOR (clean up). Run `make agent-check` after every phase; `make agent-test` at each checkpoint.
-
----
-
-## ▶ Start here — cold-start status
-
-**This plan is built for cold-start handoff: one phase per session.** Phases 1, 1.5, 2, 3, 4, 5, 5.5, 6, 7 are **landed and committed** (through CHECKPOINT E — see the checkpoint blocks and Running Notes for what shipped). The plan was **revised 2026-05-15** to make the "resilience without Temporal" strategy explicit: Phase 5.5 (bounded fan-out concurrency) was added as a coupled pillar beside Phase 5, the HTTP-status mapping was folded into Phase 7, and two coherence decisions were flagged in the Phase 5 section.
-
-**Next phase: Phase 8.** (Priority 1 — resilience — and priority 2 — error delivery — are both complete; Phase 8 is the full-chain integration coverage that verifies the whole pipeline end-to-end.)
-
-**How to run a phase from a cold start:**
-
-1. Read this section, then "Why this plan exists", "Verification findings", "Sequencing", then the target phase section in full.
-2. Read the `track-*.md` doc the phase references (under `wip/error-handling/`) — that is the verified current-state ground.
-3. Skim the Running Notes at the bottom for prior per-phase decisions.
-4. Work the phase RED → GREEN → REFACTOR. Run `make agent-check` after each step.
-5. At the phase's CHECKPOINT: fill in the **Status** line, record hand-off context in Running Notes, commit, run `make agent-test`, then **stop**. The next phase is a fresh session.
-
-Each phase from 5 onward has its own checkpoint (C, C.5, D, E, FINAL) so no single session carries more than one phase of context.
-
----
-
-## Why this plan exists
-
-Three priorities drive the next phase of error-handling work, in priority order:
-
-1. **Resilience** — perfect the Temporal integration, while still working thoroughly and efficiently *without* Temporal. "Without Temporal" has **two pillars**: **bounded retry** of transient failures (Phase 5), and **bounded fan-out concurrency** (Phase 5.5) so a large workload — e.g. one pipe over 1,000 documents — degrades gracefully instead of overwhelming asyncio / memory / provider rate limits. Durable crash-survival is explicitly *not* attempted standalone — that is the Temporal pitch, and the standalone path should *advertise* it when limits are hit, not fake it.
-2. **Errors surface cleanly on every delivery surface** — the agent CLI emits plain markdown, clear and efficiently usable by agents, with JSON via an explicit option; and `ErrorReport` carries a documented `error_domain` → HTTP-status mapping so any downstream API (relay, back-office) renders it without reinventing the contract.
-3. **Never catch broad `except Exception`** except at CLI / API boundaries, per the repo's error-handling rules.
-
-The work is sequenced so the **shared foundation lands first**: both the Temporal bridge and the agent markdown renderer draw from `ErrorReport`, which today has no `error_domain` field. Building either consumer before `error_domain` lands means re-touching an incomplete schema. The broad-`except` sweep goes first of all because it is small, independent, and de-risks the classification that the other two priorities consume.
-
----
-
-## Verification findings (checked against the codebase before planning)
-
-These were verified directly — not taken on faith from prior notes.
-
-- **`error_domain` is genuinely missing.** `ErrorReport` (`pipelex/base_exceptions.py`) has no `error_domain` field; `PipelexError.to_error_report()` returns only `error_type` + `message`. `agent_error()` (`pipelex/cli/agent_cli/commands/agent_output.py`) sources `error_domain` *unconditionally* from the `AGENT_ERROR_DOMAINS` string dict — confirmed by the inline comment "error_domain: always from lookup dict". The string dicts (`AGENT_ERROR_HINTS`, `AGENT_ERROR_DOMAINS`, `RETRYABLE_ERROR_TYPES`) are class-name-keyed and drift-prone.
-- **The broad-`except` rule is not satisfied — but the prior framing overstated the danger.** There are broad `except Exception` sites across non-test code. Triaged:
- - **Allowed** — CLI command roots (`pipelex/cli/**`), dev CLI, agent CLI command handlers, async-task / workflow root handlers (`wf_pipe_router.py`, `pipe_run.py`, telemetry exporters). These are the documented exception to the rule.
- - **Broad but re-raises (observe-and-reraise)** — `pipe_abstract.py` (around lines 496, 605) and `llm_worker_abstract.py` (around lines 374, 411) catch to record a tracing/OTel span on the error path, then `raise`. They do **not** swallow. Spirit of the rule (unknown failures must surface) is honored.
- - **Best-effort cleanup** — `teardown()` in `google_llm_worker.py`, `google_img_gen_worker.py`, `gateway_extract_worker.py` (and the gateway search worker) swallow cleanup failures *by design* ("log but don't fail teardown"). These are **not** in the inference/classification path — the prior claim that they "swallow an SDK exception before it's classified" is inaccurate.
- - **Plugin / user-code trust boundary** — `pipe_func.py` (around line 189) wraps an error from a user-supplied registered function into `PipeRunError`. User code can raise anything; a broad catch here is defensible, like a CLI boundary.
- - **Genuinely narrowable** — `pipe_func.py` (around line 196) catches broadly around `working_memory.get_stuff()` when it should catch only the stuff-not-found exception. Other sites in business logic (`func_registry.py`, `working_memory_factory.py`, `model_lists.py`, `model_deck.py`, `output_renderer.py`, `structured_content_composer.py`, `delivery_executor.py`, and similar) need per-site triage.
- - **Conclusion:** Phase 1 is a correctness/hygiene sweep, not an emergency. The genuinely-wrong narrowing set is small; most sites are either allowed or legitimate-but-broad and need an explicit, justified marker rather than a rewrite.
-- **`InferenceErrorCategory.is_retryable` already exists** — retry *decisions* (the PipeRouter loop, the Temporal `from_message_exception` bridge) are unblocked today. Only the *payloads/renderers* need the completed `ErrorReport`.
-- **PipeRouter has no retry loop** — `PipeRouterProtocol.run()` (`pipelex/pipe_run/pipe_router_protocol.py`) catches only `PipeRunError`. Retry lives inside two gateway workers via `tenacity` — vibe-coded, inconsistent (`gateway_extract_worker` retries 500s/timeouts; `gateway_search_worker` retries almost nothing) and with an absurd `max_retries = 50` default.
-- **Fan-out is unbounded** — `PipeBatch` (`pipelex/pipe_controllers/batch/pipe_batch.py`) and `PipeParallel` (`pipelex/pipe_controllers/parallel/pipe_parallel.py`) both end in a plain `asyncio.gather(*tasks)` over *all* branches. A pipe run over N items spawns N coroutines, N deep-copied working memories, and N simultaneous inference calls at once. There is **no semaphore, no chunk size, no `max_concurrency` config** anywhere — the asymmetry is concrete: the Temporal path already has task-queue rate limiting, the standalone path has none.
-- **The Temporal bridge is name-based** — `TemporalError.from_message_exception()` (`pipelex/temporal/tprl/temporal_error.py`) uses the static `non_retryable_error_types` config list and never consults `InferenceErrorCategory.is_retryable`; `ApplicationError.details` is empty.
-
----
-
-## Sequencing
-
-```
-Phase 1 Broad-except hygiene sweep (priority 3 — independent, de-risks classification)
- └─ A
-Phase 1.5 Second-pass narrowing of catches (priority 3 — narrows what Phase 1 noqa'd, finishes the sweep)
- └─ CHECKPOINT A.5
-Phase 2 error_domain on the error model (metadata foundation, part 1)
-Phase 3 Class-level metadata on exceptions (metadata foundation, part 2)
-Phase 4 Retire agent-CLI string dicts (metadata foundation, part 3)
- └─ CHECKPOINT B — shared foundation landed
-Phase 5 PipeRouter retry loop (priority 1 — resilience without Temporal, pillar A)
- └─ CHECKPOINT C
-Phase 5.5 Bounded fan-out concurrency (priority 1 — resilience without Temporal, pillar B)
- └─ CHECKPOINT C.5 — resilience-without-Temporal complete
-Phase 6 Temporal bridge: category + details (priority 1 — the Temporal half)
- └─ CHECKPOINT D — resilience landed
-Phase 7 Error delivery: CLI markdown + HTTP mapping (priority 2)
- └─ CHECKPOINT E
-Phase 8 Full-chain integration coverage (testing — verifies the above end-to-end)
- └─ FINAL
-```
-
-Phases 5 and 5.5 are a **coupled pair** — both are "resilience without Temporal". Retry without bounded concurrency amplifies a thundering herd (retrying N failed calls = N more calls), so land both before exercising retry at scale; 5.5 may even precede 5. Phases 5–6 (resilience) and Phase 7 (delivery) touch disjoint files and could run in parallel; the order above keeps priority 1 ahead of priority 2 for a sequential single-session pass.
-
----
-
-## Phase 1 — Broad `except Exception` hygiene sweep
-
-**Goal:** every broad `except Exception` in non-test code is either narrowed to the specific exception(s) actually raised, or — where the broad catch is legitimate (allowed boundary, observe-and-reraise, best-effort cleanup, user-code boundary) — carries an explicit `# noqa: BLE001` with a one-line justification. After this phase, a new unjustified broad catch fails lint.
-
-### RED
-
-- [x] Confirm whether ruff's `BLE001` (`flake8-blind-except`) rule is enabled in the project's ruff config. If not, enable it. Run `make agent-check` and capture the full list of flagged sites — this is the RED baseline (the check fails).
-- [x] Triage every flagged non-test site into one of: **allowed boundary**, **observe-and-reraise**, **best-effort cleanup**, **user-code boundary**, **narrowable**. Record the triage table in Running Notes.
-
-### GREEN
-
-- [x] **Narrowable sites** — replace `except Exception` with the specific exception type(s) the call can raise. Start with `pipe_func.py` (the inner catch around `working_memory.get_stuff()` → the stuff-not-found exception). Work through the other business-logic sites identified in triage.
-- [x] **Observe-and-reraise sites** (`pipe_abstract.py`, `llm_worker_abstract.py` span-recording catches) — keep the broad catch (telemetry must fire on *every* failure) and add `# noqa: BLE001` with a comment stating it records a span then re-raises. Alternatively restructure with `try/except/else` so success vs error span-ending is explicit. Either way, nothing is swallowed. **Note:** ruff `BLE001` does not flag handlers that re-raise, so these sites need no `noqa` and were left untouched.
-- [x] **Best-effort cleanup sites** (`teardown()` async-client close paths) — narrow to the exceptions `aclose()` / `asyncio.run()` can actually raise (`RuntimeError`, connection/transport errors) where determinable; otherwise keep with `# noqa: BLE001` and the existing "log but don't fail teardown" comment.
-- [x] **User-code boundary** (`pipe_func.py` outer catch of the registered function) — keep with `# noqa: BLE001` and a comment that registered functions are user code and may raise anything; the wrap into `PipeRunError` is the boundary. **Note:** the outer catch re-raises as `PipeRunError`, so ruff does not flag it; no `noqa` needed.
-- [x] **Allowed boundaries** (CLI roots, async-task roots) — confirm each is genuinely at a root; add `# noqa: BLE001` where the rule flags them.
-- [x] Run `make agent-check` until clean.
-
-### REFACTOR
-
-- [x] Leave `BLE001` enabled as a permanent guard so future broad catches surface in lint.
-- [x] Spot-check that no narrowing changed observable behavior (a previously-caught exception that now propagates) — note any intentional behavior changes in the changelog.
-
-> ### STOP — CHECKPOINT A: Broad-except sweep landed ✅
->
-> Update checkboxes, commit, run `make agent-test`. The codebase now satisfies priority 3 and lint guards it. Next session resumes at Phase 1.5.
->
-> **Status:** landed. `make agent-check` clean (ruff + plxt + pyright + mypy). Triage table and decisions recorded in Running Notes below. Phase 1 was deliberately conservative — it parked 93 catches behind `# noqa: BLE001` so the lint guard could land fast; Phase 1.5 narrows the ones that can be narrowed.
->
-> **Hand-off context to record in Running Notes:** the triage table, any intentional behavior changes from narrowing, and whether `BLE001` was newly enabled or already on.
-
----
-
-## Phase 1.5 — Second-pass narrowing of the `noqa: BLE001` sites
-
-**Goal:** Phase 1 enabled `BLE001` and parked 93 broad catches behind `# noqa: BLE001` so the lint guard could land fast. That was deliberately conservative — several of those catches *can* be narrowed to the exception(s) the guarded call actually raises, and a few silently swallow. Phase 1.5 revisits every `noqa: BLE001` site, narrows each catch whose raised exceptions are knowable, restructures the silent-swallow sites, and leaves a `# noqa` only where the broad catch is genuinely correct (true CLI / agent command roots, telemetry that must never break the app, `__del__` at interpreter shutdown). Special attention to the `# TODO: wip - do not catch all exceptions` markers.
-
-After this phase every surviving `# noqa: BLE001` carries a one-line justification and represents a real, defended decision — not a deferral.
-
-### RED
-
-- [x] Re-list every `# noqa: BLE001` site (`grep -rn "noqa: BLE001" pipelex`). Confirm against the triage groups below.
-- [x] For each site to be narrowed, determine the exact exception set the guarded call can raise — read the callee, do not guess. Where a narrowed catch changes observable behavior (an exception that used to be swallowed now propagates), add or extend a unit test that pins the intended behavior *before* narrowing. List those tests here. — _No new pinning tests: every narrowing catches the same real exception set on the expected path; none is an intended behavior change. `make agent-test` (REFACTOR step) is the regression check._
-- [x] The genuinely-legitimate group (Group F) gets no code change — only a verification pass and a justification comment.
-
-### GREEN
-
-**Group A — `# TODO: wip - do not catch all exceptions` sites (do these first):**
-
-- [x] `delivery_executor.py:177` `_generate_graph_files` — narrow the catch around `generate_graph_outputs()` to the exception(s) graph generation raises; keep it best-effort (a graph failure must not fail delivery) but only for those types. — _ASSESS: kept broad + justified; deep mermaid/reactflow/jinja2 render tree._
-- [x] `delivery_executor.py:192` `_try_add_rendered_file` — narrow the catch around the render coroutine to the rendering exception(s). — _ASSESS: kept broad + justified; renders include the jinja2 stuff-viewer template._
-- [x] `delivery_executor.py:231` `_deliver_to_storage` — narrow the catch wrapping `storage_provider.store()` into `StorageDeliveryError` to the storage-provider exception type(s). (Re-raises, so not `noqa`'d — but the `# TODO` still applies.) — _Kept broad `except Exception` (re-raises as `StorageDeliveryError`; ruff exempts re-raising handlers); TODO replaced with a real comment._
-- [x] `delivery_executor.py:265` `_notify_webhook` — narrow the catch wrapping the webhook POST into `WebhookDeliveryError` to `httpx` request/transport errors (`httpx.HTTPStatusError` is already handled separately just above). — _Narrowed → `except httpx.RequestError`._
-- [x] `act_assemble_graph.py:52` — Temporal graph-assembly activity. If this is a true activity root, keep the broad catch but replace the `# TODO` with a real justification. Otherwise narrow to the graph-assembly / event-log exception(s). — _Kept broad + justified (true activity root)._
-- [x] Remove every `# TODO: wip - do not catch all exceptions` comment as its site is resolved.
-
-**Group B — defensive utilities (narrow to the real exception set):**
-
-- [x] `json_utils.py:384,444,497` — three identical `kajson.dumps()` fallbacks → narrow to `(TypeError, UnijsonEncoderError)` (kajson's encoder error). — _Narrowed; added `from kajson.exceptions import UnijsonEncoderError`._
-- [x] `class_utils.py:97` `are_classes_equivalent` — narrow the catch around `model_json_schema()` to pydantic's schema-generation error(s); the manual-field-comparison fallback stays. — _Narrowed → `(PydanticUserError, PydanticUndefinedAnnotation)`._
-- [x] `library_manager.py:1177` — narrow the catch around `structure_class.model_rebuild()` to pydantic rebuild errors (`NameError` / `PydanticUndefinedAnnotation`). — _Narrowed → `(NameError, PydanticUserError)`._
-- [x] `mistral_factory.py:257` `_clean_base64` — narrow to `(binascii.Error, ValueError)`. — _Narrowed → `except ValueError` (covers `binascii.Error`/`UnicodeDecodeError`, both `ValueError` subclasses)._
-- [x] `output_renderer.py:54,92` — narrow the catches around `render_stuff_spec()` to the rendering exception(s). — _ASSESS: kept broad + justified; `render_concept_representation` spans concept-structure resolution + pydantic schema generation over dynamic concepts._
-- [x] `dry_run.py:187` and `working_memory_factory.py:190` — narrow the mock-creation fallbacks to the factory / pydantic-validation exception(s) that `make_mock_content` / `TypedNamedStuffSpec.make_from_named` / `StuffFactory.make_stuff` actually raise. — _`dry_run.py:187` narrowed → `except ValidationError`. `working_memory_factory.py:190` ASSESS: kept broad + justified (polyfactory mock build over arbitrary dynamic classes)._
-- [x] `string_utils.py:58` (`f"{value}"` on arbitrary input) and `structured_content_composer.py:107` (diagnostic string builder) — assess: arbitrary `__str__` / introspection genuinely can raise anything. Either narrow to `(AttributeError, KeyError, TypeError)` or keep with an explicit justification. Record the decision in Running Notes. — _Both KEPT broad + justified (a partial narrow would be wrong: arbitrary `__str__`/`__format__` can raise any exception). `structured_content_composer.py:107` already had a justification — left unchanged._
-
-**Group C — teardown best-effort cleanup:**
-
-- [x] `gateway_extract_worker.py:76,78`, `google_img_gen_worker.py:86,89`, `google_llm_worker.py:103,106` — narrow the inner `asyncio.run(... aclose())` catch to `RuntimeError` plus the transport/connection errors `aclose()` raises; narrow or explicitly justify the outer teardown catch. Keep the "log but don't fail teardown" intent. — _ASSESS: kept broad `except Exception` + `# noqa: BLE001` + justification. First narrowed to `except RuntimeError`; code review flagged that the inner catch wraps `asyncio.run(aclose())` which genuinely runs `aclose()` — a non-enumerable failure surface over a duck-typed/deep connection pool — so narrowing defeats the "never fail teardown" contract. Reverted; matches Phase 1's "too broad to narrow safely" note._
-
-**Group D — CLI code that is not a true command root (narrow):**
-
-- [x] `init/ui/backends_ui.py:88` — narrow the file-read catch to `(TomlError, OSError)`. — _Narrowed._
-- [x] `show_cmd.py:160` — narrow the routing-profile load catch to the config / IO error(s). — _Narrowed → `except MarkupError`. NOTE: not a "load" catch — `routing_profile` is already loaded; the block prints Rich markup with interpolated config strings, so `rich.errors.MarkupError` is the real failure mode._
-- [x] `init/backends.py:137` (extension suggestion), `:168` (save terms), `:176` (disable gateway) — narrow each inner catch to what its called helper raises; the outer `:183` is a command-level boundary (Group F). — _`:137` → `except EOFError` (no-stdin `Confirm.ask`); `:168`/`:176` → `(OSError, TOMLKitError)`; `:183` kept broad + justified (command-level boundary)._
-- [x] `doctor_cmd.py` config-load helpers (`:103`, `:121`, `:320`) — narrow to `(TomlError, OSError)`. Triage the remaining `doctor_cmd.py` catches per-site: the doctor's job is "probe and report", so a broad catch around a whole probe is defensible — keep those with a justification, narrow the ones wrapping a single well-typed call. — _DONE — `:103`→`(PipelexCLIError, OSError)`, `:121`/`:320`→`(TomlError, OSError)`; the 9 probe / `--fix`-handler catches kept broad + justified. See Running Notes._
-
-**Group E — silent-swallow sites (restructure):**
-
-- [x] `wf_pipe_router.py:120,165` — `except Exception: pass` (`# noqa: BLE001, S110`). Silent swallow of trace / event-log cleanup. Narrow to the cleanup exception(s); if kept broad, at minimum log at debug level and drop the bare `pass`. — _DONE — both `try/except` blocks removed entirely: `event_log` is always a `BufferingEventLog` and its `close()` is a verified no-op (empty body), so the calls are now bare `event_log.close()`._
-
-**Group F — genuinely legitimate (verify + justify only, no narrowing):**
-
-- [x] Agent CLI command roots that convert to `agent_error()` (the documented CLI boundary) — confirm each is at the command root and `agent_error()` is `NoReturn`; keep `# noqa: BLE001`. — _DONE — 23 sites; `agent_error()` confirmed `-> NoReturn`; each got a justification comment._
-- [x] Dev CLI command roots (`_dev_cli.py` and `dev_cli/commands/*`) — keep. — _DONE — 10 sites in `_dev_cli.py` + 3 in `dev_cli/commands/*`; each got a justification comment._
-- [x] Telemetry (`exception_capture.py`, `telemetry_manager.py`, `posthog_span_exporter.py`) — telemetry must never break the app; keep with a justification comment. — _DONE — `exception_capture.py:84,91` and `telemetry_manager.py:199` got new comments; `telemetry_manager.py:209/217/225` and `posthog_span_exporter.py:368` already had one._
-- [x] `init/command.py:484`, `init/routing.py:156`, `init/backends.py:183` — command-level boundaries; keep. — _DONE — `init/command.py:484` and `init/routing.py:156` got new comments; `init/backends.py` (now `:185`) already had one._
-- [x] `ndjson_event_log.py:190` (`__del__`) — interpreter-shutdown safety net; keep. — _DONE — already carried a justification comment; verified._
-- [x] `pipe_run.py:41` — records `DeliveryStatus.FAILED`. Decide: narrow to `PipelexError` now, or defer to Phase 5 (the PipeRouter retry loop touches this path). Record the decision. — _DECISION: kept broad + justified. It is observe-and-reraise — the catch records `DeliveryStatus.FAILED` then re-raises the original exception unconditionally at method end. Narrowing to `PipelexError` would be wrong: a non-`PipelexError` failure would skip the FAILED-status recording. Not a deferral — a legitimate permanent boundary; Phase 5 can still restructure the path._
-- [x] Run `make agent-check` until clean after each group.
-
-### REFACTOR
-
-- [x] Every surviving `# noqa: BLE001` has a one-line justification comment on the same or an adjacent line. — _Verified: all 76 surviving sites carry a comment on the following line._
-- [x] No `# TODO: wip - do not catch all exceptions` comment remains anywhere. — _Verified: `grep` returns nothing._
-- [x] Run `make agent-test`. For each narrowed site, confirm no test fails because a previously-swallowed exception now propagates — if one does, that is either the intended fix or a sign the narrowing is wrong; resolve per-site. — _DONE — `make agent-test` passed; no narrowing regressed a test._
-- [x] Record in Running Notes: the final count of surviving `noqa: BLE001`, the per-site decisions for the "assess" sites (Group B last bullet, `doctor_cmd.py`, `pipe_run.py`), and any behavior change where an exception now propagates. — _DONE — see Running Notes below._
-
-> ### STOP — CHECKPOINT A.5: broad-except sweep fully narrowed
->
-> **Status (landed 2026-05-15):** COMPLETE — Groups A, B, C, D, E, F and REFACTOR all landed. `make agent-check` clean (ruff + plxt + pyright 0 errors + mypy 0 issues); `make agent-test` passed. 76 surviving `# noqa: BLE001`, each carrying a one-line justification; no `# TODO: wip` markers remain. Per-site decisions are in the "Phase 1.5" section of Running Notes below.
->
-> Commit. Every broad catch is now either narrowed or a defended, justified boundary. Next session resumes at Phase 2.
->
-> **Hand-off context to record in Running Notes:** the final `noqa: BLE001` count, the "assess"-site decisions, and any intentional behavior change from narrowing.
-
----
-
-## Phase 2 — `error_domain` on the error model
-
-**Goal:** `error_domain` becomes a first-class field on the exception hierarchy and on `ErrorReport`, so it no longer depends on the agent-CLI string dict. This is the schema change both downstream consumers (Temporal, CLI markdown) need before they are built.
-
-Reference: [track-metadata-model.md](track-metadata-model.md) followups 1.
-
-### RED
-
-- [x] Write `tests/unit/pipelex/exceptions/test_error_domain.py` asserting:
- - `ErrorDomain` is a `StrEnum` (imported from `pipelex.types`) with values `INPUT`, `CONFIG`, `RUNTIME`.
- - `PipelexError.to_error_report()` carries `error_domain` when the class declares one, and omits it (`None`) otherwise.
- - `ErrorReport.to_dict()` drops `error_domain` when `None` and includes it otherwise.
-
-### GREEN
-
-- [x] Add `ErrorDomain` `StrEnum`. — _Placed in `pipelex/base_exceptions.py` next to `PipelexError`/`ErrorReport` (mirrors `InferenceErrorCategory` living beside `CogtError` in `cogt/exceptions.py`)._
-- [x] Add an optional class-level `error_domain: ErrorDomain | None = None` attribute on `PipelexError`.
-- [x] Add `error_domain: str | None = None` to the `ErrorReport` frozen dataclass. — _Placed after `error_category`; both `ErrorReport` constructors use kwargs so field order is safe._
-- [x] Update `PipelexError.to_error_report()` to include `error_domain` from the class attribute.
-- [x] Update `CogtError.to_error_report()` so it forwards `error_domain` too (it overrides the base method).
-- [x] Run `make agent-check`. — _Clean (ruff + plxt + pyright 0 errors + mypy 0 issues)._
-
-### REFACTOR
-
-- [x] No change to consumers yet — `agent_error()` still reads its dict. Phase 4 flips the precedence. Keeping consumer changes out of this phase keeps the schema change reviewable in isolation.
-
----
-
-## Phase 3 — Class-level metadata on non-`CogtError` exceptions
-
-**Goal:** the key non-`CogtError` exceptions self-describe `error_domain` and `user_action` at the class level, and the uncategorized `CogtError` subclasses get their `error_category` defaults. After this phase, the metadata lives on the classes — the string dicts become removable in Phase 4.
-
-Reference: [track-metadata-model.md](track-metadata-model.md) followups 2–3.
-
-### RED
-
-- [x] Write `tests/unit/pipelex/exceptions/test_class_level_metadata.py` asserting each targeted exception's `to_error_report()` carries the expected `error_domain` and `user_action`:
- - `PipelineExecutionError`, `PipeExecutionError` (`pipelex/pipeline/exceptions.py`) → `error_domain=RUNTIME`.
- - `ValidateBundleError` (`pipelex/pipeline/validate_bundle.py`) → `error_domain=INPUT`.
- - `PipelexInterpreterError` (`pipelex/core/interpreter/exceptions.py`) → `error_domain=INPUT`.
- - `PipelexSetupError`, `PipelexConfigError` (`pipelex/base_exceptions.py`) → `error_domain=CONFIG`.
- - Service errors (`pipelex/system/pipelex_service/exceptions.py`) → `error_domain=CONFIG`.
-- [x] Add tests asserting the previously-uncategorized `CogtError` subclasses now report a non-`None` `error_category` (prompt-spec / prompt-template / prompt-parameter / prompt-image / prompt-document families → `CONTENT`).
-
-### GREEN
-
-- [x] Set class-level `error_domain` (and `user_action` where the track doc proposes concrete text) on the non-`CogtError` exceptions listed above. Use the user-action wording from [track-metadata-model.md](track-metadata-model.md) followup 2. — _`user_action` set on `PipelineExecutionError` (kind `UNKNOWN`) and `ValidateBundleError` (kind `CHANGE_INPUT`); `user_action` added as a class attr on `PipelexError` and forwarded by the base `to_error_report()`. Service-error domain set on the `PipelexServiceError` base + `PipelexServiceConfigValidationError` so all gateway/remote-config subclasses inherit it._
-- [x] Set `error_category` defaults on the uncategorized `CogtError` subclasses (the prompt-* families → `CONTENT`). Decide case-by-case for `ImageContentError`, `CostRegistryError`, `ReportingManagerError`, `SdkTypeError`, `ExtractOutputError`, `GeneratedImageError`, `LLMAssignmentError`, `InferenceBackendLibraryError` — record each decision in Running Notes. Leave the four per-instance "outcome" exceptions uncategorized. — _Case-by-case decisions in Running Notes._
-- [x] Run `make agent-check`. — _Clean. Updated `tests/unit/pipelex/test_base_exceptions.py` cold-import expectation (`PipelexConfigError` now reports `error_domain=config`)._
-
-### REFACTOR
-
-- [x] Scan for any other frequently-raised `PipelexError` subclass that obviously belongs to one domain. — _Deliberately stayed within the listed scope per "do not chase exhaustiveness"; the Phase 4 drift test guards the rest._
-
----
-
-## Phase 4 — Retire the agent-CLI string dicts + drift detection
-
-**Goal:** `agent_error()` reads class-level metadata first and falls back to the string dicts *only* for non-`PipelexError` built-ins (`FileNotFoundError`, `JSONDecodeError`, `ValidationError`, …) that cannot carry class attributes. A drift-detection test guards the remaining dict entries.
-
-Reference: [track-metadata-model.md](track-metadata-model.md) followups 4–6, [track-testing.md](track-testing.md) followup 2.
-
-### RED
-
-- [x] Write the drift test. — _Placed at `tests/unit/pipelex/cli/test_agent_output_drift.py` (flat, beside the existing `test_agent_output.py` — the `agent_cli/` subdir does not exist yet). Two sub-checks, both adapted from the plan against the actual dict contents:_
- - _**Stale-key check:** every dict key is either a live `PipelexError` subclass name (walked recursively after importing the defining modules) **or** a documented non-`PipelexError` key. The plan's literal "resolves to a real exception class" is false for ~6 keys (`ArgumentError`, `BinaryNotFoundError`, `GraphSpecParseError`, `BundleError`, `InitConfigError`, `UnknownCommandError`) which are synthetic `error_type` labels passed straight to `agent_error()` — no class exists. They (plus builtins / `mthds`-package / `ValueError`-subclass keys) are listed in a documented `_NON_PIPELEX_ERROR_KEYS` allowlist._
- - _**No-double-source check:** no `PipelexError` subclass that declares class-level `error_domain` / `user_action` also appears in `AGENT_ERROR_DOMAINS` / `AGENT_ERROR_HINTS`. This replaces the plan's "every `PipelexError` subclass declares metadata or appears in the dicts" — that literal check is infeasible (dozens of subclasses have neither, and Phase 3 REFACTOR explicitly says not to chase exhaustiveness). The no-double-source check is the achievable, valuable drift guard: it fails the build if a class gains metadata but its redundant dict entry is left behind._
-- [x] Write tests asserting `agent_error()` prefers `report.error_domain` over the dict when the cause is a `PipelexError`, and still falls back to the dict for a built-in exception type. — _Added to `test_agent_output.py`; `user_action`/hint precedence was already report-first and already covered._
-
-### GREEN
-
-- [x] In `agent_output.py`, change `agent_error()` so `error_domain` comes from `cause.to_error_report()` first; the dict is the fallback. — _`hint` was already report-first; only `error_domain` needed the change (new `report_domain` local)._
-- [x] Remove the redundant `AGENT_ERROR_HINTS` / `AGENT_ERROR_DOMAINS` entries. — _Removed only entries whose class now carries class-level metadata (the "now redundant" ones): 2 from `AGENT_ERROR_HINTS` (`ValidateBundleError`, `PipelineExecutionError`), 9 from `AGENT_ERROR_DOMAINS` (`ValidateBundleError`, `PipelexInterpreterError`, `PipelineExecutionError`, `PipeExecutionError`, + 5 service errors). PipelexError subclasses NOT migrated in Phase 3 keep their dict entries — removing them would be a non-redundant regression. See Running Notes._
-- [x] Run `make agent-check`. — _Clean. Updated `test_agent_output.py::test_agent_error_falls_back_to_lookup_when_report_fields_none` to key off `PipeExecutionError` (its hint survives) instead of the removed `ValidateBundleError`._
-
-### REFACTOR
-
-- [x] Add a short comment at the dict definitions. — _States the dicts are the fallback for error types that cannot self-describe (builtins, third-party, synthetic labels, un-migrated `PipelexError` subclasses) and that migrated classes must not appear — drift-test enforced. Not "built-ins-only": the dicts still hold un-migrated `PipelexError` subclass entries._
-- [x] Confirm `RETRYABLE_ERROR_TYPES` is still needed only for non-`CogtError` causes. — _Both entries (`RemoteConfigFetchError`, `PipeOperatorModelAvailabilityError`) are non-`CogtError` `PipelexError` subclasses whose `to_error_report()` carries no `retryable`; nothing to trim. Added a comment saying so._
-
-> ### STOP — CHECKPOINT B: Shared metadata foundation landed ✅
->
-> **Status (landed 2026-05-15):** COMPLETE — Phases 2, 3, 4 landed. `make agent-check` clean (ruff + plxt + pyright 0 errors + mypy 0 issues); `make agent-test` passed (full suite). `ErrorReport` now carries `error_domain`; `error_domain` + `user_action` live as class-level metadata on the key non-`CogtError` exceptions; the uncategorized prompt-* `CogtError` families carry `error_category=CONTENT`; `agent_error()` reads `error_domain` report-first; the redundant lookup-dict entries are removed and `test_agent_output_drift.py` guards the rest. Per-phase decisions are in the Running Notes "Phase 2 / 3 / 4" sections below. Next session resumes at Phase 5.
->
-> `ErrorReport` is now complete (`error_domain` included) and the metadata lives on the exception classes, drift-guarded. Both remaining priorities can now build on a stable schema.
->
-> **Hand-off context recorded in Running Notes:** the case-by-case `error_category` decisions from Phase 3, which dict entries survived (not built-ins-only — see the note), and why the drift test does not flag un-migrated `PipelexError` subclasses.
-
----
-
-## Phase 5 — PipeRouter retry loop (resilience without Temporal)
-
-**Goal:** `PipeRouter` retries `InferenceErrorCategory.TRANSIENT` failures with exponential backoff, driven by config, **enabled by default with a small retry budget**. This is the application-level resilience layer that must work when Temporal is absent. Retry logic moves out of the two gateway workers into the dispatch layer.
-
-Reference: [track-retry-and-resilience.md](track-retry-and-resilience.md) followups 1–6.
-
-**Two coherence decisions to settle in this phase (flagged 2026-05-15):**
-
-- **Default retry budget — do not default to 0.** Today the gateway workers retry up to 50× via `tenacity`. Phase 5's REFACTOR removes that. If the new router retry defaults to `max_transient_retries = 0`, the out-of-the-box behavior becomes *no retry at all* — strictly worse than today, and that is **not** "backward compatibility". The default must be a small sane number (recommended: **3**). `0` stays a valid value (explicit opt-out), just not the default.
-- **`CAPACITY` stays out of the fast retry loop.** `InferenceErrorCategory.is_retryable` is `False` for `CAPACITY` — keep it that way; do **not** overload `is_retryable`. A rate-limit (429) is "retryable" only on a much longer timescale and is really an *overwhelm* signal — Phase 5.5 owns it (back off on `provider_metadata.retry_after_seconds`, reduce concurrency, advise Temporal). The router loop retries `TRANSIENT` only.
-
-### RED
-
-- [x] Write `tests/unit/pipelex/pipe_run/test_pipe_router_retry.py` asserting:
- - A `CogtError` with `error_category=TRANSIENT` retries up to `max_transient_retries`, then re-raises the last error (cause chain preserved).
- - A `CogtError` with `CONFIGURATION` / `CONTENT` / `CAPACITY` / `UNKNOWN` fails immediately (no retry).
- - A `PipeRunError` (non-`CogtError`) is unaffected and still wraps as `PipeRouterError`.
- - `max_transient_retries = 0` disables retry entirely (explicit opt-out — but it is *not* the default; see the coherence decisions above).
- - Backoff wait increases each attempt; the retry log line includes attempt number, wait duration, and error category.
- - `_before_run()` runs once before the loop; `_after_failing_run()` runs once after retries are exhausted or on a non-retryable error.
-
-### GREEN
-
-- [x] Add retry config fields to `PipelineExecutionConfig` (`pipelex/system/configuration/configs.py`): `max_transient_retries: int`, `transient_retry_base_wait: float`, `transient_retry_max_wait: float`, `transient_retry_backoff_multiplier: float`. Per project rules: no defaults in the class body — put defaults in `pipelex/pipelex.toml` with `max_transient_retries = 3` (a small sane budget — see the coherence decision above; **not** `0`); add commented-out overrides in `.pipelex/pipelex.toml`. — _Done; commented-out overrides also added to `pipelex/kit/configs/pipelex.toml` (kept in sync with `.pipelex/`)._
-- [x] Add the retry loop to `PipeRouterProtocol.run()` (`pipelex/pipe_run/pipe_router_protocol.py`): wrap `_run_pipe_job()`, catch `CogtError` where `error_category is not None and error_category.is_retryable`, sleep with exponential backoff, continue; re-raise on exhaustion; non-retryable categories fail immediately; the existing `PipeRunError` path is unchanged.
-- [x] Thread the retry config via `get_config()` inside the protocol (Option B in the track doc) — consistent with how `pipeline_execution_config` is already accessed. — _DEVIATION: Option B as literally written is impossible. `pipelex.config` imports `pipelex.hub`, and `hub` type-imports `PipeRouterProtocol` — any `config` import in `pipe_router_protocol.py` (module **or** function scope) trips pyright's `reportImportCycles`. Resolved with a hybrid: a dependency-free `TransientRetrySettings` model (`pipelex/pipe_run/transient_retry.py`) the protocol carries as an instance attribute, populated from `get_config()` by each concrete router at construction via `make_transient_retry_settings()` in `pipe_router.py`. See Running Notes._
-- [x] Run `make tb` (boot sequence — verifies the config model and the three `pipelex.toml` files agree). Run `make agent-check`.
-
-### REFACTOR
-
-- [x] Remove `tenacity` retry from the gateway extract and search workers (`_make_retryer`, `_is_retryable_portkey_error`, `_log_retry`, the `async for attempt` wrapper). Confirm errors still propagate with the correct `InferenceErrorCategory` on first failure. — _Done. The now-dead `response is None` defensive branches (and `attempt_number` tracking) were also removed._
-- [x] Remove `TenacityConfig` from `pipelex/cogt/config_cogt.py` and its `pipelex.toml` entries, **only if** nothing else uses it (`pipelex/plugins/fal/fal_poller.py` still uses tenacity for polling and `log_retry` from `tenacity_utils.py` — verify before removing the `tenacity` dependency or `tenacity_utils.py`). — _`TenacityConfig` removed. `tenacity` dependency and `tenacity_utils.py` KEPT — `fal_poller.py` and `remote_config_fetcher.py` still use them. See Running Notes for the breaking-change note on stale user configs._
-- [x] Add a one-line code comment at the `instructor` `max_retries` call sites noting it retries schema-validation, not transport — out of scope for router retry. — _Done in the four LLM workers (google, anthropic, openai completions, openai responses)._
-
-> ### STOP — CHECKPOINT C: PipeRouter retry loop landed
->
-> Update checkboxes, run `make agent-check` and `make agent-test`, commit. Then **stop — Phase 5.5 is a fresh session.**
->
-> **Status (landed 2026-05-15):** COMPLETE — RED, GREEN, REFACTOR all landed. `make agent-check` clean (ruff + plxt + pyright 0 errors + mypy 0 issues); `make tb` passes; `make agent-test` passed. Per-decision detail in the "Phase 5" section of Running Notes below.
->
-> **Hand-off context to record in Running Notes:** the two coherence decisions as actually settled (final default `max_transient_retries`; `CAPACITY` disposition); whether removing the gateway-worker `tenacity` changed any timing-sensitive test; the final disposition of the `tenacity` dependency, `TenacityConfig`, and `tenacity_utils.py`; the retry config fields added and their `pipelex.toml` defaults.
->
-> **Next session resumes at Phase 5.5** — re-read the "Start here" section, "Why this plan exists", the Phase 5.5 section, and [track-retry-and-resilience.md](track-retry-and-resilience.md).
-
----
-
-## Phase 5.5 — Bounded fan-out concurrency (resilience without Temporal, pillar B)
-
-**Goal:** `PipeBatch` fans out over its N items in **bounded chunks** driven by a `max_concurrency` config, so a large workload — one pipe over 1,000 documents — no longer spawns N coroutines, N deep-copied working memories, and N simultaneous inference calls at once. This is a *basic, honest* backpressure effort with plain Python — **not** durable execution. When the workload is large or `CAPACITY` errors persist, the failure path surfaces a clear `user_action` pointing at the Temporal track as the durable, rate-limited answer. Pillar B of "resilience without Temporal"; coupled with Phase 5 (see Sequencing).
-
-Reference: [track-retry-and-resilience.md](track-retry-and-resilience.md) — this is net-new ground the track doc does not yet cover; capture the design back into the track doc as it lands.
-
-### RED
-
-- [x] Write `tests/unit/pipelex/pipe_controllers/test_pipe_batch_concurrency.py` asserting:
- - With `max_concurrency = K`, no more than `K` branch coroutines are ever in flight at once (use a probe that increments/decrements a counter on entry/exit and records the peak).
- - All N items still complete and results preserve input order.
- - `max_concurrency` unset / very large → behaves as today (single `asyncio.gather`).
- - A failure in one branch still propagates (define and pin chunk-failure semantics — first error wins; in-flight branches in the failing chunk are awaited or cancelled deterministically).
- - _DEVIATION: the bounded fan-out was extracted into a generic, isolated helper `gather_bounded` (`pipelex/tools/misc/async_utils.py`) that `PipeBatch` calls — far more unit-testable than `_live_run_controller_pipe`, which needs heavy fixture setup. The test therefore lives at `tests/unit/pipelex/tools/misc/test_async_utils.py` (beside what it tests) rather than the plan's `pipe_controllers/test_pipe_batch_concurrency.py`. All four RED assertions map onto the helper. `PipeBatch`'s own use of it is covered by the existing `tests/integration/pipelex/pipes/` batch tests._
-
-### GREEN
-
-- [x] Add a `max_concurrency: int` config field (decide placement: `PipelineExecutionConfig` next to the retry fields, or a small dedicated `ConcurrencyConfig` — record the call). Per project rules: no default in the class body — default in `pipelex/pipelex.toml` (recommended: a sane modest value, **not** unbounded), commented-out override in `.pipelex/pipelex.toml`. — _Placed on `PipelineExecutionConfig` next to the retry fields (same "resilience without Temporal" concern — no separate `ConcurrencyConfig`). Typed `Annotated[int, Field(ge=1)] | Literal["unbounded"]` — an explicit literal disables the bound rather than a magic `0`. Default `max_concurrency = 8` in `pipelex/pipelex.toml`; commented-out overrides in `.pipelex/pipelex.toml` and `pipelex/kit/configs/pipelex.toml`._
-- [x] Implement bounded fan-out in `PipeBatch` (`pipelex/pipe_controllers/batch/pipe_batch.py`). Prefer **chunked execution** (process items in chunks of K) over a bare `asyncio.Semaphore`: chunking bounds *memory* — only K working-memory deep-copies are materialized at once — which a semaphore alone does not. — _Done via the `gather_bounded` helper, which takes per-branch *factories* (not coroutines) and invokes them chunk-by-chunk, so each deep-copied working memory is materialized only when its chunk runs. `PipeBatch` builds one factory per branch; item-stuff creation + graph-tracer registration stay in an upfront loop (cheap, sync)._
-- [x] Decide whether `PipeParallel` also needs a bound. It fans over a *fixed, pipe-defined* branch set (usually small), not a data-driven N — the scaling risk is `PipeBatch`. Record the decision in Running Notes. — _DECISION: not bounded. `PipeParallel` fans over a fixed, pipe-defined branch set, not a data-driven N; left as a plain `asyncio.gather`._
-- [x] Run `make tb` (boot sequence — config model ↔ `pipelex.toml` agreement). Run `make agent-check`. — _`make tb` passes; `make agent-check` clean (ruff + plxt + pyright 0 errors + mypy 0 issues)._
-
-### REFACTOR
-
-- [x] Graceful-degradation messaging: when a `PipeBatch` workload exceeds a soft threshold, or when `CAPACITY` errors recur, attach an advisory `user_action` / log line naming the **Temporal track** as the durable, rate-limited path. Advisory, never fatal — "we made a basic effort; here is the stronger solution." — _Done as a `log.warning` (advisory, never fatal): when a `PipeBatch` fans out over more than `LARGE_BATCH_ADVISORY_THRESHOLD` (100) items, it logs once, naming the Temporal track and the active `max_concurrency`. A soft item-count threshold was chosen over `CAPACITY`-recurrence detection — the latter needs cross-branch error aggregation that is out of proportion for "basic, honest backpressure"; the Phase 5 retry loop + this advisory cover the honest standalone story._
-- [x] Record in Running Notes how this composes with Phase 5: bounded concurrency *reduces* how often `CAPACITY` is hit; the router retry loop handles the residual `TRANSIENT`; persistent `CAPACITY` is the honest "go Temporal" boundary. — _Recorded below._
-
-> ### STOP — CHECKPOINT C.5: Bounded fan-out concurrency landed — resilience-without-Temporal complete
->
-> Update checkboxes, run `make tb`, `make agent-check`, and `make agent-test`, commit. Then **stop — Phase 6 is a fresh session.**
->
-> **Status (landed 2026-05-16):** COMPLETE — RED, GREEN, REFACTOR all landed. `make agent-check` clean (ruff + plxt + pyright 0 errors + mypy 0 issues); `make tb` passes; targeted `pipe_controllers` / `tools` / `pipes` suites pass; `make agent-test` passed. Per-decision detail in the "Phase 5.5" section of Running Notes below.
->
-> Both standalone-resilience pillars now stand: Pipelex retries transients (Phase 5) and bounds its fan-out (Phase 5.5) without Temporal.
->
-> **Hand-off context to record in Running Notes:** the `PipeParallel` bounding decision; the chosen `max_concurrency` default and config placement; the chunk-failure semantics; the graceful-degradation messaging; how Phases 5 + 5.5 compose.
->
-> **Next session resumes at Phase 6** — re-read the "Start here" section, the Phase 6 section, and [track-temporal-integration.md](track-temporal-integration.md).
-
----
-
-## Phase 6 — Temporal bridge: category-aware retry + details payload
-
-**Goal:** Temporal's retry decision flows from `InferenceErrorCategory.is_retryable` (the same signal as the PipeRouter loop), and `ApplicationError.details` carries the full `ErrorReport` across the activity → workflow boundary.
-
-Reference: [track-temporal-integration.md](track-temporal-integration.md) followups 1–4.
-
-### RED
-
-- [x] Write `tests/unit/pipelex/temporal/test_temporal_error_bridge.py` asserting:
- - `from_message_exception()` on a `CogtError` with `TRANSIENT` produces `non_retryable=False`.
- - …with `CONFIGURATION` / `CONTENT` / `CAPACITY` / `UNKNOWN` produces `non_retryable=True`.
- - …on a non-`CogtError` `PipelexError` falls back to the `non_retryable_error_types` name list.
- - …on a `CogtError` with `error_category=None` falls back to the name list (no crash).
- - `ApplicationError.details` round-trips through Temporal serialization with all `ErrorReport` fields intact.
- - Log severity (critical / error) matches the retry decision on both the `from_message_exception` and `from_app_error` paths.
-
-### GREEN
-
-- [x] In `pipelex/temporal/tprl/temporal_error.py`, `from_message_exception()`: when `exc` is a `CogtError` with a non-`None` `error_category`, derive retryability from `error_category.is_retryable` and set `non_retryable = not is_retryable` on the `ApplicationError`. When the category is `None`, keep the existing `non_retryable_error_types` lookup.
-- [x] Pack `exc.to_error_report().to_dict()` into `ApplicationError.details`. `from_app_error()` extracts the details payload and surfaces it back as fields on the resulting `TemporalError` so the structured data survives the round-trip.
-- [x] Update the docstrings of `RetryPolicyConfig.non_retryable_error_types` and `non_retryable_error_types_extra` (`pipelex/temporal/config_temporal.py`) to state that the name list is a *fallback* for category-less exceptions and an override mechanism — category decides retryability for `CogtError`.
-- [x] Run `make agent-check`.
-
-### REFACTOR
-
-- [x] Check the in-process PipeRouter retry (Phase 5) and the Temporal retry agree on what "transient" means — both consult `is_retryable`. Note in Running Notes how the two layers compose (Temporal sees a non-retryable error only after the router exhausted its retries, or for non-`TRANSIENT` categories).
-
-> ### STOP — CHECKPOINT D: Resilience landed (Temporal half)
->
-> Update checkboxes, run `make agent-check` and `make agent-test`, commit. Run the Temporal integration tests per `_tprl/CLAUDE.md` (`--temporal-server` options). Then **stop — Phase 7 is a fresh session.**
->
-> **Status (landed 2026-05-16):** COMPLETE — RED, GREEN, REFACTOR all landed. `make agent-check` clean (ruff + plxt + pyright 0 errors + mypy 0 issues); `make agent-test` passed (full suite). Temporal integration suite (`tests/integration/pipelex/temporal/`, in-process server) passed — 94 passed, 4 xpassed (pre-existing xdist-flaky tests that happened to pass; not a regression), 0 failures, no timing-sensitive regression. Per-decision detail in the "Phase 6" section of Running Notes below.
->
-> Priority 1 is complete: standalone, Pipelex retries transients and bounds fan-out concurrency; across the Temporal boundary, retry flows from the same `is_retryable` signal and `ErrorReport` round-trips in `ApplicationError.details`.
->
-> **Hand-off context:** the in-process retry (Phase 5) and Temporal retry compose as nested layers agreeing on `is_retryable` — see "How Phases 5 and 6 compose" in Running Notes. The Temporal integration suite surfaced no timing-sensitive regression.
->
-> **Next session resumes at Phase 7** — re-read the "Start here" section, the Phase 7 section, and [track-cli-delivery.md](track-cli-delivery.md).
-
----
-
-## Phase 7 — Error delivery: agent CLI markdown + HTTP-status mapping
-
-**Goal (priority 2 — errors surface cleanly on every delivery surface):**
-
-- **CLI:** the agent CLI emits plain markdown by default for `run` / `validate` / `init` and for the error path; JSON is available via `--format json`. The eleven near-identical Rich handlers in `error_handlers.py` collapse onto one panel helper.
-- **HTTP:** `pipelex` itself is a library — there is no API server inside the package (verified: zero `fastapi` / `HTTPException` usage). But the HTTP API repos (`pipelex-relay`, `pipelex-back-office`) need to render `ErrorReport` as an HTTP response, and today the `error_domain` → status mapping is implicit and gets reinvented per repo. This phase puts a **documented, authoritative `error_domain` → HTTP-status mapping in the library** so the downstream FastAPI exception handler is a trivial one-screen adapter. The library stays HTTP-agnostic (no FastAPI dependency) — it only owns the mapping table.
-
-Reference: [track-cli-delivery.md](track-cli-delivery.md) followups 1–6.
-
-### RED
-
-- [x] Write tests under `tests/unit/pipelex/cli/agent_cli/` (or integration where the CLI harness fits) asserting:
- - `run` / `validate` with no `--format` produce markdown to stdout.
- - `run --format json` / `validate --format json` produce valid JSON to stdout.
- - An error with no `--format` produces markdown to stderr; with `--format json`, JSON to stderr.
- - The `inputs` command is unaffected (always JSON per the `agent_cli/CLAUDE.md` contract).
- - _Landed as `test_run_format.py`, `test_validate_format.py`, `test_agent_error_format.py`, `test_inputs_format_unaffected.py` under `tests/unit/pipelex/cli/agent_cli/` + an autouse `conftest.py` resetting the format ContextVar. The error-format assertions live in `test_agent_error_format.py` (markdown vs JSON dispatch + `agent_error_markdown` rendering); the `inputs`-unaffected check is a reflection test that no `inputs` subcommand has an `output_format` param._
-- [x] Write `tests/unit/pipelex/test_error_http_status.py` asserting the `error_domain` → HTTP-status mapping: `INPUT` → 422 (unprocessable input the caller can fix), `CONFIG` → 500 (server-side environment/config problem), `RUNTIME` → 500; `error_domain = None` → 500. And: when `provider_metadata.status_code` is a 429, the mapping yields 429 with `retry_after_seconds` exposed for a `Retry-After` header (provider-status passthrough takes precedence over the domain default). — _Done; covers both `error_domain_to_http_status()` (pure function) and `ErrorReport.http_status` (property, with the 429 passthrough)._
-
-### GREEN
-
-- [x] Add `error_domain_to_http_status()` (and/or an `ErrorReport.http_status` property) — recommended location `pipelex/base_exceptions.py`, next to `ErrorDomain` / `ErrorReport`. Pure mapping, no `fastapi` import. It considers `provider_metadata.status_code` (429 passthrough) first, then `error_domain`, then a 500 default. — _Both added: `error_domain_to_http_status(ErrorDomain | None) -> int` is the pure domain table (exhaustive `match`, no `case _`); `ErrorReport.http_status` is the property that layers the 429 passthrough on top._
-- [x] Add `agent_error_markdown(message, error_type, cause, **extra)` to `agent_output.py` — markdown to stderr (error-type heading, message body, hint as a tip callout, `error_source` as a code block), still `raise typer.Exit(1)`. — _Done; shares `_assemble_error_payload()` with the JSON path, renders via `_render_error_markdown()` (heading / message / `> 💡` hint callout / `## Details` / `## Error source` code block)._
-- [x] Introduce a format-aware error dispatch (explicit `format` argument or a `ContextVar`). Keep JSON as the default when format is unknown (errors during init, before the format option is parsed — see `agent_cli_factory.py`). — _DEVIATION: a `ContextVar` (`_agent_cli_output_format`, default `JSON`) — and `agent_error()` itself is the dispatcher (JSON vs markdown) rather than a separate `agent_error_dispatch`. This is cleaner: all ~80 existing `agent_error(...)` call sites follow `--format` for free with zero edits; a command opts in via `set_agent_cli_output_format()`. JSON stays the default for anything before a command opts in (app callback, unknown-command, factory init errors). See Running Notes._
-- [x] Add `--format markdown|json` to `run`, `validate`, `init` (`match/case` on `CliOutputFormat`, default `MARKDOWN`), mirroring `models_cmd.py`. Add the markdown renderers: `_format_run_markdown`, `_format_validate_markdown`, and the `init` confirmation. Files: `commands/run/{pipe,bundle,method}_cmd.py`, `commands/validate/{pipe,bundle,method}_cmd.py`, `commands/init_cmd.py`. — _Done. Renderers: `format_run_markdown` (`run/_output_helpers.py`), `format_validate_markdown` (new `validate/_output_helpers.py`), `_format_init_markdown` (`init_cmd.py`). Success path uses a shared `agent_success_formatted(result, markdown_renderer)` helper. `models`/`check-model`/`doctor` also wired to `set_agent_cli_output_format()` so their errors follow `--format` too. NAMING CONFLICT resolved: `validate bundle`'s graph-format option was `--format`/`-f` — renamed to `--graph-format`/`-f` so `--format` is uniformly the output-format flag (breaking CLI change, per repo no-back-compat policy)._
-- [x] Run `make agent-check`. — _Clean (ruff + plxt + pyright 0 errors + mypy 0 issues)._
-
-### REFACTOR
-
-- [x] Extract `display_error_panel(console, *, title, fields, error_message, tip, links)` in `pipelex/cli/error_handlers.py`; rewrite each `handle_*` to build its field list and call the helper. Exception-specific logic stays in the handler; the panel shape lives in one place. — _`display_error_panel` extracted (banner / aligned fields / error message / 💡 tip / dimmed links). Applied to the three genuinely field-shaped handlers: `handle_model_choice_error`, `handle_model_availability_error`, `handle_model_deck_preset_error`. DEVIATION: the plan's "each `handle_*`" overstated uniformity — the gateway / telemetry / inference / validate-bundle handlers have prose / structured-detail bodies that are not a `(label, value)` field list (the track doc itself notes the gateway handlers have prose bodies); they keep custom bodies. Snapshot coverage is Phase 8._
-- [x] Update `pipelex/cli/agent_cli/CLAUDE.md`: markdown is the default for `run` / `validate` / `init` / `models` / `doctor` / `check-model`; `--format json` available on all of them; errors respect the same option; document each command's markdown structure. — _Done — new "Output format" section (default markdown, JSON-only commands, ContextVar dispatch, per-command markdown structure); commands table + Key Patterns updated._
-- [x] Document the `error_domain` → HTTP-status mapping where a downstream API author will find it (a docstring on the helper plus a short note in `wip/error-handling/track-cli-delivery.md` or `architecture.md`), including the 429 / `Retry-After` passthrough. The mapping table is authoritative in the library; API repos call the helper, they do not redefine it. — _Done — full docstrings on `error_domain_to_http_status()` and `ErrorReport.http_status`, plus a "HTTP-status mapping (authoritative)" section in `track-cli-delivery.md`._
-
-> ### STOP — CHECKPOINT E: Error delivery landed
->
-> Update checkboxes, run `make agent-check` and `make agent-test`, commit. Then **stop — Phase 8 is a fresh session.**
->
-> **Status (landed 2026-05-16):** COMPLETE — RED, GREEN, REFACTOR all landed. `make agent-check` clean (ruff + plxt + pyright 0 errors + mypy 0 issues); `make agent-test` passed (full suite). The agent CLI now emits markdown by default for `run` / `validate` / `init` (and `models` / `check-model` / `doctor` already did), with `--format json` for the structured payload; errors follow the same option via a per-invocation `ContextVar`. `ErrorReport` carries a documented, authoritative `error_domain` → HTTP-status mapping (`error_domain_to_http_status()` + `ErrorReport.http_status`, 429 passthrough). Per-decision detail in the "Phase 7" section of Running Notes below.
->
-> Priority 2 is complete: the agent CLI emits markdown by default with `--format json`, and `ErrorReport` carries a documented `error_domain` → HTTP-status mapping.
->
-> **Hand-off context to record in Running Notes:** the final HTTP-status mapping table; where the panel helper landed; any Rich-rendering change from the `error_handlers.py` refactor.
->
-> **Next session resumes at Phase 8** — re-read the "Start here" section, the Phase 8 section, and [track-testing.md](track-testing.md).
-
----
-
-## Phase 8 — Full-chain integration coverage
-
-**Goal:** prove the whole pipeline — worker error → pipe operators → `PipelineExecutionError` → `agent_error()` → stderr — produces correct structured output, in both JSON and markdown. This catches wiring regressions no per-worker test can.
-
-Reference: [track-testing.md](track-testing.md) followups 1 and 3.
-
-### RED
-
-- [x] Add a full-chain test under `tests/integration/pipelex/cli/agent_cli/`: a minimal pipeline where one pipe fails with a deterministic worker error (mocked `LLMCompletionError`, `error_category=TRANSIENT`, model + provider set). Run `pipelex-agent run` via the CLI harness, capture stderr. — _Landed as `test_run_error_chain.py` (`TestRunErrorChain`). Invokes the real `run_pipe_cmd` against a minimal `error_chain.mthds` bundle (one `PipeLLM` pipe `greet`); `ContentGenerator.make_llm_text` is mocked to raise `LLMCompletionError(TRANSIENT)` with duck-typed `model_handle`/`backend_name`. The command's own boot/teardown is stubbed (the module-scoped conftest already boots Pipelex); every layer below the CLI — PipeLLM → PipeRouter → PipelexRunner → `PipelineExecutionError` — runs for real._
- - **JSON path:** assert the JSON has `error: true`, `error_type`, `message`, `error_category: "transient"`, `retryable: true`, `error_domain`, `model`, `provider`, and an `error_source` chain in order (worker → pipe operator → router → runner → CLI).
- - **Markdown path:** assert the markdown contains the error type, message, hint, and source frames.
-- [x] Add a snapshot test for one or two representative Rich error outputs (`error_handlers.py`) to confirm the Phase 7 panel-helper refactor introduced no rendering drift. — _Landed as `tests/unit/pipelex/cli/test_error_handlers_snapshot.py` (`TestErrorHandlersSnapshot`): exact plain-text snapshots of `handle_model_choice_error` and `handle_model_availability_error` rendered through `display_error_panel` via a fixed-width, color-free Rich console (no `syrupy` in the repo — snapshots are inline string constants)._
-
-### GREEN
-
-- [x] Fix any wiring gap the full-chain test exposes (a wrapper exception dropping `error_category`, `agent_error()` not forwarding a field, `_build_error_source()` degrading the chain, an enum serialized as a Python repr instead of its `StrEnum` value). — _The gap was exactly "a wrapper exception dropping `error_category`". `PipelexError.to_error_report()` now enriches from the `__cause__` chain — see Running Notes._
-
-### REFACTOR
-
-- [x] If the full-chain test reveals a recurring forwarding bug, fix it at the source (the wrapper exception) rather than patching the renderer. — _Fixed at the source: the enrichment lives on `PipelexError.to_error_report()` (the exception layer), not in `agent_output.py`'s renderer. A second, deeper bug surfaced and is flagged as a follow-up — see Running Notes "Phase 8" and "Followup — PipeLLM wrapping defeats the router retry loop"._
-
-> ### STOP — FINAL: All three priorities landed
->
-> **Status (landed 2026-05-16):** COMPLETE — RED, GREEN, REFACTOR all landed. `make agent-check` clean (ruff + plxt + pyright 0 errors + mypy 0 issues); `make agent-test` passed (full suite); the Temporal integration suite passed (`tests/integration/pipelex/temporal/`, in-process server — 94 passed, 4 xpassed, 0 failures; the 4 xpassed are the pre-existing xdist-flaky tests noted in Phase 6, not a regression). Per-decision detail in the "Phase 8" section of Running Notes below.
->
-> All three priorities are landed: standalone resilience (Phases 5/5.5), the Temporal retry bridge (Phase 6), markdown/HTTP error delivery (Phase 7), and now full-chain integration coverage proving a worker error surfaces correctly through every wrapping layer to the CLI in both JSON and markdown.
->
-> Run `make agent-check` and `make agent-test`. Run the Temporal integration suite. Update [wip/error-handling/README.md](README.md) — flip the CLI delivery, retry & resilience, Temporal integration, and testing tracks to their new status. Archive this `TODOS.md` into `wip/error-handling/` alongside the prior sweep.
-
----
-
-## Out of scope
-
-- **Extract / Classify / Render decomposition** ([track-extract-classify-render.md](track-extract-classify-render.md)) — unblocked but a separate, large refactor. Do not pull forward.
-- **`FileNotFoundError` category/action mismatch** ([wip/error-handling/deferred-items/file-not-found-category-mismatch.md](deferred-items/file-not-found-category-mismatch.md)) — resolve only when a concrete consumer benefits.
-
----
-
-## Running Notes
-
-_Append decisions, surprises, and hand-off context here as each phase lands. Keep checkpoint hand-off context in the matching CHECKPOINT block above and the detail here._
-
-### Phase 1 — Broad-except hygiene sweep (landed)
-
-**`BLE001` status:** was *already present in ruff config but disabled* — it sat in the `# TODO: stop ignoring these rules` block of `pyproject.toml`'s ruff `ignore` list. Phase 1 removed it from that list, so it is now an active, permanent lint guard.
-
-**Scope:** `BLE001` flags broad catches repo-wide, including test code. Phase 1 is scoped to non-test code, so `tests/**/*.py` was added to ruff `per-file-ignores` for `BLE001` (7 test sites: defensive fixtures and failure-mode assertions). Test-code broad catches are out of scope.
-
-**Key surprise — ruff's re-raise exemption:** `BLE001` does **not** flag a broad `except Exception` whose handler re-raises (the caught or a wrapped exception). Of the 128 `except Exception` statements in `pipelex/`, ruff flagged only the **96** that *swallow*. This means the plan's "observe-and-reraise" sites (`pipe_abstract.py`, `llm_worker_abstract.py` span-recording catches) and the `pipe_func.py` *outer* user-code-boundary catch (wraps into `PipeRunError`) were never flagged and needed **no `noqa`** — the rule already permits them. Net work was: 3 narrowed + 93 `noqa`.
-
-**Triage table (96 flagged, swallowing sites):**
-
-| Category | Sites | Disposition |
-| --- | --- | --- |
-| Narrowable | `pipe_func.py:196` (inner `get_stuff` catch), `func_registry.py:319` (`get_type_hints`), `model_deck.py:707` (`load_toml_from_path_if_exists`) | Narrowed — see below |
-| Allowed boundary | agent-CLI command handlers (`cli/agent_cli/commands/**`), CLI command code (`cli/commands/**`), dev CLI (`cli/dev_cli/**`), Temporal workflow/activity roots (`wf_pipe_router.py`, `act_assemble_graph.py`), async-task root (`pipe_run.py`), telemetry exporters/managers (`system/telemetry/**`) | `# noqa: BLE001` |
-| Best-effort cleanup | `teardown()` async-client close paths in `gateway_extract_worker.py`, `google_img_gen_worker.py`, `google_llm_worker.py`; `__del__` in `ndjson_event_log.py` | `# noqa: BLE001` (kept "log but don't fail teardown" comments; teardown `aclose()` raises too broad a set to narrow safely) |
-| Defensive utility / fallback | `json_utils.py` (×3, kajson serialization fallback), `string_utils.py:58` (arbitrary `__str__`), `class_utils.py:97` (schema-compare fallback), `output_renderer.py` (×2, placeholder render), `structured_content_composer.py:107` (diagnostic string builder), `working_memory_factory.py:190` & `dry_run.py:187` (dry-run mock fallback), `delivery_executor.py` (×2, best-effort graph/file rendering), `library_manager.py:1177` (`model_rebuild`) | `# noqa: BLE001` — broad catch is the intended design (must never crash the surrounding flow); narrowing would risk silently re-propagating |
-
-**Narrowing decisions (3 sites — no observable behavior change intended):**
-
-- `pipe_func.py:196` — inner catch around `working_memory.get_stuff()` narrowed to `WorkingMemoryStuffNotFoundError` (the only exception `get_stuff()` raises).
-- `func_registry.py:319` — catch around `typing.get_type_hints()` narrowed to `(NameError, TypeError)`, matching the already-narrow `(ValueError, TypeError)` catch 18 lines above it.
-- `model_deck.py:707` — catch around `load_toml_from_path_if_exists()` narrowed to `(TomlError, OSError)` (TOML parse failure / unreadable file), matching the method's docstring "if the file can't be read or parsed".
-
-`noqa` directives for the 93 legitimate sites were applied with `ruff check --select BLE001 --add-noqa`. Most sites already carry an adjacent explanatory comment that serves as the justification.
-
-### Phase 1.5 — Second-pass narrowing of `noqa: BLE001` sites (IN PROGRESS — checkpoint 2026-05-15)
-
-**Final state:** ALL groups (A–F) and REFACTOR landed. `make agent-check` is clean (ruff + plxt + pyright 0 errors + mypy 0 issues). `make agent-test` passed. **76 surviving `# noqa: BLE001`** (down from 91 at RED), each carrying a one-line justification comment on the following line; zero `# TODO: wip - do not catch all exceptions` markers remain. An independent code review of the staged diff ran at the earlier checkpoint; its one finding (the Group C teardown narrowing) was applied — see the Group C entry below.
-
-**RED findings:**
-
-- 91 `# noqa: BLE001` sites found (the plan estimated 93 — line drift since Phase 1, no material difference). 5 `# TODO: wip - do not catch all exceptions` markers (`delivery_executor.py` ×4, `act_assemble_graph.py` ×1).
-- **No new pinning tests were added.** Every narrowing catches the *same real exception set* the guarded call raises on its expected path — none is an *intended* behavior change. Behavior only differs if a latent bug raises an unexpected type; `make agent-test` (the REFACTOR step) is the regression check for exactly that, as the plan frames it.
-- The editor's inline pyright surfaces many `reportMissingImports` for optional inference SDKs (`anthropic`, `google.genai`, `mistralai`, `fal_client`, `botocore`, `docling`, `temporalio`). That is an artifact of the editor's diagnostic environment — the real `make agent-check` pyright (run with `--pythonpath .venv/bin/python`) reports 0 errors. Ignore the inline noise.
-
-**Landed — per-site dispositions (all pass `make agent-check`):**
-
-_Group A (`delivery_executor.py`, `act_assemble_graph.py`) — all 5 `# TODO: wip` comments removed:_
-
-| Site | Disposition |
-| --- | --- |
-| `_generate_graph_files` | KEPT broad `# noqa: BLE001` + justification. ASSESS — `generate_graph_outputs()` is a deep mermaid/reactflow/jinja2 render tree; surface not enumerable; best-effort (a graph failure must not fail delivery). |
-| `_try_add_rendered_file` | KEPT broad `# noqa: BLE001` + justification. ASSESS — renders include the jinja2 stuff-viewer template. |
-| `_store_results` | KEPT broad `except Exception` — re-raises as `StorageDeliveryError`; ruff exempts re-raising handlers so no `noqa`. TODO replaced with a real comment. Wraps `generate_result_files()` (deep). |
-| `_notify_webhook` | NARROWED → `except httpx.RequestError` (re-raises as `WebhookDeliveryError`; `httpx.HTTPStatusError` handled just above). |
-| `act_assemble_graph` | KEPT broad `# noqa: BLE001` + justification — true Temporal activity root; best-effort observability, degrades to `None`. |
-
-_Group B:_
-
-| Site | Disposition |
-| --- | --- |
-| `json_utils.py:384,444,497` | NARROWED → `(TypeError, UnijsonEncoderError)`; added `from kajson.exceptions import UnijsonEncoderError`. |
-| `class_utils.py:97` | NARROWED → `(PydanticUserError, PydanticUndefinedAnnotation)`; added pydantic import. |
-| `library_manager.py:1177` | NARROWED → `(NameError, PydanticUserError)`. |
-| `mistral_factory.py:257` | NARROWED → `except ValueError` — `binascii.Error` and `UnicodeDecodeError` are both `ValueError` subclasses, so `ValueError` is the correct minimal catch (the plan's `(binascii.Error, ValueError)` is redundant). |
-| `dry_run.py:187` | NARROWED → `except ValidationError` (`TypedNamedStuffSpec.make_from_named` is a pydantic construction). |
-| `working_memory_factory.py:190` | KEPT broad + justification. ASSESS — `make_mock_content` builds mocks via polyfactory over arbitrary dynamic structure classes; wide unstable surface; falls back to text content. |
-| `string_utils.py:58` | KEPT broad + justification. ASSESS — `f"{value}"` invokes arbitrary `__str__`/`__format__`; can raise anything; a partial narrow would be wrong. |
-| `structured_content_composer.py:107` | KEPT broad, unchanged — already had a justification comment. |
-| `output_renderer.py:54,92` | KEPT broad + justification. ASSESS — `render_stuff_spec` → `render_concept_representation` spans concept-structure resolution + pydantic schema generation over dynamic concepts. |
-
-_Group C — all 6 teardown sites (`gateway_extract_worker.py`, `google_img_gen_worker.py`, `google_llm_worker.py`):_ KEPT broad `except Exception` + `# noqa: BLE001` + justification (ASSESS). First narrowed to `except RuntimeError`, but the code review correctly flagged that the inner catch wraps `asyncio.run(aclose())` — which genuinely runs `aclose()`; its failure surface over a duck-typed/deep connection pool is not enumerable, and the teardown contract is "never fail". Reverted; this matches Phase 1's original "`aclose()` raises too broad a set to narrow safely" note.
-
-_Group D (partial):_
-
-| Site | Disposition |
-| --- | --- |
-| `backends_ui.py:88` | NARROWED → `(TomlError, OSError)`. |
-| `show_cmd.py:160` | NARROWED → `except MarkupError`. NOT a "load" catch (the plan misread it) — `routing_profile` is already loaded; the block prints Rich markup with interpolated config strings, so `rich.errors.MarkupError` is the real mode. |
-| `backends.py:137` | NARROWED → `except EOFError` (`suggest_extension_install_if_needed`'s only uncaught exception is `EOFError` from `Confirm.ask` with no stdin). |
-| `backends.py:168,176` | NARROWED → `(OSError, TOMLKitError)`; added `from tomlkit.exceptions import TOMLKitError`. |
-| `backends.py:183` | KEPT broad + justification — command-level boundary (Group F category). |
-
-**Checkpoint fix:** the first `make agent-check` flagged 8 `E501` (justification comments >150 chars); all shortened; re-check clean.
-
-**Group D — `doctor_cmd.py` (landed):**
-
-| Site | Disposition |
-| --- | --- |
-| `:103` (`init_config`) | NARROWED → `(PipelexCLIError, OSError)`; added `from pipelex.cli.exceptions import PipelexCLIError`. `init_config` does os/shutil work (the `os.makedirs` outside its inner try raises `OSError`) and wraps the rest into `PipelexCLIError`. |
-| `:121` (`load_config` + `model_validate`) | NARROWED → `(TomlError, OSError)`. Verified `ConfigLoader.load_config()` only does TOML loading + file IO (`TomlError` / `OSError`); the `ValidationError` from `model_validate` is caught separately just above. |
-| `:320` (`load_toml_from_path`) | NARROWED → `(TomlError, OSError)`. `load_toml_from_path` raises only `TomlError` (parse) or `OSError` (`open()`). |
-| `:231`, `:253`, `:294`, `:373`, `:767` | KEPT broad + justification. Doctor probes — "probe and report" over a non-enumerable surface (whole credential/model scans, kit-template lookups). |
-| `:881`, `:900`, `:911`, `:937` | KEPT broad + justification. Doctor `--fix` handlers wrapping whole sub-commands (`init_cmd`/`update_cmd`/`replace_backend_file`); a fix failure is reported, the run continues. |
-| `:785` (`doctor_cmd` command root) | Unchanged — already had a justification comment. |
-
-**Group E — `wf_pipe_router.py:120,165` (landed):** both `try/except Exception: pass` blocks removed entirely. `event_log` is always a `BufferingEventLog`; its `close()` is a verified no-op (empty body) and cannot raise, so both call sites are now a bare `event_log.close()`. No `noqa` survives at these sites.
-
-**Group F — verify + justify (landed, no narrowing):** all sites confirmed as true boundaries; a one-line justification comment was added wherever one was missing.
-
-- **Agent CLI command roots (23 sites)** — `cli/agent_cli/commands/**`. Each catches at the command function and routes through `agent_error()` (confirmed `-> NoReturn` in `agent_output.py`) — the documented CLI error boundary. The agent-CLI `doctor_cmd.py:134` had a redundant trailing `# agent_error has NoReturn` comment folded into the new justification.
-- **Dev CLI command roots (13 sites)** — `_dev_cli.py` ×10 (all identical: print a `rich` Traceback then `sys.exit(1)`) + `generate_mthds_schema_cmd.py`, `check_mthds_schema_cmd.py`, `preprocess_test_models_cmd.py` (the last had a weak `# Catch-all for unexpected errors` comment, strengthened).
-- **Telemetry (7 sites)** — `exception_capture.py:84,91` + `telemetry_manager.py:199` got new comments; `telemetry_manager.py:209/217/225` and `posthog_span_exporter.py:368` already carried one.
-- **`wf_pipe_router.py:108,115,142,157`** — workflow tracing setup/teardown observe-and-log catches (line numbers shifted from the plan's `145,160` after the Group E removal). Each got a "best-effort — must never fail the workflow" justification.
-- **`init/command.py:484`, `init/routing.py:156`** — command-level boundaries; got new comments. `init/backends.py` (now `:185`) already had one.
-- **`ndjson_event_log.py:190`** (`__del__`) — interpreter-shutdown safety net; already justified.
-- **`pipe_run.py:41`** — kept broad + justified; see the Group F checkbox decision above (observe-and-reraise).
-
-**REFACTOR (landed):** every surviving `# noqa: BLE001` verified to carry a comment on the following line (76/76); `grep` confirms no `# TODO: wip - do not catch all exceptions` remains; `make agent-check` clean and `make agent-test` passed.
-
-**Behavior changes from Phase 1.5 narrowing:** none intended. The three Group D narrowings (`:103`, `:121`, `:320`) each catch the same real exception set the guarded call raises on its expected path. If an unexpected exception type were ever raised, it now propagates to the `doctor_cmd` root catch (`:785`) — which already degrades gracefully — instead of being caught locally. `make agent-test` passed, confirming no test depended on the previously-broad catch.
-
-**Final `noqa: BLE001` count: 76** (91 at Phase 1.5 RED → 81 after Groups A/B/C/D-partial at the earlier checkpoint → 76 after Group D narrowing ×3 and Group E removal ×2 this session).
-
-**Assess-site decisions (kept broad + justified — the REFACTOR Running Notes requirement):** `_generate_graph_files`, `_try_add_rendered_file`, `act_assemble_graph` (Group A); `working_memory_factory.py:190`, `string_utils.py:58`, `structured_content_composer.py:107`, `output_renderer.py:54,92` (Group B); the 6 `teardown()` catches in `gateway_extract_worker.py` / `google_img_gen_worker.py` / `google_llm_worker.py` (Group C); `backends.py:183` (Group D, command boundary). Each wraps a non-enumerable exception surface (deep render/template trees, polyfactory mock building, arbitrary `__str__`, `asyncio.run(aclose())` over a connection pool, or a command-level boundary) and is a genuine best-effort / boundary catch.
-
-### Phase 2 — `error_domain` on the error model (landed 2026-05-15)
-
-`ErrorDomain` (`StrEnum`: `INPUT` / `CONFIG` / `RUNTIME`) was placed in `pipelex/base_exceptions.py`, next to `PipelexError` and `ErrorReport` — the analogue of `InferenceErrorCategory` living beside `CogtError` in `cogt/exceptions.py`. The plan left placement open ("ask the user if ambiguous"); this was the consistent call and `base_exceptions.py` is what consumes it, so no import indirection is needed.
-
-`ErrorReport` gained `error_domain: str | None = None` (typed `str`, mirroring `error_category` — keeps the field a plain string and matches the existing pattern). `PipelexError` gained the class attr `error_domain: ErrorDomain | None = None`; both `PipelexError.to_error_report()` and the `CogtError` override forward it. No consumer changes (Phase 4's job).
-
-### Phase 3 — Class-level metadata on exceptions (landed 2026-05-15)
-
-**`user_action` on the base class.** Phase 3 needs class-level `user_action`, so `PipelexError` gained `user_action: UserAction | None = None` and the base `to_error_report()` now forwards it. `CogtError` already declared its own `user_action` class attr + `__init__` param — left as-is (a harmless same-typed override; removing it is out of scope).
-
-**`error_domain` set on:** `PipeExecutionError` + `PipelineExecutionError` → `RUNTIME`; `ValidateBundleError` + `PipelexInterpreterError` → `INPUT`; `PipelexConfigError` + `PipelexSetupError` → `CONFIG`; `PipelexServiceError` (base) + `PipelexServiceConfigValidationError` → `CONFIG` (all gateway / remote-config errors inherit via `PipelexServiceError`).
-
-**`user_action` set on** (only where the track doc proposes concrete text): `PipelineExecutionError` → `UserAction(UNKNOWN, "Check pipe_stack to identify which pipe failed")`; `ValidateBundleError` → `UserAction(CHANGE_INPUT, "Check the validation_errors array for specific issues")`. `CHANGE_INPUT` fits a bad-bundle fix; `UNKNOWN` is the honest kind for a generic execution failure (`UserActionKind` has no diagnostic-investigation kind — the `detail` carries the real guidance).
-
-**Prompt-* `CogtError` families → `CONTENT`** (firm, per track followup 3): `LLMPromptSpecError`, `LLMPromptTemplateInputsError`, `LLMPromptParameterError`, `PromptImageFactoryError`, `PromptImageFormatError`, `PromptDocumentFactoryError`, `ImgGenPromptError`, `ImgGenParameterError`.
-
-**Case-by-case `error_category` decisions** (the eight the plan flagged):
-
-| Class | Decision | Rationale |
-| --- | --- | --- |
-| `ImageContentError` | `CONTENT` | Name is explicit ("image content"). Currently unused — assigned by name semantics. |
-| `SdkTypeError` | `CONFIGURATION` | Raised when the injected SDK client is the wrong type for the worker — a setup/wiring misconfiguration. |
-| `InferenceBackendLibraryError` | `CONFIGURATION` | Raised during backend-library validation/setup (`backend_library.py`). |
-| `CostRegistryError` | `None` (uncategorized) | Internal cost-bookkeeping error; not a classifiable inference failure. |
-| `ReportingManagerError` | `None` | Internal reporting error; not a classifiable inference failure. |
-| `GeneratedImageError` | `None` | Internal PIL→raw image-conversion failure; not content / config / capacity. |
-| `ExtractOutputError` | `None` | Currently unused; a post-extraction processing error — not clearly one category. |
-| `LLMAssignmentError` | `None` | Currently unused; ambiguous — left uncategorized. |
-
-`None` keeps today's behavior (an uncategorized report) — the safe default for the genuinely-ambiguous / internal ones. The four per-instance "outcome" exceptions stay uncategorized as the plan directs.
-
-**Intentional behavior change.** The targeted exceptions now emit `error_domain` (and `user_action` for two) in `to_error_report()`. `tests/unit/pipelex/test_base_exceptions.py`'s cold-import assertion was updated to expect `error_domain: 'config'` on `PipelexConfigError`'s report. For a real `ValidateBundleError` / `PipelineExecutionError` cause, `agent_error()`'s `hint` now comes from the class `user_action` (`hint` was already report-first) — the text is the track-doc wording, a slight rewording of the old dict hint.
-
-### Phase 4 — Retire the agent-CLI string dicts + drift detection (landed 2026-05-15)
-
-**`agent_error()` change.** Only `error_domain` needed work — `hint` (from `user_action`) was already report-first. Added a `report_domain` local; `domain = report_domain or AGENT_ERROR_DOMAINS.get(error_type)`.
-
-**Dict entries removed** (only the now-redundant ones — those whose class gained class-level metadata in Phase 3):
-
-- `AGENT_ERROR_HINTS`: `ValidateBundleError`, `PipelineExecutionError` (the two that gained class `user_action`).
-- `AGENT_ERROR_DOMAINS`: `ValidateBundleError`, `PipelexInterpreterError`, `PipelineExecutionError`, `PipeExecutionError`, `GatewayTermsNotAcceptedError`, `GatewayApiKeyMissingError`, `GatewayDoNotTrackConflictError`, `RemoteConfigFetchError`, `RemoteConfigValidationError`.
-
-**Dict entries that survived** — the plan's "remove all `PipelexError`-keyed entries" was NOT taken literally: it would regress every `PipelexError` subclass Phase 3 did not migrate. Survivors include `PipelexError`-subclass keys with no class-level metadata (`ModelChoiceNotFoundError`, `PipeOperatorModelChoiceError`, `PipeOperatorModelAvailabilityError`, `ModelDeckPresetValidatonError`, `TelemetryConfigValidationError`, `MthdsDecodeError`, `JsonTypeError`), plus the *hint* entries for `PipeExecutionError` / `PipelexInterpreterError` / gateway errors (those gained `error_domain` but no `user_action`, so the hint stays dict-sourced). The "(now redundant)" qualifier in the plan is operative — only redundant entries were removed; the dicts are **not** "built-ins-only".
-
-**`RETRYABLE_ERROR_TYPES`:** unchanged. Both entries (`RemoteConfigFetchError`, `PipeOperatorModelAvailabilityError`) are non-`CogtError` `PipelexError` subclasses whose base `to_error_report()` carries no `retryable` — nothing the report covers, nothing to trim.
-
-**Behavior change.** None for real call paths: every agent-CLI catch site that surfaces a migrated exception passes the actual exception instance as `cause`, so `error_domain` resolves from the report. A bare `error_type` string with no matching cause for a migrated class would lose its dict domain — no such call site exists. `make agent-test` is the regression check.
-
-### Checkpoint B hand-off
-
-- **Case-by-case `error_category` decisions:** the Phase 3 table above.
-- **Which dict entries survived:** the Phase 4 "Dict entries that survived" note — un-migrated `PipelexError` subclasses + builtins / third-party / synthetic labels; **not** built-ins-only.
-- **`PipelexError` subclasses still needing metadata:** the drift test does not flag these (the literal "every subclass" check was descoped as infeasible — see the Phase 4 RED notes). Un-migrated dict-referenced subclasses (`ModelChoiceNotFoundError`, `PipeOperatorModel*`, `TelemetryConfigValidationError`, `ModelDeckPresetValidatonError`, …) still rely on the fallback dicts; migrating them is future work and does not block the shared foundation.
-
-### Phase 5 — PipeRouter retry loop (landed 2026-05-15)
-
-**Coherence decision 1 — default retry budget:** settled as recommended. `pipelex/pipelex.toml` ships `max_transient_retries = 3`, `transient_retry_base_wait = 2.0`, `transient_retry_max_wait = 30.0`, `transient_retry_backoff_multiplier = 2.0`. `0` is a valid explicit opt-out, not the default. Commented-out overrides added to both `.pipelex/pipelex.toml` and `pipelex/kit/configs/pipelex.toml`.
-
-**Coherence decision 2 — `CAPACITY`:** untouched. `InferenceErrorCategory.is_retryable` still returns `False` for `CAPACITY` (and `CONFIGURATION` / `CONTENT` / `UNKNOWN`); the router loop retries `TRANSIENT` only. `CAPACITY` (rate-limit / overwhelm) is Phase 5.5's concern.
-
-**Import-cycle deviation (the big one).** The track doc's "Option B — call `get_config()` directly inside `PipeRouterProtocol.run()`" is **not achievable**. `pipelex.config` imports `pipelex.hub`, and `hub.py` references `PipeRouterProtocol` (as a type). Any import of `pipelex.config` / `pipelex.hub` / `pipelex.system.configuration.configs` from `pipe_router_protocol.py` — at module scope **or** inside a function, and even under `TYPE_CHECKING` — trips pyright's `reportImportCycles` (verified: pyright counts function-local and TYPE_CHECKING imports for cycle detection). Resolution:
-
-- New dependency-free module `pipelex/pipe_run/transient_retry.py` holds `TransientRetrySettings` (a plain `BaseModel`: `max_transient_retries`, `base_wait`, `max_wait`, `backoff_multiplier`, plus `compute_wait(retry_count)` for the exponential backoff). It imports only pydantic, so `pipe_router_protocol.py` can import it cycle-free.
-- `PipeRouterProtocol` carries `transient_retry_settings: TransientRetrySettings` as an instance attribute (alongside `observer`). `run()` reads `self.transient_retry_settings` — no config import.
-- `make_transient_retry_settings()` in `pipe_router.py` reads `get_config().pipelex.pipeline_execution_config` and builds the model. All three concrete routers (`PipeRouter`, `DryPipeRouter`, `TemporalPipeRouter`) call it in `__init__` to populate the attribute. `dry_pipe_router.py` and `temporal_pipe_router.py` import the helper from `pipe_router.py` (none of those modules are in the `hub` import chain, so no cycle).
-- `hub.py`: `PipeRouterProtocol` import moved into the `TYPE_CHECKING` block (it was only ever a type there); the three function annotations referencing it were quoted. This is clean regardless of the cycle and was kept.
-
-Net: config is read at router **construction** time, not per-`run()`. Acceptable — retry config is static for the process lifetime. The retry loop itself lives exactly where the plan wants it (`PipeRouterProtocol.run()`).
-
-**Gateway worker `tenacity` removal.** `_make_retryer` / `_is_retryable_portkey_error` / `_log_retry` and the `async for attempt in retryer` wrappers removed from `gateway_extract_worker.py` and `gateway_search_worker.py`. The now-dead `response is None` defensive branches (only reachable if the retryer looped zero times) and the `attempt_number` counters were removed too; error messages dropped the "after N attempt(s)" phrasing. No timing-sensitive test broke — `make agent-test` passed. Three gateway test files (`test_gateway_quota_detection.py`, `test_gateway_search_worker_semantic.py`, `test_gateway_extract_worker_semantic.py`) had `worker._tenacity_config = MagicMock()` setup blocks; those are now dead and were removed.
-
-**`tenacity` dependency / `tenacity_utils.py`: KEPT.** `pipelex/plugins/fal/fal_poller.py` (polling) and `pipelex/system/pipelex_service/remote_config_fetcher.py` both still use `tenacity` directly; `fal_poller.py` uses `log_retry` from `tenacity_utils.py`. Only `TenacityConfig` (the config model) and `Cogt.tenacity_config` were removed.
-
-**Breaking change — stale `[cogt.tenacity_config]` in user configs.** `extra="forbid"` on `ConfigModel` means an existing `~/.pipelex/pipelex.toml` (or any layered override) that still carries `[cogt.tenacity_config]` now fails config load with `extra_forbidden`. Removed the section from the repo's three toml files (`pipelex/pipelex.toml`, `.pipelex/pipelex.toml`, `pipelex/kit/configs/pipelex.toml`) **and** from this machine's global `~/.pipelex/pipelex.toml` (which a prior `pipelex init` had populated — that is what surfaced the failure during testing). Users upgrading must remove `[cogt.tenacity_config]` from their global config — noted in CHANGELOG.
-
-**`instructor` `max_retries`.** A one-line comment was added at the four LLM-worker call sites (`google_llm_worker.py`, `anthropic_llm_worker.py`, `openai_completions_llm_worker.py`, `openai_responses_llm_worker.py`) noting it retries schema-validation failures only, not transport — out of scope for router retry.
-
-**Intentional behavior changes.** (1) `_after_failing_run()` now fires for a `CogtError` too (previously only `PipeRunError` was caught by `run()`; a `CogtError` propagated raw without notifying the observer). (2) An exhausted-retry or non-retryable `CogtError` is re-raised **as-is** (cause chain preserved) — it is *not* wrapped into `PipeRouterError`; only the pre-existing `PipeRunError` path still wraps.
-
-**Aside:** `make cleanderived` during this phase erased the generated `tests/integration/pipelex/fixtures/_generated_model_sets.py`; `make rtm` regenerated it. Unrelated to retry work.
-
-**Post-landing code review fix.** A review of the diff caught a regression: the deleted gateway-worker `_is_retryable_portkey_error` predicate had retried a `NotFoundError` whose message was "specified deployment could not be found" (a transient Portkey deployment-propagation race). With retry now driven by `GatewayFactory.classify_error_category()`, which mapped *every* `NotFoundError` → `CONFIGURATION` (non-retryable), that case would have stopped retrying. Fixed by adding `GatewayFactory._is_deployment_propagation_race()` and special-casing that message → `TRANSIENT` in `classify_error_category()` (and → `WAIT_AND_RETRY` in `make_user_action_from_portkey_error()`). A `not_found_404_deployment_propagation_race` case was added to `CLASSIFY_CASES`. Also restored field bounds the removed `TenacityConfig` used to provide: `PipelineExecutionConfig` retry fields now carry `Field(ge=0)` (`ge=1` for the backoff multiplier) so a malformed `pipelex.toml` fails at config load.
-
-### Phase 5.5 — Bounded fan-out concurrency (landed 2026-05-16)
-
-**The `gather_bounded` helper (design call).** The plan said "implement bounded fan-out in `PipeBatch`". Instead, the bounded fan-out is a generic, isolated helper — `gather_bounded` in the new `pipelex/tools/misc/async_utils.py` — that `PipeBatch` calls. Rationale: the helper is unit-testable in isolation with trivial probe coroutines, whereas `PipeBatch._live_run_controller_pipe` needs heavy fixture setup (working memory, concepts, a registered branch pipe). All four RED assertions test the helper directly. Consequently the test lives at `tests/unit/pipelex/tools/misc/test_async_utils.py` (beside what it tests), **not** the plan's `tests/unit/pipelex/pipe_controllers/test_pipe_batch_concurrency.py`.
-
-**Factories, not coroutines — the key design point.** `gather_bounded` takes `Sequence[Callable[[], Awaitable[T]]]`, not coroutines. It calls each factory only when its chunk is about to run. This is what bounds *memory*: a `PipeBatch` branch factory defers its `working_memory.make_deep_copy()` until the factory is invoked, so at most `max_concurrency` deep copies exist at once. A bare `asyncio.Semaphore` over already-created coroutines would bound execution but not that materialization — the plan flagged this and chunked factory invocation is the answer.
-
-**Chunk-failure semantics (pinned, uniform).** `gather_bounded` runs one code path for bounded and unbounded alike — the unbounded case is simply a single chunk of every factory. Each chunk uses `asyncio.gather(*chunk, return_exceptions=True)`: every branch in the chunk is awaited (drained — never orphaned or cancelled), then the first exception *by input index* is raised and no later chunk is started. A code review of the first cut caught that the original had a separate unbounded fast-path using *plain* `asyncio.gather`, which raises first-by-*completion-order* and leaves siblings orphaned — so a `PipeBatch` of ≤ 8 items (the default `max_concurrency`) would have had different, weaker failure semantics than a batch of 9+. Unifying the paths fixed that; `test_unbounded_run_propagates_lowest_index_error_over_a_faster_one` and `test_failing_chunk_is_drained_lowest_index_wins_and_later_chunks_skipped` pin index-order over time-order on both. A non-positive int bound now raises `ValueError` (`None` is the only way to request unbounded).
-
-**Config placement and type.** `max_concurrency` on `PipelineExecutionConfig`, next to the Phase 5 retry fields — same "resilience without Temporal" concern, so no separate `ConcurrencyConfig` was introduced. Typed `Annotated[int, Field(ge=1)] | Literal["unbounded"]`: the int arm is a real bound (≥ 1, validated at config load); the explicit `"unbounded"` literal disables the bound — chosen over a magic `0` so the disabled state is self-documenting in the TOML. Default `max_concurrency = 8` in `pipelex/pipelex.toml`. Commented-out overrides in `.pipelex/pipelex.toml` and `pipelex/kit/configs/pipelex.toml`. Existing global configs without the key inherit the default from the layered base — no breaking change (unlike Phase 5's `tenacity_config` removal).
-
-`gather_bounded` itself keeps a generic, config-agnostic contract: `max_concurrency: int | None`, where `None` is the idiomatic Python "no limit". `PipeBatch` bridges the two — it maps the config's `"unbounded"` literal to `None` before calling the helper.
-
-**`PipeBatch` wiring.** The old single loop (item-stuff creation, graph-tracer registration, deep copy, run-params copy, router call → `tasks` list → `asyncio.gather`) is split: the upfront loop keeps the cheap synchronous work (item-stuff creation + graph-tracer registration), and a nested `async def _run_branch` holds the deferred expensive work (deep copy, run-params copy, `get_pipe_router().run()`). One `functools.partial(_run_branch, item_input_stuff, branch_output_item_code)` per branch goes into `branch_factories`, then `gather_bounded(branch_factories, max_concurrency=...)`. `partial` binds the per-branch varying args eagerly, sidestepping the loop-variable capture trap; `_run_branch` closes over only loop-invariant locals.
-
-**`PipeParallel` — not bounded (decision).** It fans over a fixed, pipe-defined branch set (usually small), not a data-driven N. The scaling risk is `PipeBatch`. Left as a plain `asyncio.gather`, no change.
-
-**Graceful-degradation advisory.** Module constant `LARGE_BATCH_ADVISORY_THRESHOLD = 100` in `pipe_batch.py`. When a `PipeBatch` fans out over more than that many items, `_live_run_controller_pipe` logs one `log.warning` naming the active `max_concurrency` and pointing at the Temporal track as the durable, rate-limited path. Advisory, never fatal. A soft item-count threshold was chosen over `CAPACITY`-recurrence detection: aggregating per-branch error categories across a batch is disproportionate effort for "basic, honest backpressure" — the Phase 5 retry loop already absorbs residual `TRANSIENT`, and this advisory is the honest "go Temporal" signal.
-
-**How Phases 5 and 5.5 compose.** Bounded concurrency (5.5) *reduces how often* `CAPACITY` (rate-limit) errors are hit — fewer simultaneous provider calls. The Phase 5 router retry loop absorbs the residual `TRANSIENT` failures. Persistent `CAPACITY` *under* an already-bounded fan-out is the honest boundary where standalone resilience ends and Temporal (durable, task-queue-rate-limited execution) begins — which is exactly what the advisory log line points at. Neither pillar attempts durable crash-survival.
-
-**Intentional behavior change.** With the default `max_concurrency = 8`, a `PipeBatch` over more than 8 items no longer runs every branch at once — it runs in chunks of 8. On the *success* path, batches of ≤ 8 items (or `max_concurrency = "unbounded"`) behave exactly as before. On the *failure* path, behavior changes uniformly for all batch sizes: a failing branch now drains its chunk (siblings are awaited, not left as orphaned background tasks) and the lowest-input-index error wins, instead of the prior plain-`asyncio.gather` first-by-completion-order selection. This is a deliberate improvement, not a regression. No test regressed: `make agent-check`, `make tb`, the targeted `pipe_controllers` / `tools` / `pipes` suites, and `make agent-test` all pass.
-
-**Track doc.** `wip/error-handling/track-retry-and-resilience.md` gained a "Pillar B — Bounded fan-out concurrency" section capturing this design, as the plan directed (it was net-new ground).
-
-### Phase 6 — Temporal bridge: category-aware retry + details payload (landed 2026-05-16)
-
-**`TemporalError` extension.** `__init__` gained two passthrough params — `non_retryable: bool` and `error_report: dict[str, Any] | None`. `error_report`, when present, is splatted as the single `ApplicationError.details` entry (`super().__init__(message, *details, type=..., non_retryable=...)`) and also kept as an instance attribute for in-process readers. `non_retryable` is the Temporal-native retry flag — the inverse of `is_retryable`.
-
-**Category-aware retry decision.** `from_message_exception()` delegates to a new `_is_non_retryable(exc, error_type)` classmethod: when `exc` is a `CogtError` with a non-`None` `error_category`, it returns `not error_category.is_retryable` — the same `is_retryable` signal the Phase 5 PipeRouter loop consults. Otherwise (non-`CogtError` `PipelexError`, or a `CogtError` raised without a category) it falls back to the configured `all_non_retryable_error_types` class-name lookup. Only `InferenceErrorCategory.TRANSIENT` is retryable, so a `TRANSIENT` `CogtError` → `non_retryable=False`; `CONFIGURATION` / `CONTENT` / `CAPACITY` / `UNKNOWN` → `non_retryable=True`.
-
-**Details payload + round-trip.** `from_message_exception()` packs `exc.to_error_report().to_dict()` into details. `from_app_error()` recovers it via the module-level `_error_report_from_details()` helper, which scans `ApplicationError.details` for the first dict carrying the report's `error_type` + `message` shape (so an unrelated details payload is not mistaken for a report). `from_app_error()` preserves the round-tripped `non_retryable` flag and re-packs the report — the structured data (`error_category`, `user_action`, `model`, `provider`) survives the activity → workflow boundary. A legacy fallback remains: when an `ApplicationError` arrives with neither a details report nor `non_retryable` set (a plain error that never went through this bridge), `from_app_error()` still consults the class-name list for the severity decision.
-
-**Log helpers for testability.** Logging was extracted into `_log_critical` / `_log_error` classmethods. `workflow_log` routes through `workflow.logger`, which raises `_NotInWorkflowEventLoopError` outside a live workflow event loop — so unit tests `mocker.patch.object` these two helpers (via an autouse fixture) and assert which severity the retry decision routed to. This is a pure refactor of the existing `workflow_log.critical` / `.error` calls; production behavior is unchanged.
-
-**Config docs.** `RetryPolicyConfig.non_retryable_error_types` and `RetryPolicyConfigOverlay.non_retryable_error_types_extra` gained field-level docstrings stating the name list is a *fallback* for category-less exceptions and an *override* mechanism — category decides retryability for a category-carrying `CogtError`.
-
-**How Phases 5 and 6 compose.** The two retry layers are nested and agree on "transient" — both read `InferenceErrorCategory.is_retryable`. The Phase 5 PipeRouter loop runs *inside* the activity: it retries a `TRANSIENT` `CogtError` up to `max_transient_retries`, sleeping between attempts. Only after that budget is exhausted (or immediately, for a non-`TRANSIENT` category) does the exception leave the activity and hit the Temporal bridge. So Temporal sees a `non_retryable=False` error only after the in-process loop already gave up on it — Temporal's own retry policy (durable, cross-worker) then gets another crack; a non-`TRANSIENT` category arrives as `non_retryable=True` and Temporal does not retry. Fast in-process retry first, durable Temporal retry on the residual.
-
-**Known follow-up — `from_message_exception` is not yet wired (deferred, by decision).** A post-landing code review surfaced that `from_message_exception` — the activity-side half of the bridge, where the category-aware decision and `ErrorReport` details-packing live — has no production caller. Activities raise raw `CogtError` / `PipelexError`; Temporal's default failure converter auto-wraps them without packing our `ErrorReport`, so `from_app_error` currently always takes its `error_report is None` fallback branch and the category-aware path is inert in production. The Phase 6 unit test proves a self-consistent bridge round-trip but does not cross a real activity → workflow boundary. This was deliberately scoped out of Phase 6 (whose plan named only the bridge methods, not the activity wiring); it is recorded as **Followup 5** in [track-temporal-integration.md](track-temporal-integration.md) — wiring the ~8 `act_*` functions plus a real-boundary integration test is the next coherent unit of work.
-
-### Phase 7 — Error delivery: agent CLI markdown + HTTP-status mapping (landed 2026-05-16)
-
-**HTTP-status mapping.** `pipelex/base_exceptions.py` gained `error_domain_to_http_status(ErrorDomain | None) -> int` (the pure domain table: `INPUT` → 422, `CONFIG`/`RUNTIME`/`None` → 500; exhaustive `match`, no `case _`) and `ErrorReport.http_status` (a property that layers the provider-429 passthrough on top — when `provider_metadata.status_code == 429` it returns 429 so a downstream API can emit `Retry-After` from `retry_after_seconds`, otherwise it follows `error_domain`). The library stays HTTP-agnostic — no web-framework import; downstream FastAPI handlers call `ErrorReport.http_status` and are a trivial adapter.
-
-**Format dispatch — the big deviation.** The plan offered "explicit `format` argument *or* a `ContextVar`" and a separate `agent_error_dispatch`. Settled as: a module-level `ContextVar` (`_agent_cli_output_format` in `agent_output.py`, default `CliOutputFormat.JSON`), and **`agent_error()` itself is the dispatcher** — it reads the ContextVar and routes to `_agent_error_json` or `agent_error_markdown`. Rationale: the agent CLI has ~80 `agent_error(...)` call sites across run/validate/init/factory; threading an explicit `format` arg through all of them is noisy and error-prone, and a separate `agent_error_dispatch` would require editing every call site. With `agent_error` as the dispatcher, every existing call site follows `--format` for free — a command opts in once via `set_agent_cli_output_format(output_format)` at its start. JSON stays the default for anything raised before a command opts in (the app callback, `PipelexAgentCLI.get_command` unknown-command handling, `make_pipelex_for_agent_cli` factory errors) because the ContextVar default is JSON. The plan's "keep `agent_error()` JSON as the default" is honored by the ContextVar default, not by keeping `agent_error` literally JSON-only. `agent_error_markdown()` is still a public function (named in the plan); JSON and markdown share `_assemble_error_payload()`.
-
-**Markdown renderers + success path.** `format_run_markdown` (`run/_output_helpers.py`), `format_validate_markdown` (new `validate/_output_helpers.py`), `_format_init_markdown` (`init_cmd.py`). The success path goes through a shared `agent_success_formatted(result, markdown_renderer)` in `agent_output.py` (JSON → `agent_success`; markdown → `print(markdown_renderer(result))`). `format_run_markdown` handles both `build_run_output()` shapes — the `with_memory` envelope (renders `main_stuff.markdown`) and the compact concept JSON (fenced `json` block).
-
-**`--format` naming conflict (breaking CLI change).** `validate bundle` already used `--format`/`-f` for the *graph* renderer (`GraphFormat`: mermaidflow/reactflow/both). To make `--format` uniformly the output-format flag across all commands, that option was renamed to `--graph-format`/`-f`. Breaking change for any skill invoking `validate bundle --format reactflow` — acceptable per the repo's no-back-compat policy; the agent-CLI `CLAUDE.md` documents `--graph-format`.
-
-**`models` / `check-model` / `doctor`.** These already had `--format`; they now also call `set_agent_cli_output_format(output_format)` so their *error* paths follow the option too (previously errors were always JSON regardless). This makes the "errors respect `--format`" contract uniform.
-
-**`error_handlers.py` refactor.** `display_error_panel(console, *, title, fields, error_message, tip, links)` extracted — the canonical red-banner / aligned-fields / error / 💡-tip / dimmed-links panel. Applied to the three genuinely field-shaped handlers: `handle_model_choice_error`, `handle_model_availability_error`, `handle_model_deck_preset_error`. DEVIATION: the plan said "rewrite *each* `handle_*`" but the gateway / telemetry / inference / validate-bundle handlers have prose or structured-detail bodies that are not a `(label, value)` field list — the track doc itself notes the gateway handlers have prose bodies. Those keep their custom bodies. The Phase 8 snapshot test will guard the field-based handlers' rendering.
-
-**Behavior change — markdown is now the default.** `run` / `validate` / `init` previously always emitted JSON; they now default to markdown (`--format json` for the old behavior). Two existing unit tests asserted the old JSON default: `test_agent_validate_cmd.py::test_graph_generation_failure_emits_single_json_error` and `test_agent_doctor_cmd.py::test_unexpected_error_produces_json_error` — both updated to pass `output_format=CliOutputFormat.JSON` explicitly (they test the single-error / JSON-error invariants, which still hold on the JSON path). No other test regressed: `make agent-check` clean and `make agent-test` passed (full suite).
-
-**ContextVar leakage in tests.** The format ContextVar is process-global (fine in production — one command per process). The new `tests/unit/pipelex/cli/agent_cli/conftest.py` has an autouse fixture resetting it to JSON before and after each test so it does not leak between tests.
-
-**Post-landing code review fixes.** An independent review of the diff caught: (1) `format_validate_markdown` rendered only `validated_pipes` — it silently dropped the `graph_files` / `graphspec` keys that `validate bundle --graph` / `--view` merge into the result, so markdown mode (now the default) lost the graph-file pointers. Fixed: the renderer now surfaces a "Graph files" section and a GraphSpec note. (2) Two short loop variables (`fb`, `p`) in the rewritten `handle_model_availability_error` were left below the 3-char minimum — renamed to `fallback` / `stacked_pipe`. The reviewer's other points (the `error_domain_to_http_status` exhaustive `match` without a final return, and the ContextVar lacking `Token`/`reset`) were assessed and left as-is: pyright accepts the exhaustive match (the desired "linter catches a new enum member" guard — adding `case _` is forbidden), and the CLI is one-shot per process so `set()` without `reset()` is correct; the test conftest already isolates the ContextVar.
-
-### Phase 8 — Full-chain integration coverage (landed 2026-05-16)
-
-**The wiring gap (RED → GREEN).** The full-chain test exposed exactly the gap the plan named: *a wrapper exception dropping `error_category`*. An LLM-worker failure travels up as `LLMCompletionError` (a `CogtError`, carries `error_category` / `retryable` / `model` / `provider`) → wrapped by `PipeLLM` into `PipeRunError` → wrapped by `PipeRouter` into `PipeRouterError` → wrapped by `PipelexRunner` into `PipelineExecutionError`. The `__cause__` chain is preserved at every `raise ... from`, but `PipeRunError` / `PipeRouterError` / `PipelineExecutionError` are plain `PipelexError` subclasses that carry none of the inference metadata, and `PipelexError.to_error_report()` did not consult the cause chain — so `agent_error()` received a `PipelineExecutionError` whose report had `error_type` / `message` / `error_domain=runtime` / `user_action` and **nothing else**. RED failed with `KeyError: 'error_category'`.
-
-**The fix (at the source — the wrapper exception layer).** `PipelexError.to_error_report()` now enriches from the immediate `__cause__`: it builds its own report, then fills every `None` classification field (`error_category`, `error_domain`, `retryable`, `user_action`, `model`, `provider`, `provider_metadata`) from `cause.to_error_report()` when `__cause__` is a `PipelexError`. Because each layer recurses into its own cause, the deepest `CogtError`'s metadata propagates all the way up; a wrapper keeps its own `error_type` / `message` and its own non-`None` fields (so `PipelineExecutionError` keeps `error_domain=runtime` and its `user_action`). The enrichment is a protected method `PipelexError._enrich_error_report_from_cause(report)` so it composes uniformly: a `to_error_report()` override ends with `return self._enrich_error_report_from_cause(report)`. `CogtError.to_error_report()` (a full `@override`) was updated to do exactly that — a post-review fix: `CogtError` is *usually* a leaf (its cause is an SDK exception), but it is a `PipelexError` subclass like any other and must honor the documented "enriches from the `__cause__` chain" contract rather than silently opting out. The fix is in the exception layer, not the `agent_output.py` renderer — as the REFACTOR step directs.
-
-**Why this is the right generic fix.** Three distinct wrappers had the same bug; a per-wrapper `to_error_report()` override would triplicate the logic. Enriching once on the base class fixes every current and future wrapper, and is what makes the track-testing.md failure mode ("a new wrapper exception silently swallowing `error_category`") impossible to reintroduce.
-
-**Full-chain test design.** `tests/integration/pipelex/cli/agent_cli/test_run_error_chain.py` invokes the real `run_pipe_cmd`. `make_pipelex_for_agent_cli` and `Pipelex.teardown_if_needed` are stubbed in the command module — the module-scoped `reset_pipelex_config_fixture` already boots Pipelex, and letting the command tear it down would break sibling tests. `resolve_pipe_from_exports` / `parse_cli_inputs` are stubbed (avoid stdin / installed-method lookups). The pipe is loaded via `--library-dir` pointing at the test's own `error_chain.mthds` (one model-less `PipeLLM` pipe `greet` — model-less so the default LLM setting resolves without a backend). `ContentGenerator.make_llm_text` is mocked to raise; `model_handle` / `backend_name` are set on the error via `setattr` (string literals — lint-safe; this is the same duck-typed contract `CogtError.to_error_report()` reads with `getattr`, since worker code does not set them either — see the follow-up note). Both JSON and markdown paths are asserted, including the outermost-first `error_source` order (`PipelineExecutionError` → `PipeRouterError` → `PipeRunError` → `LLMCompletionError`).
-
-**Snapshot test.** The repo has no `syrupy`; the "snapshot" is an exact-match against inline string constants. `handle_model_choice_error` and `handle_model_availability_error` are rendered through `display_error_panel` via `Console(width=80, record=True, color_system=None)` (fixed width + no color → deterministic plain text) and compared to the baked-in expected layout. The availability case exercises the helper's conditional `Fallbacks` / `Pipe Stack` fields. A snapshot is intentionally exact — an intentional URL/wording change fails the test and the dev re-bakes the constant.
-
-**Followup — PipeLLM wrapping defeats the Phase 5 router retry loop (flagged, not fixed; by decision).** While tracing the chain, a second, deeper bug surfaced: `PipeLLM` catches `LLMCompletionError` and re-raises it as a plain `PipeRunError` (`pipe_llm.py` ~241/356/373) *before* the router sees it. The Phase 5 `PipeRouter` retry loop branches on `except CogtError` and consults `error_category.is_retryable` — but for the `PipeLLM` path the router only ever sees a `PipeRunError`, so its `except CogtError` retry branch is **dead** and a `TRANSIENT` LLM failure is never retried in-process. `test_pipe_router_retry.py` does not catch this because it mocks `_run_pipe_job` to raise a raw `CogtError`, which `PipeLLM` never actually lets through. This is a Phase 5 resilience bug, not a Phase 8 error-delivery bug; per the user's decision (2026-05-16) it is scoped out of Phase 8 — fixing it (have `PipeLLM` let the `CogtError` propagate, or have `PipeRunError` carry the category) changes the pipe-operator exception contract and resilience behavior and deserves its own focused change. Recorded as a follow-up for the retry-and-resilience track. (The delivery fix above is unaffected: `to_error_report()` enrichment surfaces the worker's `error_category` regardless of how many plain wrappers sit in between — which is exactly why the full-chain test passes despite this bug.)
-
-**Aside — worker errors do not set `model` / `provider`.** `CogtError.to_error_report()` reads `model` / `provider` via `getattr(self, "model_handle"/"backend_name", None)`, but the LLM workers raise `LLMCompletionError` without setting those attributes (the model is only in the message text). So in production a transient LLM failure currently delivers `model=None` / `provider=None`. The full-chain test sets them explicitly (as the track doc's "model + provider set" directs) to prove the *delivery wiring* carries them when present. Populating them on real worker errors is worker-construction work, out of Phase 8's delivery-wiring scope — noted alongside the retry follow-up.
diff --git a/wip/error-handling/archive-extract-classify-render.md b/wip/error-handling/archive-extract-classify-render.md
deleted file mode 100644
index c41c2e2c0..000000000
--- a/wip/error-handling/archive-extract-classify-render.md
+++ /dev/null
@@ -1,60 +0,0 @@
-# Archive — Extract / Classify / Render (ECR) Decomposition
-
-> **Archived 2026-05-20.** This is the completed ECR refactor — all 5 checkpoints landed on branch `refactor/ECR`. It is kept for the running notes, checkpoint table, and the key design deviations, which have reference value when reading the post-refactor code.
-
-> **Source of truth (current state):** [track-extract-classify-render.md](track-extract-classify-render.md).
-> **Original plan with full per-checkpoint notes:** [`~/.claude/plans/ok-let-s-do-ecr-reflective-dahl.md`](file:///Users/lchoquel/.claude/plans/ok-let-s-do-ecr-reflective-dahl.md) (local-only, not in repo).
-> **Implementation references:** `pipelex/cogt/inference/error_classify.py`, `pipelex/cogt/inference/error_render.py`, `pipelex/cogt/inference/error_classification.py`, `pipelex/cogt/inference/provider_name.py`.
-> **Parity meta-test:** `tests/unit/pipelex/cogt/inference/test_provider_classification_parity.py`.
-
----
-
-## Checkpoint summary
-
-| CP | Scope | Landed in |
-|---|---|---|
-| 1 | New `provider_name.py`, `error_classify.py`, `error_render.py`; `ProviderErrorMetadata` gains `message` + three `@property` accessors (`is_quota_exhaustion`, `is_content_policy_violation`, `is_network_error`); 12 `extract_*` functions updated to populate `message`. | `6c9415de` |
-| 2 | 6 LLM workers migrated (`anthropic`, `openai_completions`, `openai_responses`, `mistral`, `google`, `bedrock`); bedrock instance-method classifier deleted. | `6c9415de` |
-| 3 | 7 img-gen workers migrated (`openai`, `openai_completions_img_gen`, `fal`, `huggingface`, `azure_rest`, `google`, `gateway`). Azure keeps two `AMBIGUOUS` branches (non-idempotent 5xx + post-flight transport errors). Statusless map gains `MissingCredentialsError` + `FalClientError`. | `6c9415de` |
-| 4 | 7 extract + search workers migrated (`mistral`, `linkup` x2, `gateway` x2, `docling`, `pypdfium2`). All `_classify_*_error` instance methods + inline `GatewayFactory.*_from_portkey_error` calls deleted from worker bodies. Statusless map gains the remaining Linkup typed exceptions. Mistral + gateway-search now specialize HTTP 404 to `ExtractModelNotFoundError` / `SearchModelNotFoundError`. | `9c7a6ee1` |
-| 5 | Deleted the per-provider `*_error_classification.py` files (+ matching tests) and `AnthropicCredentialsError`. Deleted `GatewayFactory.classify_error_category` / `make_user_action_from_portkey_error` / `make_error_summary_from_portkey_error` and their direct tests. Privatized quota helpers (`_is_quota_exhaustion_*`, `_is_content_policy_violation`) and rewrote `test_error_classification.py` to exercise the public `ProviderErrorMetadata` properties. New parity meta-test (`test_provider_classification_parity.py`) walks every `ProviderName` against the extract-fn registry. | `aaf6acdf` |
-
----
-
-## Key deviations from the original design
-
-These are the design decisions that diverged from what was sketched in [track-extract-classify-render.md](track-extract-classify-render.md). They are recorded here because the post-refactor code reflects them, and a future reader of the track doc should not be surprised.
-
-1. **Classify + Render live in new modules, not `error_classification.py`.** `exceptions.py` already imports `error_classification.py`, so putting `classify_inference_error` (which needs `InferenceErrorCategory` from `exceptions.py`) into the same module would create a circular import. Resolution: `error_classify.py` (Classify) and `error_render.py` (Render) are separate modules. Import DAG: `error_classification` → `exceptions` → `error_classify` → `error_render`.
-2. **`ProviderErrorMetadata.message` defaults to `""`**, not required. A required field would break ~35 existing direct test constructions for no gain; all 12 `extract_*` functions populate it; the CP5 parity meta-test asserts population.
-3. **`classify_inference_error` checks `is_quota_exhaustion` early** (right after the statusless branch, before the per-status branches). Reason: AWS surfaces quota exhaustion at HTTP 400, not 429 — a pure status ladder would misclassify it. The `is_quota_exhaustion` property is the quota authority.
-4. **`extract_bedrock_metadata` derives HTTP status from the AWS error code** (via `_AWS_ERROR_CODE_TO_STATUS`) when `ResponseMetadata.HTTPStatusCode` is absent. Bedrock's canonical signal is the error-code string; this is legitimate Extract-layer normalization (same spirit as Google's `code` → `status_code`).
-5. **`_classify_statusless` is provider-aware.** Two maps: `_STATUSLESS_BY_TYPE_NAME` (global — pydantic `ValidationError`, uniquely-named Linkup typed exceptions, FAL `MissingCredentialsError` / `FalClientError`) and `_LOCAL_EXTRACT_BY_TYPE_NAME` (builtins `FileNotFoundError` / `ValueError` / `RuntimeError` / `OSError`, applied only when `metadata.provider.is_local_file_extractor`). A bare `ValueError` from an SDK provider → `UNKNOWN`; from docling / pypdfium2 → `CONTENT`.
-6. **HTTP 422 → CONFIGURATION** (unrecognized-4xx bucket), not `CONTENT` — matches the pre-refactor per-provider behavior. Only HTTP 400 → `CONTENT`.
-7. **`SDKErrorEnvelope` is a real `TypeAlias` of `ProviderErrorMetadata`** rather than a renamed class. The shape was already correct; aliasing keeps the existing tests and call sites intact while signaling the Extract → Classify → Render role at the type-annotation level.
-8. **`UserAction.detail` text is now provider-agnostic** (e.g. "Transient provider error — the system will retry automatically" rather than "Rate limited by OpenAI — …"). This is an intended ECR trade-off; the provider name still lives in `provider_metadata` and in the rendered message.
-9. **Azure ImgGen keeps two `AMBIGUOUS` branches** outside the shared classifier — non-idempotent 5xx (server reached, may have generated and billed) and post-flight `httpx` transport errors (`ReadTimeout` / `WriteTimeout` / generic `TransportError`). These encode operation idempotency, not error nature, so they cannot be expressed in the provider-blind Classify. Pre-flight transport (`ConnectError` / `ConnectTimeout` / `PoolTimeout`) still routes through ECR (`TRANSIENT`). The dual-path lives in `_raise_categorized_azure_status_error` (4xx → ECR; 5xx → AMBIGUOUS) plus per-clause `except` blocks in `_gen_image_list`. No equivalent for FAL because `fal_client` submits async to a queue first; a 5xx during submit is pre-acceptance.
-10. **`AnthropicCredentialsError` deletion deferred from CP2 to CP5.** CP2 stopped the anthropic worker from raising it (auth → generic `LLMCompletionError` with `CONFIGURATION` + `CHECK_CREDENTIALS`); the class and the four `classify_*_sdk_error` files still existed and were deleted in CP5 once nothing referenced them.
-11. **Gateway-search SDK-error path raises `SearchJobFailureError` (or `SearchModelNotFoundError`)** instead of `GatewaySearchResponseError`. `GatewaySearchResponseError` is kept for the downstream parsing errors in `_extract_content` where it remains the right class — those are not SDK errors.
-
----
-
-## Net code impact
-
-Cleanup numbers from CP5: -1605 / +45 lines (across deletions of per-provider classifier files, dead Portkey helpers, and the matching test files; partially offset by the new parity meta-test).
-
-Worker `except` blocks now all share the same three-line shape:
-
-```python
-metadata = extract_<provider>_metadata(sdk_exc)
-classification = classify_inference_error(metadata)
-raise render_inference_error(
- metadata=metadata,
- classification=classification,
- family=InferenceErrorFamily.<X>,
- model_desc=self.inference_model.desc,
- model_handle=self.inference_model.name,
-) from sdk_exc
-```
-
-Adding a provider now requires only one new `extract_*_metadata` function plus a `ProviderName` enum value; the Classify and Render code does not move. The parity meta-test fails fast if a provider is added without an extract-fn entry.
diff --git a/wip/error-handling/archive-llm-retry-loop-bypass.md b/wip/error-handling/archive-llm-retry-loop-bypass.md
deleted file mode 100644
index 36c2e5122..000000000
--- a/wip/error-handling/archive-llm-retry-loop-bypass.md
+++ /dev/null
@@ -1,83 +0,0 @@
-# TODO — Fix: PipeLLM wrapping defeats the PipeRouter transient-retry loop
-
-> **Status:** RESOLVED on branch `fix/llm-retry-loop-bypass` (branched off `feature/Error-handling-2`, not `main` — `main` does not carry the Phase 5 retry loop this fix depends on).
->
-> **Decision:** Option B. The router's `except (CogtError, PipeRunError)` branch now derives the retry classification from `exc` itself when it is a `CogtError`, or from `exc.__cause__` when it is a `PipeRunError` (the operator wrap). On exhaustion a `PipeRunError` still wraps into `PipeRouterError`, preserving the pipe location context and keeping the Phase 8 full-chain test (`test_run_error_chain.py`) green. Option A (operators stop wrapping) was rejected because it would drop the `PipeRouterError` frame from the LLM error chain and force a rewrite of that Phase 8 test.
->
-> **Coverage:** `tests/integration/pipelex/pipes/operator/test_operator_transient_retry.py` (real `PipeLLM` + `PipeStructure` through the router, worker mocked TRANSIENT) and a cause-chain case added to `tests/unit/pipelex/pipe_run/test_pipe_router_retry.py`.
-
-> **Branch:** create a fresh branch off `main` (e.g. `fix/llm-retry-loop-bypass`).
-> **Scope:** one focused change. Not a multi-phase plan.
-> **Discipline:** RED (failing test) → GREEN (minimal fix) → REFACTOR. `make agent-check` after each step; `make agent-test` before wrapping up.
-
----
-
-## ▶ Start here — cold-start context
-
-The error-handling Phase-2 plan landed in full (archived at [wip/error-handling/archive-error-handling-2.md](wip/error-handling/archive-error-handling-2.md)). Phase 8 surfaced a **pre-existing resilience bug** that was deliberately scoped out of Phase 8 — this TODO is that follow-up.
-
-**The bug.** Phase 5 added an application-level transient-retry loop to `PipeRouter`. `PipeRouterProtocol.run()` (`pipelex/pipe_run/pipe_router_protocol.py`, around line 66) retries on `except CogtError` when `error_category.is_retryable` is true (i.e. `InferenceErrorCategory.TRANSIENT`). But the LLM pipe operators **catch the worker's `LLMCompletionError` (a `CogtError`) and re-raise it as a plain `PipeRunError` before it ever reaches the router.** The router's `except PipeRunError` branch (around line 82) does *not* retry — it wraps into `PipeRouterError` and gives up. So:
-
-- The router's `except CogtError` retry branch is **dead for the LLM path**.
-- A `TRANSIENT` LLM failure (rate limit, timeout, brief outage) is **never retried in-process**, even though `max_transient_retries` defaults to 3.
-- The Phase 5 CHANGELOG entry ("Application-level retry of transient inference failures — `PipeRouter` now retries failures classified as `TRANSIENT`") is **effectively false for the most common case**, an LLM call.
-
-**Why the existing test misses it.** `tests/unit/pipelex/pipe_run/test_pipe_router_retry.py` mocks `_run_pipe_job` to raise a *raw* `CogtError` — which the real PipeLLM path never lets through. The test passes but does not reflect production.
-
----
-
-## Verified facts (checked against the code)
-
-**Operator wrapping sites that swallow the `CogtError` into a plain `PipeRunError`:**
-
-- `pipelex/pipe_operators/llm/pipe_llm.py` — `except LLMCompletionError` → `raise PipeRunError(...) from exc` at **lines 251, 360, 377** (text-gen, object-list-direct, single-object-direct). Line 266 wraps a `ValidationError` the same way — *not* a `CogtError`, so out of scope for retry (a schema-validation failure is not transient).
-- `pipelex/pipe_operators/structure/pipe_structure.py` — same pattern at **lines 166, 179** (object-list, single-object).
-
-**Operator that does NOT wrap (the inconsistency):**
-
-- `pipelex/pipe_operators/img_gen/pipe_img_gen.py` — does not appear to catch the worker's `ImgGenGenerationError`/`CogtError`; it only raises `PipeImgGenRunError` for a stuff-not-found case. So a transient *image-gen* error likely propagates as a raw `CogtError` and **is** retried by the router. Confirm this during investigation — it means LLM pipes and img-gen pipes currently behave differently, which is itself a bug.
-
-**Router branches** (`pipe_router_protocol.py`, `run()`):
-
-- `except CogtError` (~line 66): retry loop — consults `error_category.is_retryable`, sleeps with backoff, re-raises as-is on exhaustion.
-- `except PipeRunError` (~line 82): no retry — wraps into `PipeRouterError`.
-
----
-
-## The open design decision (settle this first)
-
-Pick the exception contract before writing code:
-
-- **Option A — operators let the `CogtError` propagate.** PipeLLM / PipeStructure stop converting `LLMCompletionError` into `PipeRunError`; they add context another way (e.g. attach the location to the message, or raise an `LLMCompletionError` subclass) and let the `CogtError` reach the router. Cleanest and most honest — the router then retries it and, on exhaustion, re-raises the `CogtError` as-is (Phase 5 already does this; it is *not* wrapped into `PipeRouterError`). `PipelexRunner`'s `except PipelexError` branch then wraps it into `PipelineExecutionError`. **Cost:** changes what exception type a caller of these operators sees; check every `except PipeRunError` that currently relies on the wrap.
-- **Option B — the router inspects `__cause__`.** Keep the operator wrapping; in the `except PipeRunError` branch, if `exc.__cause__` is a retryable `CogtError`, retry instead of wrapping. More contained, no operator-contract change — but less honest (the router reaching into `__cause__` is a smell) and the retry decision logic gets duplicated/forked.
-
-**Recommendation:** Option A — it makes the operator layer say what it means and keeps the router's retry decision in one place. But verify the blast radius of `except PipeRunError` callers first. Record the decision in the commit message / a short note here.
-
-Whatever the choice, **apply it consistently** to PipeLLM *and* PipeStructure (and reconcile with PipeImgGen so all inference operators behave the same).
-
----
-
-## RED
-
-- [ ] Write a test that runs a real pipe operator (not a mocked `_run_pipe_job`) through `PipeRouter` with the LLM worker mocked to raise a `TRANSIENT` `LLMCompletionError`, and asserts the router **retries** `max_transient_retries` times before failing. Model it on the Phase 8 full-chain test `tests/integration/pipelex/cli/agent_cli/test_run_error_chain.py` (which already mocks `ContentGenerator.make_llm_text` to raise and runs a real `PipeLLM`). Mock `asyncio.sleep` (in the `pipe_router_protocol` module) so the backoff does not actually wait. This test fails today: the worker is called once, not `1 + max_transient_retries` times.
-- [ ] Cover `PipeStructure` too (and `PipeImgGen` if the investigation shows it needs aligning).
-
-## GREEN
-
-- [ ] Apply the chosen option (A or B) so a `TRANSIENT` `CogtError` from an LLM operator reaches the router's retry path. Minimal change to make the RED test pass.
-- [ ] Run `make agent-check`.
-
-## REFACTOR
-
-- [ ] Fix `tests/unit/pipelex/pipe_run/test_pipe_router_retry.py` so it is no longer misleading — either route it through a real operator, or add a comment that it intentionally tests the router in isolation and the operator-level coverage lives in the new test.
-- [ ] Run `make agent-test`. Run the Temporal integration suite (`tests/integration/pipelex/temporal/`) — the Temporal retry path (Phase 6) consults the same `is_retryable` signal; confirm no regression.
-- [ ] Update the CHANGELOG (`### Fixed`) — the transient-retry feature now actually fires for LLM pipes.
-- [ ] Flip the "Known follow-up" note in [wip/error-handling/README.md](wip/error-handling/README.md) (retry & resilience track) to resolved.
-- [ ] Archive this `TODOS.md` into `wip/error-handling/` if you want to keep the running notes.
-
----
-
-## Out of scope
-
-- `pipe_func.py` `PipeRunError` raises (lines 208/266/320/326) — these wrap *user-function* failures, not transient inference errors. A failing user function is not retryable; leave it.
-- Workers not setting `model_handle` / `backend_name` on `LLMCompletionError` (so `ErrorReport.model`/`provider` come back `None` in production) — a separate, smaller follow-up noted in the Phase 8 archive notes. Not this task.
diff --git a/wip/error-handling/archive-retry-and-resilience.md b/wip/error-handling/archive-retry-and-resilience.md
deleted file mode 100644
index 394715c73..000000000
--- a/wip/error-handling/archive-retry-and-resilience.md
+++ /dev/null
@@ -1,184 +0,0 @@
-# TODOS — Retry & Resilience: remove the PipeRouter loop, make Tier 1 (transport retry) explicit
-
-> **ARCHIVED — both workstreams landed.** Workstream 1 (remove the `PipeRouter` transient-retry loop) and Workstream 2 (make Tier 1 transport retry explicit and uniform, confine `instructor` to schema re-ask) are both in the code. This file is kept for its running notes and checkpoint history. The current-state description lives in [track-retry-and-resilience.md](track-retry-and-resilience.md).
-
-> **Type:** Implementation plan — two independent workstreams. Workstream 1 is a removal; Workstream 2 is config + factory wiring + a worker audit.
-> **Source / intent:** [wip/error-handling/track-retry-and-resilience.md](wip/error-handling/track-retry-and-resilience.md) — the target-architecture doc. Where this plan and that doc differ, the doc is authoritative for *intent*; this plan is authoritative for *steps*.
-> **Branch:** Workstream 2 runs on `feature/Error-handling-4` (branched off `feature/Error-handling-3`, which carries the landed Workstream 1 removal). Workstream 1 shipped as PR #909 (`feature/Error-handling-3` → `feature/Error-handling-2`); commits `bd089c2a` (removal) + `22932ae2` (CHANGELOG cleanup). `feature/Error-handling-3` carries the error-metadata model and the now-removed Phase 5 retry loop's *absence*; `main` has neither.
-> **Packaging:** ship as **two PRs** — Workstream 1 (removal) landed first as PR #909. Workstream 2 (Tier 1 explicit) follows as a second PR off `feature/Error-handling-4`. The two workstreams don't conflict, but separate PRs keep each review scoped to one concern.
-> **Discipline:** `make agent-check` after each step; `make agent-test` before wrapping up. After deleting test files, `make cleanderived` if collection misbehaves. After config/toml changes, `make tb` (boot test — config model and toml must stay in sync).
-
-## Status
-
-**Workstream 1 complete and shipped** as PR #909 (`make agent-check` clean, `make agent-test` green; see the Workstream 1 checkpoint below). **Workstream 2 complete** — all of steps 2.1–2.5 landed on `feature/Error-handling-4`; `make agent-check` clean, `make agent-test` green (see the Workstream 2 checkpoints below). Ready for the second PR.
-
-**Cold-start for Workstream 2:** read **Cold-start context** below (the tier model and what Workstream 2 is *not*), then the **Workstream 2** section in full, then **Key files** and **Risks / gotchas**. Workstream 2 is config + SDK-factory wiring + a worker audit — it makes the provider SDKs' existing transport retry an explicit, uniform, configured policy and brings the SDK-less paths up to that floor; it does **not** build a Pipelex retry layer. The critical correction the v1 plan got wrong (`instructor`'s `max_retries` retries transport errors too, not just schema validation) is in **Cold-start context** and drives step 2.3 — do not skip it.
-
-## Cold-start context
-
-Pipelex's resilience story is Temporal. Direct (non-Temporal) execution makes one pipeline-level attempt on top of a transport that already retries brief blips — it should stay clean and honest about that, and not reproduce Temporal's durability. The full reasoning, the tier model, and the decisions are in the architecture doc linked above. The two concrete consequences this plan executes:
-
-- **Remove the `PipeRouter` application-level transient-retry loop (Phase 5).** It only ever runs on the direct path — it is dead code on the Temporal path, because `_run_pipe_job` there raises `WorkflowExecutionError` / `TemporalError`, which the loop's `except (CogtError, PipeRunError)` never catches. It also re-runs at the wrong granularity and carries a per-run/global config bug (the retry budget is snapshotted from global config at router construction, so a per-run `execution_config` is silently ignored). Removing it is cleaner than fixing it for a path that is deliberately not the resilient one.
-- **Make "Tier 1" — transport retry — an explicit, uniform policy.** The provider SDKs already retry transient transport failures (OpenAI / Anthropic: `max_retries = 2`, retry 408 / 409 / 429 / 5xx / connection errors, honor `Retry-After`); the worker factories inherit that silently, and workers not on a retrying SDK (the raw-`httpx` `azure_rest` image-gen path; the Mistral and Google SDKs, both of which default to **no** transport retry; the FAL submit path) don't get it. The work is to make the retry posture deliberate and uniform — set `max_retries` explicitly from config, and bring the SDK-less paths up to the same floor — **not** to build a Pipelex retry layer, which would duplicate the SDK.
-
-What stays untouched: `PipeBatch` bounded fan-out (`gather_bounded` / `max_concurrency`) — admission control, not retry. Temporal Tier 2 (activity `RetryPolicy` keyed off `InferenceErrorCategory`). The operator wrapping in `PipeLLM` / `PipeStructure` (`LLMCompletionError` → `PipeRunError`) — error-context propagation. The provider SDKs' own retry logic — Workstream 2 *configures* it, it does not replace it.
-
-**A correction the v1 plan got wrong:** it scoped `instructor`'s `max_retries` out as "schema-validation retry, not transport." Verified false against `instructor` 1.15.1 (`instructor/core/retry.py`): passed an `int`, `instructor` retries **any** exception — transport / API errors included. The structured-output path (`PipeLLM` / `PipeStructure`) therefore already runs an application-level transport-retry loop nested on the SDK's own. Confining `instructor` to genuine schema re-ask is Workstream 2.3.
-
----
-
-## Workstream 1 — Remove the PipeRouter transient-retry loop
-
-A removal, not a TDD build. Delete in the order below, then verify. One small guard test is added at the end.
-
-### 1.1 — Strip the retry loop from the protocol
-
-- [x] `pipelex/pipe_run/pipe_router_protocol.py` — in `run()` (around lines 54–100), remove the `while True` retry loop, the backoff `asyncio.sleep`, the retry logging, and the `find_inference_error_category_in_chain` call. The resulting `run()`: `_before_run` → one `_run_pipe_job` call → `_after_successful_run` on success; on `except (CogtError, PipeRunError)`, call `_after_failing_run`, then wrap a `PipeRunError` into `PipeRouterError` / re-raise a raw `CogtError` as-is. **Keep that handler** — it is error propagation (pipe-stack context), not retry.
-- [x] Same file — remove the `transient_retry_settings: TransientRetrySettings` attribute from `PipeRouterProtocol`.
-- [x] Let `make fix-unused-imports` clean the now-unused imports (`asyncio`, `log`, `find_inference_error_category_in_chain`, `TransientRetrySettings`).
-- [x] Leave `find_inference_error_category_in_chain` in `pipelex/cogt/exceptions.py` — Temporal still uses it (`temporal_error.py`). Only the router's *use* of it goes.
-
-### 1.2 — Delete the retry plumbing
-
-- [x] Delete `pipelex/pipe_run/transient_retry.py` (`TransientRetrySettings`).
-- [x] `pipelex/pipe_run/pipe_router.py` — delete `make_transient_retry_settings()`; drop `self.transient_retry_settings` from `PipeRouter.__init__`.
-- [x] `pipelex/pipe_run/dry_pipe_router.py` — drop `transient_retry_settings` from `DryPipeRouter` (around line 13) and its import.
-- [x] `pipelex/temporal/tprl_pipe/temporal_pipe_router.py` — drop `transient_retry_settings` from `TemporalPipeRouter` (around line 54) and its import. This was dead code.
-
-### 1.3 — Remove the config
-
-- [x] `pipelex/system/configuration/configs.py` — from `PipelineExecutionConfig` (around lines 153–177) remove the transient-retry fields and the `_validate_transient_retry_timing` validator. **Keep `max_concurrency`** — it is the bounded-fan-out pillar and stays.
-- [x] `pipelex/pipelex.toml` — remove the transient-retry settings (around lines 290–293).
-- [x] `pipelex/kit/configs/pipelex.toml` — remove the commented-out transient-retry block (around lines 41–44).
-- [x] `.pipelex/pipelex.toml` — remove the commented-out transient-retry block (around lines 40–44, including the `# Uncomment and adjust...` lead-in). It is commented so boot won't fail, but a user uncommenting `max_transient_retries` after this change would hit a config-load failure against the removed field.
-- [x] `make tb` — confirm the boot sequence still loads the config (model ↔ toml in sync).
-
-### 1.4 — Tests
-
-- [x] Delete `tests/unit/pipelex/pipe_run/test_pipe_router_retry.py`.
-- [x] Delete `tests/integration/pipelex/pipes/operator/test_operator_transient_retry.py`.
-- [x] `tests/unit/pipelex/system/configuration/test_pipeline_execution_config.py` — drop expectations on the removed retry fields.
-- [x] Add one small guard test pinning **both** branches of the kept handler: (a) a transient `CogtError` from `_run_pipe_job` surfaces on the **first** attempt (`_run_pipe_job` called exactly once) — pins the "direct = single pipeline-level attempt" contract against a future re-introduction of a loop; (b) a `PipeRunError` from `_run_pipe_job` surfaces as `PipeRouterError` with the pipe-stack context intact — pins the "keep the handler" contract against a future accidental handler deletion.
-
-### 1.5 — Docs
-
-- [x] `CHANGELOG.md` `[Unreleased]` — record the removal (reverses the Phase 5 "application-level retry of transient inference failures" entry).
-- [x] `wip/error-handling/todos-retry-graph-trace.md` — mark resolved-by-removal (the PipeRouter loop was the sole cause of the phantom-error-node bug it describes).
-- [x] `wip/error-handling/README.md` — update the Retry & resilience status row: the loop is now removed (the row currently carries a "Superseded" pointer plus a "Landed in current code" description that becomes false here).
-
-> **CHECKPOINT — Workstream 1 complete.**
-> - `make agent-check` clean (ruff, plxt, pyright 0 errors, mypy clean); `make tb` green (config model ↔ toml in sync); `make agent-test` green (full suite).
-> - `max_concurrency` left intact in `PipelineExecutionConfig` and all three `pipelex.toml` files; the `except (CogtError, PipeRunError)` handler in `run()` kept (now without the loop); the `PipeLLM` / `PipeStructure` operator wrapping untouched; `find_inference_error_category_in_chain` left in `cogt/exceptions.py` for Temporal's use.
-> - **Deviations from the steps:**
-> - 1.4 — `test_pipeline_execution_config.py` was *deleted entirely* rather than "drop expectations": both its test functions targeted only the removed `_validate_transient_retry_timing` validator, so dropping the retry expectations left an empty file.
-> - 1.4 — the guard test landed in a new file `tests/unit/pipelex/pipe_run/test_pipe_router_run.py` (`TestPipeRouterRun`), since `test_pipe_router_retry.py` was deleted.
-> - 1.5 — `CHANGELOG.md`: the "Application-level retry of transient inference failures" entry was *removed* from `[Unreleased]` rather than reversed with a "Removed" entry — it was never in a release, so a Removed line would only confuse release-notes readers. Two cross-references were also corrected: the `PipeBatch` entry ("second resilience pillar beside transient retry" → "the resilience-without-Temporal pillar") and the Temporal activity-boundary entry (dropped the "Temporal-side twin of the non-Temporal `PipeRouter` transient-retry path" sentence).
-> - Not committed — left for the user / the W1 PR step.
-
----
-
-## Workstream 2 — Make Tier 1 (transport retry) explicit and uniform
-
-Not a TDD build of a new layer — the SDK-backed paths already retry transient transport failures. This makes that retry a deliberate, uniform, configured policy, closes the worker families that don't get it (the Mistral and Google SDKs default to no transport retry), and confines `instructor`'s structured-output retry to genuine schema re-ask so the SDK floor is the *only* transport-retry layer.
-
-### 2.1 — Config
-
-- [x] Add an inference-client transport-retry setting to the `cogt` config (`pipelex/cogt/config_cogt.py`). **Name it distinctly** — `transport_max_retries` (or `sdk_client_max_retries`) — **not** `max_retries`: a bare `max_retries` collides with `llm_job.job_config.max_retries`, which is `instructor`'s schema-re-ask count (`stop_after_attempt`). The two are different things — transport floor vs. schema re-ask — and must read as different. Placement: a small transport-scoped block, or `LLMConfig`. **Do not put it in `InstructorConfig`** — it configures the SDK transport client, not `instructor`. Decide whether request `timeout` joins it or stays per-provider (Anthropic already derives its own from `structured_output_timeout_seconds` — leaving timeout per-provider is fine). — **Done:** named `transport_max_retries`, `Field(ge=0, le=10)`. **Deviation:** placed directly on the `Cogt` config (not `LLMConfig`) — the SDK client factories it feeds also build image-generation clients, so a `Cogt`-level field reads honestly for both; `LLMConfig` would have been a naming smell on the img-gen path. `timeout` left per-provider.
-- [x] Defaults in `pipelex/pipelex.toml` — `transport_max_retries = 2`, matching the current SDK default so behavior is unchanged until deliberately tuned. `make tb` to confirm the config loads. — **Done:** `transport_max_retries = 2` under `[cogt]`; `make tb` green.
-
-### 2.2 — Wire the SDK client factories
-
-- [x] Each inference client factory passes `transport_max_retries` explicitly when constructing the SDK client, from the config — instead of inheriting the silent SDK default. **Verified list of factories that actually construct a client** (the others under `pipelex/plugins/*/` are message/param helpers and build nothing):
- - `anthropic/anthropic_factory.py` — `AsyncAnthropic` (L53), `AsyncAnthropicBedrock` (L62/68). — **Done:** `max_retries=` on all three.
- - `openai/openai_client_factory.py` — `AsyncAzureOpenAI` (L55), `AsyncOpenAI` (L68). — **Done:** `max_retries=` on both.
- - `gateway/gateway_factory.py` — `AsyncPortkey` (L67) **and** the `AsyncOpenAI` clients for completions/responses (`make_portkey_openai_client_for_*`). **Note:** the gateway client is `AsyncPortkey` (the `portkey-ai` SDK), **not** `openai.AsyncOpenAI` as the track doc states. — **`AsyncPortkey` NOT wired** (see next item — became a 2.4-noted case).
- - `portkey/portkey_completions_factory.py` — `AsyncOpenAI` (L110); `portkey/portkey_responses_factory.py` — `AsyncOpenAI` (L37). — **Done:** `max_retries=` on both.
- - `mistral/mistral_factory.py` — `Mistral` (L52). — **Done:** `retry_config=` (see below).
- - `google/google_factory.py` — `GoogleGenAiClient` (L22). — **Done:** `http_options=HttpOptions(retry_options=...)`.
-- [x] `AsyncOpenAI` / `AsyncAnthropic` accept `max_retries` directly. **Verify `AsyncPortkey`'s retry parameter before wiring** — the `portkey-ai` SDK may not expose `max_retries` the same way as `openai.AsyncOpenAI`; if it doesn't, the gateway path becomes a 2.4 case. For the `Mistral` SDK and the Google SDK, find the equivalent option (Speakeasy-style `retry_config`, `HttpOptions.retry_options`, etc.). — **Done & verified:** OpenAI/Anthropic `max_retries` (SDK default 2). `AsyncPortkey` exposes **no** `max_retries` knob — it builds an internal OpenAI client with a hard-coded `max_retries=1`; left as-is (it is a retrying SDK, so wrapping it would double-retry). Mistral SDK has no transport retry by default → wired a `RetryConfig` (`strategy="backoff"`, `retry_connection_errors=True`); its retry is **time-budget based, not attempt-count based**, so `transport_max_retries` acts as an on/off switch for Mistral (positive → bounded-backoff retry). Google `genai` has no retry by default → wired `HttpOptions(retry_options=HttpRetryOptions(attempts=transport_max_retries + 1))` (`attempts` counts the initial try).
-
-> **CHECKPOINT — SDK-backed workers explicit.** Config landed on the `Cogt` model as `transport_max_retries` (`pipelex/cogt/config_cogt.py`), default `2` in `pipelex/pipelex.toml` under `[cogt]`. `make agent-check` clean (ruff, plxt, pyright 0 errors, mypy clean); `make tb` green. SDK without a `max_retries` equivalent: `AsyncPortkey` (`portkey-ai`) — it carries its own internal retry, so it is left unwired rather than treated as an SDK-less gap; only the gateway's underlying `AsyncOpenAI` clients are wired.
-
-### 2.3 — Confine `instructor` to schema re-ask
-
-The structured-output path (`PipeLLM` / `PipeStructure`) wraps each completion with `instructor`. `instructor` wraps the *factory-built* SDK client (`from_openai(client=...)`, `from_anthropic(...)`, `from_mistral(...)`, `from_genai(...)`), so 2.2's factory `max_retries` does reach structured calls. But `instructor`'s own `max_retries`, passed as an `int` (`llm_job.job_config.max_retries`, default 3), builds a `tenacity` loop whose default predicate retries **any** exception — so it re-runs the whole completion on transport / API errors too, a second retry loop nested on the SDK floor (worst case ≈ `job_config.max_retries × (cogt.max_retries + 1)` attempts). This is the layer the v1 plan wrongly scoped out as "schema-validation only."
-
-- [x] Add a shared helper returning a `tenacity.AsyncRetrying` whose `retry=` predicate is `retry_if_exception_type((pydantic.ValidationError, json.JSONDecodeError))` and whose `stop` is `stop_after_attempt(job_config.max_retries)`. `instructor.core.retry.initialize_retrying()` accepts a pre-built `AsyncRetrying` and uses it as-is. — **Done:** new module `pipelex/cogt/llm/instructor_retry.py`, `make_instructor_schema_retrying(max_attempts)`. **Deviation:** the predicate also lists `instructor`'s own `ValidationError` / `AsyncValidationError` — verified (research) that those are **not** subclasses of `pydantic.ValidationError`, so a `(pydantic.ValidationError, json.JSONDecodeError)`-only predicate would miss genuine schema failures `instructor` surfaces as its own types. The full tuple mirrors `instructor.core.retry.retry_async`'s own validation `except`.
-- [x] In the four `instructor` call sites — `openai_completions_llm_worker.py`, `openai_responses_llm_worker.py`, `anthropic_llm_worker.py`, `google_llm_worker.py` — replace `max_retries=llm_job.job_config.max_retries` (the bare `int`) with that `AsyncRetrying`. `mistral_llm_worker.py` passes no `max_retries` today (so `instructor` defaults to 1 — no re-ask; and the Mistral SDK has no transport retry either): give it the same `AsyncRetrying` so structured Mistral gets schema re-ask. — **Done:** all five wired. `openai_responses` needed a `# type: ignore[arg-type]` — instructor's `responses` path is stub-typed `int | Retrying` (no `AsyncRetrying`), though `initialize_retrying` accepts and the async path needs an `AsyncRetrying`.
-- [x] **Behavior change to handle:** with a validation-only predicate a transport error is no longer retried by `instructor` and no longer wrapped in `InstructorRetryException` — it propagates as the raw SDK exception. ... The task is therefore **verify-coverage, not add-catch** ... — **Done & verified:** OpenAI/Anthropic — `anthropic.APITimeoutError` ⊂ `APIConnectionError` and `openai.APITimeoutError` ⊂ `APIConnectionError`; every status error ⊂ `APIStatusError`; so `except (APIStatusError, APIConnectionError)` is exhaustive for transport types — **no widening needed**. (`APIResponseValidationError` is under `APIError` only, not a transport error — out of scope.) Google & Mistral — **widening needed and done:** both SDKs let raw `httpx` connection/timeout errors propagate **outside** their `ServerError`/`ClientError` / `MistralError` hierarchies, so `_gen_object` **and** `_gen_text` gained an `except httpx.TransportError` clause classifying as TRANSIENT (`_raise_categorized_google_sdk_error` extended; new `_classify_mistral_transport_error` helper).
-- [x] Update the worker comments at the `max_retries=` call sites — they were corrected during this plan markup to describe *current* (retries-everything) behavior; once this step lands, update them to the new (re-ask-only) behavior. — **Done:** all five call-site comments rewritten to the schema-re-ask-only behavior.
-- [x] `CHANGELOG.md` `[Unreleased]` — record that `instructor`'s structured-output retry no longer re-runs completions on transport errors; transport retry is solely the SDK floor. — **Done:** `### Changed` entry added.
-
-### 2.4 — Cover the non-SDK / weak-SDK workers
-
-- [x] Audit the workers that do not ride a retrying SDK and verify the rest:
- - `pipelex/plugins/azure_rest/azure_img_gen_worker.py` — raw `httpx.AsyncClient`, **no** retry layer. Genuinely SDK-less — **gets the retry floor.**
- - FAL — `fal/fal_img_gen_worker.py` submits via the **`fal_client` SDK** (`AsyncClient.submit()`). **Verified (research):** `fal_client` has its **own internal transport retry** (`MAX_ATTEMPTS`, exponential backoff, retries timeouts/transport errors/transient statuses) — so FAL is **left as-is**, not brought to the floor. `fal_poller.py`'s `tenacity` is job-status polling — left as-is.
- - Mistral / Google — **verified (research):** Mistral SDK has **no** transport retry by default, Google `genai` defaults to a never-retry stop strategy — both wired in 2.2 (`RetryConfig` / `HttpOptions.retry_options`).
-- [x] Bring each genuine gap up to the same floor ... For the SDK-less paths, build the floor on **`tenacity`** ... — **Done:** the one genuine SDK-less gap is the `azure_rest` image-gen worker. New module `pipelex/cogt/inference/transport_retry.py` — `request_with_transport_retry(send_request, max_retries, retry_on_ambiguous_failure=True)` built on `tenacity`: retry predicate on `httpx.TransportError` + transient statuses (408/409/429/5xx), a `wait` callable honoring `Retry-After` (capped 60s, else exponential backoff), `stop_after_attempt(max_retries + 1)`. **Deviation:** `stop_after_attempt(max_retries + 1)` (not the plan's literal `stop_after_attempt(transport_max_retries)`) — `transport_max_retries` counts retries beyond the initial attempt (the OpenAI/Anthropic semantics), so `+ 1` keeps the SDK-less floor consistent with the SDK-backed ones. The wrapper carries the idempotency caveat as `retry_on_ambiguous_failure` (False → no retry on an ambiguous 5xx); `azure_img_gen_worker.py` passes `retry_on_ambiguous_failure=False` — image generation is a billable, non-idempotent POST, so an ambiguous 5xx (Azure may have already generated and billed the image) is not retried; only connection errors and 408/409/429 are.
-
-### 2.5 — Tests + docs
-
-- [x] Test that each factory builds its client with the configured `transport_max_retries` (a construction test — do not try to unit-test SDK retry over the network). — **Done:** `tests/unit/pipelex/plugins/test_transport_retry_wiring.py` — `TestTransportRetryWiring`, one method per factory (patches the SDK client constructor, asserts the configured value reaches it).
-- [x] Test the `instructor` retrying helper (2.3): a transport-style exception is **not** retried (the predicate excludes it) and propagates raw; a `pydantic.ValidationError` **is** retried up to `stop_after_attempt`. — **Done:** `tests/unit/pipelex/cogt/llm/test_instructor_retry.py`.
-- [x] **CRITICAL — regression coverage for the 2.3 behavior change.** ... Add, **per worker** ... a test that a raw SDK transport exception raised from `create_with_completion` is classified into the correct `InferenceErrorCategory` ... — **Done:** added `test_raw_sdk_transport_error_is_classified` (parametrized) to each of the five `test_*_object_error_handling.py` files; google/mistral cases include raw `httpx` connection/timeout errors. Also **updated the five `test_real_instructor_wraps_*` end-to-end tests** — they asserted the *old* behavior (instructor wraps the SDK exception in `InstructorRetryException`); renamed to `test_real_instructor_propagates_transport_error_raw` and re-pointed at the new behavior (raw SDK exception propagates, `__cause__ is sdk_exc`).
-- [x] Test the new `tenacity`-based SDK-less retry wrapper (2.4): mock the `httpx` transport, assert it retries the transient statuses and honors `Retry-After`, mock `asyncio.sleep`; assert a submit-style call is **not** retried on an ambiguous 5xx (idempotency caveat). — **Done:** `tests/unit/pipelex/cogt/inference/test_transport_retry.py`.
-- [x] `CHANGELOG.md` `[Unreleased]` — record that inference-client transient retry is now an explicit, uniform policy. — **Done:** `### Added` entry.
-- [x] `wip/error-handling/README.md` + `track-retry-and-resilience.md` — flip Tier 1 status to landed. — **Done.**
-- [x] `make agent-test`. — **Done: green.**
-
-> **CHECKPOINT — Workstream 2 complete.**
-> - `make agent-check` clean (ruff, plxt, pyright 0 errors, mypy clean); `make tb` green; `make agent-test` green (full suite).
-> - Every inference worker family now has a defined, explicit transport-retry floor: OpenAI / Anthropic / gateway-OpenAI / Mistral / Google via their SDKs (configured from `cogt.transport_max_retries`); the SDK-less `azure_rest` image-gen path via the `tenacity` wrapper; FAL via its own `fal_client` SDK retry; the gateway `AsyncPortkey` via the `portkey-ai` SDK's own internal retry. `instructor`'s structured-output retry is confined to schema re-ask, so transport retry is the SDK / wrapper floor alone.
-> - **Deviations from the steps** (each explained inline above): config placed on `Cogt` not `LLMConfig`; `instructor` predicate also lists instructor's own validation-error types; `AsyncPortkey` left unwired (no `max_retries` knob, has internal retry); SDK-less wrapper uses `stop_after_attempt(transport_max_retries + 1)`; Mistral retry is on/off (time-budget SDK); the five `test_real_instructor_wraps_*` tests were renamed and re-pointed at the inverted behavior; `openai_responses` needed one `# type: ignore[arg-type]`.
-> - New modules: `pipelex/cogt/llm/instructor_retry.py`, `pipelex/cogt/inference/transport_retry.py`. New tests: `test_transport_retry_wiring.py`, `test_instructor_retry.py`, `test_transport_retry.py`, plus methods added to the five `test_*_object_error_handling.py` files.
-> - Not committed — left for the user / the W2 PR step.
-
----
-
-## Key files
-
-**Workstream 1 (remove):**
-
-- `pipelex/pipe_run/pipe_router_protocol.py` — `run()`, the loop.
-- `pipelex/pipe_run/pipe_router.py`, `pipelex/pipe_run/dry_pipe_router.py`, `pipelex/pipe_run/transient_retry.py`; `pipelex/temporal/tprl_pipe/temporal_pipe_router.py`.
-- `pipelex/system/configuration/configs.py` — `PipelineExecutionConfig`.
-- `pipelex/pipelex.toml`, `pipelex/kit/configs/pipelex.toml`.
-- Tests: `tests/unit/pipelex/pipe_run/test_pipe_router_retry.py`, `tests/integration/pipelex/pipes/operator/test_operator_transient_retry.py`, `tests/unit/pipelex/system/configuration/test_pipeline_execution_config.py`.
-
-**Workstream 2 (make Tier 1 explicit):**
-
-- `pipelex/cogt/config_cogt.py` — `Cogt` config; the new `transport_max_retries` setting goes here (not in `InstructorConfig`). `pipelex/pipelex.toml` — its default.
-- SDK client factories (verified — those that construct a client): `pipelex/plugins/anthropic/anthropic_factory.py`, `pipelex/plugins/openai/openai_client_factory.py`, `pipelex/plugins/gateway/gateway_factory.py` (`AsyncPortkey` + the gateway `AsyncOpenAI` clients), `pipelex/plugins/portkey/portkey_completions_factory.py` + `portkey_responses_factory.py`, `pipelex/plugins/mistral/mistral_factory.py`, `pipelex/plugins/google/google_factory.py`.
-- Non-SDK / weak-SDK workers: `pipelex/plugins/azure_rest/azure_img_gen_worker.py`, the FAL submit path, plus Mistral / Google verification.
-- `instructor` call sites (2.3): `pipelex/plugins/openai/openai_completions_llm_worker.py`, `openai/openai_responses_llm_worker.py`, `anthropic/anthropic_llm_worker.py`, `google/google_llm_worker.py`, `mistral/mistral_llm_worker.py`. `instructor`'s retry implementation: `.venv/.../instructor/core/retry.py` (`initialize_retrying`, `retry_async`).
-- Reference for what "transient" means: `pipelex/cogt/inference/error_classification.py` and `InferenceErrorCategory` in `pipelex/cogt/exceptions.py`. The installed SDKs' retry logic is in `.venv/.../openai/_base_client.py` and `.venv/.../anthropic/_base_client.py` (`DEFAULT_MAX_RETRIES`, `_should_retry`).
-
-## Out of scope
-
-- Multi-tenant rate pacing / quotas, caller run deadline/budget, idempotency model, circuit breaking — platform/product concerns; see [wip/temporal-next/00-enterprise-readiness-analysis.md](wip/temporal-next/00-enterprise-readiness-analysis.md).
-- Temporal Tier 2 changes — only a review of whether its `RetryPolicy` defaults are right for the hosted product; not this plan.
-- `fal_poller.py`'s `tenacity` (job-status polling) — not transport-error retry; stays as-is. (`instructor`'s `max_retries` was listed here in the v1 plan — wrongly; it retries transport errors too and is now Workstream 2.3.)
-
-## Risks / gotchas
-
-- **Keep the `except (CogtError, PipeRunError)` handler in `run()`** — only the loop is removed. Deleting the handler would drop error propagation (the `PipeRouterError` wrap, pipe-stack context).
-- **Do not touch `gather_bounded` / `max_concurrency`** — easy to over-delete when removing "resilience" config; it is the bounded-fan-out pillar and stays.
-- **Do not revert the operator wrapping** (`PipeLLM` / `PipeStructure` catching `LLMCompletionError` → `PipeRunError`) — propagation, not retry.
-- **`make tb` after config/toml edits** — the config model and every `pipelex.toml` must stay structurally in sync or boot fails.
-- **Configure the SDK retry; do not replace it.** Disabling SDK retries (`max_retries = 0`) to hand-roll a Pipelex retry would re-implement well-tested SDK behavior (status classification, `Retry-After` parsing, backoff) — over-engineering. Only the genuinely SDK-less paths (Workstream 2.3) get a Pipelex `httpx`-level retry.
-- **`Retry-After` is the SDK's job.** The OpenAI / Anthropic SDKs honor `Retry-After` only when ≤ 60s, else exponential backoff — accept that boundary; a longer wait is the Temporal line, not something to chase in direct mode.
-- **`instructor` is a second transport-retry loop.** Passed an `int`, `instructor`'s `max_retries` retries any exception, transport included (Workstream 2.3). Making Tier 1 "explicit" by touching only the factories and leaving `instructor` as an `int` leaves the structured-output floor non-uniform (`job_config.max_retries × cogt.transport_max_retries`) and unmeasured — do not skip 2.3.
-
-## GSTACK REVIEW REPORT
-
-| Review | Trigger | Why | Runs | Status | Findings |
-|--------|---------|-----|------|--------|----------|
-| CEO Review | `/plan-ceo-review` | Scope & strategy | 0 | — | — |
-| Codex Review | `/codex review` | Independent 2nd opinion | 0 | — | — |
-| Eng Review | `/plan-eng-review` | Architecture & tests (required) | 1 | CLEAR (PLAN) | 7 issues + 1 regression, all resolved into the plan |
-| Design Review | `/plan-design-review` | UI/UX gaps | 0 | — | not applicable (backend/infra) |
-| DX Review | `/plan-devex-review` | Developer experience gaps | 0 | — | — |
-
-- **UNRESOLVED:** 0
-- **VERDICT:** ENG CLEARED — plan amended, ready to implement. Ship as two PRs (W1 then W2).
diff --git a/wip/error-handling/archive-retry-graph-trace.md b/wip/error-handling/archive-retry-graph-trace.md
deleted file mode 100644
index f258ba0d1..000000000
--- a/wip/error-handling/archive-retry-graph-trace.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# TODO — Drop failed-attempt graph nodes when the PipeRouter retries
-
-> **Status:** RESOLVED BY REMOVAL. The phantom-error-node bug existed only because the `PipeRouter` retry loop reran a failed pipe within a single `run()`. That loop has been removed (Workstream 1 of the retry-and-resilience plan — see [track-retry-and-resilience.md](track-retry-and-resilience.md)): direct execution is now a single pipeline-level attempt, so a pipe runs at most once per `run()` and there is no duplicate error/success node to discard. The rest of this doc is kept only as a record of the original gap.
-> **Source:** Follow-up to the `PipeRouter` transient-retry loop — see [track-retry-and-resilience.md](track-retry-and-resilience.md). Raised as a review comment on PR #903.
-
----
-
-## The gap (one paragraph)
-
-The `PipeRouter` transient-retry loop (`PipeRouterProtocol.run()` in `pipelex/pipe_run/pipe_router_protocol.py`) retries a transient inference failure by rerunning `_run_pipe_job()`, which reruns `pipe.run_pipe()`. But `PipeAbstract.run_pipe()` has *already* called `tracer_manager.on_pipe_end_error(...)` for the failed attempt before the exception reached the router (the `except` branch in `pipe_abstract.py`). So when a transient failure succeeds on a later attempt, the graph still carries the failed attempt's error node — plus a fresh success node for the same pipe. A successful run looks partially failed to graph output and trace consumers.
-
-This is observability-only — the run itself completes correctly. It is separable from the retry-bypass fix that PR #903 delivers, hence deferred.
-
-## Pointers
-
-- **Retry loop:** `pipelex/pipe_run/pipe_router_protocol.py` — `run()`, the `while True` loop and its `except (CogtError, PipeRunError)` branch (~line 62-95). On a retryable error within budget it `continue`s the loop.
-- **Where the error node is recorded:** `pipelex/core/pipes/pipe_abstract.py` — `run_pipe()` `except` branch calls `tracer_manager.on_pipe_end_error(...)`.
-- **Graph tracer surface:** `pipelex/graph/graph_tracer.py`, `graph_tracer_manager.py`, `graph_tracer_protocol.py` — no supersede/discard/retry mechanism exists today.
-
-## Shape of the change (to be designed)
-
-The graph tracer needs a way to discard (or mark as superseded/retried) a node when its pipe is about to be retried, so a successful retried run shows a single clean node.
-
-**Open design question — settle this first:** the router does not hold the graph `node_id` (it is created and kept inside `run_pipe()`). Two candidate approaches:
-
-1. The router signals "retrying" to the tracer, and the tracer keys the discard off pipe identity / the current graph context.
-2. `run_pipe()` itself detects a retryable failure and defers/withholds the error node until the failure is final — pushing the retry-awareness one layer down.
-
-List both in the plan, weigh them, recommend one.
-
-## How to expand (do this in the new session)
-
-1. Read the retry-loop code and `run_pipe()`'s tracing branches in full; confirm the duplicate-node behavior with a trace from a forced transient-then-success run.
-2. Decide the design question above and record the decision.
-3. Write the plan as RED → GREEN → REFACTOR. RED = a test that forces a transient failure then success and asserts the resulting graph has exactly one node for the pipe, with no error event. Confirm it fails today.
-4. Run `make agent-check` after each step, `make agent-test` before wrapping up.
-
-## Out of scope
-
-- The retry loop itself — landed in PR #903.
-- The Temporal-side retry path — its activity-boundary wiring landed; see Followup 5 in [track-temporal-integration.md](track-temporal-integration.md).
diff --git a/wip/error-handling/archive-temporal-activity-boundary.md b/wip/error-handling/archive-temporal-activity-boundary.md
deleted file mode 100644
index 54cf6b035..000000000
--- a/wip/error-handling/archive-temporal-activity-boundary.md
+++ /dev/null
@@ -1,305 +0,0 @@
-# TODOS — Wire `from_message_exception` into the Temporal activity boundary
-
-> **ARCHIVED 2026-05-17 — COMPLETE.** This plan landed in full (Phases 0–5) and was moved here from the repo-root `TODOS.md`. Kept for its checkpoint history and TDD record. The remaining unchecked Phase 5 items are optional confidence checks, consciously not run — see the Status section.
-
-> **Type:** TDD plan (RED → GREEN → REFACTOR), multi-phase with checkpoints.
-> **Source:** Followup 5 of [track-temporal-integration.md](track-temporal-integration.md).
-> **Branch:** `fix/temporal-activity-error-boundary`.
-
----
-
-## Status — as of 2026-05-16
-
-**All phases (0–5) are complete and committed** on branch `fix/temporal-activity-error-boundary`. Phases 0–2 landed through `18e0135b`; Phases 3–4 landed in `cda61bae` ("feat: category-aware error boundary on all Temporal activities"). Phase 5 is verification only — `make agent-check` clean, full `make agent-test` green.
-
-What is in the code right now:
-
-- **`pipelex/temporal/tprl/activity_error_boundary.py`** — the `convert_pipelex_errors` decorator. Catches `PipelexError` raised inside an activity and re-raises it as `TemporalError.from_message_exception(exc)`.
-- **All in-scope activities wired.** `@convert_pipelex_errors` is applied beneath `@activity.defn` on `act_llm_gen_text` / `act_llm_gen_object` / `act_llm_gen_object_list`, `act_img_gen_images`, `act_extract_gen_extract_pages`, `act_jinja2_gen_text`, `act_render_page_views`, `act_deliver`, `act_flush_trace_events`. `act_assemble_graph` is deliberately **not** wired (Decision 2) — it carries a one-line comment saying so.
-- **`pipelex/temporal/tprl/temporal_error.py`** — `_log_critical` / `_log_error` branch inline on `activity.in_activity()` to pick `activity_log` vs `workflow_log` (Decision 3, landed in Phase 2). There is **no `_context_logger()` helper** — a code-review pass removed it (its `WorkflowLog | ActivityLog` union return was a type smell).
-- **`tests/integration/pipelex/temporal/test_activity_error_boundary.py`** — integration test, two probe workflows (LLM `act_llm_gen_text` + non-LLM `act_extract_gen_extract_pages`), all cases passing.
-- **`tests/unit/pipelex/temporal/test_activity_error_boundary.py`** (new) — decorator unit test pinning the `functools.wraps` invariants and the `PipelexError`-only catch.
-- **`tests/unit/pipelex/temporal/test_temporal_error_bridge.py`** — added `test_log_helpers_route_to_the_active_temporal_context`; the `log_mocks` fixture is no longer `autouse` (the routing test needs the real helpers) — the other tests opt in explicitly.
-- **`CHANGELOG.md`** — `[Unreleased]` entry added. **`wip/error-handling/track-temporal-integration.md`** — Followup 5 marked landed. The stub `wip/error-handling/todos-temporal-activity-boundary.md` was deleted.
-
-`make agent-check` is clean; the full temporal suite (`tests/unit/pipelex/temporal/ tests/integration/pipelex/temporal/`) is green.
-
-The detailed Phase 0/1/2 sections below are the **historical TDD record** — already implemented; do not redo them. Where this doc's early code sketches differ from the repo, **the committed files are authoritative**.
-
-Commits: `8acdae1f` (plan) → `ee0e7852` (Phase 0 decisions) → `e0580e89` (Phase 1 RED) → `3bb28ae4` (Phase 2 GREEN) → `18e0135b` (code-review fixes) → `cda61bae` (Phase 3 wiring + Phase 4 docs/tests).
-
----
-
-## The gap
-
-Phase 6 built `TemporalError.from_message_exception()` — category-aware retry decisions (`InferenceErrorCategory.is_retryable`) plus packing `to_error_report().to_dict()` into `ApplicationError.details`. **No activity calls it.** The activity functions in `pipelex/temporal/tprl_content_generation/act_*.py` and `pipelex/temporal/tprl_pipe/act_*.py` raise raw `CogtError` / `PipelexError`. Temporal's default failure converter auto-wraps them: it does not pack our `ErrorReport` into `details` and leaves `non_retryable=False`.
-
-Net effect in production today:
-
-- On the workflow side, `TemporalError.from_app_error()` always lands in its `error_report is None` fallback branch (`temporal_error.py:95`). The structured `ErrorReport` — `error_category`, `user_action`, `model`, `provider` — is lost.
-- The category-aware retry decision (`_is_non_retryable`) never runs. A non-retryable `CogtError` (`CONFIGURATION`, `CONTENT`, `CAPACITY`) is treated as retryable unless its class name happens to be in the static `non_retryable_error_types` list — which `CogtError` is not.
-
-Phase 6's logic is built but dead. This task wires it in.
-
-This is the Temporal-side twin of the non-Temporal `PipeRouter` retry-bypass fixed in PR #903.
-
----
-
-## Key files
-
-- **Bridge (do not change — Phase 6 landed it):** `pipelex/temporal/tprl/temporal_error.py` — `from_message_exception` (line 109), `from_app_error` (line 82), `_is_non_retryable` (line 134).
-- **Activity entry points to convert:**
- - `pipelex/temporal/tprl_content_generation/act_llm_generate.py` — `act_llm_gen_text`, `act_llm_gen_object`, `act_llm_gen_object_list`
- - `pipelex/temporal/tprl_content_generation/act_img_gen_generate.py` — `act_img_gen_images`
- - `pipelex/temporal/tprl_content_generation/act_extract_generate.py` — `act_extract_gen_extract_pages`
- - `pipelex/temporal/tprl_content_generation/act_jinja2_generate.py` — `act_jinja2_gen_text`
- - `pipelex/temporal/tprl_content_generation/act_render_page_views.py` — `act_render_page_views`
- - `pipelex/temporal/tprl_pipe/act_deliver.py` — `act_deliver`
- - `pipelex/temporal/tprl_pipe/act_flush_trace_events.py` — `act_flush_trace_events` (see Decision 2)
-- **Workflow side (already calls `from_app_error`):** `content_generator_in_workflow.py` (nine call sites), `wf_pipe_router.py:135`.
-- **Existing unit test:** `tests/unit/pipelex/temporal/test_temporal_error_bridge.py` — proves the bridge round-trips in isolation; never crosses a real activity → workflow boundary.
-- **Failure-path integration test pattern to mirror:** `tests/integration/pipelex/temporal/test_wf_pipe_run_failure_path.py` — constructs a `Worker` directly, registers a stub workflow + activity, drives it through `temporal_client.execute_workflow`.
-- **Retry config:** `pipelex/temporal/config_temporal.py` — `RetryPolicyConfig.non_retryable_error_types` / `non_retryable_error_types_extra` (name-based fallback).
-
----
-
-## Phase 0 — Resolve design decisions (do this first, record the outcome here)
-
-These must be settled before writing code. Each has a recommendation; confirm or override and write the decision back into this doc.
-
-### Decision 1 — Per-activity `try/except` vs. shared decorator
-
-**Option A — per-activity `try/except`.** Every `@activity.defn` function body wraps its call:
-
-```python
-async def act_llm_gen_text(llm_assignment: LLMAssignment) -> str:
- log.dev("act_llm_gen_text")
- try:
- return await llm_gen_text(llm_assignment=llm_assignment)
- except PipelexError as exc:
- raise TemporalError.from_message_exception(exc=exc) from exc
-```
-
-- Pro: explicit, no decorator-ordering subtlety.
-- Con: repeated in every activity; easy to forget on the next activity added; multi-statement activities (`act_render_page_views`, `act_img_gen_images`) need the whole body wrapped.
-
-**Option B — shared decorator (RECOMMENDED).** A single `@convert_pipelex_errors` decorator applied beneath `@activity.defn`:
-
-```python
-@convert_pipelex_errors
-async def act_llm_gen_text(llm_assignment: LLMAssignment) -> str:
- log.dev("act_llm_gen_text")
- return await llm_gen_text(llm_assignment=llm_assignment)
-```
-
-- Pro: one conversion point; cannot be forgotten; the whole activity body is covered with no indentation churn.
-- Con: decorator ordering matters — it must sit *below* `@activity.defn` so Temporal sees the wrapped function; the wrapper must use `functools.wraps` so `@activity.defn` still resolves the original name and signature (Temporal's `inspect.signature` follows `__wrapped__`).
-
-**Recommendation: Option B.** New module `pipelex/temporal/tprl/activity_error_boundary.py` exposing `convert_pipelex_errors`. It catches `PipelexError` only (never `Exception` — the project bans the generic catch) and re-raises `TemporalError.from_message_exception(exc=exc) from exc`. A non-`PipelexError` propagates untouched and Temporal's default converter handles it as before.
-
-> **DECISION:** Option B — shared decorator `convert_pipelex_errors` in `pipelex/temporal/tprl/activity_error_boundary.py`.
-
-### Decision 2 — Which activities get the boundary
-
-- `act_assemble_graph` (`tprl_pipe/act_assemble_graph.py`) **must NOT be wired.** It already wraps its body in `except Exception` (best-effort observability) and degrades to `return None` — it never propagates an error across the boundary. Converting it would be dead code. Leave it; note it explicitly so a future reader does not "fix" the omission.
-- `act_flush_trace_events` (`tprl_pipe/act_flush_trace_events.py`) **does** propagate errors and is observability-only. **Recommendation: wire it** for consistency — a failed flush is a real error and should carry a structured report — but flag it as the lowest-value target. If the team prefers it stay best-effort, that is a separate decision (make it swallow like `act_assemble_graph`), out of scope here.
-
-> **DECISION:** Wire `act_flush_trace_events`; leave `act_assemble_graph` unwired (it already swallows and degrades to `None`).
-
-### Decision 3 — `from_message_exception` logs through `workflow_log` but runs activity-side
-
-`from_message_exception` calls `cls._log_critical` / `cls._log_error`, which call `workflow_log.*` (`WorkflowLog` → `workflow.logger`). But `from_message_exception` runs **inside an activity**, not a workflow. `workflow.logger` outside a workflow context logs without workflow metadata (it does not crash — `workflow` runtime is simply absent), so it is not a hard bug, but it is semantically wrong and routes activity-side log lines through the workflow logger.
-
-**Recommendation:** out of scope for the *wiring* but record it. Either (a) leave as-is and note it, or (b) small follow-up: make `_log_critical` / `_log_error` pick `activity_log` when `activity.in_activity()` is true, else `workflow_log`. Do **not** silently change Phase 6 bridge behavior inside this task without calling it out — the bridge unit test patches `_log_critical` / `_log_error` and would still pass, so the change is safe but should be deliberate.
-
-> **DECISION:** Option (b) — fix it in this task. ✅ Done in Phase 2. `_log_critical` / `_log_error` branch inline on `activity.in_activity()` to select `activity_log` vs `workflow_log`. **Pulled forward into Phase 2** — it turned out to be a hard blocker, not a nicety: `workflow.logger` raises `_NotInWorkflowEventLoopError` (not a silent no-op) outside a workflow event loop, so `from_message_exception` crashed the moment an activity called it. (An interim `_context_logger()` helper was tried, then removed in code review: returning `WorkflowLog | ActivityLog` — two unrelated concrete classes — was the type smell the project's Protocols rule warns against; the branch is inlined instead.) The bridge unit test still passes (it patches both helpers). A dedicated unit test asserting the activity-context branch picks `activity_log` is still **TODO in Phase 4**.
-
----
-
-## Phase 1 — RED: failing integration test across a real activity → workflow boundary ✅ DONE
-
-> ✅ **Implemented and committed.** The section below is the historical record. The committed `tests/integration/pipelex/temporal/test_activity_error_boundary.py` is authoritative — it differs from the sketch below in spots refined during the Phase 2 code review (e.g. the probe workflow raises a descriptive `TypeError` on a non-`ApplicationError` cause; the category-less case asserts `"retryable" not in error_report`).
-
-Goal: a test that drives a **real activity** through a **real Temporal worker**, has the activity raise a real `CogtError`, and asserts what `from_app_error` receives on the workflow side. It must **fail today** (fallback branch) and **pass after Phase 2/3**.
-
-### Files
-
-- `tests/integration/pipelex/temporal/test_activity_error_boundary.py` — one `TestClass`, per the pytest standards.
-
-### Test workflow + result model (defined in the test module)
-
-A minimal probe workflow that executes one real activity, catches `ActivityError`, runs `from_app_error`, and **returns** the observed `non_retryable` + `error_report` (returns rather than re-raises, so the test can assert on the payload):
-
-```python
-class ErrorBoundaryProbeResult(BaseModel):
- non_retryable: bool
- error_report: dict[str, Any] | None
-
[email protected](name="wf_error_boundary_probe")
-class WfErrorBoundaryProbe:
- @workflow.run
- async def run(self, llm_assignment: LLMAssignment) -> ErrorBoundaryProbeResult:
- try:
- await workflow.execute_activity(
- act_llm_gen_text,
- arg=llm_assignment,
- start_to_close_timeout=timedelta(seconds=30),
- # maximum_attempts=1 so a (today wrongly) retryable error does
- # not loop and hang the test — we only care about the first hop.
- retry_policy=RetryPolicy(maximum_attempts=1),
- )
- except ActivityError as exc:
- if isinstance(exc.cause, ApplicationError):
- temporal_error = TemporalError.from_app_error(exc=exc.cause)
- return ErrorBoundaryProbeResult(
- non_retryable=temporal_error.non_retryable,
- error_report=temporal_error.error_report,
- )
- raise
- raise AssertionError("activity was expected to fail")
-```
-
-### Making the real activity raise a real `CogtError`
-
-The test worker runs **in-process** (same process as the test), so the activity's module-level reference can be patched. The activity imports `llm_gen_text` into its own module namespace — patch it there:
-
-```python
-mocker.patch(
- "pipelex.temporal.tprl_content_generation.act_llm_generate.llm_gen_text",
- side_effect=CogtError("simulated", error_category=InferenceErrorCategory.CONFIGURATION),
-)
-```
-
-Use an `async` mock (`side_effect` on an `AsyncMock`, via `mocker.patch(..., new=mocker.AsyncMock(side_effect=...))`) so `await llm_gen_text(...)` works.
-
-### Worker construction
-
-Mirror `test_wf_pipe_run_failure_path.py`: build a `Worker` directly with a unique `task_queue`, register `WfErrorBoundaryProbe` and the real `act_llm_gen_text`, `workflow_runner=UnsandboxedWorkflowRunner()`. Drive it with `temporal_client.execute_workflow(...)` using a fresh `workflow_id`.
-
-### Test cases (parametrized)
-
-| Case | Activity raises | Expected `non_retryable` | Expected `error_report` |
-|---|---|---|---|
-| `configuration-non-retryable` | `CogtError(error_category=CONFIGURATION)` | `True` | populated, `error_category == CONFIGURATION` |
-| `transient-retryable` | `CogtError(error_category=TRANSIENT)` | `False` | populated, `retryable is True` |
-| `category-less-fallback` | `CogtError()` (no category) | `False` (name-list fallback, `CogtError` unlisted) | populated, `error_type == "CogtError"` |
-
-Strong asserts: check the actual `error_report["error_category"]`, `error_report["retryable"]`, `error_report["error_type"]`, `error_report["message"]` — not just "is not None".
-
-### Markers
-
-`@pytest.mark.temporal`, `@pytest.mark.asyncio(loop_scope="class")`. No `inference`/`llm` marker — the LLM call is mocked away, never reaches a provider.
-
-### Confirm RED
-
-Run the new test against today's code:
-
-```bash
-.venv/bin/pytest tests/integration/pipelex/temporal/test_activity_error_boundary.py -q
-```
-
-Expected failure today: `error_report is None` (Temporal's default converter packed no `details`) and `non_retryable is False` even for the `CONFIGURATION` case (auto-wrap leaves `non_retryable=False`; `from_app_error`'s name-list fallback does not list `CogtError`). Record the exact failure output here, then proceed.
-
-> **CHECKPOINT 1 — RED confirmed.** ✅ Test `tests/integration/pipelex/temporal/test_activity_error_boundary.py` written and committed. All 3 parametrized cases fail for the documented reason — the workflow side observed `ErrorBoundaryProbeResult: non_retryable=False error_report=None` (log line `Error from ApplicationError[CogtError]: ...` confirms `from_app_error` hit the name-list fallback). The test asserts `error_report is not None` (fails) and, for `configuration-non-retryable`, `non_retryable is True` (fails — got `False`). The worker → activity → workflow boundary mechanics all work; `make agent-check` clean. Phase 0 decisions recorded above. Next session: Phase 2.
-
----
-
-## Phase 2 — GREEN (minimal): wire one activity, make the test pass ✅ DONE
-
-> ✅ **Implemented and committed.** The section below is the historical record. See CHECKPOINT 2 for the as-built outcome.
-
-Implement the decision from Phase 0. For Option B (recommended):
-
-### Step 2.1 — `convert_pipelex_errors` decorator
-
-New file `pipelex/temporal/tprl/activity_error_boundary.py`:
-
-- `convert_pipelex_errors` — wraps an `async` activity function with `functools.wraps`. Body: `try: return await func(*args, **kwargs)` / `except PipelexError as exc: raise TemporalError.from_message_exception(exc=exc) from exc`.
-- Typing: parametrize with a `ParamSpec` and return `TypeVar` so the wrapped signature is preserved for the type checker and for Temporal's signature inspection. (`ParamSpec` is available on 3.10 via `typing` — fine.)
-- Catch `PipelexError` only. Never `except Exception` — see CLAUDE.md error-handling rules. A non-`PipelexError` propagates unchanged.
-- No speculative handling: the decorator only converts; it does not log, swallow, or add fallbacks.
-
-### Step 2.2 — Apply to `act_llm_gen_text` only
-
-Add `@convert_pipelex_errors` beneath `@activity.defn` on `act_llm_gen_text`. Leave the other activities for Phase 3 — Phase 2 is the minimal change that turns the test green for the one activity the probe exercises.
-
-### Step 2.3 — Verify GREEN
-
-```bash
-.venv/bin/pytest tests/integration/pipelex/temporal/test_activity_error_boundary.py -q
-make agent-check
-```
-
-All three Phase 1 cases must pass: `CONFIGURATION` → `non_retryable True` + populated report; `TRANSIENT` → `non_retryable False`; category-less → `non_retryable False` + report present.
-
-> **CHECKPOINT 2 — GREEN for one activity.** ✅ Done. `convert_pipelex_errors` lives in `pipelex/temporal/tprl/activity_error_boundary.py`; applied beneath `@activity.defn` on `act_llm_gen_text`. All 3 integration cases pass; the bridge unit test still passes; `make agent-check` clean. Decision 3's logger fix was pulled forward (see above) — it was a hard blocker. A code-review pass followed: the `_context_logger()` helper was dropped (its `WorkflowLog | ActivityLog` union return was the smell the Protocols rule warns against) — the context branch is now inlined into `_log_critical` / `_log_error`; the probe workflow now fails loudly on a non-`ApplicationError` cause; the category-less case now asserts the report carries no `retryable` key. The bridge is proven live across a real worker boundary; the mechanism is settled. Phase 3 is mechanical replication. Next session: Phase 3.
-
----
-
-## Phase 3 — Wire the remaining activities ✅ DONE
-
-Applied the shared `@convert_pipelex_errors` decorator (Decision 1, Option B) to every remaining in-scope activity:
-
-- [x] `act_llm_gen_object`, `act_llm_gen_object_list` (`act_llm_generate.py`)
-- [x] `act_img_gen_images` (`act_img_gen_generate.py`)
-- [x] `act_extract_gen_extract_pages` (`act_extract_generate.py`)
-- [x] `act_jinja2_gen_text` (`act_jinja2_generate.py`)
-- [x] `act_render_page_views` (`act_render_page_views.py`)
-- [x] `act_deliver` (`act_deliver.py`)
-- [x] `act_flush_trace_events` (`act_flush_trace_events.py`) — per Decision 2
-- [x] `act_assemble_graph` — **deliberately NOT wired** (Decision 2). Carries a one-line comment stating why, so the omission reads as intentional.
-
-### Extend the integration test
-
-Add at least one more probe workflow + case covering a non-LLM activity — `act_img_gen_images` or `act_extract_gen_extract_pages` — patching its inner generate function to raise a `CogtError`. This proves the wiring is not LLM-specific. Keep it in the same `TestClass` (one class per module); add a second probe workflow class at module scope and a parametrized case, or a second test method.
-
-Also confirm no double-wrapping: `content_generator_in_workflow.py` and `wf_pipe_router.py` already call `from_app_error` on the workflow side — that is the *receiving* end and is correct. The activity side had no conversion before; there is nothing to un-wrap. Verify no activity already has a competing `try/except` that would convert differently.
-
-### Add a dedicated decorator unit test
-
-`convert_pipelex_errors`'s correctness hinges on `functools.wraps` preserving `__name__` (load-bearing — `content_generator_in_workflow.py` reads `act_llm_gen_text.__name__` for dispatch routing) and `__annotations__` (Temporal's `@activity.defn` reads them for payload typing). Add a unit test (`tests/unit/pipelex/temporal/test_activity_error_boundary.py`) that wraps a sample async function and asserts: the wrapped callable keeps the original `__name__`; a raised `PipelexError` comes out as a `TemporalError`; a non-`PipelexError` propagates untouched. This pins the invariant a future non-`wraps` refactor would silently break (code-review finding #3, deferred from Phase 2).
-
-### Verify ✅ DONE
-
-The integration test gained a second probe workflow (`WfExtractErrorBoundaryProbe`) over the non-LLM `act_extract_gen_extract_pages`, plus a shared `_probe_result_from_activity_error` helper. The decorator unit test (`tests/unit/pipelex/temporal/test_activity_error_boundary.py`) was added. No double-wrapping: the activity side had no prior conversion. `make agent-check` clean; targeted temporal suite green.
-
----
-
-## Phase 4 — REFACTOR + docs ✅ DONE
-
-- [x] Decorator order is identical everywhere (`@activity.defn` above `@convert_pipelex_errors`); `make fix-unused-imports` / `make agent-check` clean.
-- [x] `convert_pipelex_errors` docstring states it is the activity-side half of the bridge, names `from_app_error` as the workflow-side half, and that it catches `PipelexError` (not `Exception`) by design.
-- [x] Added `test_log_helpers_route_to_the_active_temporal_context` to `test_temporal_error_bridge.py` — asserts `_log_critical` / `_log_error` route to `activity_log` when `activity.in_activity()` is true and `workflow_log` otherwise. The `log_mocks` fixture is no longer `autouse` (this new test needs the real helpers); the other tests opt in explicitly.
-- [x] `CHANGELOG.md` — `[Unreleased]` entry added (covers the boundary wiring and the logger fix).
-- [x] `wip/error-handling/track-temporal-integration.md` — Followup 5 marked landed. Stub `wip/error-handling/todos-temporal-activity-boundary.md` deleted.
-
----
-
-## Phase 5 — Full verification
-
-- [x] `make agent-check` — clean.
-- [x] Targeted temporal suite (`tests/unit/pipelex/temporal/ tests/integration/pipelex/temporal/`) — green.
-- [x] `make agent-test` — full suite green (exit 0).
-- [ ] Optionally, against a real server: `.venv/bin/pytest tests/integration/pipelex/temporal/test_activity_error_boundary.py --temporal-server local` — confirms cross-process serialization (the in-process test server already exercises the real failure converter, so this is a confidence check, not strictly required).
-- [ ] Watch for zombie Temporal processes if a run stalls (project memory `feedback_test_timeouts`).
-
----
-
-## Out of scope
-
-- Changing the bridge methods `from_message_exception` / `from_app_error` themselves — Phase 6 landed them; only the wiring is missing. (Decision 3 is the one allowed, deliberate, called-out exception.)
-- The non-Temporal `PipeRouter` retry path — that is PR #903.
-- Making `act_assemble_graph` propagate errors — it is intentionally best-effort.
-- Extending `error_category` to non-`CogtError` `PipelexError` subclasses — that is [track-metadata-model.md](track-metadata-model.md); the name-list fallback covers them until then.
-
----
-
-## Risks / gotchas
-
-- **Decorator order.** `@convert_pipelex_errors` must be *below* `@activity.defn`. If placed above, Temporal registers the wrapper and `from_message_exception` never runs. `functools.wraps` is mandatory so Temporal resolves the activity name and argument types.
-- **Async mock.** The inner generate functions are `async`; patch with an async-capable mock or `await` fails before the `CogtError` is raised.
-- **Patch target.** Activities do `from pipelex.cogt... import llm_gen_text` — patch the *activity module's* name, not the source module's.
-- **Retry loop hang.** Without `maximum_attempts=1` on the probe's activity retry policy, a `TRANSIENT` (retryable) case retries until timeout and the test hangs. Always pin it.
-- **`non_retryable` is the inverse of `is_retryable`.** `ApplicationError(non_retryable=True)` ⇔ `category.is_retryable is False`. The bridge already handles this (`temporal_error.py:137`); just keep it straight when writing assertions.
diff --git a/wip/error-handling/archive-temporal-submitter-boundary.md b/wip/error-handling/archive-temporal-submitter-boundary.md
deleted file mode 100644
index 0d9f2d62b..000000000
--- a/wip/error-handling/archive-temporal-submitter-boundary.md
+++ /dev/null
@@ -1,179 +0,0 @@
-# Archive — Recover the structured error report across the Temporal submitter & child-workflow boundaries
-
-> **ARCHIVED 2026-05-17 — COMPLETE.** Both plans below landed in full (#912 submitter boundary, #911-adjacent child-workflow boundary) and were moved here from the repo-root `TODOS.md`. Kept for their full trace, root-cause analysis, TDD record, and eng-review history. The authoritative current-state summary lives in [track-temporal-integration.md](track-temporal-integration.md) ("Submitter-side report recovery (landed)" and "Child-workflow boundary recovery (landed)"); where this archive's pre-implementation sketches differ from the repo, the committed code is authoritative.
-
-## [done] Recover the structured error report across the Temporal submitter boundary
-
-**Status:** done (landed 2026-05-17 on `feature/Temporal-error-report`) · **Filed:** 2026-05-17 · **Severity:** medium — correctness degradation under distributed execution; no crash, graceful fallback to a generic error.
-**Area:** error handling — Temporal integration; the symptom surfaces in CLI delivery.
-**Tracks:** primary home is `wip/error-handling/track-temporal-integration.md` (Open gaps); cross-referenced from `wip/error-handling/track-cli-delivery.md`. Context on the activity-side half of the bridge: `wip/error-handling/archive-temporal-activity-boundary.md` (the #911 work).
-
-### TL;DR
-
-When a pipe fails inside a Temporal worker, the structured `ErrorReport` (`error_category`, `retryable`, `model`, `provider`, specific `user_action`, `provider_metadata`) is correctly carried across the activity → workflow boundary but is dropped on the workflow → submitter → CLI hop. The agent — and any HTTP adapter — receives a generic `PipelineExecutionError` with message `"Failed to execute workflow WfPipeRun"` and no classification, where the same pipe failing locally yields a fully classified error. The rich report is not lost: it survives intact inside `ApplicationError.details` on the deserialized failure that reaches the submitter. The fix is to recover it there, so the existing "delivery consumes `to_error_report()`" contract keeps holding for distributed runs.
-
-### Symptom
-
-Run an agent-CLI pipe command (`pipelex-agent run pipe|bundle|method`) with Temporal enabled (`temporal.is_enabled = true` in config, or the `--temporal` flag), against a pipe that fails on a worker — an LLM rate limit, an unavailable model, any `CogtError`. The error payload the agent receives:
-
-```json
-{
- "error": true,
- "error_type": "PipelineExecutionError",
- "message": "Failed to execute workflow WfPipeRun",
- "error_domain": "runtime",
- "pipe_code": "<the pipe>",
- "cause_type": "WorkflowExecutionError",
- "cause_message": "Failed to execute workflow WfPipeRun"
-}
-```
-
-The identical pipe failing in local (non-Temporal) execution yields `error_category`, `retryable`, `model`, `provider`, a specific `user_action`/hint, and the real failure message. Distributed execution silently produces a strictly worse error — exactly when the operator has the least visibility into the worker.
-
-### Impact / blast radius
-
-The defect is in shared `ErrorReport` production, not in any one renderer, so it affects every `to_error_report()` / `ErrorReport` consumer once execution is distributed:
-
-- **Agent CLI** (`pipelex-agent`) — JSON and markdown error payloads lose hint, domain, category, retryable, model, provider. This is the concretely traced path. Affects all of `run pipe`, `run bundle`, `run method` (they share `run_pipeline_core` → `PipelexRunner`).
-- **Human Rich CLI** (`pipelex`) — the per-error-type handlers in `pipelex/cli/error_handlers.py` render off the same exceptions; a Temporal-run failure shows as a generic panel.
-- **HTTP API adapters** (`pipelex-relay`, `pipelex-back-office`) — `ErrorReport.http_status` drives the status code. A provider 429 raised on a worker collapses to a generic `RUNTIME` → 500, and the `Retry-After` header (sourced from `provider_metadata.retry_after_seconds`) is lost, because `provider_metadata` never makes it into the submitter-side report.
-
-Not affected: the `_agent_cli_output_format` `ContextVar`. See "What is NOT the bug" below.
-
-### Full trace
-
-#### Local execution — works
-
-1. A pipe operator raises a `CogtError` (e.g. `LLMCompletionError`), carrying `error_category` / `model` / `provider`.
-2. It is wrapped on the way up: `PipeRunError` → `PipeRouterError` — all `PipelexError` instances, all live Python objects in the `__cause__` chain.
-3. `PipelexRunner.execute_pipeline` catches `PipeRouterError` (`pipelex/pipeline/runner.py:154`) and raises `PipelineExecutionError(message=exc.message, ...) from exc`.
-4. The agent CLI catches `PipelineExecutionError` (`pipelex/cli/agent_cli/commands/run/pipe_cmd.py:155`) and calls `agent_error(exc.message, "PipelineExecutionError", cause=exc, ...)`.
-5. `agent_error` → `_assemble_error_payload` (`pipelex/cli/agent_cli/commands/agent_output.py:192-202`) calls `cause.to_error_report()`. `PipelineExecutionError.to_error_report()` → `PipelexError._enrich_error_report_from_cause` walks the `__cause__` chain, every link is a `PipelexError`, reaches the `CogtError`, and inherits its full classification. **Rich payload.**
-
-#### Temporal execution — broken
-
-1. A pipe operator raises the same `CogtError`, but **inside a Temporal activity**.
-2. `convert_pipelex_errors` (`pipelex/temporal/tprl/activity_error_boundary.py:52`) wraps it as `TemporalError.from_message_exception(exc)` — a `TemporalError` (subclass of `temporalio.exceptions.ApplicationError`) with `to_error_report().to_dict()` packed into `ApplicationError.details` and `non_retryable` derived from the inference category.
-3. Temporal serializes the failure (default failure converter — see the `activity_error_boundary.py` module docstring for why the `details` packing exists). Workflow code re-wraps via `TemporalError.from_app_error` (`pipelex/temporal/tprl_pipe/wf_pipe_router.py:135`). The workflow fails.
-4. **Submitter side:** `WorkflowExecutor.execute_workflow` (`pipelex/temporal/tprl/workflow_caller.py:90`) — `client.execute_workflow` raises `WorkflowFailureError`, whose `.cause` is the deserialized `ApplicationError` still carrying `.details` (the report dict). The `except` at `workflow_caller.py:122` discards all of that: `raise WorkflowExecutionError("Failed to execute workflow WfPipeRun") from exc`.
-5. `WorkflowExecutionError` (`pipelex/temporal/exceptions.py:12`, a `TemporalFlowError` → `PipelexError`) has no class-level `error_domain` / `user_action`. Its `__cause__` is `WorkflowFailureError` — **not** a `PipelexError`.
-6. `TemporalPipeRun.run` (`pipelex/temporal/tprl_pipe/temporal_pipe_run.py:49`) has no try/except — `WorkflowExecutionError` propagates straight through.
-7. `PipelexRunner.execute_pipeline` catches it at the `except PipelexError` arm (`pipelex/pipeline/runner.py:172`) and raises `PipelineExecutionError(message=exc.message, ...) from exc` — `exc.message` is `"Failed to execute workflow WfPipeRun"`.
-8. The agent CLI catches `PipelineExecutionError` and calls `agent_error(...)` as in the local case.
-9. `to_error_report()` → `_enrich_error_report_from_cause` walks: `PipelineExecutionError.__cause__` = `WorkflowExecutionError` (a `PipelexError` ✓, but empty) → `WorkflowExecutionError.__cause__` = `WorkflowFailureError` (**✗ not a `PipelexError`**). The walk stops. Report floors to generic `RUNTIME` / `UNKNOWN`. **Degraded payload.**
-
-### Root cause
-
-`PipelexError._enrich_error_report_from_cause` in `pipelex/base_exceptions.py:127`:
-
-```python
-cause = self.__cause__
-if not isinstance(cause, PipelexError):
- return report # <-- base_exceptions.py:137-138
-```
-
-The chain-enrichment that makes wrapper exceptions inherit classification operates purely on **live `PipelexError` objects linked via `__cause__`**. Temporal serialization breaks that precondition: it destroys the original `CogtError` Python object and replaces it with a `temporalio` `ApplicationError` (not a `PipelexError`), inserting a `WorkflowFailureError` link in between. The walk terminates at that link. The data the walk wanted is intact but is now inert dict data in `ApplicationError.details`, a representation `_enrich_error_report_from_cause` knows nothing about.
-
-`ErrorReport` is explicitly the single source of truth "used by CLI JSON output, agent output, and Temporal error details" (`base_exceptions.py:56-59`). The activity → workflow half of the bridge already moves it through `ApplicationError.details`; the missing half is recovering it from `details` once back on the submitter, so it re-enters the `to_error_report()` world.
-
-### What is NOT the bug
-
-The `_agent_cli_output_format` `ContextVar` (`pipelex/cli/agent_cli/commands/agent_output.py:33`) is sound and needs no change. It is set by `set_agent_cli_output_format()` at the top of each command (`run/pipe_cmd.py:73`, etc.) and read by `agent_error` / `agent_success_formatted` after the pipe call returns — all within the **same submitter/CLI process, same root async context**. Temporal distributes pipe *execution* to worker processes; it never distributes CLI *rendering*. Workers never import `agent_output.py` and never read this ContextVar, so there is nothing to propagate across the Temporal boundary. Do not spend time "fixing" the ContextVar — the gap is the report data, not the format plumbing. (This was the original question that surfaced the real bug; recorded here so a cold start does not re-investigate it.)
-
-### Fix
-
-#### Option A — recover the report at the submitter boundary (recommended)
-
-Repair the data at its source so every downstream consumer (agent CLI, Rich CLI, HTTP adapters) is fixed at once, and `pipelex/cli/agent_cli/` stays Temporal-agnostic.
-
-1. **Add `ErrorReport.from_dict`** in `pipelex/base_exceptions.py` — the inverse of the existing `to_dict` (`base_exceptions.py:71`). Mirror it: `TypeAdapter(cls).validate_python(data)`. Verify the nested `UserAction` and `ProviderErrorMetadata` round-trip cleanly (they are dumped with `mode="python", exclude_none=True`). Keep it **strict** — `ErrorReport` is `extra="forbid"`, so `from_dict` raises `pydantic.ValidationError` on a malformed or schema-drifted dict. That is the correct behavior for a pure inverse; robustness against that failure lives at the recovery call site (step 2a), not inside `from_dict`.
-2. **Recover the report at `WorkflowExecutor.execute_workflow`** (`pipelex/temporal/tprl/workflow_caller.py:122`). Split the combined `except (WorkflowAlreadyStartedError, RPCError, WorkflowFailureError)` handler into a **dedicated `except WorkflowFailureError as exc:` clause** (report recovery) plus a combined `except (WorkflowAlreadyStartedError, RPCError) as exc:` clause (generic, `error_report=None`) — the two failure kinds get genuinely different handling, so they get separate clauses rather than an `isinstance` branch. In the `WorkflowFailureError` clause, walk its `.cause` / `__cause__` chain for an `ApplicationError` whose `.details` matches the report shape and rebuild an `ErrorReport`. Reuse the existing detection helper — **rename `_error_report_from_details` (`temporal_error.py:14`) to a public name** (e.g. `error_report_dict_from_details`), since it now has callers in two modules, and update its existing `from_app_error` caller.
-2a. **Guard the recovery against bad data.** `from_dict` is strict, so a malformed or version-skewed `details` dict makes it raise `ValidationError` — and this runs on the submitter's error path, so an unguarded raise turns a degraded-but-classified error into a hard crash. At the recovery call site, catch `ValidationError` and fall back to today's generic `WorkflowExecutionError` (`error_report=None`). Additionally, drop unknown keys from the recovered dict before calling `from_dict`, so a report serialized by a *newer* Pipelex worker (extra field) degrades silently — mirroring how `error_domain_to_http_status` / `ErrorReport.http_status` already tolerate an unrecognized `error_domain`. Worker/submitter version skew is normal during a rolling deploy.
-3. **Carry the recovered report on `WorkflowExecutionError`** — *design decision: option (a), see "Resolved design decision" below.* Give it an optional `error_report: ErrorReport | None` constructor arg + attribute, and override `to_error_report()` to return / enrich from the recovered report when present. When `error_report` is `None`, the override must fall through to base behavior — build the wrapper report and end with `self._enrich_error_report_from_cause(report)` per the contract in `base_exceptions.py:117`. The `WorkflowAlreadyStartedError` / `RPCError` clause passes `error_report=None`, so its behavior is unchanged.
-4. **Propagate the real message.** Construct the `WorkflowExecutionError` with the original failure message (from the recovered `ErrorReport.message`, or equivalently `ApplicationError.message`), not the generic `"Failed to execute workflow WfPipeRun"`. `PipelineExecutionError(message=exc.message, ...)` copies the wrapper message upward, so without this the agent still sees the generic message even after classification is restored — local execution propagates the real message, and Temporal should match.
-5. No change needed in `PipelexRunner` or `agent_output.py`: once `WorkflowExecutionError.to_error_report()` returns a populated report, `PipelineExecutionError._enrich_error_report_from_cause` inherits it natively (`WorkflowExecutionError` is a `PipelexError`, so the existing walk includes it).
-
-**Resolved design decision (eng review 2026-05-17):** `WorkflowExecutionError` holds the `ErrorReport` as an optional attribute and overrides `to_error_report()` — option (a). Rejected (b) (a `RemotePipelexError` carrier in the `__cause__` chain): although (b) needs no override, it forces a new public exception class plus manual `__cause__` wiring to keep the Temporal `WorkflowFailureError` in the traceback, whereas (a) keeps `raise WorkflowExecutionError(msg) from exc` so the Temporal failure stays in the chain for free, and the override is the same 3-line pattern `PipelineExecutionError.to_error_report()` already uses. Mirror this decision into `wip/error-handling/track-cli-delivery.md`.
-
-#### Option B — read `ApplicationError.details` in the delivery layer
-
-Make `_assemble_error_payload` (`pipelex/cli/agent_cli/commands/agent_output.py:171`) walk `cause.__cause__` for an `ApplicationError` with a details-packed report and prefer it over the outer exception's `to_error_report()`.
-
-Rejected as the primary fix: it pulls a `temporalio` dependency and Temporal-shape knowledge into the CLI delivery layer, duplicates `_error_report_from_details`, and fixes only the agent CLI — the Rich CLI and the HTTP adapters would still see the degraded report. Keep it in mind only as a fallback if Option A proves infeasible.
-
-### Implementation checklist
-
-- [x] `ErrorReport.from_dict` added (strict inverse of `to_dict`) and unit-tested for round-trip, including nested `UserAction` / `ProviderErrorMetadata` and a `provider_metadata` 429.
-- [x] `_error_report_from_details` renamed to `error_report_dict_from_details` and reused (not duplicated) on the submitter side; existing `from_app_error` caller updated.
-- [x] `execute_workflow`'s combined `except` split into a dedicated `except WorkflowFailureError` clause + a combined `except (WorkflowAlreadyStartedError, RPCError)` clause.
-- [x] Recovery guarded: a `ValidationError` from `from_dict` falls back to a generic `WorkflowExecutionError`; unknown keys dropped before validating (version-skew tolerance).
-- [x] `WorkflowExecutionError` carries and exposes the recovered report via option (a) — attribute + `to_error_report()` override that falls through to base `_enrich_error_report_from_cause` when no report is present; the no-report arms left intact.
-- [x] Real failure message propagated (Option A step 4).
-- [x] Decision (a)/(b) recorded — done in this doc ("Resolved design decision") and mirrored into `wip/error-handling/track-cli-delivery.md`.
-- [x] `track-temporal-integration.md` "Open gaps" updated to reflect the fix; this `TODOS.md` entry marked `[done]`.
-- [x] Run `make agent-check` and `make agent-test`.
-
-### Testing
-
-- **Unit (submitter recovery):** feed `execute_workflow`'s error path a synthetic `WorkflowFailureError` whose `.cause` is an `ApplicationError` with a details-packed report dict; assert the resulting `WorkflowExecutionError.to_error_report()` carries `error_category` / `retryable` / `model` / `provider` / `user_action` and the real message. Use `pytest-mock`, one `TestClass` per module (see `_tprl/CLAUDE.md`).
-- **Integration (full chain):** *(landed)* `tests/integration/pipelex/temporal/test_workflow_error_report_full_chain.py` runs a real `WfPipeRouter` workflow on the in-process Temporal server through `WorkflowExecutor.execute_workflow`, with the LLM call mocked to fail — exercising the genuine activity → workflow → submitter serialization round-trip — and asserts the recovered `WorkflowExecutionError.to_error_report()` carries `error_category` / `retryable` / `model` / `provider` / `user_action` and the real message.
-- **Regression parity:** *(landed)* the local arm `tests/integration/pipelex/error_handling/test_error_report_local_full_chain.py` runs the same failing pipe through the local `PipeRouter`. Both arms assert the shared `ErrorReportParityTestData` constants, so local/Temporal `ErrorReport` parity holds by construction. Recorded in `wip/error-handling/track-testing.md` ("Temporal boundary").
-- **Edge & error coverage (added by eng review 2026-05-17):**
- - **G1** — `from_dict` raises `ValidationError` on a malformed / missing-required dict (asserts the strict-inverse contract).
- - **G2** — a version-skewed dict carrying an unknown extra key is accepted: the key is dropped, `from_dict` validates the rest.
- - **G3** — *(tests the recovery guard, step 2a)* a `WorkflowFailureError` whose recovered `details` fail validation falls back to a generic `WorkflowExecutionError` with no submitter crash.
- - **G4** — a `WorkflowFailureError` whose `.cause` `ApplicationError` carries no report `details` yields a generic `WorkflowExecutionError(error_report=None)`.
- - **G6** *(regression)* — the `WorkflowAlreadyStartedError` / `RPCError` clause still raises a generic `WorkflowExecutionError(error_report=None)`, behavior unchanged.
- - **G7** *(regression)* — `WorkflowExecutionError.to_error_report()` with `error_report=None` falls through to the base `_enrich_error_report_from_cause` behavior.
-
-### File reference index
-
-| File | Role | Key lines |
-| --- | --- | --- |
-| `pipelex/base_exceptions.py` | `ErrorReport` (shared report type), `PipelexError.to_error_report` + `_enrich_error_report_from_cause` (chain walk) | `ErrorReport` 55, `to_dict` 71, `to_error_report` 106, **breaking line** 137 |
-| `pipelex/temporal/tprl/activity_error_boundary.py` | Activity-side: `PipelexError` → `TemporalError`, packs report into `details` | `convert_pipelex_errors` 25, 52 |
-| `pipelex/temporal/tprl/temporal_error.py` | `TemporalError` (`ApplicationError` subclass); `_error_report_from_details` recovery helper (workflow-side only today) | `_error_report_from_details` 14, `from_app_error` 99, `from_message_exception` 126 |
-| `pipelex/temporal/tprl/workflow_caller.py` | Submitter side — **where the report is dropped** | `execute_workflow` 90, `except WorkflowFailureError → WorkflowExecutionError` 122-125 |
-| `pipelex/temporal/exceptions.py` | `WorkflowExecutionError` (`TemporalFlowError` → `PipelexError`), no class-level metadata | `WorkflowExecutionError` 12 |
-| `pipelex/temporal/tprl_pipe/temporal_pipe_run.py` | `TemporalPipeRun.run` — submitter entry, no try/except | `run` 49 |
-| `pipelex/pipeline/runner.py` | `PipelexRunner.execute_pipeline` — wraps the propagated error as `PipelineExecutionError` | `execute_pipeline` 75, `except PipelexError` 172, `raise PipelineExecutionError` 184 |
-| `pipelex/pipeline/exceptions.py` | `PipelineExecutionError` — pure wrapper, `to_error_report()` floors to `RUNTIME`/`UNKNOWN` | `PipelineExecutionError` 14, `to_error_report` 38-48 |
-| `pipelex/cli/agent_cli/commands/agent_output.py` | Agent CLI delivery — reads `to_error_report()`, ContextVar (sound, do not touch) | `_assemble_error_payload` 171, `to_error_report()` read 192-202 |
-| `pipelex/cli/agent_cli/commands/run/pipe_cmd.py` | Agent CLI `run pipe` — catches `PipelineExecutionError` | `set_agent_cli_output_format` 73, `except PipelineExecutionError` 155 |
-| `pipelex/pipelex.py` | Wires `make_temporal_pipe_run()` as the hub pipe-run when Temporal is enabled | ~429-431 |
-
----
-
-## [done] Recover the structured error report on the Temporal child-workflow boundary
-
-**Status:** done (landed 2026-05-17 on `feature/Temporal-error-report`) · **Filed:** 2026-05-17 (surfaced by the eng review of the submitter-boundary fix) · **Severity:** low — latent; the affected methods are not on Pipelex's traced execution paths.
-**Depends on:** the submitter-boundary fix above landing first (it builds `error_report_dict_from_details` and `WorkflowExecutionError.error_report`).
-
-### TL;DR
-
-`WorkflowExecutor.execute_child_workflow` and `start_child_workflow` (`pipelex/temporal/tprl/workflow_caller.py:221`, `:267`) catch `ChildWorkflowError` and, when `exc.cause` is an `ApplicationError`, do `raise WorkflowExecutionError(msg) from exc.cause`. `ApplicationError` is not a `PipelexError`, so `_enrich_error_report_from_cause` stops at that link — the same structured-report drop the submitter-boundary fix addresses, in two more methods.
-
-### Why it is not live today
-
-Both methods carry a docstring (`workflow_caller.py:180`) stating that Pipelex's in-workflow child-spawn sites (`tprl_pipe.wf_pipe_run`, `tprl_pipe.temporal_pipe_router`) deliberately bypass these wrappers and call `workflow.execute_child_workflow(...)` directly to stay replay-deterministic. The workflow → workflow hop is already covered by `TemporalError.from_app_error`. So the bug is latent on public surface, not on a path Pipelex exercises.
-
-### Fix (landed)
-
-In each `except ChildWorkflowError` block of `execute_child_workflow` / `start_child_workflow`, when `exc.cause` is an `ApplicationError` the handler now calls `recover_error_report(exc.cause)` — `recover_error_report` accepts the `ApplicationError` directly and returns it on the first chain-walk iteration. On a recovered report it raises `WorkflowExecutionError(error_report.message, error_report=...)`, mirroring `execute_workflow`; otherwise it falls back to the prior generic `WorkflowExecutionError`. The `_find_application_error` docstring was updated to note callers may pass `ChildWorkflowError.cause` straight in.
-
-Unit coverage in `tests/unit/pipelex/temporal/test_workflow_caller_child_error_recovery.py` mirrors the submitter-boundary tests (recovery success, G3 malformed details → generic, G4 no report payload → generic, non-`ApplicationError` cause → generic), parametrized across both methods. `make agent-check` and the temporal unit suite pass.
-
----
-
-## GSTACK REVIEW REPORT
-
-| Review | Trigger | Why | Runs | Status | Findings |
-|--------|---------|-----|------|--------|----------|
-| CEO Review | `/plan-ceo-review` | Scope & strategy | 0 | — | — |
-| Codex Review | `/codex review` | Independent 2nd opinion | 0 | — | — |
-| Eng Review | `/plan-eng-review` | Architecture & tests (required) | 1 | CLEAR (PLAN) | 4 issues, 0 critical gaps |
-| Design Review | `/plan-design-review` | UI/UX gaps | 0 | — | — (backend-only, N/A) |
-| DX Review | `/plan-devex-review` | Developer experience gaps | 0 | — | — |
-
-- **UNRESOLVED:** 0 — all six decisions (A1, A2, Q1, Q2, outside-voice, child-workflow TODO) answered.
-- **VERDICT:** ENG CLEARED — ready to implement. Architecture, code-quality, test, and performance sections all closed.
diff --git a/wip/error-handling/archive-todos-api-readiness-2.md b/wip/error-handling/archive-todos-api-readiness-2.md
deleted file mode 100644
index dcb6b32fb..000000000
--- a/wip/error-handling/archive-todos-api-readiness-2.md
+++ /dev/null
@@ -1,535 +0,0 @@
-# TODOS — `feature/API-readiness-2`
-
-> **ARCHIVED 2026-05-28 — superseded.** Execution ledger for the `feature/API-readiness-2` branch (PRs #931 + #933 — error-handling overhaul finalization, structural refactor of `*_exceptions.py` modules, post-#931 `/review` follow-ups). All in-repo phases (0–7) landed. The only remaining track from this plan is webhook signing (Stage 5), tracked independently at [`../security/webhook-signing.md`](../security/webhook-signing.md). The cross-repo `pipelex-api` adapt PR is handed off — see [`../api-readiness-2-handoff.md`](../api-readiness-2-handoff.md). Moved here from the repo root for history. Relative links below were written relative to the repo root, not this `wip/error-handling/` location.
-
-Follow-up work for the next branch after PR #931 (error-handling overhaul). This plan finalizes the loose ends a `/review` pass on #931 surfaced: a documentation clean slate first, then the deferred Critical #2, the half-wired plan Item B, and the tracked follow-ups.
-
-**Docs come first on purpose.** We work and review step by step. Every time a doc contradicts the code or another doc, the PR review agents (Greptile, Codex, Cubic) get confused and burn the review on noise. Phase 0 makes the error-handling doc set a single coherent description of what shipped and what is still wanted — so every later phase is reviewed against a correct spec.
-
-Each phase is self-contained; checkpoints between them are hard stops where the agent must verify, record state, and make this doc cold-start-safe.
-
-## Branch setup
-
-- Cut `feature/API-readiness-2` from `dev` **after PR #931 has merged**. Every phase below builds on #931's code — the `ErrorReport` BaseModel, `DisclosureMode`, `recover_error_report`, the error-page generator. If you must start before #931 merges, branch from `feature/API-readiness-merge` instead.
-- The `/review` pass on #931 left uncommitted doc-alignment edits on `feature/API-readiness-merge` (`pipelex/errors/error_pages_generator.py`, `pipelex/temporal/exceptions.py`, `docs/under-the-hood/error-model.md`, `wip/error-handling/api-companion-revisions.md`, and the new `wip/error-handling/track-strict-disclosure-input-domain-gap.md`). Those should land with #931. Phase 0 below is written to be idempotent — it re-applies anything that did not land, so it does not matter whether those edits made it into #931 or not.
-
-## How to start (cold start)
-
-1. Read this whole file, then read the linked tracker docs under `wip/error-handling/` and `wip/security/`.
-2. Check the **Session log** at the bottom — it records what the last session landed and the exact next action.
-3. Resume at the first unchecked box. Respect the checkpoints — do not run past a `⛔ CHECKPOINT` without doing its stop-and-record steps.
-
-## Ground rules
-
-- No backward-compat shims. The Temporal integration has never shipped — there is no prior on-wire schema to preserve.
-- `request_id` is transported on `JobMetadata`. **Do not introduce a `ContextVar`** for it — a ContextVar is process-local and does not cross the Temporal activity/workflow serialization boundary in distributed execution. (The CLI-delivery track uses a ContextVar legitimately because it is single-process — do not conflate the two.)
-- After any code change run `make agent-check`. Use `make agent-test` to verify a phase before its checkpoint.
-- Spec vs Blueprint: language rules go on blueprints, authoring convenience on specs (see `pipelex/builder/CLAUDE.md`).
-
----
-
-## Phase 0 — Documentation coherence pass (clean slate)
-
-No code-behavior changes in this phase — docs and docstrings only. Goal: every error-handling doc and docstring describes either shipped code (accurately) or wanted work (clearly, marked as wanted-not-done). No doc contradicts the code; no two docs contradict each other.
-
-### 0.1 — Reference docs and docstrings must match shipped code
-
-- [x] `docs/under-the-hood/error-model.md` — verify the `extra="forbid"` warning no longer claims `recover_error_report()` trims unknown keys. Then read the whole file against the shipped `ErrorReport` / `recover_error_report` / disclosure-mode code and fix any other drift.
-- [x] `pipelex/temporal/exceptions.py` — verify the `UnrecoverableWorkflowFailureError` docstring no longer claims it is synthesized on a `from_dict` version-skew failure. It is synthesized only when no report dict is found at all.
-- [x] `pipelex/temporal/log_temporal.py` — the `WorkflowLog` / `ActivityLog` docstrings claim "activities/workflows read the value off `job_metadata.request_id` and pass it explicitly." No caller does that yet. Soften the docstrings to describe the parameter honestly (accepted; wiring tracked in Phase 2) so a review agent does not flag a false claim.
-- [x] Sweep docstrings in the #931-touched modules for code-doc drift and fix what no longer matches: `base_exceptions.py` (`ErrorReport`, `DisclosureMode`, `to_dict`, `to_problem_document`, `title`, `type_uri`), `temporal_error.py` (`recover_error_report`, `_message_from_exc`, `_find_error_report_dict`), `delivery_executor.py`, `error_pages_generator.py`, `error_module_registry.py`.
-
-### 0.2 — Plan doc `api-companion-revisions.md` coherence
-
-- [x] Verify §D.1 and "What landed in Stage 2" describe `recover_error_report` correctly (no embedded report → synthesize; found-but-invalid dict → raise as an internal contract bug) and that the `_declared_title` value quoted matches the code.
-- [x] Rewrite §B — it says "Activity logs carry it via a `ContextVar` (same pattern as `session_id`)." That is wrong. State the decided design: `request_id` is transported on `JobMetadata` and threaded explicitly into log calls; no `ContextVar`, because a ContextVar is process-local and does not survive the Temporal serialization boundary.
-- [x] Reconcile the "Current state" Stage checklist with reality: Stages 1-4 landed, Stage 5 (webhook signing) pending. Add a pointer to this `TODOS.md` for the post-review follow-ups so a reader knows where the remaining work lives.
-- [x] Make every "What landed in Stage X" section honest — in particular Stage 1's `request_id` claim must not imply the logging is wired end-to-end when it is not.
-
-### 0.3 — The `wip/error-handling/` hub
-
-- [x] `wip/error-handling/README.md` — the "Status at a glance" table does not list the API-readiness / `api-companion-revisions.md` track at all, and "What's still open" mentions only the metadata-model long tail. Add the API-readiness track to the table, and rewrite "What's still open" to list the real open items — webhook signing (Stage 5), the STRICT disclosure gap, the webhook-payload collision, the `request_id` wiring, the metadata-model long tail — each linking its tracker doc and/or this `TODOS.md`.
-- [x] Confirm the new trackers (`track-strict-disclosure-input-domain-gap.md`, `track-webhook-payload-collision.md`) are linked from the README and consistent with it.
-- [x] Confirm every `archive-*.md` file reads unambiguously as an archive (point-in-time, superseded). Do NOT rewrite archive contents — only fix a header line if one genuinely reads as a current contract.
-- [x] `changes-for-api-early-draft.md` — add a one-line "superseded — see `api-companion-revisions.md`" banner at the top if it does not already have one, so a review agent never treats the original draft spec as the contract.
-
-### 0.4 — Cross-doc coherence check
-
-- [x] Final read: `TODOS.md` ↔ `api-companion-revisions.md` "Current state" ↔ `wip/error-handling/README.md` "What's still open" must agree on what is done and what is pending. Resolve any disagreement.
-- [x] `make agent-check` clean (docstring edits can trip formatting/linting).
-
-**Acceptance:** a PR review agent reading the error-handling docs cold gets one coherent story — no doc contradicts the code, no two docs contradict each other, and pending work is clearly marked as pending.
-
-### ⛔ CHECKPOINT 0 — Clean slate verified, STOP and record
-
-- [x] Run `make agent-check` — must pass.
-- [x] Commit Phase 0 as a single docs-only commit.
-- [x] Tick every Phase 0 box above.
-- [x] Append a dated **Checkpoint 0** entry to the Session log: confirm the doc set is coherent, list any doc deliberately left as-is and why, and the next action (start Phase 1).
-
----
-
-## Phase 1 — STRICT disclosure: close the INPUT-domain leak (Critical #2)
-
-Full analysis and options: [`wip/error-handling/track-strict-disclosure-input-domain-gap.md`](wip/error-handling/track-strict-disclosure-input-domain-gap.md).
-
-STRICT disclosure mode keys its redaction passthrough on `error_domain == ErrorDomain.INPUT`, but `error_domain` is inherited up the `__cause__` chain by `_enrich_error_report_from_cause`. Two consequences: a domain-less wrapper raised `from` an INPUT cause leaks its own internal `message` through STRICT; and `to_problem_document` echoes `provider` / `model` / `provider_metadata` for INPUT reports even in STRICT.
-
-- [x] **Decision D1** — pick the Gap 1 fix: Option 1 (per-class `ClassVar` flagging classes that genuinely author caller-facing messages; gate STRICT passthrough on the flag) or Option 2 (stop inheriting `error_domain` onto a domain-less wrapper). Recommended: **Option 1** — it gates redaction on message provenance rather than an inherited classification, and avoids the `http_status` side effects Option 2 carries. Record the choice in the Decisions section. **→ Decided 2026-05-22: Option 1** (see [Decisions](#decisions)).
-- [x] Implement the chosen Gap 1 fix in `pipelex/base_exceptions.py` (`to_dict` STRICT branch, and `_enrich_error_report_from_cause` / the report-construction path as the option requires).
-- [x] Gap 2 — strip `provider` / `model` / `provider_metadata` from the INPUT passthrough branch of `to_dict(DisclosureMode.STRICT)`. An input-classification error has no business carrying provider metadata onto an external surface.
-- [x] Align the `DisclosureMode` docstring in `pipelex/base_exceptions.py` with the implemented redaction set.
-- [x] Tests: a domain-less wrapper (`PipelexUnexpectedError`) raised `from` an INPUT-domain cause must not leak the wrapper's `message` through `to_dict(STRICT)`; `to_problem_document(disclosure_mode=STRICT)` must never emit `provider` / `model` / `provider_metadata` regardless of `error_domain`. Mirror the existing STRICT tests in `tests/unit/pipelex/test_error_report_disclosure_mode.py`.
-- [x] `make agent-check` clean; STRICT-related tests green.
-- [x] Update [`wip/error-handling/track-strict-disclosure-input-domain-gap.md`](wip/error-handling/track-strict-disclosure-input-domain-gap.md) — mark it landed, note the option taken.
-
-**Acceptance:** STRICT never reflects a non-caller-facing message or provider metadata to an external surface, for any `error_domain`. The `DisclosureMode` docstring matches the code.
-
-### ⛔ CHECKPOINT 1 — STOP, verify, record
-
-- [x] Run `make agent-check` and `make agent-test` — both must pass.
-- [x] Commit Phase 1 as a single coherent commit.
-- [x] Tick every Phase 1 box above.
-- [x] Append a dated **Checkpoint 1** entry to the Session log with: Decision D1 outcome, files touched, the exact redaction behavior now in effect, anything deferred, and the next action (start Phase 2).
-
----
-
-## Phase 2 — Finish wiring `request_id` into Temporal logs (Plan Item B)
-
-Plan Item B is half-landed. `JobMetadata.request_id`, the `pipeline_run_setup(request_id=...)` kwarg, and the `request_id` kwarg on every `WorkflowLog` / `ActivityLog` method plus `_build_extra` all shipped — but **no pipelex activity or workflow reads `job_metadata.request_id` and passes it to a log call.** The kwarg is dead surface today.
-
-- [x] **Decision D2** — pick the call-site strategy. Either pass the `request_id` kwarg at each meaningful Temporal log call, or build a per-invocation bound logger/adapter from `job_metadata.request_id` at activity/workflow entry. Recommended: **the bound-adapter approach**, rebuilt every invocation, to avoid threading the kwarg through every call site. It must NOT be a ContextVar and must NOT be module/process state — it is rebuilt per activity/workflow invocation from that invocation's `JobMetadata`. Record the choice. **→ Decided 2026-05-22: bound adapter** (see [Decisions](#decisions)).
-- [x] Wire it: at each activity and workflow entry point that has `job_metadata` in scope, read `job_metadata.request_id` and make that invocation's log records carry it via the `_build_extra` → `extra={"request_id": ...}` path.
-- [x] Remove dead surface: if the bound-adapter approach wins, drop the now-unused per-method `request_id` kwargs, or fold them into the adapter — leave no unused parameter and no inaccurate docstring behind.
-- [x] Test: a pipeline run dispatched with a `request_id` produces Temporal activity/workflow log records carrying that `request_id`. Add coverage of the `_build_extra` / logging request_id path — there is none today.
-- [x] Update the docs to reflect Item B fully landed — `api-companion-revisions.md` "What landed" / "Current state", `wip/error-handling/README.md`, and the `log_temporal.py` docstrings (which can now state the wiring as fact).
-- [x] `make agent-check` clean.
-
-**Acceptance:** a run dispatched with a `request_id` has that id on its Temporal log records; no dead `request_id` parameter or inaccurate docstring remains.
-
-### ⛔ CHECKPOINT 2 — STOP, verify, record
-
-- [x] Run `make agent-check` and `make agent-test` — both must pass.
-- [x] Commit Phase 2 as a single coherent commit.
-- [x] Tick every Phase 2 box above.
-- [x] Append a dated **Checkpoint 2** entry to the Session log with: Decision D2 outcome, the wiring mechanism chosen, files touched, whether the per-method kwargs were kept or dropped, and the next action (start Phase 3).
-
----
-
-## Phase 3 — Webhook payload reserved-key collision
-
-Full analysis and options: [`wip/error-handling/track-webhook-payload-collision.md`](wip/error-handling/track-webhook-payload-collision.md).
-
-`DeliveryExecutor._notify_webhook` copies the caller's `WebhookTarget.payload` and writes Pipelex-owned keys (`pipeline_run_id`, `status`, `result_url`, `error`) on top. A caller can put any of those keys in their static payload and have the meaning shift silently with delivery status.
-
-- [x] Implement Option 1 from the tracker: a `field_validator` on `WebhookTarget.payload` in `pipelex/pipe_run/delivery_assignment.py` that rejects the reserved-key set at construction time, with a clear error naming the offending key(s).
-- [x] Tests: constructing a `WebhookTarget` with a reserved key in `payload` raises a validation error; a clean payload passes.
-- [x] `make agent-check` clean.
-- [x] Update [`wip/error-handling/track-webhook-payload-collision.md`](wip/error-handling/track-webhook-payload-collision.md) — mark it landed.
-
-**Acceptance:** a caller cannot register a webhook whose static payload collides with a Pipelex-owned key; the failure is loud and at construction time.
-
----
-
-## Phase 4 — Test coverage backfill
-
-The `/review` pass found gaps where the refactor removed or never added coverage. Some depend on Phase 2 — do this phase after Phase 2.
-
-- [x] `recover_error_report` — `tests/integration/pipelex/temporal/test_recover_error_report.py` lost the cases that pinned the old "malformed → None" behavior. Add a case pinning the current contract: a report dict that is *found* but fails `ErrorReport` validation raises `pydantic.ValidationError` (treated as an internal contract bug, not synthesized).
-- [x] `_message_from_exc` (`pipelex/temporal/tprl/temporal_error.py`) — add a test for the `id()`-based cycle guard (a self-referential `__cause__` chain must terminate) and a test for the `repr(exc)` fallback when every message in the chain is empty.
-- [x] `DeliveryActivityArg` — add a focused unit round-trip test (`model_validate_json(model_dump_json())`) with a populated nested `error_report`, so a nested-model serialization regression is caught without a real Temporal worker.
-- [x] Logging `request_id` path — covered by Phase 2's test; confirm it exists and is green here.
-- [x] `make agent-check` and `make agent-test` clean.
-
-**Acceptance:** the behaviors the refactor introduced or changed are pinned by tests; no silent regression path remains for `recover_error_report`, `_message_from_exc`, or the activity-arg round-trip.
-
-### ⛔ CHECKPOINT 3 — STOP, verify, record
-
-Phases 0–4 are a coherent unit: the in-repo finalization of the error-handling overhaul. Phase 5 is a separate cross-repo track.
-
-- [x] Run `make agent-check` and `make agent-test` — both must pass.
-- [x] Commit Phases 3–4.
-- [x] Tick every Phase 3 and Phase 4 box.
-- [x] Append a dated **Checkpoint 3** entry to the Session log: confirm all in-repo follow-ups are done, list anything still deferred, and state whether Phase 5 (webhook signing) is being picked up now or scheduled separately.
-- [x] At this point the in-repo work is shippable. Decide with the user whether to open a PR for `feature/API-readiness-2` now and run Phase 5 on its own branch, or continue. **→ Decided 2026-05-22: stop here** — no PR opened, Phase 5 not started; both deferred to a later session.
-
----
-
-## Phase 5 — Webhook signing (Plan Item F / Stage 5) — separate cross-repo track
-
-This is the last unshipped stage of the original error-handling plan. It is **cross-repo** (pipelex side + the API side land in coordinated lockstep) and has its own design and checkpoints. Treat it as an independent track — it can land on its own schedule and does not block Phases 0–4.
-
-- [ ] Read [`wip/security/webhook-signing.md`](wip/security/webhook-signing.md) end to end — it is the authoritative plan for this work.
-- [ ] Follow that doc's own phases and checkpoints. Do not duplicate them here.
-- [ ] Coordinate the cross-repo PRs (pipelex + API) so the signing secret and verification land together.
-
-**Acceptance:** as defined in `wip/security/webhook-signing.md`.
-
----
-
-## Phase 6 — Error class location convention + static enforcement
-
-Discovery of `PipelexError` subclasses in `pipelex/errors/error_module_registry.py` relies on a filesystem pattern scan (`exceptions.py`, `*_exceptions.py`, `*_errors.py`) plus a hand-maintained allowlist `_NON_STANDARD_ERROR_MODULES`. A spot check found ~20 production error classes living in files matching neither convention — plugin worker/factory modules (`anthropic_factory.py`, `bedrock_llm_worker.py`, `openai_client_factory.py`, the google workers), single-error utility modules (`validate_bundle.py`, `module_inspector.py`, `index_loader.py`, `dry_run.py`, `model_reference.py`, `extract_input.py`, `pypdfium2_renderer.py`, `func_registry.py`, `concept_spec.py`, `stuff_spec_factory.py`), and mixed-concern modules (`pipeline_manager.py`, `template_image_analyzer.py`). They are silently absent from the generated `docs/errors/` pages and from `test_pipelex_error_type_uri_uniqueness`.
-
-The fix is structural, not a runtime patch. Pipelex errors are part of the documented public contract (each has a `type_uri`, a docs page, stable identity) — they belong in dedicated exception modules, like Django's `django.core.exceptions` or SQLAlchemy's `sqlalchemy.exc`. Enforce that via filename convention and a static check; refactor stragglers into properly-named modules; remove discovery from runtime entirely.
-
-- [x] **Decision D3** — pick the filename pattern. Recommended: **`exceptions.py` (default, one per package directory) + `*_exceptions.py` (for dirs that host multiple separate-concern error modules, e.g. plugin subpackages — the existing `portkey_exceptions.py` / `anthropic_exceptions.py` / `mistral_exceptions.py` / `gateway_exceptions.py` pattern)**. Drop `*_errors.py` — it is a redundant synonym (3 files today: `jinja2_errors.py`, `secrets_errors.py`, `template_errors.py`) and synonyms are exactly what produced the drift. Record the choice in the Decisions section. **→ Decided 2026-05-23: `exceptions.py` + `*_exceptions.py`** (see [Decisions](#decisions)).
-
-### 6.1 — Static check first (TDD)
-
-- [x] New test: AST-scan `pipelex/` for every `class X(...)` whose any transitive base resolves to `PipelexError`; assert each file matches the chosen pattern (plus the top-level `pipelex/base_exceptions.py`, which is special-cased as the root). Watch it fail, capture the misplaced list — that list is the authoritative refactor target.
-- [x] Backstop test: walk `PipelexError.__subclasses__()` transitively after normal imports, assert each subclass's `__module__` resolves to a properly-named file. Catches dynamic / decorator-registered cases the AST scan would miss, and is the regression net once `error_module_registry.py` is gone.
-
-### 6.2 — Refactor misplaced error classes
-
-Expected starting list (the static check is authoritative — extend or trim as needed):
-
-- `pipelex/pipeline/pipeline_manager.py` → append to existing `pipelex/pipeline/exceptions.py`.
-- `pipelex/pipeline/validate_bundle.py` → `pipelex/pipeline/validate_bundle_exceptions.py` (sibling pattern keeps the error next to its caller in import-graph terms).
-- `pipelex/pipe_operators/shared/template_image_analyzer.py` → `pipelex/pipe_operators/shared/exceptions.py`.
-- `pipelex/tools/misc/{context_provider_abstract,filetype_utils,json_utils,toml_utils}.py` → consolidate into `pipelex/tools/misc/exceptions.py`.
-- `pipelex/tools/secrets/secrets_utils.py` and `pipelex/tools/secrets/secrets_errors.py` (rename) → consolidate into `pipelex/tools/secrets/exceptions.py`.
-- `pipelex/tools/pdf/pypdfium2_renderer.py` → `pipelex/tools/pdf/exceptions.py`.
-- `pipelex/tools/typing/module_inspector.py` → `pipelex/tools/typing/exceptions.py`.
-- `pipelex/tools/jinja2/jinja2_errors.py` → rename to `pipelex/tools/jinja2/exceptions.py`.
-- `pipelex/cogt/templating/template_errors.py` → rename to `pipelex/cogt/templating/exceptions.py`.
-- `pipelex/core/pipes/stuff_spec/stuff_spec_factory.py` → append to existing `pipelex/core/pipes/stuff_spec/exceptions.py`.
-- `pipelex/plugins/google/google_{llm,img_gen}_worker.py` → `pipelex/plugins/google/google_exceptions.py` (or `exceptions.py` — D3 will decide whether to match the existing portkey/anthropic/mistral/gateway prefix style).
-- `pipelex/plugins/anthropic/anthropic_factory.py` → append to existing `anthropic_exceptions.py`.
-- `pipelex/plugins/bedrock/{bedrock_llm_worker,bedrock_factory}.py` → `pipelex/plugins/bedrock/bedrock_exceptions.py`.
-- `pipelex/plugins/openai/{openai_client_factory,vertexai_factory}.py` → `pipelex/plugins/openai/openai_exceptions.py`.
-- `pipelex/kit/index_loader.py` → append to existing `pipelex/kit/exceptions.py`.
-- `pipelex/system/environment.py` → append to existing `pipelex/system/exceptions.py`.
-- `pipelex/system/registries/func_registry.py` → `pipelex/system/registries/exceptions.py`.
-- `pipelex/pipe_run/dry_run.py` → append to existing `pipelex/pipe_run/exceptions.py`.
-- `pipelex/builder/concept/concept_spec.py` → `pipelex/builder/concept/exceptions.py`.
-- `pipelex/cogt/models/model_reference.py` → `pipelex/cogt/models/exceptions.py`.
-- `pipelex/cogt/extract/extract_input.py` → `pipelex/cogt/extract/exceptions.py`.
-
-For each move:
-
-- Update every import site (search by class name; do not rely on the static check to surface them).
-- Watch for circular imports — if appending to an existing `exceptions.py` would create a cycle, prefer a new `<topic>_exceptions.py` module that imports only `PipelexError` / its immediate base.
-- Don't leave shims or re-exports behind. Per project policy (no backward compatibility), update callers and move on.
-
-### 6.3 — Delete the registry, simplify discovery
-
-- [x] Delete `pipelex/errors/error_module_registry.py`. Replace `iter_pipelex_error_subclasses()` callers with a small inline transitive `__subclasses__()` walk in `error_pages_generator.py` (the only production consumer plus the URI-uniqueness test). Normal imports load everything now — no force-import phase needed, no allowlist to maintain. *(Refined by Phase 7: discovery is rehydrated by a dev/test-time `_force_load_all_error_modules` helper. Production bootstrap remains untouched.)*
-- [x] `pipelex-dev generate-error-pages` — regenerate `docs/errors/` and verify the page set is complete (new pages appear for previously-missed classes; no orphan pages).
-
-### 6.4 — Rule, docs, and the absorbed minor follow-up
-
-- [x] Add the rule to `pipelex/.claude/rules/python-standards.md` under a new "Error class location" section: every `PipelexError` subclass lives in a module whose filename matches `exceptions.py` or `*_exceptions.py` (final wording per D3); the static check from 6.1 enforces it.
-- [x] Reference it from `pipelex/CLAUDE.md` if appropriate. *(N/A — no `pipelex/CLAUDE.md` exists; the rule lives in `.claude/rules/python-standards.md` which is consulted by the top-level CLAUDE.md.)*
-- [x] Also resolve here, since it touches the same generator: the `pascal_case_to_kebab` acronym collision (`LLMError` / `LlmError` both kebab to `llm-error`). Add a defensive assert in `error_pages_generator.generate_error_pages` that fails loudly if two target classes resolve to the same slug, and a short note near `PipelexError` warning that acronym-casing variants of an existing error class name collide. (Today this is caught reactively by `test_pipelex_error_type_uri_uniqueness` only.)
-
-### 6.5 — Verify
-
-- [x] Static check passes against the full tree.
-- [x] Generated `docs/errors/` set is complete and `make agent-check` clean.
-- [x] `make agent-test` clean.
-
-**Acceptance:** every `PipelexError` subclass lives in a properly-named module; the static check fails the PR if a new error class lands outside the convention; `error_module_registry.py` is gone; discovery has no production-runtime side effects (the dev/test-time `_force_load_all_error_modules` helper added in Phase 7 walks the filesystem inside the docs generator and the URI uniqueness test only); the kebab-slug collision footgun is caught at generation time, not only by the uniqueness test.
-
-### ⛔ CHECKPOINT 6 — STOP, verify, record
-
-- [x] `make agent-check` and `make agent-test` clean.
-- [x] Commit as a single coherent refactor (or a small ordered series: test-first → moves → registry deletion → rule).
-- [x] Tick every Phase 6 box.
-- [x] Append a dated **Checkpoint 6** entry to the Session log: Decision D3 outcome, files moved, import sites updated, the kebab-collision defense added, anything left as-is and why, next action.
-
----
-
-## Minor follow-ups (low priority — batch into any checkpoint)
-
-- (none open — `pascal_case_to_kebab` acronym collision and `error_module_registry` discovery fragility both folded into Phase 6.)
-
----
-
-## Phase 7 — Error-class discovery contract (Fix #1 follow-up)
-
-Phase 6 deleted `pipelex/errors/error_module_registry.py` on the premise that *every error class lives in a properly-named module that normal imports pull in*. The premise turned out **false**. A `/code-review` pass on the Phase 6 commit `0fa4440b` found that `docs/errors/index.md` had already regressed by 23 entries because plugin worker/factory modules use deferred imports (rightly so — the SDKs are heavy / optional), so the colocated `*_exceptions.py` modules for `anthropic`, `bedrock`, `google`, `openai`, `azure_rest`, `mistral`, `gateway`, `portkey`, plus a handful of non-plugin classes (`FalCredentialsError`, `GraphSpecError`/`GraphSpecValidationError`, `PipeBatchFactoryError`, `PipeSearchError`/`PipeSearchFactoryError`, `PipelexBundleSpecBlueprintError`) are never reached by `Pipelex.make()` at docs-generation time. Their `__subclasses__()` registration never happens, so the new `iter_pipelex_error_subclasses()` silently misses them.
-
-A second commit (the Fix #2/#3/#4 commit landing right after this analysis) added the orphan-deletion path to `generate_error_pages` (so the 23 stale `.md` files are cleaned up rather than left as orphans on disk), a `removed` bucket in `ErrorPagesReport`, the `tomli` runtime-import fix in `pipelex/tools/misc/exceptions.py`, and an `xfail(strict=True)` completeness assertion at `tests/unit/pipelex/errors/test_error_class_location_convention.py::TestErrorClassLocationConvention::test_runtime_walk_discovers_every_ast_classified_subclass`. The xfail makes the gap visible in CI; the moment Phase 7 closes it, `strict=True` turns the unexpected pass into a CI failure that demands the marker be removed.
-
-### Goal
-
-Close the gap. Discovery must yield the same set the AST scan finds. The convention test's completeness assertion should pass without `xfail`.
-
-### Decision D4 — discovery strategy
-
-Three architectural options (all preserve the Phase 6 file-naming convention):
-
-- **Option A — Explicit registration manifest.** A single source file (e.g. `pipelex/errors/_all_exceptions.py`) imports every `*_exceptions.py` module explicitly. The convention test grows a two-sided check: every `*_exceptions.py` on disk has a matching import in the manifest; every manifest import points at an existing `*_exceptions.py`. **Pros:** explicit, no runtime filesystem scan, fails loudly when someone adds a module without registering it. **Cons:** one extra edit per new error module; the manifest grows.
-- **Option B — Eager `*_exceptions.py` import at `Pipelex.make()`.** Filesystem-walk for the convention patterns during bootstrap; force-import each one. Only error modules are loaded (verified safe: each plugin's `*_exceptions.py` imports only `CogtError`/`CredentialsError`/`PipelexError` — none pull in the plugin's SDK). **Pros:** zero maintenance; convention enforcement is structural. **Cons:** runtime filesystem touch (the smell the Phase 6 refactor wanted to delete); breaks in zip-wheel installs where `rglob` returns nothing.
-- **Option C — Build-time codegen.** A `pipelex-dev` command regenerates `pipelex/errors/_all_exceptions.py` from the filesystem; CI fails if the generated file is stale. **Pros:** explicit at rest, automatic at update; eliminates runtime filesystem touch. **Cons:** needs CI integration; adds a generator + a check; two commits to land any new error module.
-
-**Recommendation: Option A.** Explicit manifest. Trade one extra edit per module for visibility-in-source. The convention test makes forgetfulness an immediate CI failure on either side.
-
-Record the decision in the Decisions section when taken.
-
-### 7.1 — Implement the chosen option
-
-- [x] **Decision D4** — pick A / B / C from above. Record date and rationale. **→ Decided 2026-05-23: Option B' (scoped rglob + force-import in dev/test consumers; no production bootstrap touch)** (see [Decisions](#decisions)).
-- [x] Implement.
-- [x] Verify: `make agent-test` runs the completeness assertion *without* the `xfail` marker (or, equivalently, the test passes and pytest reports `XPASS` under `strict=True`, prompting the marker's removal).
-- [x] Remove `@pytest.mark.xfail(...)` from `test_runtime_walk_discovers_every_ast_classified_subclass`.
-
-### 7.2 — Regenerate `docs/errors/`
-
-- [x] `pipelex-dev generate-error-pages` — the previously-dropped pages reappear (recreated, not "removed"). Verify `ErrorPagesReport.written` lists them.
-- [x] `docs/errors/index.md` carries every AST-discovered class.
-
-### 7.3 — Update the docs / rules
-
-- [x] In `.claude/rules/python-standards.md`, document the chosen discovery strategy alongside the existing "Error class location" rule. The convention is about file naming; D4 is about how those files become discoverable.
-
-### Acceptance
-
-- The completeness assertion test passes without `xfail`.
-- `docs/errors/index.md` contains every AST-discovered class (no silent drops).
-- Generating docs from a clean clone (`pipelex-dev generate-error-pages` after `git clean`) produces the same set as the AST scan.
-
-### ⛔ CHECKPOINT 7 — STOP, verify, record
-
-- [x] `make agent-check` and `make agent-test` clean (and the formerly-`xfail` test now passes without the marker).
-- [x] Commit.
-- [x] Tick every Phase 7 box.
-- [x] Append a dated **Checkpoint 7** entry to the Session log: Decision D4 outcome, files touched, the AST/runtime set diff before and after, next action.
-
-### Cold-start context for a fresh session
-
-1. The smoking gun: `git show 0fa4440b -- docs/errors/index.md | head -50` shows the dropped entries. The current `docs/errors/index.md` is consistent with the deferred-import discovery state (208 entries); when Phase 7 closes, it should match the AST scan (231+ entries).
-2. The completeness assertion lives at `tests/unit/pipelex/errors/test_error_class_location_convention.py::test_runtime_walk_discovers_every_ast_classified_subclass`. Run it first thing: it should xfail today. After Phase 7, remove the `@pytest.mark.xfail(...)` decorator.
-3. The deleted `error_module_registry.py` (visible at `git show HEAD~N:pipelex/errors/error_module_registry.py` for the Phase 6 commit) had a body shaped roughly like the Option B implementation — useful as reference, but the recommended approach is Option A.
-4. Plugin `*_exceptions.py` files were verified safe to force-import in any environment (extras-only included) — they don't transitively import the plugin SDK. So Option B isn't blocked by extras availability.
-
----
-
-## Out of scope (recorded, not planned here)
-
-- Webhook VERBOSE disclosure to caller-supplied URLs — sending a full `ErrorReport` to the run caller's own endpoint is by design (plan §D.3: the endpoint belongs to the caller, who already owns the run data; the receiver decides what to re-expose). Webhook signing (Phase 5) is orthogonal — it authenticates origin, it does not reduce disclosure. No separate task; revisit only if the threat model changes.
-- Critical #1 from the `/review` pass (`recover_error_report` raising on a stale report dict) — resolved as not-a-bug: the Temporal integration has never shipped, so there is no prior on-wire schema. Docs are aligned in Phase 0. Nothing else to do.
-
----
-
-## Decisions
-
-Record each decision here as it is taken, with date and rationale.
-
-- **D1** (Phase 1, Gap 1 fix) — **Option 1**, decided 2026-05-22. Add a per-class `ClassVar` flagging error classes that genuinely author caller-facing messages, and gate the STRICT-disclosure passthrough on that flag instead of on the inherited `error_domain == INPUT`. Rationale: keys redaction on the *provenance of the message* rather than an inherited classification, and avoids the `http_status` side effects Option 2 (dropping `error_domain` inheritance for domain-less wrappers) would carry.
-- **D2** (Phase 2, request_id call-site strategy) — **Bound adapter**, decided 2026-05-22. `WorkflowLog` / `ActivityLog` gain an instance-level `request_id` (held by a shared `_RequestIdLog` base), built once per workflow/activity invocation from `job_metadata.request_id`; the dead per-method `request_id` kwargs are dropped. Rationale: a new log call added inside a wired entry point picks up `request_id` automatically — no per-call threading, nothing to forget — and the per-method kwarg was unused dead surface.
-- **D3** (Phase 6, error class location filename pattern) — **`exceptions.py` + `*_exceptions.py`**, decided 2026-05-23. Every module declaring a `PipelexError` subclass must be named `exceptions.py` (default — one per package directory) or `<topic>_exceptions.py` (for directories that host multiple separate-concern error modules, matching the existing `pipelex/plugins/*/` pattern: `portkey_exceptions.py`, `anthropic_exceptions.py`, `mistral_exceptions.py`, `gateway_exceptions.py`). The `*_errors.py` synonym is dropped — it adds no information, and three files (`jinja2_errors.py`, `secrets_errors.py`, `template_errors.py`) get renamed. The root `pipelex/base_exceptions.py` is special-cased. Rationale: synonyms are exactly what produced the drift the registry exists to paper over; one canonical pattern + one topical variant covers the legitimate cases without inviting a third.
-- **D4** (Phase 7, error class discovery strategy) — **Option B' (scoped rglob + force-import in dev/test consumers only)**, decided 2026-05-23. `pipelex/errors/error_pages_generator.py` gains a `functools.cache`-d `_force_load_all_error_modules()` helper that rglob-scans the package for `exceptions.py` / `*_exceptions.py` and `importlib.import_module`s each; `iter_pipelex_error_subclasses` calls it as its first statement. Production bootstrap (`Pipelex.make()`) does NOT touch it — discovery has zero runtime side effect outside the docs generator and the type-URI uniqueness test. Rationale: this option carries the convention contract through to discovery without re-introducing a hand-maintained list (Phase 6's original drift target). Option A (explicit manifest) was rejected because the manifest is a second copy of information already on disk under the convention — it would have to be maintained for the life of the codebase and the two-sided test would be the only thing keeping it in sync. Option B' achieves the same end with zero maintenance: empirically verified that every `*_exceptions.py` imports only base error classes (zero SDK pulls), and Phase 6's filename convention guarantees the rglob is complete. The Phase 6 deletion of `error_module_registry.py` was right to remove the production runtime touch but overshot — Phase 7 restores the discovery helper, scoped to the two dev/test-time consumers that legitimately need it.
-
----
-
-## Session log
-
-Append one dated entry per session / checkpoint. Each entry must leave the next session enough to cold-start: what landed, decisions taken, current code state, what is broken or deferred, and the exact next action.
-
-- **2026-05-22 — Checkpoint 0 (Phase 0 complete).** Documentation coherence pass landed as a single docs-only commit on `feature/API-readiness-2`. No code-behavior change — docstrings, comments, and markdown only. `make agent-check` clean (pyright + mypy: 0 errors).
-
- **Drift found and fixed:**
-
- - `docs/under-the-hood/error-model.md` — `ErrorReport` now described as a frozen Pydantic *model* (was "dataclass", stale since the Stage 3 `BaseModel` conversion); added the `title` / `type_uri` rows to the field table (they were missing). The `extra="forbid"` warning was already correct — it does not claim `recover_error_report()` trims unknown keys.
- - `pipelex/temporal/log_temporal.py` — softened the `WorkflowLog` / `ActivityLog` docstrings: the `request_id` kwarg is accepted but not yet threaded by any caller (wiring is Phase 2).
- - `pipelex/base_exceptions.py` — fixed a stale inline comment on `_declared_type_uri` ("bootstrap-registered errors base URI" → the `URLs.error_docs_base` constant; `type_uri()` is pure since the `ErrorManager` removal).
- - `pipelex/temporal/tprl/temporal_error.py` — dropped two stale references to the removed in-process `PipeRouter` retry loop (`TemporalError` class docstring + `_is_non_retryable`).
- - `api-companion-revisions.md` — rewrote §B Acceptance (`request_id` rides on `JobMetadata` and is threaded explicitly into log calls; **no `ContextVar`**, because a ContextVar is process-local and does not survive the Temporal serialization boundary); made the Stage 1 `request_id` claim honest (kwarg accepted, not wired end to end); rewrote "Net to the API team" to point at this `TODOS.md` for the post-review follow-ups.
- - `wip/error-handling/README.md` — added the API-readiness track to the "Status at a glance" table; rewrote "What's still open" to list webhook signing, the STRICT-disclosure gap, the webhook-payload collision, the `request_id` wiring, and the metadata-model long tail, each linking its tracker.
- - `wip/error-handling/archive-error-handling-2.md` — added an `ARCHIVED — COMPLETE` header line (the only archive whose title still read as a current plan).
- - `wip/error-handling/changes-for-api-early-draft.md` — added a "superseded — see `api-companion-revisions.md`" banner.
-
- **Verified correct, left as-is:** `pipelex/temporal/exceptions.py` `UnrecoverableWorkflowFailureError` docstring (already states it is synthesized only when no report dict is found); `base_exceptions.py` / `delivery_executor.py` / `error_pages_generator.py` / `error_module_registry.py` docstrings (swept — no drift). **Deliberate omission:** `error-model.md` does not yet document `DisclosureMode` / `to_problem_document` — not a contradiction (an under-the-hood doc need not be exhaustive), and Phase 1 changes STRICT behavior, so documenting it now would only be rewritten.
-
- **Coherence:** `TODOS.md`, `api-companion-revisions.md` "Current state", and `README.md` "What's still open" now agree — Stages 1-4 landed via PR #931; pending = webhook signing (Stage 5) + the four `/review` follow-ups.
-
- **Decisions:** none taken — D1 (Phase 1) and D2 (Phase 2) remain pending.
-
- **Next action:** start **Phase 1** — STRICT disclosure INPUT-domain leak. Take **Decision D1** first (recommended: Option 1 — per-class `ClassVar` flagging caller-facing-message authors).
-
-- **2026-05-22 — Decision D1 recorded.** Per the user, Decision D1 is **Option 1** (see the Decisions section for the full rationale); the Phase 1 D1 box is ticked to reflect it. Phase 1 **implementation is not started** — no implementation boxes ticked, no code touched. Next action: begin Phase 1 (STRICT disclosure INPUT-domain leak) at the first unticked box (implement the Gap 1 fix).
-
-- **2026-05-22 — Checkpoint 1 (Phase 1 complete).** STRICT-disclosure INPUT-domain leak closed on `feature/API-readiness-2` as a single commit. `make agent-check` clean (pyright + mypy: 0 errors); `make agent-test` full suite green.
-
- **Decision D1:** Option 1, implemented exactly as decided.
-
- **What landed:**
-
- - `pipelex/base_exceptions.py` — new `PipelexError._authors_caller_facing_message` `ClassVar` (default `False`) and new `ErrorReport.caller_facing_message: bool` field. `to_error_report()` sets the field from the class flag; `_enrich_error_report_from_cause` carries it **wrapper-wins** — never inherited from the `__cause__` chain, since it tracks the provenance of `report.message` (always the wrapper's own message). `to_dict(STRICT)` now gates the `message` passthrough on `caller_facing_message`, not on `error_domain == INPUT`.
- - **Gap 2:** new `_STRICT_PROVIDER_FIELDS` constant — `provider` / `model` / `provider_metadata` are stripped from the STRICT caller-facing passthrough branch too (already absent from the redacted branch). STRICT now never emits provider metadata for any `error_domain`.
- - `caller_facing_message` is serialized **only when `True`** (popped from `to_dict` output otherwise), so non-caller-facing reports — the common case — serialize identically to before; `from_dict` defaults it back to `False`, so the round-trip holds. `to_problem_document` never echoes it (new `_PROBLEM_DOCUMENT_OMITTED_FIELDS`) — it is internal redaction plumbing, not consumer classification.
- - `pipelex/core/interpreter/exceptions.py` (`PipelexInterpreterError`) and `pipelex/pipeline/validate_bundle.py` (`ValidateBundleError`) — the two INPUT-domain classes — set `_authors_caller_facing_message = True`. `BundleElaboratorError` inherits it (normal inheritance, unlike `_declared_title`). All other classes keep the safe `False` default.
- - `pipelex/cogt/exceptions.py` — `CogtError.to_error_report()` override threads `caller_facing_message` through too (resolves to `False`).
- - Docstrings: `DisclosureMode`, `ErrorReport.to_dict` / `to_problem_document`, `PipelexError._enrich_error_report_from_cause`, and the module constant comments rewritten to describe provenance-gated redaction.
-
- **Redaction behavior now in effect (STRICT):** `provider` / `model` / `provider_metadata` always dropped. If `caller_facing_message` — keep `message` + `user_action` + stable identifiers. Else — `message` → `INTERNAL_ERROR_PLACEHOLDER`, drop `user_action`, keep only the stable identifiers (`error_type` / `error_domain` / `error_category` / `retryable` / `title` / `type_uri`).
-
- **Tests:** `tests/unit/pipelex/test_error_report_disclosure_mode.py` rewritten for the new contract — includes the regression pin (`PipelexUnexpectedError` raised `from` a `PipelexInterpreterError` → report classified `error_domain=INPUT` but `caller_facing_message=False` → message redacted) and the Gap 2 pin (caller-facing passthrough strips provider fields). `test_error_report_problem_document.py` — old `INPUT`-passthrough test replaced; added STRICT-never-emits-provider-fields and `caller_facing_message`-never-an-extension-member tests. `test_class_level_metadata.py` — added a `caller_facing_message` class-level parametrized test.
-
- **Tracker:** `wip/error-handling/track-strict-disclosure-input-domain-gap.md` marked landed (banner + Acceptance checkboxes ticked).
-
- **Deferred / not done:** Only `PipelexInterpreterError` and `ValidateBundleError` are flagged caller-facing — the exact two INPUT-domain classes the tracker named. Classes like `MthdsDecodeError` (TOML decode) author arguably-caller-facing messages but are not flagged: the safe default redacts them, which is a usability nit, not a leak, and STRICT is not rendered for those surfaces today. Widening the flag set is a future follow-up if it proves needed.
-
- **Decisions:** D1 done. **D2 (Phase 2) still pending.**
-
- **Next action:** start **Phase 2** — finish wiring `request_id` into Temporal logs. Take **Decision D2** first (recommended: bound-adapter approach, rebuilt per activity/workflow invocation).
-
-- **2026-05-22 — Phase 1 follow-up: `MthdsDecodeError` collapsed into `PipelexInterpreterError`.** Resolves the inconsistency flagged in the Checkpoint 1 "Deferred" note. `MthdsDecodeError` was a one-line `TomlError` subclass raised in a single place (`interpreter.py`) as a verbatim field-for-field re-wrap of `TomlError` — it added no context, sat in the wrong type family (`ToolError` lineage → no `error_domain`, so a caller's broken-TOML `.mthds` was classified as a 500 instead of a 422), and forced `agent_output.py` to carry a manual `"MthdsDecodeError": "input"` classification patch.
-
- Per the user's decision, deleted the class. `interpreter.py` now formats the TOML line/column into the message and raises `PipelexInterpreterError` directly (already `error_domain=INPUT` + `caller_facing_message=True`); the original `TomlError` stays on the `__cause__` chain. The four `except MthdsDecodeError` blocks in `validate_bundle.py` fold into the existing `except PipelexInterpreterError` clauses (identical resulting `ValidateBundleError`, same message); the three CLI `except (PipelexInterpreterError, MthdsDecodeError)` tuples collapse to `except PipelexInterpreterError`; the `agent_output.py` hint + domain patch entries are removed; the `invalid_mthds.py` test cases expect `PipelexInterpreterError`. `docs/errors/` regenerated via `pipelex-dev generate-error-pages` (orphan `mthds-decode-error.md` removed, `index.md` updated). `make agent-check` clean; `make agent-test` green. There is now one interpreter-input error class, correctly classified — no `agent_output.py` patch needed.
-
-- **2026-05-22 — Phase 1 follow-up: `/code-review` pass.** An xhigh-effort `/code-review` of the Phase 1 + `MthdsDecodeError` commits found no runtime bug but flagged doc-coherence regressions: the Phase 1 STRICT-behavior change had updated only `track-strict-disclosure-input-domain-gap.md` and this file, leaving `CHANGELOG.md`, `wip/error-handling/api-companion-revisions.md`, and `wip/error-handling/README.md` still describing the old `error_domain == INPUT` passthrough. Fixed all three to describe the provenance-gated (`caller_facing_message`) rule; `README.md` "What's still open" no longer lists the now-landed STRICT gap (items renumbered). Also restored an `error_category`-retention assertion that the STRICT-redaction test rewrite had dropped. **Two findings left as judgment calls, not acted on:** (4) `bundle_elaborator.py:81` raises an internal "...this is a bug" invariant assertion as `BundleElaboratorError`, which inherits `caller_facing_message=True`, so STRICT would reflect that internal message — it is a defense-in-depth guard the code comments call "unreachable today"; the clean fix is to raise `PipelexUnexpectedError` there. (5) `to_dict(STRICT)` of a caller-facing report emits the internal `caller_facing_message: true` flag onto the lossy projection (harmless boolean; `to_problem_document` already scrubs it via `_PROBLEM_DOCUMENT_OMITTED_FIELDS`). `make agent-check` clean. Next action unchanged: start **Phase 2**.
-
-- **2026-05-22 — Phase 1 follow-up: applied review findings 4 & 5.** The two `/code-review` findings previously left as judgment calls are now fixed. (4) `bundle_elaborator.py:81` — the internal "…this is a bug" nested-directive guard now raises `PipelexUnexpectedError` instead of `BundleElaboratorError`. It is a genuine internal-invariant violation, so it no longer rides the caller-facing `PipelexInterpreterError` path (`interpreter.py`'s `except BundleElaboratorError` no longer catches it — it surfaces as an unexpected error, 500, message redacted under STRICT, which is correct). The other `BundleElaboratorError` raises (caller-facing collision / invalid-bundle messages) are unchanged. (5) `to_dict(STRICT)` of a caller-facing report no longer emits the internal `caller_facing_message` flag — new `_STRICT_PASSTHROUGH_DROPPED_FIELDS` constant drops it alongside the provider fields; the flag rides only the VERBOSE round-trip format. The STRICT-passthrough test assertion was flipped to pin its absence. `make agent-check` clean; `make agent-test` green. Next action unchanged: start **Phase 2**.
-
-- **2026-05-22 — Checkpoint 2 (Phase 2 complete).** `request_id` log wiring finished on `feature/API-readiness-2` as a single commit. `make agent-check` clean (pyright + mypy: 0 errors); `make agent-test` full suite green.
-
- **Decision D2:** bound adapter — implemented as decided (see the Decisions section).
-
- **What landed:**
-
- - `pipelex/temporal/log_temporal.py` — new `_RequestIdLog` base holds an instance-level `request_id`; `WorkflowLog` / `ActivityLog` subclass it. `_build_extra` is now an instance method reading the bound `request_id`. The per-method `request_id` kwarg — dead surface, no caller ever passed it — is **dropped** from every log method. The module-level `workflow_log` / `activity_log` singletons stay, unbound (`request_id is None`), for call sites with no `job_metadata` in scope.
- - `pipelex/temporal/tprl_pipe/wf_pipe_run.py` and `wf_pipe_router.py` — the workflow entry points that log. Each `run()` builds a per-invocation `workflow_log = WorkflowLog(request_id=<job_metadata>.request_id)` as its first statement; every existing `workflow_log.*` call in the function picks it up unchanged (the local shadows nothing — the import is now the `WorkflowLog` class). `WfPipeRun` reads `pipe_job.job_metadata.request_id`; `WfPipeRouter` reads `workflow_arg.job_metadata.request_id`.
- - Activities were checked: no Temporal activity logs via `activity_log` today (only `TemporalError._log_*` does, and it has no `job_metadata`), so there is no activity entry point to wire — `ActivityLog` keeps the symmetric bound capability for when one appears.
-
- **Wiring mechanism:** per-invocation bound `WorkflowLog`, rebuilt every workflow `run()` from that invocation's `JobMetadata` — no `ContextVar`, no module/process state. A new log call added inside a wired entry point carries `request_id` automatically.
-
- **Per-method kwargs:** dropped (not kept). `request_id` is held as instance state on the bound adapter; the kwargs were unused dead surface.
-
- **Tests:**
-
- - `tests/unit/pipelex/temporal/test_log_temporal_request_id.py` — pins the `_build_extra` path: a bound `WorkflowLog` / `ActivityLog` packs `extra={"request_id": ...}` into the log call, an unbound one passes `extra=None`.
- - `tests/integration/pipelex/temporal/test_wf_pipe_run_request_id_logging.py` — end-to-end: dispatches `WfPipeRun` (failing-router stub, modeled on `test_wf_pipe_run_failure_path.py`) with a `request_id` on `job_metadata`, captures the `temporalio.workflow` logger, asserts records carry `record.request_id`. Verified to have teeth — temporarily unbinding the logger made it fail (`request_ids seen: ['None']`), then reverted.
-
- **Docs:** `api-companion-revisions.md` §B Acceptance + the Stage 1 `WorkflowLog`/`ActivityLog` bullet + the "Net to the API team" post-review-follow-ups bullet rewritten to describe the landed wiring; `wip/error-handling/README.md` "What's still open" — the `request_id` log-wiring item removed, items renumbered; `log_temporal.py` docstrings state the wiring as fact.
-
- **Deferred / not done:** `TemporalError._log_critical` / `_log_error` (`temporal_error.py`) still log via the unbound singletons — they are error-bridge helpers, not entry points, and have no `job_metadata` in scope; threading `request_id` there is out of scope for Item B. The `wf_test_*` workflows likewise stay unbound (test infra, no inbound request id).
-
- **Decisions:** D1 + D2 done.
-
- **Next action:** start **Phase 3** — webhook payload reserved-key collision. Full analysis and options in [`wip/error-handling/track-webhook-payload-collision.md`](wip/error-handling/track-webhook-payload-collision.md); implement Option 1 (a `field_validator` on `WebhookTarget.payload` rejecting the reserved-key set at construction time).
-
-- **2026-05-22 — Phase 2 follow-up: `/code-review` pass.** An xhigh-effort `/code-review` of the Phase 2 commit (5-angle + sweep) found **no correctness bugs** — the `request_id` wiring, the `WorkflowLog` / `ActivityLog` refactor, and both tests verified clean across line-by-line, removed-behavior, cross-file, language-pitfall, and wrapper-correctness angles (all 7 method bodies confirmed to route to the right logger at the right level; the dropped per-method kwarg confirmed dead surface with no caller). Two low-severity test-hygiene tweaks applied: the integration test's `addHandler` / `setLevel` moved inside the `try` so the `finally` restore is structurally airtight; the unit test (`test_log_temporal_request_id.py`) parametrized over all seven severity methods — was `.info()` only — so 28 cases now pin every method's level + `extra`. `make agent-check` clean; both test files green. Next action unchanged: start **Phase 3**.
-
-- **2026-05-22 — Checkpoint 3 (Phases 3 & 4 complete).** The in-repo finalization of the error-handling overhaul is done on `feature/API-readiness-2`, landed as a single coherent commit. `make agent-check` clean (pyright + mypy: 0 errors); `make agent-test` full suite green.
-
- **Phase 3 — webhook payload reserved-key collision:**
-
- - `pipelex/pipe_run/delivery_assignment.py` — new `_RESERVED_WEBHOOK_PAYLOAD_KEYS` frozenset (`pipeline_run_id` / `status` / `result_url` / `error`) and a `field_validator` (`_reject_reserved_keys`, `mode="after"`) on `WebhookTarget.payload` that raises a `ValueError` naming the offending key(s) at construction time. A misconfigured webhook now fails when the `DeliveryAssignment` is built, not silently at delivery time. Option 1 from the tracker, implemented as planned.
- - `tests/unit/pipelex/pipe_run/test_delivery_assignment.py` — added to `TestDeliveryAssignment`: a parametrized reject test (one case per reserved key), a multi-collision test (the error names every offending key), and a clean-payload pass test.
- - Tracker `track-webhook-payload-collision.md` — marked landed (banner added).
-
- **Phase 4 — test coverage backfill:**
-
- - `recover_error_report` — `tests/unit/pipelex/temporal/test_recover_error_report.py` gained `test_found_but_invalid_report_dict_raises_validation_error`: a dict that `_find_error_report_dict` accepts (`error_type` + `message`) but that fails `ErrorReport` validation (missing required `title` / `type_uri`) raises `pydantic.ValidationError` — pins the current contract that a found-but-invalid report is an internal contract bug, not synthesized away. (The TODOS Phase 4 line names this file under `tests/integration/` — stale path; the file is and always was under `tests/unit/`. Harmless.)
- - `_message_from_exc` — new `tests/unit/pipelex/temporal/test_message_from_exc.py` (`TestMessageFromExc`): the `id()`-based cycle guard (a self-referential `__cause__` chain terminates) and the `repr(exc)` fallback (every message in the chain empty). Imports the private function with the codebase's established `# noqa: PLC2701 # pyright: ignore[reportPrivateUsage]` pattern.
- - `DeliveryActivityArg` — new `tests/unit/pipelex/temporal/test_delivery_activity_arg.py` (`TestDeliveryActivityArg`): a focused JSON round-trip (`model_validate_json(model_dump_json())`) with a populated nested `ErrorReport` (incl. a nested `UserAction`), catching a nested-model serialization regression without a live Temporal worker.
- - Logging `request_id` path — confirmed `tests/unit/pipelex/temporal/test_log_temporal_request_id.py` (from Phase 2) exists and is green (28 parametrized cases).
-
- **Doc coherence (beyond the strict checklist, for clean-slate consistency):** `wip/error-handling/README.md` "What's still open" + "Status at a glance" — Phases 3-4 removed from the open list, items renumbered (only webhook signing + the metadata-model long tail remain open); `api-companion-revisions.md` "Net to the API team" — the post-review follow-ups now all marked landed; `CHANGELOG.md` `[Unreleased]` — the delivery-webhook entry gained a sentence noting reserved keys are now rejected at construction (the webhook feature is unreleased, so this is a constraint on a new feature, not a breaking change to shipped software).
-
- **Deferred / not done:** Nothing from Phases 0-4. The two "Minor follow-ups" (`pascal_case_to_kebab` acronym collision; `error_module_registry` discovery fragility) are still open — TODOS marks them low-priority and batchable into any checkpoint; left for a future pass. Phase 5 (webhook signing) is the separate cross-repo track, untouched.
-
- **Decisions:** D1 + D2 done (Phases 1-2). No new decision in Phases 3-4.
-
- **Next action:** All in-repo follow-ups (Phases 0-4) are done — `feature/API-readiness-2` is shippable. **Decision (2026-05-22, with the user): stop here** — no PR opened and Phase 5 not started; both deferred to a later session. To resume, the open work is: (1) open a PR for `feature/API-readiness-2` — Phases 0-4 are a complete, reviewable unit; (2) **Phase 5** — webhook signing, the separate cross-repo track (pipelex + API in lockstep) per [`wip/security/webhook-signing.md`](wip/security/webhook-signing.md); (3) the two low-priority "Minor follow-ups" (`pascal_case_to_kebab` acronym collision, `error_module_registry` discovery fragility), batchable into any future checkpoint.
-
-- **2026-05-22 — Checkpoint 3 follow-up: `/code-review` pass.** An xhigh-effort `/code-review` of the Phases 3-4 commit (5 angles + sweep, three independent finders) found **no runtime bug** — the `WebhookTarget.payload` reserved-key validator verified correct across line-by-line, cross-file (the reserved set exactly matches the four keys `_notify_webhook` writes), language-pitfall, bypass-path, and doc-coherence angles. One real test-quality defect fixed: the reserved-key tests' message-quality assertions were vacuous — `str(ValidationError)` contains every payload key via pydantic's echoed `input_value={...}` (and "error" via boilerplate), so `match=reserved_key` and `assert "error" in message` passed regardless of the validator's own message. Both now pin the validator's distinctive `reserved keys: [...]` phrase, which the input echo and boilerplate cannot satisfy. The core "rejects reserved keys" contract (`pytest.raises(ValidationError)`) was already sound — only the message-naming check was hardened. `make agent-check` clean; reserved-key tests green. Committed as `bfa3cfba`. Next action unchanged: in-repo work (Phases 0-4) done; PR + Phase 5 deferred per the user.
-
-- **2026-05-23 — Checkpoint 6 (Phase 6 complete).** Error-class location convention enforced and `error_module_registry.py` deleted on `feature/API-readiness-2`. `make agent-check` clean (ruff + pyright + mypy: 0 issues); `make agent-test` full suite green.
-
- **Decision D3:** `exceptions.py` (default — one per package directory) + `<topic>_exceptions.py` (for directories hosting multiple separate-concern error modules, matching the existing `pipelex/plugins/*/` convention). The `*_errors.py` synonym is dropped — it produced exactly the kind of drift the registry was papering over.
-
- **TDD path:** `tests/unit/pipelex/errors/test_error_class_location_convention.py` written first — two complementary checks. (1) An AST scan of every `.py` under `pipelex/` that resolves the transitive `PipelexError` descendant set by class-name graph traversal and asserts each one lives in a properly-named module. (2) A runtime backstop that walks `PipelexError.__subclasses__()` transitively after normal imports — catches dynamic / decorator-registered cases the AST scan would miss, and is the regression net once the registry was gone. Both tests failed on first run with **43 misplaced classes** (AST scan — the authoritative target) / **28 currently loaded** (runtime backstop), agreeing on the same offenders.
-
- **Refactor (Phase 6.2) — files moved or created:**
-
- - Appended to existing `exceptions.py`: `PipelineManagerNotFoundError` / `PipelineManagerAlreadyExistsError` / `ValidateBundleError` → `pipelex/pipeline/exceptions.py`; `BundleElaboratorError` → `pipelex/core/interpreter/exceptions.py`; `StuffSpecFactoryError` → `pipelex/core/pipes/stuff_spec/exceptions.py`; `KitIndexLoadingError` → `pipelex/kit/exceptions.py`; `EnvVarNotFoundError` → `pipelex/system/exceptions.py`; `DryRunError` → `pipelex/pipe_run/exceptions.py`; `BaseModelPayloadConverterError` → `pipelex/temporal/exceptions.py`; `AnthropicFactoryError` → `pipelex/plugins/anthropic/anthropic_exceptions.py`.
- - New `exceptions.py` modules: `pipelex/pipe_operators/shared/exceptions.py` (`WithImagesFilterError`, `UnusedInputError`); `pipelex/system/registries/exceptions.py` (`FuncRegistryError`); `pipelex/builder/concept/exceptions.py` (`ConceptSpecError`); `pipelex/cogt/models/exceptions.py` (`ModelReferenceParseError`); `pipelex/cogt/extract/exceptions.py` (`ExtractInputError`); `pipelex/cogt/img_gen/exceptions.py` (`FalCredentialsError`); `pipelex/tools/aws/exceptions.py` (`AwsCredentialsError`); `pipelex/tools/pdf/exceptions.py` (`PyPdfium2RendererError`); `pipelex/tools/typing/exceptions.py` (`ModuleFileError`); `pipelex/tools/misc/exceptions.py` (consolidates `TomlError` + `ContextProviderError` + `FileTypeError` + `ArgumentTypeError` + `JsonTypeError`); `pipelex/tools/secrets/exceptions.py` (consolidates `SecretNotFoundError` from the renamed `secrets_errors.py` + the three `secrets_utils.py` errors `VarNotFoundError` / `VarFallbackPatternError` / `UnknownVarPrefixError`).
- - Renames (drop `*_errors.py`): `pipelex/tools/jinja2/jinja2_errors.py` → `pipelex/tools/jinja2/exceptions.py`; `pipelex/cogt/templating/template_errors.py` → `pipelex/cogt/templating/exceptions.py`. `pipelex/tools/secrets/secrets_errors.py` deleted (content folded into the new `exceptions.py`).
- - New `<topic>_exceptions.py` modules (plugin-prefix pattern): `pipelex/plugins/bedrock/bedrock_exceptions.py` (`BedrockFactoryError` + `BedrockWorkerConfigurationError`); `pipelex/plugins/google/google_exceptions.py` (`GoogleLLMWorkerError` + `GoogleImgGenWorkerError`); `pipelex/plugins/openai/openai_exceptions.py` (`OpenAIClientFactoryError` + `VertexAIConfigError` + `VertexAICredentialsError`); `pipelex/plugins/azure_rest/azure_exceptions.py` (`AzureCredentialsError`).
- - **Adjacent cleanup, in scope:** the broken back-compat shim `pipelex/pipe_operators/llm/template_image_analyzer.py` (re-export aggregator referencing the no-longer-present `WithImagesFilterError` / `UnusedInputError` after the move) was deleted, its three callers migrated to the canonical paths. The sibling `pipelex/pipe_operators/llm/image_reference.py` shim was left alone — it pre-dates this refactor and is not error-class-related.
- - No back-compat shims or re-exports left behind anywhere. Every import site updated by class name across `pipelex/`, `tests/`, and `docs/` examples.
-
- **Registry deletion (Phase 6.3):** `pipelex/errors/error_module_registry.py` deleted. The `iter_pipelex_error_subclasses` helper now lives directly in `error_pages_generator.py` as a simple transitive `__subclasses__()` walk — no filesystem scan, no `_NON_STANDARD_ERROR_MODULES` allowlist, no force-import phase. The two callers (`error_pages_generator.generate_error_pages` + the URI-uniqueness test in `tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py`) import from the new location. Normal production imports now reach every error class — the convention test guarantees it.
-
- **Docs regeneration:** `pipelex-dev generate-error-pages` ran cleanly — 209 total pages, 32 updated (their "Defined in" field changed to the new module), 177 unchanged, **1 new page** (`docs/errors/base-model-payload-converter-error.md` — `BaseModelPayloadConverterError` was previously silently missed by the registry's filename pattern scan). No orphan pages; the generator walks the current hierarchy.
-
- **Rule + kebab-slug collision defense (Phase 6.4):**
-
- - New "Error class location" section in `.claude/rules/python-standards.md` — states the convention, points at the convention test, calls out the `*_errors.py` ban and the topical-split escape hatch, and warns about acronym-casing kebab collisions.
- - `error_pages_generator.generate_error_pages` now asserts kebab-slug uniqueness across `target_classes` before writing pages — raises a loud `RuntimeError` naming the two colliding classes if e.g. both `LLMError` and `LlmError` resolve to `llm-error`. Today this is caught reactively by `test_pipelex_error_type_uri_uniqueness`; now it fails at generation time too.
- - Short note added near `PipelexError.type_uri()` describing the collision footgun and pointing at both defenses.
- - New unit test `test_kebab_slug_collision_raises` in `test_error_pages_generator.py` pins the new guard with a synthetic `LLMError` / `LlmError` pair.
-
- **Test count:** 9 in `tests/unit/pipelex/errors/` (2 convention, 7 generator), all green. Both convention tests verified to have teeth — they failed on first run with the misplaced list.
-
- **Deferred / not done:** Nothing from Phase 6 itself. The `_for_api/CLAUDE.md` "Reference it from `pipelex/CLAUDE.md`" sub-bullet is N/A — no such file exists; the workspace consults `.claude/rules/python-standards.md` (which now carries the rule) from the top-level CLAUDE.md.
-
- **Decisions:** D1 + D2 + D3 all done.
-
- **Next action:** Stop at this checkpoint per the project policy. Confirm with the user before opening a PR — Phase 6 is a large, file-touching refactor (173 changed files: 1 deletion, 16 new `exceptions.py`/`*_exceptions.py` modules, 1 renamed module, ~150 source/test/doc edits) that should be reviewed as a single coherent commit (or a small ordered series: test-first → moves → registry deletion → rule).
-
-- **2026-05-23 — Phase 6 follow-up: `/code-review` pass at xhigh effort.** Five independent finder angles + Phase 2 verifiers + a sweep finder found a **shipped regression in the Phase 6 commit `0fa4440b`**: `docs/errors/index.md` dropped 23 entries (HEAD~1 = 230, HEAD = 208). The new `__subclasses__()`-based `iter_pipelex_error_subclasses` doesn't reach plugin/factory `*_exceptions.py` because plugin workers/factories use deferred imports (rightly — the SDKs are heavy/optional). Class names dropped: `AnthropicModelListingError`, `AnthropicSDKUnsupportedError`, `AnthropicWorkerConfigurationError`, the six gateway errors, the four mistral errors, the three portkey errors, `FalCredentialsError`, both graph errors, `PipeBatchFactoryError`, both pipe-search errors, `PipelexBundleSpecBlueprintError`. The OLD `error_module_registry._discover_standard_exception_modules()` filesystem-scan + force-import had been silently doing this work; Phase 6 deleted it on the premise that "natural imports reach every error module" — false premise.
-
- **Findings landed in this session (Fix #2 + Fix #3 + Fix #4 + orphan cleanup):**
-
- - **Fix #4 (`tomli` TYPE_CHECKING regression)**: `pipelex/tools/misc/exceptions.py` — moved `import tomli` out of `TYPE_CHECKING`. Pre-refactor `toml_utils.py` had it at module-top; the Phase 6 move demoted it. `typing.get_type_hints(TomlError.from_tomli_error)` now resolves cleanly; no current caller exercises that path, but the gap blocked any future autodoc / annotation-introspecting tool. Verified live: `python -c "import typing; from pipelex.tools.misc.exceptions import TomlError; typing.get_type_hints(TomlError.from_tomli_error)"` succeeds.
- - **Fix #2 (orphan-page deletion)**: `pipelex/errors/error_pages_generator.py` — added a fourth `removed` bucket to `ErrorPagesReport` and a `_remove_orphans()` helper. Generated pages whose slug is no longer in `target_classes` are deleted; pages with `<!-- pipelex:authored -->` are preserved verbatim; pages with neither marker (out-of-scope hand-files) are left untouched. The dev CLI command's success panel surfaces the new `Removed: N` count. Three new unit tests pin the behavior: orphan deletion, authored-marker preservation, unmarked-file isolation.
- - **Fix #3 (completeness assertion)**: `tests/unit/pipelex/errors/test_error_class_location_convention.py` — refactored the AST scan into a reusable `_ast_discover_pipelex_error_subclasses()` helper, then added `test_runtime_walk_discovers_every_ast_classified_subclass`. It compares the AST-discovered class-name set to the runtime-loaded class-name set after normal imports, fails loudly with the missing names if they diverge. Marked `@pytest.mark.xfail(strict=True, ...)` pending Phase 7 / Decision D4. When the discovery contract is fixed, the test passes and `strict=True` turns the unexpected pass into a CI failure that prompts the marker's removal.
- - **Orphan cleanup**: ran `pipelex-dev generate-error-pages` on the real `docs/errors/` — 23 stale per-class `.md` files (the ones dropped by the headline regression) deleted, `Written: 0 · Unchanged: 209 · Preserved: 0 · Removed: 23`. Disk now consistent with the production-imports discovery state, no orphan pages served by mkdocs.
-
- **Fix #1 deferred to Phase 7 — see the new section above.** The architectural decision (Option A explicit manifest vs Option B eager filesystem-walk import vs Option C build-time codegen) is Decision D4, pending. The xfail completeness test will start passing as soon as Phase 7 lands; remove its marker then.
-
- **What was NOT fixed (rejected as cosmetic or low-priority):**
-
- - DFS vs BFS docstring wording mismatch in `iter_pipelex_error_subclasses` — sorted output unaffected; deferred.
- - AST scan name-collision false positive risk — no current duplicate-short-name in the tree triggers it; would refactor when a real case arises.
- - `path.relative_to(_PIPELEX_ROOT.parent)` `ValueError` for non-pipelex subclasses — no downstream caller today; not a blocker.
- - Stale doc reference at `docs/under-the-hood/image-handling-in-llm-prompts.md:442` to the deleted shim — reader-facing only, batched into the next docs sweep.
-
- **Decisions:** D1 + D2 + D3 done; D4 pending (Phase 7).
-
- **Next action:** Phase 7 — close the discovery-contract gap per Decision D4. Cold-start context for a fresh session is in the Phase 7 section above. After Phase 7 lands and the `xfail` is removed, the in-repo error-handling work for `feature/API-readiness-2` is fully done (Phases 0-7).
-
-- **2026-05-23 — Checkpoint 7 (Phase 7 complete).** Error-class discovery contract closed on `feature/API-readiness-2`. `make agent-check` clean (ruff + pyright + mypy: 0 issues); targeted tests (`tests/unit/pipelex/errors/` + `tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py`) all green; production bootstrap (`Pipelex.make()`) verified unchanged — same 203 subclasses loaded, helper not triggered.
-
- **Decision D4:** Option B' — scoped rglob + force-import in dev/test consumers only. Rejected Option A (explicit manifest) because it re-introduces a hand-maintained list (the very drift target Phase 6 was attacking, just in disguise); rejected Option B (eager filesystem walk at `Pipelex.make()`) because production bootstrap shouldn't filesystem-touch; rejected Option C (build-time codegen) as unnecessary ceremony. Empirical verification underwrites B': every one of the 63 `exceptions.py` / `*_exceptions.py` files imports only base error classes (`PipelexError` / `CogtError` / `CredentialsError` / `ClickException`) — zero SDK pulls. Phase 6's filename convention guarantees the rglob is complete; no allowlist needed.
-
- **What landed:**
-
- - `pipelex/errors/error_pages_generator.py` — new `_force_load_all_error_modules()` helper (~17 lines incl. docstring), decorated with `@functools.cache` so the first call walks `pipelex/` for `exceptions.py` + `*_exceptions.py` and `importlib.import_module`s each, subsequent calls are no-ops. `iter_pipelex_error_subclasses()` calls it as its first statement. New `import functools` + `import importlib` + `import pipelex` (for `pipelex.__file__` resolution) added at the top.
- - `tests/unit/pipelex/errors/test_error_class_location_convention.py` — `@pytest.mark.xfail(strict=True, ...)` removed from `test_runtime_walk_discovers_every_ast_classified_subclass`; the test now passes positively. Docstring updated to describe the test as a regression net rather than a future-failure marker. Unused `import pytest` removed.
- - `.claude/rules/python-standards.md` (workspace level) — "Error class location" section gained a "Discovery contract" paragraph documenting the scoped force-import strategy and stating explicitly that adding a new error class is a one-step operation (no manifest to update).
- - `docs/errors/` regenerated via `.venv/bin/pipelex-dev generate-error-pages` — `Written: 35 · Unchanged: 208 · Preserved: 0 · Removed: 0`. 34 new per-class pages (anthropic family, azure_rest, bedrock family, gateway family × 6, google × 2, graph × 2, mistral × 4, openai × 3 incl. VertexAI, portkey × 3, pipe-batch, pipe-search × 2, plus `ConceptSpecError`, `FalCredentialsError`, `PipeBatchFactoryError`, `PipelexBundleSpecBlueprintError`, `PyPdfium2RendererError`) + `docs/errors/index.md` regenerated to list them.
-
- **Discovery set: before vs. after.**
-
- - AST scan: 241 PipelexError subclasses on disk (unchanged).
- - Runtime walk after naked `import pipelex`: 19 subclasses (unchanged).
- - Runtime walk after `Pipelex.make()`: 203 subclasses (unchanged — production path untouched).
- - Runtime walk after `iter_pipelex_error_subclasses()`: **241 → 241** (formerly 203, now equals AST set by construction). The 38-class gap is closed.
- - The 4-page gap between the AST set diff and the 34 new files is `KitError` / `KitIndexLoadingError` / `PipelexCLIError` / `ReadinessCheckError` — these were already loaded by the dev CLI command's own bootstrap path before the helper ran, so their pages were already present.
-
- **CHANGELOG:** `[Unreleased]` — one-line entry under the existing error-handling block noting `docs/errors/` is back to full coverage (34 previously-missing per-class pages restored).
-
- **Deferred / not done (record-only):**
-
- - AST-level "no SDK imports in `*_exceptions.py`" check on the convention test. Empirical verification suffices; revisit if the precondition is ever violated.
- - Folding `iter_pipelex_error_subclasses` into a dedicated `pipelex/errors/discovery.py` module. Marginal organizational gain; not worth the diff.
-
- **Decisions:** D1 + D2 + D3 + D4 all done. The in-repo error-handling work for `feature/API-readiness-2` is now fully complete (Phases 0-7).
-
- **Next action:** Open the PR for `feature/API-readiness-2` against `dev`. Phase 5 (webhook signing) is the remaining cross-repo track — independent, lands on its own schedule per [`wip/security/webhook-signing.md`](wip/security/webhook-signing.md). Handoff drafts for the API team are at [`wip/api-readiness-2-handoff-drafts.md`](wip/api-readiness-2-handoff-drafts.md) — both human (Slack) and agent-prompt forms ready.
-
-- **2026-05-27 — API-side adapt plan written at workspace level.** Cross-repo coordination scaffolding now in place. The pipelex-api agent in `../pipelex-api/` independently audited their TODOS + the pipelex-side `wip/api-readiness-2-handoff-drafts.md` and produced a recap of the four surface-touching deltas (Phase 6 import moves + `MthdsDecodeError` deletion; STRICT provenance keying; `WebhookTarget` reserved-key validator; native `JobMetadata.request_id`) plus their own deferred work (Phase 4 Temporal webhook recovery, Phase 5 docs/archive). Their plan: run pipelex-api's test suite against the editable pipelex first to scope the delta concretely, then walk the handoff list, then decide on Phase 4 fold-in. Cross-checked against the pipelex side — diagnosis is correct.
-
- **Workspace-level plan landed at `../wip/adapt-pipelex-api-to-feature-API-readiness-2.md`** — cold-start-safe agent prompt for a fresh session opened at `/Users/lchoquel/repos/Pipelex/` (workspace root, one level above both repos). Structure: workspace map → read-first list → delta summary → Phases A–H (validate baseline → fix imports → fix WebhookTarget → STRICT audit → wire native `request_id` → fold-or-split decisions on F/G → verify + ship) → verification matrix → don'ts → handoff checkpoint. Four `⛔ CHECKPOINT` hard-stops at the natural handoff points (A after baseline failure-bucketing; BC after mechanical fixes; DE when the adapt slice is shippable; H after PR is open) — each requires recording state in both `pipelex-api/TODOS.md` (new Phase A0 section) and this Session log, closing the cross-repo loop. Webhook signing (Phase 5) explicitly out of scope per the original handoff doc.
-
- **Decisions deferred to the API-side session** (surface at Checkpoint A, not pre-baked): (F) fold the deferred Temporal webhook recovery into the adapt PR or split — default fold-in since Phase E already does the `request_id` plumbing it depends on; (G) fold the deferred docs/archive — default split, docs deserve their own review cycle.
-
- **No code changes on the pipelex side in this session.** Branch `feature/post-pr933-followups` unchanged; the API-team feedback loop is the work that's been done. **Next action:** hand the workspace plan to a fresh Claude Code session at `/Users/lchoquel/repos/Pipelex/`, or pick up Phase 5 (webhook signing) on the pipelex side independently per [`wip/security/webhook-signing.md`](wip/security/webhook-signing.md) — the two tracks no longer block each other.
-
-- **2026-05-24 — API-side adapt PR ready on `pipelex-api/feature/Adapt-to-pipelex-update-2`.** Phase A0 ("Adapt to post-#931/#933 pipelex") landed against the editable `_for_api/feature/post-pr933-followups` install. What the API team picked up from this body of work: Phase 6 import-path moves (`EnvVarNotFoundError` from `pipelex.system.exceptions`, two test imports updated; no production touches); Phase 3 `WebhookTarget` reserved-key validator (no-op — the API's single call site was already clean); Phase 1 STRICT-disclosure provenance keying (no-op — the API delegates wholesale to `report.to_problem_document(disclosure_mode=...)`, so the upstream flip flows through untouched; the two `error_domain == INPUT` sites in `api/exception_handlers.py` are log-level switches, not wire-disclosure ones, and remain correct); Phase 2 native `request_id` (the `start` route now reads its request-scoped contextvar and passes `request_id=` to `pipeline_run_setup(...)` — pipelex then carries it onto `JobMetadata.request_id` and every worker `WorkflowLog` record); Phase 7 acronym-casing (`InvalidJSON` title now `Invalid JSON`, one test assertion updated). Also added a **T6 cross-path consistency regression** (`tests/unit/test_webhook_recovery.py`) pinning that the same source `ErrorReport` renders identical classification fields across the sync RFC 7807 response and the webhook `error` payload. Test count: 188 → 193; `make fui && make c && make tp` clean. PR not yet opened pending user review of the commit shape. **Not adapted (deferred upstream):** structured `event=webhook_delivery` / `event=webhook_failure` logging at `pipelex/pipe_run/delivery_executor.py:270` — that's a pipelex change, not an API change. Should land as a separate pipelex PR. The API-team adapt PR documents this as a known follow-up.
diff --git a/wip/error-handling/archive-todos-api-readiness-4.md b/wip/error-handling/archive-todos-api-readiness-4.md
deleted file mode 100644
index 2d875bbcc..000000000
--- a/wip/error-handling/archive-todos-api-readiness-4.md
+++ /dev/null
@@ -1,181 +0,0 @@
-# Implementation Plan — `feature/API-readiness-4`
-
-Pipelex-side cleanup branch picking up the upstream tail of the API error-handling endeavour. The API consumer (`pipelex-api`, branch `feature/Adapt-to-pipelex-update-3`) has shipped through Phases 0-5 plus Phase A0 / A1 and is at a "finalize" moment; what remains for the API to fully discharge that endeavour is a handful of upstream-pipelex items. **This branch is those items.**
-
----
-
-## Cold-start reading order
-
-Read in this order to understand why this branch exists at all:
-
-1. `wip/error-handling/README.md` — current state of error handling across pipelex; the high-level map.
-2. `wip/error-handling/archive-todos-api-readiness-2.md` — the prior ledger (formerly the repo-root `TODOS.md`, archived 2026-05-28). This branch is the successor.
-3. `../pipelex-api/wip/pipelex-changes.md` Stage 7 (items #10-#15) — the **authoritative per-item context** for five of the items on this branch. Each item there has a *What / Why / Where / How* writeup with empirical reproductions against the pinned pipelex. Do not re-derive that context here; consume it from there.
-4. `../pipelex-api/TODOS.md` "Deferred / next-track work" → "Upstream-pipelex follow-ups" — names the same items at the API end, in the consumer's voice. Useful sanity check.
-5. `wip/console-targets-and-agent-cli-stdout.md` and `wip/structured-logging/kickoff.md` — relevant background for the **webhook-delivery logging** item below; see the sequencing note in that section before starting.
-
-The `test_failed_webhook_log_includes_request_id_when_set` regression test already landed on the base (`feature/API-readiness-2`, commit `74b68bd7`) and is present in the working tree — do **not** re-add it. `git log feature/API-readiness-2..HEAD --oneline` shows this branch adds only planning docs on top of that base. Everything below is what to implement.
-
----
-
-## What this branch is NOT
-
-- Not the structured-logging refactor. That has its own kick-off doc and its own future branch (`refactor/structured-logging` or similar — see `wip/structured-logging/kickoff.md`).
-- Not webhook signing. That's the cross-repo lockstep track owned by `wip/security/webhook-signing.md`.
-- Not a `dev` merge train. If `dev` has moved, treat that as a separate prep step, not part of this plan.
-
----
-
-## Items
-
-Six concrete items, all flagged in `pipelex-changes.md` Stage 7 or surfaced by the API-side `TODOS.md`. None blocks any API release on its own; together they discharge the upstream tail of the error-handling endeavour and let the API drop a small number of follow-up catches and workarounds.
-
-Sequencing inside this branch is flexible — every item is independent except where called out. Suggested order is "smallest first to build momentum, then the two bigger ones."
-
-### 1. `ErrorDomain.is_input` (and siblings) — `@property` helpers on the enum
-
-- [x] **Status:** Done (2026-05-28). Two pieces landed in `pipelex/base_exceptions.py`: (a) `ErrorDomain.is_input` as an exhaustive-`match` `@property` (the enum-level single source of truth), and (b) a module-level `error_domain_is_input(error_domain: ErrorDomain | str | None) -> bool` that coerces the serialized form and delegates to the property — paralleling the existing `error_domain_to_http_status(...)`. The function is the one the API actually consumes: both API call sites hold `error_domain` as `str | None` (`ErrorReport.error_domain` is typed `str | None`; the problem-document dict value is a plain str), so the bare `report.error_domain.is_input` the spec sketched would not type-check. Covered by `tests/unit/pipelex/exceptions/test_error_domain.py::TestErrorDomain` (`test_is_input` + `test_error_domain_is_input`). Only `is_input` landed — `is_config` / `is_runtime` deferred until a need surfaces. The API consumes this via the editable local dependency on this worktree (no PyPI pin bump needed); the API-side switch off `== ErrorDomain.INPUT` at `api/exception_handlers.py:204,253` is being made now.
-**Authoritative spec:** `../pipelex-api/wip/pipelex-changes.md` item #14.
-**Where:** `pipelex/base_exceptions.py` — the `ErrorDomain` `StrEnum`.
-
-Add `@property` helpers (`is_input`, and `is_config` / `is_runtime` as needs surface) so callers read state via `report.error_domain.is_input` instead of `report.error_domain == ErrorDomain.INPUT`. This is the canonical project remediation for single-state enum checks (see `python-standards.md`) — call sites stay one-liners, the enumeration lives in one place.
-
-**Sequence first:** every other item benefits from being able to use the helper at call sites it touches. Trivial change; ~20 lines + a test. The API-side `archive-todos-api-readiness-2.md` Phase 3 review Q9 left two call sites in `api/exception_handlers.py` deliberately on `== ErrorDomain.INPUT` waiting for this; one follow-up commit there will switch them once this lands.
-
----
-
-### 2. `EnvVarNotFoundError` should carry `error_domain = ErrorDomain.CONFIG`
-
-- [x] **Status:** Done (2026-05-28). Added `error_domain = ErrorDomain.CONFIG` as a class attribute on `EnvVarNotFoundError` in `pipelex/system/exceptions.py`, so its rendered `ErrorReport` / RFC 7807 problem document classifies as a config-domain failure (an operator sets the missing env var, not the caller). HTTP status is unchanged — both `None` and `CONFIG` map to 500. Covered by `tests/unit/pipelex/exceptions/test_class_level_metadata.py::TestClassLevelMetadata::test_error_domain` (new `env_var_not_found` parametrize case). The API consumes this via the editable local dependency on this worktree.
-**Authoritative spec:** `../pipelex-api/wip/pipelex-changes.md` item #10.
-**Where:** `pipelex/system/exceptions.py` (note: moved here from `pipelex/system/environment.py` during the Phase 6 import-path moves the API already adapted to — the spec doc still names the old path).
-
-Today `EnvVarNotFoundError` is domain-less (it's a `ToolError`; neither parent sets `error_domain`). A missing required env var is the textbook `CONFIG`-domain failure — an operator, not the caller, fixes it. Add `error_domain = ErrorDomain.CONFIG` as a ClassVar so the rendered `ErrorReport` / RFC 7807 problem document classifies correctly. HTTP status is unaffected (both `None` and `CONFIG` map to 500).
-
-This is the upstream half of the "original bug" the entire endeavour started from — a deployment that forgot to set `COMPLETION_CALLBACK_SECRET`. The API already classifies its own config faults as `CONFIG`; this brings pipelex-authored ones into alignment.
-
----
-
-### 3. `parse_concept_spec` should validate `structure` shape before iterating
-
-- [x] **Status:** Done (2026-05-28). Two parsing functions now shape-validate raw caller input before iterating, raising typed `INPUT`-domain errors instead of leaking bare `AttributeError`/`TypeError`/`ValueError`. (a) `parse_concept_spec` (`concept_ops.py`) rejects a non-mapping `structure` and any field value that is neither a description string nor a field-spec mapping, raising `ConceptSpecError`. (b) `parse_pipe_spec` (`pipe_ops.py`) rejects a non-list `steps`/`branches` or a non-mapping entry within them, raising the new `PipeSpecError`; the raw-iterate logic moved into a shared `_normalize_sub_pipe_list(...)` helper. Both error classes now carry `error_domain = ErrorDomain.INPUT` + `_authors_caller_facing_message = True` — `ConceptSpecError` (`builder/concept/exceptions.py`) gained the domain (it was previously domain-less); `PipeSpecError` is new (`builder/pipe/exceptions.py`). Docstrings on both functions now list every exception actually raised. Covered by new cases in `tests/unit/pipelex/builder/operations/test_parse_concept_spec.py` and `test_parse_pipe_spec.py` (typed-error + INPUT-domain assertions). Verified end-to-end through both consumers: `pipelex-agent concept`/`pipe` now emit `{"error_type": "ConceptSpecError"|"PipeSpecError", "error_domain": "input"}` instead of a bug-looking bare type. Error doc pages regenerated (`pipelex-dev generate-error-pages`) — added `pipe-spec-error.md`, refreshed `concept-spec-error.md`; the run also picked up two pre-existing stale pages unrelated to this item (`env-var-not-found-error.md` from item #2, and a missing `async-execution-not-enabled-error.md`). The API consumes this via the editable local dependency on this worktree; the API-side narrow `/build/concept` + `/build/pipe` route catches are API-side follow-ups, not this branch.
-**Authoritative spec:** `../pipelex-api/wip/pipelex-changes.md` item #11.
-**Where:** `pipelex/builder/operations/concept_ops.py` — the `parse_concept_spec(...)` function.
-
-The function iterates `spec_data["structure"]` before calling `ConceptSpec.model_validate(...)`. Non-dict `structure`, or fields that are neither string nor dict, leak bare `AttributeError` / `TypeError` (undocumented; the docstring only declares `ValidationError`). Empirical reproductions live in the spec doc.
-
-Fix is upstream shape validation — either raise a typed `PipelexInputError`-equivalent, or a `pydantic.ValidationError` via a thin `model_validate(...)` over the raw input shape before the iteration. Update the docstring to list every exception actually raised.
-
-The API today cannot safely catch these at the route — `AttributeError` / `TypeError` are also the types a real programming bug would raise, so a route-level catch would mask genuine bugs. Once this lands, the API's `/build/concept` route gets a narrow, typed catch.
-
-While here: sweep `pipelex/builder/operations/*.py` for the same pattern (raw-iterate-then-validate). `parse_pipe_spec` has it too — it iterates `spec_data["steps"]` / `spec_data["branches"]` and calls `dict(step)` on each entry before `model_validate`, so a non-list `steps` / `branches` or non-mapping entries leak bare `TypeError` / `ValueError` ahead of validation. Route those through the same narrow shape-validation path before iterating. (The bad-`pipe_type` `ValueError` is a separate, already-documented case — that one is narrow enough to leave.)
-
----
-
-### 4. `LocalStorageProvider` should wrap raw `OSError` as a `StorageLocalError`
-
-- [x] **Status:** Done (2026-05-28). Added `StorageLocalError(StorageError)` (with `_declared_title = "Local storage error"`) to `pipelex/tools/storage/exceptions.py`, paralleling `StorageS3Error` / `StorageGcpError`. Both filesystem methods in `local_storage_provider.py` now wrap raw `OSError`: `_store` wraps the `mkdir` + `aiofiles.open(...).write(...)` block (`ENOSPC` / `EACCES` / `EROFS` / `FileExistsError` / `EIO` → `StorageLocalError`); `_load_with_metadata` wraps the `aiofiles.open(...).read()` call, with an explicit `except FileNotFoundError` branch first that routes the TOCTOU window (file removed between the `exists()` check and the open) to `StorageFileNotFoundError`, so "file not found" stays the same typed error regardless of timing, and a generic `except OSError` → `StorageLocalError` for the rest (`PermissionError` / `IsADirectoryError` / `EIO`). `public_url` does no filesystem I/O, so it's untouched. Docstrings updated to list `StorageLocalError`. Covered by three new cases in `tests/unit/pipelex/tools/storage/test_local_storage_provider.py` (store→`FileExistsError` via blocker file, load→`IsADirectoryError` via dir-at-key, load→TOCTOU `FileNotFoundError` via `aiofiles.open` monkeypatch) — each asserts the typed wrapper and `__cause__` is an `OSError`. Error doc page generated (`pipelex-dev generate-error-pages`) — added `storage-local-error.md`, refreshed `index.md`; no incidental stale pages this run. The API consumes this via the editable local dependency on this worktree; the API-side narrow storage-route catches are API-side follow-ups, not this branch.
-**Authoritative spec:** `../pipelex-api/wip/pipelex-changes.md` item #12.
-**Where:** `pipelex/tools/storage/local_storage_provider.py` — `_store` and `_load_with_metadata`.
-
-Today, `ENOSPC` / `EACCES` / `EROFS` / `EIO` / `FileExistsError` / TOCTOU window after `file_path.exists()` all escape as raw `OSError`. Add a narrow `try/except OSError as exc: raise StorageLocalError(msg) from exc` around the filesystem calls — mirroring the wrapping already done by `S3StorageProvider` / `GcpStorageProvider`. Empirical reproductions are in the spec doc.
-
-**Decision:** Add a new `StorageLocalError(StorageError)` to `pipelex/tools/storage/exceptions.py`, paralleling `StorageS3Error` / `StorageGcpError` (with a `_declared_title = "Local storage error"`). Keeps per-backend differentiation consistent across the storage abstraction.
-
-Pair-test with item #5 (S3) — both deliver on the same storage-abstraction contract; same review can cover both.
-
----
-
-### 5. `S3StorageProvider` should catch the full `BotoCoreError` hierarchy
-
-- [x] **Status:** Done (2026-05-28). All three methods in `s3_storage_provider.py` now wrap the entire `BotoCoreError` hierarchy instead of only `NoCredentialsError` / `EndpointConnectionError`. In `_load_with_metadata` and `_store` the final `except (NoCredentialsError, EndpointConnectionError)` branch was broadened to `except BotoCoreError as exc: raise StorageS3Error(f"S3 backend error for key '{key}': {type(exc).__name__}") from exc`, sitting after the `ClientError` *sibling* branch (kept separate — `ClientError` is not a `BotoCoreError` subclass, verified empirically) and after the two service-specific `client.exceptions.NoSuchKey` / `NoSuchBucket` branches (unchanged). This closes the real-world leak: `ReadTimeoutError` / `ConnectTimeoutError` / `ConnectionClosedError` / `PartialCredentialsError` / `CredentialRetrievalError` / `ProxyConnectionError` (all `BotoCoreError` subclasses) previously escaped unwrapped; the most likely one, `ReadTimeoutError` on a slow/transient transfer, now surfaces as a typed `StorageS3Error`. `public_url`'s presign fallback widened from `except ClientError` → `except (BotoCoreError, ClientError)`, preserving the existing "if signing fails, serve the unsigned public URL" semantics for transport failures too. Per the decision, **no new sub-error class** — wrapping stays on the existing `StorageS3Error`, so no doc page work (generator confirms 0 drift: `Written: 0 · Unchanged: 245`). Covered by three new cases in `tests/unit/pipelex/tools/storage/test_s3_storage_provider.py` (`test_load_read_timeout_error_raises_s3_error`, `test_store_read_timeout_error_raises_s3_error`, `test_public_url_falls_back_to_public_url_on_botocore_error`); the three pre-existing `NoCredentialsError` / `EndpointConnectionError` tests were updated to assert the new message (`type(exc).__name__` in the text) and that `__cause__` is a `BotoCoreError`. The lower-priority `_get_session()`-outside-the-try side issue (a `BotoCoreError` from boto's own session-startup path could still escape) is left as-is — flag in the PR, don't gate on it. The API consumes this via the editable local dependency on this worktree; the API-side narrow storage-route catches are API-side follow-ups, not this branch.
-**Authoritative spec:** `../pipelex-api/wip/pipelex-changes.md` item #13.
-**Where:** `pipelex/tools/storage/s3_storage_provider.py` — `_load_with_metadata`, `_store`, and `public_url`.
-
-The provider catches only three `BotoCoreError` subclasses (`NoCredentialsError`, `EndpointConnectionError`) plus `ClientError` (which is a *sibling*, not a subclass, of `BotoCoreError`). Every other `BotoCoreError` subclass — `ReadTimeoutError`, `ConnectTimeoutError`, `ConnectionClosedError`, `PartialCredentialsError`, `CredentialRetrievalError`, `ProxyConnectionError`, … — escapes unwrapped. `ReadTimeoutError` is the most likely real-world leak (transient AWS networking).
-
-Fix: broaden each `except` block from `(NoCredentialsError, EndpointConnectionError)` to `BotoCoreError`, keeping the `ClientError` branch as a separate sibling `except`. The two service-specific branches at the top (`NoSuchKey`, `NoSuchBucket`) stay. `public_url`'s `try/except ClientError → return public URL` fallback should likely widen the same way.
-
-**Decision:** Keep wrapping as the existing `StorageS3Error(StorageError)` — no new sub-error class needed for the broadened catch. (Symmetric to item #4's `StorageLocalError` addition.)
-
-Lower-priority side issue noted in the spec doc: `_get_session()` runs outside every method's try block. Mention in the PR but don't gate on it.
-
----
-
-### 6. Webhook-delivery SSRF DNS recheck
-
-- [x] **Status:** Done (2026-05-28). Greenfield `pipelex/tools/network/` package now closes the DNS-rebinding gap at webhook-delivery time. Three modules: (a) `host_rules.py` — `is_disallowed_ip(host)` (**deny-by-default**: `not addr.is_global`, so private/loopback/link-local — incl. `169.254.169.254` — /CGNAT `100.64/10`/shared/documentation/benchmarking/unspecified are all refused in one predicate, plus explicit `is_multicast`/`is_reserved` because `ipaddress` marks the `224.0.0.0/4` and `64:ff9b::/96` NAT64 ranges as `is_global`) + `is_disallowed_host(host)` (empty / known internal hostname `localhost`·`metadata`·`metadata.google.internal` / literal disallowed IP) — this is the single source of truth, and it is **stricter than the API's current enumerate-the-bad-ranges `_is_disallowed_host`** (the deny-by-default form closes a CGNAT leak the API check has; the API inherits the tightening when it re-points at this helper); (b) `exceptions.py` — `SsrfBlockedError(SecurityError)` with `error_domain = ErrorDomain.INPUT` (destination is caller-supplied — fixable by providing a public URL) and `_authors_caller_facing_message = True` (message names only the caller's own hostname, never the resolved private IP, so STRICT disclosure cannot confirm internal topology); (c) `ssrf_guard.py` — `SsrfGuardedTransport(httpx.AsyncHTTPTransport)` whose `resolve_to_allowed_ip(host, port)` short-circuits literal-disallowed hosts, resolves via `loop.getaddrinfo` (→ `socket.getaddrinfo`, monkeypatch-able), refuses if **any** resolved IP is disallowed (a mixed public/private resolution is itself a rebinding signal), maps a genuine `socket.gaierror` → `httpcore.ConnectError` (so a real DNS failure keeps its normal `httpx.ConnectError` → `WebhookDeliveryError` path), and connects to the **first vetted IP** (a literal → `getaddrinfo` does no DNS, so no rebind can slip between the check and the socket). **Seam choice:** on pinned `httpx` 0.28.1 / `httpcore` 1.0.9 there is no public `network_backend` kwarg and no resolver/DNS hook (event hooks are request/response only), so the guard wraps the connection pool's `_network_backend` in place via a custom `httpcore.AsyncNetworkBackend` (`SsrfGuardedBackend`). This intercepts only the TCP connect — TLS SNI / cert verification and the `Host` header keep using the origin **hostname** automatically, because `httpcore._async.connection.AsyncHTTPConnection._connect` derives `server_hostname` from the origin, not from what `connect_tcp` dials. One private-attr touch (`self._pool._network_backend`) carries the repo's established `# noqa: SLF001 # pyright: ignore[reportPrivateUsage]`. `delivery_executor._notify_webhook` now builds `httpx.AsyncClient(transport=SsrfGuardedTransport())`; `SsrfBlockedError` — a `SecurityError` — is deliberately **not** re-wrapped as `WebhookDeliveryError`, so it propagates and the delivery aborts loudly (security signals must not be swallowed by the domain-level `except httpx.RequestError`). Covered by `tests/unit/pipelex/tools/network/test_host_rules.py` (`TestHostRules` — literal-IP + hostname classification), `test_ssrf_guard.py` (`TestSsrfGuard` — public/private/literal/mixed/`gaierror` resolution + a real `httpx.AsyncClient` driven through the guarded transport aborting before any socket), and an end-to-end `test_webhook_aborts_on_dns_rebind_to_private_ip` in `tests/unit/pipelex/pipe_run/test_delivery_executor.py` (`execute()` aborts with `SsrfBlockedError` via a `socket.getaddrinfo` monkeypatch returning `169.254.169.254` — no live network). Error doc page generated (`pipelex-dev generate-error-pages`): `docs/errors/ssrf-blocked-error.md` + a one-line index refresh under `SecurityError`. `make agent-check` clean (pyright 0, mypy 0, ruff/plxt clean); targeted unit + integration-pipes suites green. **Naming deviation:** named `SsrfBlockedError` (generic — the transport guards any caller-supplied outbound URL, not only webhooks) rather than the spec's tentative `WebhookDeliverySsrfBlocked`, per the "(or whatever the typed error ends up named)" latitude; it still lives in `pipelex/tools/network/exceptions.py` per the error-location convention (not co-located with the helper). **API-side migration note:** the API doc says `from pipelex.tools.network import is_disallowed_host`, but `__init__.py` is kept empty per the no-re-export-in-`__init__` rule — the real import path is `from pipelex.tools.network.host_rules import is_disallowed_host`. **Tradeoffs to flag in the PR:** (1) the guard connects to the first vetted IP, forgoing httpx/anyio happy-eyeballs multi-IP fallback for webhooks (acceptable — pinning to a vetted IP is the whole point); (2) an egress allowlist / proxy at the deploy layer stays out of scope. The API-side narrow catch + re-point of `_is_disallowed_host` is an API-side follow-up, not this branch.
-**Where:** `pipelex/pipe_run/delivery_executor.py` — wherever the webhook HTTP client (`httpx`) actually fires.
-
-The API's `api/schemas/models.py::_is_disallowed_host` only blocks literal private / loopback / metadata IPs **at request time**. A callback URL like `https://attacker.example/cb` passes API-side validation while its DNS record can resolve to `169.254.169.254` / `127.0.0.0/8` / `10.0.0.0/8` when the worker later fires the webhook. The fix belongs at delivery time:
-
-- A custom `httpx` transport / `httpcore` network backend whose connect step resolves the host, checks every resolved IP against the same private-host rule, and refuses to open the socket to a private / metadata destination. Note: on the pinned `httpx` 0.28.1, `AsyncHTTPTransport` exposes **no** resolver hook, and event hooks are `request` / `response` only — neither fires after DNS but before payload send — so a plain event hook cannot close the DNS-rebinding gap.
-- Or an explicit resolve-and-connect flow: resolve the hostname (`socket.getaddrinfo`), validate each candidate IP against the rule, then connect to a vetted IP while preserving the original `Host` header / SNI — so a rebind between validation and send is impossible.
-- Plus optionally an egress allowlist / proxy at the deploy layer (out of scope here — flag in the PR description so the deploy team sees it).
-
-The literal-host check on the API side stays as a cheap first line of defense.
-
-**Test fixture:** synthesize a webhook URL whose DNS resolves to a private IP (use a `socket.getaddrinfo`-style monkeypatch or a test resolver). Confirm the delivery aborts with a typed error (likely a new `WebhookDeliverySsrfBlocked` or similar) rather than completing the request.
-
-**Decision — rule placement.** Create a new `pipelex/tools/network/` package (greenfield — no `network` module exists today under `pipelex/tools/`) and put the rule in `pipelex.tools.network.is_disallowed_host(...)`. The API-side `_is_disallowed_host` in `pipelex-api/api/schemas/models.py` gets re-pointed at this helper, so the CIDR set lives in one place. Follow the error-location convention: `pipelex/tools/network/exceptions.py` for `WebhookDeliverySsrfBlocked` (or whatever the typed error ends up named) — do not co-locate the error with the helper.
-
----
-
-### 7. Structured `event=webhook_delivery` / `event=webhook_failure` logging — **DEFERRED to structured-logging refactor**
-
-- [x] **Status:** Closed-by-deferral on this branch (2026-05-28). Re-scoped onto the `refactor/structured-logging` branch.
-**Where (for the deferral):** `wip/structured-logging/kickoff.md` "What good looks like" — event-name emission now in scope.
-
-The lines this item would have touched (`pipelex/pipe_run/delivery_executor.py` around 239 / 243 / 280 / 282 / 285) are exactly the lines the structured-logging refactor lists as deletion targets (`request_id_suffix` pattern, kwarg threading from commits `ceb018b5` / `07f9cce9`). Doing a narrow event-name pass on this branch would touch those lines twice.
-
-**Follow-up actions when the structured-logging branch starts:**
-
-- Emit `event=webhook_delivery` / `event=webhook_failure` (and `event=storage_delivery` / `event=storage_failure` for symmetry) as structured fields once the new `log.info(msg, **fields)` surface lands. Document this in the kickoff doc's destination shape.
-- Re-target the API-side TODO in `../pipelex-api/TODOS.md` "Deferred / next-track work" → "Upstream-pipelex follow-ups" from this branch onto the structured-logging branch.
-
-The API-side T6 test (`pipelex-api/tests/unit/test_webhook_recovery.py`) pins error-rendering consistency, not event names, so the API is not blocked on event-name emission.
-
----
-
-## Out of scope (for this branch — recorded so they don't drift back in)
-
-- **Structured-logging refactor.** Its own branch and PR. See `wip/structured-logging/kickoff.md`.
-- **Webhook signing.** Cross-repo, lockstep. See `wip/security/webhook-signing.md`.
-- **Item #15 — kajson crafted-marker exceptions.** Target repo is `kajson`, **not** `pipelex`. Belongs on a separate kajson PR. Spec lives at `../pipelex-api/wip/pipelex-changes.md` item #15; the API has a workaround in place (`_decode_body`'s widened catch tuple). Re-target there if Louis wants this on the same release train.
-- **Console targets / agent CLI stdout discipline.** Independent track — `wip/console-targets-and-agent-cli-stdout.md`. Already landed in part on `fix/Log-target`.
-- **Kajson untrusted-deserialization design pass.** Separate track at `../pipelex-api/wip/security/kajson-untrusted-deserialization.md` (workspace-level concern, needs `pipelex-app` + `pipelex-api-deploy` in the room).
-- **API-side `pipe_code` / `pipeline_run_id` log enrichment.** Done in `pipelex-api`, not here.
-- **API-side `RecursionError` in `_decode_body`.** Done in `pipelex-api`, not here.
-- **API-side JSON log sink.** Done in `pipelex-api`, not here.
-
----
-
-## Verification (when items land)
-
-- `make c` + `make t` clean on every commit.
-- For items #1-#5: add unit tests that pin the new behavior; the API-side test suite (`pipelex-api` with this branch pinned via the `[tool.uv.sources]` git rev) should also still pass — bump the pin and run `make c && make tp` over there as part of the PR.
-- For item #6 (SSRF): integration-style test using a mock resolver. No live network.
-- For item #7: depends on the sequencing decision.
-
----
-
-## Pin coordination with `pipelex-api`
-
-`pipelex-api/pyproject.toml` has a temporary `[tool.uv.sources]` git-rev pin pointing at this repo. When this branch reaches a shippable point:
-
-1. Bump that `rev` to this branch's HEAD; run `make c && make tp` in `pipelex-api`.
-2. Update the API-side `TODOS.md` "Deferred / next-track work" → "Upstream-pipelex follow-ups" — strike through the items that landed; keep the rest.
-3. Update `../pipelex-api/wip/pipelex-changes.md` Stage 7 tracking table — flip the items' status.
-
-The eventual end-state — flipping the API back to a PyPI floor (`pipelex>=<next-release>`) — is Louis-gated cross-repo release coordination; not part of this branch.
-
----
-
-## Decisions taken (2026-05-28)
-
-The open questions from the original cold-start session have been resolved. Recording here so they don't get re-litigated:
-
-1. **Item #7 sequencing — DEFERRED to structured-logging refactor.** See item #7 above. The lines it would have touched are explicit deletion targets in `wip/structured-logging/kickoff.md`. Doing the narrow event-name pass now means touching them twice.
-2. **Item #6 SSRF rule placement — SHARED HELPER.** Create `pipelex/tools/network/` (greenfield) with `is_disallowed_host(...)`. The pipelex-api side re-points its `_is_disallowed_host` at this helper. Single source of truth for the disallowed CIDR set. See item #6 above for the error-location convention note.
-3. **Items #4 / #5 error class shape — NEW `StorageLocalError(StorageError)`.** Mirrors the established per-backend pattern (`StorageS3Error` / `StorageGcpError` with `_declared_title`). Item #5 keeps wrapping as the existing `StorageS3Error`.
-4. **`dev` merge — NOT NEEDED.** `git log feature/API-readiness-2..origin/dev --oneline` returns 0 commits. `dev` is not ahead.
diff --git a/wip/error-handling/archive-todos.md b/wip/error-handling/archive-todos.md
deleted file mode 100644
index fe6e71923..000000000
--- a/wip/error-handling/archive-todos.md
+++ /dev/null
@@ -1,605 +0,0 @@
-# TODOS — pipelex changes for the pipelex-api error-handling refactor
-
-> **ARCHIVED — superseded.** This was the execution ledger for the error-handling refactor; every stage is landed. It is kept for history and moved here from the repo root. Note that "Item A" describes a deviation where `type_uri()` read its base URI through an `ErrorManager` singleton holding an `ErrorsConfig`; that machinery was later removed entirely — `type_uri()` is now a pure function reading the `URLs.error_docs_base` constant (`pipelex/urls.py`). The relative links below were written relative to the repo root, not this `wip/error-handling/` location.
-
-This worktree (`feature/API-readiness`) carries the **pipelex-side** companion work for the `pipelex-api` error-handling design. The original per-item spec is in [`wip/error-handling/changes-for-api-early-draft.md`](wip/error-handling/changes-for-api-early-draft.md); the deviations we are taking from that spec — and *why* — are documented in [`wip/error-handling/api-companion-revisions.md`](wip/error-handling/api-companion-revisions.md). The cross-repo consumer (the API) lives in the side-by-side worktree [`../pipelex-api/wip/error-handling/`](../../pipelex-api/wip/error-handling/).
-
-This file is the **execution plan** — what to land, in what order, with hard-stop checkpoints. It consolidates the error-handling items from the original spec. The original spec's webhook-signing item (item 9) is split out as a separate security track — see [`wip/security/webhook-signing.md`](wip/security/webhook-signing.md). It is security work, not error-handling work; the cross-repo coordination it needs is independent of this plan's PR series. See [`api-companion-revisions.md`](wip/error-handling/api-companion-revisions.md) for the full rationale on the error-handling consolidation.
-
----
-
-## Decisions locked in
-
-The plan reflects these decisions; no further re-litigation in the items below.
-
-- **`ErrorReport` becomes a `BaseModel`** (`model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)`). We drop the `@pydantic.dataclasses.dataclass` form. The existing Temporal data converter already handles `BaseModel` round-trips — no kajson surgery needed. (Was Item D-2's open question.)
-- **`ErrorReport.title` and `type_uri` are required `str`**, not `str | None`. Every fresh report carries them. A payload missing them fails `from_dict`, which `recover_error_report` synthesizes as `UnrecoverableWorkflowFailureError` (Item D-1) — the correct behavior under "no backward-compat shims."
-- **`title` and `type_uri` are wrapper-wins under cause-chain enrichment.** When `PipeRouterError` wraps `CogtError`, the resulting report carries `error_type="PipeRouterError"`, `title=PipeRouterError.title()`, `type_uri=PipeRouterError.type_uri()` — the identity triplet (`error_type` / `title` / `type_uri`) stays consistent. Classification fields (`error_category`, `provider`, `retryable`, `user_action`, `model`, `provider_metadata`) continue to backfill from the cause as today. The deeper-cause *identity* (its own `error_type` / `title` / `message`) is **not** preserved on the current flat `ErrorReport`; consumers who need Sentry-style cause-trail visibility get it via the deferred `causes` follow-up (see "Deferred follow-ups" below).
-- **`request_id` propagates via `JobMetadata` only.** No ContextVar layer for propagation — Temporal serializes the activity arg; only fields on `JobMetadata` cross the worker boundary. Activity-side log binding reads `arg.<path>.job_metadata.request_id` directly from the arg.
-- **`UnrecoverableWorkflowFailureError` lives in `pipelex/temporal/exceptions.py`**, not `base_exceptions.py`. It's a Temporal-flow-specific synthesis concept.
-- **`errors_config` lives under `Pipelex` config**: `get_config().pipelex.errors_config.base_uri`. Consistent with `pipe_run_config`, `pipeline_execution_config`, etc.
-- **`error_category` is kept in STRICT mode** alongside the other stable identifiers. Revisit only if a deployment surfaces it as a data-leak.
-- **Stage 3 acceptance covers the full `WfPipeRun` chain**, not just `WfPipeRouter`. The existing test bypasses `WfPipeRun`; the new test exercises the outer wrap so the inner child's report survives.
-- **`DisclosureMode.STRICT` is a classification-projection for server-side errors, NOT a path-leak shield.** `INPUT`-domain reports pass through unchanged in STRICT mode (caller-influenced; reflecting back is part of the contract). `CONFIG`/`RUNTIME` reports get redacted. This asymmetry is documented on the `DisclosureMode` docstring itself (Item C) — the entry point a developer reads when wondering "what does STRICT mean?" — so the contract can't be silently misread. If an INPUT message could surface a server-resolved path or secret, the fix is to repair the upstream message, not to expand STRICT mode.
-- **`WorkflowExecutionError` is a wrapper-loses exception to the wrapper-wins rule.** At `pipelex/temporal/exceptions.py:35-43`, `WorkflowExecutionError.to_error_report()` returns `self.error_report` verbatim, bypassing `_enrich_error_report_from_cause()`. The recovered inner classification (`error_type` / `title` / `type_uri` / `error_category` / `provider`...) is preserved as-is because the Temporal serialization boundary would otherwise drop it — the *whole point* of recovering the report is to restore the worker-side identity, not to overwrite it with the cross-boundary wrapper's identity. This is the **only** such carve-out in the hierarchy; do NOT "fix" it by adding `_enrich_error_report_from_cause(report)` to the override during Item A implementation. The wrapper-wins rule applies to in-process wrapping (`PipeRouterError(CogtError)`); the wrapper-loses behavior applies to cross-boundary recovery (`WorkflowExecutionError(recovered_report)`).
-
----
-
-## Approach
-
-- **Stages map to API-plan dependencies, not effort.** Land in stage order so the API team can start consuming primitives as early as possible.
-- **TDD red-green per item.** Add the failing test against the desired surface first, then implement until it passes. Pre-existing tests under `tests/unit/pipelex/test_base_exceptions.py`, `tests/unit/pipelex/test_error_report_from_dict.py`, `tests/unit/pipelex/pipe_run/test_delivery_executor.py`, `tests/unit/pipelex/temporal/test_recover_error_report.py`, and `tests/integration/pipelex/temporal/test_workflow_error_report_full_chain.py` are the natural homes for the new cases.
-- **After every item:** run `make agent-check` and `make agent-test`. Both must pass before checking off the item.
-- **No backward-compatibility shims, no curate-a-subset hedges, no "consumer fallback for missing data" patterns.** Pipelex owns the defaults so every consumer gets the same behavior automatically.
-
----
-
-## Stage 1 — Foundations *(unblocks `pipelex-api` Phase 0)*
-
-### [x] Item A — `PipelexError.title()` + `type_uri()` with auto-derive defaults *(merges spec items 1+2)*
-
-- **Files:**
- - `pipelex/base_exceptions.py` — new classmethods + new `ErrorReport` fields.
- - `pipelex/tools/misc/string_utils.py` — add `pascal_case_to_kebab(name: str) -> str` next to the existing `pascal_case_to_*` helpers (it's the same module's concern; no new helper module).
- - `pipelex/system/configuration/configs.py` — new `ErrorsConfig(ConfigModel)` with `base_uri: str`, mounted under `Pipelex` as `errors_config`.
- - `pipelex/pipelex.toml` — `[pipelex.errors_config]` section with `base_uri = "https://pipelex.dev/errors"`.
-- **Surface:**
- ```python
- class PipelexError(Exception):
- _declared_title: ClassVar[str | None] = None
- _declared_type_uri: ClassVar[str | None] = None
-
- @classmethod
- def title(cls) -> str:
- return cls._declared_title or _humanize(cls.__name__)
-
- @classmethod
- def type_uri(cls) -> str:
- if cls._declared_type_uri is not None:
- return cls._declared_type_uri
- base = get_config().pipelex.errors_config.base_uri
- return f"{base.rstrip('/')}/{pascal_case_to_kebab(cls.__name__)}"
- ```
-
- `ErrorReport` (now a `BaseModel` — see Item D-2 in Decisions locked in) gains:
-
- ```python
- title: str
- type_uri: str
- ```
-
- Both **required**. `PipelexError.to_error_report()` populates them from `type(self).title()` / `type(self).type_uri()`. They round-trip through `model_dump` / `model_validate`.
-
-- **`_humanize` rule.** Strip a trailing `"Error"` from the class name (if present), then `pascal_case_to_sentence(...)` (existing helper — already handles acronyms like `JSON`, `URL`, `API`). Single-token classes (`CogtError`) become `"Cogt"` — these need a curated `_declared_title` (see next bullet).
-- **`type_uri()` and config readiness.** No fallback constant. `pipelex.errors_config.base_uri` is a required config field with the default value (`"https://pipelex.dev/errors"`) shipped in `pipelex/pipelex.toml`. If config is not loaded when `type_uri()` is called, that is a programmer error and should raise loudly — do not paper over it with a module-level default. Boot-sequence errors that pre-date config load are already extremely rare and surface via other channels.
-- **Curated overrides shipped with this item** (concrete list, not "to be discovered later"):
- - `PipelexError._declared_title = "Pipelex error"`
- - `PipelexUnexpectedError._declared_title = "Unexpected internal error"`
- - `SecurityError._declared_title = "Security policy violation"`
- - `CogtError._declared_title = "AI inference failed"`
- - `EnvVarNotFoundError._declared_title = "Environment variable not set"`
- - **Wide sweep at implementation time.** With ~267 `PipelexError` subclasses in the codebase, do a focused pass through every leaf class whose auto-derived title reads as a noun, an awkward fragment, or grammatically wrong. Curate them in this same PR. Do NOT defer to a follow-up.
-- **Migration sweep — raw `ErrorReport(...)` constructions** (must land in the same PR since both fields become required):
- - **Production sites (3):**
- - `pipelex/base_exceptions.py:135` — `PipelexError.to_error_report()`: populate `title=type(self).title()`, `type_uri=type(self).type_uri()`.
- - `pipelex/base_exceptions.py:166` — `_enrich_error_report_from_cause()` rebuild path: propagate `title=report.title`, `type_uri=report.type_uri` (wrapper-wins, per "Decisions locked in").
- - `pipelex/cogt/exceptions.py:88` — `CogtError.to_error_report()` override: same as the base class.
- - **Test fixtures (~10):** mixed strategy.
- - Where the test is *about* serialization / round-trip / disclosure / RFC 7807 (`test_error_report_from_dict.py`, `test_base_exceptions.py`, the new Item C tests): construct with **real** `title="..."` / `type_uri="https://pipelex.dev/errors/..."` values. The test is honest about the contract.
- - Where the test is about classification / domain / HTTP status and doesn't exercise `title`/`type_uri` (`test_error_http_status.py`, `test_error_domain.py`, the various `test_workflow_*_error_*.py` fixtures): introduce a small helper `make_error_report(...)` in a tests-only conftest with `title="Test error"` / `type_uri="https://test.pipelex.dev/errors/test-error"` defaults, so each fixture line stays a single readable call.
- - **Special case — `tests/unit/pipelex/test_base_exceptions.py::test_error_report_constructable_without_cogt_exceptions_loaded`** (the cold-import subprocess test). This test will break twice under Item A: (a) `ErrorReport(error_type='X', message='m')` is now a `ValidationError` (missing required fields), and (b) `PipelexConfigError('boom').to_error_report()` calls `type_uri()` → `get_config()` → `RuntimeError` because the subprocess never bootstraps Pipelex. Per the "Decisions locked in" no-fallback-constant rule, this is by design — config-less `type_uri()` calls must raise loudly. The fix preserves the test's original intent (verify `ErrorReport` is fully defined without `cogt.exceptions` being loaded) by dropping the `to_error_report()` line and constructing `ErrorReport` directly with explicit `title="X"` / `type_uri="https://pipelex.dev/errors/x"`. Add a separate non-subprocess test elsewhere (e.g. in `test_base_exceptions.py` in a new `TestPipelexErrorTypeUri` class) that asserts `PipelexConfigError.to_error_report()` populates `title` / `type_uri` correctly — with config loaded by the normal pytest fixture chain.
-- **Tests** (`tests/unit/pipelex/test_base_exceptions.py` unless noted):
- - Auto-derive: `class FooBarError(PipelexError): pass` → `FooBarError.title() == "Foo bar"`, `type_uri() == "https://pipelex.dev/errors/foo-bar"`.
- - Override wins: `class X(PipelexError): _declared_title = "Custom"` → `X.title() == "Custom"`.
- - Round-trip: `ErrorReport.model_validate(report.model_dump()).title == report.title` and same for `type_uri`.
- - **Uniqueness guard:** a test that walks `PipelexError.__subclasses__()` recursively (forcing imports of the relevant `*/exceptions.py` modules first) and asserts every class's `type_uri()` is unique. Catches future class-name collisions at CI time, not docs-build time.
- - `pascal_case_to_kebab` (in `tests/unit/pipelex/tools/misc/test_string_utils.py`):
- - Basic: `"FooBarBaz"` → `"foo-bar-baz"`.
- - Trailing acronym: `"APIError"` → `"api-error"`.
- - Embedded acronym: `"HTTPError"` → `"http-error"`.
- - No-acronym multi-word: `"EnvVarNotFound"` → `"env-var-not-found"`.
- - Numeric + acronym: `"OAuth2"` → `"o-auth2"` (consistent with `pascal_case_to_sentence("OAuth2") == "o auth2"` — pin this in the test).
- - Numeric mid-string: `"V2APIError"` → `"v2-api-error"`.
- - **`from_dict` missing-required-fields:** `ErrorReport.from_dict({"error_type": "X", "message": "m"})` raises `pydantic.ValidationError` (no `title`/`type_uri`). This is the path that `recover_error_report` (Item D-1) converts into `UnrecoverableWorkflowFailureError` — pin it here as the unit-level contract.
-- **Acceptance:** consumers never humanize or kebab-case a class name themselves. The API consumes `report.title` / `report.type_uri` directly.
-
-### [x] Item B — First-class `request_id` on `JobMetadata` *(spec item 3)*
-
-**Propagation, not a ContextVar layer.** Temporal serializes the activity arg, so the only way `request_id` reaches the worker is by riding on a field that's part of the workflow input. That field is `JobMetadata.request_id`. There is no cross-boundary ContextVar.
-
-- **Files:**
- - `pipelex/pipeline/job_metadata.py` — add `request_id: str | None = None` next to `pipeline_run_id` / `user_id` / `session_id`.
- - `pipelex/pipeline/pipeline_run_setup.py` — `pipeline_run_setup(...)` accepts a `request_id: str | None = None` kwarg and threads it into the `JobMetadata` it constructs.
- - `pipelex/temporal/log_temporal.py` — extend `WorkflowLog` / `ActivityLog` with an optional `request_id` kwarg on each method: `activity_log.info("...", request_id=arg.pipe_job.job_metadata.request_id)`. Implementation: pass through to `temporalio`'s logger via `extra={"request_id": ...}`. Activities that want request_id in their logs pass it explicitly. Verbose by one parameter; explicit over clever; no global mutable state.
-- **Naming-collision note.** `ProviderErrorMetadata.request_id` already exists at `pipelex/cogt/inference/error_classification.py:80` and means "the provider's request ID" (OpenAI `x-request-id`, Anthropic equivalent). `JobMetadata.request_id` means "the API's inbound `X-Request-ID`". Both can appear in a single ErrorReport. Document this distinction in `JobMetadata.request_id`'s docstring; no field rename.
-- **Tests:**
- - Unit: `JobMetadata(request_id="r-123")` round-trips through `model_dump_json` / `model_validate_json`.
- - Unit: `pipeline_run_setup(..., request_id="r-123")` produces a `PipeJob` whose `job_metadata.request_id == "r-123"`.
- - Integration (`tests/integration/pipelex/temporal/test_workflow_error_report_full_chain.py`): dispatch with a known `request_id`. Assert it appears in the recovered `WorkflowExecutionError.to_error_report()` chain via JobMetadata propagation (read the value off the recovered context). On a `caplog`-style assertion, verify an explicit `activity_log.info(..., request_id=...)` call inside a hook emits a log record with `request_id` in `extra`.
-- **Acceptance:** a `request_id` passed to `pipeline_run_setup(...)` arrives on the worker as `arg.pipe_job.job_metadata.request_id` with no consumer-side workaround. The current `webhook.payload["request_id"]` piggyback in the API becomes obsolete.
-
-**Checkpoint 1 — End of Stage 1** ⬇ See [Checkpoint 1 brief](#checkpoint-1--end-of-stage-1) below.
-
----
-
-## Stage 2 — Rendering primitives + total recovery *(unblocks `pipelex-api` Phase 1)*
-
-### [x] Item C — Parameterized `to_dict(disclosure_mode=)` + `to_problem_document(...)` *(merges spec items 4+6)*
-
-- **File:** `pipelex/base_exceptions.py`
-- **Surface:**
- ```python
- class DisclosureMode(StrEnum):
- """How much detail to include when serializing an ``ErrorReport`` for external surfaces.
-
- - ``VERBOSE``: all classification fields plus the original ``message``. Use for
- internal-trust boundaries (webhook payloads, internal RPCs) where the receiver
- decides what to expose further downstream.
-
- - ``STRICT``: stable identifiers only (``error_type``, ``error_domain``,
- ``error_category``, ``retryable``, ``title``, ``type_uri``). For
- ``CONFIG`` / ``RUNTIME`` reports, ``message`` is replaced with a generic
- placeholder and ``provider`` / ``model`` / ``provider_metadata`` /
- ``user_action`` are dropped.
-
- **``INPUT``-domain reports are returned unchanged in STRICT mode.** Their
- ``message`` is caller-influenced and reflecting it back is part of the
- contract. STRICT is a *classification-projection for server-side errors*,
- **not a path-leak shield**. If an ``INPUT`` message could surface a
- server-resolved path or secret, fix the upstream message — don't expand
- STRICT mode's scope.
- """
- VERBOSE = "verbose"
- STRICT = "strict"
-
- class ErrorReport(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)
- ...
- def to_dict(self, disclosure_mode: DisclosureMode = DisclosureMode.VERBOSE) -> dict[str, Any]: ...
- def to_problem_document(
- self,
- *,
- instance: str | None = None,
- request_id: str | None = None,
- disclosure_mode: DisclosureMode = DisclosureMode.VERBOSE,
- ) -> dict[str, Any]: ...
-
- @classmethod
- def from_dict(cls, data: dict[str, Any]) -> "ErrorReport": ...
- ```
-- **`from_dict` / `to_dict` semantics.** `to_dict(VERBOSE)` is the inverse of `from_dict`; the round-trip is preserved. `to_dict(STRICT)` is a **lossy** projection — `from_dict(to_dict(report, STRICT))` does not reconstruct the original. Document this on the docstring (with a brief "See `DisclosureMode` for the redaction rule" cross-reference rather than duplicating the rule). Webhook payloads use VERBOSE so receivers can rehydrate (`ErrorReport.from_dict(payload["error"])`); HTTP responses use whatever disclosure the deployment configured.
-- **Strict redaction rule:**
- - `INPUT`-domain reports → returned unchanged (the caller's own input; reflecting it back is fine).
- - `CONFIG` / `RUNTIME` reports → `message` replaced with `"An internal error occurred."`; `provider`, `model`, `provider_metadata`, `user_action` dropped.
- - **Kept in all modes** (stable identifiers, RFC 7807-compatible): `error_type`, `error_domain`, `error_category`, `retryable`, `title`, `type_uri`.
-- **`to_problem_document`** builds the RFC 7807 envelope and maps pipelex fields into the standard slots. Honors `disclosure_mode` by calling `to_dict(disclosure_mode)` internally. `request_id` lands as the `request_id` extension member. Returns a plain dict — pipelex stays HTTP-agnostic, no FastAPI/Starlette import.
-- **RFC 7807 mapping table.** Standard slots get the *value* from the report; pipelex-native names are **dropped** from extensions to avoid a `title` collision and a `title`/`type` semantic split:
-
- | RFC 7807 standard slot | Source on `ErrorReport` | Note |
- |---|---|---|
- | `type` | `report.type_uri` | `type_uri` is removed from extension members |
- | `title` | `report.title` | `title` is removed from extension members (would otherwise duplicate the standard key) |
- | `status` | `report.http_status` | already a property |
- | `detail` | `report.message` (subject to disclosure-mode redaction) | the human-readable per-occurrence text |
- | `instance` | function argument | per-occurrence URN provided by caller |
-
- Extension members carry only the pipelex-native classification fields the standard does not cover: `error_type`, `error_domain`, `error_category`, `retryable`, `user_action`, `model`, `provider`, `provider_metadata`. `request_id` rides as an extension when the caller supplies one.
-- **Tests:**
- - Parametrize across the three domains × two disclosure modes (six base cases). Assert INPUT passthrough; CONFIG/RUNTIME redaction-with-stable-identifiers-kept.
- - Parametrize `retryable: True | False | None` × `disclosure_mode: VERBOSE | STRICT`. Assert `retryable` survives both modes for all three values.
- - **INPUT-strict pin test:** an INPUT report whose `message` contains a path like `/Users/alice/secret.mthds` is returned **unchanged** in STRICT mode. Pin the documented contract.
- - RFC 7807 shape: `to_problem_document(instance="urn:p:123", request_id="r-1")` returns a dict with `type`, `title`, `status`, `detail`, `instance="urn:p:123"`, and a `request_id="r-1"` extension member.
- - **RFC 7807 mapping contract** (single test, two assertions):
- - Exactly one `title` key in the returned dict (no extension named `title`).
- - `result["type"] == report.type_uri` and `result["title"] == report.title`.
- - The extension members do not contain `type_uri` or `title` (they are mapped, not duplicated).
- - Verbose round-trip: `from_dict(report.to_dict(VERBOSE))` equals `report`.
- - Strict non-round-trip: `from_dict(report.to_dict(STRICT))` for a RUNTIME report has `message == "An internal error occurred."` and `provider is None`.
- - **Receiver-rehydration test:** simulate the API-side consumer. Take a populated `ErrorReport`, render `payload = {"status": "failed", "error": report.to_dict(VERBOSE)}`, then `ErrorReport.from_dict(payload["error"])` and assert it equals the original. Pins the contract pipelex-api will consume on the webhook.
-- **Acceptance:** the API consumes both methods directly. The redaction rule and the envelope shape live exactly once in pipelex; no consumer duplicates them.
-
-### [x] Item D-1 — Make `recover_error_report` total
-
-- **Files:**
- - `pipelex/temporal/exceptions.py` — new subclass `UnrecoverableWorkflowFailureError(TemporalFlowError)` with `error_domain = ErrorDomain.RUNTIME` and `_declared_title = "Workflow failed without recoverable error details"`. Lives next to `TemporalFlowError`, `WorkflowExecutionError`, etc. (Reason: Temporal-flow-specific synthesis concept; locking it into the Temporal exceptions module keeps the base hierarchy clean.)
- - `pipelex/temporal/tprl/temporal_error.py` — `recover_error_report` signature becomes `def recover_error_report(exc: BaseException) -> ErrorReport`. When no embedded report is found or `from_dict` fails on version skew, synthesizes `UnrecoverableWorkflowFailureError(message_from_exc(exc)).to_error_report()`. `message_from_exc` extracts the most informative message available: the outer Temporal failure's message if non-empty, else `repr(exc)`.
- - `pipelex/temporal/tprl/workflow_caller.py` — call sites at `:128`, `:240`, `:292`: drop the `if error_report is not None` branches; the return is always usable.
-- **Tests** (`tests/unit/pipelex/temporal/test_recover_error_report.py`):
- - Existing case `test_g3_malformed_details_recovers_nothing` becomes `test_g3_malformed_details_synthesizes_unrecoverable` and asserts the synthesized report has `error_type == "UnrecoverableWorkflowFailureError"`, `error_domain == "runtime"`, `retryable is None`, message contains the original exception message.
- - Existing case `test_g4_application_error_without_report_details_recovers_nothing` becomes `test_g4_application_error_without_report_details_synthesizes_unrecoverable` with the same assertions.
- - Existing case `test_no_application_error_in_chain_recovers_nothing` becomes `test_no_application_error_in_chain_synthesizes_unrecoverable`.
- - Existing positive cases continue to assert recovery of the packed report unchanged.
- - **New end-to-end pin (in `tests/unit/pipelex/temporal/test_workflow_caller_error_recovery.py`)** — a `WorkflowFailureError` that is NOT carrying an embedded `ErrorReport` (i.e., a non-Pipelex worker failure or a Temporal infra error) reaches `execute_workflow` and surfaces as a `WorkflowExecutionError` whose `.message` is the synthesized message (containing the underlying exception text), NOT the legacy `"Failed to execute workflow {workflow_class.__name__}"` framing. This pins the user-visible behavior change at the call site after the totality refactor: with the `if error_report is not None` branch dropped, the unrecoverable path no longer produces the Pipelex-framed fallback string. The test should also assert `WorkflowExecutionError.error_report is not None` and `error_report.error_type == "UnrecoverableWorkflowFailureError"`.
-- **Note on no-longer-reached paths in existing tests.** After this change, `WorkflowExecutionError(msg)` without `error_report=...` is still reachable via `start_workflow` (which only catches `WorkflowAlreadyStartedError` / `RPCError`, not `WorkflowFailureError`) and the `WorkflowAlreadyStartedError` / `RPCError` branches of `execute_workflow`. The existing unit tests `test_g7_to_error_report_falls_through_to_cause_enrichment_when_no_report` and `test_to_error_report_is_generic_without_report_or_pipelex_cause` continue to exercise that defensive API path — do NOT remove them as "dead code" during D-1 implementation; they still cover the non-`WorkflowFailureError` branches.
-- **Acceptance:** callers never see `None` from this function. The "hand-author a fallback report" pattern the original spec proposed (see [`api-companion-revisions.md`](wip/error-handling/api-companion-revisions.md) §D) is eliminated — there is exactly one place that constructs the unrecoverable report. The user-visible `WorkflowExecutionError.message` on the unrecoverable path changes from the Pipelex-framed `"Failed to execute workflow X"` to the synthesized `message_from_exc(exc)` — this is intentional (more diagnostic) and pinned by the new end-to-end test above.
-
-**Checkpoint 2 — End of Stage 2** ⬇ See [Checkpoint 2 brief](#checkpoint-2--end-of-stage-2) below.
-
----
-
-## Stage 3 — Async error pipe *(unblocks `pipelex-api` Phase 4 — most important item)*
-
-### [x] Item D-2 — Thread `ErrorReport` to the webhook
-
-- **Prereq: convert `ErrorReport` from `@pydantic.dataclasses.dataclass` to `BaseModel`.**
-
- ```python
- class ErrorReport(BaseModel):
- model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)
-
- error_type: str
- message: str
- title: str # required after Item A
- type_uri: str # required after Item A
- error_category: str | None = None
- error_domain: str | None = None
- retryable: bool | None = None
- user_action: UserAction | None = None
- model: str | None = None
- provider: str | None = None
- provider_metadata: ProviderErrorMetadata | None = None
- ```
-
- `to_dict` becomes `self.model_dump(exclude_none=True)` (plus disclosure-mode redaction from Item C). `from_dict` becomes `cls.model_validate(data)`. The existing `BaseModelPayloadConverter` (`pipelex/temporal/temporal_data_converter.py:54`) already handles `BaseModel` and `BaseModel | None` — no converter or kajson surgery.
-
- **Why this over extending the data converter for Pydantic dataclasses:** one type to convert; smaller diff; the BaseModel form is what kajson and the data converter were built for. The "generic Pydantic dataclass support" framing was speculative future-proofing for a use case that does not yet exist.
-
-- **Files:**
- - `pipelex/base_exceptions.py` — the `BaseModel` conversion above.
- - `pipelex/pipeline/exceptions.py` — **breaks under the BaseModel conversion.** Currently uses `from dataclasses import replace` and `replace(report, error_domain=..., user_action=...)` at `pipeline/exceptions.py:1` and `:44`. After the conversion, this raises at runtime (`replace()` is stdlib-dataclass-only; BaseModel has `model_copy(update={...})`). Migration: drop the `from dataclasses import replace` import and rewrite the call as `report.model_copy(update={"error_domain": ..., "user_action": ...})`. **This must land in the same PR as the BaseModel conversion** — every `PipelineExecutionError.to_error_report()` call breaks without it. Add a regression test (`tests/unit/pipelex/pipeline/test_exceptions.py` or extend `test_base_exceptions.py`) that constructs a `PipelineExecutionError` with no enriching cause, calls `to_error_report()`, and asserts the resulting `error_domain == ErrorDomain.RUNTIME` and `user_action.kind == UserActionKind.UNKNOWN`. Without this test, the converter swap would break the floor behavior silently.
- - `pipelex/pipe_run/delivery_executor.py` — `execute(...)` and `_notify_webhook(...)` accept `error_report: ErrorReport | None = None`. When `status == FAILED` and `error_report is not None`, the webhook payload includes `error = error_report.to_dict(DisclosureMode.VERBOSE)`. The API can choose strict mode at its own HTTP surface.
- - `pipelex/temporal/tprl_pipe/act_deliver.py` — `DeliveryActivityArg` gains `error_report: ErrorReport | None = None`. No `_dict` shim — the data converter handles `BaseModel | None` directly.
- - `pipelex/temporal/tprl_pipe/wf_pipe_run.py` — on the `ChildWorkflowError` catch, call `error_report = recover_error_report(exc.cause)` (total — always a value, see Item D-1). Pass it into `DeliveryActivityArg`.
-- **Tests:**
- - `tests/integration/pipelex/temporal/test_payload_codec_roundtrip.py` — add a case that round-trips an `ErrorReport` carrying populated `user_action` and `provider_metadata` (nested BaseModels) through a workflow→activity hop. **This must land before** the activity arg is changed.
- - `tests/unit/pipelex/pipe_run/test_delivery_executor.py` — webhook payload includes `error = report.to_dict(VERBOSE)` on `FAILED` with non-`None` report; absent on `COMPLETED` or `None` report. Round-trips a realistic `ErrorReport` with `provider_metadata` populated.
- - `tests/integration/pipelex/temporal/test_workflow_error_report_full_chain.py` — **two extensions** that lock in the fix for the outer-wrap concern:
- 1. Existing `WfPipeRouter` case continues to assert recovered classification on the submitter side.
- 2. **New `WfPipeRun` end-to-end case** that dispatches `WfPipeRun` (not `WfPipeRouter`) with a `delivery_assignment` whose webhook points at an in-process httpx mock transport (`httpx.MockTransport`). Asserts:
- - The webhook receiver was called once with `status == "failed"`.
- - The webhook payload includes `error = <dict>` with the full classification (`error_type`, `error_category`, `retryable`, `user_action`, `model`, `provider`, `title`, `type_uri`).
- - The submitter-side `WorkflowExecutionError.to_error_report()` carries the same classification (i.e. the outer Temporal wrap does NOT drop the inner report).
- 3. A second new `WfPipeRun` case **without** a `delivery_assignment` — verifies the submitter-side path still surfaces classification even when delivery isn't configured.
-- **Acceptance:** a Temporal-side pipe failure reaches the webhook with the same classification a sync caller would see locally. No silent loss of fields across activity → workflow (child) → workflow (parent) → delivery → submitter.
-
-**Checkpoint 3 — End of Stage 3 (largest unlock; recommended stopping point if context is tight)** ⬇ See [Checkpoint 3 brief](#checkpoint-3--end-of-stage-3) below.
-
----
-
-## Stage 4 — DX polish *(pairs with `pipelex-api` Phase 5)*
-
-### [x] Item E — Per-class `type` URI doc pages *(spec item 7)*
-
-- **Files:** `docs/` (mkdocs) + a `pipelex-dev` CLI subcommand `generate-error-pages`.
-- **Generator:** a `pipelex-dev` CLI subcommand (consistent with the existing `generate-mthds-schema`, `refresh-graph-ui-sri` subcommands) that walks `PipelexError.__subclasses__()` recursively and emits one page per class under `docs/errors/<kebab>.md`. Page content: class name, `cls.title()`, `cls.error_domain`, typical `user_action` (if declared at class level), link to parent class doc, back-link to the schema page.
-- **Authors override per-class content where it adds value** by hand-editing the generated page; the generator detects an `<!-- pipelex:authored -->` marker and skips regeneration of that page.
-- **Tests:** unit smoke test that runs the generator against the current hierarchy and asserts (a) no exceptions, (b) one page per non-abstract `PipelexError` subclass, (c) kebab slugs match `pascal_case_to_kebab(cls.__name__)`. (The uniqueness guard from Item A's tests already catches collisions.)
-- **Acceptance:** clicking a `type` URI from a real error response lands on a populated page. Adding a new `PipelexError` subclass produces a new doc page automatically on next `pipelex-dev generate-error-pages` run.
-
-**Checkpoint 4 — End of Stage 4 (final stage)** ⬇ See [Checkpoint 4 brief](#checkpoint-4--end-of-stage-4) below.
-
----
-
-## What we dropped from the original spec
-
-| Spec item | Status |
-|---|---|
-| Item 8 — `query_pipeline_state(...)` | **Dropped.** Speculative future work; no current consumer needs it. Repo CLAUDE.md: *"Don't design for hypothetical future requirements."* Will be revisited when the first consumer materializes with concrete requirements. |
-| Item 9 — full-payload webhook signature | **Split out.** Lives at [`wip/security/webhook-signing.md`](wip/security/webhook-signing.md). It is security work, not error-handling — the trust-topology shift (from dispatcher-side signing to worker-side signing) deserves its own review on security merit, and its cross-repo deploy sequence is independent of this plan's. |
-
-See [`api-companion-revisions.md`](wip/error-handling/api-companion-revisions.md) for the full reasoning on this and the consolidations above.
-
----
-
-## Deferred follow-ups (out of scope for this pass)
-
-Tracked here so the idea doesn't get lost. Each lands when a concrete consumer materializes with requirements.
-
-### Cause-chain serialization on `ErrorReport`
-
-**What.** Add `causes: list[CauseEntry] | None = None` to `ErrorReport`, where each `CauseEntry` carries the identity triplet (`error_type`, `title`, `type_uri`, `message`) of one wrapper layer. `_enrich_error_report_from_cause` already walks `__cause__`; it would also collect entries during the walk.
-
-**Why deferred.** The current flat model satisfies the API-readiness plan: classification fields (`error_category`, `provider`, `retryable`, etc.) already backfill from the cause, which is what consumers need for routing decisions. The cause chain adds Sentry-style debug richness — valuable when a concrete consumer asks for it, speculative without one.
-
-**Why this is additive, not a future refactor.** Every item in this `TODOS.md` stays unchanged when `causes` later lands:
-
-- `title()` / `type_uri()` classmethods (Item A) — unchanged.
-- `recover_error_report` totality (Item D-1) — unchanged.
-- Webhook threading (Item D-2) — unchanged; carries a richer dict.
-- Webhook signing (separate security track) — unchanged; signs whatever body bytes are there.
-- Disclosure-mode redaction (Item C) — extended by adding per-entry redaction to the existing rule, not rewritten.
-- Temporal data converter — unchanged (`BaseModel` round-trips already work).
-
-`extra="forbid"` plus `exclude_none=True` in `to_dict` mean old payloads validate without the new field.
-
-**Triggers for picking it up.** Any of: (a) the CLI gains a verbose error mode operators want for debugging; (b) the API exposes a `?verbose=true` query param or `Accept-Profile` header; (c) a log-shipper consumer requests Sentry-compatible chain output.
-
-### Webhook payload reserved-key collision
-
-**What.** `DeliveryExecutor._notify_webhook` (`pipelex/pipe_run/delivery_executor.py:240-260`) copies `WebhookTarget.payload` (arbitrary caller dict) and then unconditionally assigns four Pipelex-owned keys on top: `pipeline_run_id`, `status`, `result_url` (success), `error` (failure). A caller who sets one of these keys in their static payload silently has it overwritten — the webhook schema therefore varies with delivery status in a way the caller did not opt into.
-
-**Why deferred.** Item D-2 plan explicitly specified `payload["error"] = error_report.to_dict(VERBOSE)` and the test pins it. The asymmetry is consistent with `result_url`'s pre-existing behavior — `error` just made the four-key reserved set more visible. Surfaced during the Stage 3 /review pass; not a regression introduced by this refactor.
-
-**Recommended fix.** Add a `field_validator` to `WebhookTarget.payload` that rejects the four reserved keys at construction time, with a clear error message. Lands in its own PR after this refactor merges. Full options analysis and sequencing in [`wip/error-handling/track-webhook-payload-collision.md`](wip/error-handling/track-webhook-payload-collision.md).
-
-**Triggers for picking it up.** Any of: (a) a caller reports surprise that their static `error` key vanished on failed runs; (b) `pipelex-api` or the webapp wants to add a new payload field and needs a clear contract for what's already reserved; (c) the webhook-signing track lands and we want a clean payload shape under the signature.
-
----
-
-## Tracking
-
-| ID | Item | Stage | Status |
-|---|---|---|---|
-| A | `PipelexError.title()` + `type_uri()` with auto-derive *(spec 1+2)* | 1 | [x] |
-| B | `request_id` on `JobMetadata` *(spec 3)* | 1 | [x] |
-| C | `to_dict(disclosure_mode=)` + `to_problem_document(...)` *(spec 4+6)* | 2 | [x] |
-| D-1 | Total `recover_error_report` | 2 | [x] |
-| D-2 | `ErrorReport` → `BaseModel`; thread to webhook; full `WfPipeRun` chain test *(spec 5)* | 3 | [x] |
-| E | Per-class doc pages *(spec 7)* | 4 | [x] |
-
-The original spec's item 9 (webhook signature) is tracked separately at [`wip/security/webhook-signing.md`](wip/security/webhook-signing.md).
-
----
-
-## Checkpoints
-
-Each checkpoint **must** end with: (a) all checkboxes in that stage checked, (b) `make agent-check` clean, (c) `make agent-test` clean, (d) this section updated with concrete file:line references for what landed, (e) any deviations from the plan recorded in [`api-companion-revisions.md`](wip/error-handling/api-companion-revisions.md), (f) cold-start instructions confirmed for the next session.
-
-Checkpoints are **hard stops**. Do not pick up the next stage in the same session — context will have grown and the next session is cheaper to start fresh.
-
-### Checkpoint 1 — End of Stage 1
-
-**What should be true:**
-- `PipelexError` has `_declared_title` / `_declared_type_uri` ClassVars + `title()` / `type_uri()` classmethods with auto-derive defaults.
-- `ErrorReport` carries **required `str`** `title` and `type_uri` fields; round-trip through `model_dump` / `model_validate` preserves them. (`ErrorReport` still `@dataclass` at this stage — `BaseModel` conversion lands in Stage 3.)
-- `pascal_case_to_kebab` helper exists in `pipelex/tools/misc/string_utils.py`.
-- `get_config().pipelex.errors_config.base_uri` exists, defaulting to `"https://pipelex.dev/errors"`.
-- Curated `_declared_title` overrides for `CogtError`, `EnvVarNotFoundError`, and any other class whose auto-derive reads badly.
-- `JobMetadata.request_id` exists; `pipeline_run_setup(...)` accepts it; an integration test demonstrates it riding the wire to the activity.
-- Class-name uniqueness test passes for the current hierarchy.
-- All new tests exist and pass; `make agent-check` + `make agent-test` clean.
-
-**Fill in at checkpoint time:**
-
-- **Curated `_declared_title` overrides landed:**
- - `PipelexError._declared_title = "Pipelex error"` — set directly in the class body. Inheritance is bypassed in `title()` via `cls.__dict__.get(...)` (which only consults the requesting class's *own* attribute dict, never walking the MRO), so subclasses without an explicit `_declared_title` of their own auto-derive from their own class name rather than inheriting `"Pipelex error"`.
- - `PipelexUnexpectedError._declared_title = "Unexpected internal error"`
- - `SecurityError._declared_title = "Security policy violation"`
- - `CogtError._declared_title = "AI inference failed"`
- - `EnvVarNotFoundError._declared_title = "Environment variable not set"`
- - `ToolError._declared_title = "Tool error"`
- - `CredentialsError._declared_title = "Missing or invalid credentials"`
- - `FatalError._declared_title = "Fatal error"`
- - `TomlError._declared_title = "TOML parse error"`
- - `StorageError._declared_title = "Storage error"`
- - `StorageS3Error._declared_title = "S3 storage error"` (auto-derive was broken: `pascal_case_to_sentence("StorageS3")` drops the `S` and produced `"Storage 3"`)
- - `StuffError._declared_title = "Stuff error"`
- - `ConceptError._declared_title = "Concept error"`
- - `LibraryError._declared_title = "Library error"`
-- **Files touched:**
- - Production:
- - `pipelex/base_exceptions.py` — added `_humanize_class_name`, `_declared_title` / `_declared_type_uri` ClassVars, `title()` / `type_uri()` classmethods, required `title` / `type_uri` fields on `ErrorReport`, propagation in `to_error_report()` / `_enrich_error_report_from_cause()`. `type_uri()` reads the base URI from the `ErrorManager` singleton (see deviation below).
- - `pipelex/errors/error_manager.py` — new `ErrorManager` singleton (built on `ABCSingletonMeta` / `MetaSingleton`) holding the `ErrorsConfig`. Mirrors the `GraphTracerManager` precedent so `base_exceptions.py` can read it without importing `pipelex.hub`. Types its constructor against a local structural `Protocol` so this module retains zero transitive dependency on the config layer (avoids re-entering `pipelex.base_exceptions` via `pipelex.system.exceptions`).
- - `pipelex/errors/errors_config.py` — new home for the `ErrorsConfig(ConfigModel)` model (moved out of `pipelex/system/configuration/configs.py` so it lives next to the manager that consumes it). `configs.py` now imports it and still mounts it under `Pipelex.errors_config`.
- - `pipelex/pipelex.py` — constructs `self.error_manager = ErrorManager(errors_config=get_config().pipelex.errors_config)` right after config loads; `teardown()` calls `ErrorManager.clear_instance()`.
- - `pipelex/system/configuration/configs.py` — added `ErrorsConfig(ConfigModel)` mounted under `Pipelex.errors_config`.
- - `pipelex/pipelex.toml` — `[pipelex.errors_config]` section with `base_uri = "https://pipelex.dev/errors"`.
- - `pipelex/tools/misc/string_utils.py` — added `pascal_case_to_kebab` (acronym-aware: splits on `[a-z0-9] -> [A-Z]` and `[A-Z] -> [A-Z][a-z]` transitions; does NOT reuse `pascal_case_to_sentence` which has token-loss bugs around digit boundaries).
- - `pipelex/cogt/exceptions.py:87-99` — `CogtError.to_error_report()` populates `title` / `type_uri`.
- - `pipelex/pipeline/job_metadata.py` — added `request_id: str | None = None` to `JobMetadata` (docstring distinguishes from `ProviderErrorMetadata.request_id`).
- - `pipelex/pipeline/pipeline_run_setup.py` — `request_id` kwarg threaded into the constructed `JobMetadata`.
- - `pipelex/temporal/log_temporal.py` — every `WorkflowLog` / `ActivityLog` method takes optional `request_id: str | None = None`, forwarded to the Temporal logger via `extra={"request_id": ...}`.
- - Curated `_declared_title` overrides in: `pipelex/cogt/exceptions.py`, `pipelex/system/exceptions.py`, `pipelex/system/environment.py`, `pipelex/tools/misc/toml_utils.py`, `pipelex/tools/storage/exceptions.py`, `pipelex/core/stuffs/exceptions.py`, `pipelex/core/concepts/exceptions.py`, `pipelex/libraries/exceptions.py`.
- - Tests:
- - New: `tests/helpers/error_report.py` (helper for non-serialization tests), `tests/unit/pipelex/test_pipelex_error_title_and_type_uri.py`, `tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py`, `tests/unit/pipelex/pipeline/test_job_metadata_request_id.py`, `tests/integration/pipelex/pipeline/test_pipeline_run_setup_request_id.py`.
- - Updated: `tests/unit/pipelex/test_base_exceptions.py` (cold-import test — drops `to_error_report()` line and inlines literal `title` / `type_uri`), `tests/unit/pipelex/test_error_report_from_dict.py` (real values + missing-required-field cases for `title` / `type_uri`), `tests/unit/pipelex/test_error_http_status.py` + `tests/unit/pipelex/exceptions/test_error_domain.py` (helper-based), `tests/unit/pipelex/cogt/test_exceptions.py` (expected dict includes new fields), `tests/unit/pipelex/tools/misc/test_string_utils.py` (parametrized `pascal_case_to_kebab` table), `_FULL_REPORT` fixtures in the four temporal tests.
-- **Surprises / deviations (record in `api-companion-revisions.md`):**
- 1. **`type_uri()` reads from an `ErrorManager` singleton (`pipelex/errors/error_manager.py`) constructed by Pipelex bootstrap**, not from `get_config().pipelex.errors_config.base_uri` directly. Original plan called for the lazy `from pipelex.config import get_config` inside `type_uri()`, but pyright reported the static cycle on chain-entry-point files (`pipelex/__init__.py` etc.) that a file-level pragma on `base_exceptions.py` could not suppress. The `ErrorManager` mirrors the `GraphTracerManager` pattern (`MetaSingleton`-based, not registered on `pipelex.hub`), keeping `pipelex.base_exceptions` at the bottom of the import graph (no cycle at all). The manager holds the full `ErrorsConfig` instance — moved into its own module `pipelex/errors/errors_config.py` — typed structurally via a local `Protocol` in `error_manager.py` so the manager itself takes zero dependency on `ConfigModel` (which would re-introduce the cycle through `pipelex.system.exceptions`). Locked-in behavior preserved: no fallback constant; calling `type_uri()` before bootstrap raises a clear `RuntimeError`.
- 2. **`_declared_title` inheritance is intentionally bypassed in `title()`** via `cls.__dict__.get("_declared_title")` rather than direct attribute access. Without this, every bare subclass of `PipelexError` would inherit `"Pipelex error"` instead of auto-deriving from its own class name. The locked-in semantics ("class either declares its own title or auto-derives from its own name") is pinned by a dedicated test (`test_declared_title_does_not_leak_through_inheritance`).
- 3. **`pascal_case_to_kebab` is a fresh regex-based implementation, NOT `pascal_case_to_sentence(...).lower().replace(" ", "-")`.** The existing `pascal_case_to_sentence` loses single-letter tokens before digits (`StorageS3` -> `"Storage 3"`, `V2API` -> `"2 api"`) which would silently mangle docs URIs. `pascal_case_to_kebab` splits on the standard PascalCase boundaries and preserves every character.
- 4. **`StorageS3Error` got a curated `_declared_title = "S3 storage error"`** because the auto-derive (via the existing buggy `pascal_case_to_sentence`) would have produced `"Storage 3"`. Documented as a curated override rather than fixing the underlying `pascal_case_to_sentence` bug (out of scope).
- 5. **`tests/unit/pipelex/test_base_exceptions.py` was kept with just the cold-import subprocess test** (1 TestClass per module rule); the `TestPipelexErrorTitleAndTypeUri` and `TestPipelexErrorTypeUriUniqueness` classes live in their own new files.
-
-**Cold-start for Checkpoint 2:**
-
-- Re-read items C + D-1 here, and [`api-companion-revisions.md`](wip/error-handling/api-companion-revisions.md) §C + §D.
-- Skim `pipelex/temporal/tprl/temporal_error.py:recover_error_report` and its three call sites in `workflow_caller.py`.
-- Run `git log --oneline -20` and `make agent-test` to confirm starting clean.
-- Note: `ErrorReport` is still a `@dataclass` at the end of Stage 1; Stage 3's Item D-2 converts it to `BaseModel`. The Stage 2 work on `to_dict(disclosure_mode=...)` / `to_problem_document(...)` lands on the dataclass form.
-
----
-
-### Checkpoint 2 — End of Stage 2
-
-**What should be true:**
-- `DisclosureMode` enum in `pipelex/base_exceptions.py`.
-- `ErrorReport.to_dict(disclosure_mode=...)` and `ErrorReport.to_problem_document(...)` exist and behave per the redaction rule (stable identifiers kept, message redacted for CONFIG/RUNTIME, INPUT passthrough).
-- Verbose round-trip preserved; strict round-trip explicitly documented as lossy.
-- `recover_error_report` is total: `BaseException -> ErrorReport`. `UnrecoverableWorkflowFailureError` lives in `pipelex/temporal/exceptions.py`. All three call sites in `workflow_caller.py` are simplified.
-- `make agent-check` + `make agent-test` clean.
-
-**Fill in at checkpoint time:**
-
-- **Files touched:**
- - Production:
- - `pipelex/base_exceptions.py` — added `DisclosureMode` enum (VERBOSE / STRICT) with the path-leak-shield-vs-classification-projection contract documented on its docstring; added `_INTERNAL_ERROR_PLACEHOLDER` / `_STRICT_KEPT_FIELDS` module-level constants so `to_dict` and the RFC 7807 extension projection stay in sync; added `disclosure_mode` parameter on `to_dict` (default VERBOSE) implementing the INPUT-passthrough + CONFIG/RUNTIME redaction rule; added `to_problem_document(*, instance=None, request_id=None, disclosure_mode=DisclosureMode.VERBOSE)` mapping `type_uri → type` / `title → title` / `http_status → status` / `message → detail` (no extension echoes, exactly one `title` key).
- - `pipelex/temporal/exceptions.py` — added `UnrecoverableWorkflowFailureError(TemporalFlowError)` with `error_domain = ErrorDomain.RUNTIME` and `_declared_title = "Workflow failed without recoverable error details"`.
- - `pipelex/temporal/tprl/temporal_error.py` — `recover_error_report` signature changed to `(BaseException) -> ErrorReport` (total — no more `| None`). When no embedded report is found or `from_dict` fails on version skew, synthesizes `UnrecoverableWorkflowFailureError(_message_from_exc(exc)).to_error_report()`. New private `_message_from_exc` helper walks the `__cause__` chain for the deepest non-empty message (preserving worker-side cause text), falling back to `repr(exc)` only when every node in the chain has an empty message.
- - `pipelex/temporal/tprl/workflow_caller.py` — dropped the `if error_report is not None` branches at three call sites: `execute_workflow`'s `WorkflowFailureError` clause (was `:128`), and the `isinstance(exc.cause, ApplicationError)` branches of `execute_child_workflow` (`:240`) and `start_child_workflow` (`:292`). The `recover_error_report` return is always usable now. The defensive `WorkflowExecutionError(msg)` constructions on the `WorkflowAlreadyStartedError` / `RPCError` / non-`ApplicationError`-cause paths are intentionally retained — those branches do NOT call `recover_error_report`.
- - Tests:
- - New: `tests/unit/pipelex/test_error_report_disclosure_mode.py` (`TestErrorReportDisclosureMode` — INPUT-passthrough pin, CONFIG/RUNTIME redaction, retryable survival across modes, verbose round-trip, strict non-round-trip, receiver-rehydration). `tests/unit/pipelex/test_error_report_problem_document.py` (`TestErrorReportProblemDocument` — standard-slot population, no `title`/`type_uri` extension duplication, single-`title`-key contract, `request_id` / `instance` extension optionality, strict-mode redaction passthrough for INPUT).
- - Updated: `tests/unit/pipelex/temporal/test_recover_error_report.py` — G3 / G4 / no-application-error cases renamed to `*_synthesizes_unrecoverable` and assert the synthesized report's `error_type` / `error_domain` / `retryable` / message contents instead of `is None`. `tests/unit/pipelex/temporal/test_workflow_caller_error_recovery.py` — `test_workflow_failure_without_report_stays_generic` renamed to `*_synthesizes_unrecoverable` with the round-3 P2 pin: assertion that the synthesized `error.message` contains the underlying exception text and is NOT the legacy `"Failed to execute workflow X"` framing. `tests/unit/pipelex/temporal/test_workflow_caller_child_error_recovery.py` — G3 / G4 child cases renamed and updated to assert the synthesized unrecoverable report; the non-`ApplicationError`-cause case stays unchanged.
-- **Surprises / deviations (record in `api-companion-revisions.md`):**
- 1. **`_message_from_exc` walks the full `__cause__` chain for the deepest non-empty message, NOT just `str(exc) or repr(exc)`.** The plan suggested literally "outer Temporal failure's message if non-empty, else `repr(exc)`", but `WorkflowFailureError` always carries the generic outer text `"Workflow execution failed"`, which would not satisfy the round-3 P2 pin (test asserts the synthesized message "contains the underlying exception text"). The implementation walks the chain keeping the deepest non-empty message — so `WorkflowFailureError(cause=RuntimeError("worker crashed hard"))` synthesizes a message containing `"worker crashed hard"`, not the generic outer framing. `repr(exc)` remains the final fallback when every node's `str` is empty.
- 2. **All three call sites in `workflow_caller.py` were simplified, not just the submitter-side one at `:128`.** The plan's "three call sites" list (`:128`, `:240`, `:292`) is now uniformly post-`if error_report is not None` removal. The child-workflow paths' G3 / G4 tests in `test_workflow_caller_child_error_recovery.py` were updated to match.
- 3. **Pre-existing unrelated test failure flagged for the next session:** `tests/e2e/agent_cli/test_offline_run_dry.py::TestOfflineDryRun::test_gateway_no_cache_no_network_fails_with_unavailable` fails identically on baseline (`git stash` rerun confirms). The CLI subprocess returns an empty `{}` JSON payload while the assertion expects `error_type == "RemoteConfigUnavailableError"`. NOT introduced by Stage 2 — should be fixed independently.
-
-**Cold-start for Checkpoint 3:**
-
-- Re-read Item D-2 + [`api-companion-revisions.md`](wip/error-handling/api-companion-revisions.md) §D. This is the load-bearing stage.
-- The `BaseModel` conversion is the gate — land the round-trip test before the activity arg change.
-- Confirm the new `WfPipeRun` end-to-end test is in scope, not deferred. The existing test bypasses `WfPipeRun`; the new test is the safety net for the outer Temporal wrap.
-- `recover_error_report` is already total (Item D-1) — Item D-2's `wf_pipe_run` change to `error_report = recover_error_report(exc.cause)` does NOT need a `None` guard.
-- The pre-existing `test_gateway_no_cache_no_network_fails_with_unavailable` failure on baseline is unrelated to the error-handling refactor — fix or skip independently before the next `make agent-test` gate.
-
----
-
-### Checkpoint 3 — End of Stage 3
-
-**Biggest unlock; strong stopping point.** After this, the API team can build Phase 4 against a lossless contract.
-
-**What should be true:**
-- `ErrorReport` is now a `BaseModel` with `model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)`. Round-trip test passes.
-- `DeliveryActivityArg.error_report: ErrorReport | None` (no `_dict` shim).
-- `DeliveryExecutor.execute(error_report=...)` and `_notify_webhook(error_report=...)` write `payload["error"] = error_report.to_dict(VERBOSE)` on `FAILED`.
-- `wf_pipe_run` recovers the report via total `recover_error_report(exc.cause)` and threads it through.
-- **Full `WfPipeRun` end-to-end test** demonstrates classification (`error_type`, `error_category`, `retryable`, `user_action`, `model`, `provider`, `title`, `type_uri`) surviving from a worker-side `CogtError` all the way to BOTH (a) the webhook payload AND (b) the submitter-side `WorkflowExecutionError.to_error_report()`. The outer Temporal wrap does not drop the inner report.
-- `make agent-check` + `make agent-test` clean.
-
-**Fill in at checkpoint time:**
-
-- **Files touched:**
- - Production:
- - `pipelex/base_exceptions.py` — `ErrorReport` is now a `BaseModel(model_config=ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True))`. `to_dict` uses `self.model_dump(exclude_none=True)` directly; `from_dict` uses `cls.model_validate(data)`. Dropped the cached `_ERROR_REPORT_ADAPTER` (no longer needed — `model_dump`/`model_validate` are first-class on BaseModel). Dropped the `pydantic.dataclasses` and `TypeAdapter`/`cast` imports.
- - `pipelex/pipeline/exceptions.py` — `PipelineExecutionError.to_error_report()` uses `report.model_copy(update={...})` instead of `dataclasses.replace(report, ...)`. Removed the `from dataclasses import replace` import.
- - `pipelex/temporal/tprl/temporal_error.py` — `recover_error_report` uses `set(ErrorReport.model_fields)` instead of `{field.name for field in fields(ErrorReport)}`. Removed the `from dataclasses import fields` import.
- - `pipelex/pipe_run/delivery_executor.py` — `execute(...)` and `_notify_webhook(...)` accept `error_report: ErrorReport | None = None`. When non-None, the webhook payload includes `error = error_report.to_dict(DisclosureMode.VERBOSE)` so the receiver can losslessly rehydrate via `ErrorReport.from_dict`. Imports `DisclosureMode` and `ErrorReport`.
- - `pipelex/pipe_run/pipe_run.py` — direct-mode `PipeRun.run` now captures `error_report = exc.to_error_report()` when the caught exception is a `PipelexError` and threads it into `self._delivery_executor.execute(error_report=...)`. Non-Pipelex exceptions surface no report (the in-process semantics consumers already expect).
- - `pipelex/temporal/tprl_pipe/act_deliver.py` — `DeliveryActivityArg` gains `error_report: ErrorReport | None = None`. The `act_deliver` activity forwards it to `DeliveryExecutor.execute(error_report=...)`. The existing `BaseModelPayloadConverter._unwrap_optional_base_model` handles the `ErrorReport | None` field directly — no shim needed.
- - `pipelex/temporal/tprl_pipe/wf_pipe_run.py` — on the `ChildWorkflowError` catch path, calls `recover_error_report(exc.cause if exc.cause is not None else exc)` (total since Item D-1), constructs `WorkflowExecutionError("WfPipeRouter failed", error_report=error_report)`, and threads the same `error_report` into `DeliveryActivityArg`. The `ErrorReport` import sits inside the `imports_passed_through()` block with a `noqa: TC001` because the workflow sandbox needs it at runtime for the local-variable annotation.
- - Tests:
- - New: `tests/integration/pipelex/temporal/test_payload_codec_roundtrip.py::TestPayloadCodecRoundTrip::test_error_report_round_trips_through_activity` — pre-flight that pins the `ErrorReport` BaseModel round-trip through a workflow→activity hop with populated nested `UserAction` / `ProviderErrorMetadata`. Lands before the activity arg change in the same commit; safety-net for the `BaseModelPayloadConverter` carrying the new arg.
- - New: `tests/integration/pipelex/temporal/test_workflow_error_report_full_chain.py::TestWorkflowErrorReportFullChain::test_wf_pipe_run_failure_threads_error_report_to_webhook_and_submitter` — end-to-end `WfPipeRun` chain with `delivery_assignment` whose webhook is intercepted by an `httpx.AsyncClient` mock (via `mocker.AsyncMock(side_effect=...)`). Asserts both (a) the webhook payload's `error` dict carries the full classification (`error_type` / `error_category` / `retryable` / `model` / `provider` / `title` / `type_uri` / `user_action.kind`) and (b) the submitter-side `WorkflowExecutionError.to_error_report()` carries the same classification — i.e. the outer Temporal wrap did NOT drop the inner report.
- - New: `tests/integration/pipelex/temporal/test_workflow_error_report_full_chain.py::TestWorkflowErrorReportFullChain::test_wf_pipe_run_failure_without_delivery_assignment_surfaces_classification` — verifies the submitter-side path still surfaces classification when no `delivery_assignment` is configured (skips `act_deliver` entirely).
- - New: `tests/unit/pipelex/pipe_run/test_delivery_executor.py::TestDeliveryExecutor::test_webhook_includes_error_report_on_failed_status` + `test_webhook_omits_error_when_report_is_none` — receiver-rehydration pin (`ErrorReport.from_dict(payload["error"]) == original`) and the COMPLETED-without-report contract.
- - Updated: `tests/unit/pipelex/cogt/test_exceptions.py::TestErrorCategoryInfrastructure::test_error_report_is_frozen` — now expects `pydantic.ValidationError` instead of `dataclasses.FrozenInstanceError`. Updated the test module's imports accordingly.
-- **Workflow's "preserve execution_error for failure attribution" reordering still holds.** `wf_pipe_run.py` re-raises in order: `if execution_error is not None: raise execution_error` first, `if delivery_error is not None: raise delivery_error` second. Test `tests/integration/pipelex/temporal/test_wf_pipe_run_failure_path.py::TestWfPipeRunFailurePath` continues to pin the failure-path invariant (router failure fires delivery with FAILED status before re-raising), and the new full-chain test pins the additional invariant that the structured report is recovered AND threaded through delivery before the re-raise.
-- **Surprises / deviations (recorded in `api-companion-revisions.md` §D-2):**
- 1. **The direct-mode `PipeRun` path also threads `error_report`** (not just the Temporal path the plan called out). The plan's D-2 acceptance criterion ("a Temporal-side pipe failure reaches the webhook with the same classification a sync caller would see locally") implies parity, so the local executor was updated to call `exc.to_error_report()` when the caught exception is a `PipelexError` and pass it to `DeliveryExecutor.execute`. Non-`PipelexError` exceptions still surface no report (consistent with the in-process semantics consumers already expect).
- 2. **`temporal_error.py` field-introspection swap.** `recover_error_report`'s known-fields set was built via `{field.name for field in fields(ErrorReport)}` (stdlib-dataclasses-only API). Under the BaseModel conversion this would `AttributeError` at runtime. Swapped to `set(ErrorReport.model_fields)`, which is the Pydantic v2 equivalent and is iterable as a `dict[str, FieldInfo]` keyed by field name.
- 3. **`title` auto-derive in the full-chain test.** The new `WfPipeRun` end-to-end test asserts `error_dict["title"] == "Llm completion"`, not `"AI inference failed"`. The `_declared_title` inheritance-bypass rule (locked in at Checkpoint 1) means `LLMCompletionError.title()` does NOT inherit `CogtError._declared_title`; it auto-derives from its own class name. Documented inline in the test alongside the assertion so a future reader sees why.
- 4. **Pre-existing baseline test failure persists.** `tests/e2e/agent_cli/test_offline_run_dry.py::TestOfflineDryRun::test_gateway_no_cache_no_network_fails_with_unavailable` still fails on `feature/API-readiness` for unrelated reasons (CLI subprocess returns empty `{}` instead of `{"error_type": "RemoteConfigUnavailableError"}`). Confirmed identical failure on `git stash` baseline — NOT introduced by Stage 3 and not in scope for this checkpoint. Tracked here for the Checkpoint 4 cold-start (or earlier, independent fix) per the Checkpoint 2 hand-off note.
-- **Notify the API team** that Stages 1–3 are landed and their Phases 0/1/4 are unblocked. Update [`api-companion-revisions.md`](wip/error-handling/api-companion-revisions.md) "current state" section.
-
-**Cold-start for Checkpoint 4:**
-
-- Stage 4 is docs polish. Re-read Item E.
-- Read `docs/under-the-hood/error-model.md` to understand the docs site layout.
-- Confirm docs build cleanly locally before starting.
-- The pre-existing `test_gateway_no_cache_no_network_fails_with_unavailable` failure on baseline carries over from Checkpoint 2 — fix or skip independently before the next `make agent-test` gate.
-
----
-
-### Checkpoint 4 — End of Stage 4
-
-**What should be true:**
-- `pipelex-dev generate-error-pages` emits one page per non-abstract `PipelexError` subclass under `docs/errors/<kebab>.md`.
-- A few high-traffic classes have authored overrides (marked with `<!-- pipelex:authored -->`); the rest use the generated default and look sensible.
-- mkdocs build clean; `make agent-check` + `make agent-test` clean.
-
-**Fill in at checkpoint time:**
-
-- **Generator location + invocation:**
- - Library: `pipelex/errors/error_pages_generator.py::generate_error_pages(output_dir: Path)` — renders pages, returns an `ErrorPagesReport(written / unchanged / preserved)`.
- - Class walker: `pipelex/errors/error_module_registry.py::iter_pipelex_error_subclasses()` — force-imports every `*/exceptions.py` and known non-standard error module under `pipelex/`, then walks `PipelexError.__subclasses__()` recursively (filtering out `tests.*` modules so synthetic subclasses can never leak into the docs output).
- - CLI: `.venv/bin/pipelex-dev generate-error-pages [--output DIR] [--quiet]` — defaults to `docs/errors/`, bootstraps Pipelex so `PipelexError.type_uri()` resolves, then teardown.
-- **Authored pages list:** _(none yet — initial run emits 215 generated pages, all of which can be claimed for hand-editing by adding `<!-- pipelex:authored -->` as a standalone line at the top of the page; the generator then preserves it on every subsequent run)._
-- **Files touched:**
- - Production:
- - `pipelex/errors/error_module_registry.py` (new) — explicit + filesystem-scan-based registry of modules that declare `PipelexError` subclasses. Exposes `load_all_error_modules()` and `iter_pipelex_error_subclasses()`.
- - `pipelex/errors/error_pages_generator.py` (new) — `ErrorPagesReport` dataclass, `generate_error_pages()`, `render_error_page()`, `page_slug()`. Authored-marker detection is line-anchored (`_has_authored_marker`) so the generator's own instructional text never falsely flags a generated page.
- - `pipelex/cli/dev_cli/commands/generate_error_pages_cmd.py` (new) — Typer-friendly wrapper that bootstraps + tears down Pipelex around the generator call and prints a Rich status panel.
- - `pipelex/cli/dev_cli/_dev_cli.py` — registered `generate-error-pages` in `PipelexDevCLI.list_commands` and added the matching `@app.command(...)` declaration.
- - `pipelex/core/pipes/inputs/input_stuff_specs_factory.py` — **pre-existing bug fix** (flagged per repo CLAUDE.md). A duplicate `class InputStuffSpecsFactoryError(PipelexError)` shadowed the canonical one in `pipelex/core/pipes/inputs/exceptions.py`, producing two distinct class objects with the same name. The shadow caused `iter_pipelex_error_subclasses()` to enumerate 216 classes against only 215 unique kebab slugs (1 collision). Removed the local class definition, imported the canonical one (which inherits from `InputStuffSpecsError`, the correct hierarchy), and exposed it via `__all__` so the existing test import path (`from pipelex.core.pipes.inputs.input_stuff_specs_factory import InputStuffSpecsFactoryError`) still resolves.
- - `docs/errors/*.md` (215 generated pages, new) — one page per non-test `PipelexError` subclass. Each page carries: class identity table (`error_type`, `title`, `type_uri`, `error_domain`, defining module, parent-class link, class-level `user_action` when declared), a class docstring fragment when present, and a back-link to `under-the-hood/error-model.md`. Pages are stamped with `<!-- pipelex:generated -->` and instruct maintainers to add `<!-- pipelex:authored -->` on its own line to claim a page for hand-editing.
- - Tests:
- - New: `tests/unit/pipelex/errors/test_error_pages_generator.py` (`TestErrorPagesGenerator`) — emits-one-page-per-subclass pin, idempotency pin (rerunning over a generated tree writes nothing), authored-marker preservation pin, marker-detection precision pin (a marker embedded inside other text on the same line is NOT a claim), and the `ErrorPagesReport.total` arithmetic pin.
- - Updated: `tests/unit/pipelex/test_pipelex_error_type_uri_uniqueness.py` — refactored to use the shared `iter_pipelex_error_subclasses()` registry rather than its own ad-hoc import block, so the uniqueness guard and the docs generator walk the SAME class set (eliminating the prior risk where the test missed a hierarchy a new generator would still pick up).
-- **Surprises / deviations (record in `api-companion-revisions.md` §E):**
- 1. **Pre-existing duplicate class `InputStuffSpecsFactoryError` discovered and fixed.** Two distinct class objects with the same name lived in `pipelex/core/pipes/inputs/exceptions.py` (inherits from `InputStuffSpecsError`) and `pipelex/core/pipes/inputs/input_stuff_specs_factory.py` (inherited from `PipelexError`). The existing type-URI uniqueness test missed it because its hard-coded import block loaded only one of the two modules. The shadow only surfaced once `iter_pipelex_error_subclasses()` walked the post-bootstrap class set. Fix in scope per the repo CLAUDE.md "flag and fix pre-existing bugs" rule. The factory module now re-exports the canonical class via `__all__` so test imports (`from .input_stuff_specs_factory import InputStuffSpecsFactoryError`) keep working without rewrite.
- 2. **Filesystem-discovery + non-standard-module list, not a hard-coded module list.** The plan was silent on registry strategy. I chose a `pipelex/`-rooted filesystem scan for `exceptions.py` / `*_errors.py` plus an explicit short list of non-standard modules (`system/environment.py`, `tools/misc/toml_utils.py`, `tools/secrets/secrets_utils.py`, `pipe_operators/shared/template_image_analyzer.py`) so new error modules under the standard naming convention are picked up automatically — no manual registry maintenance for the common case. The non-standard list is small and stable; adding to it is a one-line change.
- 3. **Authored-marker detection is line-anchored, not substring-anchored.** The plan called for `<!-- pipelex:authored -->` as the claim marker but did not specify how to detect it. A naive `in`-substring check would have produced a self-trap: the generator's own instructional text references the marker, so every generated page would have been flagged as authored on the second run (verified — initial implementation reproduced the bug; idempotency test caught it before landing). Detection now requires the marker to appear as its own stripped line, which is the natural form a maintainer would write and not what the generator's prose contains.
- 4. **`base_uri` retargeted to `https://docs.pipelex.com/latest/errors` — the actual docs host.** Original plan defaulted `base_uri` to `https://pipelex.dev/errors`, a domain that does not serve these pages. Per follow-up discussion, retargeted the default to the live MkDocs + mike docs site so `type_uri` dereferences directly to a real page. The `/latest/` alias is mike's canonical pointer at the current stable release (forced via `docs/overrides/main.html` already), so a `type` URI emitted by any deployed version always lands on up-to-date docs. Both `pipelex/pipelex.toml` and `.pipelex/pipelex.toml` updated; the `ErrorsConfig` docstring rewritten to match.
- 5. **`type_uri()` now emits a trailing slash (`<base>/<slug>/`).** Verified MkDocs (with its default `use_directory_urls: true`) builds each `docs/errors/<slug>.md` as `errors/<slug>/index.html`, served at `errors/<slug>/`. The built page's `<link rel="canonical">` matches: `https://docs.pipelex.com/latest/errors/llm-completion-error/`. Without the trailing slash, clients dereferencing the URI would hit a 301 — minor cost but avoidable. Implementation: one-character change inside `PipelexError.type_uri()` (`f"{base}/{slug}/"`). All hardcoded test fixtures rewritten via a one-shot regex sweep (24 replacements across 13 files); the `_DEFAULT_TYPE_URI` constant in `tests/helpers/error_report.py` updated to the same shape.
- 6. **`not_in_nav` directive added to `mkdocs.yml`.** Without it, `mkdocs build --strict` (= `make docs-check`) emits an INFO line listing the 215 generated per-class pages as "not in nav" — noisy and obscures real misses. The directive whitelists `errors/*.md` (excluding `errors/index.md`, which IS in nav) and `CLAUDE.md` (pre-existing docs-authoring guide that was producing the same noise). `make docs-check` now finishes with zero INFO/WARNING/ERROR lines.
- 7. **`errors/index.md` landing page added to the generator and to the docs nav.** Listed once under "Reference > Error Reference", links every per-class page grouped by top-level `PipelexError` branch (CogtError / PipelineExecutionError / TemporalFlowError / etc.). Best-practice take on the user's nav question: 215 leaf pages in the sidebar would be unreadable, but a single landing page in nav makes the section discoverable while the per-class pages stay reachable via direct `type_uri` dereference. Generator emits the index alongside the per-class pages and honors the same `<!-- pipelex:authored -->` preservation rule; a new test pin (`test_index_page_links_every_class`) asserts the index contains a link to each loaded class.
- 5. **Pre-existing baseline test failure persists.** `tests/e2e/agent_cli/test_offline_run_dry.py::TestOfflineDryRun::test_gateway_no_cache_no_network_fails_with_unavailable` still fails on `feature/API-readiness` for unrelated reasons (CLI subprocess returns an empty JSON payload instead of an `error_type`). Identical failure documented at Checkpoint 2 and Checkpoint 3 — NOT introduced by Stage 4 and not in scope for this checkpoint.
-
-**Post-completion (end of error-handling refactor):**
-- Mark [`api-companion-revisions.md`](wip/error-handling/api-companion-revisions.md) "current state" section as fully landed.
-- Replace this `TODOS.md` with a short pointer to the merged PRs.
-- The webhook-signing security track ([`wip/security/webhook-signing.md`](wip/security/webhook-signing.md)) is independent and can land on its own schedule.
-
----
-
-## Where to look when starting cold
-
-1. This `TODOS.md` — find the first unchecked item and its checkpoint context. **Read the "Decisions locked in" section at the top first** — the items below assume them.
-2. [`wip/error-handling/api-companion-revisions.md`](wip/error-handling/api-companion-revisions.md) — what we are actually building vs. what the original spec proposed, with rationale per item. **The pipelex-api agent reads this to know what to expect.**
-3. [`wip/error-handling/changes-for-api-early-draft.md`](wip/error-handling/changes-for-api-early-draft.md) — the original spec, kept for context but superseded by the revisions doc.
-4. [`wip/error-handling/README.md`](wip/error-handling/README.md) — the broader error-handling landscape.
-5. The most recent checkpoint's "Fill in at checkpoint time" block — running notes from the previous session.
-6. `git log --oneline -20` to see the most recent landings.
-
-The cross-repo counterpart lives in [`../pipelex-api/wip/error-handling/`](../../pipelex-api/wip/error-handling/) — open it side-by-side when reasoning about item D-2. The webhook-signing security track has its own plan at [`wip/security/webhook-signing.md`](wip/security/webhook-signing.md).
-
----
-
-## GSTACK REVIEW REPORT
-
-| Review | Trigger | Why | Runs | Status | Findings |
-|--------|---------|-----|------|--------|----------|
-| Eng Review | `/plan-eng-review` | Architecture & tests (required) | 3 | CLEAR (PLAN) | Round 1: 12 issues / 2 critical gaps (folded). Round 2: 1 P1 + 1 P2 (folded). Round 3: 1 P1 + 2 P2 (folded). |
-| CEO Review | `/plan-ceo-review` | Scope & strategy | 0 | — | — |
-| Codex Review | `/codex review` | Independent 2nd opinion | 0 | — | — |
-| Design Review | `/plan-design-review` | UI/UX gaps | 0 | n/a | not applicable (library plan) |
-| DX Review | `/plan-devex-review` | Developer experience gaps | 0 | — | — |
-
-**UNRESOLVED:** none.
-
-**Decisions resolved across review rounds:**
-- Cause-enrichment policy: **wrapper-wins** for `title`/`type_uri`. Cause-chain serialization deferred (see "Deferred follow-ups" section).
-- `WorkflowExecutionError` is the single **wrapper-loses** carve-out — preserves recovered inner classification across the Temporal serialization boundary. Documented in "Decisions locked in" above.
-- Webhook signing secret source: **env-only** (`PIPELEX_WEBHOOK_SIGNING_SECRET`). No config field. Per the repo policy that no secrets live in committed config.
-- Item F (webhook signing) **split out** of this plan into [`wip/security/webhook-signing.md`](wip/security/webhook-signing.md). The findings A3 (rollout) and A5 (env-vs-config) move with it.
-- `DisclosureMode.STRICT` documented on its own docstring as a classification-projection, NOT a path-leak shield. INPUT-domain reports pass through unchanged in STRICT mode; the contract is pinned in the enum's docstring at the entry point developers read.
-
-**VERDICT:** ENG REVIEW (3 rounds) — issues folded into the plan; plan **cleared to implement**. Structurally sound (stage decomposition, hard-stop checkpoints, TDD discipline, no backward-compat shims, no speculative surface). All P1 + P2 items integrated.
-
-**Round 1 — P1 resolution (prior session):**
-1. **Item A migration sweep** — explicit migration step added: 3 production sites (`base_exceptions.py:135`, `base_exceptions.py:166`, `cogt/exceptions.py:88`) + mixed strategy for test fixtures (real values where serialization is under test, conftest helper elsewhere).
-2. **Item C RFC 7807 mapping** — `to_problem_document` maps `type_uri → type` and `title → title`, dropping both from extension members. Single-`title`-key + `type == type_uri` contract test added.
-
-**Round 1 — P2 resolution (prior session):**
-- `_DEFAULT_ERRORS_BASE_URI` fallback rejected; default lives in `pipelex/pipelex.toml`.
-- Curated `_declared_title` for `PipelexError` / `PipelexUnexpectedError` / `SecurityError` added; wide sweep in scope for Item A's PR.
-- `pascal_case_to_kebab` tests for numerics + trailing acronyms added (including `"OAuth2" → "o-auth2"` pin).
-- `ErrorReport.from_dict` missing-required-fields → `ValidationError` test added.
-- Receiver-rehydration test added to Item C.
-
-**Round 2 — P1 finding (this session):**
-1. **`pipelex/pipeline/exceptions.py:44` uses `dataclasses.replace(report, ...)` — breaks under Item D-2's `BaseModel` conversion.** `dataclasses.replace()` is stdlib-dataclass-only; BaseModel uses `model_copy(update=...)`. Folded into Item D-2's migration sweep: drop the `from dataclasses import replace` import and rewrite the call. Regression test added (`PipelineExecutionError.to_error_report()` floor behavior).
-
-**Round 2 — P2 finding (this session):**
-- **`WorkflowExecutionError` wrapper-loses carve-out documented in "Decisions locked in"** above. Prevents future implementer from "fixing" the asymmetry by adding `_enrich_error_report_from_cause(report)` to the override during Item A implementation, which would break the Temporal boundary that this exception exists to bridge.
-
-**Round 2 — Informational (not blocking):**
-- Plan's "~267 `PipelexError` subclasses" count is overestimated. Actual: ~77 direct subclasses (`grep "^class .*(.*PipelexError"`); ~257 total `Error`-named classes, but many are stdlib or pydantic-derived. The "wide sweep" is a smaller job than the plan suggests, but the strategy ("focused pass through every leaf class whose auto-derived title reads badly") still applies — just less work than estimated.
-
-**Round 2 — Verifications performed:**
-- All file:line references in the plan verified against the codebase (`base_exceptions.py:135`, `:166`, `cogt/exceptions.py:88`, `workflow_caller.py:128`, `:240`, `:292`).
-- `pascal_case_to_sentence` confirmed present at `pipelex/tools/misc/string_utils.py:121` — `pascal_case_to_kebab` adjacent placement is sound.
-- `JobMetadata` confirmed `BaseModel` already — Item B's `request_id` field is a clean addition.
-- No existing `errors_config` / `error_base_uri` in the codebase — Item A introduces it without conflict.
-
-**Round 3 — P1 finding (this session):**
-1. **`tests/unit/pipelex/test_base_exceptions.py::test_error_report_constructable_without_cogt_exceptions_loaded` will break under Item A.** The subprocess that test runs does TWO things that fail after Item A: (a) constructs `ErrorReport(error_type='X', message='m')` which becomes a `ValidationError` (missing required `title`/`type_uri`), and (b) calls `PipelexConfigError('boom').to_error_report()` which calls `type_uri()` → `get_config()` → `RuntimeError` because the subprocess never bootstraps Pipelex. Per the locked-in "no fallback constant" decision, the `get_config()` failure is by design — but the existing cold-import regression test needs an explicit migration step. Folded into Item A's migration sweep: the test drops the `to_error_report()` line and constructs `ErrorReport` directly with explicit `title`/`type_uri`. A separate non-subprocess test asserts `PipelexConfigError.to_error_report()` with config loaded (the normal pytest fixture chain handles bootstrapping).
-
-**Round 3 — P2 findings (this session):**
-1. **User-visible behavior change at `workflow_caller.py:131-134` is not pinned by any test.** After Item D-1 drops the `if error_report is not None` branch, the unrecoverable path's `WorkflowExecutionError.message` changes from the Pipelex-framed `"Failed to execute workflow X"` to the synthesized `message_from_exc(exc)` (typically Temporal's own message or `repr(exc)`). This is intentional and more diagnostic, but no end-to-end test pins the new contract. Folded into Item D-1: a new end-to-end test in `test_workflow_caller_error_recovery.py` asserts a non-Pipelex `WorkflowFailureError` surfaces with the synthesized message, NOT the legacy fallback string, and that `error_report.error_type == "UnrecoverableWorkflowFailureError"`.
-2. **Existing `test_workflow_execution_error.py` G7-shaped tests look like dead code after D-1 but aren't.** `WorkflowExecutionError(msg)` without `error_report=...` is still reachable via `start_workflow` (catches only `WorkflowAlreadyStartedError` / `RPCError`) and the `WorkflowAlreadyStartedError` / `RPCError` branches of `execute_workflow`. Folded into Item D-1's "Note on no-longer-reached paths" — a future implementer must not remove those tests as "dead" during D-1.
-
-**Round 3 — Verifications performed:**
-- Confirmed `temporal_pipe_router.py:89-91` (in-workflow child dispatch) re-wraps `ChildWorkflowError` as `WorkflowExecutionError(msg) from exc` without explicit report recovery. Initially flagged as a 4th missing call site, but **invalidated** by `test_recovers_report_past_report_less_wrapper_application_error` (test_recover_error_report.py:70-79) — the recover walk passes through report-less wrapper `ApplicationError`s, so the inner report still surfaces at the submitter boundary regardless of the in-workflow re-wrap. No plan change needed.
-- Verified `BaseModelPayloadConverter.from_payload` (temporal_data_converter.py:147-148) already handles `Optional[BaseModel]` via `_unwrap_optional_base_model` — Item D-2's `error_report: ErrorReport | None` arg is a clean addition with no converter surgery.
-- Verified `pipeline/exceptions.py:1, :44` uses `dataclasses.replace` as the Round-2 finding flagged. Item D-2 migration sweep covers this.
diff --git a/wip/error-handling/archive-worker-classification-sweep.md b/wip/error-handling/archive-worker-classification-sweep.md
deleted file mode 100644
index c43e79da3..000000000
--- a/wip/error-handling/archive-worker-classification-sweep.md
+++ /dev/null
@@ -1,468 +0,0 @@
-# Archive — Inference Workers: Excellent Error Handling (worker-classification sweep)
-
-> **Archived 2026-05-15.** This is the completed worker-classification sweep — every phase landed. It is kept for the running notes and checkpoint history, which have reference value. The current plan is in `_tprl/TODOS.md`.
-
-> **Source of truth:** [track-worker-classification.md](track-worker-classification.md).
-> **Implementation reference:** `pipelex/plugins/anthropic/anthropic_llm_worker.py`.
-> **Test reference:** `tests/unit/pipelex/plugins/anthropic/test_anthropic_worker_object_error_handling.py`.
-> **Out-of-scope follow-up:** [track-extract-classify-render.md](track-extract-classify-render.md) — the natural next step once this sweep lands. Do **not** pull forward.
-
----
-
-## Strategy — how we test SDK boundaries
-
-We do **not** mock SDK modules wholesale. We:
-
-1. **Construct real SDK exception types** with minimal fake response objects (e.g. `anthropic.RateLimitError(..., response=httpx.Response(status_code=429, request=...))`). The worker's `isinstance(...)` checks fire against the real classes, so the test survives SDK renames.
-2. **Patch only the SDK's outbound I/O method** with `mocker.AsyncMock(side_effect=sdk_exc)` — never replace exception classes or SDK modules.
-3. **For instructor-using LLM workers, use real `instructor.from_*()`** against a patched underlying client. The whole point of this work is to handle `InstructorRetryException`'s real wrapping shape; a faked instructor would defeat it.
-
-**Tradeoff:** real-instructor tests are ~0.5s each because instructor runs its full retry loop. We keep **one** real-instructor end-to-end test per provider; the other categorization cases use a synthetic `_wrap_in_instructor_retry(sdk_exc)` helper to build an `InstructorRetryException` directly. Constructing some SDK exceptions requires reading the SDK source for required kwargs (httpx shapes for OpenAI/Anthropic; Google's response wrapper). Acceptable cost; the alternative (mock modules) is brittle and fights the type checker.
-
----
-
-## Scope
-
-Lift every inference worker **beyond** the current Anthropic-as-reference standard. "Beyond" means:
-
-1. **Primary fix:** close the `InstructorRetryException` unwrap defect on OpenAI Completions, OpenAI Responses, Mistral LLM, Google Gemini LLM (the four workers flagged in [track-worker-classification.md](wip/error-handling/track-worker-classification.md#instructor-unwrap-missing-on-four-other-workers)).
-2. **Beyond-reference upgrade A — `UNKNOWN` category.** The current "fall back to `CONTENT`" for an unrecognized underlying exception is wrong. Add `InferenceErrorCategory.UNKNOWN` (with `is_retryable=False`) and route the fallback there. Surfaces real unknowns in telemetry instead of silently mis-categorizing them.
-3. **Beyond-reference upgrade B — structured SDK metadata.** Every raised `CogtError` carries a `provider_metadata: ProviderErrorMetadata` with `status_code`, `request_id`, `retry_after_seconds`, `provider_error_code`, `body`. Unlocks the retry / temporal / CLI tracks already listed as open in the README.
-4. **Beyond-reference upgrade C — structured `UserAction`.** Replace the free-form `user_action: str` with `user_action: UserAction(kind: UserActionKind, detail: str)`. Lets the CLI render consistent advice and lets agent JSON be typed.
-5. **Hygiene:** migrate every worker's `instructor.exceptions` → `instructor.core` import.
-6. **Coverage:** test parity with the Anthropic suite per provider — ~7 categorization cases via synthetic wrap + 1 real-instructor end-to-end. Each case now asserts `provider_metadata` and `user_action.kind` alongside `error_category`.
-7. **Other worker kinds:** audit and lift img-gen, extract, and search workers to the same standard (including upgrades A–C).
-
-The Extract/Classify/Render decomposition that would eliminate duplication across all 18+ workers is **deferred** to [track-extract-classify-render.md](wip/error-handling/track-extract-classify-render.md). It is the natural next step once this sweep lands.
-
-TDD discipline applies to every phase: **RED** (test that fails) → **GREEN** (minimal code to pass) → **REFACTOR** (clean up).
-
----
-
-## Phase 0 — Test helper foundation
-
-Lift reusable test pieces from `tests/unit/pipelex/plugins/anthropic/test_anthropic_worker_object_error_handling.py` to a shared module so every provider test can import them.
-
-- [x] **RED** — write `tests/helpers/test_instructor_test_utils.py` asserting:
- - `wrap_in_instructor_retry(sdk_exc)` returns an `InstructorRetryException` whose `failed_attempts[-1].exception is sdk_exc`
- - `wrap_in_instructor_retry(sdk_exc, include_failed_attempts=False)` produces a wrap where `failed_attempts is None or []` (tenacity-fallback path; `__cause__` is set by callers)
- - `DummySchema` is a minimal `BaseModel` subclass with a single `text: str` field
-- [x] **GREEN** — create `tests/helpers/instructor_test_utils.py` exposing `wrap_in_instructor_retry`, `DummySchema`, and a `make_llm_job(mocker)` skeleton lifted from the Anthropic test (names made public so pyright doesn't flag cross-module private-use)
-- [x] Update `test_anthropic_worker_object_error_handling.py` to import from the shared helper; confirm `.venv/bin/pytest tests/unit/pipelex/plugins/anthropic/` stays green
-- [x] Investigate whether **AWS Bedrock LLM worker** (`pipelex/plugins/bedrock/bedrock_llm_worker.py`) uses `instructor` for structured generation. **Finding:** No — `_gen_object` raises `LLMCapabilityError` ("It is not possible to generate objects with a BedrockLLMWorker") with a `# TODO: try with the newest instructor release` comment. **No Phase 8.5 needed.** Bedrock LLM still benefits from upgrades A–C in Phase 11.
-- [x] Run `make agent-check`
-
-> ### **STOP — CHECKPOINT A: Test helper foundation landed**
->
-> Update this file's checkboxes, commit, and prepare cold-start handoff. Next session resumes at Phase 1.
->
-> **Hand-off context:**
-> - Shared helpers at `tests/helpers/instructor_test_utils.py` ✅
-> - Anthropic tests still green ✅
-> - AWS Bedrock instructor-usage decision: _record in Running Notes_
-
----
-
-## Phase 1 — Shared unwrap helper
-
-Move `_extract_underlying_sdk_exception` from the Anthropic worker to `pipelex/cogt/inference/error_classification.py` so the four pending workers can share one implementation. Promote it to a public name (drop the leading underscore).
-
-- [x] **RED** — write `tests/unit/pipelex/cogt/inference/test_error_classification_unwrap.py`:
- - returns the SDK exception when `instructor_exc.failed_attempts[-1].exception` is set
- - falls back to `__cause__.last_attempt._exception` when `failed_attempts` is empty (tenacity path)
- - returns `None` when both paths are empty
- - never raises on malformed input (defensive)
-- [x] **GREEN** — move the function from `pipelex/plugins/anthropic/anthropic_llm_worker.py` to `pipelex/cogt/inference/error_classification.py`. Renamed to `extract_underlying_sdk_exception` (public).
-- [x] Update `anthropic_llm_worker.py` to import from the shared module; Anthropic worker tests still pass. Removed the now-redundant `test_extract_underlying_uses_cause_when_failed_attempts_missing` test from the Anthropic suite (covered by the new shared test module).
-- [x] Run `make agent-check`
-
-> ### **STOP — CHECKPOINT B: Shared unwrap helper landed**
->
-> **Hand-off context:**
-> - `extract_underlying_sdk_exception` lives in `pipelex/cogt/inference/error_classification.py` ✅
-> - Anthropic worker imports from the shared module ✅
-> - Next phases land the three data-contract upgrades before touching the four pending workers
-
----
-
-## Phase 2 — `InferenceErrorCategory.UNKNOWN` (upgrade A)
-
-The current "fall back to `CONTENT`" path when `extract_underlying_sdk_exception` returns something we don't recognize is technically wrong — `CONTENT` means "the LLM returned bad content," but the truth is "we don't know what happened." `UNKNOWN` with `is_retryable=False` makes downstream retry decisions accurate and surfaces "we should add this case" in telemetry.
-
-- [x] **RED** — write `tests/unit/pipelex/cogt/inference/test_error_classification_unknown.py`. (Note: the enum is defined in `pipelex/cogt/exceptions.py`, not `error_classification.py`. The plan-doc reference was off; tests still import from the correct path.)
-- [x] **RED** — in `test_anthropic_worker_object_error_handling.py`, renamed `test_unrecognized_underlying_falls_back_to_content` → `test_unrecognized_underlying_falls_back_to_unknown`; assertion now expects `InferenceErrorCategory.UNKNOWN`.
-- [x] **GREEN** — added `UNKNOWN = "unknown"` to `InferenceErrorCategory` in `pipelex/cogt/exceptions.py` (lowercase value to match the existing convention; the test asserts `str(...) == "unknown"`).
-- [x] **GREEN** — extended `InferenceErrorCategory.is_retryable` to return `False` for `UNKNOWN` (added to the existing `CONFIGURATION | CONTENT | CAPACITY` group).
-- [x] **GREEN** — Anthropic worker's `InstructorRetryException` fallback now raises `error_category=UNKNOWN` (was `CONTENT`).
-- [x] Run `make agent-check`
-
-> ### **STOP — CHECKPOINT C: `UNKNOWN` category landed**
->
-> **Hand-off context:**
-> - `UNKNOWN` category present with `is_retryable=False` ✅
-> - Anthropic reference worker uses `UNKNOWN` for the unrecognized-underlying fallback ✅
-> - Other workers still use `CONTENT` fallback; migrated in their respective phases
-
----
-
-## Phase 3 — `ProviderErrorMetadata` field (upgrade B)
-
-Every raised inference error should carry structured SDK metadata so downstream consumers (retry/temporal/CLI) don't have to scrape it back from the exception chain.
-
-- [x] **RED** — wrote `tests/unit/pipelex/cogt/inference/test_provider_error_metadata.py` (required/optional fields, round-trip)
-- [x] **RED** — wrote `tests/unit/pipelex/plugins/anthropic/test_extract_anthropic_metadata.py` (status_code, request_id, retry-after, provider_error_code from body, graceful handling of APIConnectionError/APITimeoutError shapes)
-- [x] **RED** — in `test_anthropic_worker_object_error_handling.py`, added `provider_metadata` assertions to rate-limit/quota/bad-request cases plus a `to_error_report()` serialization test.
-- [x] **GREEN** — defined `ProviderErrorMetadata` (Pydantic `BaseModel`) in `pipelex/cogt/inference/error_classification.py`.
-- [x] **GREEN** — added `provider_metadata: ProviderErrorMetadata | None = None` on `CogtError` (rather than scattering on each of the four leaf classes). Rationale in running notes — every CogtError subclass now carries the field uniformly with no per-class `__init__` plumbing.
-- [x] **GREEN** — wrote `extract_anthropic_metadata(exc: BaseException) -> ProviderErrorMetadata` in `pipelex/cogt/inference/error_classification.py`. Tolerates the two SDK shapes (APIStatusError vs APIConnectionError/APITimeoutError).
-- [x] **GREEN** — updated `_raise_categorized_anthropic_sdk_error` to call `extract_anthropic_metadata(sdk_exc)` once and pass `provider_metadata=metadata` to every `LLMCompletionError` and `AnthropicCredentialsError` raise.
-- [x] **GREEN** — added `provider_metadata` to `ErrorReport` (with `arbitrary_types_allowed=True` for the Pydantic dataclass), and wired the field into `CogtError.to_error_report()`. Used `rebuild_dataclass(ErrorReport, ...)` in `cogt/exceptions.py` to resolve the forward reference at import time (keeps `base_exceptions.py` free of cogt deps).
-- [x] Ran `make agent-check` — clean.
-
-> ### **STOP — CHECKPOINT D: `ProviderErrorMetadata` field landed**
->
-> **Hand-off context:**
-> - Four dynamic-category exception types carry `provider_metadata` ✅
-> - Anthropic worker (reference) populates it via `extract_anthropic_metadata` ✅
-> - `to_error_report()` serializes it ✅
-> - Other workers leave `provider_metadata=None` for now; migrated in their respective phases
-
----
-
-## Phase 4 — Structured `UserAction` (upgrade C)
-
-Replace the free-form `user_action: str` with `user_action: UserAction(kind: UserActionKind, detail: str)`. This phase has two parts: define the new types and migrate every existing call site mechanically. Per-worker phases later refine the `kind` from the placeholder `UNKNOWN` to semantic values.
-
-- [x] **RED** — wrote `tests/unit/pipelex/cogt/inference/test_user_action.py`:
- - `UserActionKind` is a `StrEnum` with values `WAIT_AND_RETRY`, `CHECK_BILLING`, `CHECK_CREDENTIALS`, `CHANGE_INPUT`, `CHANGE_MODEL`, `CONTACT_SUPPORT`, `UNKNOWN`
- - `UserAction` is a Pydantic `BaseModel` with `kind: UserActionKind` and `detail: str`
- - Round-trips through `model_dump`/`model_validate`
-- [x] **RED** — updated Anthropic worker test cases to assert `user_action.kind` AND `user_action.detail` per the semantic mapping
-- [x] **GREEN** — defined `UserActionKind` (StrEnum) and `UserAction` (BaseModel) in `pipelex/cogt/inference/error_classification.py`
-- [x] **GREEN** — changed the `user_action` field type on `CogtError` from `str | None` to `UserAction | None`; updated `ErrorReport` accordingly with a TYPE_CHECKING forward ref; extended the `rebuild_dataclass` namespace in `cogt/exceptions.py` to include `UserAction`
-- [x] **GREEN — mechanical migration of every existing call site:** every `user_action=...` site in `pipelex/plugins/**` now wraps the existing advice string as `UserAction(kind=UserActionKind.UNKNOWN, detail=<the_string>)`. Also migrated the two class-level defaults: `InferenceBackendCredentialsError` (cogt/exceptions.py) and `AnthropicCredentialsError` (plugins/anthropic/anthropic_exceptions.py)
-- [x] **GREEN** — refined the Anthropic worker (reference) to use semantic `UserActionKind` values: rate-limit → `WAIT_AND_RETRY`, quota → `CHECK_BILLING`, timeout/connection → `WAIT_AND_RETRY`, content-policy → `CHANGE_INPUT`, bad-request fallback → `CHANGE_INPUT`, permission-denied → `CHECK_CREDENTIALS`
-- [x] **GREEN** — `to_error_report()` serialization unchanged structurally; nested `UserAction` is now serialized by `TypeAdapter.dump_python()` as a `{"kind": "...", "detail": "..."}` dict (Pydantic v2 handles the nested model). CLI consumers (`pipelex/cli/error_handlers.py` and `pipelex/cli/agent_cli/commands/agent_output.py`) now read `report.user_action.detail` instead of treating it as a string.
-- [x] **VERIFY** — targeted tests pass: `tests/unit/pipelex/cogt/`, `tests/unit/pipelex/plugins/`, `tests/unit/pipelex/cli/` all green.
-- [x] Ran `make agent-check` — clean (0 errors, 0 warnings).
-
-> ⚠️ **Risk note:** `to_error_report()` JSON shape changes from `"user_action": "<string>"` to `"user_action": {"kind": "...", "detail": "..."}`. Consumers downstream (CLI rendering, agent JSON, Temporal `ApplicationError.details`) read fields not specific shapes, but verify with a grep across `pipelex/` and the CLI for any code that does `error_report["user_action"]` as a string. Bring it up to the new shape in the same phase.
-
-> ### **STOP — CHECKPOINT E: Structured `UserAction` landed**
->
-> **Hand-off context:**
-> - `UserAction` model + `UserActionKind` enum defined ✅
-> - Field type changed on every `CogtError` subclass that owns `user_action` ✅
-> - Every existing call site mechanically migrated to wrap with `UserAction(kind=UNKNOWN, detail=<existing string>)` ✅
-> - Anthropic worker fully refined with semantic `UserActionKind` values ✅
-> - `to_error_report()` JSON shape updated ✅
-> - Other workers still carry `kind=UNKNOWN` placeholder; refined in their respective phases
-
----
-
-## Phase 5 — OpenAI Completions LLM
-
-Apply unwrap-and-dispatch to `pipelex/plugins/openai/openai_completions_llm_worker.py`. The current `_gen_object` body has a nested `try { try { ... } except InstructorRetryException }`. Collapse to a single `try`; replace the inner with the unwrap-and-dispatch branch; replace the six SDK clauses with a single tuple-catch that delegates to the same categorization helper `_gen_text` uses. Simultaneously: write `extract_openai_metadata`, populate `provider_metadata`, refine `user_action.kind` to semantic values.
-
-- [x] **RED** — wrote `tests/unit/pipelex/plugins/openai/test_extract_openai_metadata.py` covering status_code, request_id (via `exc.request_id` set from `x-request-id` header in `APIStatusError.__init__`), retry-after, provider_error_code (from `exc.type` / `exc.code` since OpenAI's `_make_status_error` already pre-unwraps `body["error"]`), and the `APIConnectionError`/`APITimeoutError` shapes.
-- [x] **RED** — wrote `tests/unit/pipelex/plugins/openai/test_openai_completions_worker_object_error_handling.py` mirroring the Anthropic layout: rate-limit→TRANSIENT/WAIT_AND_RETRY, quota→CAPACITY/CHECK_BILLING, timeout/connection→TRANSIENT/WAIT_AND_RETRY, bad-request+content-policy→CONTENT/CHANGE_INPUT, bad-request generic→CONTENT/CHANGE_INPUT, auth→CONFIGURATION/CHECK_CREDENTIALS, not-found→CONFIGURATION/CHANGE_MODEL, non-SDK→UNKNOWN with provider_metadata=None, plus real-instructor end-to-end.
-- [x] **GREEN** — added `extract_openai_metadata` in `pipelex/cogt/inference/error_classification.py` along with a small `_request_id_from_exc_or_response` helper (Anthropic exposes `exc.request_id` directly; OpenAI mirrors it from `response.headers["x-request-id"]` via `APIStatusError.__init__`).
-- [x] **GREEN** — refactored `_gen_object`: collapsed the nested try, added `InstructorRetryException` unwrap-and-dispatch through a new `_raise_categorized_openai_sdk_error` helper, and routes the unrecognized-underlying fallback to `UNKNOWN`. Tuple-catch on direct-path SDK exceptions also delegates to the same helper.
-- [x] **GREEN** — `_gen_text` now uses the same `_raise_categorized_openai_sdk_error` helper. Every raise carries `provider_metadata=extract_openai_metadata(sdk_exc)` and a semantic `UserActionKind`.
-- [x] Migrated `from instructor.exceptions import InstructorRetryException` → `from instructor.core import InstructorRetryException`.
-- [x] **AUDIT** — OpenAI SDK hierarchy (`openai/_exceptions.py`): `BadRequestError(400)`, `AuthenticationError(401)`, `OAuthError(extends AuthenticationError)`, `PermissionDeniedError(403)`, `NotFoundError(404)`, `ConflictError(409)`, `UnprocessableEntityError(422)`, `RateLimitError(429)`, `InternalServerError(5xx)`, plus `APIConnectionError`/`APITimeoutError`. Added `InternalServerError` and `PermissionDeniedError` to the tuple-catch (previously missing). `ConflictError` / `UnprocessableEntityError` are not raised by the chat-completion path in practice and fall through to the `UNKNOWN` path; documented here so they can be added later if telemetry shows them appearing.
-- [x] Ran `.venv/bin/pytest tests/unit/pipelex/plugins/openai/` (60 passed) and `make agent-check` (0 errors, 0 warnings).
-
-> ### **STOP — CHECKPOINT F: OpenAI Completions done**
->
-> **Hand-off context:**
-> - Wrapped-path categorization parity with `_gen_text` ✅
-> - `extract_openai_metadata` helper landed ✅
-> - All raised errors carry `provider_metadata` + semantic `user_action.kind` ✅
-> - `instructor.core` import migrated ✅
-> - SDK exception hierarchy audited (notes in test docstring / Running Notes)
-
----
-
-## Phase 6 — OpenAI Responses LLM
-
-Same shape as Phase 5 with one specialization: `NotFoundError` raises `LLMModelNotFoundError(message=msg, model_handle=...)` (not just `LLMCompletionError`) so callers can swap models. Keep that specialization inside the categorization helper so it fires on both wrapped and unwrapped paths. `extract_openai_metadata` from Phase 5 is reused (same SDK).
-
-- [x] **RED** — wrote `tests/unit/pipelex/plugins/openai/test_openai_responses_worker_object_error_handling.py` mirroring Phase 5's case list and assertions. Extra case: wrapped `NotFoundError` raises `LLMModelNotFoundError` (not `LLMCompletionError`), `model_handle` is populated, and `provider_metadata.status_code == 404`. Plus real-instructor end-to-end using `instructor.Mode.RESPONSES_TOOLS` with `openai_client.responses.create` patched.
-- [x] **GREEN** — refactored `_gen_object` in `pipelex/plugins/openai/openai_responses_llm_worker.py`. Added `_raise_categorized_openai_sdk_error` helper specialized for Responses (raises `LLMModelNotFoundError` for `NotFoundError`); both `_gen_text` and `_gen_object` now dispatch through it. Tuple-catch and `InstructorRetryException` unwrap path both use the same helper.
-- [x] **GREEN** — `LLMModelNotFoundError` now carries `provider_metadata` end-to-end. Required updating `ModelNotFoundError.__init__` in `pipelex/cogt/exceptions.py` to accept and forward `error_category`, `user_action`, and `provider_metadata` kwargs to `CogtError.__init__`. `ModelWaterfallError` continues to work (it forwards only `message` and `model_handle`; new optional kwargs default to `None`).
-- [x] Migrated `from instructor.exceptions import InstructorRetryException` → `from instructor.core import InstructorRetryException` in this worker.
-- [x] **AUDIT** — OpenAI SDK hierarchy confirmed identical to Phase 5 (`openai/_exceptions.py`): all of `BadRequestError(400)`, `AuthenticationError(401)`, `PermissionDeniedError(403)`, `NotFoundError(404)`, `RateLimitError(429)`, `InternalServerError(5xx)`, `APIConnectionError`, `APITimeoutError` are caught (plus `OAuthError` which extends `AuthenticationError`). `ConflictError` (409) and `UnprocessableEntityError` (422) fall through to the `UNKNOWN` path (not raised on the Responses path in practice — same call as Phase 5).
-- [x] Ran `.venv/bin/pytest tests/unit/pipelex/plugins/openai/` (70 passed), full `tests/unit/pipelex/cogt/` + `tests/unit/pipelex/plugins/` sweep (940 passed), `make agent-check` (0 errors, 0 warnings).
-
-> ### **STOP — CHECKPOINT G: OpenAI Responses done**
->
-> **Hand-off context:**
-> - `LLMModelNotFoundError(model_handle=...)` plumbing fires on the wrapped path AND carries provider_metadata ✅
-> - Both OpenAI workers at full parity ✅
-
----
-
-## Phase 7 — Mistral LLM
-
-Smallest of the four — `_classify_mistral_error` already does the work; the wrapped path just never reaches it. Add `extract_mistral_metadata`.
-
-- [x] **RED** — wrote `tests/unit/pipelex/plugins/mistral/test_extract_mistral_metadata.py` (10 tests). Mistral's body is a raw JSON string (not a pre-parsed dict like OpenAI/Anthropic), so the helper JSON-parses it on a best-effort basis. `NoResponseError` is a separate `Exception` subclass with no response metadata — every status-related field comes back as `None`.
-- [x] **RED** — wrote `tests/unit/pipelex/plugins/mistral/test_mistral_llm_worker_object_error_handling.py` (10 tests). Cases (each asserts category + `user_action.kind` + `provider_metadata`):
- - Wrapped `MistralError` (rate-limit generic 429) → `TRANSIENT` + `WAIT_AND_RETRY`
- - Wrapped `MistralError` (429 with quota keywords) → `CAPACITY` + `CHECK_BILLING`
- - Wrapped `MistralError` (HTTP 402) → `CAPACITY` + `CHECK_BILLING`
- - Wrapped `MistralError` (content-policy 400) → `CONTENT` + `CHANGE_INPUT`
- - Wrapped `MistralError` (generic 400) → `CONTENT` + `CHANGE_INPUT`
- - Wrapped `MistralError` (auth 401) → `CONFIGURATION` + `CHECK_CREDENTIALS`
- - Wrapped `MistralError` (not-found 404) → `CONFIGURATION` + `CHANGE_MODEL`
- - Wrapped `MistralError` (server error 500) → `TRANSIENT` + `WAIT_AND_RETRY`
- - Wrapped non-`MistralError` (e.g. `ValueError`) → `UNKNOWN` + `provider_metadata=None`
- - Real-instructor end-to-end: patches `Mistral.chat.complete_async` (which is what `instructor.from_mistral` ultimately calls)
- - **Note: skipped timeout/connection cases.** Mistral does not have separate `APITimeoutError`/`APIConnectionError` classes the way OpenAI/Anthropic do — its only network-layer exception is `NoResponseError` (a separate `Exception` subclass, not a `MistralError`). HTTP-level errors all surface as `MistralError` with `status_code` set.
-- [x] **GREEN** — added `extract_mistral_metadata(exc: BaseException) -> ProviderErrorMetadata` in `pipelex/cogt/inference/error_classification.py`. Reads `status_code`, `headers` (httpx.Headers — for `x-request-id` and `retry-after`), and `body` (raw JSON string). JSON-parses the body on a best-effort basis; tolerates non-JSON bodies (e.g. HTML error pages from upstream) by leaving `provider_error_code=None` and storing the raw string. Added a small `_provider_error_code_from_flat_body` helper because Mistral's body is flat (`{"message": ..., "type": ..., "code": ...}`) while OpenAI/Anthropic wrap it as `{"error": {...}}` — falls back to the nested helper for endpoints that use that shape.
-- [x] **GREEN** — refactored `_gen_object` in `pipelex/plugins/mistral/mistral_llm_worker.py`:
- ```python
- except InstructorRetryException as instructor_exc:
- underlying_exc = extract_underlying_sdk_exception(instructor_exc=instructor_exc)
- if isinstance(underlying_exc, MistralError):
- raise self._classify_mistral_error(underlying_exc) from instructor_exc
- msg = f"Mistral structured generation failed after retries for model '{self.inference_model.desc}': {instructor_exc}"
- raise LLMCompletionError(msg, error_category=InferenceErrorCategory.UNKNOWN) from instructor_exc
- except MistralError as exc:
- raise self._classify_mistral_error(exc) from exc
- ```
- Dropped the dead `except LLMCompletionError: raise` clause (no callee was raising a pre-categorized `LLMCompletionError` from inside the try). Dropped the misleading `error_category=CONTENT` fallback that previously fired for any unwrappable `InstructorRetryException` — it now routes to `UNKNOWN` per the Phase 2 convention.
-- [x] **GREEN** — refined `_classify_mistral_error` to attach `provider_metadata=extract_mistral_metadata(exc)` on every raise and use semantic `UserActionKind` values: rate-limit→WAIT_AND_RETRY, quota (402 or 429+keywords)→CHECK_BILLING, 401/403→CHECK_CREDENTIALS, 404→CHANGE_MODEL, content-policy→CHANGE_INPUT, generic bad-request→CHANGE_INPUT, 5xx→WAIT_AND_RETRY, fallback→WAIT_AND_RETRY. Note: previously the fallback path lacked a `user_action` entirely; it now carries one too so downstream consumers see a uniform shape.
-- [x] Migrated `from instructor.exceptions import InstructorRetryException` → `from instructor.core import InstructorRetryException` in `mistral_llm_worker.py`.
-- [x] **AUDIT** — `mistralai` SDK exception hierarchy (rooted at `mistralai/models/`):
- - `MistralError(Exception)` — base for all HTTP errors. Carries `message`, `status_code` (int), `body` (str — raw response text), `headers` (httpx.Headers), `raw_response` (httpx.Response).
- - `SDKError(MistralError)` — fallback when no more specific error class matches.
- - `ResponseValidationError(MistralError)` — pydantic validation failure on response shape.
- - `HTTPValidationError(MistralError)` — server-side validation error (typically 422).
- - `NoResponseError(Exception)` — separate (not a MistralError); raised when no HTTP response is received at all (network/timeout). The current worker tuple-catch only catches `MistralError`, so `NoResponseError` would propagate as-is — acceptable today because the tenacity retry layer above absorbs it. If telemetry surfaces it later, add a dedicated branch.
-- [x] Ran `.venv/bin/pytest tests/unit/pipelex/plugins/mistral/` (51 passed) and full plugins+cogt sweep (962 passed); `make agent-check` clean (0 errors, 0 warnings).
-
-> ### **STOP — CHECKPOINT H: Mistral LLM done**
->
-> **Hand-off context:**
-> - `extract_mistral_metadata` lives in `pipelex/cogt/inference/error_classification.py` alongside the OpenAI/Anthropic helpers ✅
-> - `_classify_mistral_error` now attaches `provider_metadata` + semantic `user_action.kind` on every branch ✅
-> - `_gen_object` unwraps `InstructorRetryException` and dispatches through `_classify_mistral_error`; unrecognized underlying routes to `UNKNOWN` ✅
-> - `instructor.core` import migrated ✅
-> - `MistralError` body is a raw JSON string (unlike OpenAI/Anthropic which deliver a dict); the helper parses it on a best-effort basis. The flat top-level shape (`{"type": ..., "code": ...}`) is handled in addition to the nested `{"error": {...}}` shape via the new `_provider_error_code_from_flat_body` helper.
-
----
-
-## Phase 8 — Google Gemini LLM
-
-Symmetric to Mistral, plus `ServerError → TRANSIENT` direct mapping that doesn't need `_classify_google_client_error`. Add `extract_google_metadata`.
-
-- [x] **RED** — wrote `tests/unit/pipelex/plugins/google/test_extract_google_metadata.py` (10 tests). Google's `APIError`/`ClientError`/`ServerError` carry `code: int` (HTTP status — *not* `status_code`), `message`, `status` (symbolic name like `RESOURCE_EXHAUSTED`), and `details` (the raw JSON response dict). Constructed via `genai_errors.ClientError(code, response_json, response)` with an `httpx.Response` for header-bearing cases.
-- [x] **RED** — wrote `tests/unit/pipelex/plugins/google/test_google_llm_worker_object_error_handling.py` (10 tests). Cases (each asserts category + `user_action.kind` + `provider_metadata`):
- - Wrapped `genai_errors.ServerError` (500) → `TRANSIENT` + `WAIT_AND_RETRY`
- - Wrapped `genai_errors.ClientError` (429 generic) → `TRANSIENT` + `WAIT_AND_RETRY`
- - Wrapped `genai_errors.ClientError` (429 quota / `RESOURCE_EXHAUSTED`) → `CAPACITY` + `CHECK_BILLING`
- - Wrapped `genai_errors.ClientError` (400 content-policy) → `CONTENT` + `CHANGE_INPUT`
- - Wrapped `genai_errors.ClientError` (400 generic) → `CONTENT` + `CHANGE_INPUT`
- - Wrapped `genai_errors.ClientError` (401 auth) → `CONFIGURATION` + `CHECK_CREDENTIALS`
- - Wrapped `genai_errors.ClientError` (403 forbidden) → `CONFIGURATION` + `CHECK_CREDENTIALS`
- - Wrapped `genai_errors.ClientError` (404 not-found) → `CONFIGURATION` + `CHANGE_MODEL`
- - Wrapped non-SDK exception (`ValueError`) → `UNKNOWN` + `provider_metadata=None`
- - Real-instructor end-to-end: patches `client.aio.models.generate_content` (what `instructor.from_genai` ultimately calls in `use_async=True` mode); requires injecting a real `genai_types.Content` from `prepare_user_contents` because instructor's gemini message converter rejects a bare empty list as a message.
-- [x] **GREEN** — added `extract_google_metadata(exc: BaseException) -> ProviderErrorMetadata` in `pipelex/cogt/inference/error_classification.py` alongside a small `_google_provider_error_code_from_details` helper (reads `error.status` then top-level `status` to recover symbolic names like `RESOURCE_EXHAUSTED`, `UNAUTHENTICATED`, `PERMISSION_DENIED`). `request_id` comes from `response.headers["x-goog-request-id"]` (falling back to `x-request-id`); status code from `exc.code` (Google does not use `exc.status_code`); body is `exc.details`.
-- [x] **GREEN** — refactored `pipelex/plugins/google/google_llm_worker.py`. Added `_raise_categorized_google_sdk_error(sdk_exc, chain_from)` helper that dispatches `ServerError` directly to TRANSIENT (no need for the 4xx discriminator) and routes `ClientError` through `_classify_google_client_error`. Both `_gen_text` and `_gen_object` now go through the helper. `_gen_object` unwraps `InstructorRetryException` first; unrecognized underlying routes to `UNKNOWN` per Phase 2 convention (previously fell back to `CONTENT`).
-- [x] **GREEN** — refined `_classify_google_client_error` to attach `provider_metadata=extract_google_metadata(exc)` on every raise and use semantic `UserActionKind` values: 404→CHANGE_MODEL, 401/403→CHECK_CREDENTIALS, 429+quota→CHECK_BILLING, 429+generic→WAIT_AND_RETRY, 400+content-policy→CHANGE_INPUT, 400+generic→CHANGE_INPUT, 4xx fallback→WAIT_AND_RETRY. Previously the 404, 401/403, generic-400, and 4xx-fallback paths lacked a `user_action` entirely; they now carry one so downstream consumers see a uniform shape. Existing `test_google_worker_error_handling.py` (the direct `_gen_text` path) keeps passing — the `expected_action_substring` check is `None` for the cases we newly populated, so adding a `user_action.detail` is a no-op for the assertion.
-- [x] Migrated `from instructor.exceptions import InstructorRetryException` → `from instructor.core import InstructorRetryException` in `google_llm_worker.py`.
-- [x] **AUDIT** — `google-genai` SDK exception hierarchy (`google/genai/errors.py`):
- - `APIError(Exception)` — base for all HTTP errors. Carries `code: int` (HTTP status), `response` (httpx/requests/replay response, may be `None`), `message`, `status` (symbolic), `details` (raw JSON dict).
- - `ClientError(APIError)` — 4xx errors.
- - `ServerError(APIError)` — 5xx errors.
- - `UnknownFunctionCallArgumentError(ValueError)`, `UnsupportedFunctionError(ValueError)`, `FunctionInvocationError(ValueError)`, `UnknownApiResponseError(ValueError)` — these are tool-calling / response-parsing failures, not HTTP errors. They subclass `ValueError`, not `APIError`, so they fall through to the wrapped-path `UNKNOWN` branch. Acceptable today; if telemetry shows them appearing in inference flows, add a dedicated branch.
- - Note: Google's SDK does *not* have separate timeout/connection classes the way OpenAI/Anthropic do. Network-level failures propagate as the underlying `httpx`/`requests` exceptions and would fall through tuple-catch, hitting the wrapped-path `UNKNOWN` branch or being absorbed by tenacity retry above.
-- [x] Ran `.venv/bin/pytest tests/unit/pipelex/plugins/google/` (68 passed) and full plugins+cogt sweep (889 passed); `make agent-check` clean (0 errors, 0 warnings).
-
-> ### **STOP — CHECKPOINT I: Google Gemini LLM done**
->
-> **Hand-off context:** all four instructor-unwrap workers now classify wrapped errors correctly AND carry full structured metadata + semantic user_action. LLM-side defect closed; beyond-reference upgrades A–C delivered for the four targeted workers plus Anthropic.
-
----
-
-## Phase 9 — LLM cross-cutting cleanup
-
-- [x] Full LLM test sweep: `.venv/bin/pytest tests/unit/pipelex/plugins/{anthropic,openai,mistral,google}/` — 217 passed.
-- [x] `rg "from instructor.exceptions" pipelex/` — zero results (`instructor.core` migration complete on all five LLM workers).
-- [x] **Uniformity check** — `rg "raise LLMCompletionError" pipelex/plugins/{anthropic,openai,mistral,google}/` — every match now carries `provider_metadata=` and `user_action=UserAction(...)`. The orphan response-shape validation paths (empty choices, no candidates, None content, exhausted-thinking-tokens, instructor-misconfigured-for-Responses) that previously raised bare `LLMCompletionError(msg)` were migrated to explicit `error_category` + `provider_metadata=None` (non-SDK paths) + semantic `UserAction`. Audit one-liner `rg "raise LLMCompletionError" pipelex/plugins/{anthropic,openai,mistral,google}/ -A 6 | rg -v "provider_metadata" | rg "raise (LLM|Img|Extract|Search)"` returns empty.
-- [x] **AWS Bedrock decision check** — Phase 0 confirmed Bedrock LLM worker does not use `instructor` (the `_gen_object` path raises `LLMCapabilityError`). No Phase 8.5 was created. Bedrock still benefits from upgrades A–C in Phase 11.
-- [x] Updated [wip/error-handling/track-worker-classification.md](wip/error-handling/track-worker-classification.md): the "Instructor unwrap missing on four other workers" gap is gone, the per-provider unwrap-and-dispatch followups are collapsed into a "landed" note, and a sentence about beyond-reference upgrades A/B/C now sits in the opening paragraph.
-- [x] Updated [wip/error-handling/README.md](wip/error-handling/README.md): "Worker classification" row marks the LLM-side track as landed and points the remaining non-LLM-worker migration at `_tprl/TODOS.md` Phases 10–12. "Error metadata model" row reflects that `ProviderErrorMetadata` + `UserAction` are now uniform across LLM workers.
-- [x] `make agent-check && make agent-test` — clean.
-
-> ### **STOP — CHECKPOINT J: LLM-side track closed**
->
-> **Hand-off context:** worker-classification track has no remaining LLM-side gaps. Track docs reflect reality. Beyond-reference upgrades A–C live across all LLM workers that this sweep touched (Anthropic + 4). Other LLM workers still need upgrade migration via Phase 11. Ready to audit non-LLM worker kinds.
-
----
-
-## Phase 10 — Img-gen worker audits
-
-> Note: each worker within this phase is an independent unit of work. The agent may save/checkpoint between workers if context grows — record per-worker hand-off in the Running Notes section.
-
-The img-gen workers already have basic classification landed. This phase brings each up to the beyond-reference standard: extract metadata, structured user_action, UNKNOWN fallback where applicable, and confirms SDK exception coverage.
-
-For each worker: (a) read source — confirm every documented SDK exception type is caught and routed through the right discriminator; (b) write `extract_<provider>_metadata` helper if not already done (some providers may already have it from LLM workers — e.g. OpenAI img-gen reuses `extract_openai_metadata`); (c) update each raise to pass `provider_metadata=...` and semantic `user_action=UserAction(...)`; (d) replace `CONTENT` fallback with `UNKNOWN` where the underlying is genuinely unknown; (e) update tests to assert metadata + user_action.kind.
-
-- [x] **OpenAI img-gen** — `pipelex/plugins/openai/openai_img_gen_worker.py` (reuse `extract_openai_metadata`). Introduced `_raise_categorized_openai_sdk_error` helper, collapsed the per-exception except blocks into a single tuple-catch that delegates through it. Added `InternalServerError` and `PermissionDeniedError` to the catch (previously not caught). Every raise carries `provider_metadata=extract_openai_metadata(sdk_exc)` and a semantic `UserActionKind`. `NotFoundError` continues to raise `ImgGenModelNotFoundError(model_handle=...)`.
-- [x] **OpenAI Completions img-gen** — `pipelex/plugins/openai/openai_completions_img_gen_worker.py` (reuse `extract_openai_metadata`). Same helper-method pattern as the standalone OpenAI img-gen worker.
-- [x] **Google img-gen** — `pipelex/plugins/google/google_img_gen_worker.py`. `_classify_google_client_error` now attaches `provider_metadata=extract_google_metadata(exc)` on every branch and uses semantic `UserActionKind` values: 404→CHANGE_MODEL, 401/403→CHECK_CREDENTIALS, 429+quota→CHECK_BILLING, 429+generic→WAIT_AND_RETRY, 400+content-policy→CHANGE_INPUT, 400+generic→CHANGE_INPUT, 4xx fallback→WAIT_AND_RETRY. `ServerError` (500) now also carries `provider_metadata` + semantic `WAIT_AND_RETRY`. Per Phase 11/12 follow-up, kept `ImgGenGenerationError` (not `ImgGenModelNotFoundError`) for 404 to match the existing test contract; mirror with the LLM worker.
-- [x] **Azure img-gen** — `pipelex/plugins/azure_rest/azure_img_gen_worker.py` (path was `azure_rest`, not `azure`). Added `extract_azure_metadata` to `error_classification.py` (reads status, `x-ms-request-id` / `apim-request-id` / `x-request-id` headers, retry-after; JSON-parses the response body on a best-effort basis to surface `provider_error_code` from both flat and nested error shapes; tolerates HTML error pages from upstream). Introduced `_raise_categorized_azure_status_error` helper; every raise carries `provider_metadata` + semantic `UserActionKind`. Added a 404 branch (deployment not found → CHANGE_MODEL) that wasn't present in the original worker; the previous fallback-to-CONFIGURATION path now uses `CONTACT_SUPPORT` since it's reached only for unexpected status codes.
-- [x] **FAL img-gen** — `pipelex/plugins/fal/fal_img_gen_worker.py`. Added `extract_fal_metadata` to `error_classification.py` (reads `status_code`, `response_headers` dict for `x-request-id` / `x-fal-request-id` and `retry-after`, `error_type` as `provider_error_code`, JSON-parses the response text body when available). `_raise_categorized_fal_http_error` helper handles `FalClientHTTPError` with semantic `UserActionKind`; `MissingCredentialsError` → CHECK_CREDENTIALS; `FalClientTimeoutError`/`FalClientError` → WAIT_AND_RETRY. Added a 404 branch (model not found → CHANGE_MODEL).
-- [x] **HuggingFace img-gen** — `pipelex/plugins/huggingface/huggingface_img_gen_worker.py`. Added `extract_huggingface_metadata` to `error_classification.py` (uses `exc.request_id` which `HfHubHTTPError.__init__` mirrors from `X-Request-Id` / `X-Amzn-Trace-Id` / `X-Amz-Cf-Id`; reads body from `response.text` since HF wraps `requests.Response`, not `httpx.Response`). `_raise_categorized_hf_http_error` helper with semantic `UserActionKind`; `InferenceTimeoutError` → WAIT_AND_RETRY. Added 404→CHANGE_MODEL and 402→CHECK_BILLING branches.
-- [x] **Gateway img-gen** — `pipelex/plugins/gateway/gateway_img_gen_worker.py`. Added `extract_gateway_metadata` to `error_classification.py` (Portkey SDK exception shape mirrors OpenAI — `APIStatusError` exposes `status_code`, `response.headers`, `body` as a pre-parsed dict). Added `GatewayFactory.make_user_action_from_portkey_error` and `GatewayFactory.make_provider_metadata_from_portkey_error` classmethods that complement the existing `classify_error_category`/`make_error_summary_from_portkey_error` helpers. Img-gen worker now uses all four. Extract/search workers can adopt the new helpers in Phase 11/12.
-- [x] `make agent-check && .venv/bin/pytest tests/unit/pipelex/plugins/ tests/unit/pipelex/cogt/` — 1069 passed, 0 errors, 0 warnings.
-
-> ### **STOP — CHECKPOINT K: Img-gen audit complete**
->
-> **Hand-off context:**
-> - `extract_azure_metadata`, `extract_fal_metadata`, `extract_huggingface_metadata`, `extract_gateway_metadata` all live in `pipelex/cogt/inference/error_classification.py` alongside the LLM-side helpers ✅
-> - Every img-gen worker raises `ImgGenGenerationError` / `ImgGenModelNotFoundError` with `provider_metadata` + semantic `UserActionKind` ✅
-> - All new tests parallel the Anthropic reference suite (metadata test + worker-level semantic test asserting category + user_action.kind + provider_metadata fields) ✅
-> - Gateway helpers (`make_user_action_from_portkey_error`, `make_provider_metadata_from_portkey_error`) are ready for adoption by `gateway_extract_worker.py` and `gateway_search_worker.py` in Phases 11/12
-
----
-
-## Phase 11 — Extract worker audits + AWS Bedrock LLM (if not handled in 8.5)
-
-Same approach as Phase 10. Bedrock LLM lands here too if Phase 0 found it doesn't use instructor (no unwrap defect, but it still benefits from upgrades A–C).
-
-- [x] **AWS Bedrock LLM** — `pipelex/plugins/bedrock/bedrock_llm_worker.py`. Added `extract_bedrock_metadata` to `error_classification.py` (reads `Error.Code`, `ResponseMetadata.HTTPStatusCode` / `RequestId` / `HTTPHeaders.retry-after`; keeps the full `response` dict as `body`). Introduced `_classify_bedrock_client_error` helper; every raise carries `provider_metadata` + semantic `UserActionKind` (CHECK_BILLING for quota, CHECK_CREDENTIALS for AccessDenied, CHANGE_INPUT for ValidationException, CHANGE_MODEL for ResourceNotFoundException, WAIT_AND_RETRY for throttling / unavailable / unknown). Added a `ResourceNotFoundException` branch (previously absent — fell through to the TRANSIENT fallback).
-- [x] **Mistral extract** — `pipelex/plugins/mistral/mistral_extract_worker.py`. Refactored `_classify_mistral_error` to mirror the LLM worker's shape (attached `provider_metadata` + semantic `UserActionKind` on every branch). Previously the 401/403, 404, generic-400, and fallback paths lacked a `user_action` entirely — now they all carry one for uniformity.
-- [x] **Docling extract** — `pipelex/plugins/docling/docling_extract_worker.py`. Added `extract_local_extract_metadata` (shared helper in `error_classification.py`) for local extractors — every status field comes back as `None`, only `sdk_exception_type` / `provider_error_code` are meaningful. All four exception branches (`FileNotFoundError`, `ValueError`, `RuntimeError`, `OSError`) now carry `provider_metadata` + semantic `UserActionKind`.
-- [x] **Linkup extract** — `pipelex/plugins/linkup/linkup_extract_worker.py`. Added `extract_linkup_metadata` (Linkup SDK does not expose response metadata — only `sdk_exception_type` / `provider_error_code` are meaningful; the SDK class name is the canonical signal). Refactored to a `_classify_linkup_error` method (mirrors the search worker's shape — search adoption deferred to Phase 12). Single tuple-catch in `_extract_pages` dispatches through the helper.
-- [x] **Gateway extract** — `pipelex/plugins/gateway/gateway_extract_worker.py`. Adopted `extract_gateway_metadata` + `GatewayFactory.make_user_action_from_portkey_error` (both landed in Phase 10). Both `_extract_web_fetch` and `_extract_base64_url` raise `ExtractJobFailureError` with `provider_metadata` + `user_action`. Tenacity retry wraps the call and reraises — categorization signal survives the retry boundary intact.
-- [x] **pypdfium2** — `pipelex/plugins/pypdfium2/pypdfium2_worker.py`. Reused the shared `extract_local_extract_metadata` helper added for Docling. Every exception branch carries `provider_metadata` + semantic `UserActionKind`.
-- [x] `make agent-check && .venv/bin/pytest tests/unit/pipelex/plugins/ tests/unit/pipelex/cogt/` — 0 errors, 0 warnings; 1122 passed.
-
-> ### **STOP — CHECKPOINT L: Extract audit complete**
->
-> **Hand-off context:**
-> - `extract_bedrock_metadata`, `extract_linkup_metadata`, `extract_local_extract_metadata` all live in `pipelex/cogt/inference/error_classification.py` alongside the existing per-provider helpers ✅
-> - Bedrock LLM, Mistral extract, Docling extract, Linkup extract, Gateway extract, pypdfium2 — every raise carries `provider_metadata` + semantic `UserActionKind` ✅
-> - Linkup search worker (Phase 12) still has its own `_classify_linkup_error` with UNKNOWN placeholders; it can adopt `extract_linkup_metadata` in Phase 12 with a single helper swap.
-> - Gateway search worker (Phase 12) similarly can adopt `extract_gateway_metadata` + `make_user_action_from_portkey_error` mirroring the extract worker's adoption.
-
----
-
-## Phase 12 — Search worker audits
-
-- [x] **Linkup search** — `pipelex/plugins/linkup/linkup_search_worker.py`. Refactored `_classify_linkup_error` to mirror the extract worker's shape: attaches `provider_metadata=extract_linkup_metadata(exc)` on every branch and uses semantic `UserActionKind` values (CHECK_CREDENTIALS for auth, CHECK_BILLING for insufficient-credit, WAIT_AND_RETRY for rate-limit/timeout/fallback, CHANGE_INPUT for invalid-request). Previously the timeout, invalid-request, no-result/unknown, and fallback branches lacked a `user_action` entirely — now every branch carries one. `LinkupNoResultError`/`LinkupUnknownError` route through the fallback (TRANSIENT + WAIT_AND_RETRY), same as before.
-- [x] **Gateway search** — `pipelex/plugins/gateway/gateway_search_worker.py`. `_call_relay`'s `except portkey_exceptions.APIError` block now also calls `GatewayFactory.make_user_action_from_portkey_error(exc)` and `extract_gateway_metadata(exc)` (both landed in Phase 10), and passes `user_action=` + `provider_metadata=` to `GatewaySearchResponseError`. The tenacity retry boundary is preserved: `AsyncRetrying(reraise=True)` reraises the last `APIError` verbatim into the except block, so categorization signal and request_id survive across the retry boundary — same pattern confirmed for the extract worker in Phase 11.
-- [x] `make agent-check && make agent-test` — clean.
-
-> ### **STOP — CHECKPOINT M: Search audit complete**
->
-> **Hand-off context:**
-> - Both search workers (Linkup, Gateway) now raise `SearchJobFailureError` / `GatewaySearchResponseError` with `provider_metadata` + semantic `UserActionKind` on every branch ✅
-> - Linkup search reuses `extract_linkup_metadata`; Gateway search reuses `extract_gateway_metadata` + `GatewayFactory.make_user_action_from_portkey_error` — no new helpers needed in this phase ✅
-> - New tests: `test_linkup_search_worker_semantic.py` (7 cases), `test_gateway_search_worker_semantic.py` (5 cases). Existing `test_linkup_worker_error_handling.py` still passes — the `_classify_linkup_error` refactor preserved every error message substring and category it asserts.
-> - All worker kinds (LLM, img-gen, extract, search) are now at the beyond-reference standard. Phase 13 is the final cross-cutting integration check.
-
----
-
-## Phase 13 — Final integration check
-
-- [x] Full suite: `make agent-test` — clean.
-- [x] Confirmed no `except Exception:` regressions: `rg "except Exception" pipelex/plugins/` returns matches only in `teardown()` cleanup methods (`google_llm_worker`, `google_img_gen_worker`, `gateway_extract_worker`) plus the non-worker `bedrock_list.py` / `mistral_factory.py`. Every match is pre-existing best-effort async-client cleanup with a documented reason in source ("Log but don't fail teardown if cleanup has issues"). None sit on an error-classification path; no regressions introduced by this sweep.
-- [x] Confirmed `from exc` chaining: every SDK-error raise chains via `from exc`; the migrated response-shape raises that sit inside `except` blocks (`gateway_search_worker._extract_content`, `fal_factory.make_generated_image_list`) keep `from exc`; the remaining response-shape raises are post-success validation checks (not in an `except` block) so they correctly carry no `from exc`.
-- [x] **Uniformity check** — every raised `LLMCompletionError` / `ImgGenGenerationError` / `ExtractJobFailureError` / `SearchJobFailureError` / `GatewaySearchResponseError` now carries `provider_metadata=` and `user_action=UserAction(...)`. The audit surfaced a real gap: Phases 10–12 migrated the SDK-error raises but left the **response-shape validation** bare raises (`raise XError(msg)`) untouched in the img-gen / extract / gateway-search workers — unlike the LLM workers, which Phase 9 cleaned up. Migrated all of them (openai/google/azure/gateway/openai-completions img-gen, fal_factory, gateway extract, gateway search) to mirror the Phase 9 LLM treatment. See running notes.
-- [x] Confirmed `rg "kind=UserActionKind.UNKNOWN" pipelex/plugins/` returns zero matches — no placeholder `UNKNOWN` user-action kinds remain anywhere in the plugins.
-- [x] Updated [wip/error-handling/README.md](wip/error-handling/README.md) status table — "Error metadata model" and "Worker classification" rows now read as landed for **all** inference workers (LLM + img-gen + extract + search), with the residual "still need migration" clauses dropped.
-- [x] Confirmed [wip/error-handling/track-testing.md](wip/error-handling/track-testing.md) "worker-level classification tests are comprehensive" claim still matches reality — Phases 10–12 added `test_*_semantic.py` suites for img-gen / extract / search workers; the higher-level gaps (full-chain snapshot, dict-drift detection) the doc lists are still open. No update needed.
-- [x] **Extract/Classify/Render track is ready to start:** all four prerequisites in [track-extract-classify-render.md](wip/error-handling/track-extract-classify-render.md) are satisfied — `InferenceErrorCategory.UNKNOWN` (Phase 2), `ProviderErrorMetadata` Pydantic model (Phase 3), structured `UserAction` (Phase 4), instructor-unwrap landed on the four workers (Phases 5–8). The doc's "Current state (assumed post-TODOS.md sweep)" section now matches actual reality; no update needed.
-
-> ### **DONE**
-
----
-
-## Running notes
-
-Use this section to capture decisions, surprises, and cold-start handoff context as phases land. Add timestamped entries; never delete.
-
-- **2026-05-14 — Phase 0 landed.** Shared helpers at `tests/helpers/instructor_test_utils.py` expose `wrap_in_instructor_retry`, `DummySchema`, and `make_llm_job`. Names are public (no underscore) because pyright flags cross-module use of underscore-prefixed identifiers with `reportPrivateUsage`. Anthropic worker tests refactored to import the shared helpers; all 24 tests pass.
-- **2026-05-14 — Bedrock decision.** `pipelex/plugins/bedrock/bedrock_llm_worker.py::_gen_object` raises `LLMCapabilityError` and does not use instructor (the file's only `instructor` mention is a `# TODO` comment). No `Phase 8.5` will be created. Bedrock still gets upgrades A–C in Phase 11.
-- **2026-05-14 — Phase 1 landed.** `extract_underlying_sdk_exception` lives in `pipelex/cogt/inference/error_classification.py`. Anthropic worker imports from the shared module. The defensive try/except around `failed_attempts[-1]` swallows `TypeError`/`KeyError`/`IndexError` to keep the helper safe against malformed input (the tests cover a string-as-failed_attempts case). Defending only against typing/lookup exceptions (not generic Exception) keeps real bugs visible.
-- **2026-05-14 — Phase 2 landed.** `InferenceErrorCategory.UNKNOWN` lives in `pipelex/cogt/exceptions.py` (NOT `error_classification.py` — TODOS.md text was off). Value is lowercase `"unknown"` to match other members. `is_retryable=False`. Anthropic worker's `InstructorRetryException` fallback uses UNKNOWN. Other workers still use whatever they had — they get migrated in their own phases.
-- **2026-05-14 — Phase 4 landed.** `UserActionKind` (StrEnum) and `UserAction` (BaseModel) live in `pipelex/cogt/inference/error_classification.py`. Decisions:
- - **Field type changed on the base `CogtError`** (not per-leaf), keeping subclasses uniform — same approach as `provider_metadata` in Phase 3.
- - **JSON shape change.** `report_dict["user_action"]` is now a nested `{"kind": "...", "detail": "..."}` object instead of a free string. `Pydantic v2` `TypeAdapter.dump_python(... mode="python")` recursively serializes nested `BaseModel` fields inside the `ErrorReport` Pydantic dataclass, so no extra plumbing was needed in `to_error_report()`.
- - **CLI consumers updated.** `pipelex/cli/error_handlers.py` and `pipelex/cli/agent_cli/commands/agent_output.py` read `report.user_action.detail` (with `None`-guard) instead of treating the field as a string. Tests in `tests/unit/pipelex/cogt/test_exceptions.py` and `tests/unit/pipelex/cli/test_agent_output.py` were migrated to construct `UserAction(...)` explicitly. Worker tests that previously did `exc_info.value.user_action.lower()` now do `exc_info.value.user_action.detail.lower()`.
- - **Anthropic worker semantic kinds.** The Anthropic reference worker (and `AnthropicCredentialsError`'s class-level default, plus `InferenceBackendCredentialsError`'s class-level default) use semantic `UserActionKind` values. Every other worker (OpenAI Completions/Responses, OpenAI img-gen, OpenAI completions img-gen, Google LLM/img-gen, Mistral LLM/extract, Bedrock LLM, Linkup extract/search, Azure img-gen, FAL img-gen, HuggingFace img-gen) carries `kind=UNKNOWN` as a placeholder for now. Per-worker phases will refine those.
-- **2026-05-14 — Phase 5 landed.** OpenAI Completions LLM brought up to the beyond-reference standard.
- - **`extract_openai_metadata` shape.** OpenAI's `_make_status_error` (in `_client.py`) pre-unwraps `body["error"]` so `body["type"]` / `body["code"]` sit at the top level — and the SDK already mirrors those onto `exc.type` / `exc.code`. So `extract_openai_metadata` reads `provider_error_code` from `getattr(exc, "type", None) or getattr(exc, "code", None)` rather than re-parsing the body. `request_id` comes from `exc.request_id` which `APIStatusError.__init__` sets from `response.headers["x-request-id"]`. Factored that out into a shared `_request_id_from_exc_or_response` helper that works for both Anthropic (which exposes `exc.request_id` directly) and OpenAI.
- - **Helper method pattern.** Mirrored the Anthropic worker: introduced `_raise_categorized_openai_sdk_error(sdk_exc, chain_from=None)` so both `_gen_text` and `_gen_object` dispatch through the same place. Removed the nested try in `_gen_object` — there is now a single try with two except clauses (`InstructorRetryException` then the SDK tuple).
- - **SDK coverage expanded.** Added `InternalServerError` (5xx → TRANSIENT + WAIT_AND_RETRY) and `PermissionDeniedError` (403 → CONFIGURATION + CHECK_CREDENTIALS) to the tuple-catch, neither of which was previously caught. `ConflictError` (409) and `UnprocessableEntityError` (422) are not raised on the chat-completion path in practice; if telemetry surfaces them later they fall through to the wrapped-path `UNKNOWN` branch and can be added.
- - **Semantic UserActionKind values:** rate-limit→WAIT_AND_RETRY, quota→CHECK_BILLING, timeout/connection/server→WAIT_AND_RETRY, not-found→CHANGE_MODEL, bad-request (content-policy or generic)→CHANGE_INPUT, auth/permission-denied→CHECK_CREDENTIALS.
- - **`instructor.exceptions` → `instructor.core`** import migration done in this worker.
- - **Tests.** New: `test_extract_openai_metadata.py` (10 tests) and `test_openai_completions_worker_object_error_handling.py` (10 tests including a real-instructor end-to-end). Existing `test_openai_worker_error_handling.py` still passes — the `_gen_text` refactor preserved the user-visible behavior for the cases it covered.
-- **2026-05-14 — Phase 6 landed.** OpenAI Responses LLM brought up to the beyond-reference standard.
- - **Worker-local helper, not shared with Completions.** The categorization helper is a method on `OpenAIResponsesLLMWorker` (not a shared free function with Completions) because Responses specializes `NotFoundError` into `LLMModelNotFoundError` (so callers can swap models), while Completions raises `LLMCompletionError`. The branch shape and SDK coverage are otherwise identical to Phase 5. Mirroring the helper instead of sharing avoids leaking worker-specific concerns (`inference_model.name` for `model_handle`) into a shared helper signature.
- - **`ModelNotFoundError.__init__` extended.** To carry `provider_metadata` and a semantic `user_action` on `LLMModelNotFoundError`, the parent `ModelNotFoundError.__init__` in `pipelex/cogt/exceptions.py` now accepts and forwards `error_category`, `user_action`, and `provider_metadata` kwargs to `CogtError.__init__`. `ModelWaterfallError` continues to construct correctly: it forwards only `message` and `model_handle`, and the new kwargs default to `None` so the class-level `error_category = InferenceErrorCategory.CONFIGURATION` default kicks in.
- - **Real-instructor end-to-end test uses `instructor.Mode.RESPONSES_TOOLS`.** instructor's Responses path (`AsyncResponse.create_with_completion`) is only attached on the `AsyncInstructor` when mode is `RESPONSES_TOOLS` or `RESPONSES_TOOLS_WITH_INBUILT_TOOLS`. The underlying call goes through `async_map_chat_completion_to_response → client.responses.create`, so the test patches `openai_client.responses.create` (not `.chat.completions.create` like Phase 5's test).
- - **SDK exception coverage now uniform with Phase 5.** Added `InternalServerError` (5xx → TRANSIENT + WAIT_AND_RETRY) and `PermissionDeniedError` (403 → CONFIGURATION + CHECK_CREDENTIALS) to the tuple-catch — both were previously missing. `ConflictError` / `UnprocessableEntityError` are not raised on the responses path in practice and fall through to the wrapped-path `UNKNOWN` branch.
- - **Semantic UserActionKind values:** rate-limit→WAIT_AND_RETRY, quota→CHECK_BILLING, timeout/connection/server→WAIT_AND_RETRY, not-found→CHANGE_MODEL (on `LLMModelNotFoundError`), bad-request (content-policy or generic)→CHANGE_INPUT, auth/permission-denied→CHECK_CREDENTIALS.
- - **Tests.** New: `test_openai_responses_worker_object_error_handling.py` (10 tests including a real-instructor end-to-end). Existing `test_openai_worker_error_handling.py` (which tests the `_gen_text` Responses path through `responses.create`) still passes — the `_gen_text` refactor preserved the user-visible behavior for the categories it covered.
-- **2026-05-14 — Phase 7 landed.** Mistral LLM brought up to the beyond-reference standard.
- - **`extract_mistral_metadata` body parsing.** Unlike OpenAI/Anthropic — whose SDKs deliver `body` as a pre-parsed dict — Mistral's SDK sets `MistralError.body` to the raw response *text string* (from `httpx.Response.text`). The helper JSON-parses it on a best-effort basis and stores the parsed dict back on `ProviderErrorMetadata.body` so downstream consumers see a uniform shape. Non-JSON bodies (HTML error pages from upstream gateways during 502/504s) are tolerated: `provider_error_code` stays `None` and `body` keeps the raw string.
- - **Two body shapes.** Mistral returns the flat shape `{"message": ..., "type": ..., "code": ...}` on most endpoints, but some endpoints wrap it as `{"error": {...}}`. Added a small `_provider_error_code_from_flat_body` helper and fall back to the existing nested-shape helper to cover both. The OR-chain (`flat or nested`) means whichever shape Mistral uses, we extract the code.
- - **No separate timeout/connection classes.** Mistral has only `MistralError` (HTTP errors with a `status_code`) and `NoResponseError` (a sibling `Exception` for true no-response failures — network-level). The current worker tuple-catch on `MistralError` does not catch `NoResponseError`, so it propagates up to the tenacity retry layer. Acceptable today; documented in the audit notes inside Phase 7. If telemetry surfaces it later, add a dedicated branch in `_gen_text`/`_gen_object` similar to OpenAI's `APIConnectionError`/`APITimeoutError`.
- - **Dead `except LLMCompletionError` clause removed.** The prior `_gen_object` had an `except LLMCompletionError: raise` clause between the SDK catch and the `InstructorRetryException` catch. Nothing on the call path raised `LLMCompletionError` from inside the try, so the clause was dead. Removing it lets pyright/mypy see the unwrap path more cleanly.
- - **Fallback path now routes to UNKNOWN.** Previously the unwrapped-instructor fallback used `error_category=CONTENT`, which silently mis-categorized non-Mistral underlying exceptions. Per Phase 2 convention, it now routes to `UNKNOWN` with `provider_metadata=None`.
- - **Semantic UserActionKind values:** rate-limit→WAIT_AND_RETRY, quota (402 or 429+keywords)→CHECK_BILLING, 401/403→CHECK_CREDENTIALS, 404→CHANGE_MODEL, content-policy→CHANGE_INPUT, generic bad-request→CHANGE_INPUT, 5xx→WAIT_AND_RETRY, fallback→WAIT_AND_RETRY. Previously the 401/403/404 paths and the fallback path lacked a `user_action` entirely; they now carry one so downstream consumers see a uniform shape.
- - **Tests.** New: `test_extract_mistral_metadata.py` (10 tests) and `test_mistral_llm_worker_object_error_handling.py` (10 tests including a real-instructor end-to-end). Existing `test_mistral_worker_error_handling.py` (the direct `_gen_text` path) still passes — the `_classify_mistral_error` refactor preserved the categorization output for every case it covered.
-- **2026-05-14 — Phase 8 landed.** Google Gemini LLM brought up to the beyond-reference standard.
- - **`extract_google_metadata` field shape.** Google's SDK differs from OpenAI/Anthropic on three points: (1) HTTP status lives on `exc.code` (not `exc.status_code`); (2) the response body lives on `exc.details` (the raw JSON dict the API returned, *not* `exc.body`); (3) the symbolic error code is a textual `status` field like `RESOURCE_EXHAUSTED`, `UNAUTHENTICATED`, `PERMISSION_DENIED` — read from `details["error"]["status"]` with a top-level `details["status"]` fallback for endpoints that flatten the payload. Added `_google_provider_error_code_from_details` helper to handle both shapes. `request_id` reads `x-goog-request-id` first (Google-specific) and falls back to `x-request-id` for older endpoints. `response` may be `None` (the SDK constructor accepts it), so the helper degrades gracefully — every header-derived field becomes `None`.
- - **Helper method + ServerError specialization.** Introduced `_raise_categorized_google_sdk_error(sdk_exc, chain_from)` so both `_gen_text` and `_gen_object` dispatch through one place. `ServerError` is handled directly in the helper (TRANSIENT + WAIT_AND_RETRY) without going through the 4xx-discriminator in `_classify_google_client_error` — same shape as Phase 8's plan called for.
- - **Fallback path now routes to UNKNOWN.** Previously `_gen_object`'s `InstructorRetryException` clause raised `LLMCompletionError` with `error_category=CONTENT`, which silently mis-categorized any non-Google underlying exception. Per Phase 2 convention, it now routes to `UNKNOWN` with `provider_metadata=None`.
- - **Real-instructor test required a real `Content` object.** instructor's gemini message converter (`instructor/providers/gemini/utils.py:565`) rejects a bare `list` as a message: it expects each message to be a dict or a `genai_types.Content`. The Google worker wraps `prepare_user_contents`'s return value as `messages=[contents]`, so when the mock returned `[]` we ended up with `messages=[[]]` which crashes the converter. The real-instructor test now injects a `genai_types.Content(role="user", parts=[Part.from_text(text="hi")])` so instructor reaches the SDK call (which we patched to raise `ClientError`). The other 9 tests in the suite use a synthetic `wrap_in_instructor_retry(sdk_exc)` that side-effects the instructor client mock directly, so they never go through the converter.
- - **Semantic UserActionKind values:** 404→CHANGE_MODEL, 401/403→CHECK_CREDENTIALS, 429+quota→CHECK_BILLING, 429+generic→WAIT_AND_RETRY, 400+content-policy→CHANGE_INPUT, 400+generic→CHANGE_INPUT, 4xx fallback→WAIT_AND_RETRY, 5xx (ServerError)→WAIT_AND_RETRY. Previously the 404/401/403/generic-400/fallback paths lacked a `user_action`; they now carry one so downstream consumers see a uniform shape.
- - **Img-gen worker untouched.** `pipelex/plugins/google/google_img_gen_worker.py` has its own `_classify_google_client_error` copy with the same shape. It is in scope for Phase 10 (img-gen audits), not Phase 8 — left as-is for now.
- - **SDK hierarchy audited.** `genai_errors.{APIError, ClientError, ServerError}` are the HTTP error classes; `UnknownFunctionCallArgumentError`, `UnsupportedFunctionError`, `FunctionInvocationError`, `UnknownApiResponseError` are tool-calling / parsing failures that subclass `ValueError`, *not* `APIError`. They fall through tuple-catch and route to wrapped-path `UNKNOWN`. Google's SDK doesn't have separate timeout/connection classes the way OpenAI/Anthropic do — network failures propagate as the underlying `httpx`/`requests` exceptions.
- - **Tests.** New: `test_extract_google_metadata.py` (10 tests) and `test_google_llm_worker_object_error_handling.py` (10 tests, including a real-instructor end-to-end). Existing `test_google_worker_error_handling.py` (direct `_gen_text` path through `ClientError`/`ServerError`) still passes — the `_classify_google_client_error` refactor preserved every case it covered, and the newly-populated `user_action.detail` fields are no-ops where the test asserted `expected_action_substring is None`.
-- **2026-05-14 — Phase 10 landed.** Img-gen worker audits complete. Beyond-reference upgrades A–C delivered across all seven img-gen workers (OpenAI, OpenAI Completions, Google, Azure, FAL, HuggingFace, Gateway). Decisions:
- - **Path correction.** TODOS.md text said `pipelex/plugins/azure/azure_img_gen_worker.py` but the actual path is `pipelex/plugins/azure_rest/azure_img_gen_worker.py`. No `azure` plugin directory exists; updated test paths to `tests/unit/pipelex/plugins/azure_rest/`.
- - **New `extract_*_metadata` helpers.** Four new helpers added: `extract_azure_metadata`, `extract_fal_metadata`, `extract_huggingface_metadata`, `extract_gateway_metadata`. Each handles the SDK's specific exception shape (Azure: raw httpx exceptions on a REST API; FAL: `FalClientHTTPError` with `response_headers` dict and `error_type` attribute; HuggingFace: `HfHubHTTPError` wraps `requests.Response` not `httpx.Response` and mirrors `request_id` onto the exception; Gateway: Portkey SDK mirrors OpenAI shape so the helper is straightforward).
- - **Specialization decision: 404 → `ImgGenModelNotFoundError` only on OpenAI workers.** The original Google/Azure/FAL/HF img-gen workers raised `ImgGenGenerationError(error_category=CONFIGURATION)` for 404, not `ImgGenModelNotFoundError`. To preserve existing test contracts and behavior parity with the LLM-side Google worker (which also uses `LLMCompletionError` not `LLMModelNotFoundError` for 404), kept that behavior for Google/Azure/FAL/HF. Only the OpenAI workers (which originally raised `ImgGenModelNotFoundError`) preserve that specialization. All workers now carry `UserActionKind.CHANGE_MODEL` on the 404 path regardless of which exception class fires.
- - **Gateway helper-class pattern.** Added two new `GatewayFactory` classmethods (`make_user_action_from_portkey_error`, `make_provider_metadata_from_portkey_error`) rather than inlining a helper inside the worker, so that `gateway_extract_worker.py` and `gateway_search_worker.py` can adopt the same path in Phase 11/12 without duplicating the dispatch logic.
- - **No UNKNOWN-category fallback added to img-gen workers.** Unlike the LLM workers (which have an `InstructorRetryException` wrapped path that can carry a non-recognized underlying), img-gen workers all use a direct tuple-catch on the SDK exception types. Anything that falls outside the tuple-catch propagates as-is (acceptable behavior — the tenacity retry layer above absorbs them). No new UNKNOWN code paths needed in this phase.
- - **Pyright `dict[Unknown, Unknown] | Any | None` corner.** `extract_gateway_metadata` narrows `body` inside an `isinstance(body, dict)` block, then passes `body` back to `ProviderErrorMetadata(body=...)`. Pyright widens to `dict[Unknown, Unknown] | Any | None` at the call site (the narrowing partially "leaks"). Worked around by aliasing the narrowed variable and `cast("Any", raw_body)` at the call site. This is a known pyright pattern; the other `extract_*` helpers don't trigger it because they don't narrow body via isinstance in the same block.
- - **Tests.** New test files: `test_openai_img_gen_worker_error_handling.py`, `test_openai_completions_img_gen_worker_error_handling.py`, `test_google_img_gen_worker_error_handling.py`, `test_extract_azure_metadata.py`, `test_azure_img_gen_worker_error_handling.py`, `test_extract_fal_metadata.py`, `test_fal_img_gen_worker_semantic.py`, `test_extract_huggingface_metadata.py`, `test_huggingface_img_gen_worker_semantic.py`, `test_extract_gateway_metadata.py`, `test_gateway_img_gen_worker_semantic.py`. Existing tests (`test_google_worker_error_handling.py`, `test_azure_worker_error_handling.py`, `test_fal_worker_error_handling.py`, `test_hf_worker_error_handling.py`) all still pass — the new tests are additive (asserting metadata + user_action.kind) rather than replacing existing categorization checks.
-
-- **2026-05-14 — Phase 3 landed.** `ProviderErrorMetadata` + `extract_anthropic_metadata` live in `pipelex/cogt/inference/error_classification.py`. Decisions:
- - **Field placement.** `provider_metadata` was added to `CogtError` (not the four leaf classes the plan named). The uniform base-class field keeps every subclass's `__init__` consistent and lets `to_error_report()` serialize it generically. Non-SDK CogtError subclasses just leave it `None` — same cost as Optional fields on the four leaves, simpler code.
- - **`AnthropicCredentialsError` carries metadata too** because we now have the metadata at the raise site and dropping it would lose auth-error telemetry (status_code 401, request_id).
- - **Forward reference resolution.** `ErrorReport` (Pydantic dataclass in `base_exceptions.py`) takes `ProviderErrorMetadata` as a string-forward-ref. To avoid making `base_exceptions` depend on `cogt/`, `cogt/exceptions.py` does the import and calls `rebuild_dataclass(cast("Any", ErrorReport), _types_namespace=...)`. The cast is needed because pyright doesn't recognize Pydantic dataclasses through its `PydanticDataclass` protocol. `arbitrary_types_allowed=True` is set on the dataclass config because `ProviderErrorMetadata` is a `BaseModel` (not a dataclass), which Pydantic v2 dataclasses don't accept by default.
- - **Body type handling.** `extract_anthropic_metadata` reads `exc.body` (Any) and `exc.response.headers["retry-after"]`. `_provider_error_code_from_body` casts the body to `dict[str, Any]` to silence `reportUnknownMemberType` on `.get()`. The fallback chain is `error.type` then `error.code` — Anthropic uses `type`, but other providers (when this helper pattern is replicated) commonly use `code`, so we accept both for future reuse.
-
-- **2026-05-14 — Phase 11 landed.** Extract worker audits complete. Beyond-reference upgrades A–C delivered across Bedrock LLM (only LLM-side worker remaining), Mistral extract, Docling extract, Linkup extract, Gateway extract, pypdfium2. Decisions:
- - **`extract_bedrock_metadata` shape.** botocore's `ClientError` carries `response: dict` shaped `{"Error": {"Code": ..., "Message": ...}, "ResponseMetadata": {"RequestId": ..., "HTTPStatusCode": ..., "HTTPHeaders": {...}}}`. Status comes from `ResponseMetadata.HTTPStatusCode` (note: capital H — not `status_code`), request id from `ResponseMetadata.RequestId`, retry-after from `HTTPHeaders.retry-after`, provider_error_code from `Error.Code` (e.g. `ThrottlingException`). The full `response` dict is kept as `body` so downstream consumers don't need to re-scrape `str(exc)`. Tolerates malformed exceptions (no `response` attr) — every status-related field comes back as `None`.
- - **`extract_linkup_metadata` minimal shape.** The Linkup Python SDK raises typed exceptions (`LinkupAuthenticationError`, `LinkupTooManyRequestsError`, `LinkupInvalidRequestError` …) but does *not* expose `response`, `status_code`, `request_id`, or `retry-after` headers. The exception class name is the canonical signal — surfaced as both `sdk_exception_type` and `provider_error_code` so downstream consumers can branch without importing the Linkup SDK at the call site.
- - **`extract_local_extract_metadata(exc, provider=...)`** is a single shared helper for local (non-HTTP) extractors. Docling and pypdfium2 both reuse it; the per-call `provider` argument keeps the provider name on the metadata even though the helper is generic. Local extractors raise generic Python exceptions (`FileNotFoundError`, `ValueError`, `RuntimeError`, `OSError`) — the underlying exception class name is the only meaningful signal, so both `sdk_exception_type` and `provider_error_code` carry it.
- - **Bedrock 404 branch added.** The pre-existing `_gen_text` had ThrottlingException, ServiceQuotaExceededException, AccessDeniedException, ValidationException, ModelNotReadyException / ServiceUnavailableException, and a TRANSIENT fallback — but no explicit `ResourceNotFoundException` (404) branch. Added one that routes to CONFIGURATION + CHANGE_MODEL, mirroring the LLM-side pattern for `LLMModelNotFoundError`-ish semantics. The fallback path now routes to WAIT_AND_RETRY (was bare CONFIGURATION → no user_action).
- - **Mistral extract worker: dropped placeholder `UserAction(kind=UNKNOWN)`.** The pre-existing worker had `kind=UserActionKind.UNKNOWN` placeholders on 3 of 7 branches and no `user_action` at all on the other 4 (401/403, 404, generic 400, 500, fallback). Now every branch carries a semantic `kind` — uniform with the LLM worker.
- - **Linkup search worker NOT migrated in this phase.** The search worker (`linkup_search_worker.py`) has its own near-identical `_classify_linkup_error` method with UNKNOWN placeholders. Phase 12 will migrate it; for now the extract and search workers temporarily have *different* user-action kinds for the same SDK exceptions. This is intentional — Phase 11 is "extract only" by design.
- - **Gateway extract worker: tenacity retry boundary preserved.** The worker wraps Portkey calls in `AsyncRetrying(reraise=True, stop=stop_after_attempt(N))`. When all retries are exhausted, the last `APIError` is reraised verbatim into our `except portkey_exceptions.APIError as exc:` block — categorization signal and request_id are preserved across the retry boundary. Confirmed by inspection; no behavior change needed.
- - **Pyright body-dict cast pattern.** When tests assert against `metadata.body["Error"]["Code"]`, pyright narrows `metadata.body` (typed `Any | None`) to `dict[Unknown, Unknown]` through `isinstance(..., dict)`, which trips `reportUnknownMemberType`. The fix that works across providers is `body: Any = metadata.body; assert isinstance(body, dict); assert body["Error"]["Code"] == ...` — the explicit `Any` annotation keeps pyright from re-narrowing the indexed access.
- - **Tests.** New test files: `test_extract_bedrock_metadata.py` (8 tests), `test_bedrock_worker_semantic.py` (9 cases), `test_mistral_extract_worker_semantic.py` (10 cases), `test_docling_worker_semantic.py` (4 cases), `test_linkup_extract_worker_semantic.py` (10 cases including all 10 Linkup SDK exception types), `test_gateway_extract_worker_semantic.py` (5 cases), `test_pypdfium2_worker_semantic.py` (4 cases). All existing tests (`test_bedrock_worker_error_handling.py`, `test_mistral_worker_error_handling.py`, `test_docling_worker_error_handling.py`, `test_linkup_worker_error_handling.py`, `test_pypdfium2_worker_error_handling.py`, `test_gateway_*`) keep passing — the new tests are additive (asserting metadata + user_action.kind) rather than replacing existing categorization checks. Final sweep: `make agent-check` (0 errors) + 1122 plugins/cogt unit tests pass.
-
-- **2026-05-15 — Phase 13 landed. Sweep DONE.** Final integration check complete. Decisions:
- - **Response-shape bare raises migrated.** The uniformity check surfaced that Phases 10–12 only migrated *SDK-error* raises — the *response-shape validation* bare raises (`raise XError(msg)` after a successful HTTP call when the payload is empty/malformed) were left untouched in the img-gen / extract / gateway-search workers. Phase 9 had explicitly cleaned these up for the LLM workers; Phases 10–12 had no equivalent step. Migrated every one of them to mirror Phase 9: `openai_img_gen` (5), `google_img_gen` (4), `azure_img_gen` (5), `gateway_img_gen` (13), `openai_completions_img_gen` (3), `fal_factory` (3), `gateway_extract` (2), `gateway_search` (3).
- - **Category policy for response-shape failures.** Three buckets, each with `provider_metadata=None` (non-SDK paths — no provider error code, status, or request id to extract): (a) "the model produced no usable image/output" (empty data, no candidates, no image bytes) → `error_category=CONTENT` + `UserActionKind.CHANGE_INPUT`, detail leads with "try rephrasing the prompt" — mirrors Phase 9's LLM treatment of "empty choices" / "content is None"; (b) "the provider returned a malformed/unexpected response shape" (missing output format, malformed size, missing url/width/height/content-type, unparseable payload) → `error_category=UNKNOWN` + `UserActionKind.CHANGE_MODEL` — rephrasing the prompt cannot fix a malformed response, so the actionable recourse is a different model; (c) "the provider returned no response at all" (`response is None` after retries exhausted) → `error_category=UNKNOWN` + `UserActionKind.CONTACT_SUPPORT`. The bucket-(b) split was a self-review correction: the first pass had used `CHANGE_INPUT` with detail text recommending a different model — a kind/detail mismatch — across ~21 sites; the kind, category, and detail now agree.
- - **No tests broke.** No existing test asserted on these response-shape error messages or their (previously absent) `error_category`, so the migration is purely additive. `gateway_img_gen` / `gateway_extract` / `gateway_search` / `fal_factory` needed `InferenceErrorCategory` + `UserAction` + `UserActionKind` added to their imports.
- - **`except Exception` audit.** The matches in `pipelex/plugins/` are all pre-existing best-effort `teardown()` async-client cleanup blocks (documented "log but don't fail teardown"), not error-classification paths — left as-is.
- - **Verification.** `make agent-check` clean (0 errors, 0 warnings); `make agent-test` clean. Extract/Classify/Render track prerequisites all confirmed satisfied — that track is ready to start.
-
-- **2026-05-15 — Phase 12 landed.** Search worker audits complete. Beyond-reference upgrades A–C delivered across both search workers (Linkup, Gateway). Decisions:
- - **No new helpers needed.** Linkup search reuses `extract_linkup_metadata` (added Phase 11); Gateway search reuses `extract_gateway_metadata` + `GatewayFactory.make_user_action_from_portkey_error` (added Phase 10). Phases 10/11 explicitly pre-positioned these so Phase 12 is a pure adoption phase.
- - **Linkup search `_classify_linkup_error` mirrors the extract worker.** The search worker only catches the seven search-relevant Linkup exceptions (`LinkupAuthenticationError`, `LinkupInsufficientCreditError`, `LinkupTooManyRequestsError`, `LinkupTimeoutError`, `LinkupInvalidRequestError`, `LinkupNoResultError`, `LinkupUnknownError`) — not the three fetch-specific ones (`LinkupFetchResponseTooLargeError`, `LinkupFetchUrlIsFileError`, `LinkupFailedFetchError`) that only the extract worker handles. So the search `_classify_linkup_error` has no fetch-too-large branch; otherwise it is shape-identical to extract. `LinkupNoResultError`/`LinkupUnknownError` route through the TRANSIENT + WAIT_AND_RETRY fallback. Error message strings kept identical to the prior implementation so the existing `test_linkup_worker_error_handling.py` substring assertions still pass.
- - **Gateway search retry boundary preserved.** `_call_relay` wraps the Portkey call in `AsyncRetrying(reraise=True, stop=stop_after_attempt(N))`. When retries are exhausted the last `APIError` is reraised verbatim into `except portkey_exceptions.APIError as exc:`, so `extract_gateway_metadata(exc)` sees the original response/headers and `request_id` survives — same finding as the Phase 11 Gateway extract worker.
- - **Tests.** New: `test_linkup_search_worker_semantic.py` (7 cases) and `test_gateway_search_worker_semantic.py` (5 cases), both mirroring the Phase 11 extract semantic suites. Existing `test_linkup_worker_error_handling.py` (which covers both extract and search workers) still passes. `make agent-check` clean (0 errors, 0 warnings); `make agent-test` clean.
diff --git a/wip/error-handling/changes-for-api-early-draft.md b/wip/error-handling/changes-for-api-early-draft.md
deleted file mode 100644
index d227e296f..000000000
--- a/wip/error-handling/changes-for-api-early-draft.md
+++ /dev/null
@@ -1,336 +0,0 @@
-# Pipelex changes — companion work for the API error-handling refactor
-
-> **Superseded — historical draft.** This is the original early-draft spec. The authoritative companion doc is [`api-companion-revisions.md`](api-companion-revisions.md), which records what actually shipped and the deviations taken. Kept for context only — do not treat it as the contract.
-
-Changes to the **pipelex** library to land in parallel with (and largely before) the `pipelex-api` error-handling refactor. The goal is to expose the right primitives upstream so the API consumes them cleanly instead of duplicating logic, working around missing fields, or stalling Phase 4.
-
-This is **not a follow-up list.** It is the pipelex-side workplan for the same integration. Done well, the API plan in [../../TODOS.md](../../TODOS.md) reads as straight consumer code with no compensating logic. Done poorly, the API plan accumulates small workarounds that the next consumer (CLI, agent CLI, future SDK) will have to either re-write or refactor away.
-
-Each item names a concrete API surface in pipelex, the downstream pain it removes, and a landing stage. File-path references with `pipelex/` are pipelex; with `api/` are this repo.
-
-The list is intentionally specific. "Pipelex should be better at errors" is not actionable. "`ErrorReport.to_strict_dict()` returns a dict with `CONFIG`/`RUNTIME` domain fields redacted per a fixed rule" is.
-
----
-
-## Landing stages
-
-Stages map to **dependencies on the `pipelex-api` plan**, not effort. An item in Stage 2 takes the same engineering time as one in Stage 1 — it just has fewer downstream consumers waiting on it.
-
-- **Stage 1 — Foundations (lands before pipelex-api Phase 0).** Class-level metadata on `PipelexError` subclasses. The API consumes these on day one of Phase 0 instead of building a humanize-from-classname fallback.
-- **Stage 2 — Rendering primitives (lands before pipelex-api Phase 1).** `ErrorReport` gains methods that turn the structured report into presentational shapes. The API consumes them in its problem-document builder.
-- **Stage 3 — Async error pipe (lands before pipelex-api Phase 4).** `DeliveryExecutor` carries the failure report through to the webhook. The async path becomes lossless.
-- **Stage 4 — DX polish (lands alongside pipelex-api Phase 5).** Per-class docs anchors and the optional rendering escape hatch.
-- **Stage 5 — Future-facing (lands when needed, not blocking).** Sync status-query primitive — designed now so the future `GET /api/v1/pipeline/{run_id}` endpoint has somewhere clean to land.
-- **Stage 6 — Security tightening (independent track, do soon).** Webhook signature scope. Pre-existing weakness made more visible by carrying richer payloads.
-
----
-
-## Stage 1 — Foundations
-
-### 1. `PipelexError.title: ClassVar[str | None]`
-
-**Where:** `pipelex/base_exceptions.py:114` (the `PipelexError` base class).
-
-**What.** Let `PipelexError` subclasses declare a short human title via a class attribute. Defaults to `None`, in which case downstream consumers fall back to humanizing the class name.
-
-```python
-class PipelexError(Exception):
- error_domain: ClassVar[ErrorDomain | None] = None
- user_action: ClassVar[UserAction | None] = None
- title: ClassVar[str | None] = None # NEW
-
-class EnvVarNotFoundError(PipelexError):
- error_domain = ErrorDomain.CONFIG
- title = "Environment variable not set"
-
-class LLMCompletionError(CogtError):
- title = "LLM provider returned an error"
-```
-
-`PipelexError.to_error_report()` sets `report.title = type(self).title` when defined.
-
-`ErrorReport` carries it as a new optional field:
-
-```python
-@dataclass(frozen=True, ...)
-class ErrorReport:
- error_type: str
- message: str
- title: str | None = None # NEW
- ...
-```
-
-**Why.** RFC 7807 §3.1.4 says `title` should be a "short, human-readable summary of the problem type" that is "the same for occurrences of the problem." The API uses `title` directly in the RFC 7807 envelope. Today the API would auto-derive from the class name (`EnvVarNotFoundError` → `"Env Var Not Found Error"`) — stable but awkward copy. Curating titles API-side creates drift when pipelex adds new error classes. Curating them where the class is defined removes the drift entirely.
-
-**Surfaced by.** `pipelex-api` Phase 0 review amendment A4.
-
----
-
-### 2. `PipelexError.type_uri: ClassVar[str | None]`
-
-**Where:** `pipelex/base_exceptions.py:114` (same place as item 1).
-
-**What.** Let `PipelexError` subclasses optionally declare their RFC 7807 `type` URI. Default to `None` → downstream consumers auto-derive `<base>/<kebab-case classname>` from a pipelex-config-provided base URI (default: `https://pipelex.dev/errors/`).
-
-```python
-class PipelexError(Exception):
- type_uri: ClassVar[str | None] = None
-
-class EnvVarNotFoundError(PipelexError):
- type_uri = "https://pipelex.dev/errors/env-var-not-found"
-```
-
-**Why.** The API today would hardcode `https://pipelex.dev/errors/` as the namespace in `api/error_uri.py`. If pipelex ever moves the docs anchor (renamed domain, restructured docs site, per-class custom anchors), the API has to be updated in lockstep. Owning the URI on the class itself keeps the public-facing identifier and the class definition together, where they belong.
-
-**Surfaced by.** `pipelex-api` Phase 0 design + amendment A4.
-
----
-
-### 3. First-class `request_id` on workflow input
-
-**Where:** `pipelex/pipeline/pipeline_run_setup.py` (where `pipeline_run_id` is established) and the workflow argument shape consumed by `pipelex/temporal/tprl_pipe/temporal_pipe_run.py:make_temporal_pipe_run`.
-
-**What.** Add a `request_id: str | None` field to whatever pipelex passes as the workflow/activity argument. The worker initializes its logger context from it. Pipelex consumers that drive Temporal (the API, the CLI when it runs async, future SDKs) pass an opaque correlation id; consumers that don't care pass `None`.
-
-```python
-@dataclass
-class PipeJob:
- ...
- request_id: str | None = None # NEW — caller-supplied correlation id
-```
-
-Worker-side, the logger picks it up at activity entry so every log line emitted during the workflow carries it.
-
-**Why.** The API generates an `X-Request-ID` per inbound HTTP request (Phase 0 of the API plan). For sync `/pipeline/execute`, the request id correlates the API log, pipelex internal logs, and worker logs because they run in the same process. For async `/pipeline/start`, the workflow runs on a different process — without first-class plumbing through Temporal, worker logs are correlated only by `pipeline_run_id`.
-
-Today's workaround (currently in API Phase 4b) is to piggyback on `webhook.payload["request_id"]` — the free-form extras dict on `WebhookTarget` (`pipelex/pipe_run/delivery_assignment.py:16`). That works for the webhook *delivery* log line, but does nothing for the activity's own logs *between* dispatch and delivery — exactly the place operators most need correlation when something goes wrong mid-run.
-
-**Surfaced by.** `track-observability.md` "Request correlation" section.
-
----
-
-## Stage 2 — Rendering primitives
-
-### 4. `ErrorReport.to_strict_dict()` — disclosure-mode redaction upstream
-
-**Where:** `pipelex/base_exceptions.py:71` (next to `ErrorReport.to_dict()`).
-
-**What.** Add a method (or parameterize `to_dict`) that returns the redacted form for restricted disclosure contexts:
-
-```python
-class DisclosureMode(StrEnum):
- VERBOSE = "verbose"
- STRICT = "strict"
-
-@dataclass(frozen=True, ...)
-class ErrorReport:
- ...
- def to_strict_dict(self) -> dict[str, Any]:
- """Like to_dict() but with CONFIG/RUNTIME disclosure redacted.
-
- INPUT-domain errors: returned unchanged. The caller can fix them.
- CONFIG/RUNTIME-domain errors: `message` replaced with a fixed
- string; `user_action`, `provider`, `model`, `provider_metadata`
- dropped; `error_category`, `retryable`, `error_type`, `error_domain`
- retained so consumers can still classify.
- """
- ...
-```
-
-**Why.** The architecture doc states **"Don't redefine the mapping"** ([architecture.md](architecture.md) cross-cutting principles). Strict-mode redaction IS the kind of presentational logic that should live where the error model lives — for the same reason `http_status` is on `ErrorReport` and `error_domain_to_http_status` is in pipelex.
-
-Today only the API has a need for this (hosted multi-tenant deployments set `ERROR_DISCLOSURE=strict`). But the moment a second consumer wants the same — the human CLI gains a `--share-error` mode that sanitizes before clipboard, the agent CLI emits errors to a chat surface that may leak, a hosted SDK redacts before forwarding to a user-facing app — the logic gets duplicated, and the two copies will drift.
-
-Owning the rule in pipelex means every consumer gets the same redaction behavior automatically.
-
-**Surfaced by.** `track-response-schema.md` "strict mode, in detail" section + API Phase 1 review note.
-
----
-
-## Stage 3 — Async error pipe
-
-### 5. `DeliveryExecutor.execute(...)` accepts an `error_report` parameter
-
-**Where:** `pipelex/pipe_run/delivery_executor.py:38-54` (the `execute` method) and `pipelex/pipe_run/delivery_executor.py:238-267` (`_notify_webhook`).
-
-**What.** Extend `DeliveryExecutor.execute(...)` to accept an optional `error_report: ErrorReport | None = None`. When `status == FAILED` and `error_report is not None`, include `error: <error_report.to_dict()>` in the webhook payload. Existing callers passing `None` see unchanged behavior on success.
-
-```python
-async def execute(
- self,
- pipe_output: PipeOutput | None,
- user_id: str,
- pipeline_run_id: str,
- delivery_assignment: DeliveryAssignment,
- status: DeliveryStatus,
- error_report: ErrorReport | None = None, # NEW
-) -> None:
- ...
- for webhook in delivery_assignment.webhooks:
- await self._notify_webhook(
- pipeline_run_id, status, result_url, webhook,
- error_report=error_report, # NEW
- )
-```
-
-And `_notify_webhook` adds:
-
-```python
-if status == DeliveryStatus.FAILED and error_report is not None:
- payload["error"] = error_report.to_dict()
-```
-
-**Recovery responsibility.** `DeliveryExecutor` itself does **not** call `recover_error_report(...)`. The caller — the worker/observer that catches the failing workflow — runs the recovery primitive once and passes the result. Rationale: keeps `DeliveryExecutor` oblivious to `__cause__`-walking, and there is exactly one place that needs to do recovery (the boundary that catches the Temporal failure).
-
-**Unrecoverable case.** When the caller's `recover_error_report(exc)` returns `None` (malformed details, version skew), the caller hand-authors an `ErrorReport` with `error_type="WorkflowFailureUnrecoverable"`, `error_domain="runtime"`, `retryable=False`, and a generic message, and passes that. Same code path, never silent.
-
-**Why.** Without this, `pipelex-api`'s Phase 4 is reduced to "the webhook tells you it FAILED, good luck." The async error pipe is lossy — every classification field (`error_type`, `error_category`, `retryable`, `user_action`, `provider_metadata`) is dropped at the boundary even though pipelex has it in hand. That is the contract that exists today. Phase 4 cannot deliver its promised improvement without this change.
-
-This is **the most important item in the list.** The rest are quality-of-life upgrades that remove duplication or polish the contract. This one is the difference between "the webhook is useful" and "the webhook is a notification with no content."
-
-**Surfaced by.** `track-temporal-recovery.md` and API Phase 4 review amendment A3.
-
----
-
-## Stage 4 — DX polish
-
-### 6. `ErrorReport.to_problem_document(...)` — optional rendering helper
-
-**Where:** `pipelex/base_exceptions.py` (next to `to_dict()` and `to_strict_dict()` from item 4).
-
-**What.** A thin method that builds the RFC 7807 problem document directly from an `ErrorReport`:
-
-```python
-def to_problem_document(
- self,
- *,
- instance: str | None = None,
- request_id: str | None = None,
- disclosure_mode: DisclosureMode = DisclosureMode.VERBOSE,
-) -> dict[str, Any]:
- """Return an RFC 7807 problem document built from this report.
-
- Standard fields (type, title, status, detail, instance) derive from
- the report's classification (using PipelexError.title and .type_uri
- when present on the originating class; humanize fallback otherwise).
- ErrorReport fields ride as RFC 7807 extension members. Strict mode
- is delegated to to_strict_dict.
- """
-```
-
-**Why.** Currently the `pipelex-api` Phase 4 decision is: webhook carries raw `ErrorReport` dict (the "consumer renders if needed" path), sync HTTP response renders to RFC 7807 (because HTTP wants it). That decision is correct for today's consumers — a queue / log shipper / batch processor receiving the webhook does not benefit from an envelope.
-
-But the moment a future use case wants "RFC 7807 everywhere" (e.g. a partner integration that consumes both sync and async via one schema, a regulatory requirement to emit `application/problem+json` over both transports), the rendering function needs to be callable from `pipelex/pipe_run/delivery_executor.py`. Today it cannot — the rendering lives in `pipelex-api`, which pipelex does not import.
-
-Landing this method in pipelex now makes "flip to RFC 7807 in webhooks" a one-line change later. The API consumes `to_problem_document(...)` from Phase 1 instead of building its own dict.
-
-**Why this is Stage 4, not Stage 2.** The API's Phase 1 builder needs ~30 lines anyway (to set `Content-Type`, headers, etc.) — the dict-building part is the easy half. We can land items 1, 2, 4 (the inputs to `to_problem_document`) and have the API build its own dict for now. Moving the dict-building upstream is purely about future-flexibility, not about removing today's duplication.
-
-**Surfaced by.** API Phase 4b render-decision discussion.
-
----
-
-### 7. Per-class `type` URI doc pages
-
-**Where:** pipelex's docs site (`pipelex/docs/...`).
-
-**What.** Generate one stub doc page per `PipelexError` subclass, anchored at the URI declared by `PipelexError.type_uri` (item 2) or the auto-derived default. Each page carries the class name, the title, the domain, the typical `user_action`, links to the parent class doc, and a back-link to the schema page.
-
-A small Sphinx / mkdocs plugin walks the `PipelexError` hierarchy at build time and emits one page per class. Authors override per-class content where it adds value; the default rendered content is fine for most classes.
-
-**Why.** `pipelex-api`'s Phase 5 ships a single generic schema page at `https://pipelex.dev/errors/`. Per-class URIs are stable identifiers but resolve to the schema page until each class has its own. Clients pattern-matching on `type` URIs see broken anchors when they click through to investigate.
-
-Auto-generated stubs make this a zero-maintenance fix — the docs grow as the class hierarchy grows, no manual sync.
-
-**Why this is Stage 4.** Pure docs/DX. No code dependency on the API plan. Pairs naturally with API Phase 5 (where the API publishes its own error-contract docs) but does not block any code work.
-
-**Surfaced by.** API Phase 5 implementation plan + `track-response-schema.md` "type URI namespace" section.
-
----
-
-## Stage 5 — Future-facing
-
-### 8. `query_pipeline_state(pipeline_run_id)` — sync status-query primitive
-
-**Where:** new in pipelex's Temporal layer (somewhere near `pipelex/temporal/tprl/workflow_caller.py`).
-
-**What.** Expose a pipelex-level function:
-
-```python
-async def query_pipeline_state(pipeline_run_id: str) -> PipelineState:
- """Return the current state of a previously-dispatched pipeline run.
-
- Reads Temporal's workflow history. Returns a structured state object
- that carries enough information for a status response:
- - pending: started_at
- - completed: result_url, completed_at
- - failed: recovered ErrorReport (or None if unrecoverable), failed_at
-
- The recovery primitive is called internally on the failed branch so
- callers don't need to know about `recover_error_report(...)`. Returns
- a typed state, not an exception.
- """
-```
-
-**Why.** `track-temporal-recovery.md` names a future `GET /api/v1/pipeline/{run_id}` endpoint and pins its response shape ("RFC 7807 problem document under `error` for FAILED state, mirroring the webhook"). The endpoint is out of scope for the API plan, but it will become useful the moment a client wants to poll instead of waiting for a webhook (no public endpoint to receive a webhook, firewalled environment, retry-after-restart, etc.).
-
-The blocking question for that endpoint is: how does the API query the state of a Temporal workflow it dispatched earlier, possibly from a different process / different deployment / different replica? Today there is no clean answer. Landing this primitive in pipelex means every consumer (API, CLI, agent CLI, future SDKs) can offer status polling without each rolling its own Temporal-query code.
-
-**Why this is Stage 5.** Not blocking the current API work. The webhook path exists and improves significantly via item 5. The status-query is a different use case (polling, not push) that no current consumer needs yet. But the primitive is small and clean, and landing it now means it's available when the first consumer asks.
-
-**Surfaced by.** `track-temporal-recovery.md` "Synchronous status endpoint (future)" section.
-
----
-
-## Stage 6 — Security tightening
-
-### 9. `X-Completion-Signature` covers the full webhook payload
-
-**Where:** `api/routes/pipelex/pipeline.py:44-56` (the `_completion_signature` helper) and `pipelex/pipe_run/delivery_executor.py:238-267` (the webhook POST).
-
-**What.** The current HMAC-SHA256 signature in `X-Completion-Signature` covers only `pipeline_run_id`. Sign the full payload instead.
-
-```
-sig = HMAC-SHA256(secret, request_body_bytes)
-header: X-Completion-Signature: sha256=<hex>
-```
-
-The signature is computed against the exact serialized body. Receivers verify by re-hashing the body they got.
-
-**Why.** Pre-existing weakness — a man-in-the-middle who can rewrite the body but not regenerate the signature can change `status`, `result_url`, or (after item 5 lands) the entire `error` payload, and the signature still verifies. Adding rich `error` content to the payload makes the tamper surface meaningfully larger than it was, which is why this is being addressed now even though it's an independent track.
-
-The change spans both repos: `pipelex-api` updates `_completion_signature` to take the body bytes; pipelex's `_notify_webhook` computes the signature on the serialized body before POST. Cross-repo, but a small total diff.
-
-**Why this is Stage 6.** Independent of the error model. Can land anytime — before, during, or after the rest of this list. Listed last because the work itself is straightforward and the cross-repo coordination is the only friction.
-
-**Surfaced by.** `track-temporal-recovery.md` "Webhook signing and integrity" section.
-
----
-
-## What NOT to push upstream
-
-Things that look like they belong in pipelex but actually stay API-side.
-
-- **The `api/errors.py` 4xx helpers.** `raise_validation_error`, `raise_bad_request`, `raise_forbidden`, `raise_unauthenticated`, `raise_payload_too_large`, `raise_internal_server_error`. FastAPI-specific. They emit RFC 7807 problem documents that pipelex itself never sees. Pushing them upstream would couple pipelex to FastAPI, which the project explicitly avoids ("the library itself stays HTTP-agnostic — no web-framework import lives here, only the mapping table" — `base_exceptions.py:23`).
-- **The `api/error_types.py` `ErrorType` enum.** Static API-owned error_type values for API-authored validation errors. Stays API-owned. Pipelex's `error_type` field is open-ended on purpose so the class name can be the identifier.
-- **Auth errors (`api/security.py`).** 401/403 are HTTP-layer concerns, not pipelex domain errors. Pipelex's error hierarchy does not (and should not) contain "invalid JWT signature."
-- **CORS, request body size limits, request id middleware, the request-id contextvar.** All API/HTTP concerns.
-- **Default disclosure mode.** Whether to default to verbose or strict is a deployment choice. Pipelex provides the redaction primitive (item 4); the consumer picks the default.
-
----
-
-## Tracking
-
-| # | Item | Stage | pipelex file | Status | PR |
-|---|---|---|---|---|---|
-| 1 | `PipelexError.title` class attribute | 1 | `base_exceptions.py:114` | Not started | — |
-| 2 | `PipelexError.type_uri` class attribute | 1 | `base_exceptions.py:114` | Not started | — |
-| 3 | First-class `request_id` on workflow input | 1 | `pipeline_run_setup.py`, `temporal_pipe_run.py` | Not started | — |
-| 4 | `ErrorReport.to_strict_dict()` | 2 | `base_exceptions.py:71` | Not started | — |
-| 5 | `DeliveryExecutor.execute(error_report=...)` | 3 | `pipe_run/delivery_executor.py:38` | Not started | — |
-| 6 | `ErrorReport.to_problem_document()` | 4 | `base_exceptions.py` | Not started | — |
-| 7 | Per-class `type` URI doc pages | 4 | `docs/` | Not started | — |
-| 8 | `query_pipeline_state(...)` | 5 | `temporal/tprl/workflow_caller.py` (new) | Not started | — |
-| 9 | Webhook signature covers full payload | 6 | `pipe_run/delivery_executor.py:_notify_webhook` + `api/routes/pipelex/pipeline.py:_completion_signature` | Not started | — |
-
-Update the Status / PR columns as items land. When all of Stage 1-3 are landed, the `pipelex-api` plan unblocks fully — Phase 0 consumes items 1+2 directly, Phase 1 consumes item 4 directly, and Phase 4 consumes item 5 directly.
diff --git a/wip/error-handling/error-handling.html b/wip/error-handling/error-handling.html
deleted file mode 100644
index 83c528b02..000000000
--- a/wip/error-handling/error-handling.html
+++ /dev/null
@@ -1,751 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>Error Handling Overhaul — Co-developer Briefing</title>
-<style>
- :root {
- --bg: #0f1117;
- --panel: #181b24;
- --panel-2: #1f232f;
- --ink: #e6e8ee;
- --ink-dim: #9aa0ad;
- --line: #2c313f;
- --accent: #7c83ff;
- --accent-soft: #2a2d56;
- --green: #4ade80;
- --amber: #fbbf24;
- --red: #f87171;
- --blue: #60a5fa;
- --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
- }
- * { box-sizing: border-box; }
- html { scroll-behavior: smooth; }
- body {
- margin: 0;
- background: var(--bg);
- color: var(--ink);
- font: 16px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
- -webkit-font-smoothing: antialiased;
- }
- .wrap { max-width: 980px; margin: 0 auto; padding: 0 28px 120px; }
- header {
- padding: 64px 0 40px;
- border-bottom: 1px solid var(--line);
- margin-bottom: 44px;
- }
- .eyebrow {
- font-family: var(--mono);
- font-size: 12.5px;
- letter-spacing: .12em;
- text-transform: uppercase;
- color: var(--accent);
- margin: 0 0 14px;
- }
- h1 {
- font-size: 38px;
- line-height: 1.18;
- margin: 0 0 18px;
- letter-spacing: -.02em;
- }
- .lede { font-size: 18px; color: var(--ink-dim); margin: 0 0 20px; max-width: 70ch; }
- .branchline {
- font-family: var(--mono);
- font-size: 13px;
- color: var(--ink-dim);
- background: var(--panel);
- border: 1px solid var(--line);
- border-radius: 8px;
- padding: 10px 14px;
- display: inline-block;
- }
- .branchline b { color: var(--accent); }
- h2 {
- font-size: 25px;
- margin: 60px 0 8px;
- letter-spacing: -.015em;
- scroll-margin-top: 20px;
- }
- h2 .num {
- font-family: var(--mono);
- font-size: 15px;
- color: var(--accent);
- margin-right: 12px;
- }
- h3 { font-size: 18px; margin: 32px 0 8px; }
- .section-sub { color: var(--ink-dim); margin: 4px 0 22px; }
- p { margin: 14px 0; }
- a { color: var(--accent); text-decoration: none; }
- a:hover { text-decoration: underline; }
- code {
- font-family: var(--mono);
- font-size: .88em;
- background: var(--panel-2);
- border: 1px solid var(--line);
- border-radius: 5px;
- padding: 1px 6px;
- }
- strong { color: #fff; }
-
- /* TOC */
- nav.toc {
- background: var(--panel);
- border: 1px solid var(--line);
- border-radius: 12px;
- padding: 22px 26px;
- margin-bottom: 24px;
- }
- nav.toc h4 {
- margin: 0 0 12px;
- font-size: 12.5px;
- letter-spacing: .1em;
- text-transform: uppercase;
- color: var(--ink-dim);
- font-family: var(--mono);
- }
- nav.toc ol {
- margin: 0; padding: 0;
- list-style: none;
- columns: 2;
- column-gap: 36px;
- }
- nav.toc li {
- font-size: 14.5px;
- padding: 4px 0;
- counter-increment: toc;
- }
- nav.toc li::before {
- content: counter(toc, decimal-leading-zero);
- font-family: var(--mono);
- font-size: 12px;
- color: var(--accent);
- margin-right: 10px;
- }
- nav.toc ol { counter-reset: toc; }
-
- /* Cards / callouts */
- .card {
- background: var(--panel);
- border: 1px solid var(--line);
- border-radius: 12px;
- padding: 20px 24px;
- margin: 20px 0;
- }
- .callout {
- border-left: 3px solid var(--accent);
- background: var(--panel);
- border-radius: 0 10px 10px 0;
- padding: 14px 20px;
- margin: 22px 0;
- }
- .callout.why { border-color: var(--amber); }
- .callout.why .lbl { color: var(--amber); }
- .callout .lbl {
- font-family: var(--mono);
- font-size: 11.5px;
- letter-spacing: .1em;
- text-transform: uppercase;
- color: var(--accent);
- display: block;
- margin-bottom: 4px;
- }
-
- /* Figures */
- figure {
- margin: 30px 0;
- background: var(--panel);
- border: 1px solid var(--line);
- border-radius: 12px;
- padding: 26px 24px 14px;
- text-align: center;
- }
- figure svg { max-width: 100%; height: auto; }
- figcaption {
- font-size: 13px;
- color: var(--ink-dim);
- margin-top: 14px;
- text-align: center;
- }
-
- /* Tables */
- table {
- width: 100%;
- border-collapse: collapse;
- margin: 22px 0;
- font-size: 14.5px;
- }
- th, td {
- text-align: left;
- padding: 11px 14px;
- border-bottom: 1px solid var(--line);
- vertical-align: top;
- }
- th {
- font-size: 12px;
- letter-spacing: .06em;
- text-transform: uppercase;
- color: var(--ink-dim);
- font-weight: 600;
- }
- tr:last-child td { border-bottom: none; }
- td code { white-space: nowrap; }
-
- .pill {
- display: inline-block;
- font-family: var(--mono);
- font-size: 11px;
- font-weight: 600;
- padding: 2px 9px;
- border-radius: 20px;
- letter-spacing: .03em;
- }
- .pill.landed { background: rgba(74,222,128,.13); color: var(--green); border: 1px solid rgba(74,222,128,.3); }
- .pill.open { background: rgba(251,191,36,.13); color: var(--amber); border: 1px solid rgba(251,191,36,.3); }
-
- /* Code blocks / diffs */
- .code {
- background: #0b0d13;
- border: 1px solid var(--line);
- border-radius: 10px;
- margin: 20px 0;
- overflow: hidden;
- }
- .code .filename {
- font-family: var(--mono);
- font-size: 12px;
- color: var(--ink-dim);
- padding: 9px 16px;
- background: var(--panel-2);
- border-bottom: 1px solid var(--line);
- }
- .code pre {
- margin: 0;
- padding: 16px 18px;
- overflow-x: auto;
- font-family: var(--mono);
- font-size: 12.8px;
- line-height: 1.6;
- }
- .code pre .add { color: var(--green); display: block; background: rgba(74,222,128,.07); }
- .code pre .del { color: var(--red); display: block; background: rgba(248,113,113,.07); }
- .code pre .ctx { color: var(--ink-dim); display: block; }
- .code pre .hdr { color: var(--accent); display: block; }
- .code pre .cmt { color: #6b7280; }
-
- .grid2 { display: grid; grid-template-columns: 1fr 1fr; gap: 18px; }
- @media (max-width: 720px) {
- .grid2 { grid-template-columns: 1fr; }
- nav.toc ol { columns: 1; }
- h1 { font-size: 30px; }
- }
-
- .footer {
- margin-top: 70px;
- padding-top: 24px;
- border-top: 1px solid var(--line);
- color: var(--ink-dim);
- font-size: 13.5px;
- }
- .tag {
- font-family: var(--mono);
- font-size: 11px;
- color: var(--accent);
- background: var(--accent-soft);
- padding: 2px 8px;
- border-radius: 5px;
- }
- ul.tight li { margin: 5px 0; }
-</style>
-</head>
-<body>
-<div class="wrap">
-
-<header>
- <p class="eyebrow">Co-developer Briefing</p>
- <h1>The Error-Handling Overhaul</h1>
- <p class="lede">A single, structured error model that travels intact from a raw provider SDK exception, through every wrapping layer, across the Temporal boundary, and out to humans, agents, and HTTP APIs — classified the same way at every stop.</p>
- <span class="branchline">branch <b>refactor/ECR</b> &nbsp;←&nbsp; <b>feature/Error-handling-2</b> &nbsp;←&nbsp; <b>feature/Temporal-merge-3</b></span>
-</header>
-
-<div class="card">
- <strong>TL;DR for the busy reviewer.</strong>
- <p style="margin-bottom:6px">Before this branch, an error meant whatever the layer that caught it decided to do — some swallowed it, some re-wrapped it losing the cause, some had no SDK handling at all. After this branch:</p>
- <ul class="tight" style="margin-top:6px">
- <li>Every inference worker turns SDK exceptions into a <strong>classified domain error</strong> (<code>InferenceErrorCategory</code> + structured metadata).</li>
- <li><code>ErrorReport</code> is the <strong>one serialization schema</strong> — CLI JSON, Rich panels, HTTP status, and Temporal <code>details</code> all read from it.</li>
- <li>Classification <strong>survives every wrapper</strong> via <code>__cause__</code>-chain enrichment, and <strong>survives the Temporal boundary</strong> activity → workflow → submitter.</li>
- <li>Retry is now an <strong>honest, explicit model</strong>: transport retry in the SDK, durability in Temporal, and nothing fake in between.</li>
- <li><code>except Exception</code> is banned in business logic — <strong>ruff <code>BLE001</code> enforces it</strong>.</li>
- </ul>
- <p style="margin-bottom:0">Independent tracks across metadata, worker classification, retry &amp; resilience, CLI/HTTP delivery, the Temporal boundary, testing, and the Extract / Classify / Render decomposition — all landed.</p>
-</div>
-
-<nav class="toc">
- <h4>Contents</h4>
- <ol>
- <li><a href="#why">Why we did this</a></li>
- <li><a href="#layers">The layer model</a></li>
- <li><a href="#journey">The error's journey</a></li>
- <li><a href="#report">ErrorReport — the schema</a></li>
- <li><a href="#workers">Worker classification</a></li>
- <li><a href="#retry">Retry &amp; resilience</a></li>
- <li><a href="#temporal">The Temporal boundary</a></li>
- <li><a href="#delivery">CLI &amp; HTTP delivery</a></li>
- <li><a href="#tests">Testing</a></li>
- <li><a href="#open">What's still open</a></li>
- </ol>
-</nav>
-
-<!-- ================================================================ -->
-<h2 id="why"><span class="num">01</span>Why we did this</h2>
-<p class="section-sub">The state we started from, and the principle we settled on.</p>
-
-<p>On <code>feature/Temporal-merge-3</code>, error handling was inconsistent. A tier review classified inference workers into three buckets — and a large share of them (Google, Mistral, Azure img-gen, FAL, HuggingFace, Docling, Linkup, pypdfium2) had <strong>no SDK exception handling at all</strong>: a raw provider error propagated up as-is, untyped, uncategorized. Other layers caught errors and re-wrapped them, sometimes dropping the <code>__cause__</code>. There was a <code>PipeRouter</code> retry loop that only ever ran on the direct path, re-ran at the wrong granularity, and carried a config bug. And <code>except Exception</code> appeared throughout business logic, silently swallowing bugs.</p>
-
-<div class="callout why">
- <span class="lbl">The principle</span>
- An error is <strong>data</strong>, not a control-flow accident. It is classified once, at the layer that knows the most (the worker), and that classification must reach every consumer unchanged — the human reading a Rich panel, the agent parsing JSON, the Temporal retry engine, the HTTP adapter picking a status code. No layer in between is allowed to lose it.
-</div>
-
-<p>Three cross-cutting rules now hold everywhere and the tracks build on them:</p>
-<ul class="tight">
- <li><strong>Single-rooted hierarchy.</strong> Every custom exception inherits from <code>pipelex.base_exceptions.PipelexError</code>.</li>
- <li><strong>No broad catches in business logic.</strong> <code>except Exception</code> is allowed only at CLI entry points and async task roots — and ruff rule <code>BLE001</code> is enabled to enforce it.</li>
- <li><strong>Workers transform SDK errors into domain errors.</strong> Catch the SDK's typed exceptions, attach an <code>InferenceErrorCategory</code>, chain via <code>from exc</code>.</li>
-</ul>
-
-<!-- ================================================================ -->
-<h2 id="layers"><span class="num">02</span>The layer model</h2>
-<p class="section-sub">Errors flow up through six layers. Each one has exactly one job.</p>
-
-<figure>
-<svg viewBox="0 0 760 430" xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace, Menlo, monospace">
- <defs>
- <marker id="arrowUp" markerWidth="10" markerHeight="10" refX="5" refY="2" orient="auto">
- <path d="M0,8 L5,0 L10,8 Z" fill="#7c83ff"/>
- </marker>
- </defs>
- <!-- layers -->
- <g font-size="13">
- <!-- L5 -->
- <rect x="120" y="20" width="540" height="52" rx="8" fill="#1f232f" stroke="#2c313f"/>
- <text x="140" y="42" fill="#e6e8ee" font-size="13" font-weight="bold">Layer 5 · CLI entry points</text>
- <text x="140" y="60" fill="#9aa0ad" font-size="11.5">catch + format for human (Rich) / agent (JSON·MD) / HTTP status</text>
- <!-- L4 -->
- <rect x="120" y="84" width="540" height="52" rx="8" fill="#1f232f" stroke="#2c313f"/>
- <text x="140" y="106" fill="#e6e8ee" font-size="13" font-weight="bold">Layer 4 · CLI factories</text>
- <text x="140" y="124" fill="#9aa0ad" font-size="11.5">catch setup errors, route to handlers</text>
- <!-- L3 -->
- <rect x="120" y="148" width="540" height="52" rx="8" fill="#1f232f" stroke="#2c313f"/>
- <text x="140" y="170" fill="#e6e8ee" font-size="13" font-weight="bold">Layer 3 · Pipeline runner</text>
- <text x="140" y="188" fill="#9aa0ad" font-size="11.5">catch + wrap as PipelineExecutionError</text>
- <!-- L2 -->
- <rect x="120" y="212" width="540" height="52" rx="8" fill="#1f232f" stroke="#2c313f"/>
- <text x="140" y="234" fill="#e6e8ee" font-size="13" font-weight="bold">Layer 2 · Pipe router / operators</text>
- <text x="140" y="252" fill="#9aa0ad" font-size="11.5">catch + wrap with pipe context (pipe_code, pipe_stack…)</text>
- <!-- L1 -->
- <rect x="120" y="276" width="540" height="52" rx="8" fill="#2a2d56" stroke="#7c83ff"/>
- <text x="140" y="298" fill="#fff" font-size="13" font-weight="bold">Layer 1 · Workers / SDK calls ◀ classification happens here</text>
- <text x="140" y="316" fill="#c7c9f0" font-size="11.5">catch third-party exception → CogtError + InferenceErrorCategory</text>
- <!-- L0 -->
- <rect x="120" y="340" width="540" height="52" rx="8" fill="#181b24" stroke="#2c313f" stroke-dasharray="4 3"/>
- <text x="140" y="362" fill="#9aa0ad" font-size="13" font-weight="bold">Layer 0 · Third-party SDKs</text>
- <text x="140" y="380" fill="#6b7280" font-size="11.5">raw OpenAI / Anthropic / Google / Mistral / … exceptions</text>
- </g>
- <!-- up arrow -->
- <line x1="58" y1="392" x2="58" y2="40" stroke="#7c83ff" stroke-width="2" marker-end="url(#arrowUp)"/>
- <text x="36" y="220" fill="#7c83ff" font-size="11.5" transform="rotate(-90 36 220)" text-anchor="middle">error propagates up — classification preserved at every layer</text>
-</svg>
-<figcaption>Errors originate at Layer 0, are classified at Layer 1, and accumulate context (pipe code, stack, run mode) as they rise. No layer drops the classification.</figcaption>
-</figure>
-
-<!-- ================================================================ -->
-<h2 id="journey"><span class="num">03</span>The error's journey</h2>
-<p class="section-sub">From a raw SDK exception to four different rendered outputs — one schema throughout.</p>
-
-<figure>
-<svg viewBox="0 0 760 410" xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace, Menlo, monospace">
- <defs>
- <marker id="ar" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto">
- <path d="M0,0 L7,3 L0,6 Z" fill="#7c83ff"/>
- </marker>
- </defs>
- <!-- SDK exc -->
- <rect x="20" y="40" width="150" height="64" rx="8" fill="#181b24" stroke="#2c313f" stroke-dasharray="4 3"/>
- <text x="95" y="66" text-anchor="middle" fill="#9aa0ad" font-size="12" font-weight="bold">RateLimitError</text>
- <text x="95" y="84" text-anchor="middle" fill="#6b7280" font-size="10.5">raw SDK exception</text>
-
- <!-- worker classify -->
- <rect x="215" y="28" width="170" height="88" rx="8" fill="#2a2d56" stroke="#7c83ff"/>
- <text x="300" y="52" text-anchor="middle" fill="#fff" font-size="12" font-weight="bold">Worker classifies</text>
- <text x="300" y="71" text-anchor="middle" fill="#c7c9f0" font-size="10">is_quota_exhaustion_*()</text>
- <text x="300" y="86" text-anchor="middle" fill="#c7c9f0" font-size="10">→ CAPACITY vs TRANSIENT</text>
- <text x="300" y="104" text-anchor="middle" fill="#c7c9f0" font-size="10">raise CogtError(…) from exc</text>
-
- <!-- ErrorReport -->
- <rect x="430" y="20" width="170" height="104" rx="8" fill="#1f232f" stroke="#7c83ff" stroke-width="1.5"/>
- <text x="515" y="42" text-anchor="middle" fill="#7c83ff" font-size="12" font-weight="bold">ErrorReport</text>
- <text x="515" y="60" text-anchor="middle" fill="#9aa0ad" font-size="9.5">error_category · error_domain</text>
- <text x="515" y="74" text-anchor="middle" fill="#9aa0ad" font-size="9.5">retryable · user_action</text>
- <text x="515" y="88" text-anchor="middle" fill="#9aa0ad" font-size="9.5">model · provider</text>
- <text x="515" y="102" text-anchor="middle" fill="#9aa0ad" font-size="9.5">provider_metadata</text>
- <text x="515" y="117" text-anchor="middle" fill="#6b7280" font-size="9">via to_error_report()</text>
-
- <!-- wrapping note -->
- <rect x="430" y="148" width="310" height="46" rx="8" fill="#181b24" stroke="#2c313f"/>
- <text x="585" y="167" text-anchor="middle" fill="#e6e8ee" font-size="10.5" font-weight="bold">wrapped by Pipe / Router / Runner layers…</text>
- <text x="585" y="183" text-anchor="middle" fill="#9aa0ad" font-size="9.5">__cause__-chain enrichment keeps the classification</text>
-
- <!-- consumers -->
- <g font-size="10">
- <rect x="20" y="250" width="165" height="56" rx="8" fill="#1f232f" stroke="#2c313f"/>
- <text x="102" y="273" text-anchor="middle" fill="#e6e8ee" font-weight="bold">Human CLI</text>
- <text x="102" y="290" text-anchor="middle" fill="#9aa0ad">Rich error panel</text>
-
- <rect x="205" y="250" width="165" height="56" rx="8" fill="#1f232f" stroke="#2c313f"/>
- <text x="287" y="273" text-anchor="middle" fill="#e6e8ee" font-weight="bold">Agent CLI</text>
- <text x="287" y="290" text-anchor="middle" fill="#9aa0ad">JSON / Markdown</text>
-
- <rect x="390" y="250" width="165" height="56" rx="8" fill="#1f232f" stroke="#2c313f"/>
- <text x="472" y="273" text-anchor="middle" fill="#e6e8ee" font-weight="bold">HTTP adapters</text>
- <text x="472" y="290" text-anchor="middle" fill="#9aa0ad">.http_status → 4xx/5xx</text>
-
- <rect x="575" y="250" width="165" height="56" rx="8" fill="#1f232f" stroke="#2c313f"/>
- <text x="657" y="273" text-anchor="middle" fill="#e6e8ee" font-weight="bold">Temporal</text>
- <text x="657" y="290" text-anchor="middle" fill="#9aa0ad">retry decision + details</text>
- </g>
-
- <!-- arrows -->
- <line x1="172" y1="72" x2="210" y2="72" stroke="#7c83ff" stroke-width="2" marker-end="url(#ar)"/>
- <line x1="387" y1="72" x2="426" y2="72" stroke="#7c83ff" stroke-width="2" marker-end="url(#ar)"/>
- <path d="M515 124 L515 144" stroke="#7c83ff" stroke-width="2" fill="none" marker-end="url(#ar)"/>
- <!-- fan-out -->
- <path d="M500 196 C500 224, 102 222, 102 246" stroke="#7c83ff" stroke-width="1.6" fill="none" marker-end="url(#ar)"/>
- <path d="M520 196 C520 224, 287 222, 287 246" stroke="#7c83ff" stroke-width="1.6" fill="none" marker-end="url(#ar)"/>
- <path d="M560 196 C560 224, 472 222, 472 246" stroke="#7c83ff" stroke-width="1.6" fill="none" marker-end="url(#ar)"/>
- <path d="M600 196 C600 224, 657 222, 657 246" stroke="#7c83ff" stroke-width="1.6" fill="none" marker-end="url(#ar)"/>
- <text x="380" y="364" text-anchor="middle" fill="#6b7280" font-size="10.5">one schema · four renderers · identical classification at every stop</text>
-</svg>
-<figcaption>The same <code>ErrorReport</code> drives all four delivery surfaces. Wrapper exceptions inherit the underlying classification through <code>__cause__</code>-chain enrichment.</figcaption>
-</figure>
-
-<h3>The tracks at a glance</h3>
-<table>
- <thead><tr><th>Track</th><th>Status</th><th>What it delivers</th></tr></thead>
- <tbody>
- <tr><td><strong>Metadata model</strong></td><td><span class="pill landed">Landed</span></td><td>The data contract — <code>error_category</code>, <code>error_domain</code>, <code>user_action</code>, <code>ProviderErrorMetadata</code> — carried on the exception class.</td></tr>
- <tr><td><strong>Worker classification</strong></td><td><span class="pill landed">Landed</span></td><td>Every LLM / img-gen / extract / search worker maps SDK exceptions → categorized <code>CogtError</code>.</td></tr>
- <tr><td><strong>Retry &amp; resilience</strong></td><td><span class="pill landed">Landed</span></td><td>Removed the fake <code>PipeRouter</code> loop; explicit transport retry; bounded <code>PipeBatch</code> fan-out.</td></tr>
- <tr><td><strong>CLI delivery</strong></td><td><span class="pill landed">Landed</span></td><td>Agent CLI markdown/JSON; <code>error_domain</code> → HTTP-status mapping; shared Rich panel helper.</td></tr>
- <tr><td><strong>Temporal integration</strong></td><td><span class="pill landed">Landed</span></td><td><code>ErrorReport</code> carried across activity → workflow → submitter; category-aware retry.</td></tr>
- <tr><td><strong>Testing</strong></td><td><span class="pill landed">Landed</span></td><td>Per-worker classification, full-chain snapshot, local/Temporal parity, dict drift-detection.</td></tr>
- <tr><td><strong>Extract / Classify / Render</strong></td><td><span class="pill landed">Landed</span></td><td>Per-worker pipeline decomposed into one per-provider Extract + shared Classify + shared Render. Branch <code>refactor/ECR</code>.</td></tr>
- </tbody>
-</table>
-
-<!-- ================================================================ -->
-<h2 id="report"><span class="num">04</span>ErrorReport — the schema</h2>
-<p class="section-sub">One frozen dataclass. <code>pipelex/base_exceptions.py</code>.</p>
-
-<p><code>ErrorReport</code> is a frozen pydantic dataclass with <code>extra="forbid"</code>. It is the single source of truth for error serialization — <code>to_dict()</code> drops <code>None</code> fields, <code>from_dict()</code> is its strict inverse (used to recover a report that crossed the Temporal boundary), and <code>http_status</code> maps it to an HTTP code for downstream APIs.</p>
-
-<div class="code">
- <div class="filename">pipelex/base_exceptions.py — ErrorReport gains classification + domain fields</div>
-<pre><span class="ctx"> @dataclass(frozen=True, config={"extra": "forbid"})</span>
-<span class="ctx"> class ErrorReport:</span>
-<span class="ctx"> error_type: str</span>
-<span class="ctx"> message: str</span>
-<span class="ctx"> error_category: str | None = None</span>
-<span class="add">+ error_domain: str | None = None # input / config / runtime</span>
-<span class="ctx"> retryable: bool | None = None</span>
-<span class="del">- user_action: str | None = None</span>
-<span class="add">+ user_action: UserAction | None = None # typed: kind + detail</span>
-<span class="ctx"> model: str | None = None</span>
-<span class="ctx"> provider: str | None = None</span>
-<span class="add">+ provider_metadata: ProviderErrorMetadata | None = None</span>
-</pre>
-</div>
-
-<p>The most important behaviour change is on <code>PipelexError</code> itself. A wrapper exception (<code>PipeRunError</code> → <code>PipeRouterError</code> → <code>PipelineExecutionError</code>) carries no category of its own. <code>to_error_report()</code> now enriches the report from the <code>__cause__</code> chain, so the inference classification survives every wrapping layer:</p>
-
-<div class="code">
- <div class="filename">pipelex/base_exceptions.py — cause-chain enrichment (new)</div>
-<pre><span class="add">+def _enrich_error_report_from_cause(self, report: ErrorReport) -> ErrorReport:</span>
-<span class="add">+ """Fill the None classification fields of `report` from the __cause__ chain."""</span>
-<span class="add">+ cause = self.__cause__</span>
-<span class="add">+ if not isinstance(cause, PipelexError):</span>
-<span class="add">+ return report</span>
-<span class="add">+ # ... cyclic-chain guard omitted ...</span>
-<span class="add">+ cause_report = cause.to_error_report()</span>
-<span class="add">+ return ErrorReport(</span>
-<span class="add">+ error_type=report.error_type, # keep own identity</span>
-<span class="add">+ message=report.message,</span>
-<span class="add">+ error_category=report.error_category or cause_report.error_category,</span>
-<span class="add">+ error_domain=report.error_domain or cause_report.error_domain,</span>
-<span class="add">+ retryable=report.retryable if report.retryable is not None else cause_report.retryable,</span>
-<span class="add">+ user_action=report.user_action or cause_report.user_action,</span>
-<span class="add">+ model=report.model or cause_report.model,</span>
-<span class="add">+ provider=report.provider or cause_report.provider,</span>
-<span class="add">+ provider_metadata=report.provider_metadata or cause_report.provider_metadata,</span>
-<span class="add">+ )</span>
-</pre>
-</div>
-
-<div class="callout">
- <span class="lbl">Watch for</span>
- A <code>to_error_report()</code> override on a subclass <strong>must</strong> end with <code>self._enrich_error_report_from_cause(report)</code> — otherwise that subclass becomes a black hole that drops the cause's classification. The cyclic-<code>__cause__</code> guard exists because a malformed chain must never turn the error-reporting path into a <code>RecursionError</code>.
-</div>
-
-<h3>Two enums you'll see everywhere</h3>
-<div class="grid2">
- <div class="card">
- <strong><code>InferenceErrorCategory</code></strong>
- <p style="font-size:14px;color:var(--ink-dim);margin:8px 0 0">Drives retry decisions. Only <code>TRANSIENT</code> is retryable.</p>
- <ul class="tight" style="font-size:13.5px">
- <li><code>TRANSIENT</code> — retry it</li>
- <li><code>CONFIGURATION</code> — fix the setup</li>
- <li><code>CONTENT</code> — fix the input/prompt</li>
- <li><code>CAPACITY</code> — quota / billing</li>
- <li><code>AMBIGUOUS</code> — outcome unknown, unsafe to retry</li>
- <li><code>UNKNOWN</code> — could not classify</li>
- </ul>
- </div>
- <div class="card">
- <strong><code>ErrorDomain</code></strong>
- <p style="font-size:14px;color:var(--ink-dim);margin:8px 0 0">Drives HTTP status. Class-level on the exception.</p>
- <ul class="tight" style="font-size:13.5px">
- <li><code>INPUT</code> → HTTP <strong>422</strong> — caller can fix it</li>
- <li><code>CONFIG</code> → HTTP <strong>500</strong> — env change needed</li>
- <li><code>RUNTIME</code> → HTTP <strong>500</strong> — failure during execution</li>
- </ul>
- <p style="font-size:13px;color:var(--ink-dim);margin:10px 0 0">A provider 429 in <code>provider_metadata</code> overrides this so the API can emit <code>Retry-After</code>.</p>
- </div>
-</div>
-
-<!-- ================================================================ -->
-<h2 id="workers"><span class="num">05</span>Worker classification — Extract / Classify / Render</h2>
-<p class="section-sub">Every inference worker collapses to one three-line shape.</p>
-
-<p>After the ECR (<code>refactor/ECR</code>) sweep, every provider worker under <code>pipelex/plugins/*/</code> handles SDK exceptions with the same three steps. <strong>Extract</strong> turns the provider's SDK exception into a provider-blind <code>ProviderErrorMetadata</code> envelope. <strong>Classify</strong> is a single shared, provider-blind function mapping that envelope to a <code>ClassificationResult(category, user_action_kind, is_model_not_found)</code>. <strong>Render</strong> is a single shared function per worker family that picks the right <code>CogtError</code> subclass from an <code>InferenceErrorFamily</code> tag plus the <code>is_model_not_found</code> flag (e.g. <code>LLMModelNotFoundError</code> vs <code>LLMCompletionError</code>).</p>
-
-<div class="code">
- <div class="filename">pipelex/plugins/*/…_llm_worker.py — the post-ECR uniform shape</div>
-<pre><span class="ctx">except (APIStatusError, APIConnectionError, APITimeoutError) as exc:</span>
-<span class="add">+ metadata = extract_openai_metadata(exc) # provider-specific</span>
-<span class="add">+ classification = classify_inference_error(metadata) # shared, provider-blind</span>
-<span class="add">+ raise render_llm_error( # shared</span>
-<span class="add">+ classification=classification,</span>
-<span class="add">+ metadata=metadata,</span>
-<span class="add">+ family=InferenceErrorFamily.LLM,</span>
-<span class="add">+ model_desc=self.inference_model.desc,</span>
-<span class="add">+ ) from exc</span>
-</pre>
-</div>
-
-<p>Only the per-provider <code>extract_*_metadata</code> functions stay plugin-local — one per SDK family, registered against <code>ProviderName</code>. Classify and Render live once, in <code>pipelex/cogt/inference/error_classify.py</code> and <code>error_render.py</code>. A parity meta-test (<code>test_provider_classification_parity.py</code>) walks every <code>ProviderName</code> against the extract-fn registry and the worker-family map, so adding a new provider without wiring it fails fast.</p>
-
-<p>This sweep lifted <strong>every worker kind</strong> — LLM, img-gen, extract, search, plus AWS Bedrock — to the same standard. The workers that previously had zero SDK handling (Google, Mistral, Azure img-gen, FAL, HuggingFace, Docling, Linkup, pypdfium2) now all classify. Refinements that landed alongside:</p>
-
-<ul class="tight">
- <li><strong>Per-provider concern confined to Extract.</strong> Quota-vs-rate-limit, content-policy-vs-bad-request, model-not-found-vs-other-404 discriminators now live as <code>@property</code> accessors on <code>ProviderErrorMetadata</code> (<code>is_quota_exhaustion</code>, <code>is_content_policy_violation</code>, <code>is_network_error</code>) or as a flag the Extract fn sets. Classify reads them; the worker no longer branches on them.</li>
- <li><strong>The <code>instructor</code> unwrap.</strong> On structured-generation paths, <code>extract_underlying_sdk_exception()</code> recovers the real SDK exception out of <code>InstructorRetryException</code>, so it routes through the same Extract → Classify → Render chain as the plain-text path.</li>
- <li><strong><code>UNKNOWN</code> instead of mis-labelling.</strong> An unrecognized inner exception (e.g. a <code>pydantic.ValidationError</code> from a schema mismatch) now lands in <code>UNKNOWN</code> rather than being mis-categorized as a real <code>CONTENT</code>-policy violation.</li>
- <li><strong><code>ProviderErrorMetadata</code>.</strong> Every raised inference error carries <code>status_code</code>, <code>request_id</code>, <code>retry_after_seconds</code>, <code>provider_error_code</code>, and the human <code>message</code>. The raw response <code>body</code> is held in-process but <code>exclude</code>d from serialization — it can carry credentials.</li>
-</ul>
-
-<!-- ================================================================ -->
-<h2 id="retry"><span class="num">06</span>Retry &amp; resilience</h2>
-<p class="section-sub">An honest model — and removing the loop that pretended otherwise.</p>
-
-<p>The headline change: <strong>the <code>PipeRouter</code> transient-retry loop was removed.</strong> It only ever ran on the direct (non-Temporal) path, re-ran at the wrong granularity, and carried a per-run/global config bug. Rather than fix a retry loop for a path that is <em>deliberately</em> not the resilient one, it was deleted (PR #909).</p>
-
-<div class="callout why">
- <span class="lbl">The product line</span>
- <strong>Direct execution for simplicity. Temporal for resilience.</strong> Nothing fake in between. Direct execution makes one pipeline-level attempt on top of a transport that already shrugs off brief blips — and then surfaces the error. That is the honest contract.
-</div>
-
-<figure>
-<svg viewBox="0 0 760 300" xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace, Menlo, monospace">
- <!-- Direct path -->
- <text x="190" y="30" text-anchor="middle" fill="#e6e8ee" font-size="13" font-weight="bold">Direct execution — simplicity</text>
- <rect x="40" y="48" width="300" height="50" rx="8" fill="#1f232f" stroke="#2c313f"/>
- <text x="190" y="69" text-anchor="middle" fill="#e6e8ee" font-size="11.5" font-weight="bold">Tier 1 · Transport retry</text>
- <text x="190" y="86" text-anchor="middle" fill="#9aa0ad" font-size="10">SDK retries conn / 408 / 409 / 429 / 5xx · Retry-After</text>
-
- <rect x="40" y="110" width="300" height="44" rx="8" fill="#181b24" stroke="#2c313f" stroke-dasharray="4 3"/>
- <text x="190" y="131" text-anchor="middle" fill="#6b7280" font-size="10.5">— nothing here, by design —</text>
- <text x="190" y="146" text-anchor="middle" fill="#6b7280" font-size="9">(the removed PipeRouter loop lived here)</text>
-
- <rect x="40" y="166" width="300" height="44" rx="8" fill="#1f232f" stroke="#2c313f"/>
- <text x="190" y="187" text-anchor="middle" fill="#e6e8ee" font-size="11" font-weight="bold">single pipeline attempt → surface the error</text>
- <text x="190" y="202" text-anchor="middle" fill="#9aa0ad" font-size="9.5">no durability, no crash survival</text>
-
- <!-- Temporal path -->
- <text x="570" y="30" text-anchor="middle" fill="#e6e8ee" font-size="13" font-weight="bold">Temporal execution — resilience</text>
- <rect x="420" y="48" width="300" height="50" rx="8" fill="#1f232f" stroke="#2c313f"/>
- <text x="570" y="69" text-anchor="middle" fill="#e6e8ee" font-size="11.5" font-weight="bold">Tier 1 · Transport retry</text>
- <text x="570" y="86" text-anchor="middle" fill="#9aa0ad" font-size="10">same SDK-level retry as direct</text>
-
- <rect x="420" y="110" width="300" height="100" rx="8" fill="#2a2d56" stroke="#7c83ff"/>
- <text x="570" y="133" text-anchor="middle" fill="#fff" font-size="11.5" font-weight="bold">Tier 2 · Temporal durability</text>
- <text x="570" y="152" text-anchor="middle" fill="#c7c9f0" font-size="10">activity RetryPolicy keyed off</text>
- <text x="570" y="167" text-anchor="middle" fill="#c7c9f0" font-size="10">InferenceErrorCategory.is_retryable</text>
- <text x="570" y="186" text-anchor="middle" fill="#c7c9f0" font-size="10">workflow-level durability + redelivery</text>
- <text x="570" y="201" text-anchor="middle" fill="#c7c9f0" font-size="10">survives a worker crash</text>
-</svg>
-<figcaption>Two tiers, two paths. The gap on the direct path between Tier 1 and Tier 2 is intentional — that gap <em>is</em> the difference between the two products.</figcaption>
-</figure>
-
-<p>Supporting changes that landed under this track:</p>
-<ul class="tight">
- <li><strong>Tier 1 made explicit.</strong> <code>cogt.transport_max_retries</code> (default 2) is wired into every inference SDK client factory. The two families that defaulted to <em>no</em> transport retry (Mistral, Google) are brought up to the floor. The SDK-less <code>azure_rest</code> img-gen path gets a <code>tenacity</code>-based wrapper (<code>transport_retry.py</code>) that narrows retries for non-idempotent POSTs.</li>
- <li><strong><code>instructor</code> confined to schema re-ask.</strong> Its retry predicate now matches <em>only</em> validation failures — a transport error propagates raw instead of being wrapped, so Tier 1 stays the sole transport-retry layer.</li>
- <li><strong>Bounded fan-out.</strong> <code>PipeBatch</code> uses <code>gather_bounded()</code> (<code>max_concurrency</code>, default 8) — admission control so a big batch doesn't trigger a self-inflicted rate-limit storm. This is not retry; it stays.</li>
-</ul>
-
-<!-- ================================================================ -->
-<h2 id="temporal"><span class="num">07</span>The Temporal boundary</h2>
-<p class="section-sub">Keeping the classification intact across process boundaries.</p>
-
-<p>When a pipe runs on a Temporal worker, the error has to survive serialization across the activity → workflow → submitter boundary. Temporal's default failure converter would auto-wrap a raw <code>PipelexError</code> — losing both our structured <code>ErrorReport</code> and the category-aware retry decision. The bridge closes that gap.</p>
-
-<figure>
-<svg viewBox="0 0 760 320" xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace, Menlo, monospace">
- <defs>
- <marker id="ar2" markerWidth="9" markerHeight="9" refX="7" refY="3" orient="auto">
- <path d="M0,0 L7,3 L0,6 Z" fill="#7c83ff"/>
- </marker>
- </defs>
- <!-- Activity -->
- <rect x="20" y="60" width="210" height="150" rx="10" fill="#1f232f" stroke="#2c313f"/>
- <text x="125" y="84" text-anchor="middle" fill="#e6e8ee" font-size="12" font-weight="bold">Activity process</text>
- <rect x="40" y="100" width="170" height="44" rx="6" fill="#181b24" stroke="#2c313f"/>
- <text x="125" y="118" text-anchor="middle" fill="#9aa0ad" font-size="9.5">worker raises CogtError</text>
- <text x="125" y="132" text-anchor="middle" fill="#9aa0ad" font-size="9.5">(error_category set)</text>
- <rect x="40" y="152" width="170" height="44" rx="6" fill="#2a2d56" stroke="#7c83ff"/>
- <text x="125" y="170" text-anchor="middle" fill="#fff" font-size="9.5" font-weight="bold">@convert_pipelex_errors</text>
- <text x="125" y="184" text-anchor="middle" fill="#c7c9f0" font-size="9">→ TemporalError</text>
-
- <!-- Workflow -->
- <rect x="275" y="60" width="210" height="150" rx="10" fill="#1f232f" stroke="#2c313f"/>
- <text x="380" y="84" text-anchor="middle" fill="#e6e8ee" font-size="12" font-weight="bold">Workflow</text>
- <rect x="295" y="100" width="170" height="44" rx="6" fill="#181b24" stroke="#2c313f"/>
- <text x="380" y="118" text-anchor="middle" fill="#9aa0ad" font-size="9.5">RetryPolicy reads</text>
- <text x="380" y="132" text-anchor="middle" fill="#9aa0ad" font-size="9.5">non_retryable flag</text>
- <rect x="295" y="152" width="170" height="44" rx="6" fill="#181b24" stroke="#2c313f"/>
- <text x="380" y="170" text-anchor="middle" fill="#9aa0ad" font-size="9.5">from_app_error()</text>
- <text x="380" y="184" text-anchor="middle" fill="#9aa0ad" font-size="9.5">recovers details</text>
-
- <!-- Submitter -->
- <rect x="530" y="60" width="210" height="150" rx="10" fill="#1f232f" stroke="#2c313f"/>
- <text x="635" y="84" text-anchor="middle" fill="#e6e8ee" font-size="12" font-weight="bold">Submitter process</text>
- <rect x="550" y="100" width="170" height="44" rx="6" fill="#2a2d56" stroke="#7c83ff"/>
- <text x="635" y="118" text-anchor="middle" fill="#fff" font-size="9.5" font-weight="bold">recover_error_report()</text>
- <text x="635" y="132" text-anchor="middle" fill="#c7c9f0" font-size="9">ErrorReport.from_dict()</text>
- <rect x="550" y="152" width="170" height="44" rx="6" fill="#181b24" stroke="#2c313f"/>
- <text x="635" y="170" text-anchor="middle" fill="#9aa0ad" font-size="9.5">WorkflowExecutionError</text>
- <text x="635" y="184" text-anchor="middle" fill="#9aa0ad" font-size="9.5">(error_report=…)</text>
-
- <!-- arrows -->
- <line x1="232" y1="135" x2="272" y2="135" stroke="#7c83ff" stroke-width="2" marker-end="url(#ar2)"/>
- <line x1="487" y1="135" x2="527" y2="135" stroke="#7c83ff" stroke-width="2" marker-end="url(#ar2)"/>
- <text x="380" y="244" text-anchor="middle" fill="#7c83ff" font-size="10.5">ErrorReport travels in ApplicationError.details — serialized, recovered, re-classified</text>
- <text x="380" y="266" text-anchor="middle" fill="#6b7280" font-size="10">a Temporal-run pipe failure reaches the CLI with the SAME classification as a local run</text>
-</svg>
-<figcaption>The activity-side decorator converts the error; the submitter side recovers the full report. Worker/submitter version skew is tolerated — unknown keys are dropped.</figcaption>
-</figure>
-
-<div class="code">
- <div class="filename">pipelex/temporal/tprl/activity_error_boundary.py — the activity-side decorator (new)</div>
-<pre><span class="add">[email protected](func)</span>
-<span class="add">+async def wrapper(*args, **kwargs):</span>
-<span class="add">+ try:</span>
-<span class="add">+ return await func(*args, **kwargs)</span>
-<span class="add">+ except PipelexError as exc: # ONLY PipelexError — never bare Exception</span>
-<span class="add">+ raise TemporalError.from_message_exception(exc=exc) from exc</span>
-</pre>
-</div>
-
-<p>Applied beneath <code>@activity.defn</code> on every in-scope activity. <code>from_message_exception()</code> derives <code>non_retryable</code> from <code>InferenceErrorCategory.is_retryable</code> (the class-name list is now only a <em>fallback</em> for category-less errors) and packs <code>to_error_report().to_dict()</code> into <code>ApplicationError.details</code>. On the way back, <code>recover_error_report()</code> walks the <code>__cause__</code> chain, pulls the dict, and rebuilds the <code>ErrorReport</code> — tolerating version skew so the error path never crashes on a rolling deploy.</p>
-
-<div class="callout">
- <span class="lbl">Net effect</span>
- A pipe that fails on a Temporal worker now reaches the agent CLI JSON, the Rich human panel, and the HTTP-status mapping with the <strong>same</strong> <code>error_category</code> / <code>retryable</code> / <code>model</code> / <code>provider</code> / <code>user_action</code> as the identical failure run locally. An integration parity pair locks this by construction.
-</div>
-
-<!-- ================================================================ -->
-<h2 id="delivery"><span class="num">08</span>CLI &amp; HTTP delivery</h2>
-<p class="section-sub">Where the classified error finally gets rendered.</p>
-
-<div class="grid2">
- <div class="card">
- <strong>Human CLI — Rich panels</strong>
- <p style="font-size:14px;color:var(--ink-dim);margin:8px 0 0">Every <code>handle_*</code> function builds its panel through one shared <code>display_error_panel()</code> helper — red banner, structured fields, <code>user_action</code> tip, doc/Discord links. Exception-specific logic stays in the handler; the panel shape lives in one place.</p>
- </div>
- <div class="card">
- <strong>Agent CLI — JSON / Markdown</strong>
- <p style="font-size:14px;color:var(--ink-dim);margin:8px 0 0"><code>run</code> / <code>validate</code> / <code>init</code> / <code>models</code> / <code>doctor</code> / <code>check-model</code> default to <strong>markdown</strong>, with <code>--format json</code> available. The format is set once per invocation via a <code>ContextVar</code>, so the error path inherits it without threading an argument through.</p>
- </div>
-</div>
-
-<p>The agent JSON error payload is the structured shape downstream agents parse:</p>
-<div class="code">
- <div class="filename">agent CLI — JSON error payload</div>
-<pre><span class="ctx">{</span>
-<span class="ctx"> "error": true,</span>
-<span class="ctx"> "error_type": "LLMCompletionError",</span>
-<span class="ctx"> "message": "...",</span>
-<span class="ctx"> "hint": "...",</span>
-<span class="ctx"> "retryable": true,</span>
-<span class="ctx"> "error_domain": "runtime",</span>
-<span class="ctx"> "error_category": "transient",</span>
-<span class="ctx"> "model": "gpt-4o",</span>
-<span class="ctx"> "provider": "openai",</span>
-<span class="ctx"> "error_source": ["LLMCompletionError @ .../worker.py:152 (in _gen_text)"]</span>
-<span class="ctx">}</span>
-</pre>
-</div>
-
-<p><strong>HTTP-status mapping lives in the library.</strong> <code>pipelex</code> has no API server, but <code>pipelex-relay</code> and <code>pipelex-back-office</code> both render an <code>ErrorReport</code> as an HTTP response — and were reinventing the mapping. It now lives once in <code>base_exceptions.py</code>: <code>error_domain_to_http_status()</code> is the pure table, <code>ErrorReport.http_status</code> layers the provider-429 passthrough on top. Downstream FastAPI handlers become a trivial adapter and must not redefine the contract.</p>
-
-<!-- ================================================================ -->
-<h2 id="tests"><span class="num">09</span>Testing</h2>
-<p class="section-sub">What proves the system behaves — and what stops it rotting.</p>
-
-<table>
- <thead><tr><th>Test layer</th><th>What it locks in</th></tr></thead>
- <tbody>
- <tr><td><strong>Per-worker classification</strong></td><td>Mocks each SDK to raise every typed exception; asserts the resulting <code>CogtError</code> has the expected <code>error_category</code>, <code>user_action</code>, <code>provider_metadata</code>.</td></tr>
- <tr><td><strong><code>instructor</code> unwrap</strong></td><td>One end-to-end test per provider against real <code>instructor.from_*(…)</code> so the unwrap can't silently rot if <code>instructor</code>'s wrapping shape changes.</td></tr>
- <tr><td><strong>Full-chain snapshot</strong></td><td>Builds a pipeline where one pipe fails, runs the agent CLI, asserts the JSON carries the classification + an <code>error_source</code> chain in order. Catches a wrapper silently swallowing <code>error_category</code>.</td></tr>
- <tr><td><strong>Local / Temporal parity</strong></td><td>Runs the same pipe locally and on the in-process Temporal server; asserts an <em>identical</em> <code>ErrorReport</code>. Parity holds by construction.</td></tr>
- <tr><td><strong>Dict drift-detection</strong></td><td>Walks the <code>PipelexError</code> hierarchy and asserts every subclass is covered by class-level metadata <em>or</em> a fallback dict entry — closes the "silent breakage when a class is renamed" failure mode.</td></tr>
- </tbody>
-</table>
-
-<!-- ================================================================ -->
-<h2 id="open"><span class="num">10</span>What's still open</h2>
-<p class="section-sub">Deliberately scoped out — flagged here so review doesn't treat it as missing.</p>
-
-<p>The bulk of the work has landed. One item remains, intentionally left for after this branch:</p>
-
-<div class="card">
- <strong>Metadata-model long tail</strong> <span class="pill open">Partial</span>
- <p style="margin:8px 0 0;font-size:14.5px">A handful of <code>CogtError</code> subclasses still carry no class-level <code>error_category</code>, and several non-inference <code>PipelexError</code> subclasses still rely on the <code>agent_output.py</code> fallback dicts for <code>hint</code> / <code>error_domain</code> rather than class-level metadata. The drift-detection test already enforces coverage one way or the other — the migration just moves entries onto the classes. See the Followups in <code>track-metadata-model.md</code>.</p>
-</div>
-
-<p style="margin-top:24px">Everything else — the metadata model, worker classification, retry &amp; resilience, CLI delivery, the Temporal bridge, and the test coverage — is landed and described in current-state terms in the track docs.</p>
-
-<div class="callout">
- <span class="lbl">Suggested review path</span>
- Start with <code>wip/error-handling/README.md</code> (status table + read order), then <code>architecture.md</code> (layer model, hierarchy, <code>ErrorReport</code> shape). Each <code>track-*.md</code> is a self-contained concern — read them in any order. Completed plans are archived under <code>archive-*.md</code> for their running notes.
-</div>
-
-<div class="footer">
- <p><span class="tag">briefing</span> &nbsp; Co-developer review entry point: <code>TODOS.md</code>. Source of truth: <code>wip/error-handling/</code> (track docs) and <code>docs/under-the-hood/error-model.md</code> (shipped user-facing doc). This page summarizes; the track docs are authoritative.</p>
-</div>
-
-</div>
-</body>
-</html>
diff --git a/wip/error-handling/post-pr933-followups-code-review.md b/wip/error-handling/post-pr933-followups-code-review.md
deleted file mode 100644
index c78cbbef9..000000000
--- a/wip/error-handling/post-pr933-followups-code-review.md
+++ /dev/null
@@ -1,328 +0,0 @@
-# `/code-review` findings — `feature/post-pr933-followups`
-
-Output of a 5-angle `/code-review` pass over the branch
-`feature/post-pr933-followups` (stacked on `feature/API-readiness-2`, 12 commits
-of `2409f78d..464d48c0`). The branch landed Phases A/B/C/D of
-[`./post-pr933-review-followups.md`](./post-pr933-review-followups.md).
-
-None of these are blocking, but each warrants a user decision before the branch
-opens as a PR. The list is ranked most-severe first.
-
-## How to start (cold start)
-
-1. Read [`./post-pr933-review-followups.md`](./post-pr933-review-followups.md)
- first — it explains the four phases (test backfill, refactors, cleanup,
- STRICT-disclosure feature) the review pass targeted. The Session log at the
- bottom shows the 12 commits.
-2. Read this file's findings in order; each names the exact `file:line`, the
- trigger, and the suggested action. Most need a yes/no from the user before
- acting.
-3. Branch state: `feature/post-pr933-followups` stacks on `feature/API-readiness-2`.
- Wait for PR #933 to merge before opening a PR for this branch; rebase onto
- `dev` at that point.
-4. Make any agreed changes as fresh commits on top — do NOT rewrite history of
- the 12 phase commits (they are coherent commit-by-commit).
-
-## Ground rules
-
-- `make agent-check` after every code change. `make agent-test` before pushing.
-- Same project rules as the parent plan: no backward-compat shims, one
- `TestClass` per module, `pytest-mock` (`MockerFixture`) not `unittest.mock`,
- StrEnum never `.value`. See `.claude/rules/python-standards.md` and
- `.claude/rules/pytest-standards.md`.
-
----
-
-## Finding 1 — CHANGELOG.md is stale on STRICT behavior
-
-**File**: `CHANGELOG.md:9` (Unreleased section)
-
-**What**: The Unreleased entry under `### Added` for
-`ErrorReport.to_problem_document()` / `DisclosureMode` still states:
-
-> `STRICT` always drops `provider` / `model` / `provider_metadata`
-
-This is **no longer true** as of the last commit on this branch
-(`75dfa941 fix(errors): preserve curated provider_metadata subset under STRICT
-disclosure`). STRICT now drops only `provider` / `model` and projects
-`provider_metadata` through a curated subset containing `status_code` and
-`retry_after_seconds`.
-
-**Why it matters**: downstream consumers (`pipelex-api`, `pipelex-relay`,
-third-party SDKs) reading the CHANGELOG to learn the STRICT wire-format
-contract will decide they never see `provider_metadata` on STRICT payloads,
-then break or silently mis-render when the curated subset arrives.
-
-**Suggested action** (low-risk, just doc):
-
-Update the CHANGELOG line to read something like:
-
-> `STRICT` drops `provider` / `model` and projects `provider_metadata` through
-> a curated subset (only `status_code` and `retry_after_seconds` — actionable
-> HTTP client hints, not provider attribution).
-
-**Out-of-repo cousin**: the same stale claim appears in
-`pipelex-api/wip/error-handling/pipelex-changes.md:137`. That repo is separate
-— fix it in a follow-up there, but flag it in this PR's description so the
-pipelex-api maintainers can pick it up.
-
-**Decision needed**: just `do it` / `not yet`. No design ambiguity.
-
----
-
-## Finding 2 — `error_category` type drift via `model_copy` skipping validation
-
-**File**: `pipelex/cogt/exceptions.py:96-104`
-
-**What**: The Phase B.3 refactor switched `CogtError.to_error_report` from
-constructor-build to `super().to_error_report()` + `model_copy(update={...})`.
-`model_copy` does **not** re-run Pydantic field validators by default. As a
-result:
-
-- **Fresh path**: `CogtError(error_category=InferenceErrorCategory.CAPACITY).to_error_report()`
- → `report.error_category` is an `InferenceErrorCategory` enum instance.
-- **Round-trip path**: `ErrorReport.model_validate(report.model_dump())`
- → `report.error_category` is plain `str` (`"capacity"`).
-
-The OLD constructor path always coerced through `ErrorReport`'s field validator
-(`error_category: str | None`), so both paths produced `str` and reports were
-type-identical.
-
-**Why it matters**: `InferenceErrorCategory` is a `StrEnum`, so `isinstance(x,
-str)`, equality, and JSON serialization all behave the same either way. The
-only observable difference is `type(x) is str` (False fresh, True
-round-tripped) — which is an anti-pattern, and the codebase doesn't appear to
-have any such check today. So **no current consequence** — but it is a latent
-asymmetry the OLD code did not have, and any future contributor doing strict
-type-identity checks (or comparing reports across the serialization boundary
-for equality) will be surprised.
-
-**Suggested action** (one-line fix):
-
-Pass `validate=True` to `model_copy`:
-
-```python
-return base_report.model_copy(
- update={...},
- validate=True, # restore the constructor-path coercion symmetry
-)
-```
-
-Same edit applies to `pipelex/base_exceptions.py:_enrich_error_report_from_cause`
-(`report.model_copy(update={...})`) for the same reason. The Pydantic 2.x
-`validate=True` kwarg re-runs field validators on the updated values.
-
-**Decision needed**: do you want the fresh/round-tripped symmetry restored
-(safe, defensive), or leave it (current behavior, faster by a few microseconds,
-StrEnum-equality makes it invisible to all current callers)?
-
----
-
-## Finding 3 — STRICT redacted branch leaks `status_code` from cause
-
-**File**: `pipelex/base_exceptions.py:236-243`
-
-**What**: When a wrapper `PipelexError` is raised `from` a `CogtError` that
-carries `provider_metadata`, the cause-chain enrichment copies
-`provider_metadata` onto the wrapper's `ErrorReport`. The Phase D.1 STRICT
-projection then keeps the curated subset (`status_code` /
-`retry_after_seconds`) on the **redacted** branch — even though the wrapper's
-`error_type` (e.g. `PipelexUnexpectedError`) doesn't otherwise disclose any
-provider relationship.
-
-Concrete scenario:
-
-```python
-raise PipelexUnexpectedError("internal invariant violated") from CogtError(
- "openai returned 500",
- provider_metadata=ProviderErrorMetadata(provider=OPENAI, status_code=500, ...),
-)
-```
-
-Wire payload (STRICT):
-
-```json
-{
- "error_type": "PipelexUnexpectedError",
- "title": "Unexpected internal error",
- "type_uri": ".../pipelex-unexpected-error/",
- "error_domain": "runtime",
- "detail": "An internal error occurred.",
- "provider_metadata": {"status_code": 500}
-}
-```
-
-The consumer learns "some upstream returned HTTP 500" from an `error_type`
-that advertises no provider relationship.
-
-**Why it matters**: the Phase D.1 design discussion was framed around the
-canonical 429-with-`Retry-After` case where the consumer *needs* the hint. On
-the redacted branch (where the message is replaced and `user_action` is
-dropped), surfacing a 5xx status from a wrapped provider call may surprise
-ops/security reviewers. By the design call's rationale, this is acceptable
-(`status_code` is not provider attribution); by the strictest reading of "an
-external surface should learn nothing about internal failure topology", it
-arguably is.
-
-**Suggested action** (three options):
-
-- **3a (leave as-is, document)**: this is the documented Phase D.1 Option 1
- behavior. Add a paragraph to the `DisclosureMode.STRICT` docstring at
- `pipelex/base_exceptions.py:79-106` calling out the cause-inheritance behavior
- so future readers don't think it's an oversight.
-- **3b (narrow to 429 only)**: only emit `status_code` / `retry_after_seconds`
- on the STRICT redacted branch when the underlying `error_category` is
- retryable (or when `status_code == 429`). Preserves the actionable-hint use
- case while keeping internal 5xx topology hidden.
-- **3c (redacted branch drops `provider_metadata` entirely; caller-facing keeps
- curated subset)**: matches the original "STRICT redacts non-caller-facing"
- framing more tightly — caller-facing errors get the HTTP hint, redacted
- errors get nothing.
-
-**Decision needed**: which of 3a/3b/3c. Default to 3a if no concern.
-
----
-
-## Finding 4 — STRICT no longer round-trips through `ErrorReport.from_dict`
-
-**File**: `pipelex/base_exceptions.py:243` (the curated `provider_metadata`
-return), `pipelex/base_exceptions.py:306` (`from_dict`)
-
-**What**: The curated `provider_metadata` dict on a STRICT payload only
-contains `status_code` and `retry_after_seconds`. `ProviderErrorMetadata`
-requires `provider` and `sdk_exception_type`, so `ErrorReport.from_dict(strict_payload)`
-now raises `pydantic.ValidationError`.
-
-The OLD behavior (pre-Phase-D.1) was that STRICT dropped `provider_metadata`
-entirely, so `from_dict` still succeeded — producing an `ErrorReport` with
-`provider_metadata=None` and a redacted message. The Phase D.1 commit
-explicitly rewrote `test_strict_does_not_round_trip` to read fields off the
-dict directly rather than rehydrate, masking the regression in the test
-suite.
-
-**Why it matters**: no in-repo consumer does `from_dict(strict_payload)` (the
-pipelex-api consumes the dict directly via `to_problem_document`), so this is
-not a regression for known callers. But it is a sharper failure mode than the
-existing "STRICT is lossy" framing suggested. Out-of-repo consumers that
-previously could leniently rehydrate a STRICT payload now get a hard pydantic
-ValidationError.
-
-**Suggested action** (two options):
-
-- **4a (document and accept)**: add a `!!! warning` block to the
- `DisclosureMode.STRICT` docstring explicitly stating "STRICT payloads cannot
- be passed to `ErrorReport.from_dict()` — consume the dict directly." Pin the
- behavior with a unit test that asserts `ErrorReport.from_dict(strict_payload)`
- raises `ValidationError`. Worth mentioning in the PR description so
- pipelex-api / pipelex-relay maintainers can verify they don't have a lenient
- rehydration codepath.
-- **4b (make `provider` / `sdk_exception_type` Optional on
- `ProviderErrorMetadata`)**: restores lenient round-trip. Cost: every
- downstream test that asserts `metadata.provider == "google"` keeps working
- (workers always populate), but pyright now sees the fields as
- `ProviderName | None` and may flag a few additional `assert metadata.provider
- is not None` sites. Searched: `grep -rn 'provider_metadata\.provider\|provider_metadata\.sdk_exception_type' --include='*.py' pipelex/` returned zero production-code matches — all hits are in test files that work on freshly-raised errors. Type impact is bounded.
-
-**Decision needed**: 4a (sharper failure, document it) or 4b (lenient
-round-trip, semi-Optional fields). Prefer 4a unless an external consumer is
-known to do round-trip.
-
----
-
-## Finding 5 — `_translate_to_validate_bundle_error` doesn't cover `load_concepts_only*`
-
-**File**: `pipelex/pipeline/validate_bundle.py` — helper at line ~34, used by
-`validate_bundle` (line ~84) and `validate_bundles_from_directory` (line ~143),
-but NOT by `load_concepts_only` (line ~200) or `load_concepts_only_from_directory`
-(line ~290).
-
-**What**: The Phase C.2 commit extracted the six-handler cascade into
-`_translate_to_validate_bundle_error()` and updated the two `validate_bundle*`
-call sites. The two `load_concepts_only*` functions kept their separate (smaller,
-2-handler — `PipelexInterpreterError` + `ValidationError`) inline cascades.
-
-**Why it matters**: this is a partial refactor. A future contributor adding a
-new error type to the shared helper (say, wrapping a `LibraryManagerError`
-translation) gets it picked up for `validate_bundle*` but silently misses it
-for `load_concepts_only*`. The helper's docstring calls itself "single source
-of truth" — which is misleading.
-
-**Suggested action** (three options):
-
-- **5a (extract a second helper)**: add a sibling
- `_translate_to_validate_bundle_error_concepts_only()` covering the smaller
- 2-handler cascade, used by both `load_concepts_only*` functions.
-- **5b (one helper, broader)**: extend the existing helper to be safe for the
- concepts-only path (the four handlers it carries beyond
- `PipelexInterpreterError` + `ValidationError` never fire there anyway). Use
- the same context manager in all four call sites. Lowest duplication.
-- **5c (do nothing, just rename helper)**: rename the helper to
- `_translate_full_bundle_errors_to_validate_bundle_error` to clarify it
- covers only the full-validation paths, and add a one-line comment on each
- `load_concepts_only*` cascade pointing at it.
-
-**Decision needed**: 5a / 5b / 5c. Probably 5b is cleanest (one source of
-truth, smaller diff), 5c is the minimal change.
-
----
-
-## Finding 6 — `_RequestIdLog._logger` is type-erased; subclass forgetting `_logger` crashes at runtime
-
-**File**: `pipelex/temporal/log_temporal.py:47` (the `ClassVar[Any]`
-declaration on the base)
-
-**What**: Phase B.1 hoisted the severity methods onto `_RequestIdLog` and
-declared `_logger: ClassVar[Any]` with no default. Each subclass
-(`WorkflowLog`, `ActivityLog`) sets `_logger = workflow.logger` / `activity.logger`.
-
-If a future contributor adds a third subclass (or refactors and accidentally
-drops the `_logger` assignment), pyright cannot catch it because the type is
-`Any`. The class instantiates fine, then crashes with
-`AttributeError: NewLog has no attribute '_logger'` on the first
-`.info()` / `.debug()` / etc. call.
-
-**Why it matters**: low likelihood today (only two subclasses exist, both in
-the same file), but the typing is doing zero work. If you mean for the base to
-be "extension-safe", make the typing reflect it.
-
-**Suggested action** (two options):
-
-- **6a (tighten the type)**: change to `ClassVar[logging.LoggerAdapter]` and
- remove `Any`. Forces every subclass to declare a `LoggerAdapter` explicitly;
- pyright catches a missing assignment.
-- **6b (enforce via `__init_subclass__`)**: add an `__init_subclass__` on
- `_RequestIdLog` that raises `TypeError` if the subclass doesn't define
- `_logger` in its own `__dict__`. Catches the gap at class-definition time
- rather than first severity call.
-- **6c (do nothing)**: only two subclasses ever, both in the same file —
- YAGNI.
-
-**Decision needed**: 6a / 6b / 6c. Probably 6c unless `_RequestIdLog` is
-expected to gain more subclasses.
-
----
-
-## Decisions
-
-Record each decision here as it is taken, with date and rationale.
-
-- **2026-05-24 — Finding 1: Update CHANGELOG now.** Replaced the stale `STRICT always drops provider / model / provider_metadata` claim in `CHANGELOG.md` `[Unreleased]` with the curated-subset wording. Pure doc fix; the stale claim would have misled downstream consumers (pipelex-api, pipelex-relay, third-party SDKs) reading the CHANGELOG to learn the STRICT wire-format contract. The stale claim in `pipelex-api/wip/error-handling/pipelex-changes.md:137` (out of repo) is flagged for the pipelex-api maintainers in the PR description but not fixed here.
-- **2026-05-24 — Finding 2: Leave as-is.** The finding's suggested fix (`model_copy(update=..., validate=True)`) does not exist in Pydantic 2.13.4 (signature is `(self, *, update, deep)`). The real workaround — `cls.model_validate({**self.model_dump(), **update})` — is heavier (full re-validation, deep submodel rebuild) and inconsistent with the rest of the codebase, which uses `model_copy(update=...)` extensively without re-validation. The asymmetry the finding flagged (`error_category` is enum on fresh path, plain `str` on round-trip) is invisible to every current caller because `InferenceErrorCategory` is a `StrEnum` — `isinstance`, `==`, and JSON serialization all behave identically. Only `type(x) is str` differs, and the codebase has no such strict-identity checks. Revisit if a future contributor introduces one.
-- **2026-05-24 — Finding 3: 3a — Document only.** Added a paragraph to the `DisclosureMode.STRICT` docstring explaining that the curated `provider_metadata` subset IS inherited up the `__cause__` chain via `_enrich_error_report_from_cause` and is preserved on both STRICT branches — including the redacted branch when a domain-less wrapper (e.g. `PipelexUnexpectedError`) is raised from a categorized `CogtError`. By the same reasoning as the existing path-leak-shield disclaimer, this is deliberate: `status_code` / `retry_after_seconds` are HTTP client hints, not provider attribution, and STRICT is a classification-projection, not a topology-hiding shield. 3b (narrow to retryable / 429) and 3c (redacted branch drops `provider_metadata` entirely) were rejected as inconsistent with the Phase D.1 design call.
-- **2026-05-24 — Finding 4: 4a — Document + pin with test.** Added a paragraph to the `DisclosureMode.STRICT` docstring stating that STRICT payloads carrying `provider_metadata` cannot be rehydrated via `ErrorReport.from_dict` (the curated subset lacks the required `provider` / `sdk_exception_type` fields on `ProviderErrorMetadata`, so rehydration raises `pydantic.ValidationError`). Pinned the behavior with a new test `test_strict_payload_with_provider_metadata_fails_from_dict_rehydration` in `tests/unit/pipelex/test_error_report_disclosure_mode.py`. STRICT was already documented as a lossy projection; this is a sharper failure mode external consumers should know about. The pipelex-api / pipelex-relay maintainers should verify they don't have a lenient rehydration codepath — flagged for the PR description. 4b (make `provider` / `sdk_exception_type` Optional on `ProviderErrorMetadata`) was rejected: the spec-correct projection is to consume the dict directly, and weakening the model would propagate Optionality into every test that asserts on those fields.
-- **2026-05-24 — Finding 5: 5b — Extend existing helper, use in all 4 call sites.** Refactored `pipelex/pipeline/validate_bundle.py` so `load_concepts_only` and `load_concepts_only_from_directory` now wrap their bodies in `with _translate_to_validate_bundle_error():` — single source of truth across all four entry points. The four pipe-loading / dry-run handlers (`PipeFactoryError`, `PipeValidationError`, `PipeRunError`, `DryRunError`) are dead code in the concepts-only paths but harmless, since those functions never instantiate pipes or run dry runs. Updated the helper's docstring to note this. Removed the now-redundant inline 2-handler cascades in both `load_concepts_only*` functions. 5a (separate helper) rejected as duplication; 5c (rename + comment) rejected as not actually fixing the partial refactor.
-- **2026-05-24 — Finding 6: 6c — Do nothing.** YAGNI. Only two subclasses of `_RequestIdLog` exist today (`WorkflowLog`, `ActivityLog`), both in the same module. Tightening the `ClassVar[Any]` type or enforcing via `__init_subclass__` adds machinery for a hypothetical failure mode. If a third subclass is ever added, the AttributeError on first severity call would surface immediately in any test exercising it. Revisit then.
-
-## Session log
-
-### 2026-05-24 — Code-review follow-ups landed
-
-- **All six findings resolved** as single commits per fix-bearing finding (F1 / F3 / F4 / F5). F2 and F6 are no-op "leave as-is" decisions, recorded above without code changes.
- - **F1 (CHANGELOG)**: `CHANGELOG.md` `[Unreleased]` line on STRICT behavior rewritten to reflect the curated-subset projection.
- - **F3 + F4 (docstring + test)**: `DisclosureMode.STRICT` docstring at `pipelex/base_exceptions.py:79-130` extended with two paragraphs — (a) the curated `provider_metadata` subset is inherited up the `__cause__` chain and preserved on both STRICT branches, including when a domain-less wrapper sits between caller and provider; (b) STRICT payloads carrying `provider_metadata` cannot be rehydrated through `from_dict`. Added a new test `test_strict_payload_with_provider_metadata_fails_from_dict_rehydration` in `tests/unit/pipelex/test_error_report_disclosure_mode.py` pinning the rehydration failure.
- - **F5 (validate_bundle refactor)**: `pipelex/pipeline/validate_bundle.py` — `load_concepts_only` (line ~218) and `load_concepts_only_from_directory` (line ~278) now share the `_translate_to_validate_bundle_error` context manager with `validate_bundle*`. Helper docstring updated to reflect the new 4-call-site coverage. Inline 2-handler cascades removed from both concepts-only functions.
-- **Status**: `make agent-check` clean (0 errors, 0 warnings, 0 informations on pyright; mypy clean on 1905 source files). Targeted tests pass: 50 tests in `test_error_report_disclosure_mode.py` / `test_error_report_problem_document.py` / `test_load_concepts_only.py`; 55 tests in CLI + validation-related suites; 865 tests across `tests/unit/pipelex/exceptions/` and `tests/unit/pipelex/cogt/`.
-- **Two doc carryovers for the PR description**:
- - The stale STRICT claim in `pipelex-api/wip/error-handling/pipelex-changes.md:137` mirrors the one fixed in this branch's CHANGELOG. That repo is separate — flag for pipelex-api maintainers.
- - STRICT payloads with `provider_metadata` no longer rehydrate via `from_dict`. No in-repo consumer does round-trip on STRICT payloads (pipelex-api consumes the dict directly via `to_problem_document`), but the F4 pinning test now makes the failure mode explicit. Worth a heads-up so downstream maintainers can verify they don't have a lenient rehydration codepath.
-- **Next action**: this file is complete. The branch `feature/post-pr933-followups` is ready for PR once `feature/API-readiness-2` (PR #933) lands and the branch can rebase onto `dev`. Open the PR with both doc carryovers in the description.
diff --git a/wip/error-handling/post-pr933-review-followups.md b/wip/error-handling/post-pr933-review-followups.md
deleted file mode 100644
index 918549023..000000000
--- a/wip/error-handling/post-pr933-review-followups.md
+++ /dev/null
@@ -1,437 +0,0 @@
-# TODOs — Post-PR #933 `/review` follow-ups
-
-Lower-priority items left over from the pre-landing `/review` pass on
-`feature/API-readiness-2` (PR #933 — error-handling overhaul, TODOS Phases 0–7).
-None of these block the PR — they were either pre-existing items the reviewer
-flagged per the "see something, say something" rule, or refinements that didn't
-warrant action in the same commit series. Sequenced here so a fresh session can
-land them coherently.
-
-The original plan was [`../../TODOS.md`](../../TODOS.md). This file is its
-post-merge tail.
-
-## Branch setup
-
-- Cut a new branch from `dev` **after PR #933 has merged**. Every section below
- references files in their post-#933 locations (Phase 6 moved many error classes
- into `exceptions.py` / `*_exceptions.py`). If #933 has not merged yet, branch
- from `feature/API-readiness-2`.
-
-## How to start (cold start)
-
-1. Read this whole file. It is self-contained — every item names the exact
- file:line, the symptom, and a recommended fix.
-2. Resume at the first unchecked box. Phases are independent; pick the one that
- matches the available time budget (Phase A is the smallest, Phase D is a
- judgment call worth opening with the user).
-3. Respect the ⛔ CHECKPOINT markers — they are hard stops.
-
-## Ground rules
-
-- `make agent-check` after every code change. `make agent-test` before every
- checkpoint.
-- No backward-compat shims. Per project policy.
-- One `TestClass` per test module; use `pytest-mock` (`MockerFixture`), not
- `unittest.mock`. See `.claude/rules/pytest-standards.md`.
-- StrEnum rule: never `enum_var.value`, just `{enum_var}`. See
- `.claude/rules/python-standards.md`.
-
----
-
-## Phase A — Test coverage backfill
-
-The `/review` pass flagged six gaps where observable behavior is not pinned by a
-test. None of these are bugs today; they are regression nets for future
-refactors. Land as a single test-only commit.
-
-### A.1 — `WfPipeRouter` `request_id` binding has no integration test
-
-Only `WfPipeRun` is covered, by
-`tests/integration/pipelex/temporal/test_wf_pipe_run_request_id_logging.py`. The
-router-side wiring at `pipelex/temporal/tprl_pipe/wf_pipe_router.py:33` (the
-per-invocation `workflow_log = WorkflowLog(request_id=workflow_arg.job_metadata.request_id)`)
-can break — reverting to the module-level singleton, wrong attribute path —
-without any test failing.
-
-- [x] Add `tests/integration/pipelex/temporal/test_wf_pipe_router_request_id_logging.py`
- mirroring `test_wf_pipe_run_request_id_logging.py`: register `WfPipeRouter`
- under a worker with a failing inner pipe stub, dispatch with a
- `request_id` on `job_metadata`, capture the `temporalio.workflow` logger,
- assert at least one record carries `record.request_id == "<expected>"`.
-- [x] Verify the test has teeth by temporarily reverting the `WorkflowLog(request_id=...)`
- construction to the unbound module singleton — the test must fail with
- `request_ids seen: ['None']`. Restore.
-
-### A.2 — `caller_facing_message` inheritance contract pin
-
-`pipelex/base_exceptions.py:317` documents that `_authors_caller_facing_message`
-"is consulted by plain attribute access, so it inherits normally — a subclass
-of a caller-facing error stays caller-facing." This is deliberately different
-from `_declared_title` / `_declared_type_uri` (which use `cls.__dict__` to
-bypass inheritance). The contract has no test pinning it; a future refactor
-swapping the flag to `cls.__dict__` access would silently downgrade STRICT
-disclosure for every `PipelexInterpreterError` / `ValidateBundleError`
-subclass.
-
-- [x] In `tests/unit/pipelex/exceptions/test_class_level_metadata.py`, add a
- parametrized case defining an inline subclass of `PipelexInterpreterError`
- and asserting its `to_error_report().caller_facing_message is True`.
- Mirror with a `ValidateBundleError` subclass.
-
-### A.3 — Empty-message fallback in `recover_error_report` not tested
-
-`pipelex/temporal/tprl/temporal_error.py:118` reads
-`recovered_message = report_dict.get("message") or _message_from_exc(exc)` — the
-`or` falls through to the exception-chain walk when the report dict's `message`
-is empty or whitespace. Only the truthy-message branch is pinned today; a
-regression swapping `or` to `??` / `is None` would silently emit
-`[error report failed schema validation]` with an empty preamble.
-
-- [x] In `tests/unit/pipelex/temporal/test_recover_error_report.py`, add a
- `test_invalid_report_with_empty_message_falls_back_to_exc_chain` that
- constructs the same 4-required-key payload as
- `test_found_but_invalid_report_dict_synthesizes_unrecoverable` but with
- `"message": ""`, and asserts the synthesized report's message contains
- both the underlying `ApplicationError` text and `"schema validation"`.
-
-### A.4 — Force-load multi-failure aggregation contract not pinned
-
-`pipelex/errors/error_pages_generator.py:80-98` aggregates per-module import
-failures and raises one `RuntimeError` listing all of them. The existing test
-`test_force_load_aggregates_non_import_error_failures` only asserts that the
-**first** module's name appears in the message. A regression that re-raises on
-the first failure (instead of accumulating) would still pass.
-
-- [x] In `tests/unit/pipelex/errors/test_error_pages_generator.py`, add
- `test_force_load_walk_continues_past_first_failure` that patches
- `importlib.import_module` with a `side_effect` callable failing every
- call, then asserts at least 2 distinct dotted module names appear in the
- raised `RuntimeError.args[0]`. Remember to `_force_load_all_error_modules.cache_clear()`
- in a try/finally.
-
-### A.5 — Webhook FAILED + `error_report=None` edge: assert `error` key is absent
-
-The current `_notify_webhook` (`pipelex/pipe_run/delivery_executor.py:259`)
-only writes `payload["error"]` when `error_report is not None`. The COMPLETED
-case is pinned by `test_webhook_omits_error_when_report_is_none`, but the
-FAILED case is not — a future regression defaulting `error` to `{}` on FAILED
-would slip through.
-
-- [x] In the relevant test (`tests/unit/pipelex/pipe_run/test_delivery_executor.py`),
- add a case dispatching `_notify_webhook` with `status=FAILED` and
- `error_report=None`, then `assert "error" not in payload`.
-
-### A.6 — `WebhookTarget` validator runs construction-only
-
-`pipelex/pipe_run/delivery_assignment.py:30-48`'s `_reject_reserved_keys`
-runs at construction time only — there is no `validate_assignment=True` on the
-model, so a post-construction `webhook.payload["status"] = "x"` bypasses the
-validator. `_notify_webhook` `dict(webhook.payload)` shallow-copies before
-override, so the wire payload is safe today, but the contract is implicit.
-
-- [x] Add `test_reserved_key_check_runs_only_at_construction`: construct a
- clean `WebhookTarget`, mutate `webhook.payload["status"] = "x"` in place,
- assert no `ValidationError` is raised. Pins the construction-only
- contract explicitly so a future `validate_assignment=True` toggle gets
- caught as a behavior change.
-
-### Acceptance
-
-`make agent-check` clean; `make agent-test` clean. Six new test cases or
-methods land, one regression net per gap. Each has been verified to have teeth
-(temporarily breaking the production code makes the test fail).
-
-### ⛔ CHECKPOINT A — STOP, verify, record
-
-- [x] `make agent-check` and `make agent-test` clean.
-- [x] Commit as a single test-only commit.
-- [x] Append a dated entry to the Session log below.
-
----
-
-## Phase B — Maintainability refactors
-
-Four small refactors the reviewer flagged. Each is an isolated improvement; do
-them in any order. Land as a small ordered series (one commit per refactor) so
-each is independently reviewable.
-
-### B.1 — Factor the `WorkflowLog` / `ActivityLog` severity duplication
-
-`pipelex/temporal/log_temporal.py:56-131` declares 14 nearly-identical severity
-methods across `WorkflowLog` and `ActivityLog`. They differ only by which
-logger they target (`workflow.logger` vs `activity.logger`) and a docstring
-substring ("in a workflow" vs "in an activity"). Every new severity level must
-be added in two places.
-
-- [x] Move the seven severity methods (`verbose` / `debug` / `dev` / `info` /
- `warning` / `error` / `critical`) onto the `_RequestIdLog` base. Add an
- abstract `_logger` property (or ClassVar) that each subclass overrides
- to point at `workflow.logger` or `activity.logger`. Each method becomes
- a one-liner: `self._logger.log(level=..., msg=content, extra=self._build_extra())`.
-- [x] Verify both `WorkflowLog` and `ActivityLog` still satisfy the protocols
- expected by their existing call sites — the public method set is
- unchanged.
-- [x] `tests/unit/pipelex/temporal/test_log_temporal_request_id.py` parametrizes
- over all seven severity methods — it should keep passing without
- modification.
-
-### B.2 — Hoist `[error report failed schema validation]` to a module constant
-
-`pipelex/temporal/tprl/temporal_error.py:119` builds the fallback message
-inline. The marker is referenced as a stable contract in the function's
-docstring and in `docs/under-the-hood/error-model.md`. Anything that wants to
-detect the schema-validation fallback on the wire (a test, an ops dashboard,
-the documentation) must duplicate the literal string.
-
-- [x] Add `_ERROR_REPORT_VALIDATION_FAILED_MARKER = "[error report failed schema validation]"`
- at module scope in `pipelex/temporal/tprl/temporal_error.py`. Use it in
- the f-string. Update `tests/unit/pipelex/temporal/test_recover_error_report.py`
- (the `test_found_but_invalid_report_dict_synthesizes_unrecoverable` case)
- to import and reference the constant instead of the substring
- `"schema validation"` — pins the exact marker rather than a substring.
-
-### B.3 — Switch `_enrich_error_report_from_cause` to `model_copy(update=...)`
-
-`pipelex/base_exceptions.py:393-434` rebuilds the entire `ErrorReport` via the
-constructor with 12 kwargs — 5 copied verbatim from `report`, 7 merged via
-`or` from `cause_report`. The five "wrapper-wins" kwargs duplicate the
-docstring; a new wrapper-wins field on `ErrorReport` would require editing this
-list too.
-
-- [x] Refactor to `return report.model_copy(update={...})` with just the
- cause-merged classification fields. Matches the pattern already in use
- at `pipelex/pipeline/exceptions.py:43-49` (`PipelineExecutionError.to_error_report`).
-- [x] Same refactor opportunity in `pipelex/cogt/exceptions.py:87-103`
- (`CogtError.to_error_report` override duplicates 11 of the same
- constructor kwargs to add four CogtError-only fields). Switch to
- `super().to_error_report()` (which runs cause-chain enrichment) followed
- by `.model_copy(update={...})` with just the CogtError-specific fields.
-- [x] No observable behavior change. Existing tests must keep passing.
-
-### B.4 — OpenAI/VertexAI title-suffix consistency
-
-`pipelex/plugins/openai/openai_exceptions.py:6-15` declares `_declared_title`
-values that drop the trailing "error" / "failed" word that every other curated
-title uses (`"AI inference failed"`, `"Library error"`, `"TOML parse error"`,
-etc.). The RFC 7807 `title` field is consumer-facing.
-
-- [x] Pick the dominant convention (keep the trailing "error" / "failed") and
- apply it to OpenAI + VertexAI:
- - `OpenAIClientFactoryError._declared_title = "OpenAI client factory error"`
- (was `"OpenAI client factory"`).
- - `VertexAIConfigError._declared_title = "VertexAI configuration error"`
- (was `"VertexAI config"`).
- - `VertexAICredentialsError._declared_title = "VertexAI credentials error"`
- (was `"VertexAI credentials"`).
-- [x] Regenerate `docs/errors/` via `.venv/bin/pipelex-dev generate-error-pages`
- — the three affected pages should land with updated title frontmatter.
-- [x] If `tests/unit/pipelex/test_pipelex_error_title_and_type_uri.py` asserts
- specific title strings for these classes, update them.
-
-### Acceptance
-
-`make agent-check` clean; `make agent-test` clean. Four refactors land, each
-preserving observable behavior. Diff size reductions are visible in the affected
-files.
-
-### ⛔ CHECKPOINT B — STOP, verify, record
-
-- [x] `make agent-check` and `make agent-test` clean.
-- [x] Each refactor as its own commit.
-- [x] Append a dated entry to the Session log below.
-
----
-
-## Phase C — Pre-existing cleanup surfaced by the review
-
-These items pre-date PR #933. The pre-landing review flagged them per the
-project's "Flag and fix existing bugs" rule. They are independent of Phases
-A/B — land any time.
-
-### C.1 — Stale TODOs in `pipelex/pipeline/exceptions.py`
-
-Two TODO comments live on `ValidateBundleError`:
-
-- Line 114: `TODO: Currently not caught, but structure is prepared for future
- implementation` (about `pipe_concept_instantiation_errors`).
-- Line 128: `TODO: refactor so we don't need this anymore?` (about the
- `pipe_validation_error_data` property documented as "Backwards
- compatibility").
-
-The first never landed. The second contradicts project policy ("No backward
-compatibility").
-
-- [x] Decide with the user: land the deferred catch site for
- `pipe_concept_instantiation_errors`, or remove the unused structure.
-- [x] For the `pipe_validation_error_data` property: drop it and update callers
- (preferred per policy), or remove the "Backwards compatibility" framing
- and the TODO if the property is genuinely useful as an aggregate getter.
-
-### C.2 — Duplicate handler cascade in `pipelex/pipeline/validate_bundle.py`
-
-`validate_bundle` (lines 103-137) and `validate_bundles_from_directory`
-(lines 154-188) carry an identical six-handler `try/except` cascade
-(`PipelexInterpreterError`, `PipeFactoryError`, `PipeValidationError`,
-`ValidationError`, `PipeRunError`, `DryRunError`) — each translated into
-`ValidateBundleError(...)` with the same fields. ~70 lines of pure duplication.
-A new handler must be added in two places.
-
-- [x] Extract the handler cascade into a helper
- `_translate_validation_error_to_validate_bundle_error(exc)` (or wrap the
- try-body in a context manager) so both call sites share one source of
- truth.
-- [x] Confirm both `validate_bundle` and `validate_bundles_from_directory`
- callers still get identical `ValidateBundleError` instances after the
- refactor.
-
-### C.3 — `BaseModelPayloadConverterError` dead code
-
-`pipelex/temporal/exceptions.py:96` declares
-`BaseModelPayloadConverterError(PipelexError)` but no code imports or raises it.
-Was already dead in the previous location; the Phase 6 move surfaces the
-opportunity to either delete it or wire it into actual error sites in
-`pipelex/temporal/temporal_data_converter.py` where unexpected conversion
-failures currently surface as generic exceptions.
-
-- [x] Decide: delete the class (one less generated docs page) OR wire it into
- `temporal_data_converter.py` where it would add meaningful classification.
-
-### Acceptance
-
-Each item resolved either by landing the change or by recording a deliberate
-"leave as-is" decision in the Session log with rationale.
-
-### ⛔ CHECKPOINT C — STOP, verify, record
-
-- [x] `make agent-check` and `make agent-test` clean.
-- [x] Append a dated entry to the Session log below: which items landed, which
- were deliberately left, and why.
-
----
-
-## Phase D — Design question for the user (do not action without discussion)
-
-### D.1 — STRICT 429 strips `provider_metadata`, losing `retry_after_seconds`
-
-`pipelex/base_exceptions.py:24` strips `provider` / `model` / `provider_metadata`
-unconditionally under STRICT disclosure. But for a provider 429 (rate-limit),
-`provider_metadata.retry_after_seconds` is actionable safe data the HTTP
-adapter needs to emit a useful `Retry-After` header. Under STRICT, the
-consumer sees `status=429` with no retry-after.
-
-This is a **design call**, not a bug — STRICT was designed as
-"classification-projection, not a path-leak shield", and the trade-off is
-deliberate. But for the only HTTP-status code where the response carries an
-actionable client header (`Retry-After`), the current STRICT behavior is at
-odds with usability.
-
-Options to consider:
-
-- **Option 1.** Preserve a curated subset of `provider_metadata` (just
- `status_code` and `retry_after_seconds`) on the STRICT envelope. Minimal
- scope creep; matches the "provider attribution never belongs on an external
- surface" rule because `retry_after_seconds` is not provider attribution, it
- is a rate-limit hint.
-- **Option 2.** Surface `retry_after_seconds` as a top-level field on
- `ErrorReport`, independent of `provider_metadata`. HTTP adapters read it
- whatever the disclosure mode.
-- **Option 3.** Leave as-is. STRICT consumers that need `Retry-After` must
- upgrade to VERBOSE on internal-trust boundaries.
-
-- [x] Open this with the user. Decide. Record in the Decisions section below.
-- [x] If Option 1 or 2: implement, add a STRICT-passthrough-of-retry-after
- test, regenerate docs if the public surface changes.
-
----
-
-## Out of scope (recorded, not planned here)
-
-Items the reviewer noted but explicitly did not flag as actionable:
-
-- **VERBOSE webhook payload as default** (`pipelex/pipe_run/delivery_executor.py:251`)
- — design intent: "the receiver decides what to re-expose downstream". A
- `disclosure_mode` field on `WebhookTarget` could opt a target to STRICT, but
- that is a feature, not a fix. Revisit only if a real consumer asks for it.
-- **Direct-mode wrapping bare exceptions into webhook** (`pipelex/pipe_run/pipe_run.py:54`)
- — symmetric with Temporal mode by design (the `feedback_always_deliver_failure_notification.md`
- rule). Greptile flagged and lchoquel resolved it during PR #933.
-- **Temporal `_log_critical` / `_log_error` unbound `activity_log` / `workflow_log`**
- — explicitly deferred in TODOS Checkpoint 2 ("error-bridge helpers, no
- `job_metadata` in scope; threading `request_id` there is out of scope for
- Item B"). Closing it requires threading `job_metadata` through
- `activity_error_boundary` and `workflow_caller` exception handlers — a
- bigger refactor. Track separately if it ever becomes a blocker.
-- **Temporal wire-format version skew** — per `project_temporal_not_shipped.md`,
- Temporal hasn't shipped; rolling-deploy concerns don't apply.
-- **`_humanize_class_name` `!= "Error"` guard** — theoretical, no production
- class hits the edge.
-- **`_enrich_error_report_from_cause` O(N²) on deep chains** — chains are
- 3-5 deep in practice. Sub-microsecond. Only profile if pathological chains
- appear.
-- **`error_report_dict_from_details` sentinel-key idea** — superseded by
- Phase 7's heuristic strengthening (all four required keys must be present);
- the lookalike-dict risk window is now narrow enough that adding a sentinel
- key is over-engineering.
-
----
-
-## Decisions
-
-Record each decision here as it is taken, with date and rationale.
-
-- **2026-05-24 — C.1: Remove unused `pipe_concept_instantiation_errors` infrastructure.** Per project policy "No backward compatibility", the never-populated-in-production field on `ValidateBundleError` + the `pipe_validation_error_data` aggregate (Backwards compatibility) property were both removed. The two callers (`pipelex/cli/agent_cli/commands/agent_output.py`, `pipelex/cli/error_handlers.py`) and the test fixture in `tests/unit/pipelex/cli/test_agent_output.py` were updated. Alternative considered: land the deferred catch site for Pydantic ValidationError in the factory instantiation path — rejected as bigger scope without a concrete need from production.
-- **2026-05-24 — C.3: Delete `BaseModelPayloadConverterError`.** Never imported or raised; `temporal_data_converter.py` lets kajson failures bubble raw. Wiring the class into the converter would require adding a speculative try/except, which the project rules explicitly forbid ("Do NOT add try/except speculatively"). Cleaner to delete and regenerate the docs.
-- **2026-05-24 — D.1: STRICT preserves curated `provider_metadata` subset (Option 1).** Project `provider_metadata` through a curated subset (just `status_code` + `retry_after_seconds`) on the STRICT envelope. Rationale: these two fields are actionable HTTP client hints (status mapping + `Retry-After` header), not provider attribution, so they don't violate the rule that "provider attribution never belongs on an external surface". Holds for both STRICT branches. Side effect: STRICT payloads no longer round-trip through `from_dict` (the partial `provider_metadata` fails pydantic validation on the required fields), but STRICT was already documented as a lossy projection and the existing `test_strict_does_not_round_trip` only asserted observable fields, not rehydration semantics — updated to read the dict directly. Options 2 (top-level field) and 3 (leave as-is) rejected.
-
----
-
-## Session log
-
-Append one dated entry per session / checkpoint. Each entry must leave the
-next session enough to cold-start: what landed, decisions taken, current code
-state, what is broken or deferred, and the exact next action.
-
-### 2026-05-24 — Branch cut + Checkpoint A landed
-
-- **Branch**: cut `feature/post-pr933-followups` from `feature/API-readiness-2` (PR #933 still open against `dev`).
-- **Phase A** complete — six regression nets, all verified for teeth (temporarily breaking the production code makes the test fail), restored after each verification:
- - A.1: `tests/integration/pipelex/temporal/test_wf_pipe_router_request_id_logging.py` (new file) — pins the per-invocation `WorkflowLog(request_id=...)` binding in `WfPipeRouter.run` via a real worker, LLM activity mocked to fail. Teeth check: reverting to `WorkflowLog()` makes the test report `request_ids seen: ['None']`.
- - A.2: two new tests in `test_class_level_metadata.py` covering inline subclasses of `PipelexInterpreterError` and `ValidateBundleError`. Teeth check: switching `_authors_caller_facing_message` lookup to `cls.__dict__` (matching the inheritance-bypass pattern of `_declared_title`) fails both subclass cases.
- - A.3: `test_invalid_report_with_empty_message_falls_back_to_exc_chain` in `test_recover_error_report.py`. Teeth check: swapping `or` for `dict.get(..., default)` strips the preamble.
- - A.4: `test_force_load_walk_continues_past_first_failure` in `test_error_pages_generator.py`. Teeth check: adding `break` after the first failure drops the distinct module count to 1.
- - A.5: `test_webhook_omits_error_when_failed_status_with_none_report` in `test_delivery_executor.py`. Teeth check: defaulting `payload["error"] = {}` when report is None makes the test fail.
- - A.6: `test_reserved_key_check_runs_only_at_construction` in `test_delivery_assignment.py`. Pins observed behavior; `validate_assignment=True` alone doesn't trip it (mutation vs assignment), but a stricter regression (immutable payload, custom `__setitem__` validation) would.
-- **Status**: `make agent-check` clean, `make agent-test` clean.
-- **Next action**: commit Phase A as a single test-only commit, then start Phase B.1.
-
-### 2026-05-24 — Checkpoint B landed
-
-- **Phase B** complete — four refactors, each as its own commit, no observable behavior change:
- - B.1 (`refactor(temporal): hoist severity methods onto _RequestIdLog base`): collapsed the 14 duplicated severity methods on `WorkflowLog` / `ActivityLog` onto `_RequestIdLog` with a `_logger` ClassVar per subclass. Existing parametrized test suite covers both subclasses unchanged.
- - B.2 (`refactor(temporal): hoist error-report validation marker to module constant`): added `_ERROR_REPORT_VALIDATION_FAILED_MARKER` constant in `temporal_error.py`; updated `test_recover_error_report.py` to import the constant.
- - B.3 (`refactor(errors): switch _enrich_error_report_from_cause to model_copy`): both the base implementation and `CogtError.to_error_report` override now use `super().to_error_report()` + `model_copy(update={...})` with just the cause-merged fields. Wrapper-wins fields stay untouched by construction. Verified against unit + integration error-handling tests.
- - B.4 (`fix(errors): make OpenAI/VertexAI titles match the suffix convention`): three `_declared_title` values updated; `docs/errors/` regenerated (4 files diff: 3 pages + index).
-- **Status**: `make agent-check` clean, `make agent-test` clean.
-- **Next action**: open Phase C.1 — the stale TODOs in `pipeline/exceptions.py` need a decision (land the deferred catch site OR remove the unused structure per "No backward compatibility" policy).
-
-### 2026-05-24 — Checkpoint C landed
-
-- **Phase C** complete — three commits:
- - C.1 (`refactor(errors): drop unused pipe_concept_instantiation_errors infrastructure`): user chose "Remove unused structure" (see Decisions). Dropped the field from `ValidateBundleError`, the iteration loop from `agent_output.py`, the `pipe_validation_error_data` property; inlined `pipe_validation_errors` at the call site in `error_handlers.py`; updated the test fixture.
- - C.2 (`refactor(validate): extract bundle-loading handler cascade to a helper`): both `validate_bundle` and `validate_bundles_from_directory` now wrap their try-body in `with _translate_to_validate_bundle_error():` — single source of truth for the six-handler cascade.
- - C.3 (`refactor(temporal): delete unused BaseModelPayloadConverterError`): dead class deleted; docs regenerated (one orphan page removed).
-- **Status**: `make agent-check` clean, `make agent-test` clean.
-- **Next action**: open Phase D.1 with the user — STRICT 429 stripping `provider_metadata.retry_after_seconds` is a design call between three options. Do not action without discussion (per the plan).
-
-### 2026-05-24 — Phase D.1 landed (final phase)
-
-- **Phase D.1** complete — single commit `fix(errors): preserve curated provider_metadata subset under STRICT disclosure`. User chose Option 1 (curated subset). Implementation:
- - Removed `provider_metadata` from `_STRICT_PROVIDER_FIELDS` (the always-dropped set).
- - Added `_STRICT_PROVIDER_METADATA_KEPT_FIELDS = {"status_code", "retry_after_seconds"}` and a `_redact_provider_metadata_for_strict` helper.
- - Updated both STRICT branches in `ErrorReport.to_dict` (redacted and caller-facing) to project `provider_metadata` through the curated subset.
- - Updated the `DisclosureMode.STRICT` and `to_dict` docstrings.
- - Added two new tests: `test_strict_preserves_curated_provider_metadata`, `test_strict_omits_provider_metadata_when_only_curated_subset_is_empty`, `test_strict_provider_metadata_dict_carries_http_status_for_adapter`. Updated the existing `test_strict_redacts_non_caller_facing_reports`, `test_strict_strips_provider_fields_even_from_caller_facing_passthrough`, `test_strict_does_not_round_trip` (now asserts dict reads, not rehydration), `test_strict_mode_redacts_detail_and_drops_disclosure_fields` (now asserts the curated metadata rides as an extension member of the problem document).
- - The new `_redact_provider_metadata_for_strict` helper omits `provider_metadata` entirely when both curated fields are unset (no empty-dict on the wire).
-- **Caveat captured**: STRICT payloads now break `ErrorReport.from_dict` because the curated `provider_metadata` lacks the required `provider` / `sdk_exception_type` fields. This is per-spec ("STRICT is lossy"), but is a behavior shift from the prior implementation where STRICT was still rehydratable. If a downstream consumer (`pipelex-relay`, `pipelex-api`, etc.) relies on rehydrating STRICT payloads, they need to migrate to reading the dict directly. Worth a heads-up in the PR description.
-- **Status**: `make agent-check` clean, `make agent-test` clean. All four phases (A/B/C/D) done.
-- **Next action**: this plan file is complete. Open a PR for the branch `feature/post-pr933-followups` once `feature/API-readiness-2` (PR #933) lands and the branch can rebase onto `dev`. Until then, the branch stacks on top of `feature/API-readiness-2`.
diff --git a/wip/error-handling/post-pr933-xhigh-followups.md b/wip/error-handling/post-pr933-xhigh-followups.md
deleted file mode 100644
index dab2fc1fe..000000000
--- a/wip/error-handling/post-pr933-xhigh-followups.md
+++ /dev/null
@@ -1,835 +0,0 @@
-# Plan — post-PR #933 xhigh `/code-review` follow-ups
-
-Action plan for the 15 findings surfaced by the xhigh-effort `/code-review` pass
-over the branch `feature/post-pr933-followups`. Each finding has a verify step
-(cold-start: confirm the bug/behavior still matches the description), then a
-decision needed from the user, then the fix/test work where applicable.
-
-The first 9 findings are NEW concerns not raised in the prior review. The last
-6 are re-surfaced versions of the already-decided findings from
-[`./post-pr933-followups-code-review.md`](./post-pr933-followups-code-review.md) —
-included here for recall completeness and quick re-verification, not for
-re-deciding.
-
-## Branch context (cold start)
-
-- **Branch**: `feature/post-pr933-followups`, stacked on `feature/API-readiness-2`
- (PR #933 still open against `dev` at time of writing). Do NOT rebase onto
- `dev` until PR #933 lands.
-- **Prior plans on this branch**:
- - [`./post-pr933-review-followups.md`](./post-pr933-review-followups.md) — the
- original 4-phase (A/B/C/D) plan that drove the first 12 commits.
- - [`./post-pr933-followups-code-review.md`](./post-pr933-followups-code-review.md) —
- a pre-PR `/code-review` pass that flagged 6 findings (F1-F6); all 6 were
- resolved in a follow-up session (4 commits' worth of changes: CHANGELOG
- fix, `DisclosureMode.STRICT` docstring extension, new pinning test,
- `_translate_to_validate_bundle_error` extended to `load_concepts_only*`,
- plus decision-recording entries).
-- **State at cold start** (check on entry):
- - The 4 follow-up commits resolving F1-F6 may or may not have been committed.
- Check `git status` and `git log --oneline feature/API-readiness-2..HEAD`.
- - If uncommitted: a `git diff HEAD --stat` should show changes to
- `CHANGELOG.md`, `pipelex/base_exceptions.py`,
- `pipelex/pipeline/validate_bundle.py`,
- `tests/unit/pipelex/test_error_report_disclosure_mode.py`, and a new entry
- in `wip/error-handling/post-pr933-followups-code-review.md`.
- - Either way, this plan layers ON TOP of that state — verify each finding
- against the current code, not the pre-resolution code.
-- **What this plan is**: the xhigh `/code-review` pass ran 5 finder angles (40
- raw candidates), 7 verifiers (2 CONFIRMED, 5 PLAUSIBLE, 1 REFUTED), and a
- sweep (8 more, 2 actionable). After dedup against the prior 6 findings: 9
- NEW concerns + 6 re-verifications. This is the resulting work plan.
-
-## How to start (cold start)
-
-1. **Read this whole file** — every finding names the exact `file:line`, the
- verify step, the decision needed, and the fix/test work.
-2. **Confirm branch state**: `git status`, `git log --oneline feature/API-readiness-2..HEAD`.
-3. **Confirm baseline is green**: `make agent-check` + `make agent-test` BEFORE
- touching anything. If either fails on entry, stop and investigate — this
- plan assumes a green baseline.
-4. **Phases are independent** — pick the one that matches the available time
- budget. Phase A is the smallest (2 small fixes); Phase B needs a design
- decision per finding before action; Phase D is verification-only.
-5. **Make each finding a fresh commit on top** of the existing branch history.
- Do NOT rewrite history of the 12 phase commits or the 4 F1-F6 resolution
- commits.
-
-## Ground rules
-
-- `make agent-check` after every code change. `make agent-test` before each
- phase checkpoint.
-- No backward-compat shims (project policy).
-- One `TestClass` per test module; use `pytest-mock` (`MockerFixture`), not
- `unittest.mock`. See `.claude/rules/pytest-standards.md`.
-- StrEnum rule: never `enum_var.value`, just `{enum_var}`. See
- `.claude/rules/python-standards.md`.
-- Pyright catches `model_copy` validator-skip drift only through behavior —
- not the call shape. Pin behavior with tests, not type annotations.
-
----
-
-## Phase A — HIGH severity (CONFIRMED real bugs)
-
-Two clean fixes. No design ambiguity. Land as two separate commits.
-
-### A.1 — Unify return-placement across the 4 `validate_bundle*` entry points
-
-**File**: `pipelex/pipeline/validate_bundle.py:176` (`validate_bundles_from_directory`)
-and `:291` (`load_concepts_only_from_directory`).
-
-**What**: After the Phase C.2 refactor (extracting
-`_translate_to_validate_bundle_error`) and the F5 working-diff extension to
-`load_concepts_only*`, the four bundle-loading entry points split into two
-shapes:
-
-- `validate_bundle` (block at 121-159): `return ValidateBundleResult(...)` at
- lines 135, 142, 159 — INSIDE the `with`.
-- `validate_bundles_from_directory` (block at 169-175): `return ValidateBundleResult(...)`
- at line 176 — OUTSIDE the `with`.
-- `load_concepts_only` (block at 227-260): `return LoadConceptsOnlyResult(...)`
- at lines 240, 245, 260 — INSIDE.
-- `load_concepts_only_from_directory` (block at 285-290):
- `return LoadConceptsOnlyResult(...)` at line 291 — OUTSIDE.
-
-`ValidateBundleResult` / `LoadConceptsOnlyResult` are plain pydantic BaseModels
-with typed `list[…]` fields and no `arbitrary_types_allowed`. A wrong-typed
-list element raises `pydantic.ValidationError` at construction. From inside the
-`with`, the helper's `except ValidationError` arm translates it to a
-user-facing `ValidateBundleError(pipe_validation_errors=...)`. From outside
-the `with`, it propagates raw.
-
-**Why it matters**: same internal contract bug → two different error envelopes
-depending on which entry point the caller used. Inconsistent for downstream
-handlers that only `except ValidateBundleError`.
-
-**Verify**:
-
-- [ ] `grep -n "with _translate_to_validate_bundle_error\|return ValidateBundleResult\|return LoadConceptsOnlyResult" pipelex/pipeline/validate_bundle.py`
- and confirm the line numbers above still match.
-- [ ] Confirm `ValidateBundleResult` and `LoadConceptsOnlyResult` are plain
- `BaseModel` with no `model_config` override (around lines 29 and 179) —
- so they CAN raise `pydantic.ValidationError` from construction.
-
-**Decision needed**: confirm Plan A (move returns inside) is the right
-direction vs Plan B (move all returns outside, drop translation of result-
-construction errors). Default to Plan A — translating result-construction
-errors as `ValidateBundleError` is the more useful envelope for callers, and
-all four entry points already share a `ValidateBundleError`-as-public-surface
-contract.
-
-**Fix** (Plan A):
-
-- [ ] In `validate_bundles_from_directory`: move the `return
- ValidateBundleResult(blueprints=all_blueprints, pipes=loaded_pipes,
- dry_run_result=dry_run_results)` from line 176 to just above the `with`
- block exit (i.e. at the new last line inside `with`). Indent accordingly.
-- [ ] Same for `load_concepts_only_from_directory` at line 291 → move
- `return LoadConceptsOnlyResult(blueprints=all_blueprints,
- concepts=loaded_concepts)` inside the `with` block.
-
-**Test**:
-
-- [ ] Add `tests/unit/pipelex/pipeline/test_validate_bundle_return_placement.py`
- (or extend the existing concepts-only test file at
- `tests/integration/pipelex/pipeline/test_load_concepts_only.py` — pick
- whichever already has the right fixtures). Use `mocker.patch.object` to
- replace `ValidateBundleResult.__init__` (or the model itself) with a
- stub that raises `pydantic.ValidationError`. Then call each of the four
- entry points and assert each raises `ValidateBundleError` — not raw
- `ValidationError`.
-- [ ] Teeth check: temporarily revert the fix in one entry point; the test
- for that entry point must fail. Restore.
-
-**Commit**: `fix(validate): translate result-construction errors uniformly across all 4 bundle entry points`
-
-### A.2 — Tear down `open_library()` on translated re-raise (library_id leak)
-
-**File**: `pipelex/pipeline/validate_bundle.py:112-113`, `:167-168`,
-`:219-220`, `:283-284` — all four entry points.
-
-**What**: Every entry point calls `library_manager.open_library()` +
-`set_current_library(library_id=library_id)` BEFORE entering the `with`
-block, with no `try/finally` teardown. When the helper translates and
-re-raises a `ValidateBundleError`, the opened `library_id` is leaked. Phase
-C.2 + F5 consolidated the duplication and now surface this leak as a shared
-anti-pattern across all four callers (pre-existing, but easier to fix in one
-sweep now).
-
-**Why it matters**: an IDE/server process that calls `validate_bundle` once
-per user save accumulates one un-torn-down Library per failed validation.
-Library count grows monotonically; stale entries can shadow re-loads of the
-same bundle path under the same key, producing confusing 'stale validation
-result' bugs on subsequent saves. The leak amplitude depends on how often the
-caller validates failing bundles — which is "every save while syntax-erroring"
-for the IDE/agent build flow, i.e. high.
-
-**Verify**:
-
-- [ ] Read `pipelex/hub.py` (or wherever `get_library_manager()` resolves) to
- find the teardown API. Look for `close_library`, `release_library`,
- `__exit__`, or a context-manager wrapper.
-- [ ] If none exists, the fix has TWO parts: (a) add teardown API to
- `LibraryManager`, (b) wire it into the four entry points. If one
- exists, just wire it in.
-- [ ] Determine whether `set_current_library` also needs a "reset" call on
- teardown (it sets contextvar / thread-local state).
-
-**Decision needed**:
-
-- **A.2-1**: confirm teardown API exists (or how to add it).
-- **A.2-2**: choose pattern — try/finally + explicit teardown call, OR
- context manager on `LibraryManager.open_library()` returning `(id, library)`
- via `__enter__`. Recommend context manager for self-documenting cleanup.
-- **A.2-3**: in-scope here, or split off as a separate `library-leak`
- remediation plan? Recommend in-scope — it's a 4-call-site sweep and
- consolidated by the helper refactor.
-
-**Fix**:
-
-- [ ] If `LibraryManager` lacks teardown: add `close_library(library_id)` or
- a `library_session(...)` context manager. Document and test in
- isolation first.
-- [ ] In each of the four entry points: wrap from `open_library()` through
- the final `return` in `try/finally` (or replace with `with library_session(...) as (library_id, library):`).
-- [ ] Make sure the teardown also resets the `set_current_library` state if
- relevant (avoid stale contextvar across requests).
-
-**Test**:
-
-- [ ] `tests/unit/pipelex/pipeline/test_validate_bundle_library_lifecycle.py`:
- use `mocker.spy` on the teardown API. Trigger a `ValidateBundleError`
- from each entry point (e.g. malformed `mthds_contents`). Assert
- teardown was called exactly once. Assert the spy reports the same
- `library_id` that `open_library` returned.
-- [ ] Teeth check: temporarily remove the `try/finally` in one entry point;
- the test for that entry point must fail.
-
-**Commit**: `fix(validate): tear down LibraryManager on bundle-validation failure`
-
-### ⛔ CHECKPOINT A — STOP, verify, record
-
-- [ ] `make agent-check` clean.
-- [ ] `make agent-test` clean.
-- [ ] Each fix as its own commit.
-- [ ] Append a dated entry to the Session log below.
-
----
-
-## Phase B — MEDIUM severity (design discussion before action)
-
-Two findings where the fix has design ambiguity. Open with the user before
-acting.
-
-### B.1 — V6: STRICT projection two-branch asymmetry
-
-**File**: `pipelex/base_exceptions.py:226` (caller-facing branch) and
-`:234` (redacted branch).
-
-**What**: The two STRICT branches use opposite field-selection strategies:
-
-- Caller-facing branch (line 226): `projected = {k: v for k, v in
- payload.items() if k not in _STRICT_PASSTHROUGH_DROPPED_FIELDS}` — EXCLUSION
- filter (denylist). Today's denylist is just `provider`, `model`,
- `caller_facing_message`.
-- Redacted branch (line 234): `redacted = {k: payload[k] for k in
- _STRICT_KEPT_FIELDS if k in payload}` — INCLUSION filter (allowlist).
- Today's allowlist is `error_type`, `title`, `type_uri`, `error_domain`,
- `error_category`, `retryable`.
-
-The two branches would diverge on any future top-level `ErrorReport` field:
-caller-facing branch would emit it silently (not in dropped set), redacted
-branch would silently drop it (not in kept set). The `user_action` field
-already demonstrates the divergence pattern (kept on caller-facing because
-caller-facing keeps the message context, intentionally dropped on redacted).
-No test pins the canonical STRICT-emitted field set or asserts cross-branch
-parity for non-divergent fields.
-
-**Why it matters**: adding a new public ErrorReport field for finer client
-routing (e.g. `error_subcategory`, `correlation_id`, `severity`) would
-silently appear on one STRICT envelope and silently disappear from the other.
-Downstream consumers that route on the new field see inconsistent behavior.
-The redacted branch erring on the side of dropping is the safer default — no
-accidental leak — but the divergence is a refactor trap.
-
-**Verify**:
-
-- [ ] Re-read `pipelex/base_exceptions.py` lines 193-244 and the constants
- `_STRICT_KEPT_FIELDS`, `_STRICT_PROVIDER_FIELDS`,
- `_STRICT_PASSTHROUGH_DROPPED_FIELDS`,
- `_STRICT_PROVIDER_METADATA_KEPT_FIELDS`.
-- [ ] Confirm: no test in
- `tests/unit/pipelex/test_error_report_disclosure_mode.py` asserts the
- canonical STRICT field set, parity, or "all populated fields are
- accounted for".
-
-**Decision needed** (three options):
-
-- **B.1-a** (recommended — single source of truth): factor out a shared
- allowlist (extend `_STRICT_KEPT_FIELDS` or introduce `_STRICT_BASE_FIELDS`).
- The redacted branch uses just that set; the caller-facing branch uses the
- same set plus an explicit overlay of `message` + `user_action` (the two
- fields that legitimately diverge between branches). Both branches then go
- through one place when a new field is added. Cost: a small refactor of
- `to_dict`, possibly clearer.
-- **B.1-b** (parity test only, no code change): add a test that constructs an
- `ErrorReport` with every populated field, runs STRICT on both branches,
- asserts the kept-key sets match modulo `message`/`user_action`. Future
- field additions break the test loudly. Cost: 1 test, ~10 lines.
-- **B.1-c** (document and leave): add a paragraph to the `DisclosureMode.STRICT`
- docstring naming the asymmetry and the per-branch update protocol for
- future fields. Cost: just docs.
-
-Recommend B.1-a — it eliminates the trap. B.1-b is the minimal change.
-
-**Fix** (depends on decision):
-
-- [ ] B.1-a: refactor `to_dict` to share one allowlist. Both branches read
- from the same set; caller-facing overlays the two diverging fields.
- Add the parity test from B.1-b as a bonus pin.
-- [ ] B.1-b: add the parity test only.
-- [ ] B.1-c: add the docstring paragraph only.
-
-**Test** (always add, regardless of code-fix choice):
-
-- [ ] `test_strict_branch_kept_field_parity` in
- `tests/unit/pipelex/test_error_report_disclosure_mode.py` — populate
- every optional field on a caller-facing report, STRICT-project, assert
- `set(strict_caller_facing) - {"message", "user_action"} == set(strict_redacted) - {"message"}`.
-
-**Commit**: `refactor(errors): unify STRICT projection branch field-selection (B.1-a)` —
-or `test(errors): pin STRICT branch field-set parity` for B.1-b.
-
-### B.2 — S2: Concept ValidationError mislabeled as "Pipe Validation Errors"
-
-**File**: `pipelex/pipeline/validate_bundle.py:65` (the `except ValidationError`
-arm in `_translate_to_validate_bundle_error`).
-
-**What**: The shared helper's `except ValidationError` arm calls
-`categorize_pipe_validation_error(validation_error)` at
-`pipelex/core/pipes/handle_pipe_errors.py:46`, which produces
-`pipe_validation_errors=[...]` and a message framed as "Could not load
-blueprints because of: ..." with pipe-specific categorization. Pre-F5
-(working diff in
-[`./post-pr933-followups-code-review.md`](./post-pr933-followups-code-review.md)),
-`load_concepts_only*` had their own inline `except ValidationError` arm that
-called the SAME categorizer — so the mislabeling is pre-existing for the
-concepts-only path. F5 widened the surface (4 entry points now share it) and
-the doc-review-followups doc made the helper docstring claim "single source
-of truth", which makes the mislabeling more visible.
-
-A concept-side validation error (a `Concept` field failing strict validation)
-now reaches the user via a "Pipe Validation Errors" header. The error data
-is preserved; the framing is wrong.
-
-**Why it matters**: UX/diagnostic quality. A user searches for the pipe name
-shown in the header, finds none, files a misleading bug. Not a correctness
-bug; not a security bug. Worth fixing because the F5 consolidation made the
-mislabeling cross-cutting.
-
-**Verify**:
-
-- [ ] Read `pipelex/core/pipes/handle_pipe_errors.py` —
- `categorize_pipe_validation_error` at line 46. Confirm it builds a
- pipe-framed error list independent of the source.
-- [ ] Grep for downstream consumers of `ValidateBundleError.pipe_validation_errors`
- to see how the framing is surfaced.
-- [ ] Trigger the bug: in a fresh `.mthds` bundle, declare a concept with a
- field that violates pydantic validation. Run `pipelex validate` and
- `load_concepts_only` against it. Observe the surfaced framing on each.
-
-**Decision needed** (three options):
-
-- **B.2-a** (parameterize): give the helper a `category: Literal["pipe", "concept"]`
- parameter that switches the categorizer (and the message framing). The two
- bundle-validation call sites pass `"pipe"` (default); the two concepts-only
- call sites pass `"concept"`. Cost: small refactor, two new categorizer
- variants (or one with a parameter).
-- **B.2-b** (split helpers): keep the existing helper, add a sibling
- `_translate_to_validate_bundle_error_concepts_only` for the two
- concepts-only entry points. Re-introduces the duplication the F5 fix
- reduced. Not recommended.
-- **B.2-c** (accept + document): document the mislabeling in the helper
- docstring; add a `concept_validation_errors` field on `ValidateBundleError`
- only if and when a downstream consumer needs the differentiation. Cheapest;
- preserves the UX bug.
-
-Recommend B.2-a — adds one parameter, eliminates the mislabeling cleanly,
-preserves the single-helper structure F5 introduced.
-
-**Fix** (B.2-a):
-
-- [ ] Add a sibling `categorize_concept_validation_error` in
- `pipelex/core/pipes/handle_pipe_errors.py` (or rename + parameterize
- the existing one — discuss).
-- [ ] In `_translate_to_validate_bundle_error`, accept a `category` parameter
- and route to the right categorizer + message framing inside the
- `except ValidationError` arm.
-- [ ] Update the four call sites: the two `validate_bundle*` pass `"pipe"`
- (or omit if default); the two `load_concepts_only*` pass `"concept"`.
-- [ ] Optionally add a `concept_validation_errors` field to
- `ValidateBundleError` if the structured payload differs. Discuss.
-
-**Test**:
-
-- [ ] Extend the concepts-only test file (or add
- `test_concept_validation_error_framing.py`) with a case that triggers
- a concept-side pydantic ValidationError via `load_concepts_only` and
- asserts the resulting `ValidateBundleError`'s message + payload uses
- concept framing, not pipe framing.
-- [ ] Teeth check: revert the categorizer-routing change; the test must
- fail.
-
-**Commit**: `fix(validate): differentiate concept vs pipe ValidationError framing in shared helper`
-
-### ⛔ CHECKPOINT B — STOP, verify, record
-
-- [ ] `make agent-check` clean.
-- [ ] `make agent-test` clean.
-- [ ] Each fix as its own commit.
-- [ ] Append a dated entry to the Session log below.
-
----
-
-## Phase C — LOW severity (latent footguns, mixed action)
-
-Five findings. Mix of trivial fixes, pin-with-test, and accept-as-documented.
-
-### C.1 — V1: Whole-object `or` suppresses cause's actionable `provider_metadata`
-
-**File**: `pipelex/cogt/exceptions.py:102` (`CogtError.to_error_report` —
-`"provider_metadata": self.provider_metadata or base_report.provider_metadata`)
-and `pipelex/base_exceptions.py:500`
-(`_enrich_error_report_from_cause` — `report.provider_metadata or cause_report.provider_metadata`).
-
-**What**: Both use whole-object OR on always-truthy Pydantic models
-(`bool(ProviderErrorMetadata(...))` is always True regardless of internal
-state). A wrapper that explicitly constructs a `ProviderErrorMetadata` with
-no actionable hints (`status_code=None, retry_after_seconds=None`) — for
-attribution-only purposes — would discard the cause's actionable
-`status_code=429, retry_after_seconds=12.0`. Latent today: grep confirms only
-leaf workers (`pipelex/cogt/inference/error_render.py:112,119`,
-`pipelex/plugins/azure_rest/azure_img_gen_worker.py:84,191,210`) set
-non-None `provider_metadata` — they raise from the SDK exception, not from
-another CogtError. No wrapper currently triggers this.
-
-**Why it matters**: the Phase D.1 STRICT-disclosure work specifically
-preserves `retry_after_seconds` for the HTTP adapter to emit `Retry-After`
-headers. If a future contributor adds a wrapper `CogtError` that attaches
-attribution-only metadata, the OR-chain silently loses the retry hint — the
-very thing Phase D.1 was designed to preserve.
-
-**Verify**:
-
-- [ ] Re-read both call sites. Confirm the OR pattern.
-- [ ] `grep -rn "ProviderErrorMetadata(" pipelex/ --include="*.py"` to
- confirm no wrapper currently constructs one. (At time of writing: only
- leaves.)
-
-**Decision needed** (three options):
-
-- **C.1-a** (per-field merging): switch both call sites to per-field merging:
- ```python
- if self.provider_metadata is not None or base_report.provider_metadata is not None:
- merged_metadata = ProviderErrorMetadata(
- provider=(self.provider_metadata and self.provider_metadata.provider)
- or (base_report.provider_metadata and base_report.provider_metadata.provider),
- ...
- )
- ```
- Heavier; restores semantics for the latent future case. Risk: drift between
- the two call sites if the merge logic isn't shared in a helper.
-- **C.1-b** (pin current behavior, document the trap): add a test that pins
- the wrapper-wins semantics (so a future contributor changing to per-field
- merging makes a deliberate decision), and add a comment naming the
- no-actionable-hints case. No behavior change.
-- **C.1-c** (leave as-is, ignore): no trigger today; YAGNI.
-
-Recommend C.1-b — pinning behavior is the right discipline for a documented
-latent footgun. C.1-a is overkill for a latent.
-
-**Fix** (C.1-b):
-
-- [ ] Add a test `test_wrapper_provider_metadata_wins_even_when_cause_has_richer_metadata`
- in the appropriate place (`tests/unit/pipelex/cogt/`?) — construct a
- wrapper CogtError with attribution-only `provider_metadata` raised
- `from` a leaf CogtError with actionable `provider_metadata`. Assert the
- resulting `ErrorReport.provider_metadata` equals the wrapper's (i.e.
- empty curated subset under STRICT).
-- [ ] Add a one-line comment at both call sites naming the wrapper-wins
- semantics and pointing at the test.
-
-**Test**: see Fix above.
-
-**Commit**: `test(errors): pin wrapper-wins provider_metadata semantics (latent OR-suppression trap)`
-
-### C.2 — V3: `recover_error_report` whitespace-only message bypasses `or` fallback
-
-**File**: `pipelex/temporal/tprl/temporal_error.py:125`.
-
-**What**: `recovered_message = report_dict.get("message") or _message_from_exc(exc)`.
-A whitespace-only message (`" "`, `"\n"`, etc.) is truthy in Python, so the
-fallback never fires. The function then emits `f"{recovered_message}
-{_ERROR_REPORT_VALIDATION_FAILED_MARKER}"` = `" [error report failed schema
-validation]"` — a visually broken preamble. The Phase A.3 regression net at
-`tests/unit/pipelex/temporal/test_recover_error_report.py:112` pins only the
-empty-string case, even though its docstring claims coverage of "empty or
-whitespace".
-
-No in-tree writer demonstrably emits whitespace-only messages today, but
-nothing prevents one either (e.g. `PipelexError(f"{maybe_empty_var}")` with
-a bad substitution). Impact: cosmetic/diagnostic — classification info
-(`error_type`, `error_domain`, marker presence) is preserved; only the
-human-readable preamble is degraded.
-
-**Verify**:
-
-- [ ] Read the code at the cited line. Confirm the `or` pattern.
-- [ ] Read the existing test
- `test_invalid_report_with_empty_message_falls_back_to_exc_chain` —
- confirm it parametrizes only `""`.
-
-**Decision needed**: trivial fix or skip?
-Recommend FIX — one-line change, the test pin is already there but
-incomplete.
-
-**Fix**:
-
-- [ ] Change line 125 to: `report_message = report_dict.get("message")` then
- `recovered_message = report_message.strip() if report_message and
- report_message.strip() else _message_from_exc(exc)` (or the walrus
- `(msg := report_dict.get("message")) and msg.strip() if (msg :=
- report_dict.get("message")) is not None else None` — pick the more
- readable shape).
-- [ ] Same check on line 83 (`_message_from_exc`) if it has the analogous
- truthy-fallback pattern — verify and fix if so.
-
-**Test**:
-
-- [ ] Extend the existing parametrize in
- `tests/unit/pipelex/temporal/test_recover_error_report.py:112` (or add
- a sibling case) with `" "`, `"\n"`, `"\t"`. Assert the fallback fires
- and the synthesized message contains the underlying ApplicationError
- text.
-- [ ] Teeth check: revert the strip; the new cases must fail.
-
-**Commit**: `fix(temporal): treat whitespace-only error report message as missing for fallback`
-
-### C.3 — V5: Pin the `PipeValidationError` vs `pydantic.ValidationError` sibling relationship
-
-**File**: `pipelex/pipeline/validate_bundle.py:36-81`
-(`_translate_to_validate_bundle_error`).
-
-**What**: The cascade orders `except PipeValidationError` BEFORE
-`except ValidationError`. Works today because `PipeValidationError(ValueError)`
-is NOT a subclass of `pydantic.ValidationError` (both siblings under
-`ValueError`). A future refactor that unifies the hierarchy (e.g.
-`class PipeValidationError(pydantic.ValidationError)` to share categorization
-machinery) would silently route pydantic ValidationErrors into the
-`PipeValidationError` arm. The sibling relationship is NOT pinned by test,
-comment, or annotation. The helper docstring claims "single source of truth"
-without naming the dependency.
-
-**Verify**:
-
-- [ ] Read `pipelex/core/pipes/exceptions.py` to confirm
- `class PipeValidationError(ValueError)` (sibling, not subclass).
-- [ ] Confirm no existing test asserts `not issubclass(PipeValidationError,
- pydantic.ValidationError)`.
-
-**Decision needed**: no design ambiguity. Add the pin.
-
-**Fix + Test** (one commit):
-
-- [ ] Add a test in `tests/unit/pipelex/pipeline/test_validate_bundle_helper.py`
- (or wherever the helper is tested):
- ```python
- def test_pipe_validation_error_is_not_a_pydantic_validation_error_subclass(self) -> None:
- """Cascade ordering in _translate_to_validate_bundle_error depends on this."""
- from pipelex.core.pipes.exceptions import PipeValidationError
- from pydantic import ValidationError
- assert not issubclass(PipeValidationError, ValidationError)
- ```
-- [ ] Add a one-line comment in the helper above the
- `except PipeValidationError` clause: `# Cascade order: PipeValidationError must precede ValidationError; their sibling-under-ValueError relationship is pinned by tests/.../test_validate_bundle_helper.py`.
-
-**Commit**: `test(validate): pin PipeValidationError sibling-of-pydantic-ValidationError contract`
-
-### C.4 — V4: `_authors_caller_facing_message=True` inheritance for external `ValidateBundleError` subclasses
-
-**File**: `pipelex/pipeline/exceptions.py` (`ValidateBundleError._authors_caller_facing_message = True`).
-
-**What**: The flag is read via plain attribute access (`base_exceptions.py:456`),
-so external subclasses inherit it. The Phase A.2 test
-`test_caller_facing_message_inherits_for_validate_bundle_subclass`
-deliberately pins this. The `DisclosureMode.STRICT` docstring explicitly says
-"STRICT is a classification-projection, not a path-leak shield". So this is
-documented design.
-
-The concern is a downstream subclass-and-leak hazard: external packages
-subclassing `ValidateBundleError` with a non-caller-facing message would leak
-their message verbatim under STRICT.
-
-**Decision needed**: this is a CONTRACT acceptance question, not a code-fix
-question. Three options:
-
-- **C.4-a** (no action): the contract is already documented; in-repo subclass
- count is 0 (only an ephemeral test class). External consumers are expected
- to read the docstring. Recommend default.
-- **C.4-b** (add a Sphinx-style warning to the `ValidateBundleError` docstring):
- a `!!! note` block calling out the inheritance hazard for external
- subclassers, with a one-line opt-out (`_authors_caller_facing_message = False`)
- example. Cheap; defensive.
-- **C.4-c** (change the contract): make the inheritance per-class via
- `cls.__dict__` (matching `_declared_title`). Breaks the Phase A.2 test;
- requires every subclass to opt in. Don't recommend.
-
-**Fix** (C.4-b if chosen):
-
-- [ ] Add a docstring note to `ValidateBundleError` (or its base
- `PipelexInterpreterError` if shared) about the inheritance contract.
-
-**Commit** (only if C.4-b chosen): `docs(errors): note caller_facing_message inheritance hazard for external ValidateBundleError subclasses`
-
-### C.5 — S1: `_RequestIdLog._logger` captured at class-definition time
-
-**File**: `pipelex/temporal/log_temporal.py:96` (WorkflowLog._logger),
-`:109` (ActivityLog._logger).
-
-**What**: Phase B.1 hoist captured `workflow.logger` / `activity.logger` as
-`ClassVar[Any]` at class-definition (module-import) time. Pre-B.1, each
-severity method called `workflow.logger.log(...)` per invocation, picking up
-any runtime reassignment of the module attribute. Post-B.1, `_logger` is
-bound once. If temporalio ever swapped the module-level instance (vs in-place
-mutation, which it does today), all `WorkflowLog` calls would route through
-the stale captured adapter.
-
-**Verify**:
-
-- [ ] Read the file. Confirm the `ClassVar[Any] = workflow.logger` pattern.
-- [ ] Confirm temporalio's current behavior (in-place mutation, not instance
- replacement) — read `temporalio.workflow` source if possible. If
- uncertain, leave the verify step as "TBD, low priority".
-
-**Decision needed**: this is latent. Two options:
-
-- **C.5-a** (no action): per the F6 decision (same file, same kind of
- concern), YAGNI.
-- **C.5-b** (lazy property): change `_logger: ClassVar[Any] = workflow.logger`
- to a `@classproperty` (or plain `@property` on the instance) that reads
- `workflow.logger` fresh each call. Restores pre-B.1 semantics. Cost: small.
-
-Recommend C.5-a unless temporalio's mutation behavior changes.
-
-**Fix** (C.5-b if chosen): see decision above.
-
-**Commit** (only if C.5-b chosen): `refactor(temporal): defer _logger resolution to call time so adapter swaps are picked up`
-
-### ⛔ CHECKPOINT C — STOP, verify, record
-
-- [ ] `make agent-check` clean.
-- [ ] `make agent-test` clean.
-- [ ] Each finding as its own commit (the ones with code changes).
-- [ ] Append a dated entry to the Session log below: which items landed,
- which were deliberately left, and why.
-
----
-
-## Phase D — Already-documented decisions (re-verify only)
-
-The xhigh review re-surfaced the six already-decided findings from
-[`./post-pr933-followups-code-review.md`](./post-pr933-followups-code-review.md)
-(F1-F6) for recall completeness. The decisions taken in that session still
-stand. This phase is just a sanity check that the documentation, tests, and
-code state actually match those decisions — in case the resolution commits
-got dropped or rebased.
-
-Do NOT re-open these for re-decision. If the verify step reveals a real
-deviation, raise it with the user.
-
-### D.1 — Verify F1 resolution (in-repo CHANGELOG fixed; out-of-repo flagged)
-
-- [ ] `grep -n "STRICT" CHANGELOG.md | head -5` — confirm the line in
- `[Unreleased]` reads "STRICT drops provider / model unconditionally and
- projects provider_metadata through a curated subset (only status_code
- and retry_after_seconds — actionable HTTP client hints, not provider
- attribution)" or similar wording.
-- [ ] Confirm the PR description will carry the out-of-repo carryover note
- for `pipelex-api/wip/error-handling/pipelex-changes.md:137`.
-
-### D.2 — Verify F2 resolution (model_copy validator-skip: leave as-is)
-
-- [ ] `grep -n "model_copy" pipelex/cogt/exceptions.py
- pipelex/base_exceptions.py` — confirm both still use
- `model_copy(update={...})` without a hypothetical `validate=True` kwarg
- (which doesn't exist in Pydantic 2.13.4 anyway).
-- [ ] Confirm the followups doc's Decisions section records the choice.
-
-### D.3 — Verify F3 resolution (STRICT 5xx leak — documented)
-
-- [ ] Read `pipelex/base_exceptions.py:71-130` (`DisclosureMode.STRICT` docstring).
- Confirm a paragraph names the curated `provider_metadata` subset's
- cause-chain inheritance and the deliberate-leak rationale.
-
-### D.4 — Verify F4 resolution (STRICT from_dict failure — documented + pinned)
-
-- [ ] Read the same docstring. Confirm a paragraph names that STRICT
- payloads with `provider_metadata` are NOT round-trippable via
- `from_dict` (`pydantic.ValidationError`).
-- [ ] Confirm
- `test_strict_payload_with_provider_metadata_fails_from_dict_rehydration`
- exists in
- `tests/unit/pipelex/test_error_report_disclosure_mode.py` and uses
- `pytest.raises(ValidationError)`.
-
-### D.5 — Verify F5 resolution (helper extended to load_concepts_only* — documented)
-
-- [ ] Read `pipelex/pipeline/validate_bundle.py:36-49` (helper docstring).
- Confirm the docstring names all four call sites and the
- dead-but-harmless extra handlers.
-- [ ] Confirm both `load_concepts_only` (line 227) and
- `load_concepts_only_from_directory` (line 285) wrap their body in
- `with _translate_to_validate_bundle_error():`.
-
-### D.6 — Verify F6 resolution (_logger ClassVar typing — YAGNI)
-
-- [ ] Read `pipelex/temporal/log_temporal.py:49` — confirm
- `_logger: ClassVar[Any]` is unchanged.
-- [ ] No action; per F6 decision.
-
-### ⛔ CHECKPOINT D — STOP, verify, record
-
-- [ ] No code changes expected. Append a dated entry to the Session log
- noting that F1-F6 resolutions still hold (or, if any deviation was
- found, what was raised).
-
----
-
-## Out of scope (recorded, not planned here)
-
-- The 6 sweep-low-confidence candidates the xhigh pass surfaced but did NOT
- promote (S4-S8 except S1/S2/S3 which are in Phase A/B above):
- - **S4** — `test_invalid_report_with_empty_message_falls_back_to_exc_chain`
- substring-match brittleness. Cosmetic; revisit only if temporalio's
- `ApplicationError.__str__` format changes.
- - **S5** — `_redact_provider_metadata_for_strict` `status_code=0` contract
- violation. Speculative; no producer.
- - **S6** — `recover_error_report` future schema migration widening
- `message` type. Speculative.
- - **S7** — `importlib.import_module` patch in
- `test_error_pages_generator.py`. The patch target is correct (module-
- scoped via dotted path); the original sweep concern about "global
- collision" was wrong. No action.
- - **S8** — `test_wf_pipe_router_request_id_logging.py` single `side_effect`
- instance vs retries. Masked by `maximum_attempts=1` today; if Temporal
- retries are ever enabled in tests, revisit.
-- The latent / hypothetical Angle-D findings flagged but not promoted (status
- code=0, mutable defaults, ConfigDict edge cases, etc.). Speculative; no
- trigger.
-
----
-
-## Decisions
-
-Record each decision here as it is taken, with date and rationale.
-
-- **2026-05-24, A.1**: Plan A confirmed — moved returns inside the `with` block on
- the two outliers. Result-construction errors now translate to
- `ValidateBundleError` uniformly across all 4 entry points.
-- **2026-05-24, A.2**: Teardown API already exists (`library_manager.teardown(library_id)`
- + `teardown_current_library()`); no new context manager needed. In-scope here.
- Pattern: `try/finally` with `success` flag (project policy forbids generic
- `except Exception`), only tear down on failure path — matches the
- "error-path-only cleanup" precedent at `pipeline_run_setup.py:345-360`.
-- **2026-05-24, B.1**: Option B.1-a — refactored `to_dict` STRICT branches to share
- `_STRICT_KEPT_FIELDS` as single allowlist. Caller-facing overlays
- `message` + `user_action` on the shared base. Dropped unused
- `_STRICT_PROVIDER_FIELDS` / `_STRICT_PASSTHROUGH_DROPPED_FIELDS` constants.
- Parity test added.
-- **2026-05-24, B.2**: Option B.2-a — added `category: Literal["pipe", "concept"]`
- parameter to `_translate_to_validate_bundle_error`. The two `validate_bundle*`
- call sites pass `"pipe"`, the two `load_concepts_only*` pass `"concept"`. Only
- the `except ValidationError` arm's framing changes per category; the
- structured payload (`pipe_validation_errors`) is unchanged because
- `categorize_pipe_validation_error` already detects PIPE/CONCEPT model-scope
- per error.
-- **2026-05-24, C.1**: Option C.1-b — pinned wrapper-wins semantics with a test
- at `tests/unit/pipelex/cogt/test_cogt_provider_metadata_wrapper_wins.py`.
- Added comments at both OR-suppression call sites
- (`pipelex/cogt/exceptions.py` and `pipelex/base_exceptions.py`) pointing at
- the test.
-- **2026-05-24, C.2**: Trivial fix — added `str.strip()` guard at both sites
- (`recover_error_report` line 125 + `_message_from_exc`). Extended existing
- parametrize to cover whitespace cases.
-- **2026-05-24, C.3**: Added one-line test asserting
- `not issubclass(PipeValidationError, pydantic.ValidationError)`. Added
- comment in the helper above `except PipeValidationError` clause pointing at
- the test.
-- **2026-05-24, C.4**: C.4-a (no action). The inheritance hazard for external
- `ValidateBundleError` subclasses is documented in the `DisclosureMode.STRICT`
- docstring ("STRICT is a classification-projection, not a path-leak shield");
- in-repo subclass count is 0 (only an ephemeral test class).
-- **2026-05-24, C.5**: C.5-a (no action). Same rationale as F6: temporalio's
- in-place mutation behavior makes the captured-at-class-definition reference
- safe today.
-- **2026-05-24, D.1-D.6**: All resolutions still hold — verified
- `CHANGELOG.md` STRICT line, `model_copy` no `validate=True` kwarg, STRICT
- docstring covers 5xx leak + from_dict failure, helper docstring names all 4
- call sites, `_logger: ClassVar[Any]` unchanged.
-
-## Session log
-
-Append one dated entry per session / checkpoint. Each entry must leave the
-next session enough to cold-start: what landed, decisions taken, current
-code state, what is broken or deferred, and the exact next action.
-
-- **2026-05-24**: Worked through all 15 findings in one session.
-
- **Phase A** — both committed (`1fccafd2`, `366a8aad`).
- - A.1 moved returns inside the `with` block on `validate_bundles_from_directory`
- and `load_concepts_only_from_directory` (the two outliers). Added
- `tests/integration/pipelex/pipeline/test_validate_bundle_return_placement.py`
- with one test per entry point — teeth-checked one by reverting (failed
- as expected, then restored).
- - A.2 wrapped each entry point in `try/finally` with a `success` flag that
- teardowns `library_manager` + `teardown_current_library()` only on the
- failure path. Added imports for `teardown_current_library`. Added
- `tests/integration/pipelex/pipeline/test_validate_bundle_library_lifecycle.py`
- spying on `library_manager.teardown` for each entry point — teeth-checked
- by reverting one entry point.
-
- **Phase B** — both committed (`52325498`, `0554303b`).
- - B.1-a unified the two STRICT branches in `ErrorReport.to_dict` to share
- `_STRICT_KEPT_FIELDS` as a single allowlist; caller-facing branch overlays
- `message` + `user_action`. Dropped `_STRICT_PROVIDER_FIELDS` and
- `_STRICT_PASSTHROUGH_DROPPED_FIELDS`. Updated the constant's docstring.
- Added `test_strict_branch_kept_field_parity`.
- - B.2-a added `category: Literal["pipe", "concept"]` to the helper signature.
- The four call sites now pass their category explicitly. Only the
- `except ValidationError` arm's message framing changes (Could not load
- blueprints vs Could not load concepts). Structured payload unchanged.
- Added `test_validate_bundle_category_framing.py`.
-
- **Phase C** — three committed (`d8ad53ff`, `7cfb6a20`, `b4d454fc`), two
- skipped per recommendation.
- - C.1-b added a test pinning wrapper-wins `provider_metadata` semantics
- (`tests/unit/pipelex/cogt/test_cogt_provider_metadata_wrapper_wins.py`) and
- a one-paragraph comment at both OR-suppression call sites
- (`pipelex/cogt/exceptions.py` and `pipelex/base_exceptions.py`).
- - C.2 added `str.strip()` guards at both
- `_message_from_exc` and `recover_error_report` line 125. Extended the
- existing parametrize to cover empty/space/tab/newline/mixed-whitespace.
- Teeth-checked.
- - C.3 added `test_pipe_validation_error_is_not_a_pydantic_validation_error_subclass`
- plus a one-line comment in the helper above the `except PipeValidationError`
- clause.
- - C.4 skipped per recommendation (C.4-a — no action; documented in
- `DisclosureMode.STRICT` docstring).
- - C.5 skipped per recommendation (C.5-a — no action; same rationale as F6).
-
- **Phase D** — all six F1-F6 resolutions verified intact. No code changes.
-
- **State at end of session**: baseline green (`make agent-check` clean,
- `make agent-test` passes). Branch is `feature/post-pr933-followups`, 8 new
- commits on top of `e73cb5a9`. PR #933 not yet landed at time of writing —
- do NOT rebase onto `dev` until it does.
diff --git a/wip/error-handling/post-xhigh-review-followups.md b/wip/error-handling/post-xhigh-review-followups.md
deleted file mode 100644
index 2fee41f2a..000000000
--- a/wip/error-handling/post-xhigh-review-followups.md
+++ /dev/null
@@ -1,555 +0,0 @@
-# Plan — verify and fix the 7 findings from the xhigh `/code-review`
-
-A second xhigh `/code-review` pass (recall mode) over the 8 commits added in the
-previous session surfaced 7 findings (3 HIGH, 2 MEDIUM, 2 LOW). This plan is
-the work-tracker for verifying each finding against the current code and
-landing the fix. The plan is laid out so a fresh session can cold-start from
-it.
-
-## Branch context (cold start)
-
-- **Branch**: `feature/post-pr933-followups`, stacked on `feature/API-readiness-2`.
- PR #933 still open against `dev` at time of writing — do NOT rebase onto
- `dev` until PR #933 lands.
-- **Prior plans on this branch**:
- - [`./post-pr933-review-followups.md`](./post-pr933-review-followups.md) — the
- original 4-phase (A/B/C/D) plan that drove the first 12 commits.
- - [`./post-pr933-followups-code-review.md`](./post-pr933-followups-code-review.md) —
- the F1-F6 plan that drove 4 commits.
- - [`./post-pr933-xhigh-followups.md`](./post-pr933-xhigh-followups.md) — the
- 15-finding xhigh plan that drove the 8 commits this xhigh pass reviewed.
-- **State at cold start** (check on entry):
- - `git log --oneline feature/API-readiness-2..HEAD` should show 22 commits.
- The 8 most recent (top of the log) are this xhigh pass's targets:
- - `ab07bd2c` docs(plan)
- - `b4d454fc` test(validate): pin PipeValidationError sibling
- - `7cfb6a20` fix(temporal): whitespace-only message
- - `d8ad53ff` test(errors): pin wrapper-wins provider_metadata
- - `0554303b` fix(validate): concept/pipe ValidationError framing
- - `52325498` refactor(errors): unify STRICT projection
- - `366a8aad` fix(validate): teardown LibraryManager on failure
- - `1fccafd2` fix(validate): translate result-construction errors
- - `git status` should be clean (or only this plan file unstaged).
-- **Baseline**: `make agent-check` and `make agent-test` are both green at the
- start of this session — confirm before touching anything.
-
-## How to start (cold start)
-
-1. **Read this whole file** — every finding names the exact `file:line`, the
- verify step, the decision needed, and the fix work.
-2. **Confirm branch state**: `git status`, `git log --oneline feature/API-readiness-2..HEAD | head -10`.
-3. **Confirm baseline is green**: `make agent-check` + `make agent-test` BEFORE
- touching anything. If either fails on entry, stop and investigate.
-4. **Findings are independent** — pick by phase. Phase A is the
- teardown-leak triage (3 leaks tightly related); Phase B is the helper-shape
- issues; Phase C is the test/contract-pin issues.
-5. **Make each finding a fresh commit on top** of the existing 22-commit
- history. Do NOT rewrite history.
-
-## Ground rules
-
-- `make agent-check` after every code change. `make agent-test` before each
- phase checkpoint.
-- No backward-compat shims (project policy).
-- One `TestClass` per test module; use `pytest-mock` (`MockerFixture`), not
- `unittest.mock`. See `.claude/rules/pytest-standards.md`.
-- StrEnum rule: never `enum_var.value`, just `{enum_var}`. See
- `.claude/rules/python-standards.md`.
-- Project policy forbids generic `except Exception:` (see
- `.claude/rules/python-standards.md`). Use `try/finally` with a `success`
- flag (precedent: `pipeline_run_setup.py:345-360` and the A.2 commit
- `366a8aad`).
-- `case _:` on exhaustive matches is forbidden by python-standards. Use
- `case _ as unreachable: assert_never(unreachable)` from `typing` only when
- the runtime contract is genuinely unenforceable (Literal at a call site).
-
----
-
-## Phase A — HIGH severity: pre-`try` library leaks (3 findings, one fix shape)
-
-All three are the same underlying defect: in each of the four bundle-loading
-entry points, code runs between `library_manager.open_library()` and the new
-`try:` block that holds the teardown `finally`. Any exception in that window
-— including `asyncio.CancelledError` at the `await asyncio.sleep(0)` yield —
-leaks the just-opened library. The new lifecycle tests don't exercise
-cancellation or pre-`try` raises.
-
-### A.1 — CancelledError leak on `await asyncio.sleep(0)`
-
-**File**: `pipelex/pipeline/validate_bundle.py:127-137` (`validate_bundle`).
-
-**What**: After `open_library()` at line 127 and `set_current_library()` at
-line 128, control reaches `await asyncio.sleep(0)` at line 135 BEFORE entering
-the `try:` at line 137. `asyncio.CancelledError` (a `BaseException`) raised at
-that yield propagates without entering the `try`, so the new `finally` never
-runs.
-
-**Why it matters**: the lifecycle-fix's stated use case is an IDE/server that
-cancels in-flight validation on every keystroke. That's exactly the trigger
-for cancellation at an `await` point. The fix protects against everything
-EXCEPT cancellation — silently the worst case for the stated use case.
-
-**Verify**:
-
-- [ ] `grep -n "await asyncio.sleep\|open_library\|^ try:\|^ finally:" pipelex/pipeline/validate_bundle.py | head -30`
- — confirm `await asyncio.sleep(0)` is between `open_library()` and
- `try:` in `validate_bundle`. Other entry points don't have `await
- asyncio.sleep(0)`, but they do have other pre-`try` work — see A.2.
-
-### A.2 — Pre-`try` raises from `resolve_library_dirs` / `set_current_library`
-
-**File**: `pipelex/pipeline/validate_bundle.py`
-- `validate_bundle` lines 127-137 (`open_library` → `set_current_library` →
- `resolve_library_dirs` → variable init → `await asyncio.sleep(0)` → `try:`)
-- `load_concepts_only` lines 248-258 (same pattern, no `await`)
-- `validate_bundles_from_directory` lines 184-193 (open → set_current → try:)
-- `load_concepts_only_from_directory` lines 316-321 (open → set_current → try:)
-
-**What**: `resolve_library_dirs(library_dirs)` is called between
-`open_library()` and the `try:` in `validate_bundle` and `load_concepts_only`.
-It can raise `TypeError` (e.g. `Path(None)` in `hub.py:511` when a caller
-passes a malformed `library_dirs` element). `set_current_library` is also
-outside the try in all four entry points and could in principle raise.
-
-**Why it matters**: the contract the lifecycle test (commit `366a8aad`) pins
-is "teardown fires on the failure path". Any of these pre-`try` raises
-silently breaks that contract.
-
-**Verify**:
-
-- [ ] Read `pipelex/pipeline/validate_bundle.py:120-145` and confirm
- `resolve_library_dirs(library_dirs)` is at line 131 (in `validate_bundle`)
- and line 254 (in `load_concepts_only`), both BEFORE the `try`.
-- [ ] Read `pipelex/hub.py:491-525` (`resolve_library_dirs`) and confirm
- `Path(...)` is called on user-supplied dir elements (the `TypeError`
- path).
-- [ ] Read `pipelex/hub.py:486-488` (`teardown_current_library`) — it just
- resets the contextvar to None.
-
-### A.3 — One unified fix for A.1 + A.2
-
-The same restructuring closes all three leak windows. There are two clean
-options.
-
-**Decision needed** (two options):
-
-- **A-fix-1** (recommended — move-into-try): move every line between
- `open_library()` and the existing `try:` INTO the try block, including
- `set_current_library`, `resolve_library_dirs`, the variable inits, and the
- `await asyncio.sleep(0)`. Apply uniformly to all four entry points. Net
- effect: any exception in that window now triggers the existing teardown
- path.
-- **A-fix-2** (extract context manager): replace the open/set/teardown
- scaffolding with a `library_session(...)` `@contextmanager` that yields
- `(library_id, library)` and tears down on `__exit__` only when the inner
- body raised. Costs an extra abstraction; gains clarity. Recommend A-fix-1
- unless the duplication across the four entry points triggers the same fix
- somewhere else.
-
-Recommend **A-fix-1** — minimal, no new abstraction, surgical to the four call
-sites.
-
-**Fix** (A-fix-1):
-
-- [ ] For each of the four entry points, move every statement between
- `library_manager.open_library()` and `try:` INTO the `try:` block. The
- `success = False` flag stays just before the `try`. Order:
- ```python
- library_id, library = library_manager.open_library()
- success = False
- try:
- set_current_library(library_id=library_id)
- effective_dirs, source_label = resolve_library_dirs(library_dirs)
- # ... other variable init ...
- await asyncio.sleep(0) # only in validate_bundle
- with _translate_to_validate_bundle_error(category="..."):
- # ... body ...
- result = ...Result(...)
- success = True
- return result
- finally:
- if not success:
- library_manager.teardown(library_id=library_id)
- teardown_current_library()
- ```
-- [ ] Confirm the four entry points still pass `agent-check` (no unused
- imports, no shadowed locals).
-
-**Test**:
-
-- [ ] Add `tests/integration/pipelex/pipeline/test_validate_bundle_preflight_leak.py`
- (or extend the existing `test_validate_bundle_library_lifecycle.py` —
- pick whichever has the right scope). Cover:
- - Cancellation at `await asyncio.sleep(0)`: in `validate_bundle`, wrap the
- call in an `asyncio.Task`, cancel it just after creation, assert teardown
- fired. Use `mocker.spy` on `library_manager.teardown` AND on
- `library_manager.open_library` so the test can ALSO assert the
- teardown's `library_id` matches the opened id (see C.5).
- - `TypeError` from `resolve_library_dirs`: call `validate_bundle(library_dirs=[None])`
- or similar invalid input, assert teardown fired with the right id.
- - Same two scenarios for `load_concepts_only`.
-- [ ] Teeth check: temporarily revert one entry point's move-into-try; the
- new test must fail.
-
-**Commit**: `fix(validate): close pre-try leak window in bundle entry points`
-
-### ⛔ CHECKPOINT A — STOP, verify, record
-
-- [ ] `make agent-check` clean.
-- [ ] `make agent-test` clean (full suite — these are async / lifecycle tests
- and may surface flakiness).
-- [ ] Append a dated entry to the Session log below.
-
----
-
-## Phase B — MEDIUM severity: helper shape gaps
-
-### B.1 — `PipeValidationError` arm uses pipe framing on concept entry points
-
-**File**: `pipelex/pipeline/validate_bundle.py:75-80`
-(`_translate_to_validate_bundle_error`'s `except PipeValidationError` arm).
-
-**What**: The B.2 fix from the previous xhigh round made the
-`except ValidationError` arm category-aware (line 88-91: "Could not load
-blueprints because of: ..." vs "Could not load concepts because of: ..."). But
-the helper has FIVE other arms (`PipelexInterpreterError`, `PipeFactoryError`,
-`PipeValidationError`, `PipeRunError`, `DryRunError`), and the
-`PipeFactoryError` and `PipeValidationError` arms still produce pipe-specific
-framing ("Pipe factory error: ...", "Pipe validation failed: ...") regardless
-of category.
-
-The helper's docstring asserts that those handlers are "dead code in the
-concepts-only paths" because concept-only entry points "never instantiate
-pipes or run dry runs." But that's an unverified claim — if a future change
-to `load_concepts_only_from_blueprints` ever surfaces a `PipeValidationError`
-or `PipeFactoryError` (e.g. through a shared validator on a concept's
-`refines` chain), a concepts-only caller would see "Pipe validation failed
-..." framing — exactly the B.2 mislabel the previous round was supposed to
-fix.
-
-**Verify**:
-
-- [ ] Read `pipelex/pipeline/validate_bundle.py:54-92` — re-confirm only the
- `ValidationError` arm is category-aware after the B.2 commit.
-- [ ] Grep for the dead-code claim:
- `grep -rn "raise PipeValidationError\|raise PipeFactoryError" pipelex/libraries/ pipelex/core/concepts/` —
- if any concept-loading path can raise these, the gap is real.
-
-**Decision needed** (three options):
-
-- **B.1-a** (recommended — make all framing arms category-aware): pass
- `category` to all framing arms. Use a `match category` at one place
- (extract a small `_format_message_with_category(category, kind, detail)`
- helper) so the four entry points see one place when adding a new framing.
-- **B.1-b** (rely on the docstring): document the dead-code claim with a
- test that asserts the concept-loading paths never call into pipe-validation
- helpers. Cheaper; relies on the test never going stale.
-- **B.1-c** (accept the gap): leave it. Pipe-framing on concept paths is a
- diagnostic-quality issue only if those exceptions ever fire.
-
-Recommend **B.1-a** — closes the loop on B.2's intent and removes the
-unverified docstring claim. Cost: small parametrize of the helper.
-
-**Fix** (B.1-a):
-
-- [ ] Either pass `category` to each framing string and switch on it inline,
- or factor out a small helper:
- ```python
- def _categorized_intro(category: Literal["pipe", "concept"], kind: str) -> str:
- subject = "Pipe" if category == "pipe" else "Concept"
- return f"{subject} {kind}"
- ```
- and use it in PipeFactoryError, PipeValidationError, and ValidationError
- arms.
-- [ ] Update the helper docstring to drop the "dead code" claim — replaced by
- the categorized framing.
-
-**Test**:
-
-- [ ] Extend `tests/integration/pipelex/pipeline/test_validate_bundle_category_framing.py`
- with cases that trigger PipeFactoryError / PipeValidationError from a
- concepts-only entry point — use `mocker.patch.object` on the relevant
- LibraryManager method to raise the right exception. Assert the
- resulting message uses "Concept ..." framing, not "Pipe ...".
-- [ ] Teeth check: revert one framing arm to hard-code "Pipe"; the test
- must fail.
-
-**Commit**: `fix(validate): make all helper framing arms category-aware`
-
-### B.2 — `match category:` has no `case _: assert_never(...)`
-
-**File**: `pipelex/pipeline/validate_bundle.py:85-89` (the
-`except ValidationError` arm in the helper).
-
-**What**: `Literal["pipe", "concept"]` is not enforced at runtime. A typo at
-a call site (e.g. `category="concepts"`) makes the match fall through, leaves
-`msg` unbound, and the next line `raise ValidateBundleError(message=msg, ...)`
-raises `UnboundLocalError` — bypassing the helper's translation contract.
-Today the four call sites are correct, but the gap is real for a fifth caller
-or a refactor.
-
-**Why it matters**: the helper's whole purpose is to translate the bundle-loading
-exception surface into a single `ValidateBundleError`. Letting `UnboundLocalError`
-escape silently breaks that contract.
-
-**Verify**:
-
-- [ ] `grep -n "match category\|case \"" pipelex/pipeline/validate_bundle.py |
- head -10` — confirm no `case _:` arm.
-- [ ] Re-read `.claude/rules/python-standards.md` enum section — confirm the
- project forbids `case _: ...` on exhaustive matches but allows
- `assert_never` for unenforced Literal at runtime.
-
-**Decision needed**: the rule against `case _` is about enum-exhaustive
-matches (where the linter catches missing arms). A `Literal[...]` parameter
-is different — the runtime can receive any value. Add `assert_never` so the
-runtime contract is loud.
-
-**Fix**:
-
-- [ ] Add a fallthrough arm:
- ```python
- from typing import assert_never # at top of file
- ...
- match category:
- case "pipe":
- msg = f"Could not load blueprints because of: {validation_error_msg}"
- case "concept":
- msg = f"Could not load concepts because of: {validation_error_msg}"
- case _ as unreachable:
- assert_never(unreachable)
- ```
-
-**Test**:
-
-- [ ] Add `tests/unit/pipelex/pipeline/test_validate_bundle_helper.py` (the
- file from C.3 in the previous round — append a new test method):
- ```python
- def test_translate_helper_rejects_unknown_category_at_runtime(self) -> None:
- from pipelex.pipeline.validate_bundle import _translate_to_validate_bundle_error
- with pytest.raises(AssertionError): # assert_never raises AssertionError
- with _translate_to_validate_bundle_error(category="concepts"): # type: ignore[arg-type]
- raise ValidationError.from_exception_data(...) # trigger the ValidationError arm
- ```
-
-**Commit**: `fix(validate): assert_never on unknown category in helper`
-
-### ⛔ CHECKPOINT B — STOP, verify, record
-
-- [ ] `make agent-check` clean.
-- [ ] `make agent-test` clean.
-- [ ] Each fix as its own commit.
-
----
-
-## Phase C — LOW severity: latent / future-proofing
-
-### C.1 — `to_dict` `match disclosure_mode:` is not future-proof
-
-**File**: `pipelex/base_exceptions.py:229-253` (the `match disclosure_mode`
-in `to_dict`).
-
-**What**: The match covers VERBOSE and STRICT, the only current
-DisclosureMode values. If a future variant is added (e.g. `AUDIT`) without
-updating the match, the function silently returns `None` (no `case _`, no
-implicit final return). Pyright would catch this statically — but a
-`# type: ignore` or a runtime-constructed enum (e.g. via `DisclosureMode(string_value)`)
-slips past static checking.
-
-**Why it matters**: `to_problem_document` at line 297 does `payload["message"]`
-— a `None` return crashes the HTTP adapter at `TypeError: 'NoneType' object
-is not subscriptable`.
-
-**Decision needed**: add `assert_never` on the fallthrough.
-
-**Fix**:
-
-- [ ] Add `case _ as unreachable: assert_never(unreachable)` to the
- `to_dict` match. Same shape would protect the `error_domain_to_http_status`
- match (see C.2).
-
-**Test**: not strictly required (static check catches the regression), but
-optional:
-
-- [ ] Add a test that bypasses static checking and constructs an invalid
- DisclosureMode at runtime, asserting `assert_never`'s `AssertionError`
- fires.
-
-**Commit**: `fix(errors): assert_never on unknown DisclosureMode in to_dict`
-
-### C.2 — `error_domain_to_http_status` is not future-proof (pre-existing)
-
-**File**: `pipelex/base_exceptions.py:163-174` (`error_domain_to_http_status`).
-
-**What**: Same non-exhaustive-match shape as C.1 but pre-existing — not
-touched by the previous xhigh round. Match covers INPUT, CONFIG | RUNTIME,
-None. A future `ErrorDomain.SECURITY` value without a match arm silently
-returns `None` from a `-> int` function.
-
-**Decision needed**: bundle the fix with C.1 (one assert_never pattern in
-both functions) or split. Recommend bundle.
-
-**Fix**:
-
-- [ ] Same `case _ as unreachable: assert_never(unreachable)` pattern.
-
-**Commit** (bundled with C.1): `fix(errors): assert_never on unknown DisclosureMode and ErrorDomain matches`
-
-### C.3 — Lifecycle tests don't assert the library_id value on teardown
-
-**File**: `tests/integration/pipelex/pipeline/test_validate_bundle_library_lifecycle.py:73,95,113,131`.
-
-**What**: The tests assert `"library_id" in latest_call.kwargs` but never
-assert the value matches the actually-leaked library_id. A regression that
-tore down a wrong library_id (e.g. a closure-captured stale id) would still
-pass the test.
-
-**Why it matters**: the test is the only thing pinning the A.2 fix from the
-previous xhigh round. Weakening it means a regression could slip in
-unnoticed.
-
-**Decision needed**: split off as a separate test-quality fix, or fold into
-the A.3 test commit. Recommend fold — the A.3 test also adds open_library
-spying, which is exactly what's needed to close this gap.
-
-**Fix** (fold into A.3 test):
-
-- [ ] In the new A.3 test (and in the existing lifecycle tests), `mocker.spy`
- on `library_manager.open_library` AND `library_manager.teardown`. Assert
- `teardown.call_args.kwargs["library_id"] == open_library.spy_return[0]`
- (or equivalent).
-
-**Commit**: covered by the A.3 commit.
-
-### ⛔ CHECKPOINT C — STOP, verify, record
-
-- [ ] `make agent-check` clean.
-- [ ] `make agent-test` clean.
-- [ ] Each fix as its own commit (C.1+C.2 bundled is one commit).
-
----
-
-## Out of scope (recorded, not planned here)
-
-These were surfaced by the xhigh pass but verified as REFUTED or already
-documented:
-
-- **teardown_current_library() clobbers caller's contextvar**: REFUTED.
- `set_current_library` already overwrites the caller's contextvar BEFORE the
- `try` block — the new `finally`'s `teardown_current_library()` just changes
- the post-failure state from "set to validate_bundle's failed library" to
- "set to None". No production caller currently sets a library_id then calls
- validate_bundle.
-- **`_WrapperCogtError` violates error-class-location convention**: REFUTED.
- The convention test (`tests/unit/pipelex/errors/test_error_class_location_convention.py`)
- explicitly excludes modules whose `__module__` starts with `"tests."`. The
- docs generator's `_force_load_all_error_modules` only `rglob`s the
- `pipelex/` package, not `tests/`.
-- **Trailing whitespace in `raw_message` produces doubled-space in fallback marker**:
- REFUTED as bug. Cosmetic; the marker is still parseable as a substring. No
- downstream consumer depends on whitespace normalization here.
-- **`python -O` strips the `assert mthds_file_path is not None`**:
- UNREACHABLE. The preflight check at line 119-121 uses `if`, not `assert`,
- so all-None state raises ValidateBundleError before reaching the else.
-- **Wrapper-wins provider_metadata OR-merge**: already documented + pinned by
- test (C.1-b in the previous xhigh round, commit `d8ad53ff`).
-- **STRICT allowlist narrowing vs prior denylist**: already documented as
- intentional in B.1-a (previous xhigh round, commit `52325498`) — "single
- source of truth, adding a new field is one decision".
-
----
-
-## Decisions
-
-Record each decision here as it is taken, with date and rationale.
-
-### 2026-05-24 — Phase A: A-fix-1 (move-into-try)
-
-Applied **A-fix-1** as recommended in the plan. Moved every statement between
-`library_manager.open_library()` and the existing `try:` INTO the try block
-in all four bundle-loading entry points. The `success = False` flag stays
-just before the `try`. No new abstraction.
-
-### 2026-05-24 — Phase B.1: skipped (B.1-c, accept the gap)
-
-REJECTED the plan's B.1-a recommendation. Reasoning:
-
-- Verified by grep that `PipeFactoryError` / `PipeValidationError` are raised
- only from `pipelex/core/pipes/pipe_factory.py` and `pipe_abstract.py`.
- Concept-loading paths (`load_concepts_only_from_blueprints`) don't reach
- those modules — the dead-code claim in the docstring is correct.
-- Renaming the framing to "Concept factory error" / "Concept validation
- failed" would be semantically dubious (concepts don't have factories) AND
- would HIDE the actual error type for the speculative future case where
- those arms ever do fire from a concepts-only path. The current framing is
- diagnostically accurate when those arms fire.
-- The plan's worry — "if a future change ever surfaces a PipeValidationError
- from concept loading" — is speculative; if/when that happens, the right
- fix is at the source, not at the framing layer.
-
-### 2026-05-24 — Phase B.2: applied (assert_never on Literal)
-
-Added `case _ as unreachable: assert_never(unreachable)` to the
-`match category:` block. The Literal at the call site is the right place
-for runtime backup — even though pyright catches it statically, the failure
-mode without `assert_never` is a silent `UnboundLocalError` on `msg`, which
-would silently break the helper's translation contract. Loud beats silent.
-
-### 2026-05-24 — Phase C.1 / C.2: skipped
-
-REJECTED the plan's recommendation to add `assert_never` on the
-`DisclosureMode` (`to_dict`) and `ErrorDomain | None` (`error_domain_to_http_status`)
-matches. Reasoning:
-
-- `python-standards.md` explicitly forbids `case _:` on exhaustive enum
- matches.
-- `pyright` config has `reportMatchNotExhaustive = "error"` — a new enum
- variant without updating the match fails the typecheck at the match site.
- This is the linter feedback the rule relies on.
-- No precedent for `assert_never` in `pipelex/`.
-- `DisclosureMode("audit")` raises `ValueError` at enum construction —
- before the match. A dynamically-constructed enum can't be "wrong" without
- raising on construction.
-- `# type: ignore` is an explicit developer opt-out; the codebase trusts
- static checking for these.
-
-### 2026-05-24 — Phase C.3: folded into Phase A commit
-
-Folded the library_id-value assertion into the existing lifecycle tests
-during the A.3 commit, as recommended. Each lifecycle test now spies on
-`library_manager.open_library` as well as `library_manager.teardown` and
-asserts `teardown.call_args.kwargs["library_id"] == open_library.spy_return[0]`,
-so a regression that tore down a stale closure-captured id would fail.
-
-## Session log
-
-Append one dated entry per session / checkpoint. Each entry must leave the
-next session enough to cold-start: what landed, decisions taken, current
-code state, what is broken or deferred, and the exact next action.
-
-### 2026-05-24 — Phase A + B.2 landed, B.1 + C.1 + C.2 declined
-
-**Landed commits** (on top of the 22-commit baseline `ab07bd2c`):
-
-- `4b7683cb` `fix(validate): close pre-try leak window in bundle entry points`
- — Phase A + folded C.3. Moves all pre-`try` work into the `try` block in
- all four entry points. Extends lifecycle tests with `library_id` value
- assertion (C.3) + adds new tests for `BaseException` (simulated
- `CancelledError`) and `TypeError` raised in the pre-try window.
- Teeth-checked.
-- `01f911cd` `fix(validate): assert_never on unknown category in shared helper`
- — Phase B.2. Adds `assert_never` to the `match category:` block, swaps
- silent `UnboundLocalError` for loud `AssertionError`. Teeth-checked.
-
-**Declined** (recorded in Decisions above):
-
-- B.1 (B.1-a recommendation): skipped — framing would mislead in the
- speculative case it was supposed to fix.
-- C.1, C.2: skipped — go against the codebase rule forbidding `case _:` on
- exhaustive enum matches; pyright already enforces exhaustiveness.
-
-**Current state**: working tree clean except this plan file. `make agent-check`
-green; pipeline unit + integration tests green.
-
-**Next action**: none — all 7 plan findings triaged and either landed or
-declined with rationale recorded. Ready for review.
diff --git a/wip/error-handling/review-notes/search-worker-review-followups.md b/wip/error-handling/review-notes/search-worker-review-followups.md
deleted file mode 100644
index 497ec8ad2..000000000
--- a/wip/error-handling/review-notes/search-worker-review-followups.md
+++ /dev/null
@@ -1,36 +0,0 @@
-# Review note — Phase 12 search worker follow-ups
-
-**Surfaced during:** Phase 12 (`_tprl/TODOS.md`) code review of `ca2763c2` "feat: Phase 12 search worker audits".
-
-Three minor, non-blocking observations from the code review. None is a Phase 12 regression — each is either a pre-existing pattern faithfully carried forward or a test-scope choice consistent with the sibling extract workers.
-
----
-
-## 1. `LinkupNoResultError` classified as `TRANSIENT` / `WAIT_AND_RETRY` — LANDED
-
-**Status:** resolved on branch `fix/error-classification-categories`. `_classify_linkup_error` now has an explicit `LinkupNoResultError` branch — `CONTENT` + `CHANGE_INPUT` — in both the search and the extract worker, placed before the `TRANSIENT` catch-all. The `test_data.py` `no_result` cases were updated to expect `CONTENT`, and explicit `to_error_report()` no-result tests assert `retryable is False`. Only two Linkup worker files exist (no third site / shared fallback); both were fixed together.
-
----
-
-## 2. `_search_structured` path not directly tested
-
-The new semantic tests (`test_linkup_search_worker_semantic.py`, `test_gateway_search_worker_semantic.py`) exercise the classification logic only through `_search_sourced_answer`. The `_search_structured` entry point routes through the same shared helper (`_classify_linkup_error` / `_call_relay`), so the classification logic *is* fully covered — but the second entry point is never exercised end-to-end.
-
-This is consistent with the sibling `test_gateway_extract_worker_semantic.py`, which likewise tests only `_extract_web_fetch` and not `_extract_base64_url`. The shared-helper design makes the gap low-risk.
-
-**Resolution:** optional — add a parametrized case (or a `@pytest.mark.parametrize` over the entry-point method) covering `_search_structured` if a regression ever appears there.
-
----
-
-## 3. Gateway test omits non-status `APIError` subtypes
-
-`test_gateway_search_worker_semantic.py` parametrizes the five `APIStatusError` subclasses (HTTP status errors). Non-status `APIError` subtypes — `portkey_exc.APITimeoutError` and `APIConnectionError` — also hit the same `except portkey_exceptions.APIError` branch and would produce metadata with `status_code=None`.
-
-The sibling `test_gateway_extract_worker_semantic.py` has the identical gap, so Phase 12 is consistent with the reference.
-
-**Resolution:** optional — add a parametrized case for a non-status `APIError` (timeout / connection) to both the search and extract Gateway semantic tests to assert the `status_code=None` metadata shape.
-
-**Affected files:**
-
-- `tests/unit/pipelex/plugins/gateway/test_gateway_search_worker_semantic.py`
-- `tests/unit/pipelex/plugins/gateway/test_gateway_extract_worker_semantic.py`
diff --git a/wip/error-handling/review-notes/temporal-activity-boundary-review-followups.md b/wip/error-handling/review-notes/temporal-activity-boundary-review-followups.md
deleted file mode 100644
index 622f0a7fa..000000000
--- a/wip/error-handling/review-notes/temporal-activity-boundary-review-followups.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# Review note — Temporal activity error boundary follow-ups
-
-**Surfaced during:** code review of `cda61bae` "feat: category-aware error boundary on all Temporal activities" (Followup 5 of [track-temporal-integration.md](../track-temporal-integration.md), `_tprl/TODOS.md`).
-
-Two minor, non-blocking observations from the code review. Neither is a regression — each is a deliberate scope choice that is worth recording so a future reader does not mistake it for an oversight.
-
----
-
-## 1. Integration test verifies the converted payload, not Temporal's retry behavior
-
-Both probe workflows in `tests/integration/pipelex/temporal/test_activity_error_boundary.py` pin `RetryPolicy(maximum_attempts=1)`. That is mandatory — without it, a retryable case would loop until timeout and hang the test (see the "Retry loop hang" gotcha in the TODOS). The consequence: the test asserts what `from_app_error` *receives* (the `non_retryable` flag, the structured `ErrorReport`) but never asserts that Temporal *acts* on `non_retryable` — i.e. that a non-retryable error stops the activity retrying while a retryable one does retry.
-
-This gap is acceptable: honoring `non_retryable` is Temporal's own retry-engine behavior, not Pipelex code, and the bridge unit tests (`test_temporal_error_bridge.py`) fully pin the flag derivation. Verifying the engine would mean testing the framework.
-
-**Resolution:** optional — if a regression ever appears, add a probe that lets the activity retry (a retry policy with `maximum_attempts > 1` plus a short `start_to_close_timeout`) and asserts the observed attempt count differs between a `TRANSIENT` and a `CONFIGURATION` `CogtError`.
-
-**Affected file:**
-
-- `tests/integration/pipelex/temporal/test_activity_error_boundary.py`
-
----
-
-## 2. `_error_report_from_details` identifies the report by dict shape
-
-`TemporalError._error_report_from_details` (`pipelex/temporal/tprl/temporal_error.py`) recovers the `ErrorReport` from `ApplicationError.details` by scanning for the first entry that is a `dict` carrying both `error_type` and `message` keys. After Temporal serialization the packed `to_error_report().to_dict()` comes back as a plain mapping with no type tag, so a shape heuristic is the available signal — and the function docstring already says so.
-
-The theoretical false positive: an unrelated `ApplicationError` that never went through this bridge but happens to carry a details dict with both keys would be misread as an error report. Risk is low in practice — `ApplicationError.details` is not otherwise populated in this codebase, and every in-scope activity now routes through `convert_pipelex_errors`.
-
-**Resolution:** optional — if `ApplicationError.details` ever gains other structured payloads, tag the report explicitly (e.g. a `"_pipelex_error_report": true` marker key written by the bridge and checked here) instead of duck-typing on field presence.
-
-**Affected file:**
-
-- `pipelex/temporal/tprl/temporal_error.py`
diff --git a/wip/error-handling/track-cli-delivery.md b/wip/error-handling/track-cli-delivery.md
index dbc81d585..f616c287c 100644
--- a/wip/error-handling/track-cli-delivery.md
+++ b/wip/error-handling/track-cli-delivery.md
@@ -18,7 +18,7 @@ def display_error_panel(
*,
title: str,
fields: list[tuple[str, str]], # (label, escaped value)
- error_message: str,
+ error_message: str | None, # None omits the error body line
tip: str,
links: list[tuple[str, str]], # (label, url)
) -> None:
@@ -34,9 +34,9 @@ Each `handle_*` function constructs the field list and calls the helper; the exc
`pipelex/cli/agent_cli/commands/agent_output.py` defines:
- `CliOutputFormat` (`StrEnum`): `JSON`, `MARKDOWN`.
-- A module-level `ContextVar` (`_agent_cli_output_format`) with `set_agent_cli_output_format()` / `get_agent_cli_output_format()` — set once per invocation from the command's `--format` option, so every downstream `agent_success` / `agent_error` call inherits it without threading the format argument through.
-- `agent_error(message, error_type, cause, **extra)` — dispatches on the active format: JSON to stderr via `_agent_error_json`, or markdown to stderr via `agent_error_markdown`. Both `raise typer.Exit(1) from cause`.
-- `agent_success(result)` — JSON or markdown to stdout, same dispatch.
+- A module-level `ContextVar` (`_agent_cli_error_format`, default `JSON`) with `set_agent_cli_error_format()` / `get_agent_cli_error_format()` — backs the **error** stream only. Each `--format`-aware command sets it at entry via `set_agent_cli_error_format(error_format or output_format)`, so every downstream `agent_error()` call honors it without threading the format through — including error sites that never see the Typer option (factory init failures in `agent_cli_factory.py`, the unknown-command handler, app-callback validation). The **success** stream is threaded explicitly via an `output_format` argument, not the ContextVar.
+- `agent_error(message, error_type, cause, **extra)` — dispatches on the active error format (the `_agent_cli_error_format` ContextVar): JSON to stderr via `_agent_error_json`, or markdown to stderr via `agent_error_markdown`. Both `raise typer.Exit(1) from cause`.
+- `agent_success(result)` — JSON success envelope to stdout (also drains any pending setup warnings into a `warnings` array). `agent_success_formatted(result, markdown_renderer, output_format)` wraps it for `--format`-aware commands: JSON via `agent_success`, or markdown via `markdown_renderer(result)`, dispatched on the explicit `output_format` argument.
- `extract_validation_errors(exc: ValidateBundleError)` — flattens blueprint / factory / validation / instantiation errors into a list per-category. This is the most structured error delivery in the codebase and remains the reference shape.
The JSON error payload:
@@ -62,7 +62,7 @@ The JSON error payload:
### Agent CLI — format coverage
-`--format markdown|json` is wired on `run`, `validate`, `init`, `models`, `doctor`, and `check-model`, with **markdown as the default**. The error path inherits the same option via the `ContextVar`. `inputs` / `concept` / `pipe` / `fmt` / `lint` stay JSON-only. The contract is documented in `pipelex/cli/agent_cli/CLAUDE.md`.
+`--format markdown|json` (success, stdout) is wired on `run`, `validate`, `init`, `models`, `doctor`, and `check-model`, with **markdown as the default**. A companion `--error-format markdown|json` (errors, stderr) is accepted by the same commands and, when omitted, inherits `--format`'s value — it is the option backed by the `_agent_cli_error_format` ContextVar. `inputs` / `concept` / `pipe` / `fmt` / `lint` / `accept-gateway-terms` have neither and stay JSON / raw passthrough. The contract is documented in `pipelex/cli/agent_cli/CLAUDE.md`.
`InferenceSetupRequiredError` is a markdown-by-default special case independent of `--format`: it renders setup-guidance to stdout with exit 0 (used by agent skills on first run).
@@ -90,7 +90,7 @@ The library stays HTTP-agnostic — no web-framework import, only the mapping ta
Delivery itself is landed — the Rich handlers and the agent JSON/markdown path faithfully consume `to_error_report()`. The Temporal hole in that data source is now closed: the submitter-side recovery (`recover_error_report` → `WorkflowExecutionError(error_report=...)`, owned by [track-temporal-integration.md](track-temporal-integration.md)) rebuilds the structured report from `ApplicationError.details`, so a worker-side failure now reaches delivery with the same `error_category` / `retryable` / `model` / `provider` / `user_action` classification as a local run. The fix lived entirely in the Temporal bridge — delivery and `pipelex/cli/agent_cli/` stay Temporal-agnostic.
-The recovered report is carried on `WorkflowExecutionError` as an optional attribute, with a `to_error_report()` override — option (a) from the eng review (2026-05-17). Option (b) (a `RemotePipelexError` carrier in the `__cause__` chain) was rejected: (a) keeps `raise WorkflowExecutionError(msg) from exc` so the Temporal `WorkflowFailureError` stays in the traceback for free, and the override mirrors the 3-line pattern `PipelineExecutionError.to_error_report()` already uses.
+The recovered report is carried on `WorkflowExecutionError` as an optional attribute, with a `to_error_report()` override — option (a) from the eng review. Option (b) (a `RemotePipelexError` carrier in the `__cause__` chain) was rejected: (a) keeps `raise WorkflowExecutionError(msg) from exc` so the Temporal `WorkflowFailureError` stays in the traceback for free, and the override mirrors the 3-line pattern `PipelineExecutionError.to_error_report()` already uses.
The remaining delivery-adjacent work is the metadata migration tracked in [track-metadata-model.md](track-metadata-model.md): while delivery reads `to_error_report()` first, several `PipelexError` subclasses still depend on the fallback dicts because they carry no class-level `error_domain` / `user_action`.
diff --git a/wip/error-handling/archive-delivery-error-path-request-id.md b/wip/error-handling/track-delivery-error-path-request-id.md
similarity index 76%
rename from wip/error-handling/archive-delivery-error-path-request-id.md
rename to wip/error-handling/track-delivery-error-path-request-id.md
index 461767fe4..f7d6e7749 100644
--- a/wip/error-handling/archive-delivery-error-path-request-id.md
+++ b/wip/error-handling/track-delivery-error-path-request-id.md
@@ -1,15 +1,15 @@
# track: request_id correlation on delivery error paths
-**Status:** open. Surfaced by `/code-review xhigh` on commit `07f9cce9`. Decision: TBD.
+**Status:** open. Decision: TBD.
-**TL;DR:** Commits `ceb018b5` (Temporal) and `07f9cce9` (direct-mode) thread `request_id` through `DeliveryExecutor` and into the **success-path** completion log lines. The **failure-path** log/error messages in the same executor still don't carry the field — same correlation gap the feature was meant to close, just on the unhappy path. Three lines in `delivery_executor.py`, plus one debug log in `pipe_run.py`.
+**TL;DR:** Earlier work threaded `request_id` through `DeliveryExecutor` and into the **success-path** completion log lines (Temporal + direct-mode dispatchers). The **failure-path** log/error messages in the same executor still don't carry the field — same correlation gap the feature was meant to close, just on the unhappy path. Three lines in `delivery_executor.py`, plus one debug log in `pipe_run.py`.
## Context
-Greptile's "Delivery logs lose request" PR comment was scoped to "the storage/webhook completion logs don't carry the inbound `X-Request-ID`." We addressed it twice:
+A review's "Delivery logs lose request" comment was scoped to "the storage/webhook completion logs don't carry the inbound `X-Request-ID`." We addressed it twice:
-- `ceb018b5` — `DeliveryActivityArg.request_id` plumbed through to `DeliveryExecutor.execute` and into the **two success log lines** in `_store_results` and `_notify_webhook`.
-- `07f9cce9` — direct-mode `PipeRun.run` forwards `pipe_job.job_metadata.request_id` to `DeliveryExecutor.execute` so non-Temporal dispatchers don't lose correlation.
+- Temporal path — `DeliveryActivityArg.request_id` plumbed through to `DeliveryExecutor.execute` and into the **two success log lines** in `_store_results` and `_notify_webhook`.
+- Direct mode — `PipeRun.run` forwards `pipe_job.job_metadata.request_id` to `DeliveryExecutor.execute` so non-Temporal dispatchers don't lose correlation.
Both commits stopped at the success-path log lines. The failure-path messages — which is exactly where operators most want the correlation — still emit `pipeline_run_id=...` without `request_id`.
@@ -31,7 +31,7 @@ All four lines have `request_id` (or could have it) in local scope — `_store_r
- **Completeness of the stated feature.** The point of threading `request_id` was operator correlation across the delivery phase. Operators most need that correlation when something fails — failed webhooks are exactly when they grep logs for the inbound request id. Leaving the failure messages uncorrelated defeats half the value.
- **Consistency.** Success-path log lines carry the field; failure-path messages don't. Any operator who reads logs will notice the asymmetry and learn the wrong heuristic ("request_id is on success lines only — guess I have to correlate by pipeline_run_id when things break").
- **Cheap.** The exception-path messages already have `pipeline_run_id` interpolated; adding the same conditional suffix that the success path uses is mechanical. No new arguments to thread (the kwarg is already in scope at all three executor sites). Test changes are small.
-- **The feature isn't done until this is done.** The PR review thread for greptile's #3 finding is still open — closing it with "we did half" invites a re-flag.
+- **The feature isn't done until this is done.** The review's #3 finding is still open — closing it with "we did half" invites a re-flag.
## Case for leaving it
@@ -54,7 +54,7 @@ Rationale:
## If we do it
-Single commit on `feature/API-readiness-2`, scoped to `pipelex/pipe_run/delivery_executor.py`:
+Single commit scoped to `pipelex/pipe_run/delivery_executor.py`:
- `_store_results` line 243 — append the existing `request_id_suffix` variable to the error message. (Already constructed at line 238 in the same function.)
- `_notify_webhook` lines 282 and 285 — both error-message constructions. Lift `request_id_suffix` (currently defined at line 279 after the success branch) to the top of the function so both the success and both failure messages can reuse it.
@@ -65,7 +65,7 @@ Sketch commit message:
```
fix(delivery): include request_id in DeliveryExecutor failure messages
-Closes the asymmetric correlation gap left by ceb018b5 / 07f9cce9:
+Closes the asymmetric correlation gap left by the success-path threading:
success-path completion logs carry request_id, but the matching
exception messages on storage/webhook failure paths still did not.
Operators correlating failed deliveries to inbound X-Request-ID had
@@ -80,18 +80,16 @@ refactor to a request-bound contextvar.
## Decision criteria
Push toward **close now** if:
-- The PR thread on greptile's "Delivery logs lose request" comment is still open and we don't want to leave it for a re-flag.
+- The review thread on the "Delivery logs lose request" comment is still open and we don't want to leave it for a re-flag.
- Operators have already raised an issue about asymmetric correlation in delivery failures.
- Cost of the fix stays as small as sketched (single-file, single-commit, one regression test).
Push toward **defer** if:
-- We're racing the merge of `feature/API-readiness-2` and any further change widens the audit surface.
+- We're racing a merge and any further change widens the audit surface.
- We want to land the altitude refactor (contextvar / structured-log adapter) first and not pay the per-line cost twice.
-- The greptile thread is already closed and a separate PR for the failure-path is acceptable.
+- The review thread is already closed and a separate PR for the failure-path is acceptable.
## References
-- Commit `ceb018b5` — `feat(delivery): thread request_id through DeliveryExecutor for cross-phase log correlation` (success-path lines).
-- Commit `07f9cce9` — `fix(delivery): forward request_id from PipeRun direct-mode dispatcher to DeliveryExecutor`.
-- `/code-review xhigh` outputs from both review passes — error-path findings #1-#3.
-- PR #943, greptile comment thread `PRRT_kwDOOwmMFc6FHCBU`.
+- The success-path threading in `DeliveryExecutor` (Temporal + direct-mode) — the prior work this builds on.
+- The code-review error-path findings that surfaced this gap.
diff --git a/wip/error-handling/track-extract-classify-render.md b/wip/error-handling/track-extract-classify-render.md
index 4761fe3c1..fd3e8c319 100644
--- a/wip/error-handling/track-extract-classify-render.md
+++ b/wip/error-handling/track-extract-classify-render.md
@@ -1,280 +1,40 @@
-# Track — Extract / Classify / Render Decomposition
+# Extract / Classify / Render — as built
-> **Status: landed on `refactor/ECR`.** Every inference worker's `except` block now collapses to `extract → classify → raise render(...) from exc`. **Classify** lives in `pipelex/cogt/inference/error_classify.py`, **Render** in `error_render.py`; the per-provider `extract_*_metadata` functions stay in `pipelex/cogt/inference/error_classification.py`. The per-provider `*_error_classification.py` files, `AnthropicCredentialsError`, and the dead `GatewayFactory` Portkey-classify helpers are deleted. Per-provider quota probes are now module-private (`_is_quota_exhaustion_*`), reachable only through `ProviderErrorMetadata.is_quota_exhaustion`. A new parity meta-test (`tests/unit/pipelex/cogt/inference/test_provider_classification_parity.py`) walks every `ProviderName` against the extract-fn registry, so adding a new provider without wiring it fails fast.
->
-> The rest of this doc describes the **pre-refactor problem and the design** that the refactor implements. It is kept as the historical motivation; the code is now in its post-refactor state.
+**Status: landed.** Every inference worker's `except` block resolves an SDK exception through one shared three-step chain — **extract → classify → render** — instead of hand-coding metadata extraction, categorization, and error construction inline. Only the Extract step is per-provider; Classify and Render are single shared functions.
-## What this track is
+## How it works
-Today every inference worker performs three logically separate steps inline inside its `except` blocks: (1) **Extract** structured metadata from the SDK exception (status code, request id, retry-after, error code, body), (2) **Classify** the error into an `InferenceErrorCategory` + `UserActionKind`, and (3) **Render** a `CogtError` subclass with a human-readable message and the categorization attached. The three steps are tangled together, and every new provider duplicates the entire pipeline.
+The chain lives in `pipelex/cogt/inference/`:
-This track proposes decomposing the pipeline so that only the **Extract** step is per-provider. **Classify** and **Render** become provider-agnostic and share a single implementation across all 18+ workers.
+- **Extract** (per-provider) — `extract_<provider>_metadata(exc) -> ProviderErrorMetadata` in `error_classification.py`, one function per provider. It pulls the structured fields out of the SDK exception — status code, request id, retry-after, provider error code, message, body — into a `ProviderErrorMetadata` (aliased `SDKErrorEnvelope`). This is the only place provider-specific attribute access lives.
+- **Classify** (shared, pure) — `classify_inference_error(metadata: SDKErrorEnvelope) -> ClassificationResult` in `error_classify.py`. Provider-agnostic: it maps the envelope — status code, the computed `@property` flags `is_quota_exhaustion` / `is_content_policy_violation` / `is_network_error`, and a status-less-exception-name table — to a `ClassificationResult` carrying `category: InferenceErrorCategory`, `user_action_kind: UserActionKind`, and `is_model_not_found: bool`. Because it reads only the envelope, it is tested against synthetic envelopes with no SDK installed.
+- **Render** (shared) — `render_inference_error(metadata, classification, family, model_desc, model_handle) -> CogtError` in `error_render.py`. It builds the concrete `CogtError` subclass selected by the worker `family` (`InferenceErrorFamily`: `LLM` / `IMG_GEN` / `EXTRACT` / `SEARCH`), composes the message and `UserAction`, and attaches the metadata.
-This track is **proposed but not started.** It is the natural next step after the worker-classification sweep, which has landed ([archive-worker-classification-sweep.md](archive-worker-classification-sweep.md)): now that every worker uniformly attaches `ProviderErrorMetadata` and a structured `UserAction`, the duplication across workers is the dominant complexity, and decomposition is the obvious cleanup.
-
-## Current state
-
-After the worker-classification sweep, a worker looks like this:
-
-```python
-except RateLimitError as exc:
- metadata = extract_openai_metadata(exc)
- if is_quota_exhaustion_openai(metadata.message):
- msg = f"OpenAI quota exhausted for model '{self.inference_model.desc}': {exc}"
- raise LLMCompletionError(
- message=msg,
- error_category=InferenceErrorCategory.CAPACITY,
- user_action=UserAction(
- kind=UserActionKind.CHECK_BILLING,
- detail="Your OpenAI account has exceeded its quota — check your billing dashboard",
- ),
- provider_metadata=metadata,
- ) from exc
- msg = f"Rate limited by OpenAI for model '{self.inference_model.desc}': {exc}"
- raise LLMCompletionError(
- message=msg,
- error_category=InferenceErrorCategory.TRANSIENT,
- user_action=UserAction(
- kind=UserActionKind.WAIT_AND_RETRY,
- detail=f"Rate limited by OpenAI — will retry after {metadata.retry_after_seconds}s",
- ),
- provider_metadata=metadata,
- ) from exc
-```
-
-This same shape repeats across:
-
-- 6 LLM workers
-- 7 img-gen workers
-- 5 extract workers
-- 2 search workers
-- Gateway variants
-
-Each worker duplicates: the discriminator invocation, the message construction, the `UserAction` composition, the `from exc` chaining, the `error_category` selection, and the `provider_metadata` attachment. A new provider (or a new SDK exception type) requires modifying all three steps in lockstep.
-
-Discriminator helpers like `is_quota_exhaustion_openai` (in `pipelex/cogt/inference/error_classification.py`) are extraction primitives but they live alongside classification logic, and they're called from inside each worker rather than from a central Classify step.
-
-## Open gaps
-
-### Duplicated classification logic across providers
-
-Every worker hard-codes the mapping `(SDK exception, status_code, message_pattern) → (category, user_action_kind)`. Adding a new category (e.g. splitting `TRANSIENT` into `RATE_LIMITED` and `SERVER_ERROR`) requires touching every worker.
-
-### Coupling between extraction and rendering
-
-The message string is composed inline using both the SDK exception and the categorization result. There is no clean separation between "what happened" (factual metadata) and "what the user should be told" (presentation). Localization, structured logging, and provider-blind testing all suffer.
-
-### New SDK exception types are silent gaps
-
-If a provider adds a new SDK exception type, today's categorization helper returns without raising and falls through to `UNKNOWN`. The Extract layer would centralize "did we see something we don't recognize" detection in one place — and emit a metric the moment the unknown class appears, instead of waiting for a categorization audit.
-
-### Cross-provider parity testing is expensive
-
-Testing that "every provider classifies HTTP 429 as TRANSIENT" requires a per-provider test fixture today. With decomposition, the Classify step becomes a pure function `(envelope) → (category, user_action_kind)` that can be tested provider-blind against synthetic envelopes — provider parity reduces to "every Extract function produces a well-formed envelope."
-
-## Proposed design
-
-### Three layers
-
-**1. Extract** (per-provider, small):
-
-```python
-def extract_anthropic_metadata(exc: anthropic.APIError) -> SDKErrorEnvelope:
- response = getattr(exc, "response", None)
- return SDKErrorEnvelope(
- provider=ProviderName.ANTHROPIC,
- sdk_exception_type=type(exc).__name__,
- status_code=getattr(response, "status_code", None),
- request_id=getattr(exc, "request_id", None),
- retry_after_seconds=_parse_retry_after(response),
- provider_error_code=getattr(exc, "type", None),
- message=str(exc),
- body=getattr(exc, "body", None),
- )
-```
-
-Each provider has exactly one Extract function. Adding a provider = adding one function. The function is the only place provider-specific attribute access lives.
-
-**2. Classify** (shared, pure):
-
-```python
-def classify_inference_error(envelope: SDKErrorEnvelope) -> ClassificationResult:
- if envelope.status_code == 429:
- if envelope.is_quota_exhaustion:
- return ClassificationResult(
- category=InferenceErrorCategory.CAPACITY,
- user_action_kind=UserActionKind.CHECK_BILLING,
- )
- return ClassificationResult(
- category=InferenceErrorCategory.TRANSIENT,
- user_action_kind=UserActionKind.WAIT_AND_RETRY,
- )
- if envelope.status_code in (502, 503, 504):
- return ClassificationResult(InferenceErrorCategory.TRANSIENT, UserActionKind.WAIT_AND_RETRY)
- if envelope.status_code in (401, 403):
- return ClassificationResult(InferenceErrorCategory.CONFIGURATION, UserActionKind.CHECK_CREDENTIALS)
- if envelope.is_content_policy_violation:
- return ClassificationResult(InferenceErrorCategory.CONTENT, UserActionKind.CHANGE_INPUT)
- if envelope.status_code == 404:
- return ClassificationResult(InferenceErrorCategory.CONFIGURATION, UserActionKind.CHANGE_MODEL)
- ...
- return ClassificationResult(InferenceErrorCategory.UNKNOWN, UserActionKind.CONTACT_SUPPORT)
-```
-
-One function. Provider-agnostic. Tests are synthetic-envelope-driven and don't need any SDK installed.
-
-**3. Render** (shared, small):
-
-```python
-def render_inference_error(
- envelope: SDKErrorEnvelope,
- classification: ClassificationResult,
- model_desc: str,
- error_type: type[CogtError],
-) -> CogtError:
- detail = _default_detail(envelope, classification)
- msg = _format_message(envelope, model_desc, classification.category)
- return error_type(
- message=msg,
- error_category=classification.category,
- user_action=UserAction(kind=classification.user_action_kind, detail=detail),
- provider_metadata=envelope,
- )
-```
-
-### Worker shape after decomposition
+A worker `except` block is three lines:
```python
except anthropic.APIError as exc:
- envelope = extract_anthropic_metadata(exc)
- classification = classify_inference_error(envelope)
+ metadata = extract_anthropic_metadata(exc)
+ classification = classify_inference_error(metadata)
raise render_inference_error(
- envelope, classification, self.inference_model.desc, LLMCompletionError,
+ metadata, classification, InferenceErrorFamily.LLM, self.inference_model.desc, model_handle,
) from exc
```
-Three lines per catch. Worker code shrinks dramatically — most existing 30-line catch bodies become a single delegation.
-
-## Tradeoffs
-
-**For:**
-
-- New providers and new SDK exception types only need an Extract function update.
-- Classify is one provider-agnostic function — easier to test exhaustively, easier to reason about.
-- Cross-provider parity tests become trivial (synthesize an envelope, assert classification).
-- Localization and CLI rendering changes touch one Render function, not 18+.
-- Tests of Classify are provider-blind — they run without any SDK installed (faster, fewer cross-package imports).
-
-**Against:**
-
-- Real refactor — touches every worker. Should land in one coordinated sweep, not piecemeal.
-- Some provider-specific nuance (Anthropic's `type` vs. OpenAI's `code` vs. Google's nested error structure) must be encoded in either the envelope schema OR the Classify function. Risk: the envelope becomes a kitchen sink. Mitigation: keep envelope schema flat and provider-blind; put any "is this a quota error?" smarts into computed `@property` accessors that read `status_code` + `message` + `provider`.
-- Today's per-worker tests test the full pipeline end-to-end; after decomposition, per-worker tests only verify the Extract function, and a new test suite covers Classify+Render. More test files; each is smaller and faster.
-- The Anthropic worker is currently the "reference" implementation. After this refactor, the reference is split across `extract_anthropic_metadata`, the shared Classify helper, and the shared Render helper. The Anthropic worker file shrinks dramatically. Some readers find that disorienting at first.
-
-## Risks and gotchas
-
-### `InferenceErrorCategory` granularity
-
-Decomposition exposes the limitations of today's categories. May want to split `TRANSIENT` → `RATE_LIMITED` / `SERVER_ERROR` / `NETWORK` at the same time. Mitigation: do the refactor with existing categories first; split categories in a follow-up if needed. The Classify function makes the split trivial later.
-
-### Provider-specific user actions
-
-Some providers have unique recovery actions (e.g. AWS regional capacity → "try another region"). The `UserActionKind` enum needs to be expressive enough OR the `detail` field carries the provider-specific advice. Mitigation: start with the existing `UserActionKind` set; add new kinds only when a provider-specific case can't be expressed via detail.
-
-### Streaming errors
-
-Currently no worker streams. If streaming is added, the envelope schema must handle partial-response errors (partial body, error mid-stream, resume index). Mitigation: out of scope until a streaming worker materializes.
-
-### `InstructorRetryException` integration
-
-The unwrap helper from track-worker-classification stays — it returns the SDK exception, which then goes through `extract_<provider>_metadata`. The decomposition assumes the helper has already unwrapped. The fallback case (unrecognized underlying like `pydantic.ValidationError`) becomes "envelope with `sdk_exception_type='ValidationError'` and `provider=<the provider>`, classify → UNKNOWN" — clean.
-
-### Envelope field optionality
-
-Some providers don't always populate every field (e.g. Google's `genai_errors.ClientError` doesn't always carry a `request_id`). The envelope must be permissive (Optional fields) but the Classify function must not assume optionals are present without checks.
-
-## Followups
-
-### 1. Define the schemas
-
-- `SDKErrorEnvelope` (Pydantic `BaseModel`):
- - `provider: ProviderName`
- - `sdk_exception_type: str`
- - `status_code: int | None`
- - `request_id: str | None`
- - `retry_after_seconds: float | None`
- - `provider_error_code: str | None`
- - `message: str`
- - `body: Any | None`
- - Computed `@property`: `is_quota_exhaustion`, `is_content_policy_violation`, `is_network_error`
-- `ClassificationResult` (Pydantic `BaseModel`): `category: InferenceErrorCategory`, `user_action_kind: UserActionKind`
-- `ProviderName` (`StrEnum` from `pipelex.types`): one value per provider plugin (`ANTHROPIC`, `OPENAI`, `MISTRAL`, `GOOGLE`, `BEDROCK`, `AZURE`, `FAL`, `HUGGINGFACE`, `DOCLING`, `LINKUP`, `GATEWAY`, ...)
-
-`SDKErrorEnvelope` is likely identical to the existing `ProviderErrorMetadata` (`pipelex/cogt/inference/error_classification.py`) — rename rather than reintroduce.
-
-### 2. Write the Classify function first (TDD)
-
-Pure function, easy to test with synthetic envelopes. Build the test suite that captures cross-provider parity rules:
-
-| Envelope shape | Expected category | Expected user_action_kind |
-|---|---|---|
-| status=429, is_quota_exhaustion=False | TRANSIENT | WAIT_AND_RETRY |
-| status=429, is_quota_exhaustion=True | CAPACITY | CHECK_BILLING |
-| status=503 | TRANSIENT | WAIT_AND_RETRY |
-| status=401 | CONFIGURATION | CHECK_CREDENTIALS |
-| status=400, is_content_policy_violation=True | CONTENT | CHANGE_INPUT |
-| status=400, is_content_policy_violation=False | CONTENT | (default) |
-| status=404 | CONFIGURATION | CHANGE_MODEL |
-| status=None, sdk_exception_type="ConnectionError" | TRANSIENT | WAIT_AND_RETRY |
-| status=None, sdk_exception_type="TimeoutError" | TRANSIENT | WAIT_AND_RETRY |
-| status=None, sdk_exception_type="ValidationError" | CONTENT | (default) |
-| Everything else | UNKNOWN | CONTACT_SUPPORT |
-
-### 3. Write the Render function
-
-Mostly mechanical. Tests use synthetic envelopes + classifications.
-
-### 4. Migrate workers one at a time
-
-Each worker gets:
-
-- A new `extract_<provider>_metadata` function in `pipelex/cogt/inference/error_classification.py` (or co-located with the provider plugin if cleaner)
-- A single tuple-catch in the worker that delegates to extract → classify → render
-- Existing per-worker tests rewritten to use the new shape — most categorization assertions move to the Classify test suite
-
-The per-worker test surface SHRINKS (the worker now does less). The Classify and Render test surface is paid once, not per provider. Net win.
-
-### 5. Delete redundant discriminator helpers
-
-`is_quota_exhaustion_<provider>` becomes either:
-
-- A computed `@property` on `SDKErrorEnvelope` (preferred — provider + status_code + message decide)
-- A private helper called from inside Classify
-
-Either way, the per-worker callers go away.
-
-### 6. Cross-provider parity meta-test
-
-Once all workers are migrated, write a meta-test that exercises every (provider, error-category) pair: given each provider's Extract function and a synthetic exception per category, verify the rendered error has the expected category, user_action_kind, and a populated request_id. Catches "we added a provider and forgot to wire it up" regressions.
-
-## Prerequisites — all met
-
-This refactor depended on the worker-classification sweep landing first. Those prerequisites are all in place:
+## What this buys
-- `InferenceErrorCategory.UNKNOWN` exists (`pipelex/cogt/exceptions.py`).
-- `ProviderErrorMetadata` exists as a Pydantic model with the right field shape — likely renamed to `SDKErrorEnvelope` when this refactor starts (`pipelex/cogt/inference/error_classification.py`).
-- `UserAction` is structured (`UserActionKind` enum + `detail` string).
-- The `instructor`-unwrap fix is landed on every LLM worker, so each has a clean post-unwrap call site to refactor.
+- Adding a provider — or a new SDK exception type — is an Extract-only change; Classify and Render are untouched.
+- Classification rules live in one provider-agnostic function, tested exhaustively against synthetic envelopes (no SDK imports).
+- Human-facing message formatting lives in one Render function rather than being duplicated per worker.
-The refactor can start whenever it is prioritized; nothing blocks it.
+## Adding a provider
-**Estimated effort:** 2–3 days of focused work — mostly mechanical migration after the schemas are right.
+Write one `extract_<provider>_metadata` function in `error_classification.py` and wire it at the worker's `except` site. `tests/unit/pipelex/cogt/inference/test_provider_classification_parity.py` walks every `ProviderName` against the extract-function registry, so a provider added without a wired Extract function fails fast.
## Related tracks
-- [track-worker-classification.md](track-worker-classification.md) — the current per-worker classification. This track is the next step once classification is uniform across providers.
-- [track-metadata-model.md](track-metadata-model.md) — the data contract this track restructures. `ProviderErrorMetadata` becomes `SDKErrorEnvelope`.
-- [track-retry-and-resilience.md](track-retry-and-resilience.md) — benefits from the structured `retry_after_seconds` and uniform category-to-retry policy that decomposition makes obvious.
-- [track-testing.md](track-testing.md) — cross-provider parity tests become much cheaper with provider-blind Classify tests.
-- [track-cli-delivery.md](track-cli-delivery.md) — the Render layer becomes the single place to update human-facing message formatting.
+- [track-worker-classification.md](track-worker-classification.md) — where SDK exceptions are caught; the per-worker classification this chain consolidated.
+- [track-metadata-model.md](track-metadata-model.md) — the `ProviderErrorMetadata` / `error_category` / `user_action` data contract this chain produces.
+- [track-retry-and-resilience.md](track-retry-and-resilience.md) — consumes the uniform `error_category` and `retry_after_seconds` for retry decisions.
+- [track-testing.md](track-testing.md) — the provider-blind Classify tests and the cross-provider parity meta-test.
+- [track-cli-delivery.md](track-cli-delivery.md) — Render is the single place human-facing message formatting is shaped.
diff --git a/wip/error-handling/track-metadata-model.md b/wip/error-handling/track-metadata-model.md
index 6f6b86ed9..76569258c 100644
--- a/wip/error-handling/track-metadata-model.md
+++ b/wip/error-handling/track-metadata-model.md
@@ -2,7 +2,7 @@
## What this track is
-The contract for **what every exception carries** so it can be rendered identically to humans, agents, and Temporal: `error_type`, `message`, `error_category` (TRANSIENT / CONFIGURATION / CONTENT / CAPACITY / UNKNOWN), `error_domain` (input / config / runtime), `user_action`, `retryable`, optional `model`, `provider`, and `provider_metadata`. The metadata lives on the exception class itself so there is a single source of truth.
+The contract for **what every exception carries** so it can be rendered identically to humans, agents, and Temporal: `error_type`, `message`, `title`, `type_uri`, `error_category` (TRANSIENT / CONFIGURATION / CONTENT / CAPACITY / AMBIGUOUS / UNKNOWN), `error_domain` (input / config / runtime), `user_action`, `retryable`, optional `model`, `provider`, and `provider_metadata`. The metadata lives on the exception class itself so there is a single source of truth.
The model is **landed for inference errors and the major pipeline/interpreter/service exceptions** — they self-describe via class-level attributes consumed through `to_error_report()`. The remaining work is closing the long tail: a handful of `CogtError` subclasses still carry no class-level `error_category`, and several `PipelexError` subclasses still depend on the fallback dicts in `agent_output.py` rather than carrying their own `error_domain` / `user_action`.
@@ -10,28 +10,31 @@ The model is **landed for inference errors and the major pipeline/interpreter/se
### `ErrorReport` — the serialization schema
-`ErrorReport` (`pipelex/base_exceptions.py`) is a frozen pydantic dataclass with `extra="forbid"`:
+`ErrorReport` (`pipelex/base_exceptions.py`) is a frozen `BaseModel` (`ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)`):
```
ErrorReport
- error_type: str
- message: str
- error_category: str | None
- error_domain: str | None
- retryable: bool | None
- user_action: UserAction | None
- model: str | None
- provider: str | None
- provider_metadata: ProviderErrorMetadata | None
+ error_type: str
+ message: str
+ title: str
+ type_uri: str
+ error_category: str | None
+ error_domain: str | None
+ retryable: bool | None
+ user_action: UserAction | None
+ model: str | None
+ provider: str | None
+ provider_metadata: ProviderErrorMetadata | None
+ caller_facing_message: bool
```
-`to_dict()` drops `None` fields. `http_status` maps the report to an HTTP status for downstream API adapters (see [track-cli-delivery.md](track-cli-delivery.md)).
+`to_dict(disclosure_mode=VERBOSE)` returns the non-`None` fields and round-trips through `from_dict`; `STRICT` is a lossy projection for untrusted external surfaces (see [architecture.md](architecture.md) for `DisclosureMode`). `http_status` maps the report to an HTTP status for downstream API adapters (see [track-cli-delivery.md](track-cli-delivery.md)).
-`PipelexError.to_error_report()` returns `error_type`, `message`, and the class-level `error_domain`. `CogtError.to_error_report()` overrides it to add `error_category`, `retryable` (derived from category via `InferenceErrorCategory.is_retryable`), `user_action`, `provider_metadata`, and reads `model_handle` / `backend_name` from the instance when present. `to_error_report()` also enriches from the `__cause__` chain, so a wrapper exception surfaces the inference metadata of the underlying `CogtError`.
+`PipelexError.to_error_report()` returns `error_type`, `message`, `title`, `type_uri`, the class-level `error_domain`, `user_action`, and `caller_facing_message`. `CogtError.to_error_report()` overrides it to layer on `error_category`, `retryable` (derived from category via `InferenceErrorCategory.is_retryable`), `provider_metadata`, and the `model` / `provider` it reads from the instance's `model_handle` / `backend_name` when present. `to_error_report()` also enriches from the `__cause__` chain, so a wrapper exception surfaces the inference metadata of the underlying `CogtError` (`title` / `type_uri` stay wrapper-wins).
### Inference categories
-`InferenceErrorCategory` (`pipelex/cogt/exceptions.py`) is a `StrEnum` with values `TRANSIENT`, `CONFIGURATION`, `CONTENT`, `CAPACITY`, `UNKNOWN` and an `is_retryable` property — `True` only for `TRANSIENT`. Implemented with `match/case` per the project's enum style.
+`InferenceErrorCategory` (`pipelex/cogt/exceptions.py`) is a `StrEnum` with values `TRANSIENT`, `CONFIGURATION`, `CONTENT`, `CAPACITY`, `AMBIGUOUS`, `UNKNOWN` and an `is_retryable` property — `True` only for `TRANSIENT`. Implemented with `match/case` per the project's enum style. `AMBIGUOUS` and `UNKNOWN` are both non-retryable but distinct: `AMBIGUOUS` means the error type is known yet the outcome is not (e.g. a connection dropped mid-request on a non-idempotent call, so a blind retry is unsafe), while `UNKNOWN` means classification failed outright.
### Error domains
diff --git a/wip/error-handling/track-retry-and-resilience.md b/wip/error-handling/track-retry-and-resilience.md
index 677554085..f57d3a840 100644
--- a/wip/error-handling/track-retry-and-resilience.md
+++ b/wip/error-handling/track-retry-and-resilience.md
@@ -51,7 +51,7 @@ None for this track. The one open-ended item is a review (not a change) of wheth
## Out of scope — dependencies, not part of this track
-These are real and belong to the hosted product, but they are platform/product concerns, not the engine's retry behavior. They live in [../temporal-next/00-enterprise-readiness-analysis.md](../temporal-next/00-enterprise-readiness-analysis.md).
+These are real and belong to the hosted product, but they are platform/product concerns, not the engine's retry behavior. They are tracked in the internal enterprise-readiness plans.
- **Multi-tenant admission control and per-tenant quotas / rate limits.** Tier 1 obeys a rate limit *after* hitting it; proactive pacing keyed to a provider account is separate and platform-global, not per-run.
- **Caller-supplied run deadline / budget** — a ceiling on total time or spend that bounds every tier. Belongs with the API submission envelope.
@@ -62,5 +62,3 @@ These are real and belong to the hosted product, but they are platform/product c
- [track-temporal-integration.md](track-temporal-integration.md) — Tier 2: how `InferenceErrorCategory` drives Temporal's retry decision.
- [track-metadata-model.md](track-metadata-model.md) — `ProviderErrorMetadata` carries `retry_after_seconds` for the error report; the SDK does its own `Retry-After` handling for retries.
-- [archive-retry-and-resilience.md](archive-retry-and-resilience.md) — the implementation plan and checkpoint history for the two workstreams that landed this track.
-- [../temporal-next/00-enterprise-readiness-analysis.md](../temporal-next/00-enterprise-readiness-analysis.md) — the multi-tenant / hosted concerns scoped out above.
diff --git a/wip/error-handling/track-strict-disclosure-input-domain-gap.md b/wip/error-handling/track-strict-disclosure-input-domain-gap.md
deleted file mode 100644
index cc56f2267..000000000
--- a/wip/error-handling/track-strict-disclosure-input-domain-gap.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# STRICT disclosure — INPUT-domain passthrough gap
-
-> **Landed 2026-05-22** on `feature/API-readiness-2` (Phase 1 of `_for_api/TODOS.md`). Fixed via **Option 1**: a per-class `PipelexError._authors_caller_facing_message` `ClassVar` — default `False`, set `True` on `PipelexInterpreterError` and `ValidateBundleError` (the two INPUT-domain classes whose messages describe the caller's own input). It is carried onto a new `ErrorReport.caller_facing_message` field at report construction, is *not* inherited up the `__cause__` chain (so a domain-less wrapper over an INPUT cause does not pick it up), and gates the STRICT `message` passthrough — replacing the old `error_domain == INPUT` check. **Gap 2 closed too:** `provider` / `model` / `provider_metadata` are now stripped from the STRICT passthrough branch as well, so STRICT never emits provider metadata for any `error_domain`. The `DisclosureMode` docstring matches the implemented redaction set. The rest of this doc is the original analysis, kept for context.
-
-Follow-up surfaced during the /review pass on the Stage 2 disclosure-mode work (Item C). Not a blocker for the error-handling refactor — STRICT redaction is correct for `CONFIG` / `RUNTIME` reports, which is the path the API exercises today — but the `INPUT`-domain passthrough has two soft spots that should be tightened before the API starts rendering STRICT for caller-facing surfaces.
-
-## What
-
-`DisclosureMode.STRICT` is documented as a *classification-projection for server-side errors*: `CONFIG` / `RUNTIME` reports get `message` replaced and `provider` / `model` / `provider_metadata` / `user_action` dropped, while `INPUT`-domain reports pass through unchanged because their `message` is caller-influenced. Two cases let that `INPUT` exemption cover more than it should.
-
-### Gap 1 — a domain-less wrapper inherits `INPUT` and leaks its own message
-
-`ErrorReport.to_dict(STRICT)` keys the passthrough on the report's final `error_domain == ErrorDomain.INPUT`. But `PipelexError._enrich_error_report_from_cause` fills `error_domain` from the `__cause__` chain:
-
-```python
-error_domain=report.error_domain or cause_report.error_domain,
-```
-
-A wrapper whose own class declares no domain (`PipelexError` base, `PipelexUnexpectedError` — both `error_domain = None`) raised `from` an `INPUT`-domain cause produces a report classified `error_domain=INPUT` **while keeping the wrapper's own `message`**. That wrapper message was authored as internal / "unexpected" text, not as caller-facing `INPUT` copy — so STRICT reflects it back verbatim to any surface that asked for STRICT.
-
-The redaction decision is keyed on an *inherited classification* rather than on the *provenance of the message it is protecting*.
-
-### Gap 2 — `to_problem_document` echoes provider/model for `INPUT` reports in STRICT
-
-Because STRICT returns `INPUT` reports unchanged, `to_problem_document` then copies every non-RFC-7807-mapped key onto the envelope — including `provider`, `model`, `provider_metadata`, `user_action` — when an `INPUT` report's cause-enrichment pulled them from an inference-layer `__cause__`. The `DisclosureMode` docstring states these fields are "dropped" in STRICT; that is true only on the `CONFIG` / `RUNTIME` branch, not the `INPUT` passthrough.
-
-## Why this is a follow-up, not an immediate fix
-
-- STRICT is correct and complete for `CONFIG` / `RUNTIME` reports — the only path the API renders today.
-- Both gaps need a real chain to bite: a domain-less wrapper raised `from` an `INPUT` cause, carrying a sensitive message / provider metadata. Whether such chains exist in practice needs an audit, not a guess (medium confidence, 6/10).
-- The fix is a design choice (see Options) that deserves its own focused change rather than riding the refactor PR.
-
-## Options
-
-### Option 1 — gate STRICT passthrough on message provenance, not inherited domain (preferred)
-
-Add an explicit per-class `ClassVar` marking which error classes genuinely author caller-facing messages (e.g. `PipelexInterpreterError`, bundle-validation errors), and gate the STRICT passthrough on that flag instead of on `error_domain == INPUT`. A domain-less wrapper over an `INPUT` cause then redacts normally.
-
-### Option 2 — don't inherit `error_domain` onto a domain-less wrapper
-
-In `_enrich_error_report_from_cause`, stop inheriting `error_domain` when the wrapper's own class declares none. Smaller change, but it also changes `http_status` for those wrappers (they'd fall back to 500 instead of the cause's status) — needs a sweep of the status-mapping tests.
-
-### Either option, plus
-
-Strip `provider` / `model` / `provider_metadata` from the `INPUT` passthrough branch of `to_dict(STRICT)` — an input-classification error has no business carrying provider metadata onto an external surface — and align the `DisclosureMode` docstring with whatever the final behavior is.
-
-## Acceptance — all met (2026-05-22)
-
-- [x] A domain-less wrapper (`PipelexUnexpectedError`) raised `from` an `INPUT`-domain cause does not leak the wrapper's `message` through `to_dict(STRICT)`.
-- [x] `to_problem_document(disclosure_mode=STRICT)` never emits `provider` / `model` / `provider_metadata` regardless of `error_domain`.
-- [x] The `DisclosureMode` STRICT docstring matches the implemented redaction set.
diff --git a/wip/error-handling/track-temporal-integration.md b/wip/error-handling/track-temporal-integration.md
index 9394e32d0..bba98c83e 100644
--- a/wip/error-handling/track-temporal-integration.md
+++ b/wip/error-handling/track-temporal-integration.md
@@ -40,7 +40,7 @@ The class-name list is documented as a **fallback only**: a `CogtError` carrying
The bridge moves the `ErrorReport` activity → workflow, and `from_app_error` recovers it for workflow code. The symmetric workflow → submitter recovery — reading the report back out of `ApplicationError.details` once the failure returns to the process that submitted the workflow — is now landed:
-- `recover_error_report` (`pipelex/temporal/tprl/temporal_error.py`) walks the failure's `__cause__` chain for an `ApplicationError`, pulls the details-packed report dict via the now-public `error_report_dict_from_details`, and rebuilds an `ErrorReport` through `ErrorReport.from_dict` (the strict inverse of `to_dict`, added in `pipelex/base_exceptions.py`). It tolerates worker/submitter version skew — unknown keys are dropped, a dict that still fails validation yields `None` — so the error path never crashes.
+- `recover_error_report` (`pipelex/temporal/tprl/temporal_error.py`) walks the failure's `__cause__` chain for an `ApplicationError`, pulls the details-packed report dict via the now-public `error_report_dict_from_details`, and rebuilds an `ErrorReport` through `ErrorReport.from_dict` (the strict inverse of `to_dict` in VERBOSE mode). It is **total** — it always returns an `ErrorReport`, never `None`. When the chain carries no report payload (a non-Pipelex exception, a worker crash, a heartbeat timeout) it synthesizes an `UnrecoverableWorkflowFailureError` report (`error_domain=RUNTIME`) carrying the most informative message recoverable from the chain. `from_dict` is `extra="forbid"`, so a found-but-malformed payload is an internal contract bug within one deploy (the activity bridge and submitter share the schema); rather than raise — which would abort the caller before it delivers the failure webhook — it synthesizes the same `UnrecoverableWorkflowFailureError` fallback, tagged with an `[error report failed schema validation]` marker so the contract bug stays visible on the wire. The error path therefore never crashes and the receiver is always notified.
- `WorkflowExecutor.execute_workflow` (`pipelex/temporal/tprl/workflow_caller.py`) splits the combined handler into a dedicated `except WorkflowFailureError` clause that recovers the report and a sibling `except (WorkflowAlreadyStartedError, RPCError)` clause that stays generic. The recovered report is carried on `WorkflowExecutionError(error_report=...)`, and the original failure message replaces the generic `"Failed to execute workflow ..."`.
- `WorkflowExecutionError.to_error_report()` returns the recovered report when present; with no report it falls through to base `__cause__`-chain enrichment. `PipelineExecutionError` then inherits the classification natively, since `WorkflowExecutionError` is a `PipelexError`.
@@ -56,7 +56,7 @@ The child-workflow boundary (`execute_child_workflow` / `start_child_workflow` i
### Deferred review followups
-Two optional refinements from the activity-boundary code review are recorded in [review-notes/temporal-activity-boundary-review-followups.md](review-notes/temporal-activity-boundary-review-followups.md): the integration test verifies the converted payload rather than Temporal's retry-engine behavior, and `error_report_dict_from_details` identifies the report by dict shape. Both are deliberate scope choices, optional to revisit.
+Two optional refinements from the activity-boundary review (tracked in the deferred backlog) remain deliberate scope choices: the integration test verifies the converted payload rather than Temporal's retry-engine behavior, and `error_report_dict_from_details` identifies the report by dict shape. Optional to revisit.
## Related tracks
diff --git a/wip/error-handling/track-testing.md b/wip/error-handling/track-testing.md
index dd2d9f4c9..ba24c9261 100644
--- a/wip/error-handling/track-testing.md
+++ b/wip/error-handling/track-testing.md
@@ -34,7 +34,7 @@ Coverage is landed at every level: per-worker classification, the classification
## Open gaps
-None load-bearing. Two optional refinements are recorded in [review-notes/](review-notes/): the Temporal integration tests verify the converted payload rather than Temporal's retry-engine behavior, and a couple of search/extract worker tests omit non-status `APIError` subtypes. Both are deliberate scope choices.
+None load-bearing. Two optional refinements (tracked in the deferred backlog) are deliberate scope choices: the Temporal integration tests verify the converted payload rather than Temporal's retry-engine behavior, and a couple of search/extract worker tests omit non-status `APIError` subtypes.
## Related tracks
diff --git a/wip/error-handling/track-webhook-payload-collision.md b/wip/error-handling/track-webhook-payload-collision.md
deleted file mode 100644
index 61c1c54fb..000000000
--- a/wip/error-handling/track-webhook-payload-collision.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# Webhook payload reserved-key collision
-
-> **Landed 2026-05-22** on `feature/API-readiness-2` (Phase 3 of `_for_api/TODOS.md`). Fixed via **Option 1**: a `field_validator` on `WebhookTarget.payload` (`pipelex/pipe_run/delivery_assignment.py`) that rejects the reserved-key set — `pipeline_run_id` / `status` / `result_url` / `error`, held in the new `_RESERVED_WEBHOOK_PAYLOAD_KEYS` frozenset — at construction time, with an error naming the offending key(s). A misconfigured webhook now fails the moment the `DeliveryAssignment` is built, not silently at delivery time. The rest of this doc is the original analysis, kept for context.
-
-Follow-up surfaced during the Stage 3 (Item D-2) /review pass. Not a blocker for the error-handling refactor — the behavior is consistent with how the webhook payload already handled `pipeline_run_id` / `status` / `result_url` — but the surface should be tightened before more callers depend on the schema.
-
-## What
-
-`pipelex/pipe_run/delivery_executor.py:240-260` (`DeliveryExecutor._notify_webhook`) copies `WebhookTarget.payload` (arbitrary caller dict) and then unconditionally assigns four Pipelex-owned keys on top:
-
-```python
-payload: dict[str, Any] = dict(webhook.payload)
-payload["pipeline_run_id"] = pipeline_run_id
-payload["status"] = status
-if result_url is not None:
- payload["result_url"] = result_url
-if error_report is not None:
- payload["error"] = error_report.to_dict(disclosure_mode=DisclosureMode.VERBOSE)
-```
-
-`WebhookTarget` (at `pipelex/pipe_run/delivery_assignment.py`) declares `payload: dict[str, Any] = Field(default_factory=dict)` — no schema, no key validation. A caller is free to put `{"error": "static fallback"}` in their static payload; on success that key passes through unchanged, on failure it gets silently replaced by the `ErrorReport` dict. The webhook schema therefore varies with delivery status in a way the caller did not opt into.
-
-The same is true for `result_url` (replaced on success only) and for `pipeline_run_id` / `status` (always replaced). `error` is just the most recent addition to the reserved set.
-
-## Why this is a follow-up, not a Stage 3 fix
-
-- Item D-2 plan explicitly specified `payload["error"] = error_report.to_dict(VERBOSE)` and the test pins it (`tests/unit/pipelex/pipe_run/test_delivery_executor.py::test_webhook_includes_error_report_on_failed_status`).
-- The asymmetry is consistent with `result_url`'s pre-existing behavior, so this is not a regression introduced by the error-handling refactor — it just makes the four-key reserved set more visible.
-- Fixing it in the same PR risks scope creep into webhook validation, which deserves its own review (see "Cross-track interactions" below).
-
-## Options
-
-### Option 1 — Pydantic validator on `WebhookTarget.payload` (preferred)
-
-Add a `field_validator` to `WebhookTarget.payload` that rejects the reserved set at construction time:
-
-```python
-# pipelex/pipe_run/delivery_assignment.py
-_RESERVED_WEBHOOK_PAYLOAD_KEYS: frozenset[str] = frozenset({
- "pipeline_run_id", "status", "result_url", "error",
-})
-
-class WebhookTarget(BaseModel):
- url: str
- headers: dict[str, str] = Field(default_factory=dict)
- payload: dict[str, Any] = Field(default_factory=dict)
-
- @field_validator("payload", mode="after")
- @classmethod
- def _reject_reserved_keys(cls, value: dict[str, Any]) -> dict[str, Any]:
- collisions = set(value) & _RESERVED_WEBHOOK_PAYLOAD_KEYS
- if collisions:
- msg = (
- f"WebhookTarget.payload contains reserved keys: {sorted(collisions)}. "
- "Pipelex owns these keys (assigned per delivery); choose different names."
- )
- raise ValueError(msg)
- return value
-```
-
-**Pros**
-
-- Fails at construction (`DeliveryAssignment` validation) rather than silently at delivery time.
-- Discovered the moment the caller writes the misconfiguration, not the first time a delivery happens to fail.
-- Zero schema change for well-behaved callers.
-
-**Cons**
-
-- Breaking change for any caller currently relying on a reserved key surviving — needs a CHANGELOG note.
-
-### Option 2 — Namespace Pipelex-owned fields
-
-Move the four reserved keys under a `pipelex` sub-dict:
-
-```python
-payload: dict[str, Any] = dict(webhook.payload)
-pipelex_meta: dict[str, Any] = {
- "pipeline_run_id": pipeline_run_id,
- "status": status,
-}
-if result_url is not None:
- pipelex_meta["result_url"] = result_url
-if error_report is not None:
- pipelex_meta["error"] = error_report.to_dict(disclosure_mode=DisclosureMode.VERBOSE)
-payload["pipelex"] = pipelex_meta
-```
-
-**Pros**
-
-- Cleanest separation between caller schema and Pipelex schema.
-- Only one reserved top-level key (`pipelex`), easy for the validator (Option 1) to enforce.
-
-**Cons**
-
-- Breaks every existing webhook receiver. Every consumer of `body["status"]` becomes `body["pipelex"]["status"]`. Coordinated change across pipelex-api, the webapp, n8n node, customer integrations.
-- Loses RFC 7807 affinity — when `error` is present, today it can be a near-drop-in for `application/problem+json` content with the right `Content-Type`. Burying it under `pipelex.error` makes that retargeting noisier.
-
-## Recommendation
-
-Land Option 1 in its own PR after this error-handling refactor merges. Skip Option 2 — the namespace shift cost is high and the RFC 7807 affinity is worth preserving.
-
-Sequencing:
-
-1. This PR (`feature/API-readiness`) merges with current behavior.
-2. New PR adds the `WebhookTarget.payload` validator + reserved-key constant + CHANGELOG entry. Same PR updates `pipelex-api`'s docs to call out the reserved set (the API repo is the primary consumer of this surface).
-3. Update `wip/error-handling/api-companion-revisions.md` D-2 section to point at this doc.
-
-## Cross-track interactions
-
-- **Webhook signing** (`wip/security/webhook-signing.md`) modifies the same `_notify_webhook` body. If signing lands first, the validator PR should rebase onto it. If validator lands first, the signing track inherits a well-defined payload shape — strictly easier to sign over.
-- **Deferred `causes` cause-chain serialization** (TODOS.md "Deferred follow-ups") adds richness to `error_report.to_dict(VERBOSE)` but doesn't touch the reserved-key set. Independent.
-
-## Trigger to pick this up
-
-Any of:
-
-- A new caller reports surprise that their static `error` key vanished on failed runs.
-- pipelex-api or the webapp wants to add a new payload field and needs a clear contract for what's already reserved.
-- The webhook-signing track lands and we want a clean payload shape under the signature.
diff --git a/wip/error-handling/track-worker-classification.md b/wip/error-handling/track-worker-classification.md
index 05281a33a..dbb28d4c3 100644
--- a/wip/error-handling/track-worker-classification.md
+++ b/wip/error-handling/track-worker-classification.md
@@ -93,7 +93,7 @@ The classification + beyond-reference upgrades have landed across every worker k
## What's left
-Worker classification itself is complete — there is no remaining per-worker work. The deeper **Extract / Classify / Render** refactor that consolidates the now-uniform per-worker pipeline into one per-provider Extract function plus a shared Classify + Render has also landed on `refactor/ECR` — see [track-extract-classify-render.md](track-extract-classify-render.md). The consistency gap noted earlier (LLM workers using `classify_*_sdk_error()` free functions while img-gen workers used inline `_raise_categorized_*` methods) is closed: every worker now goes through `extract → classify → render` and the per-provider `*_error_classification.py` files plus the inline `_raise_categorized_*` methods are deleted.
+Worker classification itself is complete — there is no remaining per-worker work. The deeper **Extract / Classify / Render** refactor that consolidates the now-uniform per-worker pipeline into one per-provider Extract function plus a shared Classify + Render has also landed — see [track-extract-classify-render.md](track-extract-classify-render.md). The consistency gap noted earlier (LLM workers using `classify_*_sdk_error()` free functions while img-gen workers used inline `_raise_categorized_*` methods) is largely closed: classification is unified behind the shared `classify_inference_error()` (`pipelex/cogt/inference/error_classify.py`) and the per-provider `*_error_classification.py` files are gone. One inline categorizer survives by design: the Azure REST img-gen worker keeps `_raise_categorized_azure_status_error` (`azure_img_gen_worker.py:65`, called from its generate path at `:159`). It is not a wholesale bypass — 4xx statuses route through the shared `classify_inference_error` + `render_inference_error` — but it forces 5xx statuses to `AMBIGUOUS` rather than the classifier's verdict, because image generation is a non-idempotent POST and the operation-agnostic classifier would mark a 5xx `TRANSIENT`, letting the Temporal bridge auto-retry and duplicate a billed generation.
### Risks and gotchas (for future similar work)
@@ -107,7 +107,3 @@ Worker classification itself is complete — there is no remaining per-worker wo
- [track-retry-and-resilience.md](track-retry-and-resilience.md) — once workers correctly classify TRANSIENT vs CAPACITY, the router-level retry can act on those signals.
- [track-cli-delivery.md](track-cli-delivery.md) — how Rich panels and agent JSON render the classified errors.
- [track-temporal-integration.md](track-temporal-integration.md) — uses `is_retryable` to drive Temporal's `non_retryable` flag.
-
-## Historical snapshot (2026-04-05)
-
-Before Phases 0–3, a tier review classified every worker as Tier 1 (gold standard), Tier 2 (partial coverage), or Tier 3 (minimal / no error handling). At the time, Google, Mistral (LLM + extract), Azure img-gen, FAL, HuggingFace, Docling, Linkup, and pypdfium2 had no SDK exception handling at all. The sweep closed those gaps and the tier ranking no longer reflects current reality — every worker is now at the Tier 1 standard. This historical detail is preserved here so the "what motivated this work" context isn't lost.
diff --git a/wip/offline-mode-pr-story.html b/wip/offline-mode-pr-story.html
deleted file mode 100644
index ff6cb2683..000000000
--- a/wip/offline-mode-pr-story.html
+++ /dev/null
@@ -1,327 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-<meta charset="UTF-8">
-<meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>PR Story — Offline Mode &amp; Remote Config Cache</title>
-<style>
- :root {
- --bg: #0f1117;
- --panel: #181b24;
- --panel-2: #1f2330;
- --ink: #e8eaf0;
- --muted: #9aa3b6;
- --line: #2c3142;
- --accent: #6ea8fe;
- --green: #5fd38f;
- --amber: #f0c060;
- --red: #f08a8a;
- --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
- }
- * { box-sizing: border-box; }
- body {
- margin: 0;
- background: var(--bg);
- color: var(--ink);
- font: 16px/1.65 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
- -webkit-font-smoothing: antialiased;
- }
- .wrap { max-width: 920px; margin: 0 auto; padding: 56px 28px 120px; }
- header.hero { border-bottom: 1px solid var(--line); padding-bottom: 32px; margin-bottom: 40px; }
- .eyebrow { font: 600 12px/1 var(--mono); letter-spacing: .14em; text-transform: uppercase; color: var(--accent); }
- h1 { font-size: 34px; line-height: 1.2; margin: 14px 0 10px; letter-spacing: -.01em; }
- .sub { color: var(--muted); font-size: 17px; max-width: 680px; }
- .meta { margin-top: 18px; display: flex; flex-wrap: wrap; gap: 8px; }
- .chip {
- font: 600 12px/1 var(--mono); padding: 6px 10px; border-radius: 999px;
- background: var(--panel-2); border: 1px solid var(--line); color: var(--muted);
- }
- h2 {
- font-size: 22px; margin: 52px 0 16px; letter-spacing: -.01em;
- padding-left: 12px; border-left: 3px solid var(--accent);
- }
- h3 { font-size: 16px; margin: 28px 0 10px; color: var(--ink); }
- p { margin: 12px 0; }
- .muted { color: var(--muted); }
- code {
- font: 13.5px/1.5 var(--mono); background: var(--panel-2);
- padding: 1.5px 6px; border-radius: 5px; border: 1px solid var(--line);
- }
- .panel {
- background: var(--panel); border: 1px solid var(--line);
- border-radius: 12px; padding: 20px 22px; margin: 18px 0;
- }
- .callout {
- border-left: 3px solid var(--amber); background: var(--panel);
- border-radius: 0 10px 10px 0; padding: 14px 18px; margin: 18px 0;
- }
- .callout.bug { border-left-color: var(--red); }
- .callout .lbl { font: 600 11px/1 var(--mono); letter-spacing: .1em; text-transform: uppercase; color: var(--amber); }
- .callout.bug .lbl { color: var(--red); }
-
- /* objective cards */
- .cards { display: grid; grid-template-columns: repeat(3, 1fr); gap: 14px; margin: 18px 0; }
- .card { background: var(--panel); border: 1px solid var(--line); border-radius: 12px; padding: 18px; }
- .card .n { font: 700 13px/1 var(--mono); color: var(--accent); }
- .card h4 { margin: 8px 0 6px; font-size: 15px; }
- .card p { margin: 0; font-size: 14px; color: var(--muted); }
-
- /* flow diagram */
- .flow { margin: 22px 0; }
- .flow-row { display: flex; align-items: stretch; gap: 10px; flex-wrap: wrap; }
- .node {
- background: var(--panel-2); border: 1px solid var(--line); border-radius: 10px;
- padding: 12px 14px; font-size: 13.5px; flex: 1; min-width: 150px;
- }
- .node .t { font: 600 11px/1 var(--mono); letter-spacing: .08em; text-transform: uppercase; color: var(--muted); display: block; margin-bottom: 5px; }
- .node.ok { border-color: #2f5d44; }
- .node.ok .t { color: var(--green); }
- .node.warn { border-color: #5d4f2c; }
- .node.warn .t { color: var(--amber); }
- .node.err { border-color: #5d3434; }
- .node.err .t { color: var(--red); }
- .arrow { align-self: center; color: var(--muted); font: 18px/1 var(--mono); padding: 0 2px; }
- .vsep { text-align: center; color: var(--muted); font: 13px/1 var(--mono); margin: 8px 0; }
-
- /* table */
- table { width: 100%; border-collapse: collapse; margin: 16px 0; font-size: 13.5px; }
- th, td { text-align: left; padding: 9px 11px; border-bottom: 1px solid var(--line); vertical-align: top; }
- th { font: 600 11px/1.3 var(--mono); letter-spacing: .06em; text-transform: uppercase; color: var(--muted); }
- td .dot { font-weight: 700; }
- .dot.g { color: var(--green); }
- .dot.a { color: var(--amber); }
- .dot.r { color: var(--red); }
- tbody tr:hover { background: var(--panel); }
-
- /* diff */
- .diff {
- background: #11141c; border: 1px solid var(--line); border-radius: 10px;
- overflow-x: auto; margin: 14px 0; font: 12.5px/1.7 var(--mono);
- }
- .diff .fname {
- padding: 8px 14px; border-bottom: 1px solid var(--line);
- color: var(--muted); background: var(--panel-2); font-weight: 600;
- }
- .diff pre { margin: 0; padding: 12px 14px; }
- .diff .add { color: var(--green); display: block; }
- .diff .del { color: var(--red); display: block; }
- .diff .ctx { color: #8b93a7; display: block; }
- .diff .hdr { color: var(--accent); display: block; }
-
- ul.tight { margin: 10px 0; padding-left: 22px; }
- ul.tight li { margin: 5px 0; }
- .files { columns: 2; column-gap: 26px; font: 12.5px/1.9 var(--mono); color: var(--muted); }
- .files .new { color: var(--green); }
- footer { margin-top: 70px; padding-top: 24px; border-top: 1px solid var(--line); color: var(--muted); font-size: 13px; }
- @media (max-width: 680px) {
- .cards { grid-template-columns: 1fr; }
- .files { columns: 1; }
- }
-</style>
-</head>
-<body>
-<div class="wrap">
-
-<header class="hero">
- <div class="eyebrow">Pull Request Story</div>
- <h1>Offline Mode &amp; Remote Config Cache</h1>
- <p class="sub">Making Pipelex <strong>setup</strong> and <strong>dry-run</strong> work without a network — by adding a primed, last-resort cache for the Gateway remote config, with honest provenance tracking and no silent fallbacks.</p>
- <div class="meta">
- <span class="chip">branch · fix/Offline-mode</span>
- <span class="chip">7 phases · TDD throughout</span>
- <span class="chip">~3,300 LOC added</span>
- <span class="chip">6 new test suites</span>
- </div>
-</header>
-
-<h2>Why we did this</h2>
-<p>Pipelex's Gateway needs a <strong>remote config</strong> — the catalogue of which models exist and on which backends. On every <code>setup()</code> that touches model specs, Pipelex fetched that config over HTTP. If the network was down, setup <em>crashed</em> — even for commands that never make an inference call.</p>
-
-<p>That hurt in two real places: agent CLI commands like <code>validate</code>, <code>inputs</code>, and <code>run --dry-run</code> all pass <code>needs_model_specs=True</code>, and sandboxed environments (Codex local sandbox) have no outbound network at all. None of these <em>run</em> a model — they just need to know the catalogue. Yet a missing network broke them.</p>
-
-<div class="callout bug">
- <span class="lbl">Diagnosed failure point</span>
- <p style="margin:8px 0 0"><code>pipelex.py:235</code> unconditionally called <code>RemoteConfigFetcher.fetch_remote_config()</code> whenever the Gateway was enabled and model specs were needed. Any network failure raised <code>RemoteConfigFetchError</code> straight out of setup. The only escape hatch was a Codex-<em>Cloud</em>-specific short-circuit — local sandboxes and plain offline use were not covered.</p>
-</div>
-
-<h2>The three objectives</h2>
-<div class="cards">
- <div class="card">
- <span class="n">01</span>
- <h4>BYOK works fully offline</h4>
- <p>Gateway disabled → no remote fetch is ever attempted. Setup completes with zero network.</p>
- </div>
- <div class="card">
- <span class="n">02</span>
- <h4>Dry-run survives an outage</h4>
- <p>Gateway enabled but remote temporarily unreachable → fall back to a cache primed at init time.</p>
- </div>
- <div class="card">
- <span class="n">03</span>
- <h4>No silent fallbacks</h4>
- <p>Unknown Gateway models fail loudly against fresh <em>or</em> cached specs. Stale data is always labelled.</p>
- </div>
-</div>
-<p class="muted">Non-objective: we did <em>not</em> make inference itself work offline. A real model call still needs the network. This PR is strictly about <strong>setup</strong> and <strong>dry-run</strong>.</p>
-
-<h2>The design in one picture</h2>
-<p>The whole thing hinges on one idea: <strong>the fetcher returns a result that knows where it came from.</strong> Everything downstream branches on that provenance.</p>
-
-<div class="flow panel">
- <div class="flow-row">
- <div class="node"><span class="t">setup()</span>Gateway enabled &amp; needs specs</div>
- <span class="arrow">→</span>
- <div class="node"><span class="t">fetch_remote_config()</span>HTTP GET, with retry (tenacity, 5 attempts)</div>
- </div>
- <div class="vsep">│</div>
- <div class="flow-row">
- <div class="node ok"><span class="t">success</span>parse + validate → write raw JSON to cache → <code>source = FRESH</code></div>
- <div class="node warn"><span class="t">network fails, cache hit</span>load <code>~/.pipelex/cache/remote_config.json</code> → <code>source = CACHED</code></div>
- <div class="node err"><span class="t">network fails, no cache</span>raise <code>RemoteConfigUnavailableError</code></div>
- </div>
- <div class="vsep">│ &nbsp; the <code>source</code> flows downstream &nbsp; │</div>
- <div class="flow-row">
- <div class="node">membership check: every referenced Gateway model must exist in the specs → else <code>GatewayUnknownModelError</code> (message branches on <code>source</code>)</div>
- </div>
- <div class="flow-row" style="margin-top:10px">
- <div class="node warn"><span class="t">if CACHED</span>emit <code>RemoteConfigStaleWarning</code> · disable telemetry · surface a <code>warnings</code> field on the agent-CLI JSON envelope</div>
- </div>
-</div>
-
-<h3>Why a schema-break does NOT fall back to cache</h3>
-<p>If the remote responds with JSON that fails validation, we raise <code>RemoteConfigValidationError</code> and stop — no cache fallback. We control both ends of that URL (it's versioned in <code>pipelex-back-office</code>), so a schema-rejecting payload is a real server bug, not an operational state. Failing loudly is correct. The cache is for <em>network</em> failures only.</p>
-
-<h2>The pieces we added</h2>
-<div class="panel">
- <h3 style="margin-top:0">New module — <code>remote_config_cache.py</code></h3>
- <p class="muted" style="margin-top:6px"><code>RemoteConfigCache.store()</code> / <code>.load()</code>. Stores the <strong>raw JSON dict</strong> from the response — not a re-serialised Pydantic dump — so the cache survives minor schema drift. Atomic writes (temp file + <code>os.replace</code>). Schema-versioned: a <code>CACHE_SCHEMA_VERSION</code> bump rejects old caches cleanly.</p>
- <h3>New leaf enum — <code>RemoteConfigSource</code></h3>
- <p class="muted" style="margin-top:6px"><code>FRESH</code> | <code>CACHED</code>. Lives in its own tiny <code>types.py</code> so <code>cogt/</code> code can import it without dragging in <code>httpx</code> + <code>tenacity</code>. Exposes <code>.is_cached</code> so callers never write <code>== CACHED</code>.</p>
- <h3>New exceptions &amp; warning</h3>
- <ul class="tight muted">
- <li><code>RemoteConfigUnavailableError</code> — fetch failed <em>and</em> no usable cache. Message names the cache path + remediation.</li>
- <li><code>GatewayUnknownModelError</code> — a bundle references a Gateway model absent from the specs. Message branches on <code>source</code> (a <code>CACHED</code> source hints "run <code>pipelex init</code> while online").</li>
- <li><code>RemoteConfigStaleWarning</code> — emitted when setup completes off a cached config.</li>
- <li><code>RemoteConfigFetchError</code> — <strong>kept</strong> as the internal retry-layer exception. Removing it would have broken doctor, the CLI factory, and agent hints.</li>
- </ul>
-</div>
-
-<h2>The critical code change</h2>
-<p>The behavioural heart of the PR. The fetcher stopped returning a bare <code>RemoteConfig</code> and started returning a <code>RemoteConfigResult</code> that carries provenance:</p>
-
-<div class="diff">
- <div class="fname">pipelex/system/pipelex_service/remote_config_fetcher.py</div>
-<pre><span class="del">- def fetch_remote_config(cls) -> RemoteConfig:</span>
-<span class="add">+ def fetch_remote_config(cls, require_fresh: bool = False) -> RemoteConfigResult:</span>
-<span class="ctx"> url = PipelexDetails.remote_config_url()</span>
-<span class="ctx"> try:</span>
-<span class="ctx"> payload, config = cls._fetch_fresh(url)</span>
-<span class="add">+ RemoteConfigCache.store(payload) # opportunistic refresh</span>
-<span class="add">+ return RemoteConfigResult(config=config, source=RemoteConfigSource.FRESH)</span>
-<span class="ctx"> except RemoteConfigFetchError as fetch_error: # network / HTTP only</span>
-<span class="add">+ if require_fresh: # doc generators refuse stale data</span>
-<span class="add">+ raise cls._build_unavailable_error(fetch_error, cache_refused=True) from fetch_error</span>
-<span class="add">+ cached = RemoteConfigCache.load()</span>
-<span class="add">+ if cached is None:</span>
-<span class="add">+ raise cls._build_unavailable_error(fetch_error) from fetch_error</span>
-<span class="add">+ return RemoteConfigResult(</span>
-<span class="add">+ config=cached.to_remote_config(),</span>
-<span class="add">+ source=RemoteConfigSource.CACHED,</span>
-<span class="add">+ cached_at=cached.cached_at,</span>
-<span class="add">+ )</span>
-</pre>
-</div>
-
-<p>And <code>setup()</code> consumes the provenance — warning, and tightening telemetry, when the data is stale:</p>
-
-<div class="diff">
- <div class="fname">pipelex/pipelex.py</div>
-<pre><span class="del">- remote_config = RemoteConfigFetcher.fetch_remote_config()</span>
-<span class="add">+ remote_config_result = RemoteConfigFetcher.fetch_remote_config()</span>
-<span class="add">+ remote_config = remote_config_result.config</span>
-<span class="add">+ gateway_config_source = remote_config_result.source</span>
-<span class="ctx"> ...</span>
-<span class="add">+ if gateway_config_source.is_cached:</span>
-<span class="add">+ warnings.warn(f"Pipelex Gateway is running off a cached remote config "</span>
-<span class="add">+ f"(snapshot: {cached_at_iso}). Run `pipelex init` while online.",</span>
-<span class="add">+ RemoteConfigStaleWarning, stacklevel=2)</span>
-<span class="hdr"> # stale specs imply stale model identities — don't phone home in that state</span>
-<span class="del">- is_pipelex_telemetry_enabled = is_pipelex_service_enabled and needs_inference</span>
-<span class="add">+ is_pipelex_telemetry_enabled = (is_pipelex_service_enabled and needs_inference</span>
-<span class="add">+ and not gateway_source_is_cached)</span>
-</pre>
-</div>
-
-<p class="muted">One deliberate design call: the <strong>warning is emitted in <code>setup()</code>, not in the fetcher</strong>. That keeps the fetcher a pure data-returning function, so test fixtures that swap in a cached fetcher don't have to replay warnings.</p>
-
-<h2>The behaviour matrix we validated</h2>
-<table>
- <thead><tr><th>Scenario</th><th>Gateway</th><th>Network</th><th>Cache</th><th>Outcome</th></tr></thead>
- <tbody>
- <tr><td>BYOK offline</td><td>off</td><td>down</td><td>—</td><td><span class="dot g">●</span> setup + validate + dry-run all OK — fetch never attempted</td></tr>
- <tr><td>Gateway dry-run, fresh</td><td>on</td><td>up</td><td>—</td><td><span class="dot g">●</span> fresh fetch, cache written</td></tr>
- <tr><td>Gateway dry-run, cached</td><td>on</td><td>down</td><td>present</td><td><span class="dot a">●</span> cache fallback + stale warning, dry-run OK</td></tr>
- <tr><td>Gateway dry-run, cold</td><td>on</td><td>down</td><td>absent</td><td><span class="dot r">●</span> <code>RemoteConfigUnavailableError</code> with remediation</td></tr>
- <tr><td>Unknown model referenced</td><td>on</td><td>any</td><td>any</td><td><span class="dot r">●</span> <code>GatewayUnknownModelError</code>, message branches on source</td></tr>
- <tr><td>Doc generator offline</td><td>on</td><td>down</td><td>present</td><td><span class="dot r">●</span> <code>require_fresh=True</code> refuses cache — no stale docs committed</td></tr>
- </tbody>
-</table>
-
-<div class="callout">
- <span class="lbl">The subtle one — doc generators</span>
- <p style="margin:8px 0 0"><code>gateway_models_generator.py</code> and <code>preprocess_test_models_cmd.py</code> regenerate <strong>committed</strong> reference docs and test fixtures. If they silently used the cache, they'd bake stale data into the repo. They pass <code>require_fresh=True</code> — any fallback becomes an immediate error instead.</p>
-</div>
-
-<h2>How init primes the cache</h2>
-<p>The cache is only useful if it exists before the network goes down. So when <code>pipelex init</code> accepts the Gateway terms, it does one fetch and persists the result. If <em>that</em> is offline, init logs a yellow warning and continues — the cache stays empty, but the user has been told. The agent-CLI init mirrors this and surfaces <code>cache_primed</code> / <code>cache_priming_error</code> on its JSON envelope.</p>
-
-<h2>What landed</h2>
-<div class="panel">
-<div class="files">
-<span class="new">+ remote_config_cache.py</span>
-<span class="new">+ pipelex_service/types.py</span>
-remote_config_fetcher.py
-pipelex_service/exceptions.py
-cogt/exceptions.py
-cogt/models/model_manager.py
-model_manager_abstract.py
-pipelex.py
-cli/commands/init/command.py
-agent_cli/commands/init_cmd.py
-agent_cli/commands/agent_output.py
-agent_cli/commands/agent_cli_factory.py
-cli/error_handlers.py
-cli/cli_factory.py
-cli/commands/doctor_cmd.py
-dev_cli/.../gateway_models_generator.py
-dev_cli/.../preprocess_test_models_cmd.py
-pipelex_details.py
-<span class="new">+ test_remote_config_cache.py</span>
-<span class="new">+ test_remote_config_fetcher.py</span>
-<span class="new">+ test_gateway_unknown_model.py</span>
-<span class="new">+ test_setup_with_cache.py</span>
-<span class="new">+ test_cache_priming.py</span>
-<span class="new">+ test_offline_run_dry.py (E2E)</span>
-<span class="new">+ test_offline_baseline.py</span>
-</div>
-</div>
-<p class="muted">Built TDD across 7 phases — baseline lock-down → cache module → fetcher fallback → provenance plumbing → init priming → real-<code>.mthds</code>-bundle E2E → verification. Each phase is its own commit with a checkpoint block. <code>make agent-check</code> and <code>make agent-test</code> green throughout.</p>
-
-<h2>Deferred — not in this PR</h2>
-<ul class="tight muted">
- <li><strong>doctor cache reporting</strong> — surface cache presence/age in <code>pipelex doctor</code>. Pure additive.</li>
- <li><strong>Codex Cloud cache-first</strong> — today Codex Cloud returns a dummy config; it could try the cache first now that we trust it.</li>
- <li><strong>Cross-repo</strong> — update <code>mthds-plugins/wip/codex-sandbox-escalation.md</code>: <code>--dry-run</code> no longer needs escalation once Pipelex has been initialised online once.</li>
- <li><strong>E2E pinning <code>GatewayUnknownModelError</code></strong> — the E2E currently asserts the unknown handle is visible without pinning <code>error_type</code> (it fires at the pipe-operator layer). A deck-override test would pin the deck-level membership check end-to-end.</li>
- <li><strong>Cache TTL</strong> — currently uncapped. Revisit once we have telemetry on fallback usage.</li>
-</ul>
-
-<footer>
- Full plan with phase-by-phase checkpoints archived at
- <code>wip/archive/offline-mode-remote-config-cache.md</code>.
- Questions → ping me on the PR.
-</footer>
-
-</div>
-</body>
-</html>
diff --git a/wip/phase6b-remote-deps-from-github.md b/wip/phase6b-remote-deps-from-github.md
deleted file mode 100644
index 9f506d5da..000000000
--- a/wip/phase6b-remote-deps-from-github.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Phase 6b — Remote Dependencies from GitHub
-
-> **Status**: Not started
-> **Goal**: Dependencies can be fetched from remote addresses (e.g., `github.com/org/repo/package`). The crate becomes fully self-contained for cloud-native execution where workers are stateless.
-> **Predecessor**: [phase6a-local-cross-package-deps.md](phase6a-local-cross-package-deps.md) — needs the blueprint collector extracted in 6a.
-> **Related**: [02-master-plan.md](02-master-plan.md), [future-crate-first-architecture.md](future-crate-first-architecture.md).
-
----
-
-## Key changes
-
-1. **Remote resolution strategy**: Add a `REMOTE` resolution strategy to the blueprint collector extracted in 6a. Remote fetch clones/downloads the package from GitHub, parses its `.mthds` files into blueprints, and includes them in the collection.
-
-2. **Dependency address format**: Define the address format for remote deps (e.g., `github.com/org/repo@version/path/to/package`). The address goes in the package manifest.
-
-3. **Caching**: Cache fetched packages locally (content-addressed by address + version) to avoid redundant clones.
-
-4. **Transitive deps**: Remote packages may themselves have dependencies (local or remote). The collector recurses.
-
-## Done when
-
-- [ ] Remote fetch strategy implemented (git clone or archive download)
-- [ ] Dependency address format defined and parsed
-- [ ] Remote package blueprints included in crate
-- [ ] Local cache for fetched packages
-- [ ] Transitive remote deps resolved
-- [ ] Integration test: pipeline with remote dep from a GitHub repo, executed on Temporal worker
-- [ ] `make agent-check` passes
-- [ ] `make agent-test` passes
diff --git a/wip/runtime-code-fixes.md b/wip/runtime-code-fixes.md
new file mode 100644
index 000000000..b6a155c9a
--- /dev/null
+++ b/wip/runtime-code-fixes.md
@@ -0,0 +1,19 @@
+# Runtime code fixes
+
+Concrete fixes verified against the code, not yet done. Each is independent.
+
+## `request_id` on delivery failure messages
+
+Append the already-in-scope `request_id_suffix` to the `StorageDeliveryError` failure message and to both `WebhookDeliveryError` branches in `pipelex/pipe_run/delivery_executor.py`, mirroring the success paths; add unit assertions that the messages carry `request_id=`. Full analysis — exact sites, the case for/against, and a sketch commit — is in [`error-handling/track-delivery-error-path-request-id.md`](error-handling/track-delivery-error-path-request-id.md).
+
+## Cross-worker cost report assembly wiring
+
+The single genuine functional gap from the tracing work: wire `UsageAggregator.aggregate(events)` → `ReportingManager.inject_tokens_usages(...)` → `generate_report` into the post-run readback, parallel to the existing graph readback, for both direct mode (`pipe_run/pipe_run.py` / `graph_assembly.py`) and Temporal (`act_assemble_graph` / post-workflow), with a cross-worker test. Tracked as P1 in [the distributed-execution plan](distributed-execution/README.md); the as-built context and the open T2/T3 gaps are in [`distributed-execution/tracing-cost-reporting.md`](distributed-execution/tracing-cost-reporting.md).
+
+## Deferred / out of scope
+
+Surfaced alongside the two fixes but out of scope for them:
+
+- GraphSpec causal ordering for parent/child topologies (observability-only).
+- kajson class-registry race under pytest-xdist (test-hygiene; needs runtime repro).
+- `get_config()` replay-determinism — the cheap parts (a `docs/distributed-execution` note on the config-edit-while-in-flight constraint, plus a Replayer regression test) are file-able; the full fix is Worker Versioning.
diff --git a/wip/structured-logging/kickoff.md b/wip/structured-logging.md
similarity index 81%
rename from wip/structured-logging/kickoff.md
rename to wip/structured-logging.md
index 1ecac33e8..3e915f264 100644
--- a/wip/structured-logging/kickoff.md
+++ b/wip/structured-logging.md
@@ -1,6 +1,6 @@
# Structured logging refactor — kickoff briefing
-**Status:** kicked off, not started. Sequenced AFTER `feature/API-readiness-2` and the surrounding error-handling stack merge. Will get its own branch and its own PR.
+**Status:** kicked off, not started. Sequenced AFTER the error-handling stack merges. Will get its own branch and its own PR.
**Purpose of this doc:** cold-start briefing for the session that picks this up. Captures *why* the refactor exists, *what good looks like*, *what the current code constrains us to*, and the first open questions to resolve. **Not a plan** — the plan is the first artifact of that session.
@@ -10,12 +10,12 @@ Pipelex's `log` API is string-shaped today (`log.info("a message string with stu
## What triggered this
-`wip/error-handling/archive-delivery-error-path-request-id.md` opened the question of whether to thread `request_id` into the failure-path messages of `DeliveryExecutor` (mirroring the success-path threading from commits `ceb018b5` and `07f9cce9`). The proximate decision was "do it the manual way OR do the structural fix." We chose to defer the structural fix to a dedicated branch — this one.
+`wip/error-handling/track-delivery-error-path-request-id.md` opened the question of whether to thread `request_id` into the failure-path messages of `DeliveryExecutor` (mirroring the success-path threading already in place). The proximate decision was "do it the manual way OR do the structural fix." We chose to defer the structural fix to a dedicated branch — this one.
-Two preceding commits did manual per-line threading on the success path:
+Earlier work did manual per-line threading on the success path:
-- `ceb018b5` — thread `request_id` through `DeliveryExecutor.execute` and into success log lines.
-- `07f9cce9` — forward `request_id` from `PipeRun.run` direct-mode dispatcher to `DeliveryExecutor`.
+- `DeliveryExecutor.execute` threads `request_id` into the success log lines.
+- `PipeRun.run` forwards `request_id` from the direct-mode dispatcher to `DeliveryExecutor`.
Both commits also introduced the ad-hoc `request_id_suffix = f", request_id={request_id}" if request_id is not None else ""` pattern. That pattern is exactly what this refactor exists to delete.
@@ -63,7 +63,7 @@ Key properties of the destination state:
- The two boundaries that bind today's `request_id` continue to bind it — but at the *context* level, not by threading kwargs through 4-deep call stacks. The API request handler binds; `PipeRun.run` binds for non-API direct-mode invocations (whatever metadata it has); the Temporal activity entry re-binds from `DeliveryActivityArg.*` (the wire-format fields stay; only the propagation mechanism inside the activity changes).
- The manual `request_id` kwargs on `DeliveryExecutor.execute` / `_store_results` / `_notify_webhook` are **deleted**. So is the `request_id_suffix` interpolation. The success log lines auto-pick up `request_id` from the filter; the failure log lines do too; the exception messages can stop carrying it (and stop pretending to).
- Non-API invocations (CLI, direct library use, tests) simply don't bind `request_id`; the filter sees None; the field is absent from the record. No conditional suffix code anywhere.
-- **Event-name emission on delivery paths.** The success and failure log lines in `delivery_executor.py` carry an `event` field — `event=webhook_delivery` / `event=webhook_failure` on the webhook path, `event=storage_delivery` / `event=storage_failure` on the storage path. **Why this is folded into this refactor rather than done standalone:** the lines it touches (`delivery_executor.py` around 239 / 243 / 280 / 282 / 285) are exactly the `request_id_suffix` interpolation / kwarg-threading sites listed as deletion targets in "Reality of the current code" below (introduced by commits `ceb018b5` / `07f9cce9`). A narrow event-name pass on its own branch would touch those lines, and this refactor would touch them again — so it was deferred out of `feature/API-readiness-4` (its `TODOS.md` item #7, closed-by-deferral 2026-05-28) into this branch's scope. **Follow-ups when this branch starts:** (a) emit the four `event=...` fields above once the structured-field surface lands; (b) re-target the API-side pointer in `../pipelex-api/TODOS.md` "Deferred / next-track work" → "Upstream-pipelex follow-ups" from `feature/API-readiness-4` onto this branch. Note: the API-side T6 test (`pipelex-api/tests/unit/test_webhook_recovery.py`) pins error-rendering consistency, not event names — the API is **not** blocked on event-name emission, so this is genuinely follow-up work, not a release gate.
+- **Event-name emission on delivery paths.** Add an `event` field to the delivery log lines — `event=webhook_delivery` / `event=webhook_failure` on the webhook path, `event=storage_delivery` / `event=storage_failure` on the storage path. This is folded into this refactor rather than done standalone because the lines it touches (`delivery_executor.py` around 239 / 243 / 280 / 282 / 285) are exactly the `request_id_suffix` interpolation / kwarg-threading sites listed as deletion targets in "Reality of the current code" below — a separate event-name pass would touch them, then this refactor would touch them again. Emit the four `event=...` fields once the structured-field surface lands.
## Reality of the current code (what we found during the trigger discussion)
@@ -81,7 +81,7 @@ No `extra=` kwarg, no `**fields`, no structured pathway. Dispatch flows through
Specific sites currently doing manual interpolation / threading of `request_id` and `pipeline_run_id` (these become the regression-test fixtures for the refactor, and the places we delete code):
- `pipelex/pipe_run/delivery_executor.py`
- - `execute(... request_id: str | None = None)` — kwarg added by `ceb018b5`. To delete.
+ - `execute(... request_id: str | None = None)` — the threaded kwarg. To delete.
- `_store_results(... request_id: str | None = None)` — same. To delete.
- `_notify_webhook(... request_id: str | None = None)` — same. To delete.
- Success log lines (lines around 239 and 280) interpolate `request_id_suffix`. To revert to plain narrative.
@@ -117,16 +117,16 @@ The session should answer these before writing the plan:
## Sequencing
-- **Do not start until `feature/API-readiness-2` merges.** That branch is the trigger context; this refactor touches the same files.
+- **Do not start until the API-readiness work merges.** That is the trigger context; this refactor touches the same files.
- **Do not start until the error-handling stack settles.** Several `wip/error-handling/track-*.md` items are still open; they shouldn't be racing this refactor through the same files.
- **Branch:** `refactor/structured-logging` (or similar — confirm at branch-creation time).
- **Scope discipline:** the refactor is the API extension + the contextvar machinery + the migration of the request-scoped fields we know about (`request_id`, `pipeline_run_id`, `user_id`). It is NOT "rewrite every log line in the codebase." Other call sites migrate opportunistically as they're touched.
## References
-- `wip/error-handling/archive-delivery-error-path-request-id.md` — the trigger doc; closing rationale references this refactor as the deferred altitude fix.
-- Commit `ceb018b5` — `feat(delivery): thread request_id through DeliveryExecutor for cross-phase log correlation`. To be partially reverted.
-- Commit `07f9cce9` — `fix(delivery): forward request_id from PipeRun direct-mode dispatcher to DeliveryExecutor`. To be partially reverted.
+- `wip/error-handling/track-delivery-error-path-request-id.md` — the trigger doc; closing rationale references this refactor as the deferred altitude fix.
+- The success-path threading in `DeliveryExecutor` — to be partially reverted.
+- The direct-mode forwarding from `PipeRun.run` to `DeliveryExecutor` — to be partially reverted.
- `pipelex/tools/log/log.py` — current string-shaped Log API. The surface to extend.
- `pipelex/tools/log/log_dispatch.py` — dispatch layer. First file to investigate (open question 1).
- `pipelex/tools/log/log_formatter.py` — formatter layer. Second file to investigate (open questions 1 and 2).
diff --git a/wip/stuffs-as-nodespec.md b/wip/stuffs-as-nodespec.md
index da537432d..b3c2ebc8f 100644
--- a/wip/stuffs-as-nodespec.md
+++ b/wip/stuffs-as-nodespec.md
@@ -2,7 +2,7 @@
## Why this exists
-When we promoted `description` and `domain_code` onto `NodeSpec` for pipes (see commits on `feature/Update-html-mthds-ui`), we deliberately stopped at pipes. Concepts have the same metadata (`domain_code`, `description`) and the same problem: today, the only way for a renderer to discover the domain or human description of a stuff's concept is to join with `GraphSpec.concept_registry` — and that registry is empty when `data_inclusion.pipe_and_concept_registry = False`.
+When we promoted `description` and `domain_code` onto `NodeSpec` for pipes, we deliberately stopped at pipes. Concepts have the same metadata (`domain_code`, `description`) and the same problem: today, the only way for a renderer to discover the domain or human description of a stuff's concept is to join with `GraphSpec.concept_registry` — and that registry is empty when `data_inclusion.pipe_and_concept_registry = False`.
So the symmetric fix is to make stuffs self-describing in the graph, just like pipe nodes now are.
@@ -47,7 +47,7 @@ Not exhaustive — just the obvious ones to scope from before committing:
- `pipelex/tracing/trace_events.py` — `PipeStartEvent.input_specs` rethink (events probably emit stuff-node ids instead of inline `IOSpec`).
- Every renderer that today synthesizes stuff nodes at render time (mermaidflow, reactflow JS bundle, HTML).
- All `GraphSpec` JSON fixtures under `tests/data/graphs/` — breaking change, will need regeneration.
-- The existing pipe-side `description` / `domain_code` work landed in this branch — confirm semantics stay consistent when extended to stuff kinds.
+- The existing pipe-side `description` / `domain_code` work has already landed — confirm semantics stay consistent when extended to stuff kinds.
## Open questions to settle before starting
diff --git a/wip/template-preprocessor-css-collision.md b/wip/template-preprocessor-css-collision.md
deleted file mode 100644
index 65a467c84..000000000
--- a/wip/template-preprocessor-css-collision.md
+++ /dev/null
@@ -1,147 +0,0 @@
-# Template preprocessor — sigil collision with CSS, emails, and code
-
-## Context
-
-The template preprocessor at `pipelex/cogt/templating/template_preprocessor.py` rewrites three sigils into Jinja2 before rendering:
-
-- `@var` → `{{ var|tag("var") }}` (regex `r"@(?![0-9])([a-zA-Z0-9_.]+)"`)
-- `@?var` → optional insertion (`{% if var %}…{% endif %}`)
-- `$var` → `{{ var|format() }}`
-
-There is no escape mechanism today — only a `# TODO: allow escape patterns` comment. This produces silent breakage in any template whose source text legitimately contains an `@` or `$` followed by a word.
-
-## Observed failure
-
-PipeCompose templates that embed HTML/CSS in a `<style>` block break on CSS at-rules. Example from the wild:
-
-```html
-<style>
- /* … */
- @media (max-width: 820px) {
- .fashion-project-page { padding: 24px; }
- /* … */
- }
-</style>
-```
-
-The preprocessor rewrites `@media` as a template variable. The downstream Jinja2 render then fails or produces garbage. Authoring agents currently work around this by deleting responsive blocks — losing functionality the template was meant to express.
-
-## The problem is wider than CSS
-
-The exact same regex misfires on:
-
-- **CSS at-rules**: `@media`, `@import`, `@keyframes`, `@font-face`, `@supports`, `@charset`, `@namespace`, `@page`, `@property`, `@layer`, `@container`, `@scope`, … plus everything CSS adds in the future.
-- **Email addresses** in body text: `[email protected]` → captures `example.com` as a variable (already documented in `test_email_address_partially_processed`).
-- **Code-block content in LLM prompts**: Python decorators (`@property`, `@staticmethod`, `@classmethod`), cron specs (`@daily`), social handles (`@username`).
-- **`$` has the symmetric problem**: bash vars in code blocks (`$PATH`), jQuery (`$(...)`), LaTeX math (`$…$`).
-
-Any solution scoped narrowly to CSS will be reopened the first time an agent generates an HTML template with an email address or a Python snippet.
-
-## Strategies considered
-
-### 1. Reserved CSS keyword list
-
-Maintain a static set of CSS at-rule names that the preprocessor leaves alone.
-
-- **Pros**: zero LLM cognitive overhead for the common case.
-- **Cons**: CSS-specific hack baked into a domain-agnostic templating layer; the list rots as CSS evolves; doesn't help emails / decorators / cron / handles; quietly reserves common words like `media`, `import`, `page`, `layer`, `property` as unusable variable names via `@var` syntax.
-
-### 2. Explicit escape (`@@` → literal `@`, `$$` → literal `$`)
-
-Add a Razor-style escape so authors can opt out of preprocessing on any `@` or `$`.
-
-- **Pros**: principled, generic, predictable; covers every present and future collision (CSS, emails, handles, decorators).
-- **Cons**: paste-existing-CSS-as-is doesn't "just work" — every at-rule needs `@@`. LLMs generating templates need to know the rule (prompt/doc burden).
-
-### 3. Smarter regex heuristics
-
-Refine the regex so it doesn't match the problematic shapes in the first place:
-
-- **`(?<!\w)` lookbehind before each sigil** — skips when the `@` or `$` is preceded by a word character. Kills emails: in `[email protected]`, the `@` is preceded by `r`, so it's skipped.
-- **`(?!\s*[({"'])` lookahead after the captured identifier** — skips when the identifier is followed by `(`, `"`, `'`, or `{` (with optional whitespace). Kills CSS at-rules: `@media (…)`, `@supports (…)`, `@import "…"`, `@charset "…"`, `@keyframes name {…}`, `@font-face {…}`, `@page {…}`, `@layer name {…}`, etc.
-
-Template variables in Pipelex are essentially never followed by `(` / `"` / `'` / `{`. The user confirmed that the only conceivable counter-example `@var (note)` does not occur in practice: `@var` is used for tagged block insertion, so wrapping the inserted block in a parenthetical immediately after would not make semantic sense.
-
-- **Pros**: zero burden on authors, no reserved names, no list to maintain, fixes CSS *and* emails in one stroke.
-- **Cons**: heuristic — there may be residual edge cases we haven't anticipated, which is why we want an escape too.
-
-### 4. Context-aware skipping (don't preprocess inside `<style>` / fenced code blocks)
-
-Parse the template enough to identify "code-like" regions and skip preprocessing inside them.
-
-- **Pros**: bulletproof inside the protected context.
-- **Cons**: real parsing complexity; doesn't help emails in body text; easy to get wrong (nested blocks, malformed HTML). Overkill.
-
-### 5. Stricter syntax (`@{var}`)
-
-Require a delimiter around the variable name.
-
-- **Pros**: cleanest theoretically.
-- **Cons**: breaking change across the entire MTHDS surface, churns every existing `.mthds` file, gives up the ergonomic appeal of bare `@var`. Not justified by the problem.
-
-## Decision
-
-Adopt **Strategy 3 (heuristic regex tightening) + Strategy 2 (explicit escape)**. Skip the rest.
-
-### Heuristic regex tightening (primary fix)
-
-Apply to all three sigils (`@`, `@?`, `$`):
-
-1. Add a `(?<!\w)` lookbehind in front of the sigil.
-2. Add a `(?!\s*[({"'])` lookahead immediately after the captured identifier.
-
-This silently fixes CSS at-rules, email addresses, and most code-block cases — with no author intervention, no reserved names, and no maintenance burden.
-
-### Explicit escape (safety net)
-
-1. Treat `@@` as a literal `@` (consumed during preprocessing).
-2. Treat `$$` as a literal `$` (consumed during preprocessing).
-3. The escape must be applied **after** sigil substitution so that `@@var` produces a literal `@var` and not a Jinja2 expression, but **before** Jinja2 receives the template.
-
-Heuristics fail silently; the escape gives authors a clean, explicit opt-out for any residual case the heuristic can't predict.
-
-### What we explicitly do not do
-
-- No reserved CSS keyword list.
-- No context-aware HTML parsing.
-- No breaking syntax migration.
-
-## Rationale for combining both layers
-
-- The heuristic alone makes the common case work for authors and LLMs without anyone having to know about escaping.
-- The escape alone forces every author and every prompt to learn the rule, and breaks paste-existing-CSS workflows.
-- Together, they cover the realistic surface: the heuristic handles the cases we can predict; the escape handles the cases we can't.
-
-## Scope of the change
-
-The preprocessor is shared across LLM prompts, PipeCompose templates, ImgGen prompts, and template document analyzers — all the call sites in:
-
-- `pipelex/pipe_operators/llm/pipe_llm_blueprint.py`
-- `pipelex/pipe_operators/llm/template_document_analyzer.py`
-- `pipelex/pipe_operators/compose/construct_blueprint.py`
-- `pipelex/pipe_operators/compose/pipe_compose_blueprint.py`
-- `pipelex/pipe_operators/compose/pipe_compose_factory.py`
-- `pipelex/pipe_operators/shared/template_image_analyzer.py`
-- `pipelex/pipe_operators/search/pipe_search_blueprint.py`
-- `pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py`
-- `pipelex/cogt/templating/template_blueprint.py`
-
-A single change to `preprocess_template` covers all of them.
-
-## Backward compatibility
-
-- The `(?!\s*[({"'])` lookahead changes the meaning of templates that currently match `@var (...)` or `$var "...`". The user confirmed `@var (…)` is not a real pattern (tagged blocks make a trailing parenthetical nonsensical). For `$` the same reasoning applies — `$var` is value formatting; a trailing parenthesized phrase is also unidiomatic.
-- The `(?<!\w)` lookbehind changes templates where `@var` immediately follows a word character. Today such templates already produce surprising results (see the email test); tightening here is a behavior fix, not a regression.
-- `@@` and `$$` are not currently meaningful in templates, so consuming them as escapes is a pure addition.
-
-A workspace-wide grep over existing `.mthds` files should confirm zero collisions before merge.
-
-## Documentation follow-ups (out of scope of this change, tracked separately)
-
-- Update agent-facing MTHDS authoring guidance to mention `@@` and `$$` escapes.
-- Add a short "writing templates with code/HTML inside" section to the docs.
-- Update the existing `test_email_address_partially_processed` semantics: emails should now pass through cleanly.
-
-## Open questions
-
-None blocking. The user confirmed the `@var (…)` edge case is not real, which removes the only material concern with the heuristic.
diff --git a/wip/template-preprocessor-line-bounded-at.md b/wip/template-preprocessor-line-bounded-at.md
deleted file mode 100644
index 11197ccfd..000000000
--- a/wip/template-preprocessor-line-bounded-at.md
+++ /dev/null
@@ -1,341 +0,0 @@
-# Template preprocessor — strict line-bounded `@` sigil (TDD plan)
-
-## Status: Open. Supersedes `wip/template-preprocessor-residual-edge-cases.md`. Adapts from the current state of `fix/Template-preprocessor-footguns` (the CSS / email / escape work shipped on this branch — that work stays; this plan strips the now-unnecessary heuristics on `@` and replaces them with a strict line-bounded rule + a load-time validator).
-
-## Why this design (one paragraph)
-
-`@var` produces `<var>...</var>` (a block-shaped envelope via the `tag()` filter). `$var` produces inline `format()` output. The existing collisions (`@media`, `@import`, `@font-face`, `[email protected]`, `@status. Amount (USD).`, `@var {{ jinja }}`, …) are all symptoms of letting `@` do inline duty when its rendered shape is fundamentally block-level. Restricting `@` to "alone on its own line" aligns syntax with semantics, makes the regex trivial, and turns silent pass-through (the current footgun) into a loud, actionable error.
-
-## Quick start (cold session)
-
-Working directory: `/Users/lchoquel/repos/Pipelex/pipelex` (the `pipelex/` runtime repo inside the multi-repo workspace at `/Users/lchoquel/repos/Pipelex/`).
-
-Read in this order:
-
-1. This file.
-2. `pipelex/cogt/templating/template_preprocessor.py` — current implementation (~100 lines, post-CSS-collision fix).
-3. `pipelex/cogt/templating/template_blueprint.py` — where `TemplateBlueprint` runs its pydantic `validate_template` hook; the new sigil validator hooks in alongside the existing Jinja2 syntax check.
-4. `pipelex/pipe_operators/llm/pipe_llm_blueprint.py:33-62` — example of the existing `preprocess_template + detect_jinja2_required_variables` pattern in a blueprint's `validate_inputs`; the new exception flows through this surface.
-5. `tests/unit/pipelex/cogt/templating/test_template_preprocessor.py` — single `TestTemplatePreprocessor` class with ~80 tests; many existing tests use inline `@var` and will be rewritten or repurposed.
-6. `wip/template-preprocessor-residual-edge-cases.md` — obsolete under the new rule for the `@` cases; the `$` residuals listed there are explicit non-goals here (see §Out of scope).
-
-Project conventions (from `pipelex/CLAUDE.md`):
-
-- One `TestClass` per test module. Keep everything inside `TestTemplatePreprocessor`.
-- pytest-mock, never `unittest.mock`.
-- `make agent-check` after code changes (Ruff + pyright + mypy + plxt).
-- Targeted test: `.venv/bin/pytest -q tests/unit/pipelex/cogt/templating/test_template_preprocessor.py`.
-- Full impacted run: see the source-to-test mapping in `pipelex/tests/CLAUDE.md` — `pipelex/cogt/` touches `tests/unit/pipelex/cogt/ tests/integration/pipelex/cogt/`, and the `pipe_operators` blueprints touch `tests/unit/pipelex/pipe_operators/ tests/integration/pipelex/pipes/`.
-
-## Target behavior
-
-### `@` and `@?` — line-bounded only
-
-An `@var` or `@?var` sigil is recognized **only** when it is the entire content of a line (leading/trailing whitespace allowed). Anything else containing a candidate sigil shape is an error at load time.
-
-```text
-✓ @invoice_text → {{ invoice_text|tag("invoice_text") }}
-✓ @?notes → {% if notes %}{{ notes|tag("notes") }}{% endif %}
-✓ @user.profile.bio → {{ user.profile.bio|tag("user.profile.bio") }}
-
-✗ Extract from @invoice_text. → ERROR: inline @invoice_text (line 1). Use $invoice_text for inline, or move @invoice_text onto its own line.
-✗ Hello @name! → ERROR: inline @name (line 1). …
-✗ @var $other_var → ERROR: @var is not alone on its line (line 1). …
-✗ The value (@value) is … → ERROR: inline @value (line 1). …
-```
-
-Identifier shape (unchanged in spirit, tightened slightly): `[a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*`. First char must be a letter or underscore (not a digit); dotted access supported; no trailing dot in the capture.
-
-### `$` — unchanged
-
-`$var` keeps its current inline behavior, lookaheads, and `(?![0-9])` digit guard. Known `$` residuals (`$name {{ jinja }}` not rewriting, `$user. info()` not rewriting) are explicit non-goals here — see §Out of scope.
-
-### `@@` and `$$` escapes — unchanged
-
-`@@` → literal `@`, `$$` → literal `$`. The sentinel substitution runs before validation and before the regex pass, so escaped occurrences never reach the validator and never trip the strict rule. Authors with literal CSS at-rules (`@@media`, `@@font-face`) or literal dollar amounts (`$$10`) escape with the doubled sigil.
-
-### Candidate sigil definition (the validator's scope)
-
-The validator does **not** flag every `@` in the template. It flags only "candidate sigils" — shapes that look like a malformed `@`/`@?` interpolation:
-
-- `@` (or `@?`) **not** preceded by a word character (post-`@@`-escape).
-- Followed immediately (no whitespace) by an identifier-shape capture.
-- On a line that is not solely that sigil + optional whitespace.
-
-This means:
-
-- `[email protected]` — `@` preceded by `e` (word char) → not a candidate → silently passes through. (Matches the current lookbehind protection.)
-- `@Override`, `@deprecated` in a code block at line start — IS a candidate (line-start `@` + identifier) → error if not alone. Authors escape with `@@Override` if they want literal.
-- `@media (max-width: 820px) {` — IS a candidate → error if not alone. Authors escape with `@@media`.
-- `@ media` (space after `@`) — not a candidate (no identifier immediately after `@`) → silently passes through.
-
-The validator's error message must include:
-
-- The line number (1-based).
-- The offending span (the `@` and the identifier).
-- A concrete migration hint: "Did you mean `$var` (inline) or move `@var` onto its own line? Escape with `@@` for a literal `@`."
-
-## Target code
-
-### Preprocessor (`pipelex/cogt/templating/template_preprocessor.py`)
-
-Replace `_SIGIL_PATTERN` (the unified alternation) with two patterns:
-
-```python
-# Line-bounded @ / @? sigil — must be alone on its own line.
-_AT_SIGIL_PATTERN = re.compile(
- r"^[ \t]*(@\??)([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)[ \t]*$",
- re.MULTILINE,
-)
-
-# Inline $ sigil — current heuristics, unchanged in scope (digit guard + identifier-class boundary
-# + code/CSS-shape lookahead). The `@` arm is gone from this pattern entirely.
-_DOLLAR_SIGIL_PATTERN = re.compile(
- r"(\$)(?![0-9])([a-zA-Z0-9_.]+)(?![a-zA-Z0-9_.])(?!\s*[({\"'])",
-)
-
-# Candidate-sigil detector for the validator: any unescaped @ at non-word boundary, followed by
-# an identifier shape. Used only to surface errors; never substitutes.
-_AT_CANDIDATE_PATTERN = re.compile(
- r"(?<!\w)(@\??)([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)",
-)
-```
-
-`_replace_sigil` collapses to two arms (no more `_Sigil.AT` vs `_Sigil.AT_OPTIONAL` ambiguity in shared code) but the `_Sigil` enum stays — used by both `@` and `$` callbacks.
-
-Trailing-dot handling stays in the `$` callback (where it still matters for prose like `$amount.`). It can be dropped from the `@` callback because the line-bounded regex cannot capture a trailing dot — the identifier class no longer includes `.` at segment boundaries.
-
-`preprocess_template` flow:
-
-```python
-def preprocess_template(template: str) -> str:
- # 1. Escape sentinels first — @@ and $$ disappear before validation and substitution.
- processed = template.replace("@@", _AT_ESCAPE_SENTINEL).replace("$$", _DOLLAR_ESCAPE_SENTINEL)
-
- # 2. Validate: any candidate @-sigil that is not alone on its line is an error.
- _validate_at_sigil_alone_on_line(processed)
-
- # 3. Substitute: @ line-bounded first, then $ inline. (Two passes are safe — @ output occupies
- # whole lines, so the $ pattern's lookahead never sees @-introduced braces.)
- processed = _AT_SIGIL_PATTERN.sub(_replace_at_sigil, processed)
- processed = _DOLLAR_SIGIL_PATTERN.sub(_replace_dollar_sigil, processed)
-
- # 4. Restore sentinels.
- return processed.replace(_AT_ESCAPE_SENTINEL, "@").replace(_DOLLAR_ESCAPE_SENTINEL, "$")
-```
-
-### New exception (`pipelex/cogt/templating/template_errors.py`, new module)
-
-```python
-from pipelex.system.exceptions import ToolError
-
-
-class TemplateSigilSyntaxError(ToolError):
- """Raised when a template contains a sigil shape that violates the strict @-line rule.
-
- The error message includes the line number, the offending span, and a migration hint.
- """
-```
-
-Placed alongside the other templating utilities, not under `tools/jinja2/`, because this is about Pipelex sigils, not about Jinja2 itself. Mirrors the `Jinja2TemplateSyntaxError` pattern in shape and ergonomics.
-
-### Validator (`pipelex/cogt/templating/template_preprocessor.py`)
-
-```python
-def _validate_at_sigil_alone_on_line(template: str) -> None:
- """Scan for candidate `@` / `@?` sigils that are not alone on their own line and raise.
-
- Inputs are post-`@@`-escape (so `@@` cases are already replaced by sentinels and don't trip
- the check). Word-adjacent `@` (emails, prose hashtags) is excluded by the `(?<!\w)`
- lookbehind on the candidate pattern.
- """
- for line_index, line in enumerate(template.split("\n"), start=1):
- if "@" not in line:
- continue
- if _AT_SIGIL_PATTERN.fullmatch(line):
- continue
- candidate = _AT_CANDIDATE_PATTERN.search(line)
- if candidate is None:
- continue
- sigil = candidate.group(1)
- identifier = candidate.group(2)
- msg = (
- f"Inline `{sigil}{identifier}` is not allowed on line {line_index}: "
- f"the `{sigil}` sigil produces tag-wrapped block content and must appear alone on "
- f"its own line. "
- f"Did you mean `${identifier}` (inline value), or move `{sigil}{identifier}` onto "
- f"its own line? "
- f"Escape with `@@` if you intend a literal `@`."
- )
- raise TemplateSigilSyntaxError(msg)
-```
-
-Loop semantics: report the first offending line, not all of them. Authors fix one, re-run, fix the next — cheaper to read than a bulk dump. (Worth confirming with the user before locking — see §Open decisions.)
-
-### Blueprint integration
-
-The existing `validate_inputs` methods in each pipe blueprint already call `preprocess_template(self.prompt)`. They need to catch `TemplateSigilSyntaxError` and re-raise with pipe-specific context, mirroring how they handle `Jinja2DetectVariablesError`:
-
-```python
-try:
- preprocessed_template = preprocess_template(self.prompt)
-except TemplateSigilSyntaxError as exc:
- msg = f"Template sigil error in PipeLLM prompt: {exc}"
- raise ValueError(msg) from exc
-```
-
-Same surface in `pipe_compose_blueprint.py`, `pipe_compose_factory.py`, `pipe_img_gen_blueprint.py`, `pipe_search_blueprint.py`, `pipe_compose/construct_blueprint.py`. And `TemplateBlueprint.validate_template` gets the same treatment.
-
-The `ValueError` wrapping is what pydantic surfaces in its validation error report — same path as the existing template-parsing errors. LSP / `plxt check` already render these cleanly.
-
-## Test migration framing
-
-Many tests in `test_template_preprocessor.py` exercise inline `@var` shapes that were valid under the heuristic and are invalid under the strict rule. They split into three buckets:
-
-1. **Generic-variable tests that just happen to use `@`.** Example: `test_variable_followed_by_comma` (`"Values: @first, @second, and @third"`). The point is "a sigil followed by punctuation works"; switching to `$first, $second` keeps the intent and matches the actual semantic (inline value). Rewrite the input to use `$`.
-
-2. **Tests that specifically validated the old `@`-can-be-inline contract.** Example: `test_at_variable_with_trailing_dot`, `test_back_to_back_at_variables`, `test_variable_in_parentheses`. Convert to `pytest.raises(TemplateSigilSyntaxError)` (or via a parametrized error-shape test) — these are the new contract tests.
-
-3. **Tests of `$` behavior, escape behavior, or `@` alone on a line.** Untouched. Example: `test_dollar_amounts_not_processed`, `test_double_at_escapes_to_literal_at`, `test_at_variable_pattern` (already uses `@expense\n@invoices`), `test_optional_at_variable_pattern` (uses `@?optional_field` on its own line), `test_variable_alone_on_line`, all CSS pass-through tests.
-
-The residual-rewrite tests (`test_css_namespace_residual_rewritten`, `test_css_font_face_residual_rewritten`, `test_css_dash_residual_rewritten`) get deleted — the residuals don't exist under the new rule. The companion escape tests (`test_css_namespace_escaped_pass_through`, `test_css_font_face_escaped_pass_through`, `test_css_dash_residual_escape_workaround`) stay — `@@` still works.
-
-CSS pass-through tests (`test_css_media_query_pass_through`, `test_css_supports_pass_through`, etc.) need a behavior change: today they assert the input passes through unchanged. Under the new rule, they assert the input **raises** `TemplateSigilSyntaxError`. The intent ("CSS at-rules are not sigils") is the same; the enforcement is now strict, not heuristic.
-
-Email pass-through tests (`test_email_address_pass_through`, `test_email_in_sentence_pass_through`, `test_word_adjacent_at_pass_through`) stay as pass-through — emails have a word char before `@`, so they're not candidate sigils and don't trip the validator.
-
-## Phases
-
-### Phase 1 — Replace the residuals doc and lock the plan
-
-- [x] Write this plan doc (`wip/template-preprocessor-line-bounded-at.md`).
-- [ ] Update `TODOS.md` so the next person opening the repo sees a single pointer to this file. The "Status: Complete" header from the prior CSS-collision work stays as history; a new "Next phase" section at the top points here.
-- [ ] Mark `wip/template-preprocessor-residual-edge-cases.md` as superseded (one-line note at the top pointing to this file). Don't delete it yet — it's still useful as history for the `$` residuals, which remain open.
-
-### Phase 2 — TDD red: new tests for the strict contract
-
-All new tests inside `TestTemplatePreprocessor`. Don't open a second class.
-
-- [x] **Strict-line success cases** (parametrized, all alone-on-line forms): `@var`, `@?var`, `@user.profile.bio`, `@_private_var`, ` @indented_var`, `@var\t` (trailing tab). Each rewrites correctly.
-- [x] **Strict-line error cases** (parametrized, all raising `TemplateSigilSyntaxError` with the expected message components — line number, offending span, migration hint):
- - Inline mid-sentence: `Extract from @invoice_text. Done.`
- - Inline trailing punctuation: `@var.`, `@var,`, `@var!`, `@var?`, `@var;`, `@var:`
- - Inline parenthetical: `(@var)`, `[@var]`
- - Multiple sigils per line: `@a @b`, `@a $b`, `$b @a`
- - Word-adjacent (but not email — preceded by space): `Word @var`, `@var Word`
- - CSS at-rules: `@media (max-width: 820px) {`, `@font-face { font-family: "X"; }`, `@import url("reset.css");`, `@keyframes spin { from {…} }`
- - Code constructs: `@Override`, `@deprecated def foo():`
-- [x] **Word-adjacent silent pass-through** (parametrized): `[email protected]`, `[email protected]`, `Send to [email protected] immediately.`, `prefix@suffix`. Each passes through unchanged with no error.
-- [x] **Escape cases unchanged**: existing `test_double_at_*`, `test_quadruple_at_is_two_escapes`, `test_escape_does_not_consume_legit_variable`, `test_escape_inside_style_block`. All still green. (Note: `test_triple_at_is_escape_plus_variable` survives Phase 2 untouched but is destined for Phase 3 conversion to `pytest.raises` — `@@@var` post-sentinel resolves to `<sentinel>@var`, which is no longer alone-on-line under the strict rule.)
-- [x] **Full style block now raises**: rewrote `test_full_style_block_pass_through` → `test_full_style_block_raises_under_strict_rule` (expects `TemplateSigilSyntaxError`) and added companion `test_full_style_block_escaped_pass_through` using `@@media` / `@@supports`.
-- [x] **Blueprint integration tests**: added three tests in `tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_blueprint.py` (note: actual dir is `pipe_llm/`, not `llm/`) — prompt-field, system_prompt-field, and multi-line line-number variants — each asserting pydantic surfaces `@var`, `$var` (migration), `@@` (escape), and `line N`.
-- [x] Run the suite. Confirmed: 23 red in preprocessor + 3 red in blueprint = 26 expected failures; 93 + 11 = 104 untouched tests still green.
-
-**Checkpoint A — DONE.** Phase 2 left the repo in a clean red state. Notes for whoever picks up Phase 3+:
-
-1. **Whitespace preservation deviation from §Target code.** The Phase 2 success-case tests assert that leading and trailing whitespace on indented alone-on-line forms is **preserved** (` @indented_var` → ` {{ indented_var|tag("indented_var") }}`, `@var\t` → `{{ var|tag("var") }}\t`). The plan's literal regex `r"^[ \t]*(@\??)(ident)[ \t]*$"` would consume the whitespace into the match and the `re.sub` callback would drop it. Phase 4 must use capture groups for leading/trailing whitespace and re-emit them in `_replace_at_sigil`, e.g.:
-
- ```python
- _AT_SIGIL_PATTERN = re.compile(
- r"^([ \t]*)(@\??)([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)([ \t]*)$",
- re.MULTILINE,
- )
- # callback: f"{leading}{rendered}{trailing}"
- ```
-
- This decision keeps templates embedded in indented YAML/TOML blocks rendering in the same column as the surrounding text. If you'd rather have whitespace eaten, flip the tests in `test_strict_line_at_sigil_success` (cases `indented_at_var`, `trailing_tab_at_var`, `tab_indented_optional_at_var`, `indented_at_var_in_block`) and drop the capture groups.
-
-2. **Skeleton-only `template_errors.py`.** `TemplateSigilSyntaxError(ToolError)` exists with no behavior. Phase 4 adds `_validate_at_sigil_alone_on_line` in `template_preprocessor.py` and the validator is what makes the red tests go green.
-
-3. **Phase 1 housekeeping still open.** Phase 1's checklist had two unticked items (TODOS.md pointer; superseded note on `wip/template-preprocessor-residual-edge-cases.md`). Those are still open. Pick them up before Phase 3 or fold them into Phase 6's docs work.
-
-4. **Targeted test commands for resuming work.**
-
- ```bash
- .venv/bin/pytest -q tests/unit/pipelex/cogt/templating/test_template_preprocessor.py
- .venv/bin/pytest -q tests/unit/pipelex/pipe_operators/pipe_llm/test_pipe_llm_blueprint.py
- ```
-
- Expected at start of Phase 3: 23 red + 3 red. After Phase 3 rewrite: many more red (legacy inline-`@` tests converted to `pytest.raises`). After Phase 4 implementation: all green.
-
-### Phase 3 — TDD red: rewrite the inline-`@` tests
-
-This is the meaty migration. Each test gets sorted into one of the three buckets in §Test migration framing.
-
-- [ ] Walk every test in `test_template_preprocessor.py` (and `test_template_pipeline.py`). For each that uses inline `@var`:
- - Bucket 1 (generic, switch to `$`): rewrite input from `@var` to `$var`, rewrite expected from `{{ var|tag(...) }}` to `{{ var|format() }}`.
- - Bucket 2 (specifically asserts `@` inline): convert to `pytest.raises(TemplateSigilSyntaxError)` (or fold into the parametrized error-cases test added in Phase 2 and delete the standalone test).
- - Bucket 3 (already alone-on-line, or about `$`/escapes): no change.
-- [ ] Delete `test_css_*_residual_rewritten` and `test_css_dash_residual_rewritten` — residuals don't exist under the new rule.
-- [ ] Rewrite the CSS pass-through tests (`test_css_media_query_pass_through` etc.) to expect `TemplateSigilSyntaxError`. Keep the escape companions as pass-through assertions.
-- [ ] Run the suite. State: even more red.
-
-### Phase 4 — Implementation (green)
-
-- [ ] Add `pipelex/cogt/templating/template_errors.py` with `TemplateSigilSyntaxError(ToolError)`.
-- [ ] In `template_preprocessor.py`:
- - [ ] Replace `_SIGIL_PATTERN` with `_AT_SIGIL_PATTERN`, `_DOLLAR_SIGIL_PATTERN`, `_AT_CANDIDATE_PATTERN` (see §Target code).
- - [ ] Split `_replace_sigil` into `_replace_at_sigil` and `_replace_dollar_sigil`. Drop trailing-dot handling from the `@` callback; keep it in the `$` callback.
- - [ ] Add `_validate_at_sigil_alone_on_line` (see §Target code).
- - [ ] Rewrite `preprocess_template` to: escape → validate → AT pass → DOLLAR pass → restore.
-- [ ] Update the docstring at the top of `template_preprocessor.py` to describe the strict rule and the candidate-sigil validator. Strip the long comment block describing the heuristic alternatives — it's no longer applicable.
-- [ ] In each pipe blueprint that calls `preprocess_template` (`pipe_llm_blueprint.py`, `pipe_compose_blueprint.py`, `pipe_compose_factory.py`, `pipe_img_gen_blueprint.py`, `pipe_search_blueprint.py`, `compose/construct_blueprint.py`, `shared/template_image_analyzer.py`, `template_document_analyzer.py`): wrap the `preprocess_template` call in `try/except TemplateSigilSyntaxError` and re-raise as `ValueError` with pipe-specific context. Mirror the existing `Jinja2DetectVariablesError` pattern.
-- [ ] Update `TemplateBlueprint.validate_template` to call `preprocess_template` and catch the new exception.
-- [ ] Run the suite. Expected: all Phase 2 + Phase 3 tests now green; legacy tests still green.
-
-**Checkpoint B**: Phase 4 done when `make agent-check` is clean and the targeted test run (`tests/unit/pipelex/cogt/ tests/unit/pipelex/pipe_operators/`) is green.
-
-### Phase 5 — Workspace sanity check
-
-Look for any `.mthds` file in the workspace that would now fail validation.
-
-- [ ] From the workspace root (`/Users/lchoquel/repos/Pipelex/`), run:
-
- ```bash
- # Inline @-sigil candidates — anything @var that's not on its own line:
- grep -rEn '(^|[^[:alnum:]_])@\??[a-zA-Z_][a-zA-Z0-9_.]*' --include="*.mthds" . | \
- grep -vE '^[^:]+:[0-9]+:[[:space:]]*@\??[a-zA-Z_][a-zA-Z0-9_.]*[[:space:]]*$' | \
- head -50
-
- # Existing @@ / $$ usages (already correct):
- grep -rEn '@@|\$\$' --include="*.mthds" . | head -50
- ```
-- [ ] For each hit, decide: migrate to `$var` (inline), reshape onto its own line, or escape with `@@` (literal `@`). Document the migration list in this file under a new "Workspace migration" section.
-- [ ] If hits exist in `methods/`, `pipelex-cookbook/`, `test-bed/`, or fixture-shipped `.mthds`, write the migrations as part of this branch. If hits exist in `mthds-plugins/` (the marketplace plugin), STOP and flag to the user — that repo isn't ours to touch from here.
-
-### Phase 6 — Authoring docs + CHANGELOG
-
-- [ ] Update `CHANGELOG.md` under `[Unreleased]`:
- - Replace the prior `### Fixed` entry for CSS collision with a `### Changed` (breaking) entry describing the new strict rule.
- - Keep the `### Added` entry for `@@` / `$$` escapes — still accurate.
- - Add a short migration note: "Inline `@var` is now a load-time error. Use `$var` for inline values, keep `@var` alone on its own line, or escape with `@@` for a literal `@`."
-- [ ] Update MTHDS authoring guidance to reflect the strict rule. Likely targets:
- - `pipelex/builder/` prompts and any in-repo authoring docs.
- - The MTHDS spec / `mthds-language-tutorial.md` (in the `mthds/` workspace repo) — **only if** the user explicitly opts in to a cross-repo doc change. Per the workspace rule, default is to leave the spec doc edits to a separate PR.
-- [ ] Update any IDE-side documentation (vscode-pipelex sees this via plxt — if plxt's diagnostics output changes, note it).
-
-### Phase 7 — Lint + full tests
-
-- [ ] `make agent-check` — Pyright, Ruff, Mypy, plxt all clean.
-- [ ] Targeted: `.venv/bin/pytest -n auto -m "(dry_runnable or not (inference or llm or img_gen or extract or search)) and not pipelex_api" -o log_level=WARNING --tb=short -q tests/unit/pipelex/cogt/ tests/unit/pipelex/pipe_operators/ tests/integration/pipelex/pipes/`
-- [ ] `make agent-test` — full suite green.
-
-**Checkpoint C**: Ready to ship via `/release`.
-
-## Open decisions to confirm before Phase 4
-
-These are small enough that I'll make a default call and proceed; flag any objections before locking in.
-
-1. **Validator reports first error, not all errors.** Default: yes (cheaper to read; matches Jinja2 syntax error behavior). Alternative: accumulate all sigil errors per template and raise once with a list — only worth it if templates regularly have many errors at once, which is unlikely.
-2. **Indented `@var` allowed.** Default: yes — `^[ \t]*@var[ \t]*$` permits leading indentation. Useful for templates embedded in YAML strings or indented blocks. Trailing whitespace too (forgiving on author trailing spaces). Alternative: zero indentation only — stricter but probably too aggressive for indented YAML / TOML embeddings.
-3. **Trailing-dot handling stays on `$`.** Default: yes — `$amount.` → `{{ amount|format() }}.` still works (existing behavior). The `@` callback drops the trailing-dot logic because the line-bounded regex can't capture one.
-4. **No accumulation across blueprints.** Default: each blueprint's `validate_inputs` raises the first sigil error it hits, even if the same .mthds file has more in other prompts (system_prompt, sub-templates). Pydantic's accumulation handles cross-field collection at the model level — the per-call raise is fine.
-
-## Out of scope / explicit non-goals
-
-- **`$` residuals from `wip/template-preprocessor-residual-edge-cases.md`.** `$name {{ jinja }}` not rewriting and `$user. info()` not rewriting are real but separate. They affect `$`, which keeps its inline contract. If we tackle them, it's a follow-up PR.
-- **Reserved-keyword list for CSS at-rules.** Not needed — the strict rule means CSS pass-through is by accident-free design (CSS at-rules always have content after them, so they're always inline candidates, so they always raise unless escaped).
-- **Auto-rewriting `@var` to `$var` in a migration tool.** If the workspace sanity check turns up enough hits that manual migration is painful, we could write a one-shot `plxt fix-sigils` command. Not in scope for this branch.
-- **HTML/`<style>`-aware parsing of templates.** Templates remain plain strings to the preprocessor.
-- **Changing the `tag()` / `format()` filter shapes.** Out of scope; this work is purely about which sigil sources rewrite into which Jinja form.
-- **Spec doc updates in the cross-repo `mthds/` repo.** Per the workspace plugin rule, default is to leave spec edits for a separate PR initiated from that repo.
diff --git a/wip/template-preprocessor-residual-edge-cases.md b/wip/template-preprocessor-residual-edge-cases.md
deleted file mode 100644
index 0179ad119..000000000
--- a/wip/template-preprocessor-residual-edge-cases.md
+++ /dev/null
@@ -1,280 +0,0 @@
-# Template preprocessor — residual edge cases (deferred)
-
-## Status: Superseded for the `@` cases by `wip/template-preprocessor-line-bounded-at.md` (2026-05-13). The strict line-bounded `@` rule eliminates Residual 1 and Residual 2 below — both are about inline `@var` shapes that are no longer valid under the new contract. The `$` variants of the same issues (`$name {{ jinja }}` not rewriting, `$user. info()` not rewriting) remain open and are explicit non-goals of the line-bounded plan; this doc stays as the reference if/when those `$` residuals are tackled in a follow-up PR.
-
-## Original status (historical): Open. Two false-negatives observed during PR review of `fix/Template-preprocessor-footguns` (2026-05-13). Not blocking — the CSS / email / code collisions that motivated the original fix all work. These are subtle shapes that the heuristic still silently passes through without interpolation.
-
-## Quick start (cold session)
-
-Working directory: `/Users/lchoquel/repos/Pipelex/pipelex`.
-
-Read in this order:
-
-1. This file.
-2. `wip/template-preprocessor-css-collision.md` — original design rationale (Strategy 2 + Strategy 3 from there shipped; this doc adds two more residuals on top).
-3. `pipelex/cogt/templating/template_preprocessor.py` — ~85 lines, the file being changed.
-4. `tests/unit/pipelex/cogt/templating/test_template_preprocessor.py` — the test file being extended (single `TestTemplatePreprocessor` class, 80 tests today).
-
-Project conventions (from `pipelex/CLAUDE.md`):
-
-- One `TestClass` per test module. New tests go inside `TestTemplatePreprocessor`.
-- pytest-mock, never `unittest.mock`. Neither residual needs mocking.
-- `make agent-check` after changes (Ruff + pyright + mypy + plxt).
-- Targeted test: `.venv/bin/pytest -q tests/unit/pipelex/cogt/templating/test_template_preprocessor.py`.
-
-## Current state of the regex (post-CSS-collision fix)
-
-`pipelex/cogt/templating/template_preprocessor.py:55-58`:
-
-```python
-_SIGIL_PATTERN = re.compile(
- r"(?:(?<!\w)(@\??)|(\$))(?![0-9])([a-zA-Z0-9_.]+)(?![a-zA-Z0-9_.])"
- r"(?!\s*(?:[({\"']|[a-zA-Z][\w-]*\s*(?:[(]|\{(?!\{))))"
-)
-```
-
-Three parts that matter here:
-
-- **Identifier class** `[a-zA-Z0-9_.]+` — greedy, includes trailing dots; stripped in the dispatcher (`_replace_sigil`) when the captured name ends with `.`.
-- **Direct opener arm** `[({\"']` — blocks `@var (...)`, `@var "..."`, `@var '...'`, `@var {`.
-- **Inner-word arm** `[a-zA-Z][\w-]*\s*(?:[(]|\{(?!\{))` — blocks one word + `(` or single `{` (the `\{(?!\{)` is the Jinja-aware part: `{{` is allowed).
-
-Both residuals below stem from quirks of these three pieces.
-
----
-
-## Residual 1 — `@var {{ jinja }}` / `$var {{ jinja }}` not rewritten
-
-### Symptom
-
-```python
-preprocess_template("Hello @name {{ greeting }}")
-# 'Hello @name {{ greeting }}' ← @name NOT rewritten (expected: {{ name|tag("name") }})
-
-preprocess_template("Hello $name {{ greeting }}")
-# 'Hello $name {{ greeting }}' ← same problem on the $ arm
-```
-
-### Root cause
-
-The **inner-word arm** uses `\{(?!\{)` so it allows `{{` (it only blocks a single `{` that isn't part of Jinja's `{{`). The **direct opener arm** doesn't — `[({\"']` matches any single `{`, including the first `{` of `{{`.
-
-So `@name {{` walks the direct arm:
-
-- `\s*` matches the space.
-- `[({\"']` tries `{` — matches. Direct arm fires.
-- Negative lookahead fails → `@name` is not matched.
-
-The inner-word arm and the direct arm are inconsistent: the design comment on `pipelex/cogt/templating/template_preprocessor.py:38-41` explicitly says `@var with {{ ... }}` should remain interpolated. Today it doesn't.
-
-### Fix sketch
-
-Split the `{` case out of the direct arm and reuse the `\{(?!\{)` trick:
-
-```python
-_SIGIL_PATTERN = re.compile(
- r"(?:(?<!\w)(@\??)|(\$))(?![0-9])([a-zA-Z0-9_.]+)(?![a-zA-Z0-9_.])"
- r"(?!\s*(?:[(\"']|\{(?!\{)|[a-zA-Z][\w-]*\s*(?:[(]|\{(?!\{))))"
-)
-```
-
-The change is `[({\"']` → `[(\"']|\{(?!\{)`. After the fix:
-
-- `@var (...)` — `(` matches the bracket class. ✓ still blocked.
-- `@var "..."`, `@var '...'` — same. ✓ still blocked.
-- `@var {` — `\{(?!\{)` matches (single `{`). ✓ still blocked.
-- `@page { margin }` — same as above. ✓ still blocked.
-- `@var {{ jinja }}` — `\{(?!\{)` fails because next char is `{`. Direct arm doesn't fire. Inner-word arm starts with `[a-zA-Z]` — `{` not in class, fails. Whole lookahead doesn't fire. `@var` IS rewritten. ✓ fixed.
-
-### Tests to add (red phase, inside `TestTemplatePreprocessor`)
-
-```python
-def test_at_var_then_jinja_open_rewrites(self):
- """`@var {{ jinja }}` must rewrite @var — the direct-opener arm must be Jinja-aware."""
- template = "Hello @name {{ greeting }}"
- result = preprocess_template(template)
- expected = 'Hello {{ name|tag("name") }} {{ greeting }}'
- assert result == expected
-
-def test_dollar_var_then_jinja_open_rewrites(self):
- """`$var {{ jinja }}` must rewrite $var — same fix as the @ arm."""
- template = "Hello $name {{ greeting }}"
- result = preprocess_template(template)
- expected = "Hello {{ name|format() }} {{ greeting }}"
- assert result == expected
-```
-
-Also add a regression guard so `@var {` (single brace, not Jinja) stays blocked:
-
-```python
-def test_at_var_then_single_brace_pass_through(self):
- """`@var {` (single brace, not Jinja) is still a code-shape opener — must NOT rewrite."""
- template = "Try @var { but not jinja"
- result = preprocess_template(template)
- assert result == template
-```
-
-### Open question for the implementer
-
-Is `@var {` (single brace) ever a legit Pipelex template construct? Probably not — the design doc says template variables aren't followed by `("'{` in practice. Keep the single-`{` block as-is; only `{{` becomes safe.
-
----
-
-## Residual 2 — `@var.` (trailing dot) + ` Word (` not rewritten
-
-### Symptom
-
-```python
-preprocess_template("The transaction was @status. Amount (USD).")
-# 'The transaction was @status. Amount (USD).' ← @status NOT rewritten
-
-preprocess_template("Reply @user. info()")
-# 'Reply @user. info()' ← @user NOT rewritten
-```
-
-Realistic shape: a sentence-ending sigil followed by a new sentence that contains a parenthetical (very common in prose-heavy LLM prompts).
-
-### Root cause
-
-Two interacting design choices:
-
-1. **Identifier class `[a-zA-Z0-9_.]+` includes `.`**, so the greedy match consumes the trailing dot — the dispatcher then strips it as sentence punctuation. This was the cheapest way to support both `@user.profile` (dotted access) and `@user.` (sentence end).
-
-2. **Backtracking is locked out by `(?![a-zA-Z0-9_.])`** — the post-identifier check. The greedy match captures `status.`; if the lookahead fails, the engine tries `status` (no dot), but `(?![a-zA-Z0-9_.])` then fails because the next char is `.`. No shorter match works.
-
-Concrete walk for `@status. Amount (USD)`:
-
-- Identifier matches `status.` (greedy with dot).
-- `(?![a-zA-Z0-9_.])` passes (next char is `S`).
-- Inner-word arm: `\s*` consumes ` `, `[a-zA-Z][\w-]*` matches `Amount`, `\s*` consumes ` `, `(?:[(]|\{(?!\{))` matches `(`. Inner-word fires.
-- Whole match rejected. Backtrack to `status` fails (next is `.`).
-- Final: `@status.` passes through unchanged.
-
-### Fix sketch (cleaner option)
-
-Make the identifier class NOT include the trailing dot, and rely on dotted-access via a structured pattern:
-
-```python
-_SIGIL_PATTERN = re.compile(
- r"(?:(?<!\w)(@\??)|(\$))(?![0-9])([a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*)(?![a-zA-Z0-9_.])"
- r"(?!\s*(?:[({\"']|[a-zA-Z][\w-]*\s*(?:[(]|\{(?!\{))))"
-)
-```
-
-Identifier change: `[a-zA-Z0-9_.]+` → `[a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*` (segments separated by single dots, no trailing dot allowed in the capture).
-
-After this change:
-
-- `@invoice_text.` — identifier captures `invoice_text` (no dot). The `.` is now text after the match, emitted literally by the surrounding template engine. Output: `{{ invoice_text|tag("invoice_text") }}.` — same as today.
-- `@user.profile.bio` — identifier captures `user.profile.bio` via `(?:\.[a-zA-Z0-9_]+)*`. Same as today.
-- `@status. Amount (USD)` — identifier captures `status`. The lookahead sees `. Amount (USD)`:
- - Direct arm: `\s*` zero, then `[({\"']` — `.` not in set, fails.
- - Inner-word arm: `\s*` zero, then `[a-zA-Z]` — `.` not in class, fails.
- - Lookahead doesn't fire. `@status` IS rewritten. ✓ fixed.
-
-### Bonus: dispatcher simplification
-
-If the identifier never has a trailing dot, the `trailing_dot` strip in `_replace_sigil` (`pipelex/cogt/templating/template_preprocessor.py:74-79`) becomes dead code. Delete it:
-
-```python
-def _replace_sigil(match: Match[str]) -> str:
- sigil = _Sigil(match.group(1) or match.group(2))
- variable: str = match.group(3)
- match sigil:
- case _Sigil.AT_OPTIONAL:
- return f'{{% if {variable} %}}{{{{ {variable}|tag("{variable}") }}}}{{% endif %}}'
- case _Sigil.AT:
- return f'{{{{ {variable}|tag("{variable}") }}}}'
- case _Sigil.DOLLAR:
- return f"{{{{ {variable}|format() }}}}"
-```
-
-### Tests to add
-
-Drop or rewrite the existing trailing-dot tests — their assertions still hold after the fix (the dot is emitted via the surrounding text instead of the dispatcher), but make sure they continue to pass:
-
-- `test_dollar_variable_with_trailing_dot`
-- `test_at_variable_with_trailing_dot`
-- `test_optional_at_variable_with_trailing_dot`
-- `test_multiple_at_variables_with_trailing_dots`
-- `test_nested_with_trailing_dot_in_complex_sentence`
-
-Add the new red-phase tests for the residual:
-
-```python
-def test_at_var_trailing_dot_then_word_paren_rewrites(self):
- """`@var. Word (extra)` must rewrite @var — sentence-ending sigil followed by a new
- sentence with a parenthetical is a realistic prose shape.
- """
- template = "The transaction was @status. Amount (USD)."
- result = preprocess_template(template)
- expected = 'The transaction was {{ status|tag("status") }}. Amount (USD).'
- assert result == expected
-
-def test_dollar_var_trailing_dot_then_word_paren_rewrites(self):
- template = "Reply $user. info()"
- result = preprocess_template(template)
- expected = "Reply {{ user|format() }}. info()"
- assert result == expected
-
-def test_optional_at_var_trailing_dot_then_word_paren_rewrites(self):
- template = "Optional @?notes. See (next page)."
- result = preprocess_template(template)
- expected = 'Optional {% if notes %}{{ notes|tag("notes") }}{% endif %}. See (next page).'
- assert result == expected
-```
-
-### Risks / things to double-check
-
-- **`@..foo` and similar malformed identifiers**: today, `[a-zA-Z0-9_.]+` matches `..foo` (greedy). After the fix, identifier must start with `[a-zA-Z0-9_]`, so `@.foo` fails to match — `@` stays literal. This is a behavior change for malformed input but seems harmless (no test covers it; nobody writes `@.foo`).
-- **`@user.profile.`** (dotted access + trailing dot): today captures `user.profile.` and strips the dot → `{{ user.profile|tag("user.profile") }}.`. After the fix: captures `user.profile`, dot is text → same output. Verify with a parametrized test.
-- **Inner-word arm interaction with the new identifier**: the inner-word arm is independent of the identifier class change. Existing tests for `@keyframes spin {`, `@layer reset {`, `@import url(...)` should be untouched. Re-run the full module.
-
----
-
-## Suggested TDD plan
-
-Both fixes are independent — land them in separate PRs or sequentially in one branch.
-
-### Phase 1 — Residual 1 (Jinja `{{` in direct arm)
-
-1. Add the three tests above (red).
-2. Apply the regex change `[({\"']` → `[(\"']|\{(?!\{)`.
-3. Re-run targeted tests — all green.
-4. `make agent-check`.
-
-### Phase 2 — Residual 2 (trailing dot + word + paren)
-
-1. Add the three new red-phase tests.
-2. Apply identifier change `[a-zA-Z0-9_.]+` → `[a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*`.
-3. Delete the `trailing_dot` block from `_replace_sigil`.
-4. Re-run all 80+ existing tests — every trailing-dot test should still pass because the dot survives as literal text.
-5. `make agent-check`.
-
-### Phase 3 — Workspace sanity check
-
-Same as the original fix's Phase 4: grep `.mthds` files in `/Users/lchoquel/repos/Pipelex/` for shapes that would behave differently under the new rules. Specifically:
-
-```bash
-# Mixed-Jinja templates that may now interpolate where they didn't:
-grep -rn '@[a-zA-Z_][a-zA-Z_0-9.]*[[:space:]]*{{' --include="*.mthds" . | head -50
-grep -rn '\$[a-zA-Z_][a-zA-Z_0-9.]*[[:space:]]*{{' --include="*.mthds" . | head -50
-
-# Sentence-ending sigils followed by parentheticals:
-grep -rn '@[a-zA-Z_][a-zA-Z_0-9.]*\.[[:space:]][A-Z][a-zA-Z]*[[:space:]]*[(]' --include="*.mthds" . | head -50
-```
-
-Decide per hit: accept (intended fix), document, or revert.
-
-### Phase 4 — CHANGELOG + docs
-
-Single `Fixed` entry under `[Unreleased]`. Cross-link to this doc. No new public API; no need to update `mthds-language-tutorial.md` or `pipe_compose_spec.py` (the escape mechanism is unchanged).
-
----
-
-## Out of scope
-
-- No new escape mechanism beyond `@@` / `$$`.
-- No reserved-keyword list.
-- No HTML/CSS-aware parsing.
-- No changes to the call sites of `preprocess_template` — all benefit transparently.
diff --git a/wip/temporal-listcontent-decode-bug.md b/wip/temporal-listcontent-decode-bug.md
deleted file mode 100644
index feeff3b97..000000000
--- a/wip/temporal-listcontent-decode-bug.md
+++ /dev/null
@@ -1,419 +0,0 @@
-# Tier 9b — Cross-process decode of dynamic-concept `ListContent` returned from a child workflow
-
-> **Status:** Ready to design. Bug is reproducible and root-caused. The companion fix in `template_preprocessor.py` (lookbehind on `@variable`) has already landed on this branch and unblocked the `pipelex run bundle ... generate_invoice_single` case end-to-end. Tier 9b (`generate_invoice_list`) is the remaining failure, and it sits in serialization, not in the parser.
->
-> **Workspace note:** `../kajson` (sibling repo `kajson/`) is fair game for changes — modify it if a cleaner abstraction lives there.
-
-## TL;DR
-
-`WorkingMemory.dump_for_temporal` (`pipelex/core/memory/working_memory.py:472-495`) injects raw `__class__` / `__module__` metadata onto each item of a `ListContent` payload. These markers are *meant* to be read by pipelex's own `hydrate_working_memory` after the per-workflow `LibraryCrate` has been loaded — but they are encoded with the **same keys** that `kajson`'s universal decoder uses to eagerly rebuild classes during Temporal's data-converter step, well before pipelex gets a chance to hydrate. When a child workflow returns a `PipeOutput` whose `working_memory_raw` contains those items, the parent workflow (`WfPipeRun`) tries to decode the result through `kajson` first, fails to find the dynamic class (`structured_output_test__Invoice`) in `'builtins'` or the global registry, and crashes with `KajsonDecoderError` → `RuntimeError: Failed decoding arguments`.
-
-The single-output case (`Invoice`) works because `dump_for_temporal` does **not** inject those markers for non-list content; only `ListContent` items get them.
-
-## Reproduction
-
-Prereqs:
-
-- Temporal dev server on `localhost:7233`
-- The two scoped workers from `/temporal-e2e-validate` (router + runner) running and pointed at the current code:
-
-```bash
-tmux kill-session -t temporal-worker-router 2>/dev/null
-tmux kill-session -t temporal-worker-runner 2>/dev/null
-tmux new-session -d -c "$PWD" -s temporal-worker-router \
- '.venv/bin/python -m pipelex.temporal.worker_cli --is-not-sandboxed --scope router'
-tmux new-session -d -c "$PWD" -s temporal-worker-runner \
- '.venv/bin/python -m pipelex.temporal.worker_cli --is-not-sandboxed --scope runner'
-sleep 5
-```
-
-### Failing case (Tier 9b — list)
-
-```bash
-.venv/bin/pipelex run bundle \
- tests/integration/pipelex/temporal/library_crate/structured_output_sequence.mthds \
- --pipe generate_invoice_list \
- --temporal --dry-run --mock-inputs --no-logo --graph
-```
-
-The CLI hangs. In the router tmux session you will see:
-
-```
-KajsonDecoderError: Class 'structured_output_test__Invoice' not found
- in module 'builtins' or global registry
-RuntimeError: Failed decoding arguments
- ← temporalio/worker/_workflow_instance.py:2101 (_convert_payloads)
- ← _apply_resolve_child_workflow_execution
- ← wf_pipe_run.py:43 (await workflow.execute_child_workflow(WfPipeRouter.run, ...))
-```
-
-Clean up after a failed run:
-
-```bash
-pkill -f "pipelex run bundle" 2>/dev/null
-RUNNING=$(temporal workflow list --address localhost:7233 --namespace default \
- --query 'ExecutionStatus="Running"' 2>&1 | tail -n +2 | awk '{print $2}')
-for wid in $RUNNING; do
- [ -n "$wid" ] && temporal workflow terminate --address localhost:7233 --namespace default \
- --workflow-id "$wid" --reason "cleanup"
-done
-# Restart the workers so they don't keep replaying the terminated workflow's history.
-tmux kill-session -t temporal-worker-router; tmux kill-session -t temporal-worker-runner
-# (re-create the sessions per the prereqs)
-```
-
-### Passing case (Tier 9a — single, for contrast)
-
-```bash
-.venv/bin/pipelex run bundle \
- tests/integration/pipelex/temporal/library_crate/structured_output_sequence.mthds \
- --pipe generate_invoice_single \
- --temporal --dry-run --mock-inputs --no-logo --graph
-```
-
-Completes with `✓ Dry run completed successfully`. Same dynamic `Invoice` concept, same crate. The only difference: single output (one Invoice) vs. list output (`Invoice[2]`).
-
-### Passing in-process counterpart (deliberately masks the bug)
-
-```bash
-.venv/bin/pytest -x -v tests/integration/pipelex/temporal/tracing/test_split_worker_object_gen.py \
- -m temporal --temporal-server local
-```
-
-Both `[single]` and `[list]` parametrizations pass. This is the test that was meant to validate cross-process object generation — but it shares a Python process with the in-process Temporal worker, so kajson's globals lookup succeeds by accident (see "Why this slipped past pytest" below).
-
-## Code path — what actually happens
-
-```
-CLI submitter (user process — has the crate)
- │
- │ starts top-level workflow
- ▼
-WfPipeRun.run(pipe_run_arg) (router worker process)
- │ pipelex/temporal/tprl_pipe/wf_pipe_run.py:29
- │
- │ line 43:
- │ pipe_output = await workflow.execute_child_workflow(WfPipeRouter.run, arg=pipe_job, id=...)
- │
- │ ┌────────────────────────────────────────────────────────────────┐
- │ │ When this await resolves, Temporal calls │
- │ │ _apply_resolve_child_workflow_execution → data converter │
- │ │ → kajson.loads(...) on the child's serialized PipeOutput. │
- │ │ │
- │ │ Kajson walks the JSON, sees __class__ on each list item, │
- │ │ tries to resolve 'structured_output_test__Invoice': │
- │ │ 1. module 'builtins' — not there │
- │ │ 2. global KajsonManager registry — not there │
- │ │ (WfPipeRouter registered it into a per-workflow registry │
- │ │ and tore that down in its `finally` block — see below.) │
- │ │ → KajsonDecoderError → Failed decoding arguments │
- │ └────────────────────────────────────────────────────────────────┘
- │
- ▼
-WfPipeRouter.run(pipe_job) (router worker process, child workflow)
- │ pipelex/temporal/tprl_pipe/wf_pipe_router.py:25
- │
- │ lines 51-65:
- │ workflow_registry = ClassRegistry()
- │ workflow_registry.register_classes_dict(global_registry.get_classes_dict())
- │ wf_library_id = f"wf_{workflow.info().workflow_id}"
- │ library_manager.open_library(library_id=wf_library_id)
- │ wf_library.set_class_registry(workflow_registry)
- │ set_current_library(library_id=wf_library_id)
- │ library_manager.load_from_crate(library_id=wf_library_id, crate=library_crate)
- │ └─ this registers `structured_output_test__Invoice` into workflow_registry
- │ — but NOT into the global KajsonManager registry.
- │
- │ line 127: pipe_output = await pipe.run_pipe(...)
- │ └─ dispatches act_llm_gen_object_list to the runner; runner returns list[Invoice]
- │ └─ result lands back in workflow_registry, fine here.
- │
- │ line 182: pipe_output = pipe_output.prepare_for_temporal(library_crate=library_crate)
- │ └─ PipeOutput.prepare_for_temporal (core/pipes/pipe_output.py:28-49) dehydrates:
- │ working_memory_raw = self.working_memory.dump_for_temporal()
- │ working_memory = WorkingMemory() # empty
- │
- │ finally (lines 172-176):
- │ library_manager.teardown(library_id=wf_library_id) # ← tears down per-workflow registry
- │ teardown_current_library()
- │
- │ line 185: return pipe_output
- │ └─ Temporal data converter encodes this PipeOutput via kajson.dumps(...)
-```
-
-## The actual offender
-
-`pipelex/core/memory/working_memory.py:472-495`:
-
-```python
-def dump_for_temporal(self) -> dict[str, Any]:
- raw = self.model_dump(serialize_as_any=True)
- raw_root = raw.get("root", {})
- for stuff_name, stuff in self.root.items():
- content = stuff.content
- if isinstance(content, ListContent) and stuff_name in raw_root:
- list_content = cast("ListContent[StuffContent]", content)
- serialized_items: list[dict[str, Any]] = []
- for item in list_content.items:
- item_dict = item.model_dump(serialize_as_any=True)
- # Preserve type metadata for items under Anything concepts so
- # the hydration side can reconstruct the correct content class.
- item_dict["__class__"] = type(item).__name__ # ← collides with kajson's marker
- item_dict["__module__"] = type(item).__module__ # ← collides with kajson's marker
- serialized_items.append(item_dict)
- raw_root[stuff_name]["content"] = serialized_items
- return raw
-```
-
-The intent of `__class__` / `__module__` here is pipelex-internal: a hint for `pipelex/temporal/tprl_pipe/hydration.py:_hydrate_list_item` so the `Anything[]` case can reconstruct the correct subclass. But these keys are also the **exact public protocol** that kajson uses in `kajson/json_decoder.py:113-194` (`universal_decoder`) to recognize encoded class instances. The data converter installed in `pipelex/temporal/temporal_data_converter.py` calls `kajson.loads(...)` on every payload, and kajson walks the whole tree.
-
-```python
-# kajson/json_decoder.py:132-170
-def universal_decoder(self, the_dict):
- if "__class__" not in the_dict:
- return the_dict # ← the only "leave-alone" branch
- class_name = the_dict.pop("__class__")
- module_name = the_dict.pop("__module__")
- # ... registry lookups, module imports, raise KajsonDecoderError on failure ...
-```
-
-So as long as the dehydrated payload contains `__class__` keys, kajson is going to try to bind the class **at the data-converter boundary**, before pipelex's own hydration runs. This works in-process because the dynamic class is still alive in the global registry; it does not work cross-process because `WfPipeRouter` tore down its per-workflow registry as part of returning.
-
-The fact that `PipeOutput.prepare_for_temporal` blanks out `working_memory` and moves the payload to `working_memory_raw` does **not** protect us: `working_memory_raw` is still a `dict[str, Any]`, kajson recurses into it, and finds the `__class__` keys.
-
-## Why single works and list fails
-
-Look at the same function (`working_memory.py:472-495`). The `__class__`/`__module__` injection is gated on `isinstance(content, ListContent)`. For single content (`Invoice`, not `Invoice[2]`), the function falls back to plain `model_dump(serialize_as_any=True)` output — no extra metadata. Kajson sees a plain dict at that position, returns it as-is, and pipelex's `hydrate_content` (`hydration.py:99-102`) takes over with concept-driven typing using `concept.structure_class_name`. No global-registry lookup at the kajson layer.
-
-The list path was added later to support the `Anything[]` case at `hydration.py:58-70`, where the hydrator cannot derive the per-item type from the concept alone. The author manually wrote `__class__` / `__module__` to carry the per-item type — not realizing they were also speaking kajson's language.
-
-## Why this slipped past pytest
-
-`tests/integration/pipelex/temporal/tracing/test_split_worker_object_gen.py` exercises the same `act_llm_gen_object_list` path, including the `[list]` parametrization, and passes. The reason is process topology, not test logic:
-
-- The pytest runs an **in-process** Temporal worker via the SDK's test environment.
-- The dynamic `Invoice` class is created in the test's Python process when the crate is loaded (it executes the bundle's structured-concept source code with `exec(...)`, producing a real class object).
-- That class object is referenced from the per-workflow registry, but Python's globals (and likely kajson's global `KajsonManager`) also hold a reference because the class was created in this process and has not been GC'd.
-- When kajson hits `__class__: 'structured_output_test__Invoice'` at decode time, it looks up the global registry, **finds the class accidentally**, and decodes fine.
-
-In the true 3-process CLI run:
-
-- `WfPipeRouter` runs in the router *worker* process.
-- That process loads the crate into a per-workflow registry, runs the pipe, then **explicitly tears the registry down** in the `finally` block (`wf_pipe_router.py:172-176`) before returning.
-- The class object becomes unreferenced and the global registry never had it.
-- When `WfPipeRun` (still in the router worker process, but in a different workflow scope after the child resolves) goes to decode the child's result, kajson cannot find the class anywhere.
-
-This is also why **`_validate_as_known_class` in `hydration.py:17-36`** doesn't help: it was written specifically to repair instances that kajson *did* rehydrate (using a different exec of the dynamic source). If kajson fails outright, we never reach `_validate_as_known_class`.
-
-## Constraints on any fix
-
-1. **Don't ship the crate twice.** The crate already travels with `PipeJob`. Re-attaching it to every child-workflow return payload would double the wire size.
-2. **Don't put dynamic classes into the global registry on the router process.** Per-workflow scoping is intentional — different workflows can define the same concept name with different shapes (Tier C of the concurrent isolation tests).
-3. **Don't lose the `Anything[]` use case.** The hydration side legitimately needs per-item type information when the concept does not pin it down.
-4. **Don't regress the in-process test path.** `test_split_worker_object_gen.py` and friends must keep passing.
-5. **Keep the dehydration symmetric.** `prepare_for_temporal` / `hydrate_working_memory` is a clean pair today; a fix that requires special-casing fields outside this pair is a smell.
-
-## Solution space
-
-### Option A — Use a pipelex-private marker namespace (recommended)
-
-Rename the markers in `dump_for_temporal` from `__class__` / `__module__` to a pipelex-private namespace, e.g. `__pipelex_class__` / `__pipelex_module__`. Kajson's universal decoder explicitly gates on `__class__` (`kajson/json_decoder.py:132`), so any other key set is invisible to it. Pipelex's hydration side already does its own class lookup using these markers (`hydration.py:58-62`), so it is purely a rename on both ends.
-
-Changes (estimated):
-
-- `pipelex/core/memory/working_memory.py:472-495` — write `__pipelex_class__` / `__pipelex_module__` instead.
-- `pipelex/temporal/tprl_pipe/hydration.py:58-62` — read `__pipelex_class__` instead of `__class__`; update the `{"__class__", "__module__"}` filter.
-- `pipelex/temporal/tprl_pipe/hydration.py:17-36` (`_validate_as_known_class`) — most of this function exists to repair kajson's eager-rehydrate artifacts. Once kajson is bypassed, the `isinstance(raw_item, StuffContent)` branch becomes unreachable for ListContent items; the function simplifies to dict-only handling. (Keep a cautious code path for now and add a regression test that asserts list items arrive as `dict` at hydration time.)
-
-Why this is elegant:
-
-- It recognizes that pipelex's "preserve type metadata for later hydration" was conceptually a *different protocol* from kajson's "auto-rebuild this class instance now". Today they collide because they share a key name; renaming makes them orthogonal.
-- Zero kajson changes. The protocol is documented by use: pipelex's dehydration format becomes self-contained and explicitly does not delegate class binding to the data-converter layer.
-- The `Anything[]` flow stays exactly the same — pipelex's hydration code still has the metadata it needs, just under different keys.
-- Per-workflow scoping is preserved end-to-end. Dynamic classes never need to escape into the global registry.
-
-Risk: external code that reads pipelex's dehydrated payloads and expects `__class__` would break. Grep shows zero such consumers; the only readers are `hydration.py` and the tests under `tests/integration/pipelex/temporal/library_crate/`. Worth a sweep before landing.
-
-### Option B — Make kajson skip unresolvable classes instead of raising
-
-Add a flag (or a registry option) so the decoder, when it cannot resolve a `__class__`, returns the raw dict instead of raising. Pipelex's hydration then does the binding using the per-workflow registry.
-
-Pros:
-
-- Generalizable. Other apps that ship deferred-binding payloads get the same benefit.
-- No marker rename; existing dehydrated payloads keep working.
-
-Cons:
-
-- Loses safety: typos and renamed classes silently become raw dicts. Recovering the "loud failure for unknown classes" behavior requires a second signal (a marker prefix? a registry override?).
-- The encoder still walks the tree and tries to resolve; we're paying the lookup cost for keys that we *intend* to defer.
-- This option *combines well* with A: pipelex uses Option A's private markers, and we additionally harden kajson so accidental `__class__` collisions are not fatal. But Option B alone is the wrong shape.
-
-### Option C — Walk the encoded `PipeOutput` and attach `kajson_class_source` for every nested dynamic class
-
-`BaseModelPayloadConverter` already has a mechanism (`temporal_data_converter.py:65-67`, `:75-77`, `:89-118`) where the encoder attaches `__kajson_class_source__` metadata on the top-level value, and the decoder rebuilds a scoped registry per payload from that source. Today it only fires when `type(value)` itself has `__kajson_class_source__` set. We could extend it to recursively scan the payload, collect every nested dynamic class's source, and ship the union.
-
-Pros:
-
-- Uses an existing kajson-aware mechanism.
-
-Cons:
-
-- O(payload-size) walk at every encode/decode boundary.
-- Multi-source payload metadata needs a new shape (today it's a single `bytes` field).
-- We are using a heavy hammer for what is structurally a naming collision; Option A is one rename away.
-- Doesn't actually need the source if the pipelex marker namespace is private — there is nothing for kajson to bind anymore.
-
-### Option D — Have `WfPipeRun` load the crate before awaiting the child result
-
-Add the crate to `PipeRunArg`, load it into a per-workflow registry inside `WfPipeRun` before line 43, so that when the data converter decodes the child workflow result, the class is in scope.
-
-Pros:
-
-- Conceptually consistent: every workflow that *might* see dynamic-concept payloads has the crate.
-
-Cons:
-
-- `WfPipeRun` becomes registry-aware purely to deserialize its child's return — leaks pipelex semantics into the orchestration layer.
-- Doubles the work: both `WfPipeRun` and `WfPipeRouter` would load and tear down the same crate, for the same workflow.
-- Doesn't help if a future workflow chain dispatches a child whose return contains dynamic concepts and the parent didn't expect them — Option A solves this structurally; Option D solves it case-by-case.
-
-## Recommended path
-
-Implement **Option A**. Keep Option B in the back pocket as a follow-up kajson hardening once we see the first user-defined collision (it has no value as a fix on its own but is good defense in depth). C and D should be discarded.
-
-### Concrete plan
-
-1. **Rename markers in pipelex.**
- - `pipelex/core/memory/working_memory.py:dump_for_temporal` — write `__pipelex_class__` / `__pipelex_module__`.
- - `pipelex/temporal/tprl_pipe/hydration.py:_hydrate_list_item` and the field-strip filter in `hydrate_content` — read the renamed keys.
-2. **Simplify `hydration.py:_validate_as_known_class`.** After the rename, kajson never rehydrates these dicts, so the `isinstance(raw_item, StuffContent)` branch in `_validate_as_known_class` becomes dead for the dehydrated-payload path. Keep it for any direct (non-Temporal) callers but add a code comment explaining the two execution modes.
-3. **Add a regression test.** Mirror `tests/integration/pipelex/temporal/tracing/test_split_worker_object_gen.py` but force a true cross-process topology via the test fixture (or assert at hydration time that `raw_item` is a `dict`, not a `StuffContent` instance — which is observable in-process and would have caught this).
-4. **Sweep for accidental external consumers.** `grep -rn '"__class__"\|"__module__"' pipelex/ tests/` to make sure no external test or tool reads pipelex's dehydrated format expecting kajson-compatible keys.
-5. **Update the Tier 9b expectations in `.claude/skills/temporal-e2e-validate/SKILL.md`.** Today the skill notes that this tier is "covered by the in-process pytest counterpart"; once the fix lands, the CLI form should pass too — drop the disclaimer.
-
-## Verification
-
-After the fix:
-
-1. **Unit-test:** new tests asserting that `WorkingMemory.dump_for_temporal` does not emit `__class__` and that `hydrate_working_memory` reads the renamed keys.
-2. **In-process integration test (must still pass):**
- ```bash
- .venv/bin/pytest -x -v tests/integration/pipelex/temporal/tracing/test_split_worker_object_gen.py \
- -m temporal --temporal-server local
- ```
-3. **Cross-process e2e (the original failure — must now pass):**
- ```bash
- .venv/bin/pipelex run bundle \
- tests/integration/pipelex/temporal/library_crate/structured_output_sequence.mthds \
- --pipe generate_invoice_list \
- --temporal --dry-run --mock-inputs --no-logo --graph
- ```
- Expect `✓ Dry run completed successfully` and a `results/generate_invoice_list_output_NN/` directory.
-4. **Regression sweep on the broader Temporal suite** (no behavior change expected):
- ```bash
- .venv/bin/pytest -x -v tests/integration/pipelex/temporal/library_crate/ \
- -m temporal --temporal-server local
- ```
- Expect the same 63 passed + 2 xpassed baseline.
-5. **Full agent suite:**
- ```bash
- make agent-check
- make agent-test
- ```
-
-## Critical files (reference)
-
-| File | Role |
-|------|------|
-| `pipelex/core/memory/working_memory.py:472-495` | `dump_for_temporal` — emits the colliding `__class__` markers. The offender. |
-| `pipelex/temporal/tprl_pipe/hydration.py` | Pipelex-side hydration; reads the markers. Symmetric counterpart to `dump_for_temporal`. |
-| `pipelex/core/pipes/pipe_output.py:28-49` | `PipeOutput.prepare_for_temporal` — moves `working_memory` into `working_memory_raw`. Already correct; not part of the fix. |
-| `pipelex/temporal/tprl_pipe/wf_pipe_router.py:25-185` | Child workflow that loads the crate, runs the pipe, dehydrates, returns. The crate registry is torn down in `finally`. |
-| `pipelex/temporal/tprl_pipe/wf_pipe_run.py:43` | Parent workflow's `await execute_child_workflow(WfPipeRouter.run, ...)` — the exact decode site that fails today. |
-| `pipelex/temporal/temporal_data_converter.py` | Pipelex's payload converter; wraps `kajson.dumps` / `kajson.loads` for Temporal. Notice the existing `__kajson_class_source__` mechanism on lines 65-77 / 89-118 — separate from this bug but worth understanding. |
-| `kajson/kajson/json_decoder.py:113-194` | `universal_decoder` — the function that eagerly resolves `__class__` and raises `KajsonDecoderError`. |
-| `kajson/kajson/json_decoder.py:132` | The exact line that gates "do nothing" vs "resolve class": `if "__class__" not in the_dict: return the_dict`. This is the contract Option A leans on. |
-| `tests/integration/pipelex/temporal/library_crate/structured_output_sequence.mthds` | The repro bundle. Defines a custom `Invoice` concept with nested `Customer` + `LineItem` list. |
-| `tests/integration/pipelex/temporal/tracing/test_split_worker_object_gen.py` | In-process pytest counterpart; passes today because of accidental globals reachability. Useful baseline for the regression test. |
-
-## Open question for the implementer
-
-The `__pipelex_class__` / `__pipelex_module__` names are placeholders chosen to make this proposal concrete. A more domain-specific name (`__listcontent_item_class__`, `__concept_item_type__`, …) might be worth a moment of consideration if pipelex plans to use this mechanism in more places. The key requirement is just: **not `__class__`** (or any name kajson reserves now or in the future).
-
----
-
-## Fix recap (2026-05-10) — Option A, shipped TDD
-
-**Decision:** kept the proposed names `__pipelex_class__` / `__pipelex_module__`. Direct symmetry with kajson's protocol keeps the role obvious to a future reader; no need to bikeshed a more domain-specific name.
-
-**Out-of-scope choices we deliberately did NOT take:**
-
-- **Option B (kajson skip-on-unresolvable).** Would re-couple the two protocols and convert a loud failure (unknown class) into a silent one (typo → plain dict). Skipped.
-- **Concept-aware optimization** (skip markers when the concept already pins the item class). Tiny payload win, breaks the symmetry of the `dump_for_temporal` / `hydrate_working_memory` pair. Skipped.
-- **Subprocess-based pytest regression fixture.** Brittle to add; the structural kajson-isolation unit test plus the CLI-level repro give stronger evidence. Skipped.
-
-### TDD sequence that landed
-
-**Phase 1 — RED (tests first):**
-
-- `tests/unit/pipelex/temporal/tprl_pipe/test_hydration.py` — added two tests in the existing `TestHydrateWorkingMemory` class and extended `test_hydrate_list_content_round_trip`:
- - `test_dump_for_temporal_list_items_carry_pipelex_markers_only` — asserts `__pipelex_class__` is present and `__class__` / `__module__` are absent on every dumped item.
- - `test_hydrate_list_item_reads_pipelex_markers` — uses `NumberContent` (not `TextContent`) so the legacy "`text` in raw_item" fallback cannot accidentally satisfy the test. Forces the rename to actually be read.
- - Extended round-trip test: same per-item marker assertion + existing typed assertions stay.
-- `tests/unit/pipelex/temporal/tprl_pipe/test_marker_isolation.py` (new) — `TestKajsonMarkerIsolation` with a parametrized-ish pair:
- - `test_pipelex_markers_pass_through_unchanged` — pipelex-namespaced markers must NOT trigger kajson resolution, even pointing at a non-existent class. Pins the wire-format contract without needing a Temporal server.
- - `test_kajson_markers_raise_for_unknown_class` — inverse oracle: `__class__` / `__module__` for an unknown class MUST raise. So any future re-collision shows up immediately.
-- `tests/unit/pipelex/tools/misc/test_clean_json.py` (new) — `TestCleanJsonContent::test_strips_marker_pair_at_all_depths` parametrized over `("__class__", "__module__")` and `("__pipelex_class__", "__pipelex_module__")`.
-
-Confirmed RED: 4 failing tests, 2 invariants already passing (the isolation tests, which is correct — they document the contract the rename leans on).
-
-**Phase 2 — GREEN (minimum implementation):**
-
-- `pipelex/core/memory/working_memory.py:491-492` — write `__pipelex_class__` / `__pipelex_module__` instead of `__class__` / `__module__`. Inline comment updated to explain the private-namespace rationale.
-- `pipelex/temporal/tprl_pipe/hydration.py:58, 61` — `_hydrate_list_item` reads `raw_item.get("__pipelex_class__")` and strips `{"__pipelex_class__", "__pipelex_module__"}` before `model_validate`.
-- `pipelex/tools/misc/json_utils.py:27` — `CLEAN_JSON_FIELDS_TO_SKIP` extended to `("__class__", "__module__", "__pipelex_class__", "__pipelex_module__")`. Both families stripped from user-facing JSON output — defense in depth, zero cost.
-
-All 12 tests in the bundle green after the edits.
-
-**Phase 3 — Refactor & docs (still green):**
-
-- Docstrings on `dump_for_temporal`, `_validate_as_known_class`, `_hydrate_list_item`, `hydrate_content` rewritten to reference the new keys and explain *why* the private namespace exists (not just *what* it is). `_validate_as_known_class` got an extra paragraph noting the `isinstance(raw_item, StuffContent)` branch is now defensive (kajson never rehydrates list items into instances on the Temporal hot path) — kept for direct callers and future regressions.
-- `CHANGELOG.md` `[Unreleased] > Fixed` entry added with the full diagnosis and fix description.
-
-### Verification
-
-| Layer | Result |
-|-------|--------|
-| Unit (renamed-marker emit/read/round-trip) | 4 RED → GREEN |
-| Unit (kajson isolation contract) | GREEN both directions |
-| Unit (`clean_json_content` strip) | RED on pipelex pair → GREEN |
-| Integration (`tests/integration/pipelex/temporal/` + `tests/integration/pipelex/tools/`) | 1499 passed, 1 unrelated skip, 2 baseline xpasses unchanged |
-| Cross-process CLI (`generate_invoice_list --temporal`) | Previously hung with `KajsonDecoderError`; now `✓ Dry run completed successfully` |
-| Cross-process CLI (`generate_invoice_single --temporal`) | Still passes (regression check) |
-| `make agent-check` | 0 errors, 0 warnings |
-
-### Files actually changed
-
-| File | Edit |
-|------|------|
-| `pipelex/core/memory/working_memory.py` | Emit `__pipelex_class__` / `__pipelex_module__`; docstring rewrite |
-| `pipelex/temporal/tprl_pipe/hydration.py` | Read `__pipelex_class__`; strip both renamed keys; docstring rewrites on three functions |
-| `pipelex/tools/misc/json_utils.py` | `CLEAN_JSON_FIELDS_TO_SKIP` extended to both marker families |
-| `CHANGELOG.md` | New `[Unreleased] > Fixed` entry |
-| `tests/unit/pipelex/temporal/tprl_pipe/test_hydration.py` | 2 new tests + extended round-trip; autouse fixture now registers `NumberContent` too |
-| `tests/unit/pipelex/temporal/tprl_pipe/test_marker_isolation.py` | New file |
-| `tests/unit/pipelex/tools/misc/test_clean_json.py` | New file |
-
-### No changes outside pipelex
-
-- `kajson/` — no edits (the rename leans on kajson's existing strict gate at `json_decoder.py:132`).
-- `pipelex/temporal/temporal_data_converter.py` — no edits.
-- `pipelex/core/pipes/pipe_output.py` — no edits.
-- Integration tests under `tests/integration/pipelex/temporal/` — no edits; `test_split_worker_object_gen.py` keeps passing as the in-process baseline.
-
-### Notes for a future reader
-
-- The `_validate_as_known_class` `isinstance(raw_item, StuffContent)` branch is now dead on the Temporal hot path. Kept defensively for direct callers; if a future audit confirms no such callers exist, the branch can be deleted and the function simplified to dict-only handling.
-- If you ever extend pipelex's deferred-binding protocol beyond ListContent items (e.g. nested in single-stuff dicts), reuse the `__pipelex_*` namespace — don't invent a third family.
-- The two-test pair in `test_marker_isolation.py` is the structural net. If kajson ever changes the gating key (or pipelex stops respecting it), one of those two tests fails immediately, no Temporal server required.
diff --git a/wip/temporal-next/00-enterprise-readiness-analysis.md b/wip/temporal-next/00-enterprise-readiness-analysis.md
deleted file mode 100644
index fad251206..000000000
--- a/wip/temporal-next/00-enterprise-readiness-analysis.md
+++ /dev/null
@@ -1,149 +0,0 @@
-# Pipelex × Temporal: Enterprise Readiness Analysis
-
-Strategic assessment of the current Temporal integration and a proposed phasing plan to bring it to a level of technological readiness that would clear an enterprise CIO review.
-
-Scope of audit: `pipelex/temporal/` (30 core files), `docs/distributed-execution/` (5 docs), `pipelex/pipelex.toml` config surface, `tests/` coverage, `.github/workflows/` CI gating, and `wip/temporal-primitives/` planning state.
-
----
-
-## 1. Where we stand today
-
-**Strong fundamentals (TRL ~6–7):**
-
-- Clean separation of concerns across the module: management (`temporal_manager`, `temporal_hub`), execution (`temporal_task_manager`, `worker_cli`), routing (`config_temporal.py` — three-layer baseline → queue → handle overlays), serialization (`temporal_data_converter`, `codec/`), and observability (`tprl/observability.py`, `tprl/namespace_check.py`).
-- Policy-rich configuration: server profiles, worker scopes, named runtime profiles, per-activity / per-handle routing, search-attribute pre-flight validation at worker boot with "did you mean?" UX.
-- Replay safety taken seriously: deterministic IDs, sandbox-aware logging (`sandbox_manager.py`), UTF-8-safe summary/details truncation.
-- The five docs under `docs/distributed-execution/` cover the operational story for single-tenant deployments end-to-end.
-
-Phases 1–6 of `wip/temporal-primitives/` are shipped; the only deferred item is the `WorkflowExecutionError → ApplicationError` cleanup.
-
----
-
-## 2. Critical gaps a CIO will flag
-
-Ordered by how loudly they'll come up in an enterprise security / procurement review:
-
-1. **Authentication is too narrow.** `temporal_connect.py` supports only static API keys (env var or secret provider). No mTLS, no OAuth/OIDC, no custom CA bundle. Hard blocker for regulated industries and most large enterprises with PKI/SSO requirements.
-
-2. **Payload codec has no client-side encryption.** `codec/storage_payload_codec.py` offloads payloads to GCS/S3/local but relies entirely on the backend's at-rest encryption. A stolen storage backup is plaintext customer data. No envelope encryption, no KMS hook, no field-level PII masking. Static summary/details builders dump pipe inputs into the Temporal UI with no redaction allowlist.
-
-3. **The project's own error-handling rule is violated in workflow-critical paths.** `tprl_pipe/wf_pipe_router.py` has multiple `except Exception` blocks; `tprl_pipe/act_assemble_graph.py` has one labeled "TODO: wip — do not catch all exceptions". CLAUDE.md explicitly forbids this. Adversarial reviewers and auditors anchor on exactly these.
-
-4. **No OpenTelemetry / no metrics exporter.** Observability is Temporal-UI-centric. Enterprises require traces into their own APM (Datadog, New Relic, Dynatrace, Honeycomb) and metrics into Prometheus/StatsD: queue depth, retry rate, activity duration histograms, codec offload latency, slot saturation. None of that is wired today.
-
-5. **CI only runs the in-process test server.** The default `--temporal-server none` means no regression coverage against a real Temporal server — version-drift, cluster-failover, and real-RPC semantics aren't validated in CI.
-
-6. **Test coverage is thin in core modules.** Codec encode/decode, dispatch resolution, observability builder, error classification, config composition, and the search-attribute pre-flight have no unit tests. Integration tests cover happy paths well; no chaos tests (worker crash mid-activity, server unreachable, retry exhaustion, replay non-determinism, cancellation propagation).
-
-7. **No multi-tenant admission control.** `UserId` / `DomainCode` search attributes are informational. There's no gate that says "tenant X may only invoke this pipe list", no per-tenant quotas, no per-tenant rate limit, and the codec doesn't verify `user_id` matches the authenticated submitter before writing storage keys.
-
-8. **No DR / BCP story.** Docs are silent on namespace replication, RTO/RPO, codec-storage cross-region replication, backup/restore. "What happens if our primary region goes down?" has no published answer.
-
-9. **No upgrade / rolling-deployment guidance.** Worker versioning, sticky-queue drain, blue/green via task queues — none documented. This is the #1 ops question for production rollouts.
-
-10. **Smaller but real:** hardcoded sandbox `passthrough_modules` list; `WorkerRuntimeProfile.tuning_mode = RESOURCE_BASED` is reserved but raises at config validation (creates confusion); per-queue `rate_limit` is cluster-wide and racy when multiple workers publish different values.
-
----
-
-## 3. Proposed phasing to TRL 9
-
-A 6-phase ladder, each phase with a coherent CIO-facing message and a hard exit gate. Phases 0–2 are the bulk of the lift; 3–5 are productization.
-
-### Phase 0 — Hygiene & test hardening *(foundation; no new features)*
-
-**Why:** before shipping enterprise primitives, the existing surface must pass its own rules and have a regression net.
-
-- Replace every `except Exception` in `pipelex/temporal/` with typed catches (priority: `tprl_pipe/wf_pipe_router.py`, `tprl_pipe/act_assemble_graph.py`).
-- Resolve open TODOs (`temporal_task_manager.py` sandbox-logger note; conftest `Pipelex.make()` heavy-boot note).
-- Add unit tests for: codec encode/decode + path-traversal sanitization, dispatch resolution (baseline → queue → handle merge), observability builders (UTF-8 truncation), error classification, search-attribute validator.
-- Add chaos-style integration tests: worker crash mid-activity, server disconnect & reconnect, retry-policy exhaustion, replay non-determinism, child-workflow cancellation propagation, signal/query round-trip.
-- Add a CI matrix entry that runs the integration suite against a real Temporal server (containerized) alongside the in-process one.
-- **Eliminate remaining config reads inside workflow code** (flagged by PR #891 review — chatgpt-codex-connector). The submitter-side pattern is already in place for `WorkflowExecutorFactory` (bypassed inside workflows) and for `TemporalManager.session_id` (`stamp_submitter_session_id`), but two call paths still re-derive options from `get_config()` at workflow runtime, which would diverge on replay after any config edit:
- - `pipelex/temporal/tprl/observability.py:104-107` — `build_search_attributes` reads `get_config().temporal.search_attributes` (`enabled` flag + `attributes` list). Toggling either between deploys changes the recorded `StartChildWorkflowExecution` command on replay. The docstring already claims the helper is "a pure function" — making it actually pure requires snapshotting the enabled attribute names at the submitter boundary (analogous to `stamp_submitter_session_id`) and carrying them on `PipeJob` / `JobMetadata`. Affects every in-workflow caller: `wf_pipe_run.py:57`, `temporal_pipe_router.py:85`.
- - `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py` — every `make_*` method calls `worker_config.resolve_dispatch(..., queue_options_by_queue=get_config().temporal.queue_options, is_traced=get_config()...)` inside workflow code, so changing routing, queue options, or `is_dispatch_resolution_traced` re-derives a different `task_queue` / timeout / retry policy on replay and fails the workflow task. The same class of issue is acknowledged at `workflow_caller.py:179+` for child-workflow options; activity dispatch needs the equivalent treatment. Either snapshot the resolved dispatch options per activity at the submitter boundary, or freeze the relevant config blocks into the workflow input.
-
-**Exit:** zero `except Exception` in `temporal/`; zero `get_config()` reads in workflow code paths (enforced by an AST scanner extension); CI green on real server; coverage report published per PR.
-
-### Phase 1 — Security baseline *(unblocks CISO)*
-
-**Why:** today the deal-breakers for any enterprise procurement are authentication and payload encryption.
-
-- mTLS support in `TemporalServerConfig`: client cert/key paths, custom CA bundle, configurable cipher suites.
-- OAuth/OIDC token auth as an alternative to static API keys; hot-reload on rotation without worker restart.
-- Envelope encryption in `StoragePayloadCodec`: KMS-managed DEKs, pluggable provider (AWS KMS, GCP KMS, Azure Key Vault, HashiCorp Vault); key-ID stored in payload metadata for rotation.
-- PII handling: declarative redaction allowlist for `build_static_details` / `build_static_summary`; documented "what goes into search attributes" policy.
-- Codec admission check: verify `user_id` matches authenticated submitter before storage write.
-- SBOM generation + CVE scan in CI (`pip-audit` or Grype + Syft); dependency pinning policy.
-- Published threat model document; external pen-test against a reference deployment.
-
-**Exit:** mTLS + at-rest envelope encryption working in a reference deployment; pen-test report with no high/critical findings; SBOM in releases.
-
-### Phase 2 — Observability & SRE-grade telemetry
-
-**Why:** enterprise ops teams refuse to operate what they can't see in their existing tools.
-
-- OpenTelemetry instrumentation: spans from submitter → parent workflow → child workflow → activity, with `pipeline_run_id` as trace correlation key.
-- OTLP exporter wired through `temporal_hub`; documented Datadog / New Relic / Honeycomb config.
-- Prometheus metrics: queue depth, codec offload/restore latency p50/p95/p99, retry rate per activity, slot saturation, payload-size histogram, graph-assembly failures.
-- Structured JSON logging mode in `log_formatter.py` (extending existing prefix injection); correlation IDs everywhere.
-- Shipped artifacts: Grafana dashboard JSON, PromQL alert recipes (orphaned workflows, queue lag, codec storage outage), runbooks for the top failure modes.
-
-**Exit:** demoable end-to-end trace from API request to LLM call; Grafana board + alert recipes shipped; runbook set published.
-
-### Phase 3 — Operational excellence
-
-**Why:** CIOs ask "can I deploy this on Tuesday afternoon without paging anyone?"
-
-- Rolling-upgrade strategy doc + reference: Temporal Worker Versioning, sticky-queue drain, parallel task queues for blue/green.
-- Capacity planning guide derived from a published load-test harness (req/s → worker count → runtime profile sizes per activity class).
-- Implement `WorkerRuntimeProfile.tuning_mode = RESOURCE_BASED` (or remove the enum value if not committed).
-- Auto-scaling reference: KEDA + Temporal queue-lag metric, sample helm chart.
-- Config drift CLI: `pipelex worker diff` to compare running config vs canonical.
-- Per-worker rate-limit reconciliation (eliminate the "latest writer wins" race in per-queue rate limit).
-- Document an SLO/SLI catalog: latency SLOs per activity class, queue saturation SLOs, error-budget framing.
-
-**Exit:** load-test report; SLO catalog published; reference helm chart; rolling-upgrade tested end-to-end.
-
-### Phase 4 — Multi-tenancy & governance
-
-**Why:** enterprises onboard once and run many tenants; the platform must enforce isolation, not document it.
-
-- Per-tenant RBAC at submission: tenant → allowed pipe list; codec validates scope.
-- Quota enforcement: per-tenant concurrent-workflow cap, per-tenant queue rate-limit overlay.
-- Cost attribution: per-tenant counters for activity-seconds, payload bytes, LLM tokens (extends telemetry already partially present).
-- Data residency: per-tenant codec storage region + KMS key.
-- Retention policies: configurable per `pipeline_run_id` age; automatic codec garbage-collection job.
-- Audit log sink: Kafka/SIEM-bound stream covering workflow lifecycle + admin actions (worker config reload, codec key rotation).
-- Reference deployment patterns: namespace-per-tenant, shared-namespace-with-isolation; admission control on both.
-
-**Exit:** reference multi-tenant deployment with chargeback report; auditor-friendly event stream demonstrably feeding a SIEM.
-
-### Phase 5 — Disaster recovery & business continuity
-
-**Why:** any CIO sign-off requires a documented RTO/RPO and a tested DR drill.
-
-- Multi-region active/passive pattern with Temporal namespace replication; documented submitter behavior during failover.
-- Codec storage cross-region replication recipes (S3 CRR, GCS dual-region, Azure GRS).
-- Backup/restore runbook for codec storage + a sample restore validator.
-- DR drill harness: scripted chaos test forcing namespace failover, asserting in-flight workflows resume.
-- Documented retention policies aligned to common compliance regimes (GDPR, HIPAA, PCI tier).
-
-**Exit:** DR drill log demonstrating an explicit RTO and RPO target on the reference deployment.
-
-### Phase 6 — Certification & productization *(TRL 9 marker)*
-
-- SOC 2 Type II readiness; ISO 27001 control mapping doc.
-- HIPAA / PCI tier guidance with concrete configurations.
-- Customer-facing security whitepaper.
-- Versioned compatibility matrix: Pipelex × Temporal Python SDK × Temporal Server; LTS branch policy.
-- At least one reference customer running this at production scale and willing to be quoted.
-
-**Exit:** external attestation; published compatibility matrix; reference customer in production for an extended period.
-
----
-
-## 4. Recommendation
-
-If we sequence this, **Phase 0** is a non-negotiable prerequisite — it's mostly cleanup of stated rules and missing tests, and it makes everything after it cheaper. Then **Phase 1 and Phase 2 in parallel** unblock the two distinct stakeholders (CISO and SRE) who together account for the bulk of enterprise procurement friction. Phases 3–6 are best paced against actual customer demand.
-
-The single highest-leverage item across all phases is probably **envelope-encrypted payload codec with KMS pluggability** (Phase 1) — it converts the integration from "trust the backend" to "we own the data plane", which is the framing CIOs reward.
diff --git a/wip/temporal-next/01-deferred-items.md b/wip/temporal-next/01-deferred-items.md
deleted file mode 100644
index 752ea54cd..000000000
--- a/wip/temporal-next/01-deferred-items.md
+++ /dev/null
@@ -1,108 +0,0 @@
-# Temporal — Deferred Items Index
-
-Single index of work explicitly deferred out of shipped Temporal phases and the in-flight `feature/Temporal-merge-3` (PR #891) merge. Each entry links back to the doc that owns the full context — this file is just the directory so nothing falls off the radar.
-
-For non-temporal deferrals, see [`../deferred-items.md`](../deferred-items.md).
-
----
-
-## Replay-determinism: remaining `get_config()` reads inside workflow code
-
-**Source:** PR #891 review (chatgpt-codex-connector, 2026-05; cubic-dev-ai independently flagged the same root cause at `wf_pipe_run.py:57`, 2026-05).
-**Owner doc:** Phase 0 of [`00-enterprise-readiness-analysis.md`](00-enterprise-readiness-analysis.md) — bullet "Eliminate remaining config reads inside workflow code".
-**Precedent:** the same class of issue was already solved at the submitter boundary for `WorkflowExecutorFactory` (bypassed inside workflows — see `tprl/workflow_caller.py:179+`) and for `TemporalManager.session_id` (`stamp_submitter_session_id` in `tprl/observability.py`).
-
-Two call paths still re-derive options from `get_config()` at workflow runtime, which would diverge on replay after any config edit:
-
-- `pipelex/temporal/tprl/observability.py:104-107` — `build_search_attributes` reads `get_config().temporal.search_attributes` (`enabled` + `attributes`). Affects every in-workflow caller: `wf_pipe_run.py:57`, `temporal_pipe_router.py:85`.
-- `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py` — every `make_*` method calls `worker_config.resolve_dispatch(..., queue_options_by_queue=get_config().temporal.queue_options, is_traced=get_config()...)` inside workflow code. Changing routing, queue options, or `is_dispatch_resolution_traced` re-derives a different `task_queue` / timeout / retry policy on replay and fails the workflow task. The same class of issue is acknowledged at `workflow_caller.py:179+` for child-workflow options; activity dispatch needs the equivalent treatment.
-
-### Why the "submitter snapshot on workflow input" pattern is the wrong fix
-
-An initial attempt during the PR #891 follow-up implemented a `TemporalDispatchSnapshot` pydantic model that froze `worker_config`, `queue_options`, `is_dispatch_resolution_traced`, and the search-attribute toggle + name list on `JobMetadata`, stamped at the top-level dispatch boundary alongside `stamp_submitter_session_id`. **That approach was reverted** after a Temporal-developer skill consultation. Reasons:
-
-- **Architectural inversion.** The `worker_config` slice (routing, queue tunings, retry policies) is operator-owned deployment concern. Putting it on workflow input mixes operations data with business state — the opposite of why central config exists.
-- **Payload bloat.** Temporal limits are 2 MB per payload, 4 MB per gRPC message, <10 MB per workflow history. A serious deployment with dozens of `activity_queues`, per-handle routing, queue overlays, and retry policies makes the snapshot non-trivially sized, and it now rides on (a) every workflow start, (b) every child workflow start, (c) every activity input via `JobMetadata`. For fan-out-heavy or long-running pipelines this can balloon history.
-- **Defeats the point of central config.** The whole reason operators want central config is to edit it without code changes. Freezing it on workflow input makes the edit only apply to *new workflows started after the edit* — which is exactly what Worker Versioning (PINNED) gives you natively, without the payload cost.
-- **Not Temporal-idiomatic.** The temporal-developer skill's `references/core/versioning.md` and `references/core/gotchas.md` point to **Worker Versioning + Patching API** as the canonical answer for "behavior might change while workflows are in flight," not to threading operator config through workflow inputs.
-
-### What the right fix looks like
-
-Ordered from least to most invasive — pick the combination that fits the operational maturity target:
-
-1. **Documentation + replay test (cheapest).** Add to `docs/distributed-execution/`: "Changing `[temporal.worker_config]`, `[temporal.queue_options]`, or `[temporal.search_attributes]` while workflows are in-flight may cause those workflows to fail with `NondeterminismError`. Drain workflows before rolling out routing/timeout/retry changes, or use Worker Versioning." Add a `Replayer`-based regression test over a saved history. Keep the AST scanner rule from Phase 0 — but reframe its purpose as *"prevent regressions beyond the current surface,"* not *"require zero `get_config()` reads."*
-2. **Worker Versioning (production-grade).** Wire `WorkerDeploymentConfig` + `WorkerDeploymentVersion` into `pipelex worker` (new flags `--deployment-name`, `--build-id`), default to `VersioningBehavior.PINNED`. Operators then version their deployments and old workflows keep replaying on old workers / old config. No payload cost, no architectural inversion, no application-level snapshot needed.
-3. **Thin snapshot only for search attributes (Option-3 compromise).** Stamp just `search_attributes_enabled: bool` + `search_attribute_names: list[str]` on `JobMetadata` if you want the search-attribute slice deterministic without taking the Worker-Versioning dependency. Tiny size, doesn't carry operator routing/retry config. Skip the `worker_config` + `queue_options` snapshot entirely (those need Worker Versioning or operational discipline).
-
-**Exit gate (revised):** Worker Versioning supported in the worker CLI; documentation describes the operational constraint and the versioning workflow; AST scanner extended to flag *new* `get_config()` reads in workflow-side code paths so the surface doesn't grow.
-
----
-
-## `WorkflowExecutionError` → `ApplicationError` cleanup
-
-**Source:** Phase 5 / 6 follow-up; only deferred item from temporal-primitives Phases 1–6.
-**Owner doc:** [`../temporal-primitives/03-temporal-error-handling-revamp.md`](../temporal-primitives/03-temporal-error-handling-revamp.md).
-
-`WorkflowExecutionError` doesn't subclass `temporalio.exceptions.FailureError`, so the workaround in commit `117bbe01` registers it in the Worker's `workflow_failure_exception_types` list. Proposal: make `WorkflowExecutionError` subclass `ApplicationError`, drop the registration, simplify the exception model end-to-end.
-
----
-
-## `except Exception` removals in workflow-critical paths
-
-**Source:** [`00-enterprise-readiness-analysis.md`](00-enterprise-readiness-analysis.md) gap #3 + Phase 0 first bullet.
-**Owner doc:** Phase 0 of `00-enterprise-readiness-analysis.md`.
-
-Priority files: `tprl_pipe/wf_pipe_router.py` (multiple `except Exception`), `tprl_pipe/act_assemble_graph.py` (one labeled `# TODO: wip — do not catch all exceptions`). Already partially addressed in commit `117bbe01` for `tprl/workflow_caller.py`; the workflow-side and activity-side catches remain.
-
----
-
-## Out-of-scope-but-tracked from temporal-primitives
-
-**Owner doc:** [`../temporal-primitives/02-id-and-naming-plan.md`](../temporal-primitives/02-id-and-naming-plan.md) §"Out of scope".
-
-These are explicitly out of scope for the shipped temporal-primitives work but stay on the watchlist:
-
-- `workflow.set_current_details(...)` for in-flight progress.
-- Memo population beyond the optional `library_crate` fingerprint.
-- Per-pipe Workflow Type registration.
-- Search-attribute schema versioning / migration tooling.
-- `display_label` parameter at the `PipeRun` entry point.
-- **Unifying the two child-spawn paths.** Was attempted (Phase 5 follow-up), reverted (`ac8e2335`) for replay-determinism reasons — a clean unification needs the submitter-snapshot pattern above to land first.
-- `WorkflowIDReusePolicy` choice — stays at SDK default `ALLOW_DUPLICATE`; revisit whether `REJECT_DUPLICATE` catches double-execution bugs now that workflow IDs are deterministic from `pipeline_run_id`.
-
----
-
-## Config-driven infrastructure activity tuning
-
-**Source:** PR #891 `/review` (informational finding #8).
-**Owner doc:** this file.
-
-`pipelex/temporal/tprl_pipe/wf_pipe_run.py` dispatches two infrastructure activities — `act_assemble_graph` and `act_deliver` — with hardcoded options: `start_to_close_timeout=timedelta(seconds=30)` / `RetryPolicy(maximum_attempts=3)` for graph assembly, `start_to_close_timeout=timedelta(seconds=60)` / `RetryPolicy(maximum_attempts=3)` for delivery. Content-generation activities were threaded through `worker_config.resolve_dispatch(...)` in the v2 routing work, but these two infra paths were deliberately left hardcoded: they're not part of the content-generation surface, and forwarding the dispatch resolver here re-introduces the same config-read-on-workflow-runtime concern that motivated bypassing `WorkflowExecutor.execute_child_workflow` from inside workflows.
-
-Want: a config-driven path that lets operators tune these two activities without code changes. Open design questions:
-
-- Where the config lives — a dedicated `[temporal.infrastructure_activity_options]` block, or extend `[temporal.queue_options]` with per-activity baseline overrides for infra activities specifically?
-- How to keep it replay-deterministic — same constraint as `resolve_dispatch`: any `get_config()` read at workflow runtime drifts on replay after a config edit. Probably depends on the search-attribute / Worker Versioning answer in the "Replay-determinism" section above landing first.
-
-Out of scope until: an operator hits an actual timeout/retry mismatch on graph assembly or delivery. Today's hardcoded values are conservative.
-
----
-
-## Real-cluster validation gaps
-
-**Source:** [`../temporal-primitives/02-id-and-naming-plan.md`](../temporal-primitives/02-id-and-naming-plan.md) §"Known follow-ups (deferred)" under Phase 6.
-
-- Hard-fail path against a real Temporal cluster — unit suite covers the contract via mocked clients; run `/temporal-e2e-validate` once a real-cluster credential is available.
-- `[temporal.search_attributes].enabled = false` end-to-end path on a real cluster — covered by unit tests + propagation-by-construction; deferred for explicit e2e verification.
-
----
-
-## Enterprise-readiness roadmap (Phases 1–5 of `00-enterprise-readiness-analysis.md`)
-
-Everything beyond Phase 0 in [`00-enterprise-readiness-analysis.md`](00-enterprise-readiness-analysis.md) is deferred-by-design and lives there with full context. Not duplicated here. Headline items:
-
-- Phase 1 — Security baseline (mTLS, OAuth/OIDC, envelope encryption, PII redaction).
-- Phase 2 — Observability (OpenTelemetry, metrics exporter, structured audit log).
-- Phase 3 — Multi-tenant admission control + quotas.
-- Phase 4 — DR/BCP + rolling-deployment guidance.
-- Phase 5 — Productization polish (tuning_mode resolution, sandbox passthrough config, rate-limit semantics).
diff --git a/wip/temporal-primitives/00-temporal-id-primitives.md b/wip/temporal-primitives/00-temporal-id-primitives.md
deleted file mode 100644
index 76d8d7aa0..000000000
--- a/wip/temporal-primitives/00-temporal-id-primitives.md
+++ /dev/null
@@ -1,260 +0,0 @@
-# Temporal Identifiers, Names, and UI Enrichment — A Reference
-
-## Purpose
-
-This is a **read-only reference** of every identifier, name, and UI-enrichment field that Temporal exposes — what is *required* to be unique, what is *required* to be deterministic, what shows up in the Temporal Web UI, and what is just decoration. It is the input to the next session where we redesign Pipelex's workflow/activity naming model.
-
-It deliberately does **not** propose a Pipelex design. It only collects the primitives we get to choose from.
-
-Sources: the bundled `temporal-developer` skill (`references/python/*.md`, `references/core/*.md`) and the official docs at <https://docs.temporal.io>.
-
----
-
-## 1. The full inventory of identifiers and names
-
-Temporal distinguishes between two very different things in every layer:
-
-- **An ID** — a *runtime* identifier of one *instance* of something (one execution, one activity invocation). Always scoped to a namespace / workflow / task queue. Has hard uniqueness rules.
-- **A Type / Name** — a *static* identifier of *what kind of thing* it is (which workflow class, which activity function). Maps to code. Has no per-instance uniqueness rule.
-
-Get those two confused and the design will be wrong before it starts. Pipelex currently conflates them in several places (see "Current Pipelex pain points" below).
-
-### 1.1. Namespace
-
-- Top-level tenant boundary on the Temporal cluster.
-- Workflow IDs are unique *within a namespace*. The same workflow ID can be reused in a different namespace.
-- Shown in the Web UI as the namespace selector / breadcrumb.
-- Not something Pipelex picks per call; it is cluster-config-level.
-
-### 1.2. Workflow ID
-
-- A **user-supplied string**, passed as `id=` to `client.start_workflow` / `client.execute_workflow` / `workflow.execute_child_workflow`.
-- **Uniqueness rule.** Unique within `(namespace, set of currently-open workflows)`. Reuse of an ID for a *new* execution is governed by `WorkflowIDReusePolicy` (`ALLOW_DUPLICATE`, `ALLOW_DUPLICATE_FAILED_ONLY`, `REJECT_DUPLICATE`, `TERMINATE_IF_RUNNING`).
-- **Reuse via continue-as-new / retry / cron.** Same Workflow ID, new Run ID. The chain is the "Workflow Execution Chain".
-- **Required?** Yes — no SDK-generated default. You must pass one. (Conventional samples use `str(uuid.uuid4())`.)
-- **Determinism rule for child workflows.** A child workflow ID chosen *from inside* a parent's workflow code must be replay-safe → derive it from parent IDs (e.g. `f"{workflow.info().workflow_id}-child-{n}"`) or use `workflow.uuid4()`. **Never** `uuid.uuid4()` from stdlib.
-- **Dashboard visibility.** Yes — it is the primary clickable identifier of an execution in every list and detail view. Searchable. Filterable.
-- **Use as.** The thing humans grep for. The thing oncall pastes into the dashboard. The thing your own UI links to.
-
-### 1.3. Run ID
-
-- A **server-assigned UUID**, one per individual run inside a Workflow Execution Chain.
-- **Uniqueness rule.** Globally unique. You do not control it; you read it from `workflow.info().run_id` or the start handle.
-- **Required?** No — server generates it.
-- **Dashboard visibility.** Yes — shown alongside Workflow ID; you can drill into a specific run. Most lists show only the latest run for a given Workflow ID, with a link to "history" for prior runs.
-- **Use as.** The disambiguator across continue-as-new / retry / cron. Useful as a key when you need per-run worker-side state (this is what the current `_seen_activity_ids` LRU keys on, for good reason).
-
-### 1.4. Workflow Type (a.k.a. Workflow Name)
-
-- **A static string**, registered with the worker. Defaults to the workflow class name; overridable via `@workflow.defn(name="my_workflow_type")`.
-- **Uniqueness rule.** Must be **registered on every worker that polls a given task queue**. All workers on a queue must register the same set of workflow types (one exception: Worker Versioning during upgrades). No per-execution uniqueness — this is the *kind*, not the *instance*.
-- **Required?** Yes — implicit (class name) or explicit.
-- **Dashboard visibility.** Yes — shown as the **"Workflow Type"** column in every list view, separate from Workflow ID. This is what an operator scans to recognise "what kind of pipeline is this".
-- **Why it matters for us.** Today Pipelex registers a small fixed set (`wf_pipe_router`, `wf_pipe_run`, …) so every row looks the same. A redesign could either (a) register more workflow types — one per pipe code, or per family — or (b) keep the registered set small and lean on **search attributes / memo / summary** to surface the pipe code. Both are valid; the trade-off is registration cost vs filterability of the type column itself.
-- **Versioning.** Renaming a workflow type is **incompatible** with in-flight executions of the old name. The recommended pattern for major changes is to register `OrderWorkflowV2` alongside `OrderWorkflow`, not to mutate the existing type.
-
-### 1.5. Workflow Execution
-
-- Not an identifier itself — the *concept* of "one run", uniquely keyed by `(namespace, workflow_id, run_id)`.
-- Every API call into the cluster (signal, query, cancel, terminate, describe) targets a Workflow Execution by `(workflow_id, [run_id])`. If `run_id` is omitted, the cluster operates on the latest run of that chain.
-
-### 1.6. Activity ID
-
-- A **per-invocation string** identifying *one* call to `workflow.execute_activity(...)`. Can be system-generated or supplied by the workflow.
-- **Uniqueness rule.** "Unique among the **open** Activity Executions of a Workflow Run." This is the rule that the current Pipelex bug violates. Once an activity with a given id has completed (or failed terminally), the id can be reused for a fresh activity *within the same workflow run* — but in practice nobody designs for reuse; just give every activity a distinct id.
-- **Required?** No — if you pass nothing, the Python SDK generates one (sequential integer string scoped to the workflow run; effectively `"1"`, `"2"`, …). **This is the easy correct default** and is what most user code does.
-- **Determinism rule.** Whatever you pass *from inside* workflow code must be replay-safe. Safe sources: `workflow.info().workflow_id`, `workflow.uuid4()`, a workflow-local counter incremented in workflow code (replays produce identical counter values because the code path is identical). Unsafe sources: stdlib `uuid.uuid4()`, `time.time()`, worker-singleton counters, anything that reads outside state.
-- **Dashboard visibility.** Yes — shown in the workflow's **Event History** view, on each `ActivityTaskScheduled` event. Not a top-level list column, so its naming matters less than Workflow ID. It is mostly useful (a) when you need to correlate logs / metrics back to a specific call, or (b) when you cancel a specific in-flight activity via its id.
-- **Custom value: useful when.** You want logs to read `activity_id=craft-text-for-section-3` rather than `activity_id=7`. Otherwise: don't bother, take the default.
-
-### 1.7. Activity Type (a.k.a. Activity Name)
-
-- **A static string**, the registered name of the activity function. Defaults to the Python function name; overridable via `@activity.defn(name="my_activity_type")`.
-- **Uniqueness rule.** Must be registered on every worker polling the relevant task queue. Same rule as Workflow Type. No per-call uniqueness.
-- **Required?** Yes — implicit (function name) or explicit.
-- **Dashboard visibility.** Yes — shown in Event History on `ActivityTaskScheduled` events, next to the Activity ID. This is what tells an operator "this was an LLM call" vs "this was an OCR call". `act_llm_gen_text` is good. A generic `craft` is bad.
-- **Use as.** The semantic label for *what kind of work* happened. Pipelex's current `act_*` names are already reasonable; the bug is at the *id* layer, not here.
-
-### 1.8. Task Queue
-
-- A **named queue** that workers poll for tasks. Specified at `start_workflow` time (workflow tasks) and optionally per-activity (activity tasks default to the parent workflow's queue).
-- **Uniqueness rule.** No uniqueness across executions — a task queue is a *channel*, many workflows on the same queue is the normal case. The constraint is that every worker polling the same task queue must register an identical set of workflow types + activity types (modulo Worker Versioning).
-- **Dashboard visibility.** Yes — shown per-execution in the detail view; you can list workflows by task queue.
-- **Use as.** Routing. Throttling (server-side rate limits apply per task queue). Isolation of worker fleets (e.g. one task queue for GPU activities, one for cheap ones — this is exactly the Pipelex per-activity routing work that recently landed).
-- **Naming.** Kebab-case strings, stable across deploys. Naming is purely operational, not for end-user observability.
-
-### 1.9. Worker
-
-- A process polling one or more task queues.
-- **No formal "Worker ID"** in the user-visible model. Workers identify themselves by `(task_queue, build_id)` for the Worker Versioning system, and by `identity` (a free-form string, typically `pid@host`) for diagnostics.
-- **Dashboard visibility.** Indirect — the dashboard shows workers polling each task queue, with their `identity` and `build_id`, on the task queue detail page.
-
----
-
-## 2. Determinism cheat-sheet for inside-workflow id generation
-
-When workflow code itself needs to *pick* an id (for a child workflow, for an activity, for anything else), it must be **deterministic across replay**. The same code, replayed, must produce the same id.
-
-| Need | Use | Do NOT use |
-|---|---|---|
-| Unique-per-call disambiguator | `workflow.uuid4()` | `uuid.uuid4()` from stdlib (sandbox forbids; also non-deterministic) |
-| Sequence / counter | Plain Python `int` incremented in workflow code (the *code path* is deterministic, so the counter is too) | A counter living on the worker-singleton instance |
-| Derived from parent | `workflow.info().workflow_id`, `workflow.info().run_id` | `os.getpid()`, `socket.gethostname()`, env vars |
-| Current time component | `workflow.now()` (note: time progresses *in the workflow* — same value on replay) | `datetime.now()`, `time.time()` |
-| Randomness | `workflow.random()` | `random.*` from stdlib |
-
-**Key consequence for Pipelex.** The current LRU on `ContentGeneratorInWorkflow` is a worker-singleton — that's why it has to be keyed by `(workflow_id, run_id)` and gated on `is_replaying()`. Both of those complications **disappear** if the disambiguator lives in workflow-local state (a counter on the workflow class, or `workflow.uuid4()` per call). The singleton survives only because the current design accidentally requires it.
-
----
-
-## 3. Enrichment primitives — observability without touching ids
-
-Temporal provides several fields that **do not affect ids or routing** but show up in the Web UI and are searchable / filterable. These are the right place to put "operator-readable context" instead of stuffing it into the Workflow ID.
-
-### 3.1. Static Summary
-
-- Set at workflow start: `client.start_workflow(..., static_summary="Order #12345 — expedited shipping")`.
-- **Limit:** 200 bytes, single-line, Markdown (no images / HTML / scripts).
-- **UI:** Appears in the **Workflow list view**, alongside Workflow ID and Workflow Type. This is the column an operator skims to know "what is this run *about*".
-- **Pipelex fit.** Perfect for the pipe code / human-readable label that today is jammed into the Workflow ID.
-
-### 3.2. Static Details
-
-- Same call as static_summary: `client.start_workflow(..., static_details="...")`.
-- **Limit:** 20 KB, multi-line, Markdown.
-- **UI:** Shown on the workflow's detail page, not in the list. Good for the structured run context (inputs hash, user, session, etc.).
-
-### 3.3. Current Details
-
-- Mutable from inside workflow code: `workflow.set_current_details("Processing chunk 17/42")`.
-- **Replay-safe:** can be set multiple times across the run.
-- **UI:** Overlays the static details on the detail page; reflects latest state.
-- **Pipelex fit.** Phase / step indicator for a pipeline as it progresses through controllers. Costs nothing.
-
-### 3.4. Per-Activity Summary
-
-- Set per-call: `workflow.execute_activity(act_llm_gen_text, ..., summary="Draft section 3, model=gpt-5")`.
-- **Limit:** 200 bytes.
-- **UI:** Rendered in **purple text** next to the corresponding `ActivityTaskScheduled` event in the Event History view. Visible without expanding the event.
-- **Pipelex fit.** This is the *correct* place to put per-call context like "craft-text for `summary_paragraph`" — not in the Activity ID. The id becomes the SDK default integer; the summary carries the meaning.
-
-### 3.5. Per-Timer Summary
-
-- Set per-call: `workflow.sleep(timedelta(minutes=5), summary="Wait for upstream batch")`.
-- **Limit:** 200 bytes.
-- **UI:** Same purple-text rendering on `TimerStarted` events.
-
-### 3.6. Search Attributes (typed, indexed, filterable)
-
-- Set at start *or* upserted from inside the workflow.
-- **Indexed:** these are the only fields you can query with `list_workflows("PipeCode = 'translate_doc'")`.
-- **Schema:** custom attributes must be registered on the cluster ahead of time (per-namespace, via `tctl`/`temporal operator search-attribute create`). Built-in ones (`WorkflowType`, `WorkflowId`, `StartTime`, `ExecutionStatus`, `TaskQueue`, …) come for free.
-- **Types:** `Keyword`, `Text`, `Int`, `Double`, `Bool`, `Datetime`, plus `KeywordList`.
-- **UI:** Shown as filterable columns in the list view; users can build custom views per-namespace.
-- **Pipelex fit.** The *queryable* slice of the operator story: `PipeCode`, `SessionId`, `UserId`, `RootPipelineId`. Pair with summary/details for the human-readable slice.
-
-### 3.7. Memo
-
-- Set at start: `client.start_workflow(..., memo={"customer_name": "Acme", "trace_url": "https://..."})`.
-- **NOT indexed / searchable** — arbitrary metadata, returned with the workflow handle and visible in the UI but not filterable.
-- **Readable from workflow code** via `workflow.memo_value(key, type_hint=...)`.
-- **Pipelex fit.** Larger or sensitive context that doesn't need filtering (e.g. dispatch resolution trace pointer, library crate version).
-
----
-
-## 4. What the Temporal Web UI actually shows you
-
-Approximate column layout in the workflow **list view** (default; users can customise):
-
-| Column | Source |
-|---|---|
-| Status | Cluster-managed (`Running`, `Completed`, `Failed`, …) |
-| Workflow ID | The `id=` you passed at start |
-| Run ID | Server-generated, latest of the chain |
-| Workflow Type | The `@workflow.defn(name=...)` (or class name) |
-| Task Queue | The `task_queue=` you passed at start |
-| Start Time | Cluster |
-| End Time | Cluster |
-| **Summary** | `static_summary` (if set) — purple |
-| Custom search attributes | Whatever you registered on the namespace |
-
-In the **detail view** for one execution:
-
-- Header: Workflow ID, Run ID, Workflow Type, Task Queue, Status, Start/End, Summary, Details (static + current).
-- Event History: each `ActivityTaskScheduled` shows Activity ID, Activity Type, Task Queue, attempt number, and (if set) the per-activity Summary in purple. Timers show similarly.
-- Pending Activities panel: live view of currently-open activities (with their Activity ID — relevant for cancelling a specific one).
-
-What is **not** in the UI by default:
-
-- Memo values (you can see them in the "Memo" tab on the detail page, but they don't filter lists).
-- The internal counter Temporal uses to auto-assign default Activity IDs (you just see `"1"`, `"2"`, … on each event).
-
----
-
-## 5. Naming best practices distilled
-
-### Workflow ID
-
-- **Readable** is good but **stable + unique** matters more.
-- Use a deterministic, business-meaningful prefix when possible: `order-{order_id}`, `pipeline-{pipe_code}-{session}-{shortuuid}`.
-- Avoid embedding things that change between retries (timestamps fine if you want chain-level temporal ordering; *attempt numbers* not fine).
-- Avoid embedding things that a human cannot copy-paste (spaces, special chars).
-- If you need pure uniqueness with zero semantics, `str(uuid.uuid4())` at the **client** is fine. Inside workflow code, use `workflow.uuid4()`.
-
-### Workflow Type
-
-- One per *kind* of orchestration. Don't dynamically generate; the worker has to register them statically.
-- If you want per-pipe filterability without registering 200 workflow types, use a **search attribute** instead.
-
-### Activity ID
-
-- **Default to letting the SDK generate it** (omit the parameter). Sequential integers per workflow run, guaranteed unique, no thought required.
-- Customize **only** when you want a specific log/metric anchor or when you'll cancel by id.
-- If you do customize, derive from workflow-local state (counter or `workflow.uuid4()`), never from worker-singleton state.
-
-### Activity Type
-
-- One per *kind* of side effect. Stable, descriptive, registered on the worker (`act_llm_gen_text`, `act_extract_pages`).
-- Don't embed parameters in the type; put parameters in the per-activity summary or in structured logs.
-
-### Task Queue
-
-- Stable, operational names. One per worker fleet / capacity class.
-- Per-activity overrides for routing-by-capability (already in place in Pipelex).
-
-### Summary / details / search attributes
-
-- **Use them.** They are free observability. Pipelex currently uses zero of them.
-- Decide for each piece of context: do operators *filter* on this (→ search attribute) or do they *read* this (→ summary / details)?
-
----
-
-## 6. Mapping back to the Pipelex pain points
-
-This section is descriptive, not prescriptive — it just lines up the primitives above with the issues catalogued in `workflow-and-activity-ids.md`. The *design* (which primitive to use for what) is for the next session.
-
-| Pipelex symptom | Primitive(s) that can address it |
-|---|---|
-| `activity_id = "craft-text"` collides on second call | (a) Omit the param → SDK default integers. (b) Counter on `ContentGeneratorInWorkflow` *not* the worker singleton — per-execution counter passed through workflow state. (c) `workflow.uuid4()` per call. |
-| `wfid` parameter conflates "child workflow id base" and "activity id" | Two different primitives; split the parameter at the protocol layer. The activity-side concern can be dropped entirely if Pipelex stops customizing activity_id (option (a) above). |
-| Workflow IDs like `EdgdJ-HR5fd-TemporalPipeRun-pipe-router` are uninformative | Move semantic context to `static_summary` (display) and search attributes (filtering). The Workflow ID can stay opaque-and-unique. |
-| Only `wf_pipe_router` / `wf_pipe_run` show up in the Workflow Type column | Either (a) register more workflow types (one per pipe family) or (b) keep the small set and surface pipe-code via `PipeCode` search attribute. Either works. |
-| LRU + `is_replaying()` + `(workflow_id, run_id)` keying in `_seen_activity_ids` | All of this exists *only* because the disambiguator lives on a worker singleton. Move the disambiguator into workflow-local state → all this machinery becomes deletable. |
-| Operators cannot trace a row in our own webapp back to a Temporal execution | Pass the Pipelex run id as Workflow ID (or store both via memo / search attribute). The current "5-char prefix of session + 5-char prefix of shortuuid + class name" loses information for no benefit. |
-
----
-
-## 7. Open questions for the design session
-
-These are the choices the next session has to make, with the primitives above as the menu:
-
-1. **Workflow ID shape.** Pure UUID? `{pipe_code}-{session_short}-{uuid}`? Something else? Determinism is a constraint only for *child* workflow ids; top-level ids are set client-side and can use anything.
-2. **Child workflow id derivation.** `{parent_workflow_id}-child-{counter}` vs `{parent_workflow_id}-{workflow.uuid4()}` vs `workflow.uuid4()` alone.
-3. **Activity id policy.** Default integers (recommended) vs custom strings. If custom: where does the disambiguator live (workflow-local counter, `workflow.uuid4()`, both)?
-4. **Workflow Type granularity.** One per pipe code (registered dynamically — adds complexity) vs the current handful plus search attributes.
-5. **Summary / details strategy.** What goes in `static_summary` (operator skim), what goes in `static_details` (structured context), what goes in `current_details` (in-flight progress).
-6. **Search attribute schema.** Which custom attributes do we register on the namespace? Minimum likely set: `PipeCode` (Keyword), `SessionId` (Keyword), `UserId` (Keyword), `RootPipelineId` (Keyword). Anything else?
-7. **Memo contents.** Anything large or sensitive that we want round-tripped with the execution but not indexed (e.g. dispatch resolution debug pointer)?
-8. **`wfid` parameter rename.** Once activity-id concerns are off this parameter, what does it represent? Probably "base for the workflow id" — name it accordingly (`workflow_id_base`? `caller_id`?).
-
-The TDD gate in `tests/unit/pipelex/temporal/test_default_activity_id_collision_bug.py` must turn green as a side effect of whichever activity-id policy is picked.
diff --git a/wip/temporal-primitives/02-id-and-naming-plan.md b/wip/temporal-primitives/02-id-and-naming-plan.md
deleted file mode 100644
index 53a90984f..000000000
--- a/wip/temporal-primitives/02-id-and-naming-plan.md
+++ /dev/null
@@ -1,644 +0,0 @@
-# Temporal IDs and Naming — Implementation Plan
-
-## Status
-
-**Phases 1–6 shipped on `feature/Temporal-ids`.** Latest: commit `c89674f5` (Phase 6 hard-fail worker boot + configurable search attributes + setup CLI), with follow-up cleanup in `ac8e2335` and doc sync in `5afe850d`. `make agent-check` clean, `make agent-test` green. Phase-by-phase checkpoints below capture handoff state and decisions.
-
-The only remaining temporal-primitives work captured in this directory is `03-temporal-error-handling-revamp.md` — a deferred proposal to make `WorkflowExecutionError` inherit from `temporalio.exceptions.ApplicationError`, dropping the Worker-side `workflow_failure_exception_types` registration.
-
-Original frame: implements `01-id-and-naming-design.md` against the failing TDD gate in `tests/unit/pipelex/temporal/test_default_activity_id_collision_bug.py`. The problem statement (`workflow-and-activity-ids.md`) and pre-checkpoint plan (`id-and-naming-plan.md`) are archived under `wip/archive/`.
-
-## Cold-start orientation
-
-A fresh session picking this up should read in this order:
-
-1. `wip/archive/workflow-and-activity-ids.md` — the problem statement and the (now-green) TDD gate that framed this work.
-2. `wip/temporal-primitives/00-temporal-id-primitives.md` — what Temporal's identifier and observability surface actually offers.
-3. `wip/temporal-primitives/01-id-and-naming-design.md` — the authoritative spec. If anything in this plan conflicts with the design doc, the design doc wins.
-4. This file — the sequencing of work and the per-phase done-when criteria.
-
-### Key code anchors
-
-The redesign rotates around these load-bearing locations. Open them before touching anything:
-
-- `pipelex/temporal/temporal_manager.py:95-110` — current top-level workflow_id construction; Phase 1 replaces it.
-- `pipelex/temporal/tprl/workflow_caller.py:84-87` — `make_workflow_id` delegator; Phase 1 simplifies it.
-- `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py:48-109` — the LRU + `_record_activity_id` machinery deleted in Phase 2.
-- `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py:111-528` — every `make_*` method whose `wfid` parameter and `activity_id=` argument are rewritten in Phase 2.
-- `pipelex/cogt/content_generation/content_generator_protocol.py` — `wfid` on every method; dropped in Phase 2.
-- `pipelex/temporal/tprl_pipe/wf_pipe_run.py:46` — hardcoded `f"{workflow_id}-pipe-router"` child id; separator flips to `/` in Phase 3.
-- `pipelex/temporal/tprl_pipe/temporal_pipe_router.py:55-87` — child + top dispatch branches rewritten in Phase 3.
-- `pipelex/temporal/tprl_pipe/temporal_pipe_run.py:43-65, 73-101` — top-level dispatch rewritten in Phase 3.
-- `pipelex/pipe_run/pipe_run_protocol.py`, `pipe_router_protocol.py` — non-Temporal protocols still carrying `wfid`; dropped in Phase 3.
-- `pipelex/pipelex.py:347` — worker-singleton instantiation of `ContentGeneratorInWorkflow`. Why this matters: the LRU exists *because* the disambiguator lived on this singleton; once the SDK assigns activity_ids, the singleton becomes plain stateless code and the LRU goes away.
-- `pipelex/pipeline/pipeline_factory.py:17` — `make_pipeline_run_id` (UUID, unchanged; we just stop ignoring its output).
-- `pipelex/pipeline/job_metadata.py:43` — `JobMetadata.pipeline_run_id` (the canonical identity, unchanged).
-- `tests/unit/pipelex/temporal/test_default_activity_id_collision_bug.py` — the TDD gate. Run it on entry to confirm it is red; it must be green after Phase 2.
-
-### The fact that unblocks the protocol cleanup
-
-A grep at design time confirmed: **no production code passes a non-`None` `wfid`**. Every `wfid=` call site is in `tests/`. That is the empirical reason it is safe to drop the parameter from `PipeRunProtocol`, `PipeRouterProtocol`, and `ContentGeneratorProtocol` without a deprecation cycle. Re-run the grep if time has passed:
-
-```bash
-grep -rn "wfid=" pipelex/ | grep -v "wfid=None" | grep -v "wfid: str"
-```
-
-If this returns anything, stop and reassess before touching protocols.
-
-### Verification commands
-
-The "Done when" criteria in each phase reference these checks:
-
-```bash
-# Run the failing TDD gate (red on entry; green after Phase 2)
-.venv/bin/pytest -v tests/unit/pipelex/temporal/test_default_activity_id_collision_bug.py
-
-# Phase 2 done: no wfid in the activity layer
-grep -rn "wfid" pipelex/cogt/ pipelex/temporal/tprl_content_generation/
-
-# Phase 3 done: no wfid anywhere in pipelex/
-grep -rn "wfid" pipelex/
-
-# Quality gates (every phase)
-make agent-check
-make agent-test
-```
-
-### Tooling
-
-- `make agent-check` — runs ruff (fix-unused-imports, lint, format), pyright, mypy, plxt. Silent on success, full output on failure.
-- `make agent-test` — runs the test suite the same way. Use this, not `make test`.
-- `/temporal-e2e-validate` — slash-command skill (declared in the agent's skill list) that validates Temporal distributed execution against a real server. Use it once Phase 3 lands to confirm the new identity model end-to-end.
-- Integration tests support `--temporal-server local|testing|<profile>` — see CLAUDE.md "Temporal Integration Test Options."
-
-## How to use this plan
-
-Four phases, each independently mergeable. Every phase ends with `make agent-check` and `make agent-test` green. Checkpoints between phases are explicit handoff points: the next session can pick up cold by reading this doc + the checkpoint notes filled in by the previous session.
-
-The phase ordering is chosen so that the bug fix (Phase 2) lands as early as possible: foundations first, then the activity-layer rewrite that flips the TDD gate green, then the workflow-layer rewrite, then deployment & docs.
-
-**Parallelism.** Phase 1 must land first (helpers + extended `WorkflowExecutor` surface). Phases 2 and 3 are formally independent — Phase 2 touches `tprl_content_generation/*` and `cogt/content_generation/*` exclusively; Phase 3 touches `tprl_pipe/*` and `pipe_run/*` exclusively. They can run in parallel branches after Phase 1 merges. Phase 4 waits for both so the CHANGELOG is final. **Lane structure: Phase 1 → (Phase 2 ∥ Phase 3) → Phase 4.**
-
-Each phase section answers the same four questions: **What lands**, **Files touched**, **Tests**, **Done when**. The change set in the design doc is the authoritative spec for every file change — this plan only sequences the work.
-
----
-
-## Phase 1 — Foundations (additive only)
-
-**What lands.** A new `observability.py` helper module, a renamed/simplified `make_top_workflow_id` on `TemporalManager`, and additive `search_attributes` / `static_summary` / `static_details` / `memo` parameters on every `WorkflowExecutor` workflow-start method (top-level **and** child). No call site uses the new infrastructure yet. No behavior changes for end users.
-
-**Files touched.**
-
-- `pipelex/temporal/tprl/observability.py` (new) — five pure-function helpers:
- - `build_search_attributes(pipe_job: PipeJob) -> Mapping[str, list[str]]`
- - `build_search_attributes_for_child(child_pipe_job: PipeJob, parent_search_attrs: Mapping[str, list[str]]) -> Mapping[str, list[str]]`
- - `build_static_summary(pipe: PipeBase) -> str` — `pipe.description` is required-but-can-be-empty (Pydantic field, not Optional). The "omit when missing" rule is interpreted as "omit the dash-and-tail when `pipe.description == ""`".
- - `build_static_details(pipe_job: PipeJob, library_crate_id: str | None) -> str`
- - `build_activity_summary(method_label: str, job_metadata: JobMetadata, **extras: str) -> str`
-- `pipelex/temporal/temporal_manager.py` — replace `make_top_workflow_id(base_id: str)` with `make_top_workflow_id(pipeline_run_id: str)`. The session-id and random-id truncations are deleted; `self.session_id` stays as an instance field so the search-attribute helper can read it.
-- `pipelex/temporal/tprl/workflow_caller.py` — extend the wrapper's full surface:
- - `WorkflowExecutor.execute_workflow` and `start_workflow` gain optional `search_attributes`, `static_summary`, `static_details`, `memo` parameters that pass through to `client.execute_workflow` / `client.start_workflow`.
- - **`WorkflowExecutor.execute_child_workflow` and `start_child_workflow` gain the same four parameters**, passed through to `workflow.execute_child_workflow` / `workflow.start_child_workflow`. The SDK supports them on both top-level and child variants; Phase 3 needs them on the child path.
- - `make_workflow_id(base_id: str)` is renamed to `make_workflow_id(pipeline_run_id: str)`.
-
-**Tests.**
-
-- `tests/unit/pipelex/temporal/test_observability_helpers.py` (new) — unit tests for every helper, including 200-byte UTF-8 truncation behavior, empty-string `pipe.description`, child-attribute inheritance with PipeCode/DomainCode overridden and the other three inherited.
-- `tests/unit/pipelex/temporal/test_workflow_caller_passthrough.py` (new) — assert that `search_attributes`, `static_summary`, `static_details`, `memo` reach the SDK call. Mock the temporal client / `workflow.execute_child_workflow` and assert `call_args.kwargs.get("search_attributes")` (and the other three) match what `WorkflowExecutor` was given. Covers all four entry points (`execute_workflow`, `start_workflow`, `execute_child_workflow`, `start_child_workflow`).
-- A grep at design time confirmed **no existing test asserts on the old `{session5}-{rand5}-{base_id}` workflow-id shape**. No transitional handling is needed; the only legitimate production caller of `make_top_workflow_id` is `WorkflowExecutor.make_workflow_id`, and that's the renamed-arg change.
-
-**Done when.**
-
-- `make agent-check` clean.
-- `make agent-test` green. The TDD gate test in `test_default_activity_id_collision_bug.py` is still red (expected — Phase 2 fixes it).
-- The new helpers have unit-test coverage for the formats specified in the design doc.
-
-### Checkpoint — end of Phase 1
-
-- **Status.** Implemented on branch `feature/Temporal-config` (uncommitted).
-- **Code state.**
- - `pipelex/temporal/tprl/observability.py` added with the five helpers exactly as planned. Signatures: `build_search_attributes(pipe_job)`, `build_search_attributes_for_child(child_pipe_job, parent_search_attrs)`, `build_static_summary(pipe)`, `build_static_details(pipe_job, library_crate_id)`, `build_activity_summary(method_label, job_metadata, **extras)`. UTF-8 200-byte truncation appends a `…` and decodes with `errors="ignore"` to drop partial multi-byte sequences at the cut.
- - `TemporalManager.make_top_workflow_id` renamed to take `pipeline_run_id: str` and now returns `f"{prefix}{pipeline_run_id}"` — the session/random parts are gone. `self.session_id` still on the instance for the search-attribute helper.
- - `WorkflowExecutor.make_workflow_id(pipeline_run_id: str)` renamed accordingly.
- - `WorkflowExecutor.execute_workflow` / `start_workflow` / `execute_child_workflow` / `start_child_workflow` all gained additive `search_attributes`, `static_summary`, `static_details`, `memo` kwargs, passed through to the underlying SDK call.
- - The two existing call sites in `tprl_pipe/temporal_pipe_run.py` and `tprl_pipe/temporal_pipe_router.py` were updated to use the new `pipeline_run_id=` kwarg name. They still pass `wfid or self.class_name` (a degraded value), which is intentional — Phase 3 threads the real `pipeline_run_id` through.
-- **Transitional state to flag for Phase 3.** Because `make_top_workflow_id` now does `{env_prefix}{pipeline_run_id}` with no session/random suffix, and callers still pass `"TemporalPipeRun"` / `"TemporalPipeRouter"` until Phase 3, top-level workflow IDs are currently the degraded shape `ut-TemporalPipeRun` / `ut-TemporalPipeRouter`. Two pipe runs in a row chain under `ALLOW_DUPLICATE` instead of producing distinct IDs. This is a known-broken intermediate state; Phase 3 fixes it by threading `pipe_job.job_metadata.pipeline_run_id` through.
-- **Tests added.** `tests/unit/pipelex/temporal/test_observability_helpers.py` (11 tests covering all five helpers, UTF-8 truncation at multi-byte boundaries, child-attr inheritance, empty-description path). `tests/unit/pipelex/temporal/test_workflow_caller_passthrough.py` (4 tests — one per executor entry point, asserting all four kwargs reach the SDK).
-- **Quality gates.** `make agent-check` clean (pyright + mypy + ruff + plxt). Full `tests/unit/pipelex/temporal/` targeted run: 192 passed, 2 failed (the expected TDD gate in `test_default_activity_id_collision_bug.py` — still red, fixed by Phase 2).
-- **Handoff notes for Phase 2.** No conftest changes; helpers are pure functions. The TDD gate test asserts `len(set(observed_activity_ids)) == 2` — once Phase 2 stops passing `activity_id=`, both calls produce `kwargs.get("activity_id") is None` and the assertion as written would fail with `set([None, None])`. Phase 2 must rewrite the kept gate test per the plan (rename + assert `kwargs.get("activity_id") is None` and inspect the per-call `summary`).
-
----
-
-## Phase 2 — Activity-layer rewrite (TDD gate green)
-
-**What lands.** The bug fix. `ContentGeneratorInWorkflow` stops customizing `activity_id`, the worker-singleton LRU is deleted, the `wfid` parameter is dropped from `ContentGeneratorProtocol` and every implementation, and every `workflow.execute_activity(...)` call carries a `summary=` derived from the helpers. The TDD gate in `test_default_activity_id_collision_bug.py` flips green naturally.
-
-**Files touched.**
-
-- `pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py`:
- - Delete `_seen_activity_ids`, `_MAX_SEEN_RUNS`, `_record_activity_id`, and every call site of `_record_activity_id`.
- - Drop the `wfid` parameter from every `make_*` method.
- - Drop the `activity_id = wfid or "…"` line and the `activity_id=...` argument from every `workflow.execute_activity(...)` call.
- - Add `summary=build_activity_summary(...)` per the format table in the design doc.
-- `pipelex/cogt/content_generation/content_generator_protocol.py` — drop `wfid` from every `make_*` method signature.
-- `pipelex/cogt/content_generation/content_generator.py` (direct mode) — drop `wfid` (currently a dead pass-through; direct mode never reads it).
-- `pipelex/cogt/content_generation/content_generator_dry.py` (dry mode) — drop `wfid` (currently a dead pass-through).
-
-**Tests.**
-
-- `tests/unit/pipelex/temporal/test_default_activity_id_collision_bug.py`:
- - **Delete** `test_two_make_llm_text_calls_with_same_explicit_wfid_should_succeed` — its premise (`wfid` as the disambiguator) literally no longer exists after the parameter is dropped; it exercises the same code path as the first case anyway.
- - **Keep and rename** `test_two_make_llm_text_calls_without_wfid_should_succeed` → `test_two_default_activity_calls_in_one_workflow_produce_distinct_activity_ids`. The new name reflects the invariant being guarded (per-call uniqueness via SDK default), not the historic bug.
-- `tests/unit/pipelex/temporal/test_seen_activity_ids_lru.py` — **delete the entire file (101 lines).** The file is wholly about the LRU machinery; once `_seen_activity_ids` / `_MAX_SEEN_RUNS` / `_record_activity_id` are removed, every test in it fails on `AttributeError`. Nothing to salvage.
-- `tests/unit/pipelex/temporal/test_content_generator_in_workflow.py` — every test in this file that asserts on a specific `activity_id` string must be rewritten. Full enumeration (verified by grep at design time):
- - Delete: `test_make_llm_text_threads_explicit_wfid` (line 121), `test_duplicate_wfid_raises_content_generation_error` (line 250), `test_default_wfids_for_image_methods_are_distinct` (line 409), `test_duplicate_check_is_skipped_during_replay` (line 277), `test_activity_id_cache_is_scoped_by_run_id` (line 308) — last two are tests for the deleted LRU short-circuit and cache scoping respectively.
- - Rewrite (replace `activity_id`-string asserts with `kwargs.get("activity_id") is None` and `summary` content asserts):
- - `test_every_dispatch_omits_task_queue_with_empty_routing` (line 100) — drops `activity_id == "craft-text"` assert (line 119).
- - `test_non_llm_text_methods_omit_task_queue_with_empty_routing` (line 146) — drops `activity_id == method_default_id` assert (line 167) plus the parametrized default-id list.
- - `test_make_extract_pages_dispatches_extract_only_when_no_page_views` (line 169) — drops `activity_id == "extract-pages"` assert (line 187).
- - `test_make_extract_pages_image_uri_with_page_views_skips_render_activity` (line 189) — drops `activity_id == "extract-pages"` assert (line 210).
- - `test_make_extract_pages_document_uri_with_page_views_dispatches_two_activities` (line 212) — drops `observed_activity_ids == ["extract-pages", "extract-render-page-views"]` assert (line 244) and the in-loop dispatch-routing-by-activity_id helper (lines 220-225).
- - Add: `test_make_llm_text_omits_activity_id_and_sets_summary` (and one per method) — asserts `mock_execute.call_args.kwargs.get("activity_id") is None` and `kwargs.get("summary")` matches the formatted helper output for that method.
-- Any other test in `tests/unit/` / `tests/integration/` that passes `wfid=` to a `make_*` content-generator method is updated to remove the kwarg.
-
-**Done when.**
-
-- `make agent-check` clean.
-- `make agent-test` green.
-- `test_default_activity_id_collision_bug.py` is green (renamed canonical-gate test exercises the SDK-default integer assertion).
-- `tests/unit/pipelex/temporal/test_seen_activity_ids_lru.py` is **deleted from disk** (not commented out).
-- Grep confirms zero remaining references to `wfid` in `pipelex/cogt/` and `pipelex/temporal/tprl_content_generation/`.
-- Grep confirms zero remaining references to `_seen_activity_ids`, `_MAX_SEEN_RUNS`, or `_record_activity_id` anywhere in `pipelex/` or `tests/`.
-- Manual smoke (optional, recommended): run a multi-step pipe via the `temporal-e2e-validate` skill and confirm in the Temporal dashboard's Event History that activity ids are now `"1"`, `"2"`, … with purple-text per-activity summaries.
-
-### Checkpoint — end of Phase 2
-
-- **Status.** Implemented on branch `feature/Temporal-config` (uncommitted).
-- **TDD gate.** Green. Renamed canonical-gate test: `tests/unit/pipelex/temporal/test_default_activity_id_collision_bug.py::TestDefaultActivityIdCollisionBug::test_two_default_activity_calls_in_one_workflow_produce_distinct_activity_ids`. Asserts `kwargs.get("activity_id") is None` on every call — Pipelex never customizes `activity_id`, the SDK assigns deterministic integers per workflow run. Targeted run (`tests/unit/pipelex/temporal/ tests/unit/pipelex/cogt/`): 692 passed.
-- **Code state.**
- - `ContentGeneratorInWorkflow` rewritten: `_seen_activity_ids`, `_MAX_SEEN_RUNS`, `_record_activity_id` deleted; `wfid` parameter dropped from every `make_*` method; every `workflow.execute_activity(...)` call no longer passes `activity_id=` and now carries `summary=build_activity_summary(...)`. The per-method summary formats are: `LLM text · pipe={code} · model={handle}`, `LLM object · pipe={code} · class={class_name}`, `LLM object list · pipe={code} · class={class_name}`, `Img gen 1× · pipe={code} · model={handle}`, `Img gen N× · pipe={code} · model={handle} · n={count}`, `Templated text · pipe={code}`, `Render page views · pipe={code}`, `Extract pages · pipe={code} · handle={extract_handle}`, `Render page views (extract) · pipe={code}` for the render step inside `make_extract_pages`. The `extract_activity_id` / `render_activity_id` / `base_id` locals were also removed.
- - `wfid` dropped from `ContentGeneratorProtocol` and both other implementations (`pipelex/cogt/content_generation/content_generator.py`, `pipelex/cogt/content_generation/content_generator_dry.py`).
- - Grep confirms zero remaining `wfid` references in `pipelex/cogt/` and `pipelex/temporal/tprl_content_generation/`. Zero references to `_seen_activity_ids` / `_MAX_SEEN_RUNS` / `_record_activity_id` anywhere in `pipelex/` or `tests/`.
-- **Tests.**
- - **Deleted from disk:** `tests/unit/pipelex/temporal/test_seen_activity_ids_lru.py` (entire 101-line file).
- - **Rewritten:** `tests/unit/pipelex/temporal/test_default_activity_id_collision_bug.py` reduced to the single canonical-gate test (two parallel tests collapsed; renamed; assertion flipped from "set of two distinct strings" to "every call has `activity_id is None`").
- - **Rewritten:** `tests/unit/pipelex/temporal/test_content_generator_in_workflow.py` — five tests deleted (LRU short-circuit, run-id cache scoping, `threads_explicit_wfid`, `duplicate_wfid_raises`, `default_wfids_for_image_methods_are_distinct`); remaining `activity_id`-string asserts swapped for `activity_id is None` + per-method `summary` strings checked against the formatter output.
- - **Updated integration test:** `tests/integration/pipelex/temporal/tracing/test_split_worker_extract_pages.py::test_two_activity_branch_dispatches_with_distinct_activity_ids` — no longer pins `"extract-pages"` / `"extract-render-page-views"`; now asserts (a) the two activities are scheduled in order and (b) their SDK-assigned activity_ids are distinct.
-- **Quality gates.** `make agent-check` clean (pyright + mypy + ruff + plxt).
-- **Replay-safety note for future reviewers.** The LRU + `is_replaying()` short-circuit was deleted *because* the disambiguator is no longer worker-singleton state. Any future change that reintroduces worker-singleton state into the activity-dispatch path breaks the determinism guarantee — push back on it in review.
-- **Handoff notes for Phase 3.**
- - The `pipe_run/*` and `pipe_router/*` protocols still carry `wfid` as a dead pass-through (the activity layer no longer reads it). Phase 3 drops them.
- - `temporal_pipe_run.py` and `temporal_pipe_router.py` still pass `wfid or self.class_name` to `make_workflow_id(pipeline_run_id=...)` — i.e. workflow IDs are currently shaped `ut-TemporalPipeRun` (degraded). Phase 3 threads the real `pipe_job.job_metadata.pipeline_run_id` through.
- - `wf_pipe_run.py:46` still uses the `{workflow_id}-pipe-router` separator. Phase 3 flips this to `/` (slash). Note that `wf_pipe_run.py` uses **raw** `workflow.execute_child_workflow(...)` directly — not the `WorkflowExecutor.execute_child_workflow` wrapper — so adding `search_attributes=` there is a separate touch from `temporal_pipe_router.py`.
-
----
-
-## Phase 3 — Workflow-layer rewrite + protocol cleanup
-
-**What lands.** Workflow IDs switch to `{env_prefix}{pipeline_run_id}`. Child workflow IDs switch to slash-separated paths. Search attributes and static summary land on every workflow start. `wfid` is dropped from `PipeRunProtocol`, `PipeRouterProtocol`, and the remaining implementations. Tests assert the new identity model.
-
-**Files touched.**
-
-- `pipelex/temporal/tprl_pipe/temporal_pipe_run.py`:
- - Drop the `wfid` parameter from `run(...)` and `start(...)`.
- - `workflow_id` is built from `pipe_job.job_metadata.pipeline_run_id` via the renamed manager method.
- - Pass `search_attributes`, `static_summary`, `static_details` to `executor.execute_workflow` / `start_workflow` using the helpers.
-- `pipelex/temporal/tprl_pipe/temporal_pipe_router.py`:
- - Drop the `wfid` parameter from `_run_pipe_job(...)`.
- - Top-level branch mirrors `temporal_pipe_run.py`.
- - Child branch (inside a workflow): `child_workflow_id = f"{parent_workflow_id}/{pipe_job.pipe.code}-{str(workflow.uuid4())[:8]}"`. Pass `search_attributes` updated for the child via `build_search_attributes_for_child`. Routes through `executor.execute_child_workflow(...)` (the `WorkflowExecutor` wrapper extended in Phase 1).
- - **No defensive `pipe_job.pipe.code or "pipe"` fallback.** `PipeAbstract.code: str` is a required Pydantic field with non-empty syntax validation (`validate_pipe_code_syntax`); the fallback is dead code. If invariants ever change, silently swallowing the violation is worse than crashing loudly.
-- `pipelex/temporal/tprl_pipe/wf_pipe_run.py`:
- - Line 46: switch the separator from `-` to `/`: `id=f"{workflow.info().workflow_id}/pipe-router"`.
- - **NOTE — uses raw `workflow.execute_child_workflow(...)`, not the `WorkflowExecutor` wrapper.** Two child-spawn code paths exist in the codebase: this file's raw API call and `temporal_pipe_router.py`'s wrapper call. Both need the search-attribute kwarg added in this phase; the implementer should not assume a single centralization point. (Unifying the two paths is captured in **Out of scope**.)
- - Pass `search_attributes=` directly to the raw call. Re-use the parent's attributes via `workflow.info().typed_search_attributes` (or read the parent's mapping plumbed via workflow input if simpler) — `PipeCode` and `DomainCode` do not change between `wf_pipe_run` and its `wf_pipe_router` child because the router is just executing the same pipe.
-- `pipelex/pipe_run/pipe_run.py` and `pipe_run_protocol.py` — drop `wfid` from `run(...)` (dead pass-through today).
-- `pipelex/pipe_run/pipe_router.py`, `pipe_router_protocol.py`, `dry_pipe_router.py` — drop `wfid` from `run(...)` / `_run_pipe_job(...)` (dead pass-throughs today; only `TemporalPipeRouter` ever consumed the value).
-- Any remaining call sites of these protocols in tests update to not pass `wfid`.
-
-**Static details "Input" line — settled.** `build_static_details` derives the Input row from `pipe_job.pipe.inputs.specs` keys (already a structured `InputStuffSpecs` on `PipeAbstract`). It is declared once per pipe, stable across runs, and does not grow at runtime. If `pipe.inputs.specs` is empty, the Input row is omitted entirely. Working-memory keys are rejected as a source: they expand mid-run depending on which sub-pipe sets them, and would make the Input row racy and noisy.
-
-**Tests.**
-
-- `tests/unit/pipelex/temporal/test_workflow_id_construction.py` (new) — asserts:
- - Top-level: `{env_prefix}{pipeline_run_id}` for each `RunMode`.
- - Fixed-role child: `{parent}/pipe-router`.
- - Dynamic child: `{parent}/{pipe_code}-{8-hex-chars}`.
- - **Replay determinism:** mock `workflow.uuid4` to return a fixed UUID; assert the dynamic child id is fully determined by `(parent_workflow_id, pipe_job.pipe.code, workflow.uuid4 output)`. This forces the implementer to use `workflow.uuid4()`, not stdlib `uuid.uuid4()` (which Temporal's workflow sandbox forbids).
-- `tests/unit/pipelex/temporal/test_search_attribute_dict_construction.py` (new) — asserts the five-keyed dict from a representative `pipe_job`, plus the child-attribute inheritance / override rule (PipeCode + DomainCode replaced for the child's pipe; PipelineRunId + SessionId + UserId inherited unchanged).
-- A grep at design time confirmed **no existing test asserts on the old `{session5}-{rand5}-{ClassName}` workflow-id shape**; the cross-phase risk listed below for this is already vacated. If a stray assertion is found during implementation, rewrite it.
-- Integration tests under `tests/integration/pipelex/temporal/` continue to pass without modification (they don't inspect the workflow_id shape); if any does, it's rewritten.
-- Run the `temporal-e2e-validate` skill end-to-end as a final cross-check.
-
-**Done when.**
-
-- `make agent-check` clean.
-- `make agent-test` green.
-- Grep confirms zero remaining `wfid` references in `pipelex/`.
-- A manual run in the Temporal dashboard shows: top-level workflow ID = the `pipeline_run_id` (with env prefix); child workflow IDs are slash-separated paths; the `PipeCode`, `PipelineRunId`, `SessionId`, `UserId`, `DomainCode` search attributes are populated on every workflow row; static summary shows `{pipe_code} — {description}`.
-
-### Checkpoint — end of Phase 3
-
-- **Status.** Implemented on branch `feature/Temporal-config` (uncommitted).
-- **Code state.**
- - `wfid` parameter is removed from every protocol and implementation: `PipeRunProtocol`, `PipeRouterProtocol`, `PipeRun`, `PipeRouter`, `DryPipeRouter`, `TemporalPipeRun`, `TemporalPipeRouter`. Final `grep -rn "wfid" pipelex/ tests/` returns empty.
- - `TemporalPipeRun.run` / `start` now thread `pipe_job.job_metadata.pipeline_run_id` into `make_workflow_id(pipeline_run_id=...)` and pass `search_attributes` / `static_summary` / `static_details` via the helpers on every workflow start.
- - `TemporalPipeRouter._run_pipe_job` rewritten: child-branch id is `f"{parent_workflow_id}/{pipe_job.pipe.code}-{str(workflow.uuid4())[:8]}"`; the slash separator is in place; child search attributes are built via `build_search_attributes_for_child` from a parent-attribute dict reconstructed from `pipe_job.job_metadata` + `TemporalManager`. No defensive `pipe.code or "pipe"` fallback — relies on `PipeAbstract.code` being a required non-empty Pydantic field.
- - `wf_pipe_run.py`: line 46 separator flipped from `-` to `/` (`f"{workflow.info().workflow_id}/pipe-router"`). `search_attributes=` now passed to the raw `workflow.execute_child_workflow` call. The parent's attributes are rebuilt locally from `pipe_job` since PipeCode + DomainCode do not change for the fixed-role child (same pipe). `get_temporal_manager` was added to the `workflow.unsafe.imports_passed_through()` block so the sandbox lets it through.
- - `WorkflowExecutor.make_workflow_id` parameter rename from Phase 1 is now wired up to a real `pipeline_run_id` source (was previously receiving the degraded `class_name`).
-- **Tests.**
- - New: `tests/unit/pipelex/temporal/test_workflow_id_construction.py` — top-level shape per `RunMode` (parametrized for all five modes), absence-of-session-id assertion, fixed-role child slash suffix, dynamic-child format with mocked `workflow.uuid4()` proving replay determinism (re-running the construction returns the same id).
- - New: `tests/unit/pipelex/temporal/test_search_attribute_dict_construction.py` — five-keyed dict shape + child inheritance rule (PipeCode + DomainCode override; PipelineRunId + SessionId + UserId inherit).
-- **Quality gates.** `make agent-check` clean. Targeted run (`tests/unit/pipelex/`): 4497 passed, 1 skipped, 1 xfailed (skip + xfail are pre-existing, unrelated).
-- **Operational notes (deferred to Phase 4).** Phase 4 will add the namespace-bootstrap warning. Integration tests under `tests/integration/pipelex/temporal/` will only get a chance to fire that warning when run against a real Temporal server with `--temporal-server <profile>` — they are not run as part of the regular CI agent-test sweep.
-- **Handoff notes for Phase 4.**
- - Search-attribute keys to register: `PipeCode`, `PipelineRunId`, `SessionId`, `UserId`, `DomainCode` (all `Keyword`).
- - Bootstrap check belongs in `pipelex/temporal/temporal_task_manager.py` near `TemporalManager.setup(...)` (line ~59). Soft-fail catch is `temporalio.service.RPCError` only; everything else propagates.
- - CHANGELOG should call out the pipeline_run_id → Workflow ID chain semantics shift: callers that pass a stable `pipeline_run_id` to `PipelineFactory.make_pipeline(...)` and re-run now land on the same Temporal Workflow Execution Chain (with `ALLOW_DUPLICATE` reuse policy), where previously the random/session id suffix made every run unique.
- - `wf_pipe_run.py` still uses raw `workflow.execute_child_workflow(...)`, not the wrapper. Unifying the two child-spawn paths is captured in the design's **Out of scope** list — not a Phase 4 deliverable. *(Update: a Phase 5 follow-up briefly unified them through `WorkflowExecutor.execute_child_workflow`; the Phase 6 follow-up reverted that for replay-determinism reasons — see "Phase 5 follow-up — Child-spawn path unification (reverted)" below.)*
-
----
-
-## Phase 4 — Deployment hooks, docs, CHANGELOG
-
-**What lands.** A bootstrap soft-fail check that warns when required custom search attributes are missing on the namespace. A new docs section explaining the one-time registration step. A CHANGELOG entry covering every breaking change.
-
-**Files touched.**
-
-- `pipelex/temporal/temporal_task_manager.py` (worker boot lives here — `TemporalManager.setup(session_id=...)` runs at line 59 today) — add a `DescribeNamespace` call on worker start. Failure-mode spec:
- - **Catch only `temporalio.service.RPCError`** (the specific cluster-metadata RPC failure). Log a warning naming the unreachable namespace; continue worker boot. Any other exception propagates — it is a real bug, not a degraded-dashboard concern.
- - **Required attributes present:** no warning. Continue boot silently.
- - **Required attributes missing:** log a warning naming exactly which attributes are missing, including the exact `temporal operator search-attribute create` command to register them. Continue boot.
- - Runs **once per worker process** (at boot, not per workflow). The result is not cached across processes — every worker boot does its own check.
-- `docs/under-the-hood/temporal-deployment.md` (new) — section on required custom search attributes and how to register them. Cross-link from any existing Temporal-related docs.
-- `CHANGELOG.md` — `[Unreleased]` entry covering:
- - Workflow ID shape change (`{env}{session5}-{rand5}-{ClassName}` → `{env_prefix}{pipeline_run_id}`).
- - **Pipeline run chain semantics.** Because the Workflow ID is now derived from `pipeline_run_id`, callers that pass a stable `pipeline_run_id` to `PipelineFactory.make_pipeline(pipeline_run_id=...)` and re-execute will land on the same Temporal Workflow Execution Chain (with a fresh `run_id` per execution and `WorkflowIDReusePolicy` at SDK default `ALLOW_DUPLICATE`). Old behavior produced a fresh workflow_id per execution by accident, via the session-id and random-id components. This is documented behavior now — not a bug, but a real semantic shift for any caller that supplied stable IDs.
- - Child workflow ID separator change (`-` → `/`).
- - Activity ID change (semantic labels → SDK-default integers).
- - `wfid` parameter removed from `PipeRunProtocol`, `PipeRouterProtocol`, `ContentGeneratorProtocol`, and every implementation.
- - New required custom search attributes on the Temporal namespace.
-
-**Tests.**
-
-- `tests/unit/pipelex/temporal/test_search_attribute_bootstrap_check.py` (new) — mocks `DescribeNamespace` to return:
- - (a) all attributes present — no warning logged.
- - (b) some attributes missing — warning logged with the exact registration command, missing names enumerated.
- - (c) `DescribeNamespace` raises `temporalio.service.RPCError` — worker boot continues, soft-fail warning logged, the check returns cleanly. Any other exception type propagates and crashes the worker (assert with `pytest.raises`).
-
-**Done when.**
-
-- `make agent-check` clean.
-- `make agent-test` green.
-- Docs preview renders the new section.
-- CHANGELOG entry written in the project's voice (one line per breaking change is fine; the pipeline-run-chain semantics line spells out the behavioral change explicitly).
-- `temporal-e2e-validate` skill run on a clean namespace (without the attributes registered) emits the warning; with attributes registered, runs cleanly.
-
----
-
-## Phase 5 — Migrate to `TypedSearchAttributes` (deprecation cleanup)
-
-**What lands.** Replace the dict-based `search_attributes` arg (currently `Mapping[str, list[str]]`) with `temporalio.common.TypedSearchAttributes` everywhere Pipelex sets them. The dict form still works on temporalio 1.23.0 but emits `DeprecationWarning: Dictionary-based search attributes are deprecated` on every workflow start; the SDK has announced removal in a future version.
-
-**Code anchors.**
-
-- `pipelex/temporal/tprl/observability.py` — `build_search_attributes` and `build_search_attributes_for_child` return `Mapping[str, list[str]]` today. They should return `TypedSearchAttributes`. Define five module-level constants: `PIPE_CODE_KEY = SearchAttributeKey.for_keyword("PipeCode")`, etc.
-- `pipelex/temporal/tprl/workflow_caller.py` — the four entry points (`execute_workflow`, `start_workflow`, `execute_child_workflow`, `start_child_workflow`) declare `search_attributes: Mapping[str, list[str]] | None`. Switch the type annotation to `TypedSearchAttributes | None`. The pass-through to the SDK is unchanged at the call site.
-- `pipelex/temporal/tprl_pipe/temporal_pipe_run.py`, `temporal_pipe_router.py` — call sites currently do `search_attributes=dict(build_search_attributes(pipe_job))`. Drop the `dict(...)` wrap; pass the `TypedSearchAttributes` directly.
-- `pipelex/temporal/tprl_pipe/wf_pipe_run.py` — currently builds a local `child_search_attributes` dict. Rebuild as `TypedSearchAttributes` (or call `build_search_attributes(workflow_arg.pipe_job)` directly — fine inside the `imports_passed_through` block).
-- `build_search_attributes_for_child` is currently a dict merge. `TypedSearchAttributes` is immutable; use `parent_attrs.updated(SearchAttributePair(PIPE_CODE_KEY, child_code), SearchAttributePair(DOMAIN_CODE_KEY, child_domain))`.
-
-**Tests.**
-
-- `tests/unit/pipelex/temporal/test_observability_helpers.py` and `test_search_attribute_dict_construction.py` currently assert dict equality (`attrs == {"PipeCode": ["..."], ...}`). Rewrite to assert membership in a `TypedSearchAttributes` instance — iterate `.search_attributes` and check each `SearchAttributePair`'s key + value, or use the public `for_keyword(...)` lookup.
-- `test_workflow_caller_passthrough.py` reads `call_args.kwargs.get("search_attributes")` — that value is now a `TypedSearchAttributes` instance; assert against the typed form.
-- `tests/integration/pipelex/temporal/conftest.py` and `test_payload_codec_pipeline.py` already call `ensure_required_search_attributes_registered` — no test changes needed there; the registration helper uses the bridge-level `AddSearchAttributesRequest`, not the workflow client API.
-
-**Done when.**
-
-- `make agent-check` clean.
-- `make agent-test` green.
-- Running `tests/integration/pipelex/temporal/` produces **zero** `DeprecationWarning: Dictionary-based search attributes are deprecated` lines.
-- `grep -rn "Mapping\[str, list\[str\]\]" pipelex/temporal/` returns no results in the search-attribute pass-through code.
-
-**Open questions (decide during implementation).**
-
-- Where to put the five `SearchAttributeKey` constants — top of `observability.py` (current preference) or a dedicated `search_attribute_keys.py` if any other module ever needs them. Default: keep them in `observability.py` for now.
-- Whether the `build_static_summary` helper should also accept a `TypedSearchAttributes` for callers that already have one. Probably no — `static_summary` is a separate concept (Markdown string, not Keyword).
-
-### Checkpoint — end of Phase 5
-
-- **Status.** Implemented on branch `feature/Temporal-ids` (uncommitted).
-- **Code state.**
- - `pipelex/temporal/tprl/observability.py` now defines five module-level `SearchAttributeKey[str]` constants (`PIPE_CODE_KEY`, `PIPELINE_RUN_ID_KEY`, `SESSION_ID_KEY`, `USER_ID_KEY`, `DOMAIN_CODE_KEY`) and `build_search_attributes` returns `TypedSearchAttributes` instead of `Mapping[str, list[str]]`. The five `SearchAttributePair` instances replace the old dict literal one-for-one. No `build_search_attributes_for_child` exists today — earlier phases collapsed child-attribute construction to just calling `build_search_attributes(child_pipe_job)`, since the child's `pipe_job` already carries inherited identity. Phase 5 did not need to touch that simplification.
- - `pipelex/temporal/tprl/workflow_caller.py` — all four executor entry points (`execute_workflow`, `start_workflow`, `execute_child_workflow`, `start_child_workflow`) now declare `search_attributes: TypedSearchAttributes | None`. The SDK pass-through is unchanged; only the type annotation flipped.
- - `pipelex/temporal/tprl_pipe/temporal_pipe_run.py`, `temporal_pipe_router.py`, `wf_pipe_run.py` — the four `search_attributes=dict(build_search_attributes(pipe_job))` call sites are now `search_attributes=build_search_attributes(pipe_job)` (dict wrap dropped). No other changes at these call sites.
-- **Tests.**
- - `tests/unit/pipelex/temporal/test_observability_helpers.py` — imports the five `*_KEY` constants and rewrote `test_build_search_attributes_returns_five_keyed_dict` → `test_build_search_attributes_returns_five_typed_keys`, asserting against the typed form (`attrs[KEY] == "..."` plus `len(attrs) == 5`) instead of dict equality.
- - `tests/unit/pipelex/temporal/test_search_attribute_dict_construction.py` — same conversion: imports the five `*_KEY` constants; asserts via `attrs[KEY]` instead of dict access by string. Renamed the top-level test to `test_top_level_attrs_have_five_keys_with_correct_value_sources`.
- - `tests/unit/pipelex/temporal/test_workflow_caller_passthrough.py` — `_SEARCH_ATTRS` constant changed from a `dict` to a `TypedSearchAttributes([SearchAttributePair(SearchAttributeKey.for_keyword("PipeCode"), "translate_doc"), ...])`. The four pass-through assertions (`kwargs.get("search_attributes") == _SEARCH_ATTRS`) still work — `TypedSearchAttributes` supports value equality.
-- **Quality gates.** `make agent-check` clean (pyright 0/0/0, mypy success). Targeted unit run (`tests/unit/pipelex/temporal/`): 201 passed. Integration run (`tests/integration/pipelex/temporal/` with default `--temporal-server none`): 117 passed, 2 xpassed. `grep -rn "Mapping\[str, list\[str\]\]" pipelex/temporal/` returns empty. Running the integration suite with `-W "always::DeprecationWarning"` produces zero "Dictionary-based search attributes are deprecated" lines.
-- **API note.** Each typed key holds a single `str` value, not a list. The old dict form used `list[str]` because Temporal's dashboard filtering API on Keyword attributes is multi-valued; with `SearchAttributeKey.for_keyword(...)` the value type is `str` (single-valued). The SDK serializes both forms to the same wire shape, so the cluster-side behavior is identical.
-- **Handoff notes for Phase 6.**
- - No unrelated dict-based search-attribute call sites surfaced. The only remaining places that touch search attributes are `namespace_check.py` (`AddSearchAttributesRequest` and `ListSearchAttributesRequest` — bridge-level, not SDK workflow API) and the conftest auto-registration. Both are untouched and correct.
- - Phase 6 is the soft-fail → hard-fail flip in `namespace_check.py:check_required_search_attributes`. The five attribute keys are already centralized as the module-level `REQUIRED_SEARCH_ATTRIBUTES` tuple there; no further refactor needed before flipping the failure mode.
- - Tests that mock `build_search_attributes` no longer need to manufacture dicts; they can use `TypedSearchAttributes([])` or call the helper directly with a stubbed `pipe_job`.
-
-### Phase 5 follow-up — Child-spawn path unification (reverted)
-
-- **What was attempted.** `wf_pipe_run.py` was briefly routed through `WorkflowExecutor.execute_child_workflow(...)` via `WorkflowExecutorFactory[PipeJob, PipeOutput]().create_executor(task_queue=None)` — the same pattern `TemporalPipeRouter._run_pipe_job` then used on its child branch. The stated goal was consistency across both child-spawn code paths.
-- **Why it was reverted (Phase 6 follow-up, commit `ac8e2335`).** `WorkflowExecutorFactory.create_executor` reads `get_config().temporal.worker_config` to seed `execution_timeout`, `retry_policy`, `run_timeout`, `task_timeout`, `start_delay`, `rpc_timeout` for the executor instance. Inside a workflow, those values would then be baked into the recorded `StartChildWorkflowExecution` command. After any config edit on the worker process, replay would re-derive different values, and Temporal would reject the replay with a non-determinism mismatch. The wrapper is safe at the **submitter boundary** (top-level dispatch) where the executor is constructed once per call from current config; it is NOT safe inside a workflow.
-- **Current state (both child-spawn paths).** `wf_pipe_run.py` (fixed-role `pipe-router` child) and `temporal_pipe_router.py` (dynamic sub-pipe child) both call `workflow.execute_child_workflow(...)` directly. They wrap `ChildWorkflowError` as `WorkflowExecutionError` in-place to preserve the `workflow_failure_exception_types` contract registered on the Worker — see `pipelex/temporal/temporal_task_manager.py:make_worker`.
-- **Related session-id determinism fix (same `ac8e2335` commit).** `build_search_attributes` and `build_static_details` previously read `get_temporal_manager().session_id` at workflow run time. That field is per-worker-process and would differ across replays after a worker restart. Replaced with a new `stamp_submitter_session_id(pipe_job)` helper called at every top-level Temporal dispatch boundary; `JobMetadata.session_id` carries the stamped value through every child workflow input, and both helpers now read it off `pipe_job` so they stay pure functions of the workflow input.
-- **What the `WorkflowExecutor.execute_child_workflow` / `start_child_workflow` wrapper methods are good for.** Production code does not call them. They remain on `WorkflowExecutor` for completeness of the four-entry-point surface, with docstring warnings about the in-workflow replay-determinism trap. If a future caller is OK with config-baked options (e.g. a one-shot script that doesn't care about replay), they're available.
-- **Quality gates.** `make agent-check` clean. `make agent-test` green.
-
-### Phase 5 follow-up — Pre-Phase-6 cleanup
-
-- **What landed.**
- - **Tightened exception handling in `pipelex/temporal/tprl/workflow_caller.py`.** Replaced catch-all `except Exception` on all four entry points with named SDK exceptions: `(WorkflowAlreadyStartedError, RPCError, WorkflowFailureError)` for `execute_workflow`; `(WorkflowAlreadyStartedError, RPCError)` for `start_workflow`; trailing `except Exception` blocks dropped from `execute_child_workflow` and `start_child_workflow` (the existing `except ChildWorkflowError` is the only thing those paths can raise). Resolves the `# TODO: wip - do not catch all exceptions` self-comment. Per CLAUDE.md, anything outside these named exceptions is a real bug and must propagate.
- - **Failure-path test for `WfPipeRun`.** Added `tests/integration/pipelex/temporal/test_wf_pipe_run_failure_path.py`. Pins the invariant: when the child `WfPipeRouter` raises `ApplicationError`, the wrapper converts it to `WorkflowExecutionError`, `WfPipeRun` catches it, `act_deliver` fires exactly once with `status=DeliveryStatus.FAILED` and `pipe_output=None`, and the workflow re-raises the original execution error. Stubs the failing router via a `WfPipeRouterFailingStub` workflow registered with `@workflow.defn(name="wf_pipe_router")` (replaces the real router by name on the test worker). Stubs `act_deliver` via a closure-capturing activity.
- - **Latent production bug fix: `workflow_failure_exception_types` registration.** While writing the failure-path test, discovered that `WfPipeRun` re-raising `WorkflowExecutionError` triggers indefinite workflow-task retry instead of a terminal workflow failure — because `WorkflowExecutionError` is a `PipelexError(Exception)`, not a `temporalio.exceptions.FailureError` subclass. Temporal SDK only treats `FailureError` subclasses as workflow failures by default; everything else is treated as a programmer bug and the activation is retried forever. Pre-Phase-5 code raised `ChildWorkflowError` directly (a `FailureError`), so this was masked. Fixed by adding `workflow_failure_exception_types=[WorkflowExecutionError]` to `pipelex/temporal/temporal_task_manager.py:make_worker` (production) and the equivalent option on the test Worker. With this registered, any workflow that propagates `WorkflowExecutionError` now ends terminally and the failure surfaces to the client as `WorkflowFailureError`.
- - **TODOS.md doc-path fix.** Phase 4 "Files touched" section now points at `docs/under-the-hood/temporal-deployment.md` (Phase 6's "Code anchors" already had the correct path).
-- **Quality gates.** `make agent-check` clean. `make agent-test` green (full suite).
-
----
-
-## Phase 6 — Hard-fail worker boot + configurable attributes + CLI registration
-
-### Cold-start orientation for Phase 6
-
-A fresh session picking this up should read in this order:
-
-1. The top of this file (`## Status`, `## Cold-start orientation`, `## How to use this plan`) — gives global framing and confirms Phases 1–5 are merged on `feature/Temporal-ids`.
-2. `wip/temporal-primitives/id-and-naming-design.md` — authoritative spec for the five search attributes (`PipeCode`, `PipelineRunId`, `SessionId`, `UserId`, `DomainCode`) and what they're for. The design doc framed missing attributes as a degraded-dashboard concern; **this phase overrides that framing** for reachable real namespaces, because real clusters reject every workflow start that references an unregistered attribute (not just degrade filtering).
-3. This Phase 6 section in full.
-4. The Phase 5 checkpoint just above — confirms the typed-attribute surface (`TypedSearchAttributes`, `SearchAttributeKey.for_keyword`) that Phase 6 builds on.
-
-**Verification before touching anything:**
-
-```bash
-# Targeted unit suite must be green on entry — that's the Phase 5 final state.
-.venv/bin/pytest tests/unit/pipelex/temporal/ -q
-
-# The existing unit test for the bootstrap check exercises today's soft-fail
-# behavior. Read it before rewriting — the rewrite changes the contract.
-.venv/bin/pytest tests/unit/pipelex/temporal/test_search_attribute_bootstrap_check.py -v
-```
-
-**Key code anchors (line numbers verified at plan time; re-check if drift suspected):**
-
-- `pipelex/temporal/tprl/namespace_check.py:32` — `REQUIRED_SEARCH_ATTRIBUTES` tuple (rename + relocate target). The full module is ~120 lines and covers both the soft-fail check and the auto-register helper used by tests.
-- `pipelex/temporal/tprl/namespace_check.py:54` — `check_required_search_attributes` (the soft-fail audit; today logs `log.warning(...)` and returns — must hard-fail for the configured subset on reachable namespaces).
-- `pipelex/temporal/tprl/namespace_check.py:93` — `ensure_required_search_attributes_registered` (auto-register helper; gains `configured_attributes` parameter + permission-denied fallback).
-- `pipelex/temporal/temporal_task_manager.py:32` — top-level import of `check_required_search_attributes`.
-- `pipelex/temporal/temporal_task_manager.py:195` — call site inside `run_worker`. Gate on `enabled` flag from new config.
-- `pipelex/temporal/config_temporal.py:577-586` — `class Temporal(ConfigModel)`. Add `search_attributes: SearchAttributesConfig` field here. New `SearchAttributesConfig` model goes earlier in the module (alongside `WorkerScopesConfig` at line 84). New `BUILTIN_SEARCH_ATTRIBUTES` tuple also lives here (the `TYPE_CHECKING`-only `temporalio` import guarantees the module is safe to load without the temporal extra).
-- `pipelex/temporal/exceptions.py:20` — `TemporalConfigError`. New `SearchAttributeRegistrationError` subclasses this.
-- `pipelex/temporal/tprl/observability.py:53-69` — `build_search_attributes`. Add the early-return-when-disabled branch + filter-by-configured-subset logic before the five `SearchAttributePair` constructors.
-- `pipelex/temporal/tprl/observability.py:29-33` — the five `*_KEY` module constants. Filter logic walks these by name.
-- `pipelex/pipelex.toml:445-449` — `[temporal]` block (currently just `is_enabled` + `payload_codec_config`). New `[temporal.search_attributes]` block inserts after line 449 (before `[temporal.worker_config]`).
-- `pipelex/cli/_cli.py:20` — `from pipelex.cli.commands.worker_cmd import worker_cmd` — the precedent for module-level CLI command import; the new `setup_temporal_namespace_cmd` slots in next to it on line 21.
-- `pipelex/cli/_cli.py:33` — `list_commands` order (`["login", "init", "doctor", ..., "worker"]`). Append `"setup-temporal-namespace"` (or chosen name) at the end.
-- `pipelex/cli/_cli.py:209` — `app.command(name="worker", ...)` registration; new command registers next to it.
-- `pipelex/cli/commands/worker_cmd.py:45` — example of deferred `pipelex.temporal.*` import with `# noqa: PLC0415`. **Copy this pattern verbatim** in the new command so the temporal extra stays optional.
-- `pipelex/cli/cli_factory.py` — `make_pipelex_for_cli(...)` accepts `temporal_enabled=True`. The new command calls this the same way `worker_cmd` does at line 43.
-- `pipelex/temporal/temporal_connect.py` — `connect_to_temporal_selected_server(selected_server_config=...)` is the entry the new CLI command uses to honor `--server <profile>`. Already used by the integration conftest at line 145.
-- `tests/integration/pipelex/temporal/conftest.py:16,120,126` — three existing call sites of `ensure_required_search_attributes_registered`. After the helper grows a `configured_attributes` parameter, these must pass `BUILTIN_SEARCH_ATTRIBUTES` explicitly. **Don't forget the third call site** at line 126 (time-skipping server branch).
-- `tests/integration/pipelex/temporal/test_payload_codec_pipeline.py:25,123` — second test file calling the helper; same signature update.
-- `tests/unit/pipelex/temporal/test_search_attribute_bootstrap_check.py:20,42,46,58,80,90` — the existing four tests against the soft-fail contract. Phase 6 rewrites them per the Tests section below; the `REQUIRED_SEARCH_ATTRIBUTES` import becomes `BUILTIN_SEARCH_ATTRIBUTES`.
-
-**Three call sites of `build_search_attributes(pipe_job)` that will inherit the filter automatically** (no Phase 6 work here, but flag them if a test surfaces the wrong behavior):
-
-- `pipelex/temporal/tprl_pipe/temporal_pipe_run.py:69, 106`
-- `pipelex/temporal/tprl_pipe/temporal_pipe_router.py:72, 93`
-- `pipelex/temporal/tprl_pipe/wf_pipe_run.py:55`
-
-Since they all delegate to `build_search_attributes`, the `enabled = false` early-return propagates through five workflow-start paths with one change.
-
-**External tooling worth knowing about:**
-
-- `/temporal-e2e-validate` skill (Claude Code) — validates Temporal distributed execution against a real server end-to-end. Use after Phase 6 lands with `[temporal.search_attributes] enabled = true` AND `enabled = false` to confirm both paths.
-- Integration tests support `--temporal-server local|testing|<profile>` for running against a real cluster. See CLAUDE.md "Temporal Integration Test Options."
-- For Temporal Cloud verification: cluster admin registers via `tcld namespace search-attributes add` or the Cloud UI's "Namespace → Custom Search Attributes" page. Worker API keys typically lack `OperatorService` permissions — the `pipelex setup-temporal-namespace --dry-run` path is the operator-facing fallback for that case.
-
-**What lands.** Three intertwined deliverables:
-
-1. **Configurable search-attribute surface.** A new `[temporal.search_attributes]` config block with a master `enabled` toggle and an `attributes` subset selector (opt-in/opt-out of the fixed five — names and value sources stay built-in; custom attributes are out of scope).
-2. **Hard-fail worker boot when attributes are missing on a reachable namespace.** Flip the current soft-fail framing (warn-and-continue) into a hard fail. The current behavior is dishonest: workers boot fine when the configured custom attributes are missing, but every workflow dispatch then fails with `RPCError: Namespace ... has no mapping defined for search attribute PipeCode`. Better to fast-fail at worker boot with the exact registration command than to keep failing on every dispatch with a less actionable error.
-3. **`pipelex setup-temporal-namespace` CLI command.** Wraps the existing `ensure_required_search_attributes_registered` helper so operators don't need a separate `temporal` / `tcld` install for the common case. Reads the same `[temporal.temporal_config]` block the worker uses, so the namespace/host can never drift between "what got registered" and "what the worker will dispatch to". `--dry-run` prints the equivalent `temporal operator search-attribute create` command instead of executing.
-
-**Why this isn't a no-op.** The Phase 4 design doc framed the missing-attributes case as "degraded dashboard, workflows still run". That premise is false against a real Temporal server — the cluster rejects every workflow start that references an unregistered attribute. The CHANGELOG and `docs/under-the-hood/temporal-deployment.md` need to be updated to match the new strict behavior. The in-process / test path keeps auto-registering via `ensure_required_search_attributes_registered` (already in place in `tests/integration/pipelex/temporal/conftest.py`).
-
-### Deliverable 1 — Configurable `[temporal.search_attributes]`
-
-**Config schema.** Add a `SearchAttributesConfig` model to `pipelex/temporal/config_temporal.py`, wired onto `TemporalConfig`:
-
-```toml
-[temporal.search_attributes]
-# Master toggle. When false: workflow starts don't attach any custom search
-# attributes, the worker-boot check is skipped, and the dashboard view falls
-# back to WorkflowType / WorkflowId / StartTime only.
-enabled = true
-
-# Subset of the five built-in attributes to populate. Names not in this list
-# are skipped at workflow-start time AND not required at worker boot.
-# Pipelex only knows how to populate these five; arbitrary custom names are
-# out of scope (they would require code to know the value source).
-attributes = ["PipeCode", "PipelineRunId", "SessionId", "UserId", "DomainCode"]
-```
-
-**Pydantic model.**
-
-```python
-class SearchAttributesConfig(ConfigModel):
- enabled: bool
- attributes: list[str]
-
- @model_validator(mode="after")
- def validate_attribute_names(self) -> Self:
- # The five built-ins live in namespace_check.BUILTIN_SEARCH_ATTRIBUTES.
- # Reject any unknown name with a helpful message — protects against
- # typos like "PipelineRunID" silently producing no attribute.
- ...
-```
-
-**Behavior changes in three call sites.**
-
-- `pipelex/temporal/tprl/observability.py:build_search_attributes` — early-return `TypedSearchAttributes([])` when `enabled = false`. Otherwise, filter the five `SearchAttributePair`s by membership in `config.attributes`. Pull config via `get_config().temporal.search_attributes` (the helper is already called from sandbox-safe code paths; `get_temporal_manager()` is the existing precedent for sandbox imports in this module).
-- `pipelex/temporal/tprl/namespace_check.py:check_required_search_attributes` — accept the configured subset (`list[str]`) as a parameter instead of reading `REQUIRED_SEARCH_ATTRIBUTES`. The hard-coded tuple stays in the module as `BUILTIN_SEARCH_ATTRIBUTES` (the union of all five Pipelex can populate) for validator + CLI use; the *runtime check* uses only the configured subset.
-- `pipelex/temporal/temporal_task_manager.py:run_worker` — read `enabled` and `attributes` from config; skip the boot check entirely when `enabled = false`.
-
-**Renaming.** `REQUIRED_SEARCH_ATTRIBUTES` → `BUILTIN_SEARCH_ATTRIBUTES` to reflect that "required" is now a function of config, not a constant.
-
-### Deliverable 2 — Hard-fail worker boot on missing attributes
-
-**Code anchors.**
-
-- `pipelex/temporal/tprl/namespace_check.py:check_required_search_attributes` — today logs `log.warning(...)` and returns. Switch to raising a new exception (`SearchAttributeRegistrationError`, subclass of `TemporalConfigError`) when any *configured* attribute is missing AND the `ListSearchAttributes` call succeeds (i.e. it's a real namespace, not an unreachable one). The exact registration command — both the `pipelex setup-temporal-namespace` invocation **and** the equivalent `temporal operator search-attribute create` fallback — goes in the exception message.
-- `RPCError` on the call itself stays a soft fail — the namespace was unreachable, not misconfigured. Keep the warning, don't raise. (In-process / time-skipping test servers don't trigger this path because the conftest pre-registers.)
-- `pipelex/temporal/temporal_task_manager.py:run_worker` — the call site is already in place; only the failure mode changes. The exception propagates and crashes worker boot, which is the desired behavior. When `enabled = false`, the call is skipped entirely.
-- The error message format must be copy-paste-ready: both the Pipelex CLI invocation and the raw `temporal` CLI command, on separate lines, so operators on either side of the fence can fix the gap.
-
-### Deliverable 3 — `pipelex setup-temporal-namespace` CLI command
-
-**Why a flat command, not a `pipelex temporal` group.** There is no `pipelex temporal` Typer sub-app today (just the single `pipelex worker` command). Adding a sub-app is a separate refactor; flat command keeps the diff focused on the search-attribute problem.
-
-**Optional-dependency handling.** The `temporal` extra (`temporalio==1.23.0`, `aiohttp`) is optional — `pipelex` works without it for non-Temporal users. The new command follows the existing `worker_cmd` pattern:
-
-- Module file `pipelex/cli/commands/setup_temporal_namespace_cmd.py` has **no** `pipelex.temporal.*` imports at module level — only `typer` and standard pipelex. This way `pipelex/cli/_cli.py` can import it unconditionally and `pipelex --help` works without the extra installed (verified by the same flow today for `pipelex worker`).
-- All `pipelex.temporal.*` imports go inside the function body with `# noqa: PLC0415` — `temporal_connect`, `namespace_check`, anything else.
-- Wrap the deferred import in `try/except ImportError` with a friendly `Install with: pip install pipelex[temporal]` message. (Strictly nicer than `worker_cmd` today, which lets the raw Python `ImportError` bubble. Optionally retrofit `worker_cmd` with the same handler — small bonus.)
-
-**`BUILTIN_SEARCH_ATTRIBUTES` location.** The tuple of attribute names is referenced by the config validator in `SearchAttributesConfig`. If it lives in `pipelex/temporal/tprl/namespace_check.py` (current `REQUIRED_SEARCH_ATTRIBUTES`), the validator can't reference it without importing temporal at config-load time — defeating the optional-dep contract. **Move the tuple to `pipelex/temporal/config_temporal.py`** (which already only imports `temporalio` under `if TYPE_CHECKING:`, so it's safe to load without the extra). `namespace_check.py` imports it from there. The validator reads it locally.
-
-**Command surface.**
-
-```bash
-# Default: read [temporal.temporal_config] from pipelex.toml, connect, register
-# any missing configured attributes. Idempotent.
-pipelex setup-temporal-namespace
-
-# Print the equivalent `temporal operator search-attribute create` invocation
-# without executing — useful for ops folks who need the namespace admin to
-# register on their behalf.
-pipelex setup-temporal-namespace --dry-run
-
-# Target a non-default server profile.
-pipelex setup-temporal-namespace --server testing
-```
-
-**Files touched.**
-
-- `pipelex/cli/commands/setup_temporal_namespace_cmd.py` (new) — Typer command. Calls `make_pipelex_for_cli(temporal_enabled=True)`, connects via `connect_to_temporal_selected_server`, calls `ensure_required_search_attributes_registered`. On `RPCError(PermissionDenied)`, prints the fallback runbook (raw `temporal` CLI command, `tcld` for Cloud, Cloud UI link).
-- `pipelex/cli/_cli.py` — register the new command alongside `worker_cmd`.
-- `pipelex/temporal/tprl/namespace_check.py:ensure_required_search_attributes_registered` — accept a `configured_attributes: list[str]` parameter so the CLI registers only what config says is enabled. Test conftest call site keeps default = all five (passes `BUILTIN_SEARCH_ATTRIBUTES`).
-
-**Permission-denied fallback.** Helper catches `RPCError` where `status == PERMISSION_DENIED` and returns a structured `RegistrationFailure` instead of raising — the CLI command formats it into the fallback runbook. Other RPC errors (`UNAVAILABLE`, `NOT_FOUND`) re-raise.
-
-### Files touched (consolidated)
-
-- `pipelex/temporal/config_temporal.py` — new `SearchAttributesConfig`, wired to `TemporalConfig`.
-- `pipelex/pipelex.toml` — new `[temporal.search_attributes]` block with documented defaults.
-- `.pipelex/pipelex.toml` (project template) — same block commented out as an override invitation, per project convention.
-- `pipelex/temporal/tprl/observability.py:build_search_attributes` — filter by configured subset; early-return when disabled.
-- `pipelex/temporal/tprl/namespace_check.py` — rename `REQUIRED_SEARCH_ATTRIBUTES` → `BUILTIN_SEARCH_ATTRIBUTES`; accept `configured_attributes` parameter; hard-fail instead of warning; permission-denied fallback in `ensure_required_search_attributes_registered`; new `SearchAttributeRegistrationError` exception.
-- `pipelex/temporal/temporal_task_manager.py:run_worker` — gate the check on `enabled`; pass configured subset.
-- `pipelex/cli/commands/setup_temporal_namespace_cmd.py` (new) — CLI command.
-- `pipelex/cli/_cli.py` — wire the new command.
-- `tests/integration/pipelex/temporal/conftest.py` — pass `BUILTIN_SEARCH_ATTRIBUTES` to the helper (no behavior change for tests, just makes the signature change explicit).
-- `docs/under-the-hood/temporal-deployment.md` — full rewrite of the "soft fail" framing → "strict prerequisite + configurable + here's the easy registration command".
-- `CHANGELOG.md` — replace the soft-fail line with the strict-prerequisite framing; add config block; add CLI command.
-
-### Tests
-
-- `tests/unit/pipelex/temporal/test_search_attribute_bootstrap_check.py` — rewrite:
- - "all present" → still no exception, no warning.
- - "some missing" → now `pytest.raises(SearchAttributeRegistrationError)` with both the `pipelex setup-temporal-namespace` invocation AND the raw `temporal operator search-attribute create` command in the message.
- - "`RPCError(UNAVAILABLE)`" → still soft-fails (warns, returns).
- - "non-`RPCError`" → propagates unchanged.
- - **New:** "configured subset" — only the subset is checked; missing built-ins outside the subset don't trigger the error.
- - **New:** "disabled" — `enabled = false` skips the check entirely (verify the operator service is never called).
-- `tests/unit/pipelex/temporal/test_observability_helpers.py` — extend:
- - **New:** `enabled = false` → `build_search_attributes` returns empty `TypedSearchAttributes`.
- - **New:** `attributes = ["PipeCode", "DomainCode"]` → only those two pairs in the returned set.
-- `tests/unit/pipelex/temporal/test_setup_temporal_namespace_cmd.py` (new) — exercise the CLI command with a mocked temporal client: happy path registers missing, dry-run prints without registering, permission-denied path prints the fallback runbook.
-- `tests/unit/pipelex/temporal/test_search_attributes_config.py` (new) — config validator rejects unknown attribute names with a helpful error; default config matches the historic five.
-- No integration test changes; the test path auto-registers before any workflow runs (Phase 4 fix).
-
-### Done when
-
-- `make agent-check` clean.
-- `make agent-test` green.
-- The full integration suite (`tests/integration/pipelex/temporal/`) still passes — the auto-registration in the test conftest keeps everything green there.
-- A manual run against a real Temporal server with **no** attributes registered fails clean at worker boot with both registration commands in the error message. Running `pipelex setup-temporal-namespace` once, the worker then boots and dispatches succeed.
-- Setting `[temporal.search_attributes] enabled = false` lets a worker boot against a namespace with zero custom attributes registered; workflows dispatch successfully (verified by the same `temporal-e2e-validate` flow with the toggle flipped).
-- `pipelex setup-temporal-namespace --dry-run` prints the exact `temporal operator search-attribute create` command, including the configured subset.
-- `docs/under-the-hood/temporal-deployment.md` documents: the configurable surface, the two registration paths (Pipelex CLI vs Temporal CLI), and the Cloud-specific runbook (`tcld` + UI), plus the permission model for self-managed workers on Temporal Cloud.
-- `CHANGELOG.md` updated.
-
-### Open questions (cold-start may need to decide)
-
-- For Temporal Cloud customers running self-managed Pipelex workers, what permission level does the customer's API key need to call `OperatorService.AddSearchAttributes`? (Probably "Namespace Admin" — confirm against Cloud docs at implementation time and document in `temporal-deployment.md`.)
-- Is there a sane fallback for `--temporal-server <profile>` integration test runs that point at a real cluster the developer doesn't have admin on? Likely: call `ensure_required_search_attributes_registered` in the conftest's real-server branch too, and tolerate `RPCError(PermissionDenied)` (warn and continue — the cluster admin will have done it). Decide when this case actually surfaces.
-- Should the `enabled = false` mode also short-circuit the static summary / static details (which are independent of search attributes today)? Probably no — those are orthogonal observability features and may be useful even when filtering is disabled. Leave them on; only search attributes are gated by this toggle.
-
-### Checkpoint — end of Phase 6
-
-- **Status.** Implementation complete on `feature/Temporal-ids`. `make agent-check` clean, `make agent-test` green, 561 targeted unit tests pass in `tests/unit/pipelex/temporal/` + `tests/unit/pipelex/cli/` + `tests/unit/pipelex/system/`.
-
-- **Behavior change confirmed.** Worker boot now hard-fails on a reachable namespace when a configured custom search attribute is missing (raises `SearchAttributeRegistrationError` with both the `pipelex setup-temporal-namespace` invocation and the equivalent raw `temporal operator search-attribute create` command in the message). `RPCError` from the operator service stays a soft fail. `[temporal.search_attributes].enabled = false` skips both the check and the per-workflow attachment. In-process / time-skipping test servers continue to auto-register via the conftest, now passing `BUILTIN_SEARCH_ATTRIBUTES` through the helper's new `configured_attributes` parameter. The new `pipelex setup-temporal-namespace` CLI command was smoke-tested with `--dry-run` and prints the exact `temporal operator search-attribute create` invocation for the resolved namespace + the Cloud `tcld` fallback.
-
-- **What landed.**
- - `pipelex/temporal/config_temporal.py` — new `SearchAttributesConfig` model + `BUILTIN_SEARCH_ATTRIBUTES` tuple. The constant lives here (not in `namespace_check.py`) so the validator can reference it without pulling `temporalio` into the config-load path. `Temporal` gains a `search_attributes: SearchAttributesConfig` field.
- - `pipelex/pipelex.toml` — new `[temporal.search_attributes]` block (enabled = true, all five attributes). `.pipelex/pipelex.toml` template ships the same block commented out as an override invitation.
- - `pipelex/temporal/tprl/namespace_check.py` — `REQUIRED_SEARCH_ATTRIBUTES` removed; helpers now take `configured_attributes: Sequence[str]`. `check_required_search_attributes` raises `SearchAttributeRegistrationError` instead of warning when configured attributes are missing on a reachable namespace. `ensure_required_search_attributes_registered` returns a structured `RegistrationFailure` dataclass on `RPCError(PERMISSION_DENIED)` instead of raising, so the CLI command can format the fallback runbook. Other `RPCError` codes propagate. Empty `configured_attributes` short-circuits both helpers.
- - `pipelex/temporal/exceptions.py` — new `SearchAttributeRegistrationError(TemporalConfigError)`.
- - `pipelex/temporal/tprl/observability.py` — `build_search_attributes` early-returns `TypedSearchAttributes([])` when `enabled = false`, otherwise filters the five `SearchAttributePair`s by `config.attributes`. The five workflow-start call sites in `tprl_pipe/` inherit the filter automatically.
- - `pipelex/temporal/temporal_task_manager.py` — `run_worker` gates the bootstrap check on `enabled` and passes the configured subset.
- - `pipelex/cli/commands/setup_temporal_namespace_cmd.py` (new) — Typer command. `--dry-run` prints the equivalent raw `temporal` CLI command + the Cloud `tcld` runbook. `--server <profile>` targets a non-default profile. Permission-denied path prints the actionable fallback and exits with code 1. Module-level imports stay pure-pipelex; all `pipelex.temporal.*` imports are deferred inside the function body (carrying `# noqa: PLC0415`) and wrapped in a `try/except ImportError` so `pipelex --help` works without the `temporal` extra.
- - `pipelex/cli/_cli.py` — registers the new command next to `pipelex worker`, appended to `list_commands` order.
- - `tests/integration/pipelex/temporal/conftest.py` + `test_payload_codec_pipeline.py` — three integration call sites of the helper now pass `BUILTIN_SEARCH_ATTRIBUTES` explicitly.
- - `tests/unit/pipelex/temporal/test_search_attribute_bootstrap_check.py` — rewritten for the hard-fail contract (six cases: all-present silent, some-missing raises with both commands, RPC soft-fail, non-RPC propagation, configured-subset, disabled).
- - `tests/unit/pipelex/temporal/test_observability_helpers.py` + `test_search_attribute_dict_construction.py` — extended with `enabled = false` and partial-subset cases; existing tests patch `get_config` via a new module-local fixture.
- - `tests/unit/pipelex/temporal/test_search_attributes_config.py` (new) — config validator rejects unknown attribute names; default config matches the historic five.
- - `tests/unit/pipelex/cli/test_setup_temporal_namespace_cmd.py` (new) — CLI command unit tests: dry-run, happy-path, permission-denied fallback, disabled short-circuit, unknown-server-profile.
- - `tests/unit/pipelex/temporal/test_temporal_config_warnings.py` — `_make_temporal_config` helper passes the new `search_attributes=SearchAttributesConfig(...)` arg.
-
-- **Docs + CHANGELOG synced.** `docs/under-the-hood/temporal-deployment.md` was fully rewritten away from the "soft fail" framing into "strict prerequisite + configurable surface + two registration paths + permission model for Temporal Cloud self-managed workers". `CHANGELOG.md` replaces the soft-fail line under [Unreleased] with the strict-prerequisite framing and adds two new entries for the config block and the CLI command.
-
-- **Promotion.** `namespace_check._format_registration_command` → `format_temporal_cli_command` (public) because the CLI command now also calls it. Implementation unchanged.
-
-- **Open questions resolved during implementation.**
- - **Temporal Cloud permission model.** Documented in `temporal-deployment.md` as "the customer's namespace admin owns `OperatorService.AddSearchAttributes`; the worker API key typically doesn't have it." `pipelex setup-temporal-namespace` handles `RPCError(PERMISSION_DENIED)` by printing the exact `temporal` / `tcld` / Cloud UI commands the admin needs to run.
- - **Static summary / static details independence.** Confirmed orthogonal to the search-attribute toggle. `build_static_summary` / `build_static_details` are not gated by `[temporal.search_attributes].enabled`.
- - **Custom attribute names beyond the five built-ins.** Out of scope (per the design). The config validator rejects them with a helpful message listing the five known names.
-
-- **Known follow-ups (deferred).**
- - Verifying the hard-fail path against a real Temporal cluster with `--temporal-server <profile>` (using `/temporal-e2e-validate`) was not run as part of this checkpoint — the unit suite covers the hard-fail contract via mocked clients, and the integration test path keeps the in-process server registered by the conftest. Run the e2e slash command once a real-cluster credential is available.
- - The `enabled = false` end-to-end path was not run on a real cluster either. The unit tests verify the bootstrap check is skipped and `build_search_attributes` returns empty; the workflow-start call sites all delegate to `build_search_attributes`, so the propagation is by construction.
-
----
-
-## Cross-phase risks and mitigations
-
-- **~~Integration tests that asserted on workflow_id shape.~~** **VACATED.** A grep at design time confirmed zero existing tests assert on the `{session5}-{rand5}-{ClassName}` shape. No transitional handling needed in Phase 1; no test rewrites needed in Phase 3 beyond the new files.
-- **~~`make_top_workflow_id` callers outside `WorkflowExecutor`.~~** **VACATED.** A grep confirms exactly one production caller (`WorkflowExecutor.make_workflow_id` at `workflow_caller.py:85`). Phase 1's rename covers it.
-- **Namespace registration in CI.** CI's in-process Temporal server skips search-attribute registration. Phase 4's bootstrap check still calls `DescribeNamespace` on every worker boot, including in-process test workers — verify whether the in-process server raises `RPCError` (covered by Phase 4's soft-fail path) or returns an empty/synthetic namespace description. If the latter, decide in Phase 4 whether the warning level should be downgraded for in-process mode specifically (detect via `temporal_server_config` or absence of a real namespace) to keep CI logs clean.
-- **Replay-safety regression.** The deletion of the LRU + `is_replaying()` short-circuit is correct *because* the disambiguator stops coming from worker-singleton state. If a future change re-introduces worker-singleton state into the activity dispatch path, the determinism guarantee breaks. Phase 2's PR description calls this out so reviewers know to push back on any reintroduction.
-- **~~`pipe_job.pipe.code` empty in pathological inputs.~~** **VACATED.** `PipeAbstract.code: str` is a required Pydantic field with `validate_pipe_code_syntax` non-empty validation. No fallback in Phase 3; trust the invariant. If invariants ever change, the resulting crash points cleanly at the bug instead of hiding it behind a silently-degraded workflow id.
-
-## Test plan (cumulative across phases)
-
-By the end of Phase 4, the following must be green:
-
-- All existing `make agent-test` tests.
-- The renamed TDD gate test in `test_default_activity_id_collision_bug.py` (`test_two_default_activity_calls_in_one_workflow_produce_distinct_activity_ids`).
-- New unit tests added in Phase 1: `test_observability_helpers.py` (helper formats + truncation + child-attr inheritance) and `test_workflow_caller_passthrough.py` (the four kwargs reach the SDK on all four entry points: `execute_workflow` / `start_workflow` / `execute_child_workflow` / `start_child_workflow`).
-- Rewritten / deleted tests in Phase 2 — see the explicit per-test enumeration in Phase 2 above. The deletions include the entire `test_seen_activity_ids_lru.py` file.
-- New unit tests added in Phase 3: `test_workflow_id_construction.py` (top-level shape per RunMode + fixed-role child + dynamic child + **replay-determinism with mocked `workflow.uuid4`**) and `test_search_attribute_dict_construction.py` (five keys + child inheritance rules).
-- New unit test added in Phase 4: `test_search_attribute_bootstrap_check.py` (three cases: all present, some missing, `DescribeNamespace` raises `RPCError`).
-- The Temporal integration test suite (`tests/integration/pipelex/temporal/`) with `--temporal-server local` and `--temporal-server testing` profiles for the dev environments that have those configured.
-- The `temporal-e2e-validate` skill against a real Temporal server with the five search attributes registered.
-
-## Decisions settled inline (formerly "open questions")
-
-These were deferred during the design phase; review settled them so the implementer does not re-open them. Captured here as a paper trail.
-
-- **Helper module location.** `pipelex/temporal/tprl/observability.py`. No reason to bikeshed.
-- **One canonical gate test vs two.** **Keep one, delete the other** (Phase 2 above). The kept test is renamed to `test_two_default_activity_calls_in_one_workflow_produce_distinct_activity_ids` so its name reflects the invariant being guarded, not the historic bug.
-- **`pipe_job.pipe.code or "pipe"` fallback.** **No fallback** (Phase 3 above). `code: str` is required-non-empty by Pydantic + `validate_pipe_code_syntax`; the fallback is dead code; silently swallowing an invariant violation is worse than crashing.
-- **Static details "Input" line.** **Use `pipe_job.pipe.inputs.specs` keys** (Phase 3 above). Working-memory keys rejected because they grow at runtime and are sub-pipe-dependent.
-- **Soft-fail warning in CI for in-process server.** **Decide in Phase 4** based on whether the in-process server returns `RPCError`, an empty namespace, or a synthetic one. Two acceptable answers — suppress the warning entirely in in-process mode, or downgrade its level. Either is fine; CI log cleanliness is the deciding criterion.
-
-## Out of scope (per the design doc + this review)
-
-These do **not** ship in this plan. They are listed here so they don't accidentally creep in:
-
-- `workflow.set_current_details(...)` for in-flight progress.
-- Memo population beyond the optional `library_crate` fingerprint.
-- Per-pipe Workflow Type registration.
-- Search attribute schema versioning / migration tooling.
-- An optional `display_label` parameter at the `PipeRun` entry point.
-- **Unifying the two child-spawn paths.** Out of scope (correctly). A Phase 5 follow-up briefly routed both `wf_pipe_run.py` and `temporal_pipe_router.py` through `WorkflowExecutor.execute_child_workflow(...)`; the Phase 6 follow-up reverted it because `WorkflowExecutorFactory.create_executor` reads config to seed `execution_timeout` / `retry_policy` / etc., which would bake config-derived values into the recorded `StartChildWorkflowExecution` command and break replay determinism after any config change. Both call sites now use `workflow.execute_child_workflow(...)` directly and wrap `ChildWorkflowError` as `WorkflowExecutionError` in-place. See "Phase 5 follow-up — Child-spawn path unification (reverted)" above for the full rationale.
-- **`WorkflowIDReusePolicy` choice.** Stays at SDK default `ALLOW_DUPLICATE`. A separate decision (later) is whether `REJECT_DUPLICATE` would catch double-execution bugs at the Temporal layer once workflow IDs are deterministic from `pipeline_run_id`.
diff --git a/wip/temporal-primitives/id-and-naming.html b/wip/temporal-primitives/id-and-naming.html
deleted file mode 100644
index 48ecb18a9..000000000
--- a/wip/temporal-primitives/id-and-naming.html
+++ /dev/null
@@ -1,389 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<title>Temporal IDs &amp; Naming — what changed and why</title>
-<style>
- :root {
- --bg: #0f1115;
- --panel: #161a22;
- --panel-2: #1c2230;
- --line: #2a3142;
- --fg: #e6e9ef;
- --muted: #9aa3b2;
- --accent: #7ad7ff;
- --accent-2: #c9a8ff;
- --bad: #ff8e8e;
- --good: #8ce5b3;
- --warn: #ffd28a;
- }
- html, body { margin: 0; padding: 0; background: var(--bg); color: var(--fg); }
- body { font-family: -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", Roboto, sans-serif; line-height: 1.5; }
- .wrap { max-width: 1100px; margin: 0 auto; padding: 32px 24px 64px; }
- h1 { font-size: 30px; margin: 0 0 8px; font-weight: 700; letter-spacing: -0.01em; }
- h2 { font-size: 22px; margin: 40px 0 12px; padding-top: 18px; border-top: 1px solid var(--line); letter-spacing: -0.01em; }
- h3 { font-size: 16px; margin: 22px 0 8px; color: var(--accent); font-weight: 600; }
- h4 { font-size: 14px; margin: 16px 0 6px; color: var(--accent-2); font-weight: 600; letter-spacing: 0.02em; text-transform: uppercase; }
- p, li { font-size: 14.5px; }
- .lede { color: var(--muted); font-size: 15.5px; margin: 0 0 6px; }
- code, pre, .mono { font-family: ui-monospace, SFMono-Regular, "JetBrains Mono", Menlo, monospace; }
- code { background: var(--panel-2); padding: 1px 6px; border-radius: 4px; font-size: 13px; }
- pre {
- background: var(--panel); border: 1px solid var(--line); border-radius: 8px;
- padding: 14px 16px; overflow: auto; font-size: 12.5px; line-height: 1.55;
- }
- pre.diff .add { color: var(--good); display: block; }
- pre.diff .del { color: var(--bad); display: block; }
- pre.diff .ctx { color: var(--muted); display: block; }
- pre.diff .hdr { color: var(--accent); display: block; }
- table { width: 100%; border-collapse: collapse; margin: 8px 0 12px; font-size: 13.5px; }
- th, td { text-align: left; padding: 8px 10px; border-bottom: 1px solid var(--line); vertical-align: top; }
- th { color: var(--muted); font-weight: 600; font-size: 12px; text-transform: uppercase; letter-spacing: 0.05em; }
- .kicker { display: inline-block; padding: 2px 8px; border-radius: 999px; background: var(--panel-2); color: var(--accent); font-size: 12px; letter-spacing: 0.04em; }
- .row { display: flex; gap: 16px; flex-wrap: wrap; }
- .card { flex: 1 1 320px; background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 14px 16px; }
- .card.bad { border-color: #5a2a2a; }
- .card.good { border-color: #295a3a; }
- .pill { display: inline-block; padding: 2px 8px; border-radius: 999px; font-size: 11.5px; font-weight: 600; letter-spacing: 0.04em; }
- .pill.before { background: #3a1d22; color: var(--bad); }
- .pill.after { background: #1d3a2c; color: var(--good); }
- .muted { color: var(--muted); }
- .small { font-size: 12.5px; }
- .grid-2 { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; }
- @media (max-width: 720px) { .grid-2 { grid-template-columns: 1fr; } }
- .diagram { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 16px; margin: 8px 0; }
- .nest { font-family: ui-monospace, monospace; font-size: 13px; line-height: 1.7; }
- .nest .key { color: var(--accent); }
- .nest .val { color: var(--good); }
- .nest .muted { color: var(--muted); }
- .legend { font-size: 12px; color: var(--muted); margin-top: 4px; }
- .tag { display: inline-block; padding: 1px 7px; border-radius: 4px; font-size: 11.5px; background: #1d2a3a; color: var(--accent); margin-right: 4px; }
- .check { color: var(--good); }
- .x { color: var(--bad); }
- .note { background: var(--panel-2); border-left: 3px solid var(--accent); padding: 10px 12px; border-radius: 4px; margin: 12px 0; font-size: 13.5px; color: var(--muted); }
- .note strong { color: var(--fg); }
- ul.tight li { margin: 2px 0; }
-</style>
-</head>
-<body>
-<div class="wrap">
-
-<span class="kicker">Temporal primitives · session note</span>
-<h1>Temporal IDs &amp; Naming — what changed, and why each choice</h1>
-<p class="lede">A walk-through of the redesign on <code>feature/Temporal-ids</code>. We rebuilt Pipelex's Temporal identity layer around the principle: <em>Pipelex already mints the right IDs — thread them straight through Temporal's primitives, don't invent new ones</em>. Phases 1–6 are shipped; this note explains the shape so you can navigate the diff without reading every plan file.</p>
-
-<h2>1. The two problems we were fixing</h2>
-
-<div class="grid-2">
- <div class="card bad">
- <span class="pill before">BEFORE — bug</span>
- <h3 style="margin-top:8px">Activity ID collisions</h3>
- <p>Pipelex was customizing <code>activity_id="craft-text"</code> for LLM-text calls. When a pipe made two LLM calls in the same workflow run, Temporal rejected the second one because activity IDs must be unique among <em>open</em> activities of a run. The root cause was a disambiguator living on the wrong layer — at the worker, instead of on the workflow.</p>
- </div>
- <div class="card bad">
- <span class="pill before">BEFORE — confusing IDs</span>
- <h3 style="margin-top:8px">Opaque dashboard rows</h3>
- <p>Workflow IDs looked like <code class="small">EdgdJ-HR5fd-TemporalPipeRun-pipe-router</code> — a truncated session prefix, a random short-uuid, and the calling class name. No way to filter by pipe, no way to find a run from our app's pipeline_run_id, no semantic context in the Workflow Type column either (everything registered as <code>wf_pipe_run</code> / <code>wf_pipe_router</code>).</p>
- </div>
-</div>
-
-<h2>2. The Temporal identity primitives, distilled</h2>
-
-<p>Temporal makes a hard distinction between <strong>IDs</strong> (per-instance, unique, runtime) and <strong>Types</strong> (per-class, registered, static). Get those mixed up and the design will be wrong before it starts.</p>
-
-<table>
- <thead><tr><th>Primitive</th><th>What it is</th><th>UI visibility</th><th>Determinism rule</th></tr></thead>
- <tbody>
- <tr><td><strong>Workflow ID</strong></td><td>User-supplied <em>per-instance</em> string. Unique among open workflows in a namespace.</td><td>Primary clickable identifier in every list / detail view.</td><td>Set client-side: anything. Set inside workflow code (child): must be replay-safe.</td></tr>
- <tr><td><strong>Run ID</strong></td><td>Server-assigned UUID, one per run inside a chain.</td><td>Shown next to Workflow ID. Disambiguates retries / continue-as-new.</td><td>You don't control it.</td></tr>
- <tr><td><strong>Workflow Type</strong></td><td>Registered class name. Static. Same set on every worker polling the queue.</td><td>"Type" column in the list view.</td><td>n/a — registered at worker boot.</td></tr>
- <tr><td><strong>Activity ID</strong></td><td>Per-invocation string. Unique among <em>open</em> activities of a run.</td><td>Shown in Event History next to Activity Type.</td><td>Inside workflow code: replay-safe. SDK default = sequential integer by history position.</td></tr>
- <tr><td><strong>Activity Type</strong></td><td>Registered function name. Static.</td><td>"Activity Type" in Event History — tells you "this was an LLM call".</td><td>n/a — registered at worker boot.</td></tr>
- <tr><td><strong>Task Queue</strong></td><td>Routing channel that workers poll.</td><td>Shown per-execution; filterable.</td><td>n/a — operational.</td></tr>
- <tr><td><strong>Search Attributes</strong></td><td>Typed, indexed, filterable key/value pairs.</td><td>Filterable columns in the list view.</td><td>n/a — derived from workflow input.</td></tr>
- <tr><td><strong>Static Summary</strong> / <strong>Details</strong></td><td>200-byte / 20 KB Markdown set at workflow start.</td><td>Purple text in list / detail views.</td><td>Set at submit time — no replay concern.</td></tr>
- <tr><td><strong>Per-activity Summary</strong></td><td>200-byte Markdown set per <code>execute_activity</code> call.</td><td>Purple text on <code>ActivityTaskScheduled</code> events.</td><td>Must be a pure function of workflow input.</td></tr>
- </tbody>
-</table>
-
-<h2>3. The mapping we picked</h2>
-
-<p>One sheet, one decision per row. <strong>No information is lost on the way down, no information is invented on the way up.</strong></p>
-
-<table>
- <thead><tr><th>Pipelex concept</th><th>Temporal primitive</th><th>Why</th></tr></thead>
- <tbody>
- <tr><td><code>pipeline_run_id</code> (existing UUID)</td><td>Workflow ID (top-level)</td><td>Already unique. Already used by our app. No reason to truncate or wrap it.</td></tr>
- <tr><td>Implicit "child role"</td><td>Slash-suffix on parent's Workflow ID</td><td>Path-like, trivially parseable with <code>split("/")</code>.</td></tr>
- <tr><td>Pipe family</td><td>Workflow Type (registered: <code>wf_pipe_run</code>, <code>wf_pipe_router</code>)</td><td>Two is enough. Filter by pipe via search attributes instead of registering hundreds of types.</td></tr>
- <tr><td>Generation method</td><td>Activity Type (registered: <code>act_llm_gen_text</code>, …)</td><td>Already good — bug was at the ID layer, not the type layer.</td></tr>
- <tr><td>One call to a generator method</td><td>Activity ID (SDK-default integer)</td><td>Stop customizing. Let Temporal assign <code>"1"</code>, <code>"2"</code>, … per history position. Deterministic by construction.</td></tr>
- <tr><td><code>pipe_code</code></td><td>Search attribute <code>PipeCode</code> + leading segment of static_summary</td><td>Filterable column + readable column.</td></tr>
- <tr><td><code>domain_code</code> / <code>user_id</code> / <code>session_id</code></td><td>Search attributes <code>DomainCode</code> / <code>UserId</code> / <code>SessionId</code></td><td>Filterable. Five total: <code>PipeCode</code>, <code>PipelineRunId</code>, <code>SessionId</code>, <code>UserId</code>, <code>DomainCode</code>.</td></tr>
- <tr><td>Pipe description</td><td>Tail of static_summary</td><td>e.g. <code>translate_doc — Translate EN→FR</code>. 200-byte Markdown.</td></tr>
- <tr><td>Per-call context (model handle, class name…)</td><td>Per-activity <code>summary=</code></td><td>This is the right place — not <code>activity_id</code>.</td></tr>
- </tbody>
-</table>
-
-<h2>4. Workflow ID shape</h2>
-
-<h3>Top-level</h3>
-<div class="diagram">
- <div class="nest">
- <span class="muted"># Format:</span><br>
- <span class="key">{env_prefix}</span><span class="val">{pipeline_run_id}</span>
- </div>
- <p class="legend">
- <code>env_prefix</code> is one of <code>ut-</code> (unit test), <code>ci-</code>, <code>cc-</code> (codex cloud), <code>cct-</code>, or empty for <code>NORMAL</code>.<br>
- <code>pipeline_run_id</code> is Pipelex's existing UUID from <code>JobMetadata.pipeline_run_id</code> — set by <code>PipelineFactory.make_pipeline_run_id</code>.
- </p>
- <p class="small mono">Examples:<br>
- <span class="muted">ut-</span>3f9c8b2a-1e4d-4f5b-9c7a-2d8e1f0a6b3c &nbsp;<span class="muted"># unit test</span><br>
- 3f9c8b2a-1e4d-4f5b-9c7a-2d8e1f0a6b3c &nbsp;<span class="muted"># production</span>
- </p>
-</div>
-
-<h3>Child workflows — slash-nested path</h3>
-<div class="diagram">
- <p class="small">Separator is <code>/</code> (not <code>-</code>): UUIDs already contain <code>-</code>, and a fresh separator keeps the path structure unambiguous.</p>
- <pre class="mono"><span style="color:var(--muted)">// Top-level </span>ut-3f9c…b3c
-<span style="color:var(--muted)">// Fixed-role child </span>ut-3f9c…b3c/pipe-router
-<span style="color:var(--muted)">// Dynamic sub-pipe child </span>ut-3f9c…b3c/pipe-router/translate_doc-7c1e2f8a
-<span style="color:var(--muted)">// Nested router </span>ut-3f9c…b3c/pipe-router/translate_doc-7c1e2f8a/extract_text-4d9b1c83
-</pre>
- <p class="legend">
- Two suffix conventions:<br>
- • <strong>Fixed-role child</strong> (1:1, known role): <code>pipe-router</code> — used by <code>wf_pipe_run</code> spawning its sole <code>wf_pipe_router</code> child.<br>
- • <strong>Dynamic sub-pipe child</strong>: <code>{pipe_code}-{8-hex-chars}</code> — used inside the router when dispatching a sub-pipe. The 8 hex chars come from <code>workflow.uuid4()</code>, which is <em>replay-safe</em> (Temporal's <code>workflow.uuid4</code> is deterministic; stdlib <code>uuid.uuid4</code> is forbidden inside workflows).
- </p>
-</div>
-
-<h3>The construction site, in code</h3>
-<pre class="diff"><span class="hdr">// pipelex/temporal/temporal_manager.py — make_top_workflow_id</span>
-<span class="del">- def make_top_workflow_id(self, base_id: str) -&gt; str:
-- # Truncated session + random shortuuid + caller class name
-- return f"{prefix}{self.session_id[:5]}-{random_short_uuid()}-{base_id}"</span>
-<span class="add">+ def make_top_workflow_id(self, pipeline_run_id: str) -&gt; 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}"</span>
-</pre>
-
-<pre class="diff"><span class="hdr">// pipelex/temporal/tprl_pipe/temporal_pipe_router.py — child branch</span>
-<span class="ctx"> if is_in_temporal_workflow():
- parent_workflow_id = workflow.info().workflow_id</span>
-<span class="add">+ # 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),
-+ )</span>
-</pre>
-
-<div class="note">
- <strong>Pipeline-run-chain semantic shift.</strong> Because the Workflow ID is now <code>{env_prefix}{pipeline_run_id}</code>, callers that pass a stable <code>pipeline_run_id</code> to <code>PipelineFactory.make_pipeline</code> and re-execute now land on the <em>same</em> Temporal Workflow Execution Chain (with a fresh <code>run_id</code>, under SDK-default <code>ALLOW_DUPLICATE</code>). The old behavior produced a fresh workflow_id per execution <em>by accident</em>, via the random short-uuid. Documented behavior now, not a bug.
-</div>
-
-<h2>5. Activity ID — let the SDK do its job</h2>
-
-<p>Pipelex no longer passes <code>activity_id=</code> anywhere. The Python SDK auto-assigns sequential integers (<code>"1"</code>, <code>"2"</code>, …) per workflow run. They are:</p>
-
-<ul class="tight">
- <li><span class="check">✓</span> Unique per <code>(workflow_id, run_id)</code> by construction.</li>
- <li><span class="check">✓</span> Deterministic across replay (assigned by history position).</li>
- <li><span class="check">✓</span> Visible in Event History next to the Activity Type and per-activity summary.</li>
-</ul>
-
-<p>Per-call meaning lives in <code>summary=</code>. Every <code>make_*</code> method in <code>ContentGeneratorInWorkflow</code> looks like this:</p>
-
-<pre class="mono"><span style="color:var(--accent)">async def</span> make_llm_text(self, job_metadata, llm_setting_main, llm_prompt_for_text) -&gt; 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()
- <span style="color:var(--accent)">return await</span> 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, <span class="muted"># task_queue + timeouts + retry, see queues-and-options.html</span>
- )</pre>
-
-<p>Pipe authors never think about Temporal IDs: identity flows entirely through <code>JobMetadata.pipeline_run_id</code>, the SDK assigns the activity ID, the per-call summary carries the call-specific meaning.</p>
-
-<h2>6. Observability — three primitives, zero new fields</h2>
-
-<p>We weren't using any of Temporal's display primitives. Now we use all the relevant ones, in three layers.</p>
-
-<h3>Static summary (workflow list view)</h3>
-<p>Set once at workflow start. 200-byte single-line Markdown.</p>
-<pre><span class="mono">{pipe_code} — {description}</span>
-<span class="mono">// e.g. "translate_doc — Translate a document from English to French"</span></pre>
-
-<h3>Static details (workflow detail view)</h3>
-<p>Set once at workflow start. 20 KB Markdown table.</p>
-<pre><span class="mono">| Field | Value |
-|---------------|------------------------------------------------|
-| Pipe | `translate_doc` |
-| Domain | `documents` |
-| Pipeline run | `3f9c8b2a-1e4d-4f5b-9c7a-2d8e1f0a6b3c` |
-| User | `acme-corp` |
-| Session | `EdgdJ7Yk4Q3HF2pXyZv9w8` |
-| Library crate | `[email protected]` |
-| Input | `source_text`, `target_language` |</span></pre>
-
-<h3>Per-activity summary (Event History)</h3>
-<p>Set per <code>workflow.execute_activity(...)</code> call. 200 bytes. Where the call-specific meaning lives.</p>
-<table>
- <thead><tr><th>Method</th><th>Summary format</th></tr></thead>
- <tbody>
- <tr><td><code>make_llm_text</code></td><td><code>LLM text · pipe={code} · model={handle}</code></td></tr>
- <tr><td><code>make_object</code></td><td><code>LLM object · pipe={code} · class={class_name}</code></td></tr>
- <tr><td><code>make_object_list</code></td><td><code>LLM object list · pipe={code} · class={class_name}</code></td></tr>
- <tr><td><code>make_single_image</code></td><td><code>Img gen 1× · pipe={code} · model={handle}</code></td></tr>
- <tr><td><code>make_image_list</code></td><td><code>Img gen N× · pipe={code} · model={handle} · n={count}</code></td></tr>
- <tr><td><code>make_templated_text</code></td><td><code>Templated text · pipe={code}</code></td></tr>
- <tr><td><code>make_extract_pages</code></td><td><code>Extract pages · pipe={code} · handle={extract_handle}</code></td></tr>
- </tbody>
-</table>
-
-<p>Formatting is centralized in one place — <code>pipelex/temporal/tprl/observability.py</code> — so call sites stay thin:</p>
-<pre class="mono"><span style="color:var(--accent)">build_search_attributes</span>(pipe_job) <span style="color:var(--muted)"># 5 typed keys → TypedSearchAttributes</span>
-<span style="color:var(--accent)">build_static_summary</span>(pipe) <span style="color:var(--muted)"># "{code} — {description}", 200B clamp</span>
-<span style="color:var(--accent)">build_static_details</span>(pipe_job) <span style="color:var(--muted)"># markdown table, 20KB clamp</span>
-<span style="color:var(--accent)">build_activity_summary</span>(label, metadata, <span style="color:var(--muted)"># "{label} · pipe={code} · {extras…}"</span>
- extras={...})</pre>
-
-<h2>7. Search attributes — the filterable layer</h2>
-
-<p>Five custom Keyword attributes, registered once per namespace, set on every workflow start:</p>
-
-<table>
- <thead><tr><th>Attribute</th><th>Type</th><th>Source</th></tr></thead>
- <tbody>
- <tr><td><code>PipeCode</code></td><td>Keyword</td><td><code>pipe_job.pipe.code</code></td></tr>
- <tr><td><code>PipelineRunId</code></td><td>Keyword</td><td><code>pipe_job.job_metadata.pipeline_run_id</code></td></tr>
- <tr><td><code>SessionId</code></td><td>Keyword</td><td>stamped at submitter boundary from <code>TemporalManager.session_id</code></td></tr>
- <tr><td><code>UserId</code></td><td>Keyword</td><td><code>pipe_job.job_metadata.user_id</code></td></tr>
- <tr><td><code>DomainCode</code></td><td>Keyword</td><td><code>pipe_job.pipe.domain_code</code></td></tr>
- </tbody>
-</table>
-
-<h3>Hard-fail at worker boot (Phase 6)</h3>
-<p>A real Temporal cluster rejects every <code>StartWorkflowExecution</code> 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:</p>
-
-<pre class="mono">$ 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</pre>
-
-<h3>The escape hatch</h3>
-<pre><span class="mono"># pipelex.toml — turn off custom attributes entirely
-[temporal.search_attributes]
-enabled = false
-attributes = ["PipeCode", "PipelineRunId", "SessionId", "UserId", "DomainCode"]
-</span></pre>
-<ul class="tight">
- <li><code>enabled = false</code> 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).</li>
- <li>The validator rejects unknown attribute names so typos like <code>"PipelineRunID"</code> fail at config load instead of silently producing no attribute.</li>
- <li>The new <code>pipelex setup-temporal-namespace</code> CLI wraps <code>OperatorService.AddSearchAttributes</code> so operators don't need a separate Temporal CLI install. <code>--dry-run</code> prints the equivalent raw command for handing off to a namespace admin.</li>
-</ul>
-
-<h2>8. Why the design is replay-safe</h2>
-
-<p>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.</p>
-
-<table>
- <thead><tr><th>Choice</th><th>Why it is replay-safe</th></tr></thead>
- <tbody>
- <tr><td>Top-level Workflow ID set on the submitter</td><td>Set outside workflow code; no replay concern.</td></tr>
- <tr><td>SDK-default <code>activity_id</code></td><td>Server-assigned by history position.</td></tr>
- <tr><td>Child Workflow ID disambiguator uses <code>workflow.uuid4()</code></td><td>Temporal's <code>workflow.uuid4()</code> is deterministic by design (stdlib <code>uuid.uuid4()</code> is forbidden in workflow code).</td></tr>
- <tr><td>Child Workflow ID uses <code>pipe_job.pipe.code</code></td><td>Read from workflow input, not from outside state.</td></tr>
- <tr><td>Search attribute values</td><td>Derived from <code>pipe_job</code> + <code>JobMetadata</code> (workflow input).</td></tr>
- <tr><td>Static summary / details</td><td>Set at submit time, outside workflow code.</td></tr>
- <tr><td>Per-activity summary</td><td>Pure function of <code>job_metadata</code> + activity input — no I/O, time, or randomness.</td></tr>
- <tr><td><code>SessionId</code> stamped at the submitter boundary</td><td>Threaded through every child workflow via <code>JobMetadata.session_id</code> so child-workflow starts stay byte-equal across replays even after a worker restart.</td></tr>
- </tbody>
-</table>
-
-<div class="note">
- <strong>The invariant to defend in code review.</strong> Nothing on the activity-dispatch path may read worker-singleton state. If any future change introduces that, replays diverge and Temporal will reject them with a non-determinism error.
-</div>
-
-<h2>9. Before / after — the dashboard view</h2>
-
-<div class="grid-2">
- <div class="card bad">
- <span class="pill before">BEFORE</span>
- <table class="small">
- <thead><tr><th>Workflow ID</th><th>Type</th><th>PipeCode</th></tr></thead>
- <tbody>
- <tr><td><code>EdgdJ-HR5fd-TemporalPipeRun-pipe-router</code></td><td><code>wf_pipe_run</code></td><td><em>(unset)</em></td></tr>
- <tr><td><code>EdgdJ-HR5fd-TemporalPipeRun-pipe-router</code> (child)</td><td><code>wf_pipe_router</code></td><td><em>(unset)</em></td></tr>
- </tbody>
- </table>
- </div>
- <div class="card good">
- <span class="pill after">AFTER</span>
- <table class="small">
- <thead><tr><th>Workflow ID</th><th>Type</th><th>PipeCode</th><th>Summary</th></tr></thead>
- <tbody>
- <tr><td><code>ut-3f9c…b3c</code></td><td><code>wf_pipe_run</code></td><td><code>translate_doc</code></td><td>translate_doc — Translate EN→FR</td></tr>
- <tr><td><code>ut-3f9c…b3c/pipe-router</code></td><td><code>wf_pipe_router</code></td><td><code>translate_doc</code></td><td>translate_doc — Translate EN→FR</td></tr>
- <tr><td><code>ut-3f9c…b3c/pipe-router/extract_text-4d9b1c83</code></td><td><code>wf_pipe_router</code></td><td><code>extract_text</code></td><td>extract_text — Extract paragraphs</td></tr>
- </tbody>
- </table>
- </div>
-</div>
-
-<h3>Event History — one workflow's activities</h3>
-<pre class="diff"><span class="hdr">// BEFORE</span>
-<span class="del">ActivityTaskScheduled: id=craft-text, type=act_llm_gen_text
-ActivityTaskScheduled: id=craft-text, type=act_llm_gen_text ← collision, workflow crashes</span>
-
-<span class="hdr">// AFTER</span>
-<span class="add">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</span>
-</pre>
-
-<h2>10. Where to look</h2>
-
-<ul class="tight">
- <li>The decision log: <code>wip/temporal-primitives/01-id-and-naming-design.md</code></li>
- <li>The per-phase execution: <code>wip/temporal-primitives/02-id-and-naming-plan.md</code></li>
- <li>The reference inventory: <code>wip/temporal-primitives/00-temporal-id-primitives.md</code></li>
- <li>The formatting helpers: <code>pipelex/temporal/tprl/observability.py</code></li>
- <li>The bootstrap check + CLI: <code>pipelex/temporal/tprl/namespace_check.py</code>, <code>pipelex/cli/commands/setup_temporal_namespace_cmd.py</code></li>
- <li>Companion note: <a href="queues-and-options.html" style="color:var(--accent)">queues-and-options.html</a> — per-activity routing, per-queue options, worker-runtime profiles</li>
-</ul>
-
-</div>
-</body>
-</html>
diff --git a/wip/temporal-primitives/queues-and-options.html b/wip/temporal-primitives/queues-and-options.html
deleted file mode 100644
index 5af986001..000000000
--- a/wip/temporal-primitives/queues-and-options.html
+++ /dev/null
@@ -1,448 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8">
-<title>Temporal queues &amp; options — per-activity routing, per-queue tuning, runtime profiles</title>
-<style>
- :root {
- --bg: #0f1115;
- --panel: #161a22;
- --panel-2: #1c2230;
- --line: #2a3142;
- --fg: #e6e9ef;
- --muted: #9aa3b2;
- --accent: #7ad7ff;
- --accent-2: #c9a8ff;
- --bad: #ff8e8e;
- --good: #8ce5b3;
- --warn: #ffd28a;
- }
- html, body { margin: 0; padding: 0; background: var(--bg); color: var(--fg); }
- body { font-family: -apple-system, BlinkMacSystemFont, "Inter", "Segoe UI", Roboto, sans-serif; line-height: 1.5; }
- .wrap { max-width: 1100px; margin: 0 auto; padding: 32px 24px 64px; }
- h1 { font-size: 30px; margin: 0 0 8px; font-weight: 700; letter-spacing: -0.01em; }
- h2 { font-size: 22px; margin: 40px 0 12px; padding-top: 18px; border-top: 1px solid var(--line); letter-spacing: -0.01em; }
- h3 { font-size: 16px; margin: 22px 0 8px; color: var(--accent); font-weight: 600; }
- h4 { font-size: 14px; margin: 16px 0 6px; color: var(--accent-2); font-weight: 600; letter-spacing: 0.02em; text-transform: uppercase; }
- p, li { font-size: 14.5px; }
- .lede { color: var(--muted); font-size: 15.5px; margin: 0 0 6px; }
- code, pre, .mono { font-family: ui-monospace, SFMono-Regular, "JetBrains Mono", Menlo, monospace; }
- code { background: var(--panel-2); padding: 1px 6px; border-radius: 4px; font-size: 13px; }
- pre {
- background: var(--panel); border: 1px solid var(--line); border-radius: 8px;
- padding: 14px 16px; overflow: auto; font-size: 12.5px; line-height: 1.55;
- }
- pre.diff .add { color: var(--good); display: block; }
- pre.diff .del { color: var(--bad); display: block; }
- pre.diff .ctx { color: var(--muted); display: block; }
- pre.diff .hdr { color: var(--accent); display: block; }
- table { width: 100%; border-collapse: collapse; margin: 8px 0 12px; font-size: 13.5px; }
- th, td { text-align: left; padding: 8px 10px; border-bottom: 1px solid var(--line); vertical-align: top; }
- th { color: var(--muted); font-weight: 600; font-size: 12px; text-transform: uppercase; letter-spacing: 0.05em; }
- .kicker { display: inline-block; padding: 2px 8px; border-radius: 999px; background: var(--panel-2); color: var(--accent); font-size: 12px; letter-spacing: 0.04em; }
- .row { display: flex; gap: 16px; flex-wrap: wrap; }
- .card { flex: 1 1 320px; background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 14px 16px; }
- .card.bad { border-color: #5a2a2a; }
- .card.good { border-color: #295a3a; }
- .pill { display: inline-block; padding: 2px 8px; border-radius: 999px; font-size: 11.5px; font-weight: 600; letter-spacing: 0.04em; }
- .pill.before { background: #3a1d22; color: var(--bad); }
- .pill.after { background: #1d3a2c; color: var(--good); }
- .muted { color: var(--muted); }
- .small { font-size: 12.5px; }
- .grid-2 { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; }
- @media (max-width: 720px) { .grid-2 { grid-template-columns: 1fr; } }
- .note { background: var(--panel-2); border-left: 3px solid var(--accent); padding: 10px 12px; border-radius: 4px; margin: 12px 0; font-size: 13.5px; color: var(--muted); }
- .note strong { color: var(--fg); }
- ul.tight li { margin: 2px 0; }
- .diagram { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 16px; margin: 8px 0; }
- /* Layered overlay diagram */
- .stack { display: flex; flex-direction: column; gap: 8px; max-width: 780px; }
- .stack .layer {
- border-radius: 8px; padding: 10px 14px; border: 1px solid var(--line);
- display: flex; align-items: center; gap: 12px; font-size: 13.5px;
- }
- .stack .layer .num {
- width: 24px; height: 24px; border-radius: 50%; background: var(--panel-2); color: var(--accent);
- display: inline-flex; align-items: center; justify-content: center; font-weight: 700; flex-shrink: 0; font-size: 12px;
- }
- .layer.baseline { background: linear-gradient(90deg, #1a1f2c 0%, #161a22 100%); }
- .layer.queue { background: linear-gradient(90deg, #1d2a3a 0%, #161a22 100%); }
- .layer.handle { background: linear-gradient(90deg, #2a1d3a 0%, #161a22 100%); }
- .layer.result { background: linear-gradient(90deg, #1d3a2c 0%, #161a22 100%); border-color: #295a3a; }
- .layer .label { color: var(--muted); font-size: 11.5px; text-transform: uppercase; letter-spacing: 0.05em; }
- .arrow { color: var(--muted); font-size: 18px; text-align: center; padding: 2px 0; }
- .pipeflow {
- display: grid; grid-template-columns: 1fr auto 1fr auto 1fr; gap: 8px; align-items: center;
- font-family: ui-monospace, monospace; font-size: 12.5px;
- }
- .pipeflow .box { background: var(--panel-2); border: 1px solid var(--line); border-radius: 6px; padding: 8px 10px; text-align: center; }
- .pipeflow .sep { color: var(--muted); font-size: 18px; text-align: center; }
- .legend { font-size: 12px; color: var(--muted); margin-top: 4px; }
- .tag { display: inline-block; padding: 1px 7px; border-radius: 4px; font-size: 11.5px; background: #1d2a3a; color: var(--accent); margin-right: 4px; }
- .check { color: var(--good); }
- .x { color: var(--bad); }
-</style>
-</head>
-<body>
-<div class="wrap">
-
-<span class="kicker">Temporal primitives · session note</span>
-<h1>Temporal queues &amp; options — per-activity routing, per-queue tuning, worker-runtime profiles</h1>
-<p class="lede">The companion to <a href="id-and-naming.html" style="color:var(--accent)">id-and-naming.html</a>. Where the ID work was about <em>identity</em>, this work is about <em>knobs</em>: which task queue an activity dispatches to, what timeouts and retry policy apply, how the worker process itself is tuned. Three independent config layers, each addressing a real operational pain.</p>
-
-<h2>1. The three things this layer lets you do</h2>
-
-<div class="row">
- <div class="card">
- <span class="pill after">CAPABILITY #1</span>
- <h3 style="margin-top:8px">Route by activity and by handle</h3>
- <p>Send each activity (and optionally each handle within an activity) to a dedicated task queue. Isolate GPU-bound image-gen runners from cheap LLM workers, route a specific OCR backend to a dedicated queue, scale OpenAI vs Anthropic pools independently.</p>
- </div>
- <div class="card">
- <span class="pill after">CAPABILITY #2</span>
- <h3 style="margin-top:8px">Tune dispatch per queue and per handle</h3>
- <p>Set <code>start_to_close_timeout</code>, retry policy, heartbeat, and rate caps per task queue. Override for a single handle when one model variant on a backend needs different tuning. The workflow's own deadline is no longer spent by a single in-flight activity.</p>
- </div>
- <div class="card">
- <span class="pill after">CAPABILITY #3</span>
- <h3 style="margin-top:8px">Specialize worker processes</h3>
- <p>Named worker-runtime profiles bundle the <code>Worker(...)</code> tuning (slots, pollers, heartbeat throttles, graceful shutdown). One worker process picks one profile via <code>pipelex worker --profile &lt;name&gt;</code>, plus a <code>--scope</code> selecting which activities it registers.</p>
- </div>
-</div>
-
-<h2>2. The shape of the solution — three orthogonal layers</h2>
-
-<div class="diagram">
- <div class="pipeflow">
- <div class="box">
- <strong>Layer A</strong><br>
- <span class="muted">where it goes</span><br>
- <code>activity_queues</code>
- </div>
- <div class="sep">+</div>
- <div class="box">
- <strong>Layer B</strong><br>
- <span class="muted">how it's dispatched</span><br>
- <code>queue_options</code><br>
- <code>handle_options</code>
- </div>
- <div class="sep">+</div>
- <div class="box">
- <strong>Layer C</strong><br>
- <span class="muted">how the worker behaves</span><br>
- <code>worker_runtime_profiles</code>
- </div>
- </div>
- <p class="legend">
- <strong>Layer A — routing.</strong> Per activity, per handle, which task queue do we dispatch to? <em>Submitter-side.</em><br>
- <strong>Layer B — options.</strong> For that resolved queue (and optionally that specific handle), what timeouts and retry policy apply? <em>Submitter-side.</em><br>
- <strong>Layer C — worker.</strong> Inside one worker process, how do we tune slots/pollers/heartbeats? <em>Worker-side, selected via <code>--profile</code>.</em>
- </p>
-</div>
-
-<h2>3. Layer A — per-activity, per-handle routing</h2>
-
-<p>The <code>activity_queues</code> table on <code>WorkerConfig</code> is the entry point. Each entry declares a default queue for one activity and an optional <code>by_handle</code> map keyed by runtime handle (LLM model handle, image-gen handle, extract handle).</p>
-
-<pre><span class="mono"># pipelex.toml
-[temporal.worker_config]
-default_task_queue = "temporal_task_queue"
-default_activity_start_to_close_timeout = "0:10:00"
-
-# Route LLM text by model family. Anthropic runs on a dedicated pool;
-# everything else falls back to the activity default.
-[temporal.worker_config.activity_queues.act_llm_gen_text]
-default = "llm-default-queue"
-by_handle = {
- "claude-4.6-sonnet" = "anthropic-queue",
- "claude-4.6-opus" = "anthropic-queue",
- "gpt-5.1" = "openai-queue",
-}
-
-# Image generation on a GPU pool.
-[temporal.worker_config.activity_queues.act_img_gen_images]
-default = "img-gen-gpu-queue"
-
-# Extract: route Azure Doc Intel separately from Mistral OCR.
-[temporal.worker_config.activity_queues.act_extract_gen_extract_pages]
-default = "extract-default-queue"
-by_handle = { "azure-doc-intel" = "extract-azure-queue" }</span></pre>
-
-<h3>The resolver — three steps, last-wins</h3>
-<pre class="mono"><span style="color:var(--accent)">WorkerConfig.resolve_queue</span>(activity_name, routing_key) -&gt; str | None
-
- 1. activity_queues[activity_name].by_handle[routing_key] <span class="muted"># most specific</span>
- 2. activity_queues[activity_name].default <span class="muted"># activity-level default</span>
- 3. self.default_task_queue <span class="muted"># worker-wide default</span></pre>
-
-<div class="note">
- <strong>Hybrid fallback semantic.</strong> When <code>activity_queues</code> is <em>fully empty</em> (default config, no routing configured), <code>resolve_queue</code> returns <code>None</code> — and the dispatch path then <em>omits</em> the <code>task_queue</code> kwarg so Temporal routes the activity to the workflow's own queue. This preserves the pre-v1 single-queue default and the <code>with_conditional_worker</code> test pattern. As soon as any <code>activity_queues</code> entry exists, the operator has opted into routing topology and unmapped activities fall back explicitly to <code>default_task_queue</code>.
-</div>
-
-<h2>4. Layer B — per-queue and per-handle options</h2>
-
-<p><code>queue_options</code> declares the submitter options (timeouts, retry policy, queue-level rate cap) for one task queue. <code>handle_options</code> (inside an <code>activity_queues</code> entry) declares the rare per-handle override on top of the queue's options.</p>
-
-<pre><span class="mono"># pipelex.toml — queue-level submitter options
-[temporal.queue_options.temporal_task_queue]
-start_to_close_timeout = "0:10:00"
-heartbeat_timeout = "0:01:00"
-max_task_queue_activities_per_second = 1000
-
-[temporal.queue_options.anthropic-queue]
-start_to_close_timeout = "0:05:00"
-heartbeat_timeout = "0:01:00"
-max_task_queue_activities_per_second = 50
-[temporal.queue_options.anthropic-queue.retry_policy_config]
-initial_interval = "0:00:01"
-backoff_coefficient = 2.0
-maximum_interval = "0:01:00"
-maximum_attempts = 5
-# IMPORTANT: overlay uses ``_extra`` (additive), not the baseline field name.
-non_retryable_error_types_extra = ["AnthropicAuthError"]
-
-[temporal.queue_options.img-gen-gpu-queue]
-start_to_close_timeout = "0:30:00" # GPU calls take longer
-heartbeat_timeout = "0:02:00"
-max_task_queue_activities_per_second = 10
-
-# Rare per-handle override for ONE long-context model on the anthropic queue
-[temporal.worker_config.activity_queues.act_llm_gen_text.handle_options."claude-4.6-opus"]
-start_to_close_timeout = "0:15:00"</span></pre>
-
-<h3>Resolution — three layers, last-wins for scalars</h3>
-<div class="diagram">
- <div class="stack">
- <div class="layer baseline">
- <span class="num">1</span>
- <div>
- <span class="label">baseline</span><br>
- <code>worker_config.default_activity_start_to_close_timeout</code><br>
- <code>worker_config.default_activity_heartbeat_timeout</code><br>
- <code>worker_config.retry_policy_config</code>
- </div>
- </div>
- <div class="arrow">↓ overlay</div>
- <div class="layer queue">
- <span class="num">2</span>
- <div>
- <span class="label">queue_options[resolved_queue]</span><br>
- Per-queue timeouts, retry overlay, queue-level rate cap.
- </div>
- </div>
- <div class="arrow">↓ overlay</div>
- <div class="layer handle">
- <span class="num">3</span>
- <div>
- <span class="label">activity_queues[activity].handle_options[handle]</span><br>
- Per-handle timeout / retry override for a single model variant.
- </div>
- </div>
- <div class="arrow">↓ result</div>
- <div class="layer result">
- <span class="num">✓</span>
- <div>
- <span class="label">DispatchOptions</span><br>
- <code>task_queue</code> · <code>start_to_close_timeout</code> · <code>schedule_to_close_timeout</code> · <code>schedule_to_start_timeout</code> · <code>heartbeat_timeout</code> · <code>retry_policy</code>
- </div>
- </div>
- </div>
-</div>
-
-<h3>The additive rule for non_retryable_error_types</h3>
-<p>Scalars (timeouts, attempts, intervals) are <strong>last-wins</strong>. <code>non_retryable_error_types</code> is <strong>additive</strong> — every layer can only <em>add</em> to the no-retry list, never remove from it. The schema enforces this asymmetry by splitting the retry-policy model in two:</p>
-
-<table>
- <thead><tr><th>Layer</th><th>Class</th><th>Field</th></tr></thead>
- <tbody>
- <tr><td>Baseline only</td><td><code>RetryPolicyConfig</code></td><td><code>non_retryable_error_types: list[str]</code> — the main list</td></tr>
- <tr><td>Queue / handle overlay</td><td><code>RetryPolicyConfigOverlay</code></td><td><code>non_retryable_error_types_extra: list[str]</code> — additive</td></tr>
- </tbody>
-</table>
-<p>Pydantic's <code>extra="forbid"</code> rejects the wrong field on each layer, so a config like <code>queue_options.foo.retry_policy_config.non_retryable_error_types = [...]</code> fails at load time with a clear validation error — you can't accidentally bypass the additive rule.</p>
-
-<h3>The resolver in code</h3>
-<pre class="mono"><span style="color:var(--accent)">WorkerConfig.resolve_dispatch</span>(activity_name, routing_key, queue_options_by_queue, is_traced) -&gt; <span style="color:var(--accent-2)">DispatchOptions</span>
-
-@dataclass
-class <span style="color:var(--accent-2)">DispatchOptions</span>:
- task_queue: str | None <span class="muted"># None ⇒ omit kwarg, ride workflow's queue</span>
- start_to_close_timeout: timedelta
- retry_policy: RetryPolicy
- schedule_to_close_timeout: timedelta | None = None
- schedule_to_start_timeout: timedelta | None = None
- heartbeat_timeout: timedelta | None = None
-
- def <span style="color:var(--accent)">to_execute_kwargs</span>(self) -&gt; dict[str, Any]:
- <span class="muted"># Splat into workflow.execute_activity(...) — omits keys whose value is None
- # so the Temporal SDK's own defaults kick in rather than receiving None.</span>
- ...</pre>
-
-<div class="note">
- <strong>queue_options without activity_queues — the asymmetry.</strong> If <code>activity_queues</code> is empty (no routing topology) but <code>queue_options[default_task_queue]</code> exists, the resolver <em>still</em> applies that queue's overlay. This lets single-queue deployments tune timeouts/retry/rate without opting into the routing model. Dispatch returns <code>task_queue=None</code> (activity rides the workflow's own queue) but the queue's options still flow through.
-</div>
-
-<h2>5. The call-site shape</h2>
-
-<p>Every <code>workflow.execute_activity(...)</code> in <code>ContentGeneratorInWorkflow</code> splats the resolver output. One uniform pattern across LLM, image-gen, jinja2, and extract calls:</p>
-
-<pre class="mono"><span style="color:var(--accent)">async def</span> make_llm_text(self, job_metadata, llm_setting_main, llm_prompt_for_text):
- worker_config = get_config().temporal.worker_config
- dispatch_kwargs = worker_config.resolve_dispatch(
- activity_name=act_llm_gen_text.__name__,
- routing_key=llm_assignment.llm_handle, <span class="muted"># for by_handle / handle_options</span>
- 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()
- <span style="color:var(--accent)">return await</span> 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, <span class="muted"># task_queue + start_to_close + schedule_to_close + heartbeat + retry_policy</span>
- )</pre>
-
-<h2>6. Layer C — worker-runtime profiles</h2>
-
-<p>A single worker process selects one named profile via <code>pipelex worker --profile &lt;name&gt;</code>. The profile bundles every <code>Worker(...)</code> constructor knob.</p>
-
-<pre><span class="mono">[temporal.worker_runtime_profiles]
-default_profile = "balanced"
-
-[temporal.worker_runtime_profiles.profiles.balanced]
-tuning_mode = "explicit"
-max_cached_workflows = 1000
-max_concurrent_workflow_tasks = 100
-max_concurrent_activities = 100
-max_concurrent_local_activities = 100
-max_concurrent_workflow_task_polls = 5
-max_concurrent_activity_task_polls = 5
-max_activities_per_second = 1000 # worker-local rate cap
-sticky_queue_schedule_to_start_timeout = "0:00:10"
-max_heartbeat_throttle_interval = "0:01:00"
-default_heartbeat_throttle_interval = "0:00:30"
-graceful_shutdown_timeout = "0:00:30"
-
-# Router profile — workflow-only, no activities at all.
-[temporal.worker_runtime_profiles.profiles.router]
-tuning_mode = "explicit"
-max_cached_workflows = 2000
-max_concurrent_workflow_tasks = 200
-max_concurrent_activities = 0 # 👈 ge=0 allows workflow-only workers
-max_concurrent_local_activities = 0
-max_concurrent_workflow_task_polls = 10
-max_concurrent_activity_task_polls = 0
-max_activities_per_second = 1
-sticky_queue_schedule_to_start_timeout = "0:00:10"
-max_heartbeat_throttle_interval = "0:01:00"
-default_heartbeat_throttle_interval = "0:00:30"
-graceful_shutdown_timeout = "0:00:30"
-
-# GPU profile — small slot count, long heartbeats
-[temporal.worker_runtime_profiles.profiles.gpu]
-tuning_mode = "explicit"
-max_cached_workflows = 100
-max_concurrent_workflow_tasks = 10
-max_concurrent_activities = 4 # GPU memory-bound
-max_concurrent_local_activities = 0
-max_concurrent_workflow_task_polls = 2
-max_concurrent_activity_task_polls = 2
-max_activities_per_second = 10
-sticky_queue_schedule_to_start_timeout = "0:00:30"
-max_heartbeat_throttle_interval = "0:05:00"
-default_heartbeat_throttle_interval = "0:01:00"
-graceful_shutdown_timeout = "0:01:00"</span></pre>
-
-<p>Boot a specialized worker:</p>
-<pre class="mono">$ pipelex worker --task-queue img-gen-gpu-queue --profile gpu --scope runner-img-gen
-$ pipelex worker --task-queue temporal_task_queue --profile router --scope router
-$ pipelex worker --task-queue anthropic-queue --profile balanced --scope runner-llm</pre>
-
-<p>Scopes (specialized worker scopes from the same diff): <code>runner-llm</code>, <code>runner-img-gen</code>, <code>runner-extract</code>, <code>runner-jinja2</code>. Each scope registers only its activities. <code>act_render_page_views</code> is registered under both <code>runner-img-gen</code> and <code>runner-extract</code> (belt-and-suspenders for the two paths that need it).</p>
-
-<h2>7. Strict CLI validation</h2>
-
-<p><code>pipelex worker --task-queue X</code> now fast-fails if <code>X</code> isn't declared anywhere — <code>default_task_queue</code>, any <code>activity_queues</code> entry, or any <code>queue_options</code> key. With a Levenshtein "did you mean?" suggestion.</p>
-
-<pre class="mono">$ pipelex worker --task-queue antrhopic-queue
-WorkerTaskQueueUnknownError: task queue 'antrhopic-queue' is not declared in config.
- Known queues: ['anthropic-queue', 'img-gen-gpu-queue', 'openai-queue',
- 'temporal_task_queue', 'extract-default-queue', 'extract-azure-queue']
- Did you mean: 'anthropic-queue'?</pre>
-
-<p>This is the strict counterpart to the lenient WARN at config-load on <code>activity_queues</code> entries that name unknown queues. Routing config can be sloppy in one direction (warn); the worker boot picks one queue and that one must exist (fail).</p>
-
-<h2>8. Dispatch resolution tracing</h2>
-
-<p>Flip a config flag to see exactly which layer each scalar came from on every activity call:</p>
-
-<pre><span class="mono">[temporal.temporal_config.temporal_log_config]
-is_dispatch_resolution_traced = true</span></pre>
-
-<pre class="mono">INFO dispatch act_llm_gen_text routing_key=claude-4.6-opus
- task_queue=anthropic-queue (activity_queues.by_handle)
- start_to_close_timeout=0:15:00 (handle_options)
- heartbeat_timeout=0:01:00 (queue_options)
- retry.maximum_attempts=5 (queue_options)
- retry.non_retryable=['AnthropicAuthError','OAIBillingError'] (baseline + queue_extra)</pre>
-
-<p>Off by default — verbose; turn it on when debugging mis-tuned timeouts or a queue that shouldn't be receiving traffic.</p>
-
-<h2>9. Workflow timeout vs activity timeout — separated</h2>
-
-<p>Two distinct budgets, set in distinct places:</p>
-
-<ul class="tight">
- <li><code>workflow_execution_timeout</code> on <code>WorkerConfig</code> bounds the workflow as a whole.</li>
- <li><code>default_activity_start_to_close_timeout</code> on <code>WorkerConfig</code> (ships at 10 min) is the baseline budget on each activity call.</li>
- <li><code>queue_options[&lt;queue&gt;].start_to_close_timeout</code> overrides the activity budget per queue.</li>
- <li><code>handle_options[&lt;handle&gt;].start_to_close_timeout</code> overrides it for one specific handle when the queue baseline doesn't fit.</li>
-</ul>
-
-<p>Each kind of activity ends up with a timeout shaped to its real cost — a jinja2 render fails fast, a slow PDF extract gets the headroom it actually needs, and the workflow's own deadline isn't spent by a single in-flight activity.</p>
-
-<h2>10. Rate caps live in two distinct places</h2>
-
-<table>
- <thead><tr><th>Knob</th><th>Where</th><th>Semantics</th></tr></thead>
- <tbody>
- <tr><td><code>max_task_queue_activities_per_second</code></td><td><code>[temporal.queue_options.&lt;queue&gt;]</code></td><td>Cluster-wide cap on this queue. Conveyed to the Temporal server by every worker on the queue. Latest value wins.</td></tr>
- <tr><td><code>max_activities_per_second</code></td><td><code>[temporal.worker_runtime_profiles.profiles.&lt;name&gt;]</code></td><td>Worker-local cap on this <em>process</em>. Caps what one worker pulls regardless of cluster headroom.</td></tr>
- </tbody>
-</table>
-
-<p>The shipping default <code>[temporal.queue_options.temporal_task_queue]</code> sets <code>max_task_queue_activities_per_second = 1000</code>. Deployments using non-default queue names should add their own <code>[temporal.queue_options.&lt;queue&gt;]</code> entries with the cap appropriate for that backend pool.</p>
-
-<h2>11. The whole picture, in one example</h2>
-
-<p>Say someone calls a pipe whose router needs an Anthropic Opus completion. Here's the trace from submit to the wire:</p>
-
-<div class="diagram">
- <ol style="font-family: ui-monospace, monospace; font-size: 12.5px; line-height: 1.7; padding-left: 22px;">
- <li><span class="muted">// inside WfPipeRouter:</span> <code>content_generator.make_llm_text(...)</code></li>
- <li><span class="muted">// llm_assignment.llm_handle resolves to</span> <code>"claude-4.6-opus"</code></li>
- <li><code>worker_config.resolve_dispatch("act_llm_gen_text", routing_key="claude-4.6-opus", queue_options_by_queue=...)</code></li>
- <li>&nbsp;&nbsp;<span class="muted">// step 1:</span> <code>resolve_queue</code> → <code>activity_queues["act_llm_gen_text"].by_handle["claude-4.6-opus"]</code> = <span style="color:var(--accent)">"anthropic-queue"</span></li>
- <li>&nbsp;&nbsp;<span class="muted">// step 2:</span> overlay <code>queue_options["anthropic-queue"]</code> → <code>start_to_close=5m, heartbeat=1m, retry: 5 attempts, +AnthropicAuthError</code></li>
- <li>&nbsp;&nbsp;<span class="muted">// step 3:</span> overlay <code>activity_queues["act_llm_gen_text"].handle_options["claude-4.6-opus"]</code> → <code>start_to_close=15m</code> (longer context)</li>
- <li>&nbsp;&nbsp;<span class="muted">// step 4:</span> non_retryable composed additively: <span style="color:var(--good)">baseline + queue._extra + handle._extra</span></li>
- <li>→ <code>DispatchOptions(task_queue="anthropic-queue", start_to_close_timeout=15m, heartbeat_timeout=1m, retry_policy=&lt;5 attempts, no-retry: [...]&gt;)</code></li>
- <li><code>workflow.execute_activity(act_llm_gen_text, **dispatch_kwargs, summary="LLM text · pipe=translate_doc · model=claude-4.6-opus")</code></li>
- <li>→ Temporal server routes the task to a worker polling <code>anthropic-queue</code> with the <code>balanced</code> profile.</li>
- </ol>
-</div>
-
-<h2>12. Where to look</h2>
-
-<ul class="tight">
- <li>Config models: <code>pipelex/temporal/config_temporal.py</code> — <code>WorkerConfig</code>, <code>QueueOptions</code>, <code>HandleOptions</code>, <code>ActivityRouteConfig</code>, <code>WorkerRuntimeProfile</code>, <code>DispatchOptions</code></li>
- <li>The two resolvers: <code>WorkerConfig.resolve_queue</code> and <code>WorkerConfig.resolve_dispatch</code> in the same file</li>
- <li>Call sites that splat the resolver output: <code>pipelex/temporal/tprl_content_generation/content_generator_in_workflow.py</code> — every <code>make_*</code> method</li>
- <li>Defaults: <code>pipelex/pipelex.toml</code> under <code>[temporal.worker_config]</code>, <code>[temporal.queue_options.*]</code>, <code>[temporal.worker_runtime_profiles.*]</code></li>
- <li>Override invitations: <code>.pipelex/pipelex.toml</code> ships the same blocks commented out</li>
- <li>Companion note: <a href="id-and-naming.html" style="color:var(--accent)">id-and-naming.html</a> — Workflow IDs, child IDs, activity IDs, search attributes, summaries</li>
-</ul>
-
-</div>
-</body>
-</html>
diff --git a/wip/text-then-object/PR-text-then-object.html b/wip/text-then-object/PR-text-then-object.html
deleted file mode 100644
index e948b8114..000000000
--- a/wip/text-then-object/PR-text-then-object.html
+++ /dev/null
@@ -1,798 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8" />
-<meta name="viewport" content="width=device-width, initial-scale=1" />
-<title>PR brief — Reintroduce <code>structuring_method = preliminary_text</code> + new <code>PipeStructure</code> operator</title>
-<style>
- :root {
- --bg: #0e1116;
- --panel: #161b22;
- --panel-2: #1c2330;
- --ink: #e6edf3;
- --ink-dim: #9aa6b2;
- --accent: #79c0ff;
- --accent-2: #d2a8ff;
- --good: #7ee787;
- --warn: #f5b352;
- --bad: #ff7b72;
- --line: #30363d;
- --kbd: #21262d;
- }
- html { color-scheme: dark; }
- body {
- margin: 0;
- padding: 0;
- font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
- background: var(--bg);
- color: var(--ink);
- line-height: 1.55;
- }
- .wrap { max-width: 1100px; margin: 0 auto; padding: 32px 28px 96px; }
- header.title {
- border-bottom: 1px solid var(--line);
- margin-bottom: 24px;
- padding-bottom: 16px;
- }
- header.title h1 {
- margin: 0 0 6px;
- font-size: 28px;
- line-height: 1.25;
- }
- header.title p.lede {
- margin: 0;
- color: var(--ink-dim);
- font-size: 15px;
- }
- .meta {
- display: flex;
- flex-wrap: wrap;
- gap: 6px 12px;
- margin-top: 12px;
- font-size: 13px;
- color: var(--ink-dim);
- }
- .pill {
- display: inline-block;
- background: var(--panel);
- border: 1px solid var(--line);
- border-radius: 999px;
- padding: 2px 10px;
- color: var(--ink);
- }
- .pill.added { color: var(--good); border-color: rgba(126,231,135,.4); }
- .pill.changed { color: var(--accent); border-color: rgba(121,192,255,.4); }
- .pill.removed { color: var(--bad); border-color: rgba(255,123,114,.4); }
- h2 {
- margin: 36px 0 12px;
- font-size: 21px;
- border-bottom: 1px solid var(--line);
- padding-bottom: 6px;
- }
- h3 {
- margin: 24px 0 8px;
- font-size: 17px;
- color: var(--accent);
- }
- h4 {
- margin: 18px 0 6px;
- font-size: 15px;
- color: var(--ink-dim);
- text-transform: uppercase;
- letter-spacing: .04em;
- }
- p { margin: 8px 0 12px; }
- code, pre, kbd {
- font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
- font-size: 13px;
- }
- code {
- background: var(--kbd);
- border: 1px solid var(--line);
- padding: 1px 5px;
- border-radius: 4px;
- }
- pre {
- background: var(--panel);
- border: 1px solid var(--line);
- border-radius: 8px;
- padding: 14px 16px;
- overflow: auto;
- margin: 10px 0 16px;
- line-height: 1.45;
- }
- pre code { background: none; border: none; padding: 0; font-size: 12.5px; }
- .grid-2 {
- display: grid;
- grid-template-columns: 1fr 1fr;
- gap: 16px;
- }
- @media (max-width: 800px) {
- .grid-2 { grid-template-columns: 1fr; }
- }
- .card {
- background: var(--panel);
- border: 1px solid var(--line);
- border-radius: 10px;
- padding: 16px 18px;
- }
- .card h3 { margin-top: 0; }
- table {
- width: 100%;
- border-collapse: collapse;
- margin: 12px 0 18px;
- font-size: 14px;
- }
- th, td {
- border-bottom: 1px solid var(--line);
- padding: 8px 10px;
- text-align: left;
- vertical-align: top;
- }
- th { color: var(--ink-dim); font-weight: 600; font-size: 12px; text-transform: uppercase; letter-spacing: .04em; }
- tr td:first-child { white-space: nowrap; color: var(--accent-2); font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace; }
- .diff {
- background: var(--panel-2);
- border: 1px solid var(--line);
- border-radius: 8px;
- overflow: hidden;
- }
- .diff .filehead {
- background: var(--panel);
- padding: 8px 14px;
- color: var(--ink-dim);
- font-size: 12px;
- border-bottom: 1px solid var(--line);
- font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
- }
- .diff pre { margin: 0; border: 0; border-radius: 0; background: transparent; }
- .add { color: var(--good); }
- .del { color: var(--bad); }
- .hunk { color: var(--ink-dim); }
- .callout {
- background: rgba(121,192,255,.08);
- border-left: 3px solid var(--accent);
- border-radius: 4px;
- padding: 10px 14px;
- margin: 12px 0 16px;
- font-size: 14px;
- }
- .callout.warn {
- background: rgba(245,179,82,.08);
- border-left-color: var(--warn);
- }
- .callout strong { color: var(--accent); }
- .callout.warn strong { color: var(--warn); }
- /* ASCII diagram */
- .diagram {
- background: var(--panel);
- border: 1px solid var(--line);
- border-radius: 8px;
- padding: 14px 16px;
- overflow: auto;
- font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace;
- font-size: 12.5px;
- color: var(--ink);
- white-space: pre;
- line-height: 1.4;
- }
- .legend { font-size: 12px; color: var(--ink-dim); margin-top: 6px; }
- ul.tight, ol.tight { margin: 6px 0 14px 22px; }
- ul.tight li, ol.tight li { margin: 3px 0; }
- .filelist {
- columns: 2;
- column-gap: 24px;
- font-size: 13px;
- margin: 8px 0 0;
- padding-left: 18px;
- }
- .filelist li { break-inside: avoid; }
- hr { border: 0; border-top: 1px solid var(--line); margin: 28px 0; }
- .toc {
- background: var(--panel);
- border: 1px solid var(--line);
- border-radius: 8px;
- padding: 12px 18px;
- font-size: 13px;
- }
- .toc ol { margin: 4px 0; padding-left: 20px; }
- .toc a { color: var(--accent); text-decoration: none; }
- .toc a:hover { text-decoration: underline; }
-</style>
-</head>
-<body>
-<div class="wrap">
-
-<header class="title">
- <h1>Reintroduce <code>structuring_method = preliminary_text</code> via build-time elaboration + new <code>PipeStructure</code> operator</h1>
- <p class="lede">
- Brings back the "text-then-object" capability removed in <code>16b775b8</code>, but reshapes it as a build-time
- rewrite into <code>PipeSequence[PipeLLM(text), PipeStructure]</code> instead of a runtime branch inside
- <code>PipeLLM</code>. Adds a first-class <code>PipeStructure</code> operator that users can also call directly.
- </p>
- <div class="meta">
- <span class="pill">Branch: <code>feature/Text-then-object</code></span>
- <span class="pill">Base: <code>bb9bdb32</code> → HEAD <code>62fc10e4</code></span>
- <span class="pill">55 files changed · +3208 / −97</span>
- <span class="pill added">Added: PipeStructure</span>
- <span class="pill changed">Changed: PipeLLM runtime simplified</span>
- <span class="pill changed">Changed: BundleElaborator pass</span>
- </div>
-</header>
-
-<nav class="toc">
- <strong>Contents</strong>
- <ol>
- <li><a href="#tldr">TL;DR</a></li>
- <li><a href="#why">Why this change</a></li>
- <li><a href="#shape">Architectural shape</a></li>
- <li><a href="#elaborator">The bundle elaborator</a></li>
- <li><a href="#pipestructure">The <code>PipeStructure</code> operator</a></li>
- <li><a href="#pipellm">What changed on <code>PipeLLM</code></a></li>
- <li><a href="#metadata">The <code>elaboration_metadata</code> side-table</a></li>
- <li><a href="#validation">Validation layers</a></li>
- <li><a href="#tests">Test surface</a></li>
- <li><a href="#followups">Follow-ups deliberately deferred</a></li>
- </ol>
-</nav>
-
-<h2 id="tldr">TL;DR</h2>
-<ul class="tight">
- <li><strong>Build-time, not runtime.</strong> <code>structuring_method = "preliminary_text"</code> is now a <em>directive</em>. <code>PipelexInterpreter</code> rewrites the bundle through <code>BundleElaborator</code> before any pipe runs. The runtime never sees the directive.</li>
- <li><strong>One pipe in, three pipes out.</strong> A <code>PipeLLM</code> with the directive becomes a <code>PipeSequence</code> wrapping a synthetic <code>PipeLLM</code> (draft text) and a synthetic <code>PipeStructure</code> (structuring). The user-facing pipe code is preserved, so <code>main_pipe</code>, callers, and the run API are unaffected.</li>
- <li><strong>New first-class operator.</strong> <code>PipeStructure</code> takes one Text-compatible input, runs one LLM call against the canned <code>structuring_prompt</code> template, and produces any structured concept with full multiplicity support (<code>Foo</code>, <code>Foo[]</code>, <code>Foo[N]</code>). Usable directly in MTHDS too — handy after PDF extraction, search results, or upstream prose.</li>
- <li><strong>Runtime <code>PipeLLM</code> simplified.</strong> The field, validator, runtime branch, and execution-data line for <code>structuring_method</code> are gone. Less surface, fewer code paths, no <code>NotImplementedError</code> trap.</li>
- <li><strong>Side-table over field pollution.</strong> Synthetic-pipe metadata lives in a process-local <code>PipelexBundleBlueprint.elaboration_metadata</code> dict (excluded from serialization), not as a new field on every blueprint or runtime pipe.</li>
-</ul>
-
-<h2 id="why">Why this change</h2>
-<p>
- Before this PR, <code>structuring_method = "preliminary_text"</code> existed as a field on the runtime
- <code>PipeLLM</code>, but it raised <code>NotImplementedError</code> at run time — left over after the original
- text-then-object implementation was removed in <code>16b775b8</code>. The directive was effectively dead.
-</p>
-<p>
- We have two kinds of users who want this:
-</p>
-<ul class="tight">
- <li><strong>"Let the model think in prose first, then structure."</strong> Improves quality for tasks where reasoning is awkward in JSON. They want a one-line directive on <code>PipeLLM</code>.</li>
- <li><strong>"I already have text from somewhere else (PDF extraction, search, user input) — just structure it."</strong> They don't want a <code>PipeLLM</code> at all; they want a dedicated structuring step.</li>
-</ul>
-<p>
- Solving both with a runtime branch on <code>PipeLLM</code> bloats the operator and hides a sequence behind one
- pipe. Instead, we introduce <code>PipeStructure</code> as the underlying primitive, then make
- <code>structuring_method = "preliminary_text"</code> a build-time shorthand that expands into it. The runtime
- layer (and Temporal) never sees the directive — it sees only ordinary <code>PipeSequence</code> +
- <code>PipeLLM</code> + <code>PipeStructure</code>.
-</p>
-
-<h2 id="shape">Architectural shape</h2>
-
-<h3>Where elaboration sits in the load path</h3>
-<div class="diagram">
-.mthds file
- │
- ▼
-TOML parser ─► dict
- │
- ▼
-PipelexBundleBlueprint.model_validate(dict) ◄── parse-time validators fire here
- │ (incl. new validate_preliminary_text_output)
- ▼
-BundleElaborator.elaborate(bundle) ◄── NEW: rewrites preliminary_text
- │ (fast-path short-circuit if absent)
- │ ┌─ scans for PipeLLM with structuring_method=preliminary_text
- │ ├─ for each match: synthesize draft + structure + wrapping sequence
- │ ├─ writes bundle.elaboration_metadata side-table
- │ └─ re-validates the rewritten bundle (ref checks, main_pipe)
- ▼
-elaborated PipelexBundleBlueprint
- │
- ▼
-LibraryManager → PipeFactory → runtime PipeAbstract objects
- (sees only PipeSequence, PipeLLM, PipeStructure — never the directive)
-</div>
-<p class="legend">
- Every code path that loads a bundle from a <code>.mthds</code> file goes through the elaborator.
- The fast-path returns the input bundle unchanged (identity-preserving) when no
- <code>preliminary_text</code> directive is present, so the common case pays no overhead.
-</p>
-
-<h3>What <code>preliminary_text</code> rewrites into</h3>
-<div class="grid-2">
-<div class="card">
-<h4>Before — what the user writes</h4>
-<pre><code>[pipe.review_restaurant]
-type = "PipeLLM"
-description = "..."
-inputs = { transcript = "Text" }
-output = "RestaurantReview"
-structuring_method = "preliminary_text"
-prompt = """Write a thorough review …
-@transcript
-"""</code></pre>
-</div>
-<div class="card">
-<h4>After — what the runtime sees</h4>
-<pre><code># original code reused for the wrapping sequence
-[pipe.review_restaurant]
-type = "PipeSequence"
-inputs = { transcript = "Text" }
-output = "RestaurantReview"
-steps = [
- { pipe = "review_restaurant__draft_text",
- result = "draft_text" },
- { pipe = "review_restaurant__structure",
- result = "review_restaurant" },
-]
-
-[pipe.review_restaurant__draft_text]
-type = "PipeLLM"
-inputs = { transcript = "Text" }
-output = "Text" # always single Text
-prompt = "...verbatim..."
-
-[pipe.review_restaurant__structure]
-type = "PipeStructure"
-inputs = { draft_text = "Text" }
-output = "RestaurantReview" # multiplicity preserved
-model = original.model_to_structure</code></pre>
-</div>
-</div>
-<p>
- The original pipe code is reused for the wrapping sequence, so anything that referenced
- <code>review_restaurant</code> — other pipes, <code>main_pipe</code>, the run API — keeps working unchanged.
-</p>
-
-<h3>Multiplicity rule</h3>
-<p>
- Step 1 always emits <strong>a single <code>Text</code></strong>, even when the original output is <code>Foo[]</code>
- or <code>Foo[3]</code>. Step 2 (<code>PipeStructure</code>) is the one that fans out: one preliminary text →
- N structured objects. This matches the deleted <code>make_text_then_object_list</code> behavior verbatim.
-</p>
-
-<h2 id="elaborator">The bundle elaborator</h2>
-
-<h3>New module: <code>pipelex/core/interpreter/bundle_elaborator.py</code></h3>
-<p>
- A single class with one public classmethod <code>elaborate(bundle)</code>. The dispatch is intentionally narrow —
- there is exactly one elaboration kind today. The structure is set up so adding a second kind is mechanical, but
- no premature plugin registry.
-</p>
-
-<div class="diff">
-<div class="filehead">pipelex/core/interpreter/bundle_elaborator.py · key path</div>
-<pre><code><span class="add">@classmethod
-def elaborate(cls, bundle: PipelexBundleBlueprint) -> PipelexBundleBlueprint:
- if not bundle.pipe or not any(_is_preliminary_text_pipe(bp) for bp in bundle.pipe.values()):
- return bundle # fast-path: identity-preserving short-circuit
-
- existing_codes: set[str] = set(bundle.pipe.keys())
- new_pipe_dict: dict[str, PipeBlueprintUnion] = {}
- elaboration_metadata: dict[str, ElaborationMetadata] = {}
-
- for pipe_code, pipe_blueprint in bundle.pipe.items():
- if _is_preliminary_text_pipe(pipe_blueprint):
- cls._elaborate_preliminary_text(
- pipe_code=pipe_code,
- pipe_blueprint=pipe_blueprint,
- new_pipe_dict=new_pipe_dict,
- elaboration_metadata=elaboration_metadata,
- existing_codes=existing_codes,
- )
- else:
- new_pipe_dict[pipe_code] = pipe_blueprint
-
- # Defense in depth: synthesized pipes must never themselves carry the directive.
- for synthetic_code, synthetic_blueprint in new_pipe_dict.items():
- if synthetic_code in elaboration_metadata and _is_preliminary_text_pipe(synthetic_blueprint):
- raise BundleElaboratorError(...)
-
- elaborated = bundle.model_copy(update={
- "pipe": new_pipe_dict,
- "elaboration_metadata": elaboration_metadata,
- })
-
- # Re-run bundle-level validators against the synthetic pipes.
- try:
- PipelexBundleBlueprint.model_validate(elaborated.model_dump(by_alias=True))
- except ValidationError as exc:
- raise BundleElaboratorError(...) from exc
-
- return elaborated</span></code></pre>
-</div>
-
-<p>
- A module-level <code>TypeGuard</code> narrows the union type at the iteration site so the dispatch helper
- receives a properly-typed <code>PipeLLMBlueprint</code>:
-</p>
-
-<div class="diff">
-<div class="filehead">pipelex/core/interpreter/bundle_elaborator.py · TypeGuard</div>
-<pre><code><span class="add">def _is_preliminary_text_pipe(pipe_blueprint: PipeBlueprintUnion) -> TypeGuard[PipeLLMBlueprint]:
- if not isinstance(pipe_blueprint, PipeLLMBlueprint):
- return False
- method = pipe_blueprint.structuring_method
- return method is not None and method.is_preliminary_text</span></code></pre>
-</div>
-
-<h3>Wiring into the interpreter</h3>
-<div class="diff">
-<div class="filehead">pipelex/core/interpreter/interpreter.py</div>
-<pre><code><span class="hunk">@@ make_pipelex_bundle_blueprint @@</span>
- try:
- pipelex_bundle_blueprint = PipelexBundleBlueprint.model_validate(blueprint_dict)
- pipelex_bundle_blueprint.source = str(bundle_path) if bundle_path else None
-<span class="del">- return pipelex_bundle_blueprint</span>
- except ValidationError as exc:
- ...
-<span class="add">+
-+try:
-+ return BundleElaborator.elaborate(bundle=pipelex_bundle_blueprint)
-+except BundleElaboratorError as exc:
-+ raise PipelexInterpreterError(message=str(exc)) from exc</span></code></pre>
-</div>
-
-<h2 id="pipestructure">The <code>PipeStructure</code> operator</h2>
-
-<p>
- Mirrors the shape of <code>PipeLLM</code> for object generation but stripped of everything that doesn't apply:
- no user-controlled prompt template, no image/document inputs, no system prompt, exactly one Text input.
-</p>
-
-<table>
-<thead><tr><th>Field</th><th>Type</th><th>Notes</th></tr></thead>
-<tbody>
- <tr><td>type</td><td><code>"PipeStructure"</code></td><td>Discriminator</td></tr>
- <tr><td>inputs</td><td>dict</td><td>Exactly one entry. Concept must be Text or refine Text. No multiplicity (use <code>PipeBatch</code>).</td></tr>
- <tr><td>output</td><td>string</td><td>Any structured concept, with optional multiplicity (<code>Foo</code>, <code>Foo[]</code>, <code>Foo[N]</code>). Cannot be Text.</td></tr>
- <tr><td>model</td><td><code>LLMModelChoice | None</code></td><td>Falls back to <code>llm_choice_overrides.for_object</code> → <code>llm_choice_defaults.for_object</code>.</td></tr>
-</tbody>
-</table>
-
-<h3>Runtime flow</h3>
-<div class="diagram">
-working_memory.get_stuff_as_str(text_input_name)
- │
- ▼
-render_template(structuring_prompt, {text}) ◄── new generic template in pipelex.toml
- │
- ▼
-+ get_output_structure_prompt(target_concept) ◄── shared with PipeLLM.object generation
- │
- ▼
-LLMSetting = self.llm_choice
- ?? deck.llm_choice_overrides.for_object
- ?? deck.llm_choice_defaults.for_object
- │
- ▼
-content_generator.make_object (single)
-content_generator.make_object_list (Foo[] / Foo[N])
- │
- ▼
-StuffFactory.make_stuff → working_memory.set_new_main_stuff
-</div>
-
-<h3>Critical code: <code>_live_run_operator_pipe</code></h3>
-<div class="diff">
-<div class="filehead">pipelex/pipe_operators/structure/pipe_structure.py</div>
-<pre><code><span class="add">text_str = working_memory.get_stuff_as_str(name=self.text_input_name)
-
-multiplicity_resolution = output_multiplicity_to_apply(
- base_multiplicity=self.output_multiplicity,
- override_multiplicity=pipe_run_params.output_multiplicity,
-)
-is_multiple_output = multiplicity_resolution.is_multiple_outputs_enabled
-fixed_nb_output = multiplicity_resolution.specific_output_count
-
-llm_choice_for_object = (
- self.llm_choice
- or model_deck.llm_choice_overrides.for_object
- or model_deck.llm_choice_defaults.for_object
-)
-llm_setting_for_object = model_deck.get_llm_setting(llm_choice=llm_choice_for_object)
-
-structuring_template = llm_config.get_template(template_name="structuring_prompt")
-rendered_user_prompt = await render_template(
- template=structuring_template,
- category=TemplateCategory.LLM_PROMPT,
- context={"text": text_str},
-)
-if llm_config.is_structure_prompt_enabled:
- rendered_user_prompt += await get_output_structure_prompt(
- concept_ref=self.output.concept.concept_ref
- )
-
-llm_prompt = LLMPrompt(user_text=rendered_user_prompt)
-content_class = get_class_registry().get_required_subclass(
- name=self.output.concept.structure_class_name, base_class=StuffContent,
-)
-
-if is_multiple_output:
- generated_objects = await content_generator.make_object_list(
- job_metadata=job_metadata, object_class=content_class,
- llm_prompt_for_object_list=llm_prompt,
- llm_setting_for_object_list=llm_setting_for_object,
- nb_items=fixed_nb_output,
- )
- the_content = ListContent(items=generated_objects)
-else:
- the_content = await content_generator.make_object(...)</span></code></pre>
-</div>
-
-<h3>The new generic template</h3>
-<div class="diff">
-<div class="filehead">pipelex/pipelex.toml · [cogt.llm_config.generic_templates]</div>
-<pre><code><span class="add">structuring_prompt = """
-Read the following text carefully and produce the requested structured output from it.
-
----
-{{ text }}
-"""</span></code></pre>
-</div>
-<p>
- The operator deliberately has <em>no</em> user-controlled prompt template — the only variable is <code>text</code>,
- fed automatically from the declared input. Customization for <code>preliminary_text</code> is captured as a
- follow-up; if a user really needs custom prompts they author the two pipes by hand.
-</p>
-
-<h2 id="pipellm">What changed on <code>PipeLLM</code></h2>
-
-<p>
- The runtime <code>PipeLLM</code> no longer carries <code>structuring_method</code> at all. The field, validator,
- the <code>NotImplementedError</code> trap, the <code>execution_data_dict</code> entry, and the factory's forwarding
- of the field are all removed.
-</p>
-
-<div class="diff">
-<div class="filehead">pipelex/pipe_operators/llm/pipe_llm.py · removed</div>
-<pre><code><span class="del">- structuring_method: StructuringMethod | None = None
-
-- @model_validator(mode="after")
-- def validate_output_concept_consistency(self) -> Self:
-- if self.structuring_method is not None and self.output.concept.structure_class_name == NativeConceptCode.TEXT:
-- msg = (
-- f"Output concept '{self.output.concept.code}' is considered a Text concept, "
-- f"so it cannot be structured. Maybe you forgot to add '{NativeConceptCode.TEXT}' to the class registry?"
-- )
-- raise ValueError(msg)
-- return self
-
-# inside _live_run_operator_pipe:
-- if self.structuring_method is not None:
-- match self.structuring_method:
-- case StructuringMethod.PRELIMINARY_TEXT:
-- msg = (
-- f"PipeLLM '{self.code}': structuring_method='preliminary_text' is not currently supported. "
-- "The text-then-object mechanism was removed; a new implementation is planned."
-- )
-- raise NotImplementedError(msg)
-- case StructuringMethod.DIRECT:
-- pass
-
-# inside execution_data_dict:
-- if self.structuring_method is not None:
-- execution_data_dict["structuring_method"] = self.structuring_method</span></code></pre>
-</div>
-
-<h3>The blueprint keeps the field — and gains a parse-time validator</h3>
-<p>
- <code>structuring_method</code> remains part of the language surface. <code>PipeLLMBlueprint</code> gets a
- <code>model_validator(mode="after")</code> that mirrors the elaborator's pre-check, so the user gets the error
- during <code>model_validate</code> (parse time) instead of at elaboration time. The elaborator's check stays
- as defense-in-depth (only reachable via <code>model_construct</code>).
-</p>
-
-<div class="diff">
-<div class="filehead">pipelex/pipe_operators/llm/pipe_llm_blueprint.py · added</div>
-<pre><code><span class="add">class StructuringMethod(StrEnum):
- DIRECT = "direct"
- PRELIMINARY_TEXT = "preliminary_text"
-
- @property
- def is_preliminary_text(self) -> bool: # avoid `==` against enum (project rule)
- match self:
- case StructuringMethod.PRELIMINARY_TEXT:
- return True
- case StructuringMethod.DIRECT:
- return False
-
-
-class PipeLLMBlueprint(PipeBlueprint):
- ...
- structuring_method: StructuringMethod | None = None
-
- @model_validator(mode="after")
- def validate_preliminary_text_output(self) -> Self:
- if self.structuring_method is None or not self.structuring_method.is_preliminary_text:
- return self
- output_parse_result = parse_concept_with_multiplicity(self.output)
- if QualifiedRef.parse(output_parse_result.concept_ref_or_code).local_code == NativeConceptCode.TEXT:
- raise ValueError(
- f"PipeLLM with `structuring_method = preliminary_text` cannot have output `{self.output}`. "
- "The output must be a structured concept, not Text."
- )
- return self</span></code></pre>
-</div>
-
-<div class="callout warn">
- <strong>Heads-up for direct importers.</strong> <code>StructuringMethod</code> moved from
- <code>pipelex.pipe_operators.llm.pipe_llm</code> to
- <code>pipelex.pipe_operators.llm.pipe_llm_blueprint</code> (it now lives next to the only consumer).
- CHANGELOG entry calls this out.
-</div>
-
-<h3><code>PipeLLMSpec</code> still exposes the directive</h3>
-<p>
- AI agents authoring via specs can still opt in. <code>PipeLLMSpec</code> gains a plain
- <code>structuring_method: StructuringMethod | None = None</code> field (intentionally <em>not</em>
- <code>SkipJsonSchema</code>, so it shows up in the JSON schema we hand to agents) and forwards it in
- <code>to_blueprint()</code>.
-</p>
-
-<h2 id="metadata">The <code>elaboration_metadata</code> side-table</h2>
-
-<p>
- Synthetic-pipe metadata lives on the <em>bundle</em>, not on every pipe blueprint and not on the runtime
- <code>PipeAbstract</code>. The user-facing per-pipe schema stays unpolluted.
-</p>
-
-<div class="diff">
-<div class="filehead">pipelex/core/bundles/pipelex_bundle_blueprint.py · added</div>
-<pre><code><span class="add">class StepRole(StrEnum):
- DRAFT_TEXT = "draft_text"
- STRUCTURE = "structure"
-
-
-class ElaborationMetadata(BaseModel):
- parent_pipe_code: str
- step_role: StepRole
-
-
-class PipelexBundleBlueprint(BaseModel):
- ...
- # Process-local. Survives model_copy. Dropped by any model_dump→model_validate
- # round-trip (exclude=True keeps MTHDS / TOML / JSON exports clean).
- elaboration_metadata: dict[str, ElaborationMetadata] | None = Field(default=None, exclude=True)
-
- def get_elaboration_for(self, pipe_code: str) -> ElaborationMetadata | None:
- if not self.elaboration_metadata:
- return None
- return self.elaboration_metadata.get(pipe_code)</span></code></pre>
-</div>
-
-<h3>Lifetime</h3>
-<ul class="tight">
- <li>Within a single process, after <code>BundleElaborator.elaborate(...)</code>, the metadata is reachable via the bundle reference.</li>
- <li>Across any serialization boundary — kajson, library cache, Temporal payload, MTHDS export — the metadata is gone.</li>
- <li>The elaborator's own re-validate pass is by-design discarded: it round-trips <em>only</em> to surface ref-rot errors with bundle context, then returns the original <code>model_copy</code>-built bundle (with metadata intact).</li>
-</ul>
-
-<h3>One specific consumer wired today</h3>
-<p>
- The dependency loader in <code>LibraryManager._load_single_dependency</code> walks the side-table to keep
- synthetic helpers attached to exported parents. Without this, exporting <code>review_restaurant</code> from a
- package would leave the wrapping <code>PipeSequence</code> referencing unresolved
- <code>review_restaurant__draft_text</code> / <code>__structure</code> codes:
-</p>
-
-<div class="diff">
-<div class="filehead">pipelex/libraries/library_manager.py · added</div>
-<pre><code><span class="add">all_exported = resolved_dep.exported_pipe_codes | main_pipes
-synthetic_helpers: set[str] = set()
-for blueprint in dep_blueprints:
- if not blueprint.elaboration_metadata:
- continue
- for synthetic_code, meta in blueprint.elaboration_metadata.items():
- if meta.parent_pipe_code in all_exported:
- synthetic_helpers.add(synthetic_code)
-all_exported |= synthetic_helpers</span></code></pre>
-</div>
-
-<h2 id="validation">Validation layers</h2>
-<p>
- Three layers guard against the only authoring mistake the elaborator can hit — combining
- <code>preliminary_text</code> with a Text output:
-</p>
-
-<table>
-<thead><tr><th>Layer</th><th>Where</th><th>What it catches</th></tr></thead>
-<tbody>
- <tr>
- <td>1. Construction</td>
- <td><code>PipeLLMBlueprint.validate_preliminary_text_output</code></td>
- <td>String-level: rejects <code>"Text"</code>, <code>"native.Text"</code>, <code>"Text[]"</code>, <code>"Text[N]"</code>. Fires during <code>model_validate</code>, before the elaborator runs.</td>
- </tr>
- <tr>
- <td>2. Defense-in-depth</td>
- <td><code>BundleElaborator._elaborate_preliminary_text</code></td>
- <td>Same string-level check — only reachable if a caller bypassed validation via <code>model_construct</code>. Test suite exercises it.</td>
- </tr>
- <tr>
- <td>3. Library-time</td>
- <td><code>PipeStructure.validate_output_with_library</code></td>
- <td>Concept-level: catches a domain concept that <code>refines = "Text"</code> — those slip past string-level guards because they don't read as <code>Text</code> in the source.</td>
- </tr>
-</tbody>
-</table>
-
-<p>The elaborator additionally guards against:</p>
-<ul class="tight">
- <li>Synthetic-code collisions with user-authored pipes in the same bundle.</li>
- <li>Synthetic codes that don't pass <code>is_pipe_code_valid</code> (snake_case + length).</li>
- <li>Recursive elaboration — a synthesized blueprint must never carry <code>structuring_method = preliminary_text</code> itself.</li>
- <li>Reference rot in the rewritten bundle — re-runs <code>PipelexBundleBlueprint.model_validate</code> on the elaborated form, wraps any <code>ValidationError</code> in <code>BundleElaboratorError</code> with the originating-pipe context.</li>
-</ul>
-
-<h2 id="tests">Test surface</h2>
-
-<p>
- Test counts: PipeStructure-focused subset is <strong>92 passed</strong>. Touched-source areas overall:
- <strong>1506 passed, 1 xfailed</strong>. <code>make agent-check</code> and <code>make docs-check</code> clean.
-</p>
-
-<h3>New test modules</h3>
-<ul class="filelist">
- <li><code>tests/unit/pipelex/core/bundles/test_elaboration_metadata.py</code></li>
- <li><code>tests/unit/pipelex/core/interpreter/test_bundle_elaborator.py</code></li>
- <li><code>tests/unit/pipelex/core/interpreter/test_interpreter_preliminary_text.py</code></li>
- <li><code>tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_blueprint.py</code></li>
- <li><code>tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_factory.py</code></li>
- <li><code>tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_validate_inputs.py</code></li>
- <li><code>tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_validate_outputs.py</code></li>
- <li><code>tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_kajson.py</code></li>
- <li><code>tests/unit/pipelex/builder/pipe/pipe_operator/pipe_structure/test_pipe_structure_spec.py</code></li>
- <li><code>tests/unit/pipelex/libraries/dependencies/test_dependency_preliminary_text_export.py</code></li>
- <li><code>tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure.py</code></li>
- <li><code>tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure_in_sequence.py</code></li>
- <li><code>tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure_in_batch.py</code></li>
- <li><code>tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_e2e.py</code></li>
- <li><code>tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_inline_e2e.py</code></li>
-</ul>
-
-<h3>Integration coverage worth knowing about</h3>
-<ul class="tight">
- <li><strong>End-to-end <code>preliminary_text</code> with real LLM calls</strong>, parametrized over all three multiplicity forms (<code>Foo</code>, <code>Foo[]</code>, <code>Foo[2]</code>), against both Python-class concepts (<code>RestaurantReview</code>, 8 fields) and inline-structure concepts (<code>HikingTripReport</code>, 12 fields with lists).</li>
- <li><strong>Exactly two LLM calls per invocation</strong> asserted via the reporting registry — confirms one draft + one structure.</li>
- <li><strong><code>PipeStructure</code> inside a hand-authored <code>PipeSequence</code></strong> (no elaboration sugar) — confirms the operator is usable on its own.</li>
- <li><strong><code>PipeStructure</code> inside a <code>PipeBatch</code></strong> — three free-form review texts, per-item shape assertions.</li>
- <li><strong>kajson round-trip</strong> for <code>PipeStructureBlueprint</code>, for a <code>PipeLLMBlueprint</code> carrying the directive, and for every blueprint in an elaborated bundle.</li>
-</ul>
-
-<div class="callout">
- <strong>Authoring note.</strong> Writing <code>type = "PipeStructure"</code> directly in a <code>.mthds</code>
- file currently fails <code>plxt</code> schema validation: the bundled schema in
- <code>vscode-pipelex/crates/taplo-common/schemas/mthds_schema.json</code> predates this PR. The
- <code>preliminary_text</code> path is unaffected (the synthesized <code>PipeStructure</code> lives in-memory
- only). Cross-repo follow-up: ship a <code>pipelex-tools</code> release with the regenerated schema. Captured
- in <code>TODOS.md</code>.
-</div>
-
-<h2 id="followups">Follow-ups deliberately deferred</h2>
-<p>Listed in <code>TODOS.md</code>; none of these block this PR.</p>
-<ol class="tight">
- <li>Synthetic-pipe marker on graph node tags + CLI listing exclusion (uses the side-table).</li>
- <li>Friendly synthetic-pipe rendering across logs, traces, and run-reporting.</li>
- <li><code>mthds-ui</code> graph viewer integration.</li>
- <li>Bundle-load benchmark in CI.</li>
- <li><code>PipeStructure</code> image-input support.</li>
- <li>Per-step prompt customization for <code>preliminary_text</code>.</li>
- <li>Generic meta-pipe / build-time elaboration framework — when a <em>second</em> directive lands.</li>
- <li><code>pipelex-dev elaborate-bundle &lt;path&gt;</code> debugging CLI.</li>
- <li>Revisit <code>StructuringMethod.DIRECT</code> (functionally identical to <code>None</code> today; kept for symmetry).</li>
- <li>Persist <code>elaboration_metadata</code> across serialization boundaries — drop <code>exclude=True</code> when a second cross-boundary consumer materializes (graph viewer over a serialized bundle, Temporal payload, persistent library cache). Today the only consumer is the in-process dependency loader.</li>
-</ol>
-
-<hr />
-
-<p style="color: var(--ink-dim); font-size: 12px; margin-top: 24px;">
- Brief generated from the diff between <code>bb9bdb32</code> and HEAD on
- <code>feature/Text-then-object</code>. See <code>TODOS.md</code> for the full phase-by-phase plan, decisions
- taken, and audit notes; <code>docs/under-the-hood/build-time-elaboration.md</code> for the user-facing
- mechanism doc; <code>docs/building-methods/pipes/pipe-operators/PipeStructure.md</code> for the operator
- reference.
-</p>
-
-</div>
-</body>
-</html>
diff --git a/wip/text-then-object/deferred-items.md b/wip/text-then-object/deferred-items.md
deleted file mode 100644
index 66ed3478f..000000000
--- a/wip/text-then-object/deferred-items.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# Text-then-object — Deferred Items
-
-Follow-ups deferred out of the text-then-object work that landed in PR #891 (`feature/Temporal-merge-3`). Mirrored here so they survive `TODOS.md` being cleared at release time.
-
-**Source:** `TODOS.md` §"What remains as follow-up TODOs" from the PR recap.
-**Owner doc:** this file once `TODOS.md` is cleared on next release.
-
----
-
-1. **plxt schema sync.** `vscode-pipelex/crates/taplo-common/schemas/mthds_schema.json` is from before this PR — authoring `type = "PipeStructure"` directly in a `.mthds` file fails plxt validation. Regenerate via `pipelex-dev generate-mthds-schema` and ship a `pipelex-tools` release. The `preliminary_text` path is unaffected because the synthesized `PipeStructure` lives in-memory only.
-
-2. **Synthetic-pipe marker on graph nodes + CLI listing exclusion.** When emitting `NodeSpec`, look up `bundle.elaboration_metadata` and set `tags["synthetic"] = "true"` + `tags["parent_pipe_code"] = parent`. Requires either a runtime-only field on `PipeAbstract` or a side-registry keyed by pipe code. Also hide synthetic pipes from `pipelex list`. ~2–3 file edits.
-
-3. **Friendly synthetic-pipe rendering across logs/traces/run-reporting.** After (2), render `<parent_pipe_code> [<step_role_label>]` everywhere `self.code` appears. Touches graph_tracer, run_reporting, journal, distributed-tracing. ~5–8 file edits.
-
-4. **`mthds-ui` graph viewer integration.** After (2), decide in the UI repo whether to nest synthetic pipes under their parent or hide them.
-
-5. **Bundle-load benchmark in CI.** Microbenchmark library load time; alert on >5% regression. Protects future elaboration-pass additions.
-
-6. **PipeStructure image input support.** v1 takes Text only; extend when a concrete need arises.
-
-7. **Per-step prompt customization for `preliminary_text`.** Don't build until requested.
-
-8. **Generic meta-pipe / build-time elaboration framework.** Promote `BundleElaborator._elaborate_preliminary_text` into a plugin registry when a SECOND elaboration directive appears.
-
-9. **`pipelex-dev elaborate-bundle <path>`** debugging CLI to print the elaborated form without running.
-
-10. **Revisit `StructuringMethod.DIRECT`.** Functionally identical to `None`. Delete if no second method materializes.
-
-11. **Persist `elaboration_metadata` into MTHDS/JSON exports.** Today `Field(exclude=True)` drops it on every `model_dump`. When a cross-boundary consumer materializes (graph viewer over a serialized bundle, Temporal payload, persistent cache), flip `exclude=False`, regenerate the schema, ship a plxt bump. The regression test at `test_elaboration_metadata.py::test_bundle_round_trip_drops_elaboration_metadata` flips first.
diff --git a/wip/text-then-object/text-then-object-plan.md b/wip/text-then-object/text-then-object-plan.md
deleted file mode 100644
index d58f187ca..000000000
--- a/wip/text-then-object/text-then-object-plan.md
+++ /dev/null
@@ -1,395 +0,0 @@
-# Plan: Reintroduce `structuring_method = preliminary_text` via blueprint elaboration + a new `PipeStructure` operator
-
----
-
-## CHECKPOINT — current state (resume here)
-
-**Branch:** `feature/Text-then-object` (worktree at `_tto/`).
-
-**Last verified:** `make agent-check` clean (ruff/plxt/pyright/mypy all 0 errors, 0 warnings). Targeted run for the touched source areas: `1506 passed, 1 xfailed`. PipeStructure-focused subset (`tests/unit/pipelex/pipe_operators/pipe_structure/ tests/unit/pipelex/core/interpreter/ tests/integration/pipelex/pipes/operator/pipe_structure/`): `92 passed`.
-
-### Status by phase
-
-- [x] **Phase 1 — bundle elaboration metadata.** `StepRole`, `ElaborationMetadata`, and the `elaboration_metadata: dict[str, ElaborationMetadata] | None = Field(default=None, exclude=True)` side-table live on `PipelexBundleBlueprint` (`pipelex/core/bundles/pipelex_bundle_blueprint.py`). Accessor `get_elaboration_for(pipe_code)` added. Unit tests in `tests/unit/pipelex/core/bundles/test_elaboration_metadata.py`.
-- [x] **Phase 2 — PipeStructure operator.** Module at `pipelex/pipe_operators/structure/` with `__init__.py`, `pipe_structure_blueprint.py`, `pipe_structure.py`, `pipe_structure_factory.py` (no `exceptions.py` — neither operator-level nor factory-level errors had call sites, so the file was deleted per "no half-finished implementations"). Registered in `PipeBlueprintUnion`, `PipeType.PIPE_STRUCTURE`, `CoreRegistryModels.PIPE_OPERATORS{,_FACTORY}`. Added `PipeType.PIPE_STRUCTURE` arm to the `match` in `pipelex/core/pipes/output/output_renderer.py:_collect_possible_outputs` and to `_PIPE_DEFINITION_NAMES` in `pipelex/language/mthds_schema_generator.py`. New `structuring_prompt` template under `[cogt.llm_config.generic_templates]` in `pipelex/pipelex.toml`. Unit tests in `tests/unit/pipelex/pipe_operators/pipe_structure/` + dry-run integration test in `tests/integration/pipelex/pipes/operator/pipe_structure/`. Regenerated `derived/mthds_schema.json` via `pipelex-dev generate-mthds-schema`.
-- [x] **Phase 3 — PipeStructureSpec.** `pipelex/builder/pipe/pipe_structure_spec.py`, registered in `pipe_spec_union.py` and `pipe_spec_map.py`. Tests in `tests/unit/pipelex/builder/pipe/pipe_operator/pipe_structure/test_pipe_structure_spec.py`.
-- [x] **Phase 4 — bundle elaboration framework.** `pipelex/core/interpreter/bundle_elaborator.py` with `BundleElaborator.elaborate()`, `BundleElaboratorError(PipelexInterpreterError)`, fast-path short-circuit (identity-preserving), recursive-elaboration guard, post-elaboration `model_validate` re-run. Wired into `PipelexInterpreter.make_pipelex_bundle_blueprint`. Uses a module-level `TypeGuard` (`_is_preliminary_text_pipe`) so callers narrow `PipeBlueprintUnion → PipeLLMBlueprint` without casts.
-- [x] **Phase 5 — preliminary_text elaboration.** Synthesizes step-1 (`<code>__draft_text` PipeLLM, output always literal `Text`), step-2 (`<code>__structure` PipeStructure, original output preserved), and replaces the original `<code>` with a `PipeSequence` wrapping both. `elaboration_metadata` populated for the two synthetic codes. Tests in `tests/unit/pipelex/core/interpreter/test_bundle_elaborator.py` cover: short-circuit identity, empty bundle, three-pipe rewrite shape, multiplicity preservation (`Foo` / `Foo[]` / `Foo[3]`), Text-output rejection (incl. `native.Text` and bracketed forms — gated by both the blueprint validator at construction time AND the elaborator's defense-in-depth check via `model_construct`), synthetic-name collision, image-input only on step-1, `main_pipe` regression, model + `model_to_structure` propagation. **Integration test against a real LLM is deferred to Phase 8.**
-- [x] **Phase 6 — remove `structuring_method` from runtime PipeLLM.** Done.
- - Removed field, validator, NotImplementedError block, and `execution_data_dict` line from `PipeLLM`. Factory no longer forwards the field.
- - Added `model_validator(mode="after")` `validate_preliminary_text_output` on `PipeLLMBlueprint` — rejects `preliminary_text + Text output` at construction time, before the elaborator runs. The elaborator's matching pre-check stays as defense-in-depth (only reachable via `model_construct`).
- - Added `is_preliminary_text` `@property` on `StructuringMethod` (project rule: never `==` against an enum value).
- - `PipeLLMSpec` exposes `structuring_method: StructuringMethod | None = None` (plain `Field`, not `SkipJsonSchema`) and forwards it in `to_blueprint()`.
- - Deleted obsolete `test_pipe_llm_preliminary_text_raises_not_implemented` integration test.
- - Updated `tests/unit/pipelex/language/test_mthds_schema.py::test_all_pipe_types_present` to derive expected blueprint names from `PipeType.value_list()` instead of hardcoding the count (the count test was failing once `PipeStructure` was added).
-- [x] **Phase 8 — round-out tests.** Done. (Phase 7 intentionally skipped per the plan.) Files added:
- - `tests/unit/pipelex/pipe_operators/pipe_structure/test_pipe_structure_kajson.py` — kajson round-trip for `PipeStructureBlueprint`, `PipeLLMBlueprint` with `structuring_method = preliminary_text`, and every blueprint in an elaborated bundle. (The dedicated `ElaborationMetadata` round-trip case was dropped after review — already covered by `tests/unit/pipelex/core/bundles/test_elaboration_metadata.py`.)
- - `tests/unit/pipelex/core/interpreter/test_interpreter_preliminary_text.py` — `PipelexInterpreter.make_pipelex_bundle_blueprint(mthds_content=...)` end-to-end, both with and without `structuring_method = "preliminary_text"`.
- - `tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure_in_sequence.py` + `text_then_structure_helpers.mthds` — hand-authored `PipeSequence` wrapping a PipeLLM (text) + a `PipeStructure` step (no elaboration sugar). Live-mode shape assertions on the structured `RestaurantReview` output.
- - `tests/integration/pipelex/pipes/operator/pipe_structure/test_pipe_structure_in_batch.py` — `PipeBatch` iterating a `PipeStructure` over three free-form review texts; live-mode per-item shape assertions on `RestaurantReview`.
- - `tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_e2e.py` + `preliminary_text_e2e.mthds` — Python-class case. Parametrized over **all three multiplicity forms** (`RestaurantReview`, `RestaurantReview[]`, `RestaurantReview[2]`). Asserts the wrapping pipe is a `PipeSequence`, step-2 is a `PipeStructure`, the run produces a populated typed result, and **exactly two LLM calls are issued** in live mode (one for the draft text, one for the structuring step) via a private-registry helper.
- - `tests/integration/pipelex/pipes/operator/pipe_structure/test_preliminary_text_inline_e2e.py` + `preliminary_text_inline_e2e.mthds` — **Inline-structure case**. Declares a richer `HikingTripReport` concept (12 fields including numbers, integers and several lists of text) entirely via `[concept.HikingTripReport.structure]` — no Python class file. Pipelex generates the backing class at library load. Parametrized over single + dynamic-list output, same 2-LLM-call assertion.
- - **Concept richness.** `RestaurantReview` (Python class in `test_structures_basic.py`) has 8 fields including two `list[str]`. `HikingTripReport` (inline) has 12 fields. The pre-existing `SimpleResult` (title + score) is untouched and still backs the original `test_pipe_structure.py` integration test.
- - **Prompt topics.** All Phase-8 prompts use everyday non-AI topics (restaurants, hiking trails) — no self-references to Pipelex.
- - **PipeStructure in MTHDS not yet supported by `plxt`.** Authoring `type = "PipeStructure"` directly in a `.mthds` file fails plxt schema validation (the bundled schema in `vscode-pipelex/crates/taplo-common/schemas/mthds_schema.json` is from before this PR). The `preliminary_text` path works because the synthesized `PipeStructure` is built in-memory after plxt parsing. Phase 8.3 / 8.4 therefore exercise PipeStructure programmatically. **Follow-up:** ship a plxt release with the regenerated schema so users can author `PipeStructure` directly in MTHDS. Captured in the follow-up TODOs.
- - **Note on the previously-listed Temporal test.** The original Phase 8 bullet for "preliminary_text via Temporal" is dropped: with the runtime change in Phase 6, Temporal sees only the elaborated form (PipeSequence + PipeLLM + PipeStructure), and Temporal's PipeStructure handling rides on the existing PipeOperator path that the Temporal data converter / class registry already cover. Re-add a dedicated Temporal smoke test only if a Temporal-specific bug surfaces.
-- [x] **Phase 9 — docs & changelog.** Done.
- - New page `docs/building-methods/pipes/pipe-operators/PipeStructure.md` covering the standalone operator (mirrors the PipeLLM page shape).
- - New page `docs/under-the-hood/build-time-elaboration.md` explaining the `BundleElaborator` mechanism (mechanism, multiplicity rule, image-input flow, pre-checks, runtime semantics).
- - `docs/building-methods/pipes/pipe-operators/PipeLLM.md` — replaced the legacy "Direct/Preliminary Text Mode" prose with a concise overview pointing at PipeStructure; updated the `structuring_method` and `model_to_structure` rows in the parameters table; added a new "Structuring Method (preliminary_text)" section (with explicit anchor `#structuring-method-preliminary-text`) that describes the build-time elaboration, trade-offs, and when to use what.
- - `docs/features/llm-integration.md` and `docs/building-methods/adapt-to-llm-prompting-style-openai-anthropic-mistral.md` — relinked references that previously pointed to the deleted `llm-structured-generation-config.md`.
- - `mkdocs.yml` — added PipeStructure.md and build-time-elaboration.md to both the `llmstxt-md` sections list AND the `nav` tree; added redirect entries from the deleted `llm-structured-generation-config.md` paths to the new under-the-hood page.
- - `docs/under-the-hood/index.md` — added the new page to the bullet list and the button row.
- - `CHANGELOG.md` `[Unreleased]` — Added section for `PipeStructure`; Changed section for `structuring_method = "preliminary_text"` working again (build-time elaboration) and the runtime simplification on `PipeLLM`.
-- [x] **Phase 10 — final validation.** Done.
- - `make agent-check` — clean (ruff, plxt, pyright, mypy all 0 errors / 0 warnings).
- - `make docs-check` — clean under `mkdocs build --strict` (only the harmless info note about `docs/CLAUDE.md` being outside nav, which is intentional).
- - `make agent-test` — clean (silent-on-success target).
- - The previously-listed Phase 10 manual smoke is covered end-to-end by the Phase 8 integration tests (`test_preliminary_text_e2e.py`, `test_preliminary_text_inline_e2e.py`) — both run real LLM calls, assert exactly two `LLMTokensUsage` records per invocation, and verify the elaborated `PipeSequence` shape. No additional manual run was performed.
-
-### Code-quality decisions made during implementation (audit notes)
-
-- **No premature error types.** `pipe_operators/structure/exceptions.py` was deleted — the operator/factory had no call site that distinguished from generic `PipeRunError` / Pydantic `ValidationError`. Easy to add back when a real raise site appears.
-- **No speculative `try/except`.** `pipe_structure.py` initially caught `ValidationError` around `make_object`. PipeLLM's parallel path doesn't catch it (the cogt layer wraps any underlying validation error in `LLMCompletionError`), so the catch was speculative — removed per CLAUDE.md "do not add try/except speculatively."
-- **No duplicated factory-level input validation.** `PipeStructureFactory` no longer re-checks `len(blueprint.inputs) == 1`. The blueprint's `model_validator` runs unconditionally on construction; the factory trusts it.
-- **`QualifiedRef.parse(...).local_code`** is used in three places (`pipe_structure_blueprint.py`, `pipe_llm_blueprint.py`, `bundle_elaborator.py`) instead of inline `split(".")` — consolidates "extract the local code from a possibly qualified ref" through the existing helper.
-- **`StructuringMethod.is_preliminary_text` property** added so call sites read as `method.is_preliminary_text` rather than `method == StructuringMethod.PRELIMINARY_TEXT`.
-- **`TypeGuard[PipeLLMBlueprint]`** on `_is_preliminary_text_pipe` eliminates the `# type: ignore[arg-type]` that was bridging `PipeBlueprintUnion → PipeLLMBlueprint` at the elaborator's iteration site.
-- **Bundle re-validation pattern.** `BundleElaborator.elaborate` round-trips the new bundle through `model_validate(elaborated.model_dump(by_alias=True))` purely for error detection — the validate result is discarded and the original `model_copy`-built bundle (with its side-table intact) is returned.
-
-### Open questions / observations
-
-- **`StructuringMethod.DIRECT`** kept in the enum per original plan decision. No functional difference from `None` today. Revisit if no second method materializes.
-
-### How to resume
-
-1. `git status` to see uncommitted state — Phase 8 added test modules + two MTHDS fixtures under `tests/integration/pipelex/pipes/operator/pipe_structure/`. Decide whether to commit before Phase 9.
-2. Move on to **Phase 9 (docs & changelog)**:
- - Restore / rewrite the structuring docs deleted in `16b775b8` (the old runtime mechanism is gone — the new docs explain the build-time elaboration).
- - Add a `PipeStructure` operator page (mirror the `PipeLLM` page).
- - Document the trade-off: `preliminary_text` produces 2 LLM calls per invocation.
- - Add a `[Unreleased]` entry in `CHANGELOG.md`.
- - Reconcile with the partial docs work already on this branch in commits `bb9bdb32` and `fabb22a2` — review them before adding new content.
-3. Then **Phase 10 (final validation)**.
-4. **Cross-repo follow-up (out of scope for this PR):** open a PR on `vscode-pipelex` to refresh `crates/taplo-common/schemas/mthds_schema.json` from `derived/mthds_schema.json` (regenerate via `pipelex-dev generate-mthds-schema`) and ship a new `pipelex-tools` release. Without this, `plxt lint` rejects MTHDS files that author `PipeStructure` directly.
-
----
-
-### CHECKPOINT 3 — end of Phase 8
-
-`structuring_method = preliminary_text` is now exercised end-to-end via the library loader (real-LLM-capable), across all three output multiplicities and across both Python-class and inline-structure concept declarations. `PipeStructure` is also exercised inside hand-authored `PipeSequence` and `PipeBatch`. Kajson round-tripping holds for the synthesized blueprints. Each elaborated run is asserted to issue exactly two LLM calls in live mode. Runtime has no knowledge of `structuring_method`. Tests green, lint/types clean.
-
-State to capture for the next session:
-
-- New MTHDS fixtures under `tests/integration/pipelex/pipes/operator/pipe_structure/`: `text_then_structure_helpers.mthds`, `preliminary_text_e2e.mthds`, `preliminary_text_inline_e2e.mthds`. The earlier `test_structures_basic.mthds` is unchanged.
-- New Python concept class `RestaurantReview` (added to `test_structures_basic.py`) is shared by all Python-class Phase-8 tests; the inline `HikingTripReport` is exercised in the inline-structure test.
-- All synthetic-pipe assertions reference codes `<parent>__draft_text` / `<parent>__structure` (still the working naming convention — revisit only if length pressure surfaces).
-- LLM-call counting uses `ReportingManager._get_or_create_registry(pipeline_run_id).get_current_tokens_usage()` filtered to `LLMTokensUsage`. Helper duplicated across the two e2e test files; if a third consumer appears, hoist it to a shared fixture / utility.
-- One ergonomics gap surfaced: the bundled plxt schema (in `vscode-pipelex/crates/taplo-common/schemas/mthds_schema.json`) does not yet include `PipeStructure`. The `preliminary_text` path is unaffected because the synthesized `PipeStructure` lives in-memory only. Captured as a Phase 9 cross-repo follow-up.
-
----
-
-## Goal
-
-Bring back the "text-then-object" capability that was removed in `16b775b8`, but in a fundamentally different shape:
-
-- Introduce a first-class `PipeStructure` operator (`Text → StructuredConcept`).
-- Add a bundle **elaboration pass** in `pipelex/core/interpreter/` that runs after parsing and before the runtime pipe construction. When it sees a `PipeLLMBlueprint` with `structuring_method = preliminary_text`, it rewrites that single pipe into a `PipeSequence[PipeLLM(text), PipeStructure]`. Synthetic pipes are tracked in a **bundle-level side-table** so the language surface stays clean.
-- The runtime layer (`PipeLLM`, cogt, Temporal) never sees `structuring_method` anymore — it is purely a **build-time directive**.
-
-This keeps every downstream layer simple and gives users a reusable structuring operator they can also call directly when text comes from elsewhere (extracted PDFs, search results, user input).
-
-## Architectural decisions locked in (from review)
-
-- **Synthetic-pipe metadata lives on the bundle, NOT on every pipe.** A new `PipelexBundleBlueprint.elaboration_metadata: dict[str, ElaborationMetadata] | None` side-table stores the synthetic→parent mapping. The base `PipeBlueprint` and runtime `PipeAbstract` do NOT get a `parent_pipe_code` field. This keeps the user-facing pipe schema unpolluted and makes the elaboration concern strictly internal.
-- **PipeStructure's user-prompt template is config-driven.** Defined under `[cogt.llm_config.generic_templates]` next to `output_structure_prompt`, retrievable via `llm_config.get_template(template_name="structuring_prompt")`. Default text shipped in `pipelex.toml`. No hardcoded prompt inside the operator.
-- **PipeStructure accepts any Text-compatible concept.** Validation uses `Concept.are_concept_compatible(strict=False)` so domain concepts that `refines = Text` (e.g. `business.RawDocument`) work without an extra cast pipe. The elaboration path always passes literal `Text`.
-- **Multiplicity rule (matches deleted-code behavior).** Step-1 always produces a **single** `Text`; step-2 (`PipeStructure`) produces the list when the original output was `Foo[]` or `Foo[N]`. Confirmed by reading `make_text_then_object_list` at `16b775b8^:pipelex/pipe_operators/llm/pipe_llm.py`.
-- **Phase 7 is dropped entirely from this PR.** No synthetic-pipe marker, no friendly rendering, no CLI exclusion. Synthetic pipes appear as regular pipes in logs/traces/graph viewer until the follow-up TODOs land. The `bundle.elaboration_metadata` side-table is the durable source of truth that downstream tools can read whenever they're wired up. Keeps this PR focused on the language and runtime change.
-- **`StructuringMethod.DIRECT` is kept as-is.** Functionally a no-op identical to `None`, but kept in the enum for language symmetry and future extensibility. Documented in Open Questions for future revisit.
-
-## Non-goals (explicitly deferred)
-
-- A generic "meta-pipe" framework for arbitrary build-time expansions. We build the one elaboration pass needed today; the abstraction can be extracted once a second concrete need appears.
-- Per-step prompt customization for `structuring_method`. If users want fine control, they author the two pipes by hand using `PipeLLM` + `PipeStructure`.
-- Image inputs on `PipeStructure`. v1 takes Text only; image-aware structuring stays in `PipeLLM`.
-- Friendly synthetic-pipe rendering across logs, traces, and graph viewer. Captured as a follow-up TODO at the end of this file.
-- Any synthetic-pipe marker on graph node tags or CLI listings. Also a follow-up TODO.
-
----
-
-## Phase 1 — Foundations: bundle-level elaboration metadata
-
-A side-table on the bundle blueprint records which synthesized pipes belong to which user-authored pipe and what role they play. Nothing leaks onto the per-pipe blueprint surface or onto the runtime pipe object.
-
-- [ ] In `pipelex/core/bundles/pipelex_bundle_blueprint.py`:
- - [ ] Add a `StepRole(StrEnum)` (or `Literal`) enum with `DRAFT_TEXT = "draft_text"` and `STRUCTURE = "structure"`. Use the StrEnum pattern per `pipelex.types`.
- - [ ] Add an `ElaborationMetadata(BaseModel)` model with `parent_pipe_code: str` and `step_role: StepRole`.
- - [ ] Add `elaboration_metadata: dict[str, ElaborationMetadata] | None = Field(default=None, exclude=True)` to `PipelexBundleBlueprint`. The `exclude=True` ensures it is never serialized back to MTHDS / TOML / JSON.
- - [ ] Add a small accessor: `def get_elaboration_for(pipe_code: str) -> ElaborationMetadata | None`.
-- [ ] Confirm by read-through of `library_manager.py` callers that the bundle blueprint is never re-serialized to disk after construction. If any code path does (`pipelex export`, builder helpers, etc.), audit it to make sure `elaboration_metadata` is dropped on output. The `exclude=True` should make this automatic, but verify.
-- [ ] Unit test: `ElaborationMetadata` round-trips through `model_dump` / `model_validate`. `model_dump` of a `PipelexBundleBlueprint` with `elaboration_metadata` set produces output that has NO `elaboration_metadata` key (excluded).
-
----
-
-## Phase 2 — `PipeStructure` operator (runtime + blueprint + factory)
-
-A minimal operator: one Text-compatible input, one structured output, one LLM call in the middle.
-
-- [ ] Add the structuring prompt template to `pipelex/pipelex.toml` under `[cogt.llm_config.generic_templates]`, alongside `output_structure_prompt`. Default body roughly:
-
- ```toml
- structuring_prompt = """
- Read the following text carefully and produce the requested structured output from it.
-
- ---
- {{ text }}
- """
- ```
-
-- [ ] Create `pipelex/pipe_operators/structure/` with:
- - [ ] `__init__.py`
- - [ ] `exceptions.py` defining `PipeStructureError(PipelexError)`, `PipeStructureFactoryError(PipelexError)`.
- - [ ] `pipe_structure_blueprint.py` defining `PipeStructureBlueprint(PipeBlueprint)`:
- - `type: Literal["PipeStructure"] = "PipeStructure"`
- - `pipe_category: Literal["PipeOperator"] = "PipeOperator"`
- - `model: LLMModelChoice | None = None` — the structuring model (analog of `model_to_structure`).
- - `validate_inputs()` enforces exactly one input, and that input's concept must be **Text-compatible** (use `concept_library.is_compatible(tested_concept=..., wanted_concept=native.Text)` — equivalent to `strict=False`).
- - `validate_output()` enforces the output is NOT Text-compatible (i.e. structured concept).
- - [ ] `pipe_structure.py` defining `PipeStructure(PipeOperator[PipeStructureOutput])`:
- - Holds `llm_choice: LLMModelChoice | None`, `text_input_name: str`, `output_multiplicity: VariableMultiplicity | None`.
- - `_live_run_operator_pipe`:
- 1. Resolve the input `Text` from `working_memory` by `text_input_name`.
- 2. Render the structuring user prompt by loading `cogt.llm_config.get_template(template_name="structuring_prompt")` and substituting `{{ text }}` with the input's text content.
- 3. Append the schema via `get_output_structure_prompt(...)` from `pipelex/pipe_operators/llm/helpers.py` (the same helper PipeLLM uses).
- 4. Resolve the LLM setting with the same precedence as PipeLLM: `self.llm_choice → llm_choice_overrides.for_object → llm_choice_defaults.for_object`.
- 5. Use `output_multiplicity_to_apply` to resolve list vs single, then call `content_generator.make_object` or `content_generator.make_object_list` with `nb_items` from the multiplicity.
- 6. Wrap in `PipeStructureOutput`.
- 7. `_register_execution_data(...)` with `{"resolved_model": ..., "is_multiple_output": ..., "rendered_user_prompt": ..., "structuring_path": "structure"}`.
- - `_dry_run_operator_pipe` mirrors PipeLLM's pattern: delegate to `_live_run_operator_pipe(..., content_generator=ContentGeneratorDry())`. **This bullet is mandatory — without it, dry-run tests will fail.**
- - `validate_inputs_static`, `validate_inputs_with_library`, `validate_output_static`, `validate_output_with_library`: implement to mirror the PipeLLM analogues, minus image / document concerns.
- - `needed_inputs()` returns the single Text input.
- - `required_variables()` returns `{self.text_input_name}` (PipeStructure has no user template variables; the structuring template's only var is `text`, fed from working memory).
- - [ ] `pipe_structure_factory.py` defining `PipeStructureFactory(PipeFactoryProtocol[PipeStructureBlueprint, PipeStructure])`:
- - Resolve LLM choice from `blueprint.model`.
- - Parse output multiplicity from `blueprint.output` (single `Foo`, `Foo[]`, `Foo[N]`).
- - Resolve `text_input_name` from `inputs` (must be exactly one).
- - **No template analysis** (no image refs, no document refs — PipeStructure has no user-controlled prompt). This is intentionally simpler than `PipeLLMFactory`.
-- [ ] Register `PipeStructureBlueprint` in `PipeBlueprintUnion` (`pipelex/core/bundles/pipelex_bundle_blueprint.py`).
-- [ ] Register `PipeStructure` and `PipeStructureFactory` in:
- - [ ] `pipelex/core/registry_models.py` → append to `CoreRegistryModels.PIPE_OPERATORS` and `PIPE_OPERATORS_FACTORY`. The class-registry lookup key is `"PipeStructureFactory"` (computed by `pipe_factory.py:108` as `f"{pipe_type.value}Factory"`).
- - [ ] `pipelex/core/pipes/pipe_blueprint.py` `PipeType` enum → add `PIPE_STRUCTURE = "PipeStructure"` and the corresponding `category` mapping in the match statement (must be exhaustive — no default case allowed).
-- [ ] Audit Temporal data converter / kajson allow-lists. From inspection, `pipelex/temporal/temporal_data_converter.py` does not enumerate pipe types directly; it uses the global class registry. Confirm registration via `CoreRegistryModels` is sufficient.
-- [ ] Unit tests in `tests/unit/pipelex/pipes/operator/pipe_structure/test_pipe_structure.py`:
- - Blueprint validation rejects non-Text-compatible input.
- - Blueprint validation accepts a domain concept that `refines = Text`.
- - Blueprint validation rejects Text output.
- - Factory produces a runtime `PipeStructure` with the right model choice and output multiplicity for `Foo`, `Foo[]`, `Foo[N]`.
- - Long pipe_code edge case: declare a `PipeStructure` with a maximally long valid snake_case pipe_code; confirm the factory and runtime construct successfully.
- - Dry-run: `_dry_run_operator_pipe` produces a dry-run output without LLM calls.
-- [ ] Integration test running `PipeStructure` end-to-end on a small fixture concept (use the existing `inference` / `llm` markers).
-
----
-
-### CHECKPOINT 1
-
-`PipeStructure` exists as a standalone, directly-usable operator. A `.mthds` file can declare a `PipeStructure` pipe and run it. Elaboration not introduced yet. `make agent-check` and `make agent-test` are green.
-
-State to capture in this file at checkpoint time:
-
-- File paths created.
-- Open questions that surfaced during implementation.
-- Anything deferred to later phases.
-
----
-
-## Phase 3 — `PipeStructureSpec` (authoring layer)
-
-Mirror the operator at the spec layer so AI builders authoring via specs can declare it.
-
-- [ ] Create `pipelex/builder/pipe/pipe_structure_spec.py` defining `PipeStructureSpec(PipeSpec)`:
- - `type: SkipJsonSchema[Literal["PipeStructure"]] = "PipeStructure"`
- - `pipe_category: SkipJsonSchema[Literal["PipeOperator"]] = "PipeOperator"`
- - `model: str | None = Field(default=None, description="...")`
- - `to_blueprint()` returning `PipeStructureBlueprint`.
- - `rendered_pretty()` consistent with the other spec classes.
-- [ ] Add `PipeStructureSpec` to `PipeSpecUnion` in `pipelex/builder/pipe/pipe_spec_union.py`.
-- [ ] Add `PipeStructureSpec` to `pipelex/builder/pipe/pipe_spec_map.py` if that mapping exists.
-- [ ] Unit test for the spec → blueprint round-trip.
-
----
-
-## Phase 4 — Bundle elaboration framework
-
-Add the elaboration pass infrastructure, kept narrow on purpose. No generic plugin system yet.
-
-- [ ] Create `pipelex/core/interpreter/bundle_elaborator.py`:
- - [ ] `BundleElaboratorError(PipelexInterpreterError)` exception type.
- - [ ] `class BundleElaborator` with a single classmethod `elaborate(bundle: PipelexBundleBlueprint) -> PipelexBundleBlueprint`.
- - [ ] **Fast-path short-circuit**: scan bundle for any `PipeLLMBlueprint` with `structuring_method == StructuringMethod.PRELIMINARY_TEXT`. If none found, return the input bundle unchanged. **This avoids per-bundle dump/validate overhead in the common case.**
- - [ ] When elaboration is needed, build a NEW `PipelexBundleBlueprint` (don't mutate input). Copy `domain`, `description`, `system_prompt`, `main_pipe`, `concept`, `source` over; rebuild `pipe` dict by walking each entry; populate `elaboration_metadata` with one entry per synthetic pipe inserted.
- - [ ] Internal helpers per elaboration kind. v1 has only `_elaborate_preliminary_text` (Phase 5), but the dispatch is structured so adding more is mechanical.
- - [ ] **Recursive-elaboration guard**: after elaboration, assert that no synthetic blueprint contains a `preliminary_text` directive itself. Raise `BundleElaboratorError` if violated. Cheap defense in depth — protects against future mistakes when adding new elaboration kinds.
- - [ ] **Post-elaboration re-validation**: after producing the new bundle dict, call `PipelexBundleBlueprint.model_validate(elaborated.model_dump(...))` once more to re-run bundle-level validators (`validate_local_concept_references`, `validate_local_pipe_references`, `validate_main_pipe`) against the synthetic pipes. Wrap any `ValidationError` in `BundleElaboratorError` with context naming which synthetic pipe triggered it. Skip when the fast-path short-circuit fired.
-- [ ] Wire elaboration into `PipelexInterpreter.make_pipelex_bundle_blueprint()` in `pipelex/core/interpreter/interpreter.py`. After the existing `model_validate(blueprint_dict)` and `pipelex_bundle_blueprint.source = ...`, call `BundleElaborator.elaborate(...)` and return the elaborated bundle. Errors raised by the elaborator must surface as `PipelexInterpreterError` with clear context (which pipe, which directive).
-- [ ] Verify all callers of `make_pipelex_bundle_blueprint()` (in `library_manager.py` lines 363, 697, 909) still work; the contract is unchanged from their perspective.
-- [ ] Unit tests in `tests/unit/pipelex/core/interpreter/test_bundle_elaborator.py`:
- - Vanilla bundle (no `preliminary_text`, contains `PipeLLM`, `PipeFunc`, `PipeImgGen` mix) → elaborator returns the input unchanged (use `is` identity check to confirm short-circuit, not just equality).
- - Empty `bundle.pipe = None` or `{}` → no crash, returns unchanged.
- - Recursive-elaboration guard fires when a synthetic blueprint is artificially given `preliminary_text` (test the guard itself).
-
----
-
-## Phase 5 — `preliminary_text` elaboration
-
-Implement the actual rewrite. This is the meat of the change.
-
-- [ ] In `BundleElaborator._elaborate_preliminary_text`, given an entry `(pipe_code, PipeLLMBlueprint)` with `structuring_method = preliminary_text`:
- - [ ] **Pre-checks** (raise `BundleElaboratorError` with good context on failure):
- - [ ] Output concept must NOT be Text-compatible. (Today this is a runtime check in `pipe_llm.py:66`; move it here with a clear message tying back to the user's pipe code.)
- - [ ] No collision: synthetic codes (`<pipe_code>__draft_text`, `<pipe_code>__structure`) must not already exist in `bundle.pipe`.
- - [ ] Synthetic codes must pass `is_pipe_code_valid` (snake_case check). Raise with a clear message if the original `pipe_code` is so long that the suffixed synthetic code becomes invalid.
- - [ ] **Synthesize step-1**: a `PipeLLMBlueprint` keyed at `<pipe_code>__draft_text`:
- - `inputs = original.inputs` (all of them — including any image inputs the user declared).
- - `system_prompt = original.system_prompt` (verbatim).
- - `prompt = original.prompt` (verbatim).
- - `model = original.model` (verbatim).
- - `model_to_structure = None` (step-1 produces Text, no structuring needed).
- - `output = "Text"` — **always single Text**, never `Text[]` or `Text[N]`. This matches the deleted code's `make_text_then_object_list` behavior, where one preliminary text was structured into N objects.
- - `structuring_method = None`.
- - `description = f"Draft text for {pipe_code}"`.
- - [ ] **Synthesize step-2**: a `PipeStructureBlueprint` keyed at `<pipe_code>__structure`:
- - `inputs = {"draft_text": "Text"}`.
- - `output = original.output` (preserves multiplicity: `Foo`, `Foo[]`, or `Foo[N]`).
- - `model = original.model_to_structure` (may be `None` → step-2 falls back to `model_deck.llm_choice_overrides.for_object` at runtime; this is identical to the old PipeLLM behavior when `model_to_structure` was not set).
- - `description = f"Structure step for {pipe_code}"`.
- - [ ] **Synthesize the wrapping sequence**: a `PipeSequenceBlueprint` keyed at the original `pipe_code`:
- - `inputs = original.inputs`.
- - `output = original.output`.
- - `description = original.description`.
- - `steps = [SubPipeBlueprint(pipe="<code>__draft_text", result="draft_text"), SubPipeBlueprint(pipe="<code>__structure", result=<original_result_or_pipe_code>)]`.
- - Step references use **bare codes** (no domain prefix), per the bundle's same-domain reference convention.
- - [ ] Insert all three blueprints into the new `pipe` dict (replacing the original entry at `pipe_code`).
- - [ ] Register two entries in `elaboration_metadata`:
- - `<pipe_code>__draft_text → ElaborationMetadata(parent_pipe_code=pipe_code, step_role=DRAFT_TEXT)`.
- - `<pipe_code>__structure → ElaborationMetadata(parent_pipe_code=pipe_code, step_role=STRUCTURE)`.
- - The wrapping sequence is NOT registered — it's the user-facing pipe.
-- [ ] **Image-input handling**: deliberately do NOT add explicit drop logic. Step-2's input dict is `{"draft_text": "Text"}` and step-2's prompt template is the canned `structuring_prompt`, which references only `{{ text }}`. Any image variables on the original prompt naturally flow only to step-1, where they belong. Document this in a code comment in `_elaborate_preliminary_text` so future maintainers understand the mechanism.
-- [ ] Unit tests in `tests/unit/pipelex/core/interpreter/test_bundle_elaborator.py`:
- - [ ] Bundle with one `preliminary_text` PipeLLM produces the expected three-pipe structure (one PipeSequence + two synthetic pipes) and two `elaboration_metadata` entries.
- - [ ] Output `Text` raises `BundleElaboratorError` with a message naming the user's pipe code.
- - [ ] Output `Text`-compatible concept (refines Text) ALSO raises `BundleElaboratorError`.
- - [ ] Synthetic-name collision raises `BundleElaboratorError`.
- - [ ] Multiplicity preserved for `Foo`, `Foo[]`, `Foo[N]`. Step-1's output is always literal `Text` (single), regardless of original output's multiplicity.
- - [ ] Image input present on original → declared on step-1's `inputs`, NOT declared on step-2's `inputs`.
- - [ ] `model_to_structure = None` on original → step-2 has `model = None` (defaults applied at runtime).
- - [ ] `main_pipe = "<pipe_code>"` pointing at the original `preliminary_text` pipe → still resolves correctly post-elaboration (the original code is now the wrapping sequence). This is a **mandatory regression test** per review.
- - [ ] Long pipe_code edge case: original pipe_code at the boundary of `is_pipe_code_valid` length → either passes or fails with a clear message.
- - [ ] Bundle without `preliminary_text` is unchanged (identity check confirming short-circuit).
-- [ ] Integration test (`tests/integration/...`) running an end-to-end `preliminary_text` PipeLLM through a real LLM call, asserting the structured output is valid. Use `inference` and `llm` markers.
-
----
-
-### CHECKPOINT 2
-
-`structuring_method = preliminary_text` works end-to-end via elaboration. Tests green. The runtime layer still has the legacy field on `PipeLLM` though — Phase 6 cleans it.
-
-State to capture:
-
-- Final synthetic naming convention chosen (`__draft_text` / `__structure` is the working assumption — see Open Questions).
-- Multiplicity confirmed as "single Text → list" (matches deleted code).
-- Any blockers found in the existing factories or registries.
-
----
-
-## Phase 6 — Remove `structuring_method` from runtime `PipeLLM`
-
-The field is now purely a build-time directive. The runtime should not know about it.
-
-- [ ] Remove `structuring_method: StructuringMethod | None = None` from `PipeLLM` (`pipelex/pipe_operators/llm/pipe_llm.py:61`).
-- [ ] Remove the `validate_output_concept_consistency` validator (`pipe_llm.py:64-72`) — the elaborator now owns this check.
-- [ ] Remove the `if self.structuring_method is not None:` block in `_live_run_operator_pipe` (the `NotImplementedError` raise site at `pipe_llm.py:190-199`).
-- [ ] Remove the `structuring_method` line in `execution_data_dict` near `pipe_llm.py:338-339`.
-- [ ] In `PipeLLMFactory.make()` (`pipe_llm_factory.py:148`): stop passing `structuring_method=blueprint.structuring_method` to the `PipeLLM(...)` constructor.
-- [ ] Keep `structuring_method` on `PipeLLMBlueprint` — it remains part of the language surface and is consumed by the elaborator. Add a `model_validator(mode="after")` on `PipeLLMBlueprint` that enforces the same rule the elaborator does: `structuring_method != PRELIMINARY_TEXT or output is not Text-compatible`. Raise plain `ValueError` (Pydantic convention; `PipelexInterpreter` already wraps `ValidationError` into `PipelexInterpreterError` with categorized error data). Authoring-time errors then surface during `model_validate`, before the elaborator runs. The elaborator's own check stays as defense in depth.
-- [ ] Add `structuring_method: StructuringMethod | None = None` field to `PipeLLMSpec` (`pipelex/builder/pipe/pipe_llm_spec.py`) so AI builders can opt in. Use plain `Field(default=None, description="...")` — **NOT** `SkipJsonSchema` — so the field appears in the JSON schema given to AI agents.
-- [ ] Update `PipeLLMSpec.to_blueprint()` to forward the field.
-- [ ] Run `make agent-check` and verify the `StructuringMethod` enum is still imported only where it's used (the blueprint, the spec, the elaborator).
-
----
-
-## Phase 7 — Skipped
-
-All trace/log/CLI/graph-viewer integration work is deferred to follow-up TODOs at the bottom of this file. The runtime stays unaware of which pipes are synthetic; only `bundle.elaboration_metadata` knows. Downstream tools can opt in later by consulting that side-table when they load bundles.
-
-**Do not add anything to this phase.** Anything that would touch tracer / CLI / graph viewer / run reporting belongs in the follow-up TODO list, not here.
-
----
-
-## Phase 8 — Round-out tests
-
-Belt-and-suspenders coverage.
-
-- [ ] Test: running the same `preliminary_text` PipeLLM via Temporal works (elaboration runs once at bundle load; Temporal sees only the expanded form). Use the existing Temporal integration test infrastructure.
-- [ ] Test: kajson serialization of the elaborated bundle (or its individual synthetic pipes) round-trips correctly. Specifically, confirm `PipeStructureBlueprint` and `PipeLLMBlueprint` round-trip through `kajson.dumps` / `kajson.loads`.
-- [ ] Test: an MTHDS file with `structuring_method = "preliminary_text"` validates and parses (not just programmatic blueprints). Add a fixture `.mthds` file under `tests/...`.
-- [ ] Test: directly using `PipeStructure` in a hand-written `PipeSequence` (independent of the elaboration sugar).
-- [ ] Test: `PipeStructure` inside a `PipeBatch` — process a list of texts, structuring each into a `Foo`. This is a common composition users will reach for.
-- [ ] Test: confirm the "no preliminary_text → no behavior change" guarantee — the existing PipeLLM test suite passes unchanged. **Mandatory regression gate.**
-- [ ] Test: an MTHDS file that previously failed with `NotImplementedError` (the current behavior in `pipe_llm.py:194-197`) now succeeds. Delete the old negative-case test that asserted that NotImplementedError, if any exists.
-
----
-
-## Phase 9 — Documentation & changelog
-
-- [ ] Add a docs page for `PipeStructure` under the operators section (mirror the structure of the `PipeLLM` page). Cover: what it does, when to use it, inputs / outputs, model choice, examples (including text-from-PDF and text-from-search-results scenarios).
-- [ ] Restore / rewrite the structuring docs that were deleted in `16b775b8` (the deleted file was `*/llm-structured-generation-config.md` per that commit's stat). New version explains the build-time elaboration behavior, NOT the old runtime mechanism. Show before/after of what the user writes vs what runs.
-- [ ] Note in the docs: `preliminary_text` produces 2 LLM calls per invocation (text + structure). Document the trade-off vs single-call structuring.
-- [ ] Add an entry under `[Unreleased]` in `CHANGELOG.md` summarizing: new `PipeStructure` operator, `structuring_method = preliminary_text` works again, runtime simplification.
-- [ ] Cross-check `mkdocs.yml` includes any new doc pages.
-- [ ] Reconcile with the partial docs work already on this branch in commits `bb9bdb32` and `fabb22a2` — review them before adding new content to avoid duplication.
-
----
-
-## Phase 10 — Final validation
-
-- [ ] `make agent-check` (lint + types) clean.
-- [ ] `make agent-test` (full test suite) clean.
-- [ ] Manually run a small `.mthds` example using `structuring_method = preliminary_text` and a separate one using `PipeStructure` directly. Confirm both produce structured output.
-- [ ] Spot-check a graph trace for a `preliminary_text` run — synthetic pipes will appear as regular nodes for now (no marker). Confirm the run completes successfully and the output structure matches the user's declared output concept. Note any rendering oddities for the follow-up TODOs.
-- [ ] Update this `TODOS.md` with any deviations from the plan and remaining follow-ups.
-
----
-
-## Open questions to revisit during implementation
-
-- **Synthetic-name pattern**: `__draft_text` / `__structure` (descriptive) vs shorter (`__t` / `__s`). Plan assumes descriptive. Revisit only if pipe-code length becomes a real problem in practice.
-- **`StructuringMethod.DIRECT` enum value**: kept for symmetry per decision during planning. Functionally identical to `None`. Revisit if the enum stays single-meaningful-value for too long without a second method appearing.
-- **Recursive elaboration**: v1 only expands the top-level `bundle.pipe` dict and explicitly guards against synthetic blueprints containing `preliminary_text` (Phase 4 guard). If a future elaboration kind needs fixed-point iteration, lift that guard into a proper iteration loop.
-- **`PipeStructure` direct-usage validation strictness**: plan accepts any Text-compatible concept. If users frequently misuse this with concepts that *technically* refine Text but are semantically not text-like, tighten later.
-
----
-
-## Follow-up TODOs (out of scope for this PR)
-
-These are captured here for project tracking; they should be moved to wherever the team tracks deferred work after this PR lands.
-
-1. **Synthetic-pipe marker on graph node tags + CLI listing exclusion.** Smallest follow-up: when emitting `NodeSpec`, look up `bundle.elaboration_metadata.get(self.code)` and, if present, set `tags["synthetic"] = "true"` and `tags["parent_pipe_code"] = parent`. Plumbing question: the graph tracer doesn't currently have direct access to the bundle, so this needs either (a) an optional runtime-only field on `PipeAbstract` populated by the factory, or (b) a side-registry keyed by pipe code. Also: hide synthetic pipes from `pipelex list`-style CLI surfaces. Cheap, ~2–3 file edits.
-
-2. **Friendly synthetic-pipe rendering across logs, traces, and run-reporting.** After (1) lands, render `<parent_pipe_code> [<step_role_label>]` everywhere `self.code` appears in observability surfaces. Touches: graph_tracer, run_reporting, journal, distributed-tracing files. Estimate ~5–8 file edits. Driver: observability UX.
-
-3. **`mthds-ui` graph viewer integration.** After (1) ships the `tags["synthetic"]` API, decide in the UI repo whether to nest synthetic pipes under their parent or hide them entirely. Requires `mthds-ui` repo work that this PR does not block on.
-
-4. **Bundle-load benchmark in CI.** Microbenchmark library load time on a representative library set; alert on >5% regression. Protects against future elaboration-pass additions silently slowing startup.
-
-5. **PipeStructure image input support.** When a concrete need arises (e.g. structure a PDF page image into an invoice without an intermediate `PipeExtract`), extend `PipeStructure` to accept an optional image input alongside the Text input. Out of scope for v1 to keep the operator narrow.
-
-6. **Per-step prompt customization for `structuring_method = preliminary_text`.** If users complain that the canned `structuring_prompt` is wrong for their domain, expose a per-pipe override on `PipeLLMBlueprint` that gets propagated to the synthesized step-2. Don't build until requested.
-
-7. **Generic meta-pipe / build-time elaboration framework.** When a SECOND build-time elaboration directive appears, promote `BundleElaborator._elaborate_preliminary_text` into a registry of elaboration plugins. Today's narrow shape is intentional.
-
-8. **`pipelex-dev elaborate-bundle <path>`** debugging CLI to print the elaborated form of a bundle without running it. Helpful when diagnosing weird behavior. Low priority.
-
-9. **Revisit `StructuringMethod.DIRECT`** — currently kept for symmetry. If a year passes with no second method materializing and no consumer for `DIRECT`, delete it.
-
-10. **Persist `elaboration_metadata` into MTHDS / JSON exports.** Today the side-table is `Field(exclude=True)`, so it survives `model_copy` but is dropped by every `model_dump` / `model_validate` round-trip. The dependency loader has a special case (`LibraryManager._load_single_dependency` walks `dep_blueprints[*].elaboration_metadata` to keep synthetic helpers attached to exported parents). When a second cross-boundary consumer materializes — graph viewer over a serialized bundle, Temporal payload, persistent library cache — drop `exclude=True`, regenerate `derived/mthds_schema.json` via `pipelex-dev generate-mthds-schema`, and ship a corresponding `vscode-pipelex/crates/taplo-common/schemas/mthds_schema.json` bump so plxt accepts the field. The unit regression at `tests/unit/pipelex/core/bundles/test_elaboration_metadata.py::test_bundle_round_trip_drops_elaboration_metadata` will be the first to flip.
diff --git a/wip/security/webhook-signing.md b/wip/webhook-signing.md
similarity index 93%
rename from wip/security/webhook-signing.md
rename to wip/webhook-signing.md
index 83739dce7..e6a3f4a52 100644
--- a/wip/security/webhook-signing.md
+++ b/wip/webhook-signing.md
@@ -1,8 +1,8 @@
# Webhook signing — security track
-This plan covers webhook signing for the `pipelex → pipelex-api → external receiver` completion-callback flow. It is **independent of the error-handling refactor** ([`../error-handling/`](../error-handling/)) — the two were originally bundled in the same TODO list because the same cross-repo PR window was convenient, but they have no functional dependency on each other.
+This plan covers webhook signing for the `pipelex → pipelex-api → external receiver` completion-callback flow. It is **independent of the error-handling refactor** ([`error-handling/`](error-handling/)) — they have no functional dependency on each other.
-Splitting signing into its own track lets reviewers evaluate it on security merit (trust topology, threat model, tamper detection, rollout safety) rather than as a footnote to an error-handling PR.
+Splitting signing into its own track lets reviewers evaluate it on security merit: trust topology, threat model, tamper detection, rollout safety.
---
@@ -223,6 +223,6 @@ The pipelex-api companion plan (when written) lives at `pipelex-api/wip/security
## How this relates to the error-handling refactor
-The error-handling refactor at [`../error-handling/`](../error-handling/) (and its execution plan at [`../../TODOS.md`](../../TODOS.md)) lands Item D-2, which puts a structured `error` dict on the webhook body. That meaningfully expands the tamper surface — a MitM body rewrite previously could change `status` / `result_url`, now it can also rewrite the classification.
+The error-handling work (in [`error-handling/`](error-handling/)) puts a structured `error` dict on the webhook body. That meaningfully expands the tamper surface — a MitM body rewrite previously could change `status` / `result_url`, now it can also rewrite the classification.
-The error-handling refactor is **the motivating context** for accelerating this signing work, but the signing fix itself is correct independent of D-2. The two PR series can be merged on independent schedules; there is no functional dependency.
+That expanded tamper surface is **the motivating context** for accelerating this signing work, but the signing fix itself is correct independently. The two can land on independent schedules; there is no functional dependency.