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.
tidy wip docs
Louis Choquelecf7e1f7def9
diff --git a/wip/img-gen-size/deferred-review-findings.md b/wip/img-gen-size/deferred-review-findings.mddeleted file mode 100644index 02fde059d..000000000--- a/wip/img-gen-size/deferred-review-findings.md+++ /dev/null@@ -1,23 +0,0 @@-# Portable img-gen size — deferred review findings--Non-bug findings from the Checkpoint 4 feature-wide `/code-review` (context-free, `17f478e7b..HEAD`) that are design tradeoffs or polish rather than correctness fixes. The correctness findings from that review (non-positive `ImageSize` crash, exact-size deck default silently defeating an explicit pipe `aspect_ratio`, gateway unknown-taxonomy hard-fail on size-unset jobs) were fixed in the Checkpoint 4 follow-up commit.--## Gateway user gets a deck-config error message they cannot action--Under gateway routing, a sized request on a gemini model whose remote spec has no `rules` yields "set rules.aspect_ratio to a Gemini taxonomy (e.g. 'gemini_3_flash')" — an instruction only someone editing the gateway catalog can follow, not a gateway end user. Fail-loud and correct, but the message could branch on the spec's origin (remote catalog vs local deck) to say "this gateway model does not support size selection yet" instead. Revisit if a user actually hits it: Pipelex owns the catalog and the rules are deployed (verified live by the Phase 4 e2e smoke), so the population should be empty.--## Blueprint-load "hard validation error" only fires when routing resolves rules--The static (blueprint-load) arm of size validation silently skips when the pipe's model choice resolves through a preset/alias or a spec without rules (`PipeImgGen._validate_param_support_against_model_rules` returns early). That is the documented two-layer design — the runtime pre-call check still catches everything — but it means the default `all_pipelex_gateway` profile relies on the remote catalog carrying the rules. The related integration test forces `all_google` routing; default-routing static validation is untested by design (it depends on remote state).--## The size⊕aspect_ratio exclusivity is invisible to the JSON schema--The mutual exclusion of an exact `size` and `aspect_ratio` lives in a pydantic `model_validator`, which the generated MTHDS JSON Schema cannot express — `plxt lint` passes a bundle that blueprint load rejects. Expressing it as a schema `not`/`dependencies` construct in the generator's post-processing would close the gap; weigh against generator complexity if editor-time feedback for this case proves valuable.--## Gemini-taxonomy models routed through an args-dict img-gen worker would silently drop the resolved size--The GEMINI branch of `ImgGenArgsFactory.make_args_from_aspect_ratio` resolves and validates the `(aspect_ratio, size)` pair through the taxonomy grids, then returns only the ratio literal — by design, because the two real gemini wire paths build their own `image_config` (the native `GoogleImgGenWorker` directly, the gateway via `GatewayFactory.make_extras` on the `gateway_completions` path). But the args-dict workers (`GatewayImgGenWorker`/`gateway_img_gen`, fal, HuggingFace, azure_rest, openai) also consume this branch: if a gemini-taxonomy model were ever routed through one of them, a requested `2k`/`4k` would validate client-side and then silently fall back to the provider's 1K default. Today that routing doesn't exist — the gateway remote catalog defaults gemini img-gen models to `gateway_completions` (no per-model `sdk` override), the kit deck uses the native `google` sdk, and the Phase 4 live e2e proved exact 2K pixels through `all_pipelex_gateway`. Hardening would require splitting "validate the pair" from "build wire args" (the same branch backs `img_gen_param_support` checks, which must not raise on valid sized pairs). Revisit if the remote catalog ever re-routes a gemini image model to `gateway_img_gen`.--## `'0.5k'` still listed by `SizeTier.quoted_tokens()` error messages--The spec field description now marks `'0.5k'` as reserved, but the parse-error message ("expected a size tier ('0.5k', '1k', '2k', '4k')...") and the blueprint exclusivity message still enumerate it via `quoted_tokens()`. It *is* a parseable token (rejected later per-model with an honest reason), so the parse layer is not lying — but a user steered to it gets a second error. Fold a "reserved" annotation into `quoted_tokens()` if this confuses anyone in practice; it disappears entirely once the 0.5k wire token is verified and enabled (see the feature's out-of-scope list).diff --git a/wip/img-gen-size/design.md b/wip/img-gen-size/design.mddeleted file mode 100644index 39249a384..000000000--- a/wip/img-gen-size/design.md+++ /dev/null@@ -1,139 +0,0 @@-# Portable image size for image generation — design--Supersedes `wip/gemini-img-gen-size-tier-follow-up.md` (Gemini-only follow-up note, now folded in here). Deferred from the Gemini 3.1 aspect-ratio work on `feature/Img2Img-with-gpt-image`.--## The promise--Pipelex abstracts away provider APIs. For image size that means: a `PipeImgGen` in a bundle carries a size intent, and switching the pipe's `model` between providers (Google ↔ OpenAI ↔ anything else) **adapts when the intent is satisfiable and raises a validation error when it is not** — in both directions, ideally at blueprint-load time. We face the future: the newest models (Gemini 3.x size tiers up to 4K, gpt-image-2 arbitrary exact sizes) get first-class access even where older models can't follow.--## Provider landscape--The two flagship providers speak opposite size dialects, and the older models barely speak at all:--| Model family | Size control | Values / constraints |-| --- | --- | --- |-| Gemini 2.5 Flash Image (nano-banana) | none | 1K fixed, standard ratios |-| Gemini 3 Pro Image (nano-banana-pro) | tier | `1K`/`2K`/`4K`, standard ratios only |-| Gemini 3.1 Flash Image (nano-banana-2) | tier | `1K`/`2K`/`4K` + published 512px grid (wire token unconfirmed), all ratios incl. banners |-| Gemini 3.1 Flash Lite Image | none | 1K fixed |-| OpenAI gpt-image-1 / -1-mini / -1.5 (legacy) | fixed sizes | `1024x1024`, `1536x1024`, `1024x1536` |-| OpenAI gpt-image-2 | arbitrary exact WxH | multiples of 16, max edge < 3840, long:short ≤ 3:1, 0.65–8.29 MP, reliability boundary 2560×1440 |-| Flux / Flux 1.1 Ultra / SDXL / Qwen (fal) | none | aspect-ratio presets only, ~1–1.6 MP outputs |--Key facts about current code:--- `ImgGenJobParams.size` is an `ImageSize` (exact width/height) that **nothing populates** — a dead wire aimed at the OpenAI exact-size path. `OpenAIImgGenFactory.size_for_gpt_image_2` + `validate_gpt_image_2_size` already implement the real gpt-image-2 constraints.-- The Google worker **hardcodes `size="1K"`** and never sends `image_size` on the wire; `GoogleImgGenFactory` already holds the full Gemini 3 grids at 1K/2K/4K, unreachable in production. The gateway path is the same (`# "image_size": "2K"` commented out in `gateway_factory.py`).-- Google image models have **no `rules` block in the deck**, so `PipeImgGen._validate_param_support_against_model_rules` silently skips them — an unsupported aspect ratio on nano-banana today only fails at runtime. OpenAI models do have rules and get static validation.-- The installed google-genai SDK types `ImageConfig.image_size` as open `str` documented as `1K`/`2K`/`4K`; the 512px column Google publishes for Gemini 3.1 Flash has no confirmed wire token yet.--## Design decisions (settled with Louis, 2026-07-02)--1. **One `size` field** on the pipe, accepting either a portable **tier token** or an **exact `WxH`** — not two separate fields, not tier-only.-2. **Exact-grid match** when an exact size hits a tier-grid model: if the WxH exactly equals a cell of the model's published grid, derive (aspect ratio, tier) and run; otherwise validation error naming the nearest valid cells. Never silently snap.-3. **`1k` is satisfiable everywhere** a model natively produces ~1K-class images (Flux, SDXL, Qwen, legacy gpt-image, nano-banana, lite) — accepted as a no-op. Unsatisfiable tiers (`2k` on Flux, `4k` on gpt-image-2, `0.5k` anywhere but Gemini 3.1 Flash) are **hard validation errors**, never warn-and-ignore.-4. **Google per-model gating moves into deck rules** (in scope): Google image models get `rules` blocks and a Google geometry taxonomy, closing the static-validation gap so model switching is checked at load time in both directions.--## The `size` field--```toml-[pipe.render_poster]-type = "PipeImgGen"-prompt = "..."-model = "nano-banana-2"-aspect_ratio = "landscape_16_9"-size = "2k" # portable tier: "0.5k" | "1k" | "2k" | "4k"--# expert mode — exact pixels (gpt-image-2-class models):-# size = "2048x1152" # aspect_ratio is then forbidden: the size implies it-```--**Semantics of a tier**: "produce this pixel class at my chosen `aspect_ratio`". A tier promises a class, **not identical pixel dimensions across providers** — `size = "2k"` at 16:9 yields 2752×1536 on nano-banana-2 (Google's grid) and 3072×1728 on gpt-image-2 (our computed table). Both are 2K-class; that is the abstraction.--**Semantics of an exact size**: "produce exactly these pixels". Deterministic everywhere it runs; models that cannot hit the exact dims reject at validation.--**Interaction with `aspect_ratio`**: a tier composes with `aspect_ratio` (which keeps its current default behavior). An exact size *implies* a ratio, so setting both `size = "WxH"` and `aspect_ratio` is a blueprint validation error — no silent precedence.--### Types and parsing--- New `SizeTier` StrEnum in `img_gen_job_components.py`, next to `AspectRatio`: `HALF_K = "0.5k"`, `ONE_K = "1k"`, `TWO_K = "2k"`, `FOUR_K = "4k"`.-- `ImgGenJobParams.size` becomes `SizeTier | ImageSize | None` with a `BeforeValidator` that parses strings: a tier token → `SizeTier`, `"<int>x<int>"` → `ImageSize`, anything else → clear `ValueError`. Both arms serialize cleanly (StrEnum as str, `ImageSize` as dict), so the union is wire-safe.-- `PipeImgGenBlueprint.size` / `PipeImgGenSpec.size` use the same annotated union, so the MTHDS JSON Schema exposes enum-or-pattern for editors. Blueprint gains the `size`-vs-`aspect_ratio` exclusivity validator.-- `PipeImgGen` threads `self.size or img_gen_param_defaults.size` into `ImgGenJobParams` like the other one-time settings.-- `ImgGenJobParamsDefaults` gains optional `size` (class default `None` per config rules — `None` means "provider default", no key added to `pipelex.toml` or `.pipelex/pipelex.toml`). `ImgGenSetting` (deck presets) deliberately does **not** get `size`: geometry is pipe intent, not model preset — revisit only if a real "4k-img-gen preset" need materializes.--## Per-provider mapping--### Google Gemini (native worker + gateway)--- Tier → `image_config.image_size` wire token (`"1k"` → `"1K"`, etc.). **Omit the param when `size` is unset** so the provider default (1K) applies — never silently upgrade, since 2K/4K cost proportionally more output tokens.-- The worker stops hardcoding `"1K"`; computed grid dims keep stamping `GeneratedImageRawDetails.size` metadata as today.-- Exact size → **exact-grid match**: search the model's grids for a cell equal to WxH; on hit, derive (ratio, tier) and proceed exactly as if the user had written them; on miss, `ImgGenParameterError` suggesting the nearest cells (same or adjacent ratio, closest area). So a bundle written for gpt-image-2 with `size = "2048x2048"` runs on nano-banana-2 (1:1 @ 2K), while `"2000x2000"` errors with "did you mean 2048x2048 (square @ 2k)?".-- Per-model gating (which tiers, which ratios) moves out of the `GoogleImageGenModel` name-enum `match` in `GoogleImgGenFactory` and into deck rules (below). The dimension grids stay in the factory as the single source of truth for dims.-- `gateway_factory.make_extras` threads the same `image_size` into `extra_body["image_config"]` for gemini-routed jobs.-- **0.5k tier**: grid dims are published (1:1 512×512, 1:4 256×1024, 1:8 192×1536, 2:3 424×632, 3:2 632×424, 3:4 448×600, 4:1 1024×256, 4:3 600×448, 4:5 464×576, 5:4 576×464, 8:1 1536×192, 9:16 384×688, 16:9 688×384, 21:9 792×168) but the wire token is unverified — the SDK documents only `1K`/`2K`/`4K` while the field is open `str`. Ship `1k`/`2k`/`4k` first; `0.5k` lands behind an empirical wire test against Gemini 3.1 Flash (try `"512"` / `"0.5K"`; if neither works, `0.5k` stays a validation error on every model until Google opens it).--### OpenAI gpt-image-2--- Tier → computed exact size by **scaling the existing 1K preset table** (`GPT_IMAGE_2_ASPECT_RATIO_TO_SIZE`): `2k` = ×2 per edge, `0.5k` = ×½, `4k` = ×4, then run the result through the existing `validate_gpt_image_2_size`. Verified outcomes:- - `2k`: every supported ratio stays valid (all cells remain multiples of 16, max edge 3584 < 3840, max 7.08 MP < 8.29 MP). All 2K cells sit above the 2560×1440 reliability boundary, so the existing warning fires — keep it (it reflects OpenAI's documented boundary) but demote to `log.verbose` for tier-derived sizes, reserving the loud warning for user-supplied exact sizes.- - `4k`: every ratio violates max edge and/or pixel cap → validation error ("gpt-image-2 caps out below 4K; use 2k or an exact size ≤ 8.29 MP").- - `0.5k`: every ratio falls below the 0.65 MP floor → validation error.- - Rejected alternative: computing dims from a constant pixel budget per tier (closer to Google's constant-area semantics). Doubling wins on simplicity, keeps the shipped 1K presets as the anchor, and produces OpenAI-round numbers; the class overshoot on wide ratios is acceptable because a tier is a class, not a dims contract.-- Exact size → existing pass-through + validation, unchanged.--### Legacy gpt-image (gpt-image-1 / -1-mini / -1.5)--- Tier `1k` → the existing fixed size for the chosen ratio (that grid *is* the 1K class); `0.5k`/`2k`/`4k` → validation error.-- Exact size → existing behavior (only the fixed sizes accepted).--### Flux / Flux 1.1 Ultra / SDXL / Qwen--- Tier `1k` → accepted as a no-op (their native outputs are 1K-class); `0.5k`/`2k`/`4k` → validation error.-- Exact size → validation error ("this model does not support exact sizes; use aspect_ratio, optionally with size = '1k'").--## Rules, taxonomy, and validation--Aspect ratio and size are one entangled concern per provider (one `size` param on OpenAI, one `image_config` on Google, one grid lookup for dims), and the code already reflects it: `make_args_from_aspect_ratio` takes `size`, and `ImgGenParamSupport.check_aspect_ratio` reuses it. The design leans into that:--- **Keep the topic named `aspect_ratio`** (no rename). The key appears in the `[model.rules]` blocks of backend TOMLs — a user-writable config surface (custom model registration, the add-model workflow), and that vocabulary should match what users know from blueprints (`aspect_ratio`, `size`), not introduce a third word. The topic's joint responsibility for ratio + size is documented in the `AspectRatioTaxonomy` docstring; `make_args_from_aspect_ratio` and `check_aspect_ratio` already take `size`, so no code rename is needed either. (Rejected alternative: `ImgGenArgTopic.ASPECT_RATIO` → `GEOMETRY` across code + deck TOMLs — internal naming purity wasn't worth config-vocabulary drift on a user-facing surface.)-- **New Google taxonomy values**, one per capability generation: `gemini_2_5` (1K only, standard ratios), `gemini_3_pro` (1K/2K/4K, standard ratios), `gemini_3_flash` (all tiers incl. 0.5k-when-verified, all ratios), `gemini_3_flash_lite` (1K only, all ratios). Each value encodes its (ratio set × tier set); `GoogleImgGenFactory` is re-keyed by taxonomy instead of matching on model *names*, killing the fragile `GoogleImageGenModel` enum (model handles are deck config, not code constants).-- **Deck**: `google.toml` image models gain `rules` blocks (at minimum `aspect_ratio = "gemini_3_flash"` etc.). This is what turns on static blueprint validation for Google — today `spec.rules is None` short-circuits it.-- **`ImgGenParamSupport`**: `check_aspect_ratio` covers (aspect_ratio, size) jointly — it already receives `size`, now including tier values; `check_blueprint_params` now receives the explicitly-set `size` (today it passes `size=None`), and `check_job_params` picks it from params as before. The existing unknown-taxonomy abstain policy stays (gateway rules may predate the enum).-- **Failure timing**: when the pipe's model choice resolves to a concrete spec with rules → error at blueprint-load time; when the choice is a preset/alias resolved later → same check errors at runtime before any API call. Same two-layer pattern the aspect-ratio work shipped.--## Portability worked examples (the acceptance bar)--- `nano-banana-2` + `aspect_ratio = "landscape_16_9"` + `size = "2k"` → switch model to `gpt-image-2`: runs, 2K-class dims (3072×1728). Switch to `flux-pro/v1.1`: **load-time error** ("flux cannot produce 2k; supported: 1k").-- `gpt-image-2` + `size = "2048x2048"` → switch to `nano-banana-2`: runs (1:1 @ 2K exact-grid hit). With `size = "2000x2000"`: **error** suggesting 2048x2048.-- `fast-img-gen` (SDXL) + `size = "1k"` → switch to any model: runs everywhere (worst case as a no-op); only `0.5k`-capable check would block it nowhere.-- `nano-banana-2` + `size = "4k"` → switch to `gpt-image-2`: **error** (above its pixel cap) — honest refusal, not a silent downgrade.--## Cost note--Tiers change the bill: Google output tokens scale with tier (4K ≫ 1K), OpenAI prices scale with size. Usage reporting needs no code change (token usage comes from responses), but the `PipeImgGen` docs must state that `2k`/`4k` cost proportionally more, and the never-send-unless-set rule above keeps unset bundles at provider-default cost.--## Implementation plan--### Phase 1 — types & surface--`SizeTier` + union parsing on `ImgGenJobParams.size`; blueprint/spec `size` field + `aspect_ratio` exclusivity validator; threading in `PipeImgGen`; optional default in `ImgGenJobParamsDefaults`. TDD: parsing unit tests (tier / exact / garbage), blueprint validator tests.--### Phase 2 — rules & validation--Google taxonomy values on `AspectRatioTaxonomy` (+ docstring stating the topic governs ratio and size jointly); `google.toml` rules blocks; `GoogleImgGenFactory` re-keyed by taxonomy (grids unchanged); `ImgGenParamSupport.check_aspect_ratio` extended for tiers incl. blueprint-side `size`; exact-grid match + nearest-cell error messages. TDD: per-taxonomy support matrices, exact-grid hit/miss, static-validation tests for Google models (the previously-skipped gap).--**CHECKPOINT** — validation story complete and green before any wire change; natural handoff point (Phase 3 opens the worker/API-call area).--### Phase 3 — wire--Google worker sends `image_size` (omit when unset), stops hardcoding `"1K"`; gateway `make_extras` threads the same; `ImgGenArgsFactory` handles the union for OpenAI paths (tier → scaled table → existing validator, verbose-not-warning for tier-derived reliability overshoot); metadata dims stamping for tiers.--### Phase 4 — docs, e2e & release--`PipeImgGen.md` param table + portability section with the worked examples; cogt-config docs; MTHDS schema regen; changelog. E2E smoke: one 2K gen on nano-banana-2 and one on gpt-image-2 (cost-gated test profile).--### Follow-up (separate)--- `0.5k` wire-token verification against Gemini 3.1 Flash, then enable in `gemini_3_flash` taxonomy + add the 512px grid to the factory.-- `AspectRatio` enum lacks 4:5/5:4, which the Gemini grids publish — decide separately whether to add them.diff --git a/wip/img-gen-size/plan.md b/wip/img-gen-size/plan.mddeleted file mode 100644index 085334a8b..000000000--- a/wip/img-gen-size/plan.md+++ /dev/null@@ -1,158 +0,0 @@-# Portable image size for image generation — implementation plan--Implements the design in [`wip/img-gen-size/design.md`](design.md). The design decisions are **settled** (with Louis, 2026-07-02) — do not re-litigate them; if implementation reveals a genuine conflict with the design, stop and surface it instead of silently deviating.--**Branch**: `feature/Img2Img-with-gpt-image`.--## Working conventions for this plan--- **TDD**: write the failing tests first, then implement (red → green), per phase.-- **One commit per phase.** Record each phase's commit SHA in the "State for cold start" section below, so each review fan-out gets a precise diff pointer.-- **Verification commands**: `make agent-check` after code changes; targeted tests via `.venv/bin/pytest -x -q <path>` during development; `make tb` whenever a config model or `pipelex.toml` structure changes; full `make agent-test` at the final checkpoint (and at any checkpoint if the phase touched shared surfaces).-- **Keyword-only args**: any new function in `pipelex/` source must follow the keyword-only convention (bare `*` after the subject) — `make agent-check` hard-blocks violations.-- **Checkpoint protocol** (mandatory at every CHECKPOINT below — the agent must stop and do all of this before starting the next phase):- 1. **Verify**: run the phase's verification commands; everything green before proceeding.- 2. **Commit** the phase's work.- 3. **Update this file**: tick the boxes, record the commit SHA, note decisions taken, open questions, and anything a cold-start session needs in "State for cold start".- 4. **Fan out a code review**: spawn a **Sonnet-5** sub-agent with **no inherited context** to run the `/code-review` skill. Hand it *only* a pointer to the changes (the phase's commit SHA / `git diff <sha>^..<sha>`, or `git diff <base>..HEAD` for multi-commit spans) — never this plan, the design doc, the rationale, or your own conclusions. Target: clean solid software, not over-engineering.- 5. **Triage the review findings**: apply clear correctness/simplification fixes (amend or follow-up commit); findings that are design tradeoffs (not silent bugs) go to a deferred-items doc under `wip/img-gen-size/` instead of being reflexively "fixed".- 6. It must be safe to end the session at any checkpoint — the "State for cold start" section is the handoff.--## Phase 0 — baseline--The working tree starts with the prior aspect-ratio work **staged but uncommitted** (img-gen aspect-ratio files + the design doc). That work is authorized prior work — commit it as-is first so the size work diffs cleanly.--- [x] Commit the currently staged changes as their own commit (aspect-ratio follow-up + design doc); record the SHA below as `BASE`-- [x] Confirm green baseline: `make agent-check` + `.venv/bin/pytest -x -q tests/unit/pipelex/cogt/img_gen/ tests/unit/pipelex/plugins/ tests/unit/pipelex/pipe_operators/pipe_img_gen/` + `make tb`-- [x] If the baseline is not green, fix or surface to the user before writing any size code--## Phase 1 — types & surface--New `size` field end to end on the params/blueprint/spec surface, no behavior on the wire yet.--- [x] **Tests first**: parsing unit tests in `tests/unit/pipelex/cogt/img_gen/` — tier tokens (`"0.5k"`/`"1k"`/`"2k"`/`"4k"`), exact `"WxH"` → `ImageSize`, garbage strings → clear `ValueError`; serialization round-trip for both union arms (StrEnum as str, `ImageSize` as dict)-- [x] **Tests first**: blueprint validator tests in `tests/unit/pipelex/pipe_operators/pipe_img_gen/test_pipe_img_gen_blueprint.py` — tier composes with `aspect_ratio`; exact size + `aspect_ratio` set together → validation error; each alone OK-- [x] `SizeTier` StrEnum in `pipelex/cogt/img_gen/img_gen_job_components.py` next to `AspectRatio`: `HALF_K = "0.5k"`, `ONE_K = "1k"`, `TWO_K = "2k"`, `FOUR_K = "4k"`-- [x] `ImgGenJobParams.size` becomes `SizeTier | ImageSize | None` via an annotated union with a `BeforeValidator` that parses strings (tier token → `SizeTier`, `"<int>x<int>"` → `ImageSize`, else `ValueError`); reuse the same annotated type for all three surfaces-- [x] `PipeImgGenBlueprint.size` (`pipelex/pipe_operators/img_gen/pipe_img_gen_blueprint.py`) + `PipeImgGenSpec.size` (`pipelex/builder/pipe/pipe_img_gen_spec.py`) use the same union; blueprint gains the `size`-vs-`aspect_ratio` exclusivity validator (spec's `to_blueprint()` threads it through)-- [x] `PipeImgGen` (`pipelex/pipe_operators/img_gen/pipe_img_gen.py`) threads `self.size or img_gen_param_defaults.size` into `ImgGenJobParams` like the other one-time settings-- [x] `ImgGenJobParamsDefaults` gains optional `size` — class default `None` (the Optional exception to the no-class-defaults config rule); **no key added** to `pipelex/pipelex.toml` or `.pipelex/pipelex.toml` (`None` = provider default)-- [x] Explicit non-goal, do not add: `size` on `ImgGenSetting` (deck presets) — geometry is pipe intent, not model preset-- [x] Verify: `make agent-check`, targeted tests, `make tb` (config model changed)--### CHECKPOINT 1 — surface in place--The new `size` surface is the foundation everything else builds on; catch shape/over-engineering problems now, before Phase 2 builds on the union type. Full checkpoint protocol: verify → commit → update this file → fan out `/code-review` (Sonnet-5, context-free, pointer = this phase's commit SHA) → triage findings.--- [x] Checkpoint 1 done (commit SHA recorded below, review findings triaged)--Checkpoint 1 review triage (context-free Sonnet `/code-review` on `19ce81eeb`):--- **Fixed** (follow-up commit `18b1364c5`): exact `ImageSize` was silently dropped on the Flux / Flux-1.1-Ultra / Qwen taxonomies — now a hard `ImgGenParameterError` ("does not support exact image sizes"), with a parametrized test. Also deduplicated the tier-token error text into `SizeTier.quoted_tokens()` and removed the spec `size` description's reference to `aspect_ratio` (the spec surface has no such field).-- **Known, deferred by plan**: `check_blueprint_params` not yet receiving `size` (no static validation of `size` at blueprint load) — that is exactly the Phase 2 item "`check_blueprint_params` now receives the explicitly-set `size`"; not fixed early.--## Phase 2 — rules & validation--Static validation story complete: Google models get deck rules, tiers and exact sizes are checked at blueprint-load/runtime-pre-call, exact-grid matching works. **No wire changes in this phase.**--- [x] **Tests first**: per-taxonomy support matrices in `tests/unit/pipelex/cogt/img_gen/test_img_gen_param_support.py` — which (aspect_ratio × tier) pairs pass/fail per taxonomy value, incl. `1k` as universal no-op, `2k`/`4k` rejections on incapable models, `0.5k` rejected everywhere for now-- [x] **Tests first**: exact-grid hit/miss tests — `"2048x2048"` on a gemini-3 grid → derives (1:1, 2K); `"2000x2000"` → error naming nearest cells-- [x] **Tests first**: static blueprint-validation tests for Google models (the previously-skipped gap) + the four portability worked examples from the design's "acceptance bar" section as test cases-- [x] New `AspectRatioTaxonomy` values in `pipelex/cogt/img_gen/img_gen_model_rules.py`: `gemini_2_5` (1K only, standard ratios), `gemini_3_pro` (1K/2K/4K, standard ratios), `gemini_3_flash` (1K/2K/4K now — 0.5k deferred, all ratios), `gemini_3_flash_lite` (1K only, all ratios); docstring states the topic governs ratio **and** size jointly (topic keeps its `aspect_ratio` name — no rename)-- [x] `pipelex/kit/configs/inference/backends/google.toml`: `rules` blocks on Google image models (`aspect_ratio = "gemini_3_flash"` etc.); source of truth is `.pipelex/inference/backends/google.toml`, synced via `make ukc` + `make ccs` (both run, in sync)-- [x] `GoogleImgGenFactory` (`pipelex/plugins/google/google_img_gen_factory.py`) re-keyed by taxonomy instead of matching on model names; **`GoogleImageGenModel` name enum killed** (model handles are deck config, not code constants); dimension grids stay in the factory as the single source of truth for dims-- [x] Exact-grid match: `derive_ratio_and_size_from_exact_size` searches the taxonomy's grids for an equal cell → derives (ratio, tier); on miss → `ImgGenParameterError` suggesting the nearest valid cells (closest ratio, then closest area); never silently snaps-- [x] `ImgGenParamSupport`: `check_aspect_ratio` covers (aspect_ratio, size) jointly incl. tier values; `check_blueprint_params` now receives the explicitly-set `size`; `check_job_params` picks it from params as before; unknown-taxonomy abstain policy kept-- [x] Tier satisfiability for non-Google taxonomies wired into the same check: gpt-image-2 accepts `1k`/`2k`, rejects `0.5k`/`4k`; legacy gpt-image accepts `1k` only; Flux/SDXL/Qwen accept `1k` as no-op, reject the rest; exact size on no-exact-size models → validation error-- [x] Verify: `make agent-check`, targeted unit tests, `make tb` (deck TOML changed), full `tests/unit/` suite green--### CHECKPOINT 2 — validation story complete (design's explicit checkpoint)--Natural handoff point: everything static is done and green; Phase 3 opens the worker/API-call area. Full checkpoint protocol: verify → commit → update this file → fan out `/code-review` (Sonnet-5, context-free, pointer = this phase's commit SHA) → triage findings. Also run the broader unit suite here (`.venv/bin/pytest -x -q tests/unit/`) since taxonomy/deck changes have wide reach.--- [x] Checkpoint 2 done (commit SHA recorded below, review findings triaged)--Checkpoint 2 review triage (context-free Sonnet `/code-review` on `ec0aa7ce7`): **no correctness bugs found**; the reviewer confirmed the hardcoded worker `size="1K"` and the gateway's commented-out `image_size` are the planned Phase 3 gap, not regressions. Two low-severity notes, both addressed in follow-up commit `a8e56bfe5`:--- `grids_for_taxonomy` returned the class-level grid dict directly (latent mutation footgun) → return type is now a read-only `Mapping`, with the shared-tables contract stated in the docstring.-- The SQUARE stand-in in `check_blueprint_params` relied on an unstated invariant (every taxonomy supports SQUARE; tier verdicts are ratio-uniform) → now guarded by `test_square_stand_in_invariant`, parametrized over every taxonomy, which fails first if a future taxonomy breaks either half.--## Phase 3 — wire--Providers actually receive the size intent.--- [x] **Tests first**: worker/gateway payload assertions (extend `tests/unit/pipelex/plugins/google/test_google_img_gen_factory.py` and gateway factory tests) — tier → `image_size` token (`"1k"` → `"1K"`), **param omitted entirely when `size` unset** (never silently upgrade; provider default = 1K); args-factory tests for OpenAI tier-derived sizes-- [x] Google worker (`pipelex/plugins/google/google_img_gen_worker.py`): send `image_config.image_size` from the tier, stop hardcoding `"1K"`; computed grid dims keep stamping `GeneratedImageRawDetails.size` metadata, now tier-aware-- [x] Gateway (`pipelex/plugins/gateway/gateway_factory.py` `make_extras`): thread the same `image_size` into `extra_body["image_config"]` for gemini-routed jobs (replaces the commented-out placeholder)-- [x] `ImgGenArgsFactory` (`pipelex/cogt/img_gen/img_gen_args_factory.py`) handles the union on OpenAI paths: tier → scale the existing `GPT_IMAGE_2_ASPECT_RATIO_TO_SIZE` table (`2k` = ×2 per edge, `0.5k` = ×½, `4k` = ×4) → run through existing `validate_gpt_image_2_size`; exact size → existing pass-through unchanged (implemented in Phase 2; payload tests added here)-- [x] Reliability-boundary warning: demote to `log.verbose` when the size is tier-derived; keep the loud warning for user-supplied exact sizes-- [x] Legacy gpt-image path: tier `1k` → the existing fixed size for the chosen ratio; nothing else changes (implemented in Phase 2; payload tests added here)-- [x] Verify: `make agent-check`, targeted tests (`tests/unit/pipelex/cogt/img_gen/`, `tests/unit/pipelex/plugins/`)--### CHECKPOINT 3 — wire complete--The provider-facing change surface is done; Phase 4 is docs/e2e/release, a different concern. Full checkpoint protocol: verify → commit → update this file → fan out `/code-review` (Sonnet-5, context-free, pointer = this phase's commit SHA) → triage findings.--- [x] Checkpoint 3 done (commit SHA recorded below, review findings triaged)--Checkpoint 3 review triage (context-free Sonnet `/code-review` on `1e4642b6f`):--- **Fixed** (follow-up commit `94ded54f0`): the gateway's gemini `image_config` tier branch mapped the tier token directly without taxonomy/grid validation — an unsupported tier (e.g. `2k` on the 1K-only `gemini_2_5` `nano-banana`) was silently forwarded to the provider while the native worker rejects the identical request client-side, and the reviewer traced the dispatch chain to confirm no upstream backstop catches it (blueprint-time validation skips deck aliases; `check_job_params` has no production caller). Any requested size (tier or exact) now resolves through `GoogleImgGenFactory.resolve_image_config` like every other call site — which also absorbed the reviewer's low-severity note that `_make_gemini_image_config` partially re-implemented the resolver. The gap-locking test `test_tier_without_rules_still_maps_directly` was replaced by `test_tier_without_rules_raises` + `test_tier_beyond_taxonomy_raises`; the no-size/no-rules case keeps the pre-existing ratio-only mapping (covered by its own test).-- Reviewer confirmed the rest clean: the hardcoded-`"1K"` worker bug is genuinely fixed, the `is_tier_derived` warning demotion is threaded correctly at all call sites, and the new tests assert real values.--## Phase 4 — docs, e2e & release readiness--- [x] `docs/building-methods/pipes/pipe-operators/PipeImgGen.md`: `size` in the param table; portability section with the design's worked examples; cost note (2k/4k cost proportionally more; unset = provider default cost) — Material for MkDocs conventions, blank line before lists, no hard wraps-- [x] `docs/configuration/config-technical/cogt-config.md`: document the optional `size` default in `ImgGenJobParamsDefaults`-- [x] MTHDS JSON Schema regen: `.venv/bin/pipelex-dev generate-mthds-schema` (blueprint field changed — schema should expose enum-or-pattern for `size`)-- [x] `CHANGELOG.md` entry under `[Unreleased]` (breaking changes marked "breaking"; no mention of `wip/` docs)-- [x] E2E smoke (cost-gated test profile, see `/test-model` skill conventions): one 2K generation on `nano-banana-2` and one on `gpt-image-2` in `tests/e2e/pipelex/pipes/pipe_operators/pipe_img_gen/`-- [x] Retire the superseded WIP note if still present anywhere; move any deferred-review-findings doc into `wip/img-gen-size/` — **no-op**: `wip/gemini-img-gen-size-tier-follow-up.md` never existed on this branch (folded into the design doc before it was written), and every checkpoint review finding was fixed in a follow-up commit, so there is no deferred-findings doc to move-- [x] Full gates: `make agent-check` + `make agent-test` + `make tb`--### CHECKPOINT 4 — final gate--Full checkpoint protocol one last time: full suite green → commit → update this file (final state, remaining follow-ups) → fan out `/code-review` (Sonnet-5, context-free, pointer = `git diff <BASE>..HEAD` for the whole feature) → triage findings. Then hand back to the user for merge/release decisions.--- [x] Checkpoint 4 done (feature-complete, full suite green, final review triaged)--Checkpoint 4 review triage (context-free Sonnet `/code-review` on `17f478e7b..HEAD`, five independent passes — CLAUDE.md compliance, bug scan, git-history regression, docs/schema/test drift, comment-invariant audit; compliance/history/comment audits came back clean). All fixes in follow-up commit `d6e5d81b5`:--- **Fixed — non-positive exact size crashed the Google grid derivation**: the `size = { width = 0, ... }` table wire form bypassed the `WxH` string regex and reached `derive_ratio_and_size_from_exact_size` as a raw `ZeroDivisionError`. `ImageSize` now enforces `Field(gt=0)` on both dims (the honest type invariant — schema regen picks it up as Draft-4 `minimum`+`exclusiveMinimum`); the now-dead OpenAI positivity guard was removed.-- **Fixed — exact-size deck default silently defeated an explicit pipe `aspect_ratio`**: the `self.size or img_gen_param_defaults.size` merge could pair a config-default exact size with a pipe's explicit ratio, and factories ignore the ratio when size is exact. New `resolve_default_size` (unit-tested pure function): an exact-size default only applies to pipes that don't set their own `aspect_ratio` (specificity semantics); a tier default composes with any ratio. Documented in cogt-config.md.-- **Fixed — gateway hard-failed size-unset jobs on unknown taxonomy strings**: `_make_gemini_image_config` raised for a remotely-fetched spec whose `rules.aspect_ratio` predates the taxonomy enum, contradicting the support layer's documented abstain policy. New `GoogleImgGenFactory.optional_img_gen_taxonomy` (None on missing/unknown) lets the no-size case keep the ratio-only mapping; sized requests still hard-fail with the honest message.-- **Fixed (polish)**: spec `size` description marks `'0.5k'` reserved; the docs/changelog claim "nothing is sent when size unset" is now scoped honestly (Gemini omits `image_size`; OpenAI always sends its fixed 1K-class preset).-- **Deferred** to `wip/img-gen-size/deferred-review-findings.md`: gateway no-rules error message is deck-config-speak a gateway user can't action; static-arm validation silently skips when routing can't resolve rules (by design); size⊕aspect_ratio exclusivity invisible to the JSON schema (model_validator); `quoted_tokens()` still lists `'0.5k'` in parse errors.--## Out of scope (explicit follow-ups, do not implement here)--- `0.5k` wire-token verification against Gemini 3.1 Flash (empirical test of `"512"` / `"0.5K"`), then enabling it in the `gemini_3_flash` taxonomy + adding the published 512px grid to the factory. Until then `0.5k` is a validation error on every model.-- Adding 4:5/5:4 to the `AspectRatio` enum (published in Gemini grids) — separate decision.-- `size` on `ImgGenSetting` deck presets — only if a real need materializes.--## State for cold start--> Update this section at every checkpoint. A fresh session should be able to resume from this section + the design doc alone.--- **Status**: **FEATURE COMPLETE.** Phases 0–4 done and committed; Checkpoint 4 done (feature-wide review triaged, fixes committed, deferred items in `wip/img-gen-size/`). All gates green after the review fixes: `make agent-check`, `make tb`, full `make agent-test`, `make docs-check`. Remaining decisions are the user's: merge/release (release ordering note: the published mthds.ai schema and the plxt/pipelex-tools bundled schema need the regenerated `size`-aware schema before downstream repos lint `.mthds` files using `size`; this repo lints against its own generated schema since `d6593bc8b`). The gateway remote config with the `rules` blocks is **live**: the Phase 4 live e2e smoke ran 2K generations through the `all_pipelex_gateway` routing profile and both passed with exact expected pixels (nano-banana-2 2752×1536, gpt-image-2 3072×1728). The design doc moved to `wip/img-gen-size/design.md`.-- **`BASE` commit (Phase 0)**: `17f478e7b` (plan + design doc; the aspect-ratio code itself was already committed as `d42084e91` before this plan started — nothing else was staged)-- **Phase 1 commit**: `19ce81eeb`; Checkpoint 1 review fixes: `18b1364c5`-- **Phase 2 commit**: `ec0aa7ce7`; Checkpoint 2 review follow-ups: `a8e56bfe5`-- **Phase 3 commit**: `1e4642b6f`; Checkpoint 3 review fix: `94ded54f0`-- **Phase 4 commit**: `d6593bc8b`; Checkpoint 4 review fixes: `d6e5d81b5`-- **Decisions taken during implementation**:- - The shared annotated union is `ImgGenSize: TypeAlias = Annotated[SizeTier | ImageSize, BeforeValidator(parse_img_gen_size)]` in `img_gen_job_components.py`; fields declare `ImgGenSize | None`.- - Exact-size parsing accepts only positive `WxH` (regex `([1-9]\d*)x([1-9]\d*)`, lowercase `x`, no spaces); everything else raises "expected a size tier (…) or an exact size like '2048x1152'".- - Interim guard: `ImgGenArgsFactory.make_args_from_aspect_ratio` raises `ImgGenParameterError` for any `SizeTier` ("not yet supported") so a tier can never silently reach the wire between Phase 1 and Phases 2–3; `check_aspect_ratio` was widened to the union. Phases 2–3 replace this guard with real per-taxonomy logic.- - `mthds_schema.json` regen deliberately deferred to Phase 4 (the schema unit tests don't gate on drift — verified).- - Phase 2 necessarily implements the gpt-image-2 tier→scaled-size computation (`OpenAIImgGenFactory._gpt_image_2_size_for_tier`): the capability check reuses `ImgGenArgsFactory` as the single source of truth, so "gpt-image-2 accepts 1k/2k" can only be checked by actually deriving and validating the scaled size. Phase 3's OpenAI item reduces to the reliability-warning demotion + payload assertions.- - No global early guard for `0.5k`: each taxonomy rejects it with its honest reason (Gemini: unverified wire token via `image_size_for_tier`; gpt-image-2: below the 0.65 MP floor via the scaled-size validator; Flux/SDXL/Qwen/legacy: only-'1k' message).- - `check_blueprint_params` checks a set `size` even when `aspect_ratio` is None, using `AspectRatio.SQUARE` as a neutral stand-in — the size verdict is ratio-independent (exact sizes ignore the ratio everywhere; tier satisfiability is uniform across each model's supported ratios). The deferred deck-default ratio itself still gets checked at runtime.- - `GoogleImgGenWorker` resolves its taxonomy from `inference_model.rules` (new `_img_gen_taxonomy()`, clear `ImgGenParameterError` if rules/topic missing or unknown); the wire still hardcodes `size="1K"` until Phase 3.- - Gemini taxonomy cases in `make_args_from_aspect_ratio` validate (ratio, size) against the grids and return `{"aspect_ratio": <literal>}` — the Google native worker and gateway build their own `image_config`, so nothing consumes these args yet (Phase 3 threads `image_size`).- - Pre-existing drift fixed by `make ukc`: kit `google.toml` had `nano-banana-2-lite` `inputs = ["text"]` while the `.pipelex` source (of-truth) said `["text", "images"]` since the img2img commit `38c716b56` — kit now matches the source (lite accepts image inputs).- - Gateway remote config (`pipelex-back-office/pipelex_back_office/remote_config/gateway_models.toml`, per Louis) also got the four `rules` blocks: older pipelex releases abstain on the unknown taxonomy, so the addition is version-safe. **Confirmed live** by the Phase 4 e2e smoke (2K through the gateway on both models). Since Checkpoint 3 the rules are load-bearing on the gateway wire path: `GatewayFactory._make_gemini_image_config` resolves any requested `size` through the taxonomy grids and raises if `rules.aspect_ratio` is missing (only the no-size case falls back to the ratio-only mapping).- - Phase 4: the MTHDS JSON Schema exposes `size` as tier-enum | `^WxH$`-pattern string | ImageSize table via pydantic's `json_schema_input_type` on the `ImgGenSize` `BeforeValidator` (schema tests in `test_mthds_schema.py`); the pattern is derived from `_EXACT_SIZE_PATTERN` so the two can't drift.- - Phase 4: plxt's bundled MTHDS schema (from the released pipeline: pipelex → mthds.ai → vscode-pipelex → pipelex-tools) predates `size`, which made `plxt lint` (and CI's `merge-check-plxt-lint`) reject any `.mthds` using it. Fixed structurally: `.pipelex/plxt.toml` now points the `.mthds`/`.plx` rule at the locally generated `derived/mthds_schema.json` (this repo is the language's source of truth), and the `plxt-lint`/`merge-check-plxt-lint` make targets regenerate it first. Caveat: taplo resolves the relative schema path against the CLI's CWD (repo root for make/CI/hooks — correct) and against the LSP workspace root in editors — an editor rooted at the multi-repo workspace parent won't resolve it (falls back to a noisy schema-load error). A config-file-relative resolution fix would belong in `vscode-pipelex` (taplo-common `Options::prepare`).- - Phase 4: the live 2K e2e asserts actual decoded pixel dimensions (PIL) rather than metadata — this is the assertion that would have caught the historical hardcoded-1K bug.-- **Open questions**: —diff --git a/wip/img2img-edits-worker-review-findings.md b/wip/img2img-edits-worker-review-findings.mddeleted file mode 100644index 0e75d6424..000000000--- a/wip/img2img-edits-worker-review-findings.md+++ /dev/null@@ -1,74 +0,0 @@-# img2img /edits worker — code review findings--xhigh-effort workflow review (`/code-review`) of the staged changes adding GPT Image `/images/edits` (img2img) support across the Azure REST and Gateway workers. 9 findings survived independent verification (4 CONFIRMED, 5 PLAUSIBLE).--Reviewed diff: `git diff --cached` at the time of review, covering:-- `.pipelex/inference/backends/azure_openai.toml`-- `pipelex/cogt/img_gen/img_gen_args_factory.py`-- `pipelex/kit/configs/inference/backends/azure_openai.toml`-- `pipelex/plugins/azure_rest/azure_img_gen_worker.py`-- `pipelex/plugins/gateway/gateway_img_gen_worker.py`-- `pipelex/plugins/openai/openai_img_gen_worker.py`-- `tests/integration/pipelex/cogt/test_img2img.py`-- `tests/unit/pipelex/cogt/img_gen/test_img_gen_args_input_images.py`-- `tests/unit/pipelex/plugins/gateway/test_gateway_img_gen_worker_edit_routing.py` (new)--## Confirmed showstoppers--### 1. ✅ RESOLVED — `pipelex/plugins/gateway/gateway_img_gen_worker.py:91` — endpoint-path derivation raises for the standard model_id convention-The `/images/edits` route derivation assumes `endpoint_path` literally contains the substring `"/images/generations"`, but the worker's own fallback (and its sibling test file `test_gateway_img_gen_worker_semantic.py`) build `endpoint_path` as `f"/{model_id}"` (e.g. `"/gpt-image-1"`), which never contains that substring.--**Failure scenario:** With `extra_headers={}` and `model_id="gpt-image-1"` (the naming convention used by every other model spec and by this same worker's existing test suite), `endpoint_path="/gpt-image-1"`, then `edits_endpoint_path = endpoint_path.replace("/images/generations", "/images/edits", 1)` returns the identical string, tripping the `edits_endpoint_path == endpoint_path` guard and raising `ImgGenParameterError("Could not derive an /images/edits route from endpoint path '/gpt-image-1'")` for every img2img request through the Gateway.--**Resolution:** Fixed config-side, not code-side. The production gateway config never hit this (its `model_id` smuggled the full `/images/generations?...` route, so the derivation happened to work), but the trap was real for the standard bare-`model_id` convention. The remote config (`pipelex-back-office/pipelex_back_office/remote_config/gateway_models.toml`, per-env deploy) now sets the explicit `endpoint_path` key on `[gpt-image-1]` — the escape hatch the worker has honored since v0.18.0, already used by the Azure Flux entries — and `model_id` is back to the bare deployment name. Version-skew-safe: the new `endpoint_path` value is the old `f"/{model_id}"` value minus the leading slash (portkey delegates URL merging to httpx, whose `base_url.raw_path + url.lstrip("/")` merge makes the two forms equivalent), so clients ≥ 0.18.0 build identical requests. The GPT Image mini entry also gained the img2img config (`inputs = ["text", "images"]` + `input_images = "gpt_image"`), matching its Azure REST counterpart. The worker's derivation + loud `ImgGenParameterError` stays as the guard against misconfigured specs; no `edits_endpoint_path` override until a provider needs a non-derivable route.--### 2. ✅ RESOLVED — `pipelex/plugins/gateway/gateway_img_gen_worker.py:95` — wrong multipart field name drops multi-image input-The sync-client multipart fallback for GPT Image edits builds `("image", image_file)` parts instead of `("image[]", image_file)`, so multi-image edits routed through the Gateway will not carry more than one image to the provider.--**Failure scenario:** A caller supplies 2+ input images to a GPT Image model routed through the Gateway. `multipart_fields = [("image", image_file) for image_file in image_files]` sends every image under the bare `"image"` key. The downstream OpenAI-compatible endpoint (which expects `"image[]"` for arrays) receives several conflicting single-image fields; only the last one is honored (or the call is rejected), so earlier input image(s) are silently dropped.--**Resolution:** Confirmed against the openai SDK's own multipart serialization (`extract_files` with `array_format="brackets"`, paths `[["image"], ["image", "<array>"], ["mask"]]`): a single file is sent as the bare `image` field, every element of a list as `image[]`. The worker now picks the field name by count — `image[]` when 2+ images, bare `image` for a single image (kept for maximal compatibility with legacy single-image edit endpoints). Covered by a new multi-image case in `test_gateway_img_gen_worker_edit_routing.py` asserting the `image[]` parts and the absence of bare `image` keys. Finding 5 (same bug in the Azure REST worker) is fixed separately.--### 3. ✅ RESOLVED — `pipelex/plugins/gateway/gateway_img_gen_worker.py:100` — unclosed per-request Portkey client leaks connections-The throwaway sync `Portkey` client built for every img2img/edit call is never closed, leaking its underlying `httpx.Client` connection pool.--**Failure scenario:** `portkey_ai`'s `Portkey` class opens an `httpx.Client` internally and exposes `close()`/`is_closed` for callers to release it; the new code constructs `Portkey(base_url=..., api_key=..., debug=...)` and lets it go out of scope after the single `post()` call, with no `with`/try-finally. Under sustained img2img traffic, each request opens a fresh `httpx.Client` whose sockets are only reclaimed whenever GC happens to collect the object — under load this can exhaust file descriptors or leave many idle sockets open. (Source inspection showed it was actually two leaked pools per request: the throwaway `Portkey`'s own `httpx.Client` plus the internal one opened by the vendored sync `OpenAI` client it constructs at init.)--**Resolution:** The throwaway sync client is gone entirely. Verified at source level that `AsyncPortkey.post(..., files=...)` is broken on every released portkey-ai (2.3.0 through 2.3.2: the async `AsyncAPIClient._build_request()` omits `files=options.files` while the sync one passes it) and on current GitHub main — so a version bump was no way out. The edit call now routes through the vendored `AsyncOpenAI` client the worker's `AsyncPortkey` already carries (`portkey_client.openai_client.post(...)`): fully async (no `asyncio.to_thread`), same base_url, Portkey auth headers baked in as `default_headers`, long-lived shared connection pool (no per-request client at all), custom edits endpoint path preserved, per-request `x-portkey-config` header passed via request options. Scalar args travel as `body` and are serialized to multipart form fields by the openai SDK. A `# TODO` in the worker tracks the upstream one-line fix (PR `files=options.files` into portkey's async `_build_request`) and restoring the plain `with_options(config=...).post(url=..., files=...)` call once it ships — commit `2d4ae4ecb71116e942c0adf2e6516de4b42f0614` holds the pre-change state and analysis.--### 4. `tests/integration/pipelex/cogt/test_img2img.py:35` — JPG single-image test silently commented out-The single-input-image JPG img2img test case was commented out (not fixed or deleted with explanation) rather than kept passing, silently dropping coverage for JPG input in the single-image edit path.--**Failure scenario:** A regression specific to JPG single-file input images in the new GPT_IMAGE edit flow (e.g. an extension/mime mismatch in the new `(filename, bytes, mime_type)` tuple construction in `img_gen_args_factory.py`, or a provider-side rejection of JPG on `/images/edits`) would no longer be caught by CI: the analogous multi-image JPG cases (`MULTIPLE_INPUT_IMAGES`) still run, but the single-JPG-file scenario silently stops being exercised.--## Plausible (latent / config-gated)--### 5. ✅ RESOLVED — `pipelex/plugins/azure_rest/azure_img_gen_worker.py:147` — same field-naming bug on the Azure REST worker-Multipart image-edit request always uses the field name `"image"` for every file, but the OpenAI/Azure `/images/edits` API requires the array field name `"image[]"` when more than one image is submitted (confirmed against OpenAI's official API reference and Azure OpenAI REST examples).--**Failure scenario:** A user runs img2img with two input images (exercised by the still-active `MULTIPLE_INPUT_IMAGES` cases in `tests/integration/pipelex/cogt/test_img2img.py`, e.g. "Two JPG files"). `files=[("image", image_file) for image_file in image_files]` posts two multipart parts both named `"image"` instead of `"image[]"`. Azure's REST endpoint either rejects the request or (more likely, since most multipart parsers keep only the last value for a repeated non-array key) silently drops all but the last image.--**Resolution:** Same fix as finding 2 — the field name is picked by count (`image[]` when 2+ images, bare `image` for a single image, matching the openai SDK's `extract_files` serialization). Covered by the new `tests/unit/pipelex/plugins/azure_rest/test_azure_img_gen_worker_edit_routing.py`, which asserts the edits/generations routing, the multipart field naming for both single and multiple images, and the scalar-args `data` payload.--### 6. `pipelex/plugins/azure_rest/azure_img_gen_worker.py:146` — 'moderation' arg not stripped before Azure edits call-New Azure `/images/edits` multipart path forwards every scalar arg (including `moderation`) without dropping it, unlike the parallel OpenAI-direct worker which explicitly strips `moderation` before calling `images.edit`.--**Failure scenario:** `openai_img_gen_worker.py` (unchanged in this diff) pops `moderation` before calling `images.edit` because "OpenAI images.edit does not accept moderation" (its own comment) — that guard exists precisely because `gpt-image-1`/`1-mini`/`1.5` on the OpenAI backend already ship with `safety_checker="openai_moderation"` + `input_images="gpt_image"`. This diff adds an equivalent img2img (edits) code path to `azure_img_gen_worker.py` and `gateway_img_gen_worker.py` for the same GPT_IMAGE taxonomy/args_dict shape, but neither strips `moderation`. Today the Azure entries this diff enables all have `safety_checker="unavailable"`, so `moderation` never lands in `args_dict` for them yet — but the moment any GPT_IMAGE Azure/gateway model rule reuses `safety_checker="openai_moderation"` (the same taxonomy already active on the OpenAI backend for these very model names), every img2img request sent through the Azure REST or Gateway worker will include an unexpected `moderation` field in the multipart body and the provider will reject it with a 400.--### 7. `pipelex/plugins/azure_rest/azure_img_gen_worker.py:146` (+ duplicated at `pipelex/plugins/gateway/gateway_img_gen_worker.py:96`) — blanket `str(value)` mis-serializes bools-Blanket `str(value)` over every remaining `args_dict` entry for the multipart `/images/edits` request silently mis-serializes non-string scalars (notably Python bools stringify to `"True"`/`"False"`, not the lowercase `"true"`/`"false"` an HTTP API expects). Same root cause duplicated in the Gateway worker.--**Gateway half resolved as a side effect of the finding-3 fix:** the Gateway edit path no longer stringifies scalars at all — they travel as `body` through the vendored openai SDK's multipart serializer, which lowercases bools and brackets arrays. The Azure REST worker's `str(value)` remains open.--**Failure scenario:** The moment a GPT Image model's `safety_checker` rule is anything other than today's hardcoded `"unavailable"` (e.g. `available`, which yields `args_dict["enable_safety_checker"] = True/False`) while `input_images = "gpt_image"` is also set, the img2img/edit request sends the multipart field as `("enable_safety_checker", (None, "True"))` — capitalized, non-JSON-boolean — so Azure's/the Gateway's `/images/edits` endpoint either rejects the request with a 400 or silently ignores/misreads the flag, breaking image editing for that model after only a one-line TOML rule flip.--### 8. ✅ RESOLVED — `pipelex/plugins/gateway/gateway_img_gen_worker.py:102` — hand-duplicated Portkey client construction-The image-edit code path builds a brand-new sync `Portkey` client from only 3 hand-picked fields (`base_url`, `api_key`, `debug`) instead of delegating through the already-configured `self.portkey_client`, so any other client-level configuration silently doesn't apply to edit requests.--**Failure scenario:** `self.portkey_client` is currently built by `GatewayFactory.make_portkey_client()`, which only sets `base_url`/`api_key`/`debug`, so today the two clients happen to match. But the moment any of Portkey's other constructor parameters is added to the async client's construction (e.g. the tracing/metadata support flagged by an adjacent `# TODO: add portkey tracing headers when enabled` comment, or a future virtual-key/provider override), plain image-generation calls (which reuse `self.portkey_client`) will carry it while every img2img/edit call (routed through this freshly-built sync client) silently drops it — producing wrong-provider routing, missing trace correlation, or an auth failure that only reproduces when an input image is supplied.--**Resolution:** Resolved by the finding-3 fix. The hand-built sync client is gone; the edit path now goes through `self.portkey_client.openai_client`, which portkey constructs from the async client's own `allHeaders` at init — so client-level configuration added to the async client's construction flows to edit requests automatically.--## Priority fix order--Finding 1 (Gateway endpoint-path bug) is RESOLVED via the remote gateway config (explicit `endpoint_path` key). Findings 2 and 5 (`image[]` field naming on the Gateway and Azure REST workers) are RESOLVED in code. Findings 3 and 8 (throwaway sync Portkey client: leak + hand-duplicated construction) are RESOLVED in code — the edit path now routes through the vendored `AsyncOpenAI` client the worker's `AsyncPortkey` carries, with a `# TODO` tracking the upstream portkey fix that would let us restore the plain async portkey call. Finding 7's Gateway half is resolved as a side effect (SDK-serialized multipart scalars); its Azure half remains. Finding 4 (commented-out test) should be un-commented or explained now that #2/#5 are fixed, since it likely exists to sidestep a currently-broken path. Finding 6 and the Azure half of 7 are latent/config-gated — worth fixing but not urgent until the relevant TOML config combination is introduced.diff --git a/wip/required-main-stuff-brief.html b/wip/required-main-stuff-brief.htmldeleted file mode 100644index 53a759c33..000000000--- a/wip/required-main-stuff-brief.html+++ /dev/null@@ -1,468 +0,0 @@-<title>Required main stuff — design brief</title>-<style>- :root {- --ground: #FBFCFC;- --panel: #F1F5F6;- --panel-deep: #E7EEF0;- --ink: #1A2B32;- --muted: #5B6E75;- --line: #D8E0E3;- --accent: #0E7490;- --danger: #B3422F;- --danger-soft: #F6E9E5;- --good: #2F7D4F;- --good-soft: #E6F1EA;- --code-bg: #EEF3F4;- }- @media (prefers-color-scheme: dark) {- :root {- --ground: #10181C;- --panel: #182228;- --panel-deep: #1E2B33;- --ink: #E8EDEF;- --muted: #8FA3AB;- --line: #2A3840;- --accent: #3FB2D2;- --danger: #E07856;- --danger-soft: #33211C;- --good: #5CB884;- --good-soft: #1B2E24;- --code-bg: #16212A;- }- }- :root[data-theme="dark"] {- --ground: #10181C;- --panel: #182228;- --panel-deep: #1E2B33;- --ink: #E8EDEF;- --muted: #8FA3AB;- --line: #2A3840;- --accent: #3FB2D2;- --danger: #E07856;- --danger-soft: #33211C;- --good: #5CB884;- --good-soft: #1B2E24;- --code-bg: #16212A;- }- :root[data-theme="light"] {- --ground: #FBFCFC;- --panel: #F1F5F6;- --panel-deep: #E7EEF0;- --ink: #1A2B32;- --muted: #5B6E75;- --line: #D8E0E3;- --accent: #0E7490;- --danger: #B3422F;- --danger-soft: #F6E9E5;- --good: #2F7D4F;- --good-soft: #E6F1EA;- --code-bg: #EEF3F4;- }-- * { box-sizing: border-box; }- body {- margin: 0;- background: var(--ground);- color: var(--ink);- font: 400 16px/1.62 -apple-system, "SF Pro Text", "Segoe UI Variable", "Segoe UI", system-ui, sans-serif;- -webkit-font-smoothing: antialiased;- }- .wrap { max-width: 46rem; margin: 0 auto; padding: 0 1.25rem; }- .wrap-wide { max-width: 56rem; margin: 0 auto; padding: 0 1.25rem; }-- header.masthead { padding: 3rem 0 1.75rem; }- .kicker {- font-size: 0.6875rem;- font-weight: 650;- letter-spacing: 0.1em;- text-transform: uppercase;- color: var(--accent);- margin: 0 0 0.75rem;- }- h1 {- font-size: clamp(1.7rem, 4.5vw, 2.15rem);- line-height: 1.18;- font-weight: 750;- letter-spacing: -0.015em;- margin: 0 0 0.6rem;- text-wrap: balance;- }- .standfirst { color: var(--muted); font-size: 1.05rem; margin: 0; max-width: 42rem; }- .meta { display: flex; flex-wrap: wrap; gap: 0.4rem 1.4rem; margin-top: 1.1rem; font-size: 0.8125rem; color: var(--muted); }- .meta code { font-size: 0.78rem; }-- .tldr {- background: var(--panel);- border-top: 1px solid var(--line);- border-bottom: 1px solid var(--line);- padding: 1.6rem 0 1.7rem;- margin: 1.25rem 0 0;- }- .tldr .label {- font-size: 0.6875rem;- font-weight: 700;- letter-spacing: 0.12em;- text-transform: uppercase;- color: var(--accent);- margin: 0 0 0.9rem;- }- .tldr ul { margin: 0; padding: 0 0 0 1.1rem; display: grid; gap: 0.65rem; }- .tldr li { padding-left: 0.2rem; }- .tldr li::marker { color: var(--accent); }- .tldr b { font-weight: 650; }-- main { padding: 0.5rem 0 3rem; }- section { margin-top: 2.9rem; }- h2 {- font-size: 1.28rem;- font-weight: 700;- letter-spacing: -0.01em;- line-height: 1.25;- margin: 0.3rem 0 0.9rem;- text-wrap: balance;- }- .sec-kicker {- font-size: 0.6875rem;- font-weight: 650;- letter-spacing: 0.1em;- text-transform: uppercase;- color: var(--muted);- margin: 0;- }- p { margin: 0 0 1rem; }- .note { color: var(--muted); font-size: 0.875rem; }-- code, pre {- font-family: ui-monospace, "SF Mono", "Cascadia Code", "JetBrains Mono", Consolas, monospace;- font-size: 0.845rem;- }- code { background: var(--code-bg); border-radius: 4px; padding: 0.1em 0.35em; }- pre {- background: var(--code-bg);- border: 1px solid var(--line);- border-radius: 6px;- padding: 0.9rem 1rem;- overflow-x: auto;- line-height: 1.55;- margin: 0;- }- pre code { background: none; padding: 0; }- .del { color: var(--danger); }- .add { color: var(--good); }- .dim { color: var(--muted); }-- figure { margin: 1.4rem 0; }- .fig-frame {- border: 1px solid var(--line);- border-radius: 6px;- background: var(--panel);- padding: 0.75rem;- overflow-x: auto;- }- .fig-frame svg { display: block; min-width: 720px; width: 100%; height: auto; }- figcaption { font-size: 0.8125rem; color: var(--muted); margin-top: 0.55rem; line-height: 1.5; }-- table.modes { width: 100%; border-collapse: collapse; font-size: 0.9rem; margin: 1.2rem 0; }- .modes-scroll { overflow-x: auto; }- table.modes th, table.modes td { text-align: left; padding: 0.55rem 0.9rem 0.55rem 0; border-bottom: 1px solid var(--line); vertical-align: top; }- table.modes th { font-size: 0.6875rem; font-weight: 650; letter-spacing: 0.08em; text-transform: uppercase; color: var(--muted); }- table.modes td:first-child { font-weight: 650; white-space: nowrap; }- .pill {- display: inline-block; font-size: 0.72rem; font-weight: 650; letter-spacing: 0.02em;- padding: 0.1rem 0.5rem; border-radius: 999px; white-space: nowrap;- }- .pill-danger { color: var(--danger); background: var(--danger-soft); }- .pill-good { color: var(--good); background: var(--good-soft); }-- .duo { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 1.2rem 0; }- .duo h3 { font-size: 0.6875rem; font-weight: 650; letter-spacing: 0.08em; text-transform: uppercase; color: var(--muted); margin: 0 0 0.5rem; }- @media (max-width: 720px) { .duo { grid-template-columns: 1fr; } }-- ol.phases { margin: 1rem 0 0; padding-left: 1.2rem; display: grid; gap: 0.6rem; }- ol.phases li::marker { color: var(--accent); font-weight: 650; }- ol.phases b { font-weight: 650; }-- footer { border-top: 1px solid var(--line); padding: 1.4rem 0 3rem; font-size: 0.875rem; color: var(--muted); }- a { color: var(--accent); text-underline-offset: 2px; }- a:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; border-radius: 2px; }-- /* SVG diagram tokens */- .sv-box { fill: var(--ground); stroke: var(--line); stroke-width: 1.2; rx: 6; }- .sv-slot { fill: var(--ground); stroke: var(--line); stroke-width: 1.2; rx: 5; }- .sv-slot-good { fill: var(--good-soft); stroke: var(--good); stroke-width: 1.3; rx: 5; }- .sv-lane { fill: var(--panel-deep); stroke: none; rx: 8; }- .sv-t { fill: var(--ink); font-size: 13px; font-weight: 650; }- .sv-ts { fill: var(--muted); font-size: 11.5px; font-weight: 400; }- .sv-mono { fill: var(--ink); font-size: 11.5px; font-family: ui-monospace, "SF Mono", Consolas, monospace; }- .sv-mono-dim { fill: var(--muted); font-size: 11px; font-family: ui-monospace, "SF Mono", Consolas, monospace; }- .sv-good-t { fill: var(--good); font-size: 11.5px; font-weight: 650; }- .sv-danger-t { fill: var(--danger); font-size: 11.5px; font-weight: 650; }- .sv-flow { stroke: var(--muted); stroke-width: 1.4; fill: none; }- .sv-flow-danger { stroke: var(--danger); stroke-width: 1.6; fill: none; stroke-dasharray: 5 4; }- .sv-flow-good { stroke: var(--good); stroke-width: 1.8; fill: none; }-</style>--<header class="masthead">- <div class="wrap">- <p class="kicker">Pipelex runtime · design note</p>- <h1>A pipeline must always deliver its main output</h1>- <p class="standfirst">Why reading a pipeline's result is uglier than it should be, the rule we adopted to fix it, and the API shape divergence we're tracking separately.</p>- <div class="meta">- <span>Branch <code>feature/Required-main-stuff</code></span>- <span>Full design: <code>wip/required-main-stuff.md</code></span>- </div>- </div>-</header>--<div class="tldr">- <div class="wrap">- <p class="label">TL;DR</p>- <ul>- <li><b>Problem.</b> A pipeline doesn't always deliver a <code>main_stuff</code>. One construct — <code>PipeParallel</code> with only <code>add_each_output</code> — never stamps it, so callers get a <em>stale</em> value, <em>nothing at all</em>, or (hosted) an <em>empty result envelope</em>. Every consumer pays with defensive code.</li>- <li><b>Decision.</b> Every pipe run now delivers a main stuff. <code>PipeParallel</code> <b>always combines</b> its branch outputs into its declared <code>output</code> concept. The redundant <code>combined_output</code> field is <b>deleted</b>, and a new <code>native.Composite</code> concept covers the "just give me the named results" case.</li>- <li><b>Payoff.</b> <code>main_stuff</code> stops being optional across the runtime, the wire, and the SDKs — a stale-output bug disappears and a pile of defensive branches gets deleted.</li>- <li><b>Side track.</b> The two execution surfaces return the same data in <b>different shapes</b>: blocking <code>POST /v1/execute</code> nests everything under <code>pipe_output</code> (working memory in its transport encoding, main stuff reached via the <code>main_stuff_name</code> pointer), while <code>POST /v1/start</code> → delivery relays flat artifacts via <code>GET /v1/runs/{id}/results</code> — <code>main_stuff</code> (content pre-extracted), <code>graph_spec</code>, and <code>working_memory</code> too, as a clean render. Same information, two encodings — every client normalizes. Unifying them is a companion track, designed separately.</li>- </ul>- </div>-</div>--<main>- <div class="wrap">-- <section>- <p class="sec-kicker">The symptom</p>- <h2>Reading a result takes a page of guesswork</h2>- <p>Our own starter project needs a normalizer just to get a pipeline's output. It checks whether <code>main_stuff</code> exists, falls back to walking the serialized working memory, and picks "the first entry whose content is a dict" — a heuristic, in code we hand to every new user:</p>- <pre><code><span class="dim"># pipelex-starter-python/my_project/run_output.py (abridged)</span>-def find_main_content(results: RunResults) -> dict[str, Any] <span class="del">| None</span>:- if isinstance(results.main_stuff, dict): <span class="dim"># /start → delivery shape…</span>- return results.main_stuff- working_memory = results.pipe_output.get("working_memory") <span class="dim"># …or /execute blocking shape</span>- for entry in working_memory["root"].values(): <span class="dim"># heuristic: first dict wins</span>- ...</code></pre>- <p>Two distinct flaws feed this: <b><code>main_stuff</code> is optional</b>, and <b>the two execution paths return different shapes</b>. This note covers the fix for the first and the plan for the second.</p>- </section>-- <section>- <p class="sec-kicker">Root cause</p>- <h2>One pipe doesn't stamp the main stuff</h2>- <p>Every operator (<code>PipeLLM</code>, <code>PipeExtract</code>, <code>PipeCompose</code>, …) stamps its result as the working memory's <code>main_stuff</code>. So do <code>PipeBatch</code> and <code>PipeCondition</code>. The single exception: <b><code>PipeParallel</code> without <code>combined_output</code></b>. It drops each branch result into memory by name and leaves the <code>main_stuff</code> pointer untouched — and the language explicitly allows that as a pipeline's last step.</p>- </section>- </div>-- <div class="wrap-wide">- <figure>- <div class="fig-frame">- <svg viewBox="0 0 860 315" role="img" aria-label="Before: a sequence ending in PipeParallel leaves the main_stuff pointer on the previous step's output">- <defs>- <marker id="arrA" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0,0 L8,4 L0,8 z" fill="var(--muted)"/></marker>- <marker id="arrAd" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0,0 L8,4 L0,8 z" fill="var(--danger)"/></marker>- </defs>- <text x="20" y="26" class="sv-t">Before — PipeSequence ending in a PipeParallel (add_each_output only)</text>-- <rect x="20" y="44" width="215" height="62" class="sv-box" rx="6"/>- <text x="36" y="70" class="sv-t">1 · PipeLLM extract_info</text>- <text x="36" y="90" class="sv-good-t">stamps main_stuff ✓</text>-- <line x1="235" y1="75" x2="285" y2="75" class="sv-flow" marker-end="url(#arrA)"/>-- <rect x="288" y="44" width="252" height="62" class="sv-box" rx="6"/>- <text x="304" y="70" class="sv-t">2 · PipeParallel (last step)</text>- <text x="304" y="90" class="sv-danger-t">never stamps ✗</text>-- <path d="M 380 106 C 380 140, 380 150, 462 172" class="sv-flow" marker-end="url(#arrA)"/>- <path d="M 470 106 C 470 140, 545 145, 630 172" class="sv-flow" marker-end="url(#arrA)"/>- <text x="500" y="140" class="sv-ts">branch results added by name</text>-- <rect x="20" y="176" width="820" height="86" class="sv-lane" rx="8"/>- <text x="36" y="200" class="sv-ts">working memory after the run</text>-- <rect x="36" y="210" width="130" height="38" class="sv-slot" rx="5"/>- <text x="50" y="234" class="sv-mono">input_text</text>- <rect x="182" y="210" width="130" height="38" class="sv-slot" rx="5"/>- <text x="196" y="234" class="sv-mono">info</text>- <rect x="328" y="210" width="200" height="38" class="sv-slot" rx="5"/>- <text x="342" y="234" class="sv-mono">short_summary</text>- <rect x="544" y="210" width="200" height="38" class="sv-slot" rx="5"/>- <text x="558" y="234" class="sv-mono">detailed_summary</text>-- <path d="M 120 292 C 170 292, 210 280, 240 254" class="sv-flow-danger" marker-end="url(#arrAd)"/>- <text x="20" y="298" class="sv-mono">main_stuff</text>- <text x="260" y="298" class="sv-danger-t">stale — still points at step 1's output</text>- </svg>- </div>- <figcaption>The caller asks for <code>main_stuff</code> and silently receives step 1's output. When the parallel is the whole pipeline (API input path), the pointer doesn't exist at all.</figcaption>- </figure>- </div>-- <div class="wrap">- <div class="modes-scroll">- <table class="modes">- <thead><tr><th>Failure mode</th><th>When it happens</th><th>What the caller sees</th></tr></thead>- <tbody>- <tr>- <td><span class="pill pill-danger">Stale</span></td>- <td>The parallel ends a <code>PipeSequence</code> — the shared memory keeps the previous step's stamp</td>- <td>The <em>wrong</em> output, silently</td>- </tr>- <tr>- <td><span class="pill pill-danger">Missing</span></td>- <td>The parallel <em>is</em> the main pipe, inputs came through the API path (no input alias)</td>- <td><code>main_stuff_name = null</code>; typed accessors raise</td>- </tr>- <tr>- <td><span class="pill pill-danger">Empty envelope</span></td>- <td>The <code>/start</code> → delivery path — delivery always writes <code>working_memory.json</code>, but the <code>main_stuff.*</code> artifacts are only written when a stamp exists</td>- <td>A "successful" run with <code>main_stuff: null</code> — clients dig through the raw memory dump</td>- </tr>- </tbody>- </table>- </div>-- <section>- <p class="sec-kicker">Decision</p>- <h2>PipeParallel always combines — and <code>combined_output</code> dies</h2>- <p>The rule: <b>a pipe run always delivers a main stuff</b>. We enforce it at the one leaf that breaks it — <code>PipeParallel</code> now always combines its branch results into its declared <code>output</code> concept and stamps that as main stuff. Sequences, conditions, and nesting then deliver the invariant for free, and the stale pointer is always overwritten.</p>- <p>This also kills a redundant field. Today a combining parallel declares the same concept twice (<code>output</code> <em>and</em> <code>combined_output</code>), while a non-combining one declares an <code>output</code> that is a lie — it never produces it. After the change, <code>output</code> is the single, truthful declaration:</p>- </section>-- <div class="duo">- <div>- <h3>Before — output is a lie</h3>- <pre><code>[pipe.parallel_summarize]-type = "PipeParallel"-inputs = { input_text = "Text" }-<span class="del">output = "Text" # never produced</span>-add_each_output = true-branches = [- { pipe = "sum_short", result = "short_summary" },- { pipe = "sum_long", result = "detailed_summary" },-]</code></pre>- </div>- <div>- <h3>After — combines into what it declares</h3>- <pre><code>[pipe.parallel_summarize]-type = "PipeParallel"-inputs = { input_text = "Text" }-<span class="add">output = "Composite" # named combination</span>-add_each_output = true-branches = [- { pipe = "sum_short", result = "short_summary" },- { pipe = "sum_long", result = "detailed_summary" },-]</code></pre>- </div>- </div>-- <p>Declare a bespoke structured concept and the combination is fully typed (today's <code>combined_output</code> behavior, minus the duplicate line). Don't want to declare one? The new <b><code>native.Composite</code></b> concept holds the branch results under their names — the "dict of results" experience — while staying a first-class stuff that renders, serializes, and travels like any other. And a new <b>static validation</b> checks branch names against the declared structure at authoring time, so today's runtime combine error becomes a <code>/validate</code> error.</p>- </div>-- <div class="wrap-wide">- <figure>- <div class="fig-frame">- <svg viewBox="0 0 860 300" role="img" aria-label="After: PipeParallel combines branch outputs into its declared concept and stamps it as main_stuff">- <defs>- <marker id="arrB" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0,0 L8,4 L0,8 z" fill="var(--muted)"/></marker>- <marker id="arrBg" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0,0 L8,4 L0,8 z" fill="var(--good)"/></marker>- </defs>- <text x="20" y="26" class="sv-t">After — the same pipeline under the new rule</text>-- <rect x="288" y="44" width="252" height="62" class="sv-box" rx="6"/>- <text x="304" y="70" class="sv-t">2 · PipeParallel (last step)</text>- <text x="304" y="90" class="sv-good-t">always combines ✓</text>-- <path d="M 350 106 C 330 135, 300 145, 250 168" class="sv-flow" marker-end="url(#arrB)"/>- <path d="M 420 106 C 420 135, 420 145, 420 168" class="sv-flow" marker-end="url(#arrB)"/>- <path d="M 490 106 C 510 135, 570 140, 640 166" class="sv-flow-good" marker-end="url(#arrBg)"/>- <text x="530" y="136" class="sv-good-t">combine into declared output</text>-- <rect x="20" y="172" width="820" height="86" class="sv-lane" rx="8"/>- <text x="36" y="196" class="sv-ts">working memory after the run</text>-- <rect x="36" y="206" width="170" height="38" class="sv-slot" rx="5"/>- <text x="50" y="230" class="sv-mono">short_summary</text>- <rect x="222" y="206" width="190" height="38" class="sv-slot" rx="5"/>- <text x="236" y="230" class="sv-mono">detailed_summary</text>- <rect x="428" y="206" width="396" height="38" class="sv-slot-good" rx="5"/>- <text x="442" y="230" class="sv-mono">Composite { short_summary, detailed_summary }</text>-- <path d="M 120 288 C 200 290, 340 280, 425 240" class="sv-flow-good" marker-end="url(#arrBg)"/>- <text x="20" y="294" class="sv-mono">main_stuff</text>- <text x="440" y="292" class="sv-good-t">always stamped, always the last step's result</text>- </svg>- </div>- <figcaption>Symmetry worth remembering: <code>PipeBatch</code> aggregates homogeneous results into a <em>list</em>; <code>PipeParallel</code> now aggregates heterogeneous results into a <em>named composite</em>.</figcaption>- </figure>- </div>-- <div class="wrap">- <section>- <p class="sec-kicker">Side track</p>- <h2><code>/execute</code> and <code>/start</code> → delivery speak different shapes</h2>- <p>The second flaw behind the ugly starter code: the two execution surfaces carry the <em>same information</em> in structurally different results. <b><code>POST /v1/execute</code></b> blocks until the run completes and responds with the runner's native envelope: everything nested under <code>pipe_output</code>, the working memory in its cross-process <em>transport</em> encoding (type-metadata keys, lists flattened — built for rehydration, not reading), and the main stuff not extracted — you follow the <code>main_stuff_name</code> pointer into <code>root</code> and unwrap <code>.content</code> yourself.</p>- <p><b><code>POST /v1/start</code></b> returns immediately; the run then goes through <b>delivery</b>, which writes a folder of result artifacts to storage — <code>working_memory.json</code>, <code>main_stuff.{json,md,html}</code>, <code>main_stuff_viewer.html</code>, <code>graphspec.json</code>, mermaid/reactflow views — and <code>GET /v1/runs/{id}/results</code> relays three of them as flat fields: <code>main_stuff</code> (the output content, pre-extracted), <code>graph_spec</code>, and <code>working_memory</code> (a clean render). So it's not that one path lacks the memory — <em>both carry it</em>. What differs is the envelope, the main-stuff addressing, and the memory encoding — and the SDK only names a subset (<code>working_memory</code> rides along as an unnamed extra field). Every client normalizes.</p>- </section>- </div>-- <div class="wrap-wide">- <figure>- <div class="fig-frame">- <svg viewBox="0 0 860 250" role="img" aria-label="Blocking /execute and /start with delivery return different result shapes, normalized in client code">- <defs>- <marker id="arrC" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0,0 L8,4 L0,8 z" fill="var(--muted)"/></marker>- </defs>-- <rect x="20" y="30" width="110" height="150" class="sv-box" rx="6"/>- <text x="45" y="100" class="sv-t">Client</text>- <text x="41" y="118" class="sv-ts">app / SDK</text>-- <line x1="130" y1="70" x2="185" y2="70" class="sv-flow" marker-end="url(#arrC)"/>- <rect x="188" y="44" width="250" height="52" class="sv-box" rx="6"/>- <text x="204" y="66" class="sv-t">Blocking execution</text>- <text x="204" y="84" class="sv-mono-dim">POST /v1/execute</text>-- <line x1="438" y1="70" x2="490" y2="70" class="sv-flow" marker-end="url(#arrC)"/>- <rect x="493" y="44" width="240" height="52" class="sv-slot" rx="5"/>- <text x="507" y="66" class="sv-mono">{ pipe_output: {working_memory},</text>- <text x="507" y="84" class="sv-mono"> main_stuff_name }</text>- <text x="507" y="112" class="sv-ts">transport encoding · main stuff via pointer</text>-- <line x1="130" y1="145" x2="185" y2="145" class="sv-flow" marker-end="url(#arrC)"/>- <rect x="188" y="119" width="250" height="52" class="sv-box" rx="6"/>- <text x="204" y="141" class="sv-t">Start → delivery</text>- <text x="204" y="159" class="sv-mono-dim">POST /v1/start → GET …/results</text>-- <line x1="438" y1="145" x2="490" y2="145" class="sv-flow" marker-end="url(#arrC)"/>- <rect x="493" y="119" width="240" height="52" class="sv-slot" rx="5"/>- <text x="507" y="141" class="sv-mono">{ main_stuff, graph_spec,</text>- <text x="507" y="159" class="sv-mono"> working_memory }</text>- <text x="507" y="187" class="sv-ts">flat artifacts · main stuff pre-extracted</text>-- <path d="M 733 70 C 780 75, 790 95, 795 105" class="sv-flow" marker-end="url(#arrC)"/>- <path d="M 733 145 C 780 140, 790 122, 795 112" class="sv-flow" marker-end="url(#arrC)"/>- <text x="620" y="215" class="sv-danger-t">same data, two shapes →</text>- <text x="620" y="233" class="sv-danger-t">every client normalizes</text>- </svg>- </div>- <figcaption>Companion track — not part of this refactor: converge on one result shape so SDK consumers read <code>main_stuff</code> the same way on both paths. Designed separately, after the invariant lands (it belongs to <code>pipelex-api</code> / <code>pipelex-platform</code> / SDK repos).</figcaption>- </figure>- </div>-- <div class="wrap">- <section>- <p class="sec-kicker">Rollout</p>- <h2>Three phases, breaking by design</h2>- <p>No backward compatibility, per house policy — <code>combined_output</code> disappears and existing <code>.mthds</code> files migrate (mechanically: delete the redundant line, or make the declared <code>output</code> truthful).</p>- <ol class="phases">- <li><b>Runtime + language surface</b> (pipelex repo): always-combine, delete the field, add <code>native.Composite</code> and the static branch-name check, migrate fixtures, regenerate the MTHDS schema.</li>- <li><b>Enforce the invariant</b>: tighten the defensive <code>optional_main_stuff</code> branches (delivery, graph tracer, CLI, telemetry) and make <code>main_stuff_name</code> non-optional on the wire models.</li>- <li><b>Cross-repo sweep</b> (gated on a pipelex release): MTHDS spec + JSON schema, <code>plxt</code> pinned schema, conformance, plugin skills, app/UI TypeScript types, cocode pipelines, docs sites, SDKs + starter.</li>- </ol>- </section>- </div>-</main>--<footer>- <div class="wrap">- Full design with file-level inventory, rejected alternatives, and open questions: <code>wip/required-main-stuff.md</code> on <code>feature/Required-main-stuff</code>.- </div>-</footer>diff --git a/wip/required-main-stuff.md b/wip/required-main-stuff.mddeleted file mode 100644index 80ca92f06..000000000--- a/wip/required-main-stuff.md+++ /dev/null@@ -1,206 +0,0 @@-# Required main stuff — PipeParallel always combines--**Branch:** `feature/Required-main-stuff` · **Status:** Phases 1–2 COMPLETE (Checkpoint 2 cleared — invariant enforced at every in-repo post-run boundary: wire `main_stuff_name` required, delivery always writes `main_stuff.*`, defensive branches gone, `final_stuff_code` honored on the parallel's combined stuff; decisions & audit in `TODOS.md` → Checkpoint log). Next: Phase 3 (cross-repo sweep, GATED on merge to `main` + version cut).--## 1. Problem--A pipeline is the language's function abstraction, and every pipe already declares `output` in its blueprint — yet the runtime sometimes finishes a run without delivering a main stuff. The result is that `main_stuff` is optional everywhere, and every consumer pays for it with defensive code. The symptom that triggered this design: `pipelex-starter-python/my_project/run_output.py` needs a page of isinstance-walking heuristics just to read a pipeline's result.--### Verified mechanics (current state)--- Every operator (`PipeLLM`, `PipeCompose`, `PipeExtract`, `PipeImgGen`, `PipeSearch`, `PipeStructure`, `PipeFunc`, `PipeSignature`) unconditionally stamps its result via `WorkingMemory.set_new_main_stuff`.-- Among controllers: `PipeSequence` threads one evolving memory so the last step's stamp wins; `PipeBatch` stamps its aggregated `ListContent`; `PipeCondition` delegates to the chosen branch, which stamps.-- The **only** non-stamping path in the runtime is `PipeParallel` without `combined_output` (`pipe_parallel.py` — the `set_new_main_stuff` call sits inside `if self.combined_output`). The blueprint validator explicitly allows `add_each_output = true` alone, so this is a legal terminal step.-- `pipe_abstract.py` acknowledges the hole in a comment: *"main_stuff may not exist for pipes like PipeParallel with add_each_output=true"*.--### The three concrete failure modes--1. **Stale main stuff (silent wrong data).** Inside a `PipeSequence`, the parallel adds branch outputs by name into the shared memory but never touches the `main_stuff` alias. A pipeline ending in an `add_each`-only parallel silently reports the *previous* step's output (or even an input — `make_from_single_stuff` / `make_from_multiple_stuffs` alias an input as main stuff at construction) as its main result.-2. **Truly missing main stuff.** When such a parallel is the top-level `main_pipe` and memory came from `make_from_pipeline_inputs` (the API path — which sets no main-stuff alias), the run completes with no main stuff at all: `main_stuff_name` serializes as `None`, `PipeOutput.main_stuff` raises.-3. **Empty delivery envelope.** On the `/start` → delivery path, delivery always writes `working_memory.json`, but the `main_stuff.json/md/html/viewer` artifacts are only generated when a main stuff exists. An `add_each`-terminal method started via `POST /v1/start` completes "successfully" and `GET /v1/runs/{pipeline_run_id}/results` relays `main_stuff: null` — consumers are left digging through the raw `working_memory` render (which the SDKs don't even name — see below).--### Blast radius of the optionality--Defensive `get_optional_main_stuff` branches exist in the CLI pretty-printer, the CLI file/CSV writers, the agent CLI, OTel telemetry, the graph tracer, and the delivery executor. On the wire, `main_stuff_name: str | None` (bridge payloads, `PipelexRunResultExecute`), `RunResults.main_stuff: Any = None` in both SDKs, and downstream user projects re-implement the same heuristics.--### Related but out of scope--The starter's `run_output.py` ugliness has a second, independent cause: the **result-shape divergence** between the two execution surfaces. Both carry the same information, including the working memory — delivery writes a full artifact folder (`working_memory.json`, `main_stuff.{json,md,html}`, `main_stuff_viewer.html`, `graphspec.json`, mermaid/reactflow views) and `GET /v1/runs/{pipeline_run_id}/results` relays `main_stuff` + `graph_spec` + `working_memory` as flat fields — but the shapes differ on three axes:--- **Envelope**: `/execute` nests everything under `pipe_output`; `/results` returns flat top-level fields.-- **Main-stuff addressing**: `/results` pre-extracts the main stuff's *content* into `main_stuff`; on `/execute` the caller follows the `main_stuff_name` pointer into `working_memory.root` and unwraps `.content`.-- **Memory encoding**: `/execute` returns the `dump_for_transport()` shape (`__pipelex_class__` metadata, `ListContent` flattened — built for rehydration, not reading); delivery writes a clean `smart_dump()` render — except on the cross-process Temporal path, where it writes the raw transport dump it received (`working_memory_raw`), so even the delivered `working_memory.json` is not one stable shape today.--On top of that, the SDKs only *name* `main_stuff`, `graph_spec`, and `pipe_output` on their `RunResults`; the relayed `working_memory` rides along as an unnamed `extra="allow"` field. This refactor removes the optionality and the heuristic root-walk; unifying the shapes is a companion API/SDK change tracked separately (see §9, cross-repo follow-ups).--## 2. The decision--> **A pipe run always delivers a main stuff. Consequently, a pipeline always delivers a main stuff.**--This is enforced at the leaf cause, not the pipeline boundary: `PipeParallel` — the single non-stamping pipe — now **always combines its branch outputs into its declared `output` concept and stamps the combination as main stuff**. Composition (sequences, conditions, nesting) then gives the pipeline-level invariant for free, and the stale-stamp hazard disappears because the parallel always overwrites the alias.--`combined_output` **is deleted as a field**. It was redundant with `output`: in our own fixtures, pipes declare `output = "PgcCombinedResult"` and `combined_output = "PgcCombinedResult"` — the same value twice. Meanwhile `add_each`-only parallels declare an `output` that is a lie (e.g. `output = "Text"` for a pipe that produces named summaries). Killing the field makes `output` truthful and unique.--No backward compatibility, per house policy. Breaking changes are noted in the changelog; existing `.mthds` files migrate.--## 3. New PipeParallel semantics--### Field changes--| Field | Before | After |-|---|---|---|-| `output` | Required but meaningless when only `add_each_output` is set | Required and truthful: the concept the branch outputs are combined into |-| `combined_output` | Optional concept ref; triggers combination when set | **Deleted** |-| `add_each_output` | One of the two must be set (model validator) | Unchanged meaning ("also expose branch outputs by name in memory"), default `false`, no more one-of-two validator |-| `branches` | Each branch must declare a unique `result` name | Unchanged |--### Runtime behavior (live and dry run identically)--1. Run all branches on deep copies of the memory, as today.-2. If `add_each_output`, add each branch's main stuff into the parent memory under its `result` name, as today.-3. **Always** build the combination: `{result_name: branch_main_stuff.content}` → validate into the declared `output` concept's structure class via `StuffFactory.combine_stuffs` → `set_new_main_stuff(stuff=combined, name=output_name)`. This is today's `combined_output` code path made unconditional, with the concept taken from `output`.-4. Graph tracer registration (branch outputs, parallel-combine edges) as today, except the combine edges are now always registered.--### Typing rules for the declared `output`--- **Structured concept** (bespoke, with a structure class): the combination validates into it — today's typed `combined_output` path, unchanged. The structure's fields must correspond to the branch `result` names.-- **`native.Composite`** (new native concept, see §4): the untyped escape hatch — a named composition holding the branch contents as-is, the `dict[str, Any]`-shaped developer experience for authors who don't want to declare a bespoke concept.-- **Anything else is a static validation error**: native non-composite concepts (`Text`, `Image`, …), `Dynamic`, `Anything`, and any multiplicity suffix (`Foo[]`, `Foo[N]`) are rejected — a parallel combination is a named composite, never a scalar or a bare list (a list aggregation is `PipeBatch`'s shape).--### New static validation (bundle/library validation time)--- The declared `output` of a `PipeParallel` must be `Composite` or a structured concept whose declared fields are compatible with the branch `result` names (required fields ⊆ result names; result names ⊆ declared fields). This turns today's runtime `StuffFactoryError` from `combine_stuffs` into an author-time error, which the builder and `/validate` can surface.-- The one-of-two (`add_each_output` / `combined_output`) validators in both the blueprint and the spec are removed.--### Example migration--Before (`add_each`-only, lying output):--```toml-[pipe.parallel_summarize]-type = "PipeParallel"-description = "Generate short and detailed summaries in parallel"-inputs = { input_text = "Text" }-output = "Text" # never produced — a lie-add_each_output = true-branches = [- { pipe = "summarize_short", result = "short_summary" },- { pipe = "summarize_detailed", result = "detailed_summary" },-]-```--After (untyped composite — minimal migration):--```toml-[pipe.parallel_summarize]-type = "PipeParallel"-description = "Generate short and detailed summaries in parallel"-inputs = { input_text = "Text" }-output = "Composite" # truthful: named composition of the branch results-add_each_output = true # still exposes short_summary / detailed_summary by name-branches = [- { pipe = "summarize_short", result = "short_summary" },- { pipe = "summarize_detailed", result = "detailed_summary" },-]-```--Before (combined, redundant declaration):--```toml-output = "PgcCombinedResult"-add_each_output = true-combined_output = "PgcCombinedResult"-```--After — delete the `combined_output` line; nothing else changes.--## 4. The `Composite` native concept--The untyped fallback needs a real vehicle. Verified: `DynamicContent` cannot serve as-is — `StuffContent`/`CustomBaseModel` use default pydantic config, so `model_validate({"short_summary": ..., ...})` silently *drops* unknown fields. Silent data loss is disqualifying; overloading `Dynamic` (whose meaning is "concept resolved at runtime", used by `PipeFunc`) would also blur two distinct semantics.--Implemented design: `COMPOSITE = "Composite"` on `NativeConceptCode` with a `CompositeContent(StuffContent)` structure class that holds the named branch contents as top-level fields (pydantic `extra="allow"` so the branch names surface at the top level of the serialized content, exactly like the typed path — not nested under a wrapper key). It supports the full content surface: `smart_dump`, kajson round-trip (`__json_encode__` hands kajson the live components), transport round-trip (`dump_for_transport` stamps each component with `__pipelex_class__`/`__pipelex_module__` markers and hydration rebuilds typed contents), `rendered_markdown`/`rendered_html` (iterate named sub-contents), so `main_stuff.json/md/html/viewer` delivery works unchanged.--Brand note: this is MTHDS-language semantics, not a Pipelex runtime detail. The concept is `native.Composite` (no `pipelex_` anything), and the change belongs in the MTHDS spec (`mthds/` repo) in the same motion as killing `combined_output`.--Alternatives considered for the vehicle:--- `DynamicContent` with `extra="allow"` — rejected: `Dynamic` already means something else, and changing its config affects unrelated `PipeFunc` paths.-- `CompositeContent` with an explicit `composed: dict[str, StuffContent]` field — rejected: nests the payload under a wrapper key, so the wire shape of the untyped path would differ from the typed path.-- Runtime-synthesized anonymous pydantic model per parallel — rejected: the class wouldn't exist in the class registry on the other side of a process boundary, breaking rehydration.--## 5. What the invariant unlocks (follow-through tightening)--Once every pipe stamps, "a completed run has a main stuff" is guaranteed, and the following tighten from defensive to direct (in-repo):--- Graph tracer output-spec branch in `pipe_abstract.py` (and its apologetic comment).-- Delivery executor: always writes the `main_stuff.*` artifact files for completed runs.-- CLI run cores (bare + agent): drop the "no main output produced" branches for live runs.-- OTel telemetry attribute extraction.-- `resolve_main_stuff_root_key` / bridge payloads / `PipelexRunResultExecute.main_stuff_name`: producer-side always set; the field types can go non-optional (Temporal payload history is not a concern — never shipped to prod).--`WorkingMemory.get_optional_main_stuff` itself stays — a *pre-run* or empty memory legitimately has no main stuff; it's the post-run boundary accessors that tighten.--Cross-repo (flagged, not done here): SDKs can drop `main_stuff`-absent handling for completed runs, and the starter's `find_main_content` shrinks; full cleanup of the two-branch shape additionally needs the `/execute`-vs-`/start`→delivery result-shape unification (companion track).--## 6. Rejected alternatives (for the record)--- **Auto-stamp at the pipeline boundary** ("if no main stuff at the end, synthesize one"): papers over the stale-stamp bug inside sequences and needs an ill-defined generic aggregation rule. Fixing the one non-stamping pipe is strictly better.-- **Validation-error-only** ("a terminal pipe must deliver; force authors to add `combined_output` or a final step"): position-dependent validity (valid as sub-pipe, invalid as `main_pipe`) is confusing, and it makes casual fan-out methods annoying to author.-- **Raw `dict[str, Any]` main stuff with no concept**: escapes the concept system entirely — no rendering, no typed access, no static checks. The `Composite` concept gives the same developer experience while staying a first-class stuff.-- **Keep `combined_output` optional, defaulting to `output`**: keeps a redundant field alive with subtle precedence rules; deleting it is simpler and the migration is mechanical.-- **SDK-only ergonomics fix**: treats the symptom; every consumer stays defensive; the empty-delivery hole remains.--## 7. Open questions (resolve during implementation)--- **`final_stuff_code`**: the parallel currently clears it on entry (with a copy-pasted `PipeBatch` log line). Now that the parallel stamps a final stuff, it should presumably honor `final_stuff_code` on the combined stuff like operators do. Confirm what `final_stuff_code` drives (graph/trace identity) and wire it through.-- **Graph `execution_data` key `combined_output_concept`**: under the new semantics it is always set and equals the declared output concept. Keep the key name for `mthds-ui` compatibility in phase 1; consider renaming in the next coordinated `mthds-ui` bump.-- **`add_each_output` naming**: semantics unchanged, but with combination always on, a name like `expose_branches` might read better. Recommendation: keep the name — pure churn across skills/docs otherwise. Revisit only if the MTHDS spec editors want it.-- **`PipeOutputAbstract` (mthds-python protocol layer)**: check whether the protocol shape encodes main-stuff optionality that should tighten in the same motion (cross-repo).--## 8. Implementation plan--### Phase 1 — runtime + language surface (this repo)--- `pipe_parallel.py`: unconditional combine in `_live_run_controller_pipe` and `_dry_run_controller_pipe` (shared helper — the existing TODO already asks for it); concept from `self.output`; always register parallel-combine graph edges.-- `pipe_parallel_blueprint.py` / `pipe_parallel_factory.py`: delete `combined_output` + one-of-two validator; factory stops resolving the combined concept separately.-- `builder/pipe/pipe_parallel_spec.py`: delete `combined_output` + validators; `to_blueprint()` simplifies; update pretty-render; `builder/operations/pipe_ops.py` + `cli/agent_cli/commands/pipe_cmd.py` display code.-- `core/bundles/pipelex_bundle_blueprint.py`: drop the `combined_output` concept-ref collection; add the new static structure-compatibility check (§3).-- New native concept `Composite` + `CompositeContent` (§4): `concept_native.py`, new `composite_content.py`, class registry, concept factory.-- Tests (TDD: write the red tests first): regression test for the stale-stamp bug (sequence ending in `add_each`-only parallel must deliver the composite, not the previous step's stuff); terminal-parallel-delivers-main-stuff; static validation accept/reject cases; `CompositeContent` serialization + rendering round-trip; dry-run parity. Migrate existing fixtures (`pipe_parallel_1.mthds`, `parallel_graph_*.mthds`, unit/builder test data, mermaidflow test, bundle-validator + agent-validate tests).-- Regenerate the MTHDS JSON Schema (`pipelex-dev generate-mthds-schema`).-- Docs: rewrite `docs/building-methods/pipes/pipe-controllers/PipeParallel.md` to the new semantics (current reality only, no history); changelog entry under `[Unreleased]`, marked breaking.-- Gates: `make agent-check`, targeted pipes tests, then full `make agent-test`.--**CHECKPOINT 1** — parallel always combines; `combined_output` gone; all gates green. Update this doc: status, decisions taken, deviations. Natural handoff point before touching the delivery/telemetry surfaces.--### Phase 2 — enforce the invariant across in-repo surfaces--- Tighten the boundary consumers listed in §5 (graph tracer, delivery executor, CLI run cores, OTel, serialization payload types → `main_stuff_name: str`).-- Keep `WorkingMemory.get_optional_main_stuff` for pre-run memories; audit each remaining call site and either justify or tighten.-- Resolve the `final_stuff_code` open question.-- Gates: full `make agent-test`.--**CHECKPOINT 2** — invariant enforced in-repo; doc updated with the final call-site audit results. Cross-repo work starts fresh from here.--### Phase 3 — cross-repo sweep (gated, coordinate releases)--Do not start before phases 1–2 are merged and a pipelex version is cut.--| Repo | Change |-|---|---|-| `mthds/` | Spec: `mthds-format.md`, `pipes-controllers.md`, `validation-rules.md`, `namespace-resolution.md`, `cross-package-references.md`, `docs/mthds_schema.json` — remove `combined_output`, define always-combine + `native.Composite` |-| `vscode-pipelex/` | Pinned `mthds_schema.json` in taplo-common (plxt lint/format must accept the new shape and reject `combined_output`) |-| `conformance/` | `tests/pipelex/test_validate_subcommands.py` fixture updates; keep spec ↔ test links (`make check-spec-links`) |-| `mthds-plugins/` | Skills references: `mthds-reference.md`, `build-phases.md`, `recursive-cheat-sheet.md`, `mthds-run/SKILL.md` across plugin variants |-| `pipelex-app/` | `src/types/core/pipes/pipe_controllers/pipe-parallel.ts` |-| `mthds-ui/` | `src/graph/types.ts` (`combined_output_concept` exec-data key — see open question); graph-spec data fixtures |-| `cocode/` | `ai_instruction_update.mthds`, `swe_docs.mthds` migration |-| `pipelex-website/` | `docs/mthds-doc.md` |-| demo/workshop repos | `illustration_generator/bundle.mthds` copies |-| SDKs + starter | Tighten `main_stuff` handling for completed runs; pair with the result-shape unification companion track |--**CHECKPOINT 3** — cross-repo consumers aligned; close this doc or fold residual items into follow-up trackers.--## 9. Companion track (separate design)--Result-shape unification between `/execute` and `/start` → delivery. Both surfaces already carry the same information, working memory included; what differs is the envelope, the main-stuff addressing, and the memory encoding (see §1). Converge on one shape: e.g. `/execute` also pre-extracts `main_stuff` at top level, one canonical working-memory render on both surfaces (the transport dump stays an internal format), and the SDKs naming `working_memory` on the results surface instead of leaving it an unnamed extra. This is what deletes the *second* half of the starter's `find_main_content`. Belongs to `pipelex-api` / `pipelex-platform` / SDK repos; design separately once the invariant lands.diff --git a/wip/required-main-stuff/deferred-phase-1-review.md b/wip/required-main-stuff/deferred-phase-1-review.mddeleted file mode 100644index 55f7919e7..000000000--- a/wip/required-main-stuff/deferred-phase-1-review.md+++ /dev/null@@ -1,11 +0,0 @@-# Deferred items — Phase 1 code review (Checkpoint 1)--Context-free review of commit `757146324` (Phase 1: always-combine PipeParallel). No correctness bugs found. Triage outcome of the two cleanup findings:--## Fixed at checkpoint--- **Duplicated native-concept rejection match** between `PipeParallel.validate_output_static` and `PipeParallelBlueprint.validate_output` — extracted into `NativeConceptCode.is_composite` (exhaustive match lives once, on the enum, per house style). Both validators now branch on the property.--## Deferred (design tradeoff, not a bug)--- **Double-parse of the pipe output string in blueprint validation.** `PipeBlueprint.generic_validate_output` parses `self.output` with `parse_concept_with_multiplicity`, then `PipeParallelBlueprint.validate_output` parses the same string again. Avoiding it means changing the `validate_output()` hook signature across every blueprint subclass to thread the `MultiplicityParseResult` through. This runs once per pipe definition at load time — not a hot path — so the signature churn across all pipe blueprints isn't worth it today. Revisit only if a blueprint-validation hook redesign happens for other reasons.diff --git a/wip/required-main-stuff/deferred-review-round-3.md b/wip/required-main-stuff/deferred-review-round-3.mddeleted file mode 100644index d3015626c..000000000--- a/wip/required-main-stuff/deferred-review-round-3.md+++ /dev/null@@ -1,40 +0,0 @@-# Deferred items — review round 3 (`/review` on PR #1014, pre-merge)--Independent context-free review (own critical pass + testing, maintainability, and adversarial sub-agents) on the full `dev..HEAD` diff. It converged on **one genuine latent defect** (F1), one verified robustness gap (F2), and cleanup items. The one test gap deemed worth closing in-PR (`DirectOrchestrator.start()` raise-path) was applied — see `tests/unit/pipelex/runtime_bridge/test_direct_orchestrator.py`. Everything below was **deliberately deferred** to keep the merge-ready PR frozen, since none is reachable in production today.--## F1 — Nested `CompositeContent` transport round-trip is asymmetric (latent silent corruption)--**Where:** encode `pipelex/core/memory/working_memory.py` (`_encode_composite_for_transport` / `_encode_content_with_class_markers`) vs decode `pipelex/runtime_bridge/primitives/hydration.py` (`_hydrate_composite_component` → `_hydrate_list_item`).--**What:** Encode recurses into a component that is itself a `CompositeContent` (stamping `__pipelex_class__="CompositeContent"`). Decode does **not** recurse: `_hydrate_list_item` resolves the `CompositeContent` class and calls `model_validate(clean_item)` without re-hydrating the inner components. Because `CompositeContent` is `extra="allow"`, the still-encoded inner components are stored verbatim — as raw `dict`s that **retain the pipelex-private `__pipelex_class__` / `__pipelex_module__` marker keys**.--**Failure scenario:** a nested `PipeParallel` (a branch whose own output is `Composite`), or a `CompositeContent` carried as a `ListContent` item, crosses the Temporal `dump_for_transport` → `hydrate_working_memory` boundary. The inner composite's components decay to `dict` (typed `.content_as(...)` / field access breaks) **and** `smart_dump()` / `rendered_markdown()` of that inner composite leaks the private marker keys into user/LLM-visible output. Silent — no exception at hydrate time. Confirmed by reproduction in the adversarial pass; the flat (depth-1) and `ListContent`-of-scalars cases are correct and tested — only the *nested composite* case is affected.--**Why deferred:** the Temporal/cross-process transport path has never shipped to production (see workspace memory `project_temporal_not_shipped`), and nested-parallel composition is an edge case. The corrupting code does ship in this PR, so this must be fixed **before the hosted-Temporal rollout**, not left indefinitely.--**Fix (small, localized):** in `_hydrate_list_item`, when the resolved class is a `CompositeContent` subclass, rebuild its components via `_hydrate_composite_component` before `model_validate` (mutual recursion; terminates on finite nesting). Add a nested round-trip test to `tests/unit/pipelex/core/stuffs/test_composite_content.py`: a composite whose component is a composite, asserting the inner component entries hydrate to typed `StuffContent` and carry no `__pipelex_*` keys.--## F2 — `ConceptValueError` (a bare `ValueError`) escapes the validate sweep--**Where:** `pipelex/pipe_controllers/parallel/pipe_parallel.py:153,223` call `concept.get_structure_class()`, which raises `ConceptValueError` (`pipelex/core/concepts/exceptions.py` — subclasses `ValueError`, **not** `PipelexError`; its sibling `ConceptError` does subclass `PipelexError`) when a structure class is not registered.--**What:** the validate sweep's step-1 wiring pass (`pipelex/pipeline/bundle_validator.py` `validate_with_libraries()`) catches only `PipeNotFoundError`; the per-pipe step-3 catch is `(PipelexError, ValidationError, FactoryException)`. A `ConceptValueError` matches neither, so it escapes `validate_pipes` and aborts validation of the **whole bundle** with an unhandled error instead of being reported as that one pipe's FAILURE. `PipeSequence`'s equivalent path avoids `get_structure_class()` (it uses `is_compatible`), so this exposure is net-new to `PipeParallel`.--**Why deferred:** low reachability — a loaded pipe's own output concept normally has its structure class registered. The failure mode (unhandled sweep abort vs clean per-pipe error) is poor DX but not a data-integrity issue.--**Fix (cheap):** catch `ConceptValueError` in `validate_output_with_library` and re-raise as `PipeValidationError` (or widen the sweep's step-1 catch).--## M1 — `rendered_html` table wrapper still duplicated--**Where:** `pipelex/core/stuffs/composite_content.py` (`rendered_html`) + `pipelex/core/stuffs/structured_content.py` (`rendered_html`).--**What:** the PR extracted per-value rendering into `render_value_html` (good), but the *table-of-named-values* wrapper and the verbatim empty-table literal (`<table><tr><td><em>empty</em></td></tr></table>`) are still copy-pasted in both classes — the same drift the extraction targeted, one level up.--**Fix:** add a shared `render_named_values_table(pairs)` helper in `html_rendering.py`; `StructuredContent` passes its non-`None` fields, `CompositeContent` passes all components. Pure refactor, no behavior change.--## Minor / noted (no action)--- **`combined_output_concept` graph execution-data key name** (`pipe_parallel.py`): now always `self.output.concept.concept_ref`. The misleading-name observation is correct, but the key is **deliberately kept** for `mthds-ui` compatibility — rename is already tracked as a Phase 3 cross-repo item (design open-question #2). Renaming before `mthds-ui`'s coordinated update would break it. Do not rename in-repo.-- **Unguarded `get_required_pipe` in `_validate_branch_output_types`** (`pipe_parallel.py`): asymmetric with `PipeSequence`'s cross-package-guarded form, but benign in the sweep (which anticipates unguarded sub-pipe resolution and catches `PipeNotFoundError`; `needed_inputs` would raise first anyway). Consistency nit for a future refactor.-- **`PipelexRunResultExecute.from_pipe_output`** (`pipeline/pipeline_response.py`): accepts non-`COMPLETED` states but unconditionally calls the now-raising `resolve_main_stuff_root_key`. Latent only — the sole caller passes `state=COMPLETED` on the success path. A future caller routing a failed `PipeOutput` here would have the real failure masked by a secondary `PipeJobError`. Tighten by asserting completion or dropping the `state` param if a caller ever needs the failed path.-- **Duplicate branch-result-name detection** stays a runtime guard (`validate_output_with_library` builds `result_names` as a set, silently collapsing duplicates; the runtime duplicate guard with its stale `# TODO` remains). Design tradeoff, not a bug — the runtime guard still catches it.