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.
fix(search): keep the caller's class on structured search and serialize by alias (#1077)
Louis Choquel941987951d6b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8f7c5293f..5c69a2dd4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,11 +4,18 @@### Fixed+- **An Output Field Named `json`, `copy`, `schema` or `construct` No Longer Breaks The Worker-Boundary Round Trip:** when a structured result crosses a worker boundary, the output class is rebuilt from its JSON schema — and the rebuilder cannot give a field a name that shadows a Pydantic attribute, so it renames it and records the real name as an alias. The result was then serialized under the renamed key, and validating it back against your class failed with `Field required` on a field you had supplied. The shared conversion — and the dry-run boundary mock, which dumps for the same wire — now serializes by alias, so the keys match the schema your class published. Field names that needed no rename are unaffected. Our distributed-execution plugin still carries its own copy of the conversion until it adopts the shared helper, so distributed runs pick this fix up with that plugin's next release.+- **Structured Web Search No Longer Loses Your Class's Invariants Either:** `PipeSearch` with a structured (non-text) output was the one path the structured-output fix below left behind — in-process it still handed the search provider a class rebuilt from JSON schema, dropping the custom validators, `json_schema_extra` hints and output-structure description the rebuild cannot express. The caller's live class now travels down to the search leaf and is used as-is, exactly as on the LLM object paths. The rebuild remains for the case it exists for: a distributed worker holding only the serialized assignment, where the class genuinely cannot travel and the raw result dict stays on the wire.+- **Structured Web Search Returned An Envelope No Output Class Could Accept:** both search backends handed the leaf `{data, sources}` instead of the structured payload itself — the direct Linkup backend by asking for sources alongside the payload, the gateway backend because its relay does the same — which then failed validation against the output structure class, making structured search unusable on either backend. The direct backend now asks for the payload alone (a structured result has nowhere to put sources), and the gateway backend unwraps the envelope its relay returns, so both hand the leaf the bare payload. A response shape neither backend can hand on now surfaces as a classified search error — a new `LinkupSearchResponseError` on the direct backend, the existing `GatewaySearchResponseError` on the gateway — instead of an opaque validation failure against your output structure class. On the direct backend the output structure's schema still reaches the provider in full; it just crosses as JSON rather than as a class, so the provider SDK cannot pre-validate the response and make your validators run twice. Neither backend *trusts* its own request to have decided the response shape: both recognise the envelope structurally, because not asking for sources is a request rather than a guarantee, and an output structure whose fields all carry defaults would validate an unexpected envelope *silently* into an all-defaults object — wrong answers with no error. Recognising rather than demanding it also means the two sides never have to deploy together.+- **A Web Search You Were Billed For Now Always Reaches Your Cost Report:** a structured search whose response shape the backend rejected raised after the provider had already answered and after its usage was recorded, and the search worker only reported a job on the success path — so the call was billed and then vanished from the run's report. Completion and reporting now happen on every way out. A failure that never reached the provider recorded no tokens, so it reports as the zero-cost attempt it was.+- **A Malformed Gateway Response Body Is Now A Classified Search Error:** a relay answering with something that is not JSON raised a bare `JSONDecodeError` — neither a Pipelex error nor annotated with the model — slipping past the classification the rest of that path provides. Both gateway search paths now surface it as `GatewaySearchResponseError`. Relatedly, a search that simply found nothing to fill your output structure no longer reports itself as a malformed response advising you to change model: it raises the new `LinkupSearchEmptyResultError` / `GatewaySearchEmptyResultError` and points at the query instead.- **Structured Output No Longer Loses Your Class's Invariants:** In-process structured generation handed the provider a class rebuilt from the output structure's JSON schema instead of the class the caller passed — so a model with a custom `@field_validator` or `json_schema_extra` format hints reached the provider as a weaker contract than the one you wrote, because `datamodel-code-generator` cannot express those on round-trip. The output structure's own description (its class docstring) was dropped too, so the provider never saw it. The caller's live class now travels down to the leaf and is used as-is, on both the live and the dry path. The rebuild remains exactly as before for the case it exists for: a distributed worker holding only the serialized `ObjectAssignment`, where the class genuinely cannot travel. `ObjectAssignment`'s wire shape is unchanged.### Changed-- **Dry-Run Object Mocks Are Built From Your Real Class:** a consequence of the structured-output fix above, called out separately because it can require action. The dry-run leaf mock now builds from your output class rather than a schema rebuild of it, so constraints the rebuild used to erase are enforced at mock-build time. A field whose type polyfactory cannot satisfy — an opaque custom type with a `__get_pydantic_core_schema__`, or a bare generic `ListContent` — can now fail `pipelex validate` with `DryRunMockBuildError` where it previously passed. Declare `examples` or `mock_format` on the offending field to fix it. The failure is loud and names the class and the remedy; it is not a silent behavior change. (Breaking)+- **One Home For Converting A Leaf Result Into Your Class:** the conversion that turns a content-generation leaf's result into the caller's own class — with its `isinstance` short-circuit and its typed dry-run fidelity error — now lives in `pipelex.cogt.content_generation.object_revalidation` instead of being copied per backend. The helper takes `dump_mode="json"` for a payload boundary, so a distributed-execution plugin can call it instead of carrying its own copy that can drift.+- **Dry-Run Object Mocks Are Built From Your Real Class:** a consequence of the structured-output fix above, called out separately because it can require action. The dry-run leaf mock — for `PipeLLM` outputs and now for `PipeSearch`'s structured output too — now builds from your output class rather than a schema rebuild of it, so constraints the rebuild used to erase are enforced at mock-build time. A field whose type polyfactory cannot satisfy — an opaque custom type with a `__get_pydantic_core_schema__`, or a bare generic `ListContent` — can now fail `pipelex validate` with `DryRunMockBuildError` where it previously passed. Declare `examples` or `mock_format` on the offending field to fix it. The failure is loud and names the class and the remedy; it is not a silent behavior change. (Breaking)+- **`pipelex validate` Now Rejects A Structured-Search Output Your Provider Could Never Be Given:** every structured leaf describes your output class to the provider as JSON Schema, so a class Pydantic cannot describe — an `arbitrary_types_allowed` field, or an opaque type carrying only `__get_pydantic_core_schema__` — cannot drive one. The mock factory will happily build such a class, so a dry run used to pass and the live run then died inside the worker on a raw Pydantic error with no model attribution and no remedy. It now fails validation as `OutputStructureSchemaError`, naming the class. Replace the offending field's type, or give that type a `__get_pydantic_json_schema__`. (Breaking)- **PipeFunc Name Collisions Are Now Loud:** Registering two different functions under the same PipeFunc name raises `FuncRegistryError` naming both origins, instead of logging at debug level and letting the last scan win. Registration names are unqualified and every scanned library directory feeds one process-wide registry, so a silent overwrite made which function a `.mthds` step actually ran depend on filesystem scan order — and could differ between two machines running the same code. Re-registering the *same* function object stays a no-op, so overlapping scan roots are unaffected. See [PipeFunc](building-methods/pipes/pipe-operators/PipeFunc.md). (Breaking)## [v0.41.0] - 2026-07-30diff --git a/TODOS.md b/TODOS.mdindex 52b2bdc10..5aeb8a6f1 100644--- a/TODOS.md+++ b/TODOS.md@@ -1,157 +1,137 @@-# Two places where the runtime silently substituted something for what the caller gave it+# The follow-ups #1076 deferred, in the order they had to happen-Branch `refactor/Exec`, off `dev` at v0.41.0. Two independent fixes, batched because they share a shape and nothing else: in both, the runtime accepted a caller's object, quietly replaced it with something almost-equivalent, and never said so. One replaced a Pydantic class with a lossy rebuild of it; the other replaced a registered function with a later one of the same name.+Branch `refactor/Follow-ups`, off `dev` at #1076. Three items, ruled to run 2 → 4 → 3 for a reason worth stating up front: item 4 *removes* an in-process conversion, so item 3's audit of the surviving conversions is only meaningful after it — and item 2 first, because both of the others needed a single home for the contract they were about to change. (The numbering is #1076's, kept so the deferral notes still line up. Its item 1 — func-registry entries outliving their library — is untouched here and stays its own later PR.)-This file is the review guide. It carries the reasoning, the measurements, and — importantly — the two places where doing the work **corrected the plan that motivated it**. Read those first if you are short on time: they are where a reviewer's attention is worth the most.--- **Commit `ba9b0750c`** — `FuncRegistry.register_function` silently overwrote (item 2 below).-- **Commit `bbf06b707`** — the schema→`exec()` round trip was paid in-process, and it was lossy (item 1 below).--Each commit is independently green on `make agent-check`, `make drift-check`, and the full `make agent-test`.+This file is the review guide. The part most worth a reviewer's time is at the end of item 4: the live structured-search path turned out to be **broken today**, in a way none of the deferral notes predicted, and fixing it is what makes item 4 correct rather than merely wider.----## Item 1 — the schema→`exec()` round trip was paid in-process, and it was lossy+## Item 2 — one home for "convert a leaf result into the caller's class"### What was wrong-Structured generation handed a concrete Pydantic class to the content generator, which threw the class away, rebuilt an approximation of it from its JSON schema through code generation plus `exec()`, and gave the **rebuild** to the provider as the structured-output schema — while the original class was still sitting in the caller's frame.+The same conversion existed four times across two repos: `_revalidate_against_object_class` in `content_generator.py`, a copy of it in our distributed-execution plugin's workflow arm, and a dict-shaped inline in each repo's `make_search_structured`. All four implement one contract — validate the leaf's data against the caller's original class, and on the dry path re-raise the `ValidationError` as `DryRunObjectFidelityError` naming the class and the `examples` / `mock_format` remedy.-The path: `content_generator.make_object` / `make_object_list` received `object_class: type[BaseModelTypeVar]`; `ObjectAssignment.make_for_class` kept only `__name__` + `model_json_schema()` and dropped the class; `llm_generate.py` rebuilt it via `SchemaToModelFactory.make_from_json_schema` and passed the rebuild to `llm_worker.gen_object(schema=...)`; `dry_mock.py` rebuilt it on the dry path too. Then `content_generator` re-validated the result against the class it had never stopped holding.+The copies existed for one reason only: the original was `_`-private, so the plugin could not import it — even though it already imports `assignment_models`, `content_generator_protocol` and `exceptions` from that same package.-### What the rebuild drops — verified, not assumed+#1076 then made them **diverge**: core's copy gained the `isinstance` short-circuit, the plugin's did not. That is correct today — across `workflow.execute_activity` the object is always an instance of the class kajson rebuilt from `__kajson_class_source__`, never of `object_class` — but it is a latent trap, and the reasoning for why the check is `isinstance` and not `type(...) is` lived only in core's docstring.-- custom `@field_validator` / `@model_validator` logic-- `json_schema_extra` format/pattern hints-- **the output structure's own description** — its class docstring lands in `model_json_schema()["description"]`, and `datamodel-code-generator` does not re-emit it, so the rebuilt class has `__doc__ = None` and its schema has no top-level `description`. Field-level descriptions do survive.+### What landed-That last one the original plan did not name, and it is the most directly user-visible: every in-process structured call was sending the provider a schema stripped of the concept's own description — prompt-relevant signal, silently gone. Reproduce in three lines:+`pipelex/cogt/content_generation/object_revalidation.py`, a leaf module beside `object_class_resolution.py`. The two are the down leg and the up leg of the same journey, which is why they are siblings rather than one module.-```python-class Line(StructuredContent):- """A billed line."""- label: str+- `revalidate_leaf_object(raw_obj, *, object_class, is_mock_built, dump_mode="python")` — the object arm, carrying the short-circuit.+- `revalidate_leaf_data(raw_data, *, object_class, is_mock_built)` — the data arm. Data is never an instance of anything, so there is no short-circuit to make and its validation is the single one on its path.-rebuilt = SchemaToModelFactory.make_from_json_schema(schema=Line.model_json_schema(), class_name="Line")-assert rebuilt.__doc__ is None # and "description" is absent from rebuilt.model_json_schema()-```+The object arm delegates to the data arm, so the tree has exactly one `model_validate` call and one `except ValidationError` for this contract. The dry/live split is a branch inside that single `except`, rather than the two separate validate calls all four copies carried.-Read from the user's side: someone who writes a model with a validator got a structured-output schema that had silently lost it, so the provider was constrained by a weaker contract than the one they wrote. The re-validation caught the bad result *afterwards*; it did not stop the weaker schema from being sent.+**`dump_mode` is a parameter, not a unification.** Json mode coerces values (`datetime` → `str` and back); the in-process path must keep `"python"`. That was the deferral note's explicit instruction, and item 3 is why.-### The constraint that shaped the fix+### Worth a reviewer's attention-`ObjectAssignment` is a serializable DTO **by design**. It is the payload a distributed orchestrator — our Temporal plugin, hooked in via `pipelex/plugins/orchestrator_registry.py` — sends to a worker that has no access to the caller's class object. Across that boundary the class genuinely cannot travel, and rebuilding from schema is the right answer. So the fix is not "remove the reconstruction". It is "stop paying for it when nothing crossed a boundary".+- **The short-circuit now reaches the plugin's boundary path, where it never fires.** Intentional, not an oversight: it is dead code there today and exists so that a boundary which ever *does* hand back the caller's real class — a local activity, an in-process shortcut, a converter change — cannot silently reinstate the double validation. `test_instance_short_circuits_in_either_dump_mode` pins it in both modes.+- **A LIVE `ValidationError` passes through untouched, on purpose.** The plugin's `make_search_structured` catches exactly that to convert it into a terminal typed error, because a bare `ValidationError` raised in workflow code is neither a workflow-execution error nor a `PipelexError`, so the host runtime treats it as a workflow-task failure and retries it forever — hanging the submitter. Had the shared helper swallowed or re-typed it, that conversion would have gone quiet. `test_live_data_failure_keeps_its_validation_error` pins the half of the contract that lives here.+- **The plugin still carries its copies, and must.** It pins a released `pipelex` from PyPI, so it cannot import the new module until this ships. The swap is written up in the workspace notes, outside this repo.-### What changed+----- **`ObjectAssignment` is untouched.** No live-class field was added. It is a wire model; a `type[BaseModel]` field makes it unserializable and breaks the boundary path outright. This is the tempting wrong fix — the class is *right there* in `make_for_class` — and it was rejected deliberately, not overlooked.-- **The class is threaded as an explicit keyword-only parameter beside the assignment**, on the in-process path only: `llm_gen_object(object_assignment, *, object_class=None)` and the same on `llm_gen_object_list` and the two dry leaves. `None` means "no class in hand, rebuild from the schema" — which is exactly what a worker entering from the boundary passes, so **the boundary path keeps today's behaviour by construction, with no flag to set**.-- **One resolution helper serves both run modes** — `object_class_resolution.resolve_object_class`, a new leaf module so neither `llm_generate` nor `dry_mock` has to import the other. Live and dry both rebuilt before and both take the fast path now. Had only the live leaf been fixed, the dry mock would be built against a *weaker* class than the one the provider is constrained by — the mock would be more faithful than the thing it mocks, which is worse than the state we started from. `test_dry_leaf_resolves_the_class_the_same_way_as_the_live_leaf` asserts this directly rather than leaving it inferred from two separate passing tests.-- Keyword-only matters mechanically here: every function on this path already carries a subject grant in `subject_grants.toml`, and a grant covers one positional subject. A second bare positional would be a violation with or without it. No grant was added; the grant for the deleted `dry_mock._reconstruct_object_class` was removed.+## Item 4 — the in-process structured-*search* path still rebuilt the output class-### The measurement, and the correction it forces+### What was wrong-The plan asserted "a code generation plus an `exec()` per structured call". **That is wrong**, and the number says so: `SchemaToModelFactory.make_from_json_schema` memoizes on a sha256 of the schema, so the cost is per *distinct structure per process*, not per call. Measured on a representative `StructuredContent` (mixed primitives, an optional, a nested `$defs` list):+`make_search_structured` held the caller's `output_structure_class` and never threaded it down, so `PipeSearch` with a structured output still handed the provider a class rebuilt from JSON schema — losing the custom validators, the `json_schema_extra` hints, and the output structure's own description, exactly as #1076 established for the object paths. Same defect, same shape, one remaining path.-| | before | after |-|---|---|---|-| first structure in a process (one-time `datamodel-code-generator` warmup + codegen + `exec()`) | ~81 ms | 0 |-| each additional distinct structure | ~6–7 ms | 0 |-| repeat call on an already-seen structure | ~0.01 ms (cache hit) | 0 |+### Why it was not "four lines"-So the throughput win is real but small and front-loaded: ~81 ms + ~7 ms × (N−1) per process for a method with N distinct structured outputs, and effectively nothing per call after warm-up. **The fidelity fix is the reason to do this; the saved `exec()` perimeter and the codegen are the bonus.** Please weigh it that way — this is not a performance change.+The search leaf is **dict-out by contract** — that is what keeps a dynamic class off a distributed orchestrator's wire — and the submitter's re-validation of that dict is the single validation on the live path. Mirroring the object path naively breaks that in the dry arm: `dry_search_gen_structured` builds the mock and *dumps it*, so a mock built from the real class would have the caller's validators run at build **and again** on the dump. A transforming validator would produce `INV-INV-…` — the defect #1076 fixed on the object path with the `isinstance` short-circuit, which cannot apply once the instance has become a dict.-`schema_to_model_factory.py`'s module docstring now opens by saying when its perimeter is actually walked: only when no live class is in hand, which is also the only case where the schema is attacker-influenceable. Its Layer 2 restricted builtins are explicitly *not* a sandbox (`().__class__.__base__.__subclasses__()` stays reachable), so not walking it where nothing crossed a boundary is worth having on its own.+### What landed-### The three "verify rather than assume" items+Two entry points rather than one nullable parameter, because the two arms genuinely return different things:-- **Kajson's `__kajson_class_source__`.** Nothing regresses. The attribute exists so kajson can rebuild the reconstructed class on the far side of a process boundary. In-process, the leaf's return value is immediately converted by `_revalidate_against_object_class` into an instance of the caller's real class and never serialized as the rebuild; in-tree the attribute is read only by `SchemaToModelFactory`'s own tests. The boundary path — the only one that ships the rebuilt class anywhere — is untouched.-- **`_revalidate_against_object_class` on the fast path.** ⚠ **The plan got this one wrong, and both PR review bots caught it.** The plan said to keep the call and framed short-circuiting it as declining a *performance* saving. It is not a performance question: with the live class at the leaf, the provider (instructor's `response_model=`) already constructs **and validates** an instance of the caller's class, so re-validating the dump ran the caller's validators a **second** time, on data they had already normalized. A validator that transforms rather than rejects — `return f"INV-{value}"` — produced `INV-INV-…`; one that asserts its input is not yet normalized would reject valid provider output. Same defect on the list path and on the dry path. That is a regression this branch introduced, and it hit exactly the population the fix exists to serve. The fix is subtractive: `if isinstance(raw_obj, object_class): return raw_obj`. **`isinstance`, not `type(...) is`** — and not for defensiveness: instructor never returns the class you gave it, it returns `create_model(cls.__name__, __base__=(cls, OpenAISchema))`, a subclass. A `type(...) is` check would miss every real provider call and silently reinstate the double validation. `test_instructor_style_subclass_is_returned_without_revalidation` pins that. The call is still the boundary-path conversion (a schema-rebuilt class is never a subclass of `object_class`, so it falls through) and still the site that raises the dry fidelity error. The measured cost of the removed round trip is ~0.008 ms/object — nil, which is the point: the reason to short-circuit is semantic, not throughput.-- **`DryRunObjectFidelityError` reachability.** It stops firing on the in-process object path and stays reachable on the boundary path and on the structured-search path, which always rebuilds. Not deleted; its tests were re-scoped rather than removed.+- `search_gen_structured(search_object_assignment) -> dict[str, Any]` — the boundary arm. Unchanged signature, unchanged return, so **the activity that calls it needs no change at all**.+- `search_gen_structured_object(search_assignment, *, output_class) -> BaseModelTypeVar` — the in-process arm. The class goes down to the provider; an instance of it comes back, validated once at the leaf. It takes the plain `SearchAssignment`, not the wire model: nothing crosses a boundary in-process, so there is no schema to ship — and building the `SearchObjectAssignment` anyway would pay a `model_json_schema()` per call for a field nothing reads.-### The behaviour change a reviewer should actually look at+`dry_search_gen_structured_object` is the dry counterpart and returns the mock *instance*, not a dump of it. That is the double-validation fix, and its docstring says so in those terms.-On the in-process path the mock is now built from the real class, so an invariant the schema round-trip used to drop is present at *build* time. The constrained fixture therefore fails earlier and with a different class: `DryRunMockBuildError` out of `build_mock_object`, instead of `DryRunObjectFidelityError` out of the re-validation. Both are `ErrorDomain.INPUT`, both are caller-facing, and both name the same `examples` / `mock_format` remedy — but it is a wire-visible `error_type` change on that path and it should be seen, not skimmed.+No search-side resolution helper survived review: once the in-process arm carries the class outright, a `resolve_search_output_class` would have had no caller that ever passes a live class — a nullable arm that cannot fire. The boundary sites call `SchemaToModelFactory.make_from_json_schema` directly, and `resolve_object_class` keeps its genuinely dual-armed nullable parameter (exercised by `llm_generate`).-`test_dry_run_object_fidelity.py` was rewritten around exactly this split: it asserts the fidelity error against the boundary composition (leaf with no class in hand → re-validate, the same comprehension shape `make_object_list` uses), and asserts the build error in-process.+`ContentGenerator.make_search_structured` now returns the leaf's instance directly. It no longer re-validates, and therefore no longer raises `DryRunObjectFidelityError` — in-process the mock is built from the real class, so a constrained class fails earlier and louder as `DryRunMockBuildError`, exactly as the object path has since #1076. `test_dry_search_structured_fidelity_gap_raises_typed_error` was re-scoped to the boundary composition and renamed for it; the in-process build-error arm and an `INV-INV-` once-only arm are new tests beside it.-### Tests+### ⚠ The live search path was broken, and threading the class down would have made it worse-- **Identity, not equality** — `test_object_class_passthrough.py` asserts the provider receives *the same class object* (`schema is HintedName`), never a structurally-equal one. Structural equality is precisely what the round trip already preserved, so an equality assertion would have passed against the bug.-- **A validator that transforms, asserted to run exactly once** (`NormalizedReference`, `INV-` prefix). The original test suite used only a *rejecting* validator, which is idempotent and therefore structurally blind to double execution — which is why the double-validation regression above got past it. Both new tests were confirmed red without the `isinstance` short-circuit and green with it.-- A model carrying a custom validator and `json_schema_extra` hints reaches the provider with both intact, asserted observably (the received class rejects the invalid value; its schema still carries the hint).-- A **control** test proves the loss is real: with no class in hand, the rebuilt class *accepts* data the author's class rejects.-- The list path asserts the wrapper's item annotation is the caller's class, on both arms.-- Both run modes take the same path, asserted directly.+The deferral note flagged the live arm as "unverified: check whether the SDK internally instantiates the schema class". It does — and checking turned up something else first.----+**The Linkup backend asked for `include_sources=True`.** With that flag the SDK returns a `LinkupSearchStructuredResponse`, and the worker dumped the whole thing — so `search_structured` returned `{"data": {...}, "sources": [...]}` rather than the structured payload. The submitter then validated that envelope against the caller's output structure class, which has no `data` and no `sources` field. **Structured search through Linkup could not have worked.** The only test covering it is a live worker-level one written to assert the envelope, so it documented the shape rather than catching it. And the gateway backend had the same defect one hop removed: the relay's `WebSearcher.search_structured` also passes `include_sources=True` and returns the SDK response's `model_dump()`, so the gateway worker handed the leaf the same envelope — the default routing profile ships `all_pipelex_gateway`, so this was the arm users actually hit. The direct backend now asks for the payload alone; the gateway worker unwraps the relay's envelope on receipt (loudly, so a relay contract change surfaces as a classified error), and both backends hand the leaf the bare payload.-## Item 2 — `FuncRegistry.register_function` silently overwrote+**And the SDK does instantiate the class.** `_parse_search_response` calls `structured_output_schema.model_validate(...)` whenever it was handed a class rather than a string. Threading the caller's real class in would therefore have run the caller's validators inside the SDK and then again at the leaf — the same `INV-INV-…` defect, arriving through the provider instead of through the mock.-### What was wrong+Both are fixed at the worker, and the fix for the second is the one to check: **the schema crosses as a JSON string.** `_get_search_params` sends `json.dumps(cls.model_json_schema())` when handed a class and the string verbatim when handed a string, so `json.dumps(schema.model_json_schema())` is byte-for-byte the same request — while the parse branch that instantiates is guarded by `not isinstance(..., str)`, so the response comes back raw. The caller's real schema still reaches the provider in full; the single validation stays at the leaf, where the run mode and the fidelity contract live. `include_sources` is now `False`, matching what the contract can actually carry.-On a key collision, `register_function` logged and then overwrote anyway. `log()` is `self._logger.debug(...)`, so under any normal configuration the collision produced no visible output at all — and the assignment ran on both branches, so the `if` distinguished only the wording.+`tests/unit/pipelex/providers/linkup/test_linkup_structured_search_contract.py` pins all three properties against a mocked client, and the live worker test's assertions were corrected to the payload shape.-Three facts made it reachable rather than theoretical: the registry is a flat, process-global `dict[str, Callable]`, so there is one key space for every source that ever registers; registration names are unqualified (the `@pipe_func` custom name if given, otherwise the bare `func.__name__` — no module, no package, no library prefix); and registration is driven by scanning the configured library directories.+---++## Item 3 — auditing the boundary dump→validate round trip-**The asymmetry gives it away.** `unregister_function` and `unregister_function_by_name` *raise* `FuncRegistryError` when a name is absent. Removing something that was never there was a hard error; replacing something that is there was a debug line.+The deferral said: audit what actually crosses this conversion, add a round-trip property test over the models that do, and *if the audit finds a real loss*, consider having the boundary return raw data instead of a reconstructed instance. It found one. The fix turned out to be one keyword, not a redesign.-### The failure+### Who reaches the conversion-Two library directories — or a library plus an installed package — each defining a `@pipe_func` named `summarize` produced a registry containing one of them, chosen by scan order. Every `PipeFunc` step naming `summarize` then ran the winner, including steps authored against the loser, with no warning at author time, boot time, or run time. Scan order comes from the filesystem and `pkgutil`, so which one wins could differ between two machines running the same code.+**Nothing in this repo does.** Every branch of `make_object` / `make_object_list` returns an `isinstance` of `object_class`, so the short-circuit always fires:-### What changed+- **DRY** — `resolve_object_class` returns the caller's class unchanged and polyfactory's `build()` instantiates `__model__` itself, so the mock is exactly `object_class`.+- **LIVE** — checked against every concrete LLM worker, not a sample: the OpenAI (completions + responses), Anthropic, Mistral and Google workers all return instructor's object untouched, and Bedrock raises `LLMCapabilityError` rather than returning. Gateway / Portkey / Azure / OpenRouter are those same workers under a different factory. Instructor's wrapper is `create_model(cls.__name__, __base__=(cls, OpenAISchema))`, a subclass — which is why the check is `isinstance`.+- **The list path** wraps only the top-level `ListSchema`; its `items` are constructed by pydantic against `list[item_class]`.-A collision now raises `FuncRegistryError` naming the key, both origins, and the remedy (`@pipe_func(name=...)`). The registry already raised on the symmetric case, so this is consistency, not a new posture.+**The distributed boundary always reaches it**, and cannot short-circuit: the activity calls the leaves without a class, and kajson re-execs the rebuilt class on the workflow side from `__kajson_class_source__`, so what comes back is never a subclass of `object_class`. That is the split the design intends, now established rather than assumed.-### The two open questions, answered by reading the code+### The loss-- **Is re-registering the *same* function object a collision?** No — it is a no-op. This is the shape the double-scan actually produces: `import_module_from_file` keys `sys.modules` by a name mangled from the file's **absolute path**, so a folder scanned twice returns the cached module and therefore the *same* function object. Two distinct objects under one key is the only shape that indicates a real clash. Pinned by `test_rescanning_the_same_folder_is_idempotent`.-- **Does any first-party code deliberately overwrite?** No — `pipelex/` defines no `@pipe_func` of its own, so nothing registers a builtin expecting a user function to replace it. **No `replace=True` parameter was added**; with no caller for it, it would have been a speculative surface.+`object_class` is always a `StuffContent` subclass resolved **by name** from the class registry, so the set is open — any field name a user writes in a concept structure crosses this conversion.-### ⚠ The one place this narrows a path that used to work+`datamodel-code-generator` cannot name a field `json`, `copy`, `schema` or `construct` (they shadow `BaseModel` attributes), nor use a python keyword. It renames the field and records the schema's property name as an alias. Dumping **by field name** emitted `construct_` for a field the caller's class calls `construct`, and re-validation failed with a bare `Field required` — on a field the caller had supplied.-`LibraryManager.teardown(library_id=…)` does **not** clear `func_registry` — only `RuntimeBoot.teardown` does. So in a long-lived process that loads bundle A, tears it down, then loads bundle B, a registration name shared by both now collides with A's **stale** entry and B fails to load until the process restarts. Previously the overwrite was silent and B won, which for the sequential case was right.+`by_alias=True` on the dump fixes it: the schema's property names are what the class was serialized as and what it accepts back, and where nothing was renamed the alias *is* the field name, so nothing else moves. The same one-word fix was needed on `dry_search_gen_structured`, which dumps its mock for the wire. `test_boundary_roundtrip_fidelity.py` fails on every shadowing field without it, in both dump modes, and carries the native content classes as controls.-Tracing the hosts shows **no first-party process can reach this today**: a direct-mode `pipelex-api`'s library dirs are process-constant (per-request `ApiRunner()` passes `library_dirs=None`, resolving to boot-time defaults or `PIPELEXPATH`, and inline `.mthds` text registers no functions), the local MCP workshop is a TypeScript client that runs no pipelex in-process, and the hosted runner is immune (it takes the source-capture branch and never registers in-process). The exposed population is a third-party embedder varying `library_dirs` per call in one long-lived process — a public surface, so the narrowing is real, but the failure there is loud and typed, not silent. Two loads of the *same* bundle are fine — the module is cached by absolute path, so the same object re-registers and the idempotent no-op absorbs it.+**The old note had the mechanism wrong, and it matters.** It supposed `PipeSearchSpec` / `PipeComposeSpec` survive thanks to `populate_by_name=True`. `PipeComposeSpec` did **not** survive — its `construct` property is exactly a shadowed name, and `populate_by_name` cannot help when the emitted key (`construct_`) matches neither the field name nor the alias. `PipeSearchSpec` survived only because `query` happens to be a legal field name.-Not fixed here, and not because it is unimportant: there is no small correct fix. `func_registry` is a flat process-global dict with **no ownership dimension**, so per-library eviction has nothing to key on — note that each `Library` already owns its own `ClassRegistry`, and functions never got the same treatment. The remedy (ownership side table, id threaded through registration, eviction on teardown, rollback on a failed scan) is a design change that deserves its own review, not a late addition to this branch. Written up in `wip/refactoring/func-registry-entries-outlive-their-library.md`. **Ruled 2026-07-31: non-blocking.** With no first-party path reachable (see above) and the third-party failure mode loud and typed, this PR ships with the gap documented and the ownership design lands as its own follow-up PR.+### What turned out to be safe, and now has a test-### One reachability check worth recording+- **Plain aliases need no compensation at all.** `model_json_schema()` emits by alias, so the rebuilt class's field name *is* the alias — with or without `populate_by_name`.+- **Subclass erasure is structurally unreachable**, not merely unobserved: the crossing object is built from `object_class`'s own schema so it cannot carry extra fields, and the one object that *is* a subclass hits the short-circuit and is never dumped. No test, because the case cannot be constructed through this path.+- **`CompositeContent` survives** — `extra="allow"` comes through the rebuild, so its components are preserved rather than dropped as unknown keys.-The transported PipeFunc path (`DirectPipeFuncExecutor.run_pipe_func_transported`) materializes customer sources into a fresh `mkdtemp` workdir, which *would* yield a different function object under the same name on a second run in one process. It stays safe because that path is one-shot per process: `pipe_func_transported_entrypoint` runs exactly one request and then calls `Pipelex.teardown_if_needed()`, which clears the registry. Recorded here so a reviewer does not have to re-derive it.+### Left open, deliberately-### Tests+- **Instructor's `PARALLEL_TOOLS` modes return a generator, not an instance** — which would break the short-circuit's premise. Reachable from `StructureMethod`, but no model in the shipped TOMLs selects them. A config-reachable hazard, not a live one; worth a guard when one is configured, not before.+- **Json-mode losslessness for arbitrary user field types** on the distributed arm. The residue of the original note, now narrowed to that.-Two distinct functions under one name raise, and the message names both sources; the same function object registered twice is a no-op; an ineligible function still routes to `register_ineligible_function` and does not participate in collision detection; and end to end, two library directories defining the same function name fail the scan with the typed error instead of silently picking one.+Both are recorded in `wip/refactoring/boundary-revalidation-round-trip-audit.md`, which replaces the "unaudited" note.----## Deliberately not done+## What the pre-landing review changed-Each of these is a plausible-looking scope expansion that was declined on purpose.+A full `/review` pass on this branch found production holes the deferral notes did not anticipate, and they are fixed here: the **direct Linkup backend could silently return wrong answers** (its only guard was `isinstance(response, dict)`, which the `{data, sources}` envelope passes — and an output structure whose fields all carry defaults validates that envelope *successfully* into an all-defaults object); a **billed search whose shape was rejected vanished from the cost report** (both new guards raise after the provider answered and after usage was recorded, and the worker only reported on the success path); and **`pipelex validate` stopped catching an output class that cannot emit a JSON schema** (dropping `SearchObjectAssignment.make_for_class` in-process also dropped the only `model_json_schema()` call on that path, so a dry run passed and the live run died inside the worker on a bare `RuntimeError`).-- **Not replacing `exec()` with `pydantic.create_model()`.** That is the standing TODO at `schema_to_model_factory.py` and a larger change with its own compatibility surface (`__kajson_class_source__` exists because the generated source is shipped verbatim). Item 1 makes that TODO matter *less* by not walking the path in-process; it does not close it, and the docstring does not imply otherwise.-- **Not namespacing the function registry by module.** Qualified names would remove the collision class entirely, but `function_name` is authored in `.mthds` files, so that is a language decision, not a registry fix.-- **Not changing `ObjectAssignment`'s wire shape.** Anything that alters the payload an orchestrator plugin sends belongs in its own change, argued on its own terms.-- **Not extending the fix to the in-process structured-*search* path.** `make_search_structured` holds `output_structure_class` and does not thread it down, so `PipeSearch` with a structured output still loses the docstring, validators and `json_schema_extra` hints to the rebuild. It is the same bug in the same shape, roughly four lines away — declined here rather than in scope creep, because it changes a *second* error-class surface the same way the object path's did (fidelity error → build error), which needs its own test re-scoping and its own review pass rather than riding in on a branch that is already bot-clean. Deferred to `wip/refactoring/structured-search-still-rebuilds-in-process.md`.-- **Not auditing the *boundary* arm of `_revalidate_against_object_class`.** Its `model_dump(serialize_as_any=True)` → `model_validate` round trip is not identity-preserving in general (subclass erasure; dumped-by-field-name data that only revalidates thanks to `populate_by_name=True` and a compensating before-validator elsewhere). Pre-existing, unchanged here, must stay — it *is* the boundary conversion. Deferred to `wip/refactoring/boundary-revalidation-round-trip-is-unaudited.md`.+Both backends now recognise the envelope **structurally** — via `pipelex/cogt/search/structured_search_payload.py` — rather than inferring the response shape from their own request. That also decouples the deploy: when the relay stops asking Linkup for sources, the gateway keeps working on the bare payload instead of rejecting every search. Alongside: reporting moved into `finally` in both search methods; a schema-generability check with a typed `OutputStructureSchemaError` on the in-process dry arm; `json.loads` wrapped so a non-JSON relay body is classified; an empty result now says so and points at the query instead of advising "try a different model"; and `linkup/exceptions.py` became `linkup_exceptions.py` with a `LinkupError` base, matching the sibling providers.-## Cross-repo+## Still deferred-⚠ **An earlier revision of this file claimed "checked, nothing to change". That claim was false, and the reason is worth knowing: a workspace-rooted `grep -r … .` silently returned zero matches while iterating the sibling repo directories explicitly returned 71.** The sweep below was redone by enumerating `*/` one directory at a time. Never trust a single `.`-rooted recursive grep for a cross-repo sweep here.+The items the review surfaced and did **not** fix are written up, with their evidence and the command that produced it, in [`wip/refactoring/leaf-conversion-and-search-follow-ups.md`](wip/refactoring/leaf-conversion-and-search-follow-ups.md) — cite them as **RF-1** … **RF-7**. **RF-1 is the one to settle before the plugin sweep:** the bare live re-raise documented above as deliberate is right, but the plugin's *own* two arms disagree about it — its object helper lets a live `ValidationError` escape workflow code, while its search submitter converts it to a terminal typed error with a comment explaining that letting it escape retries forever and hangs the submitter. Both run in workflow code, so they cannot both be right, and swapping in the shared helper as-is would carry that unresolved disagreement into the shared home.-**`cocode` breaks on upgrade — release-gated, needs a follow-up PR in that repo.** `cocode/cocode/pipelines/doc_proofread/file_utils.py` carries `@pipe_func()` *and* a redundant module-level `func_registry.register_function(read_file_content, name="read_file_content")`. `cocode/cocode/swe/swe_cmd.py:18` dotted-imports that module at CLI startup, registering object **A**; `PIPELINE_LIBRARY_DIRS` then makes the same directory a library dir, so the boot scan re-imports the file under a path-mangled `sys.modules` key, the module-level call fires again with object **B**, and the new collision check raises. Every `cocode` command would die at first `load_libraries`. Shielded only by cocode's `pipelex==0.41.0` pin. The fix belongs in cocode and is a deletion: the `@pipe_func()` decorator already covers the registration, so the explicit call is redundant belt-and-braces. `cocode/cocode/pipelines/text_utils.py:81` is the same shape but currently latent — it has no `@pipe_func`, so the scan's AST pre-check skips the file entirely.+- **Func-registry entries outliving their library** (#1076's item 1). Ruled to be its own later PR, after these. `wip/refactoring/func-registry-entries-outlive-their-library.md`.+- **Our distributed-execution plugin's copies of the revalidation helper.** Release-gated on shipping `object_revalidation` — but no longer just a swap: see **RF-1** (the live-error contract blocks adoption) and **RF-2** (the copies now diverge on the `by_alias` fix this branch announces, which is reachable only on the plugin's arm).+- **Dry search leaves report no usage.** Pre-existing, not introduced here; a small design rather than a mechanical patch, because it means choosing the synthetic-search-job conventions. Now recorded as **RF-6** rather than living only in this file.+- **The remaining test gaps, the missing Linkup request timeout, and a coupled optimisation trap on the LLM path** — **RF-3**, **RF-4**, **RF-5**. RF-5 is worth reading before anyone "cleans up" the unused `model_json_schema()` call in `ObjectAssignment.make_for_class`: that call is what still implicitly guards the LLM path.++## Cross-repo-Checked and clean:+The sweep was done by enumerating the workspace's sibling repos one directory at a time. ⚠ A workspace-rooted `grep -r … .` silently returns zero matches here; exactly one consumer holds affected code, and every other hit is another worktree of this same repo.-- The private Temporal plugin's `act_llm_gen_object` / `act_llm_gen_object_list` call `llm_gen_object(object_assignment=...)` with no class, so they take the boundary path unchanged. Its `content_generator_in_workflow.py` comment describing the reconstruction stays accurate for that path.-- `pipelex-transport` and `pipelex-mistralai-workflows` bridge conftests register module-level function objects with teardown — the idempotent case.-- `pipelex-demo-mistral` / `pipelex-demo-vibe` register `flaky_echo` explicitly, and it carries no `@pipe_func` decorator, so the folder scan's AST pre-check never imports the file. One registration per process.-- The only `llm_gen_object` mention in `docs/specs/` is the `UnitJobId` string value, which did not change.+**Our distributed-execution plugin** — carries the copies item 2 replaces, and needs no change for item 4: the structured-search activity calls the boundary arm, whose signature and return type did not move. Release-gated on this shipping; the swap is written up in the workspace notes, outside this repo.-## Docs touched+**`pipelex-relay`** — optional alignment, not required for correctness, and **no longer a coordinated two-sided change**: the relay's structured route still passes `include_sources=True`, making Linkup gather sources the structured contract cannot carry, and wraps the payload in the `{data, sources}` envelope. The gateway worker now recognises that envelope *structurally* rather than demanding it, so the relay can stop requesting sources and return the payload alone on its own schedule — the worker handles either shape. What is left is that nothing on the producing side pins the contract, and the relay's own unit test asserts the opposite shape; that is **RF-7**.-- `docs/building-methods/pipes/pipe-operators/PipeFunc.md` — new "Function names share one flat name space" section.-- `docs/under-the-hood/dry-run-mock-generation.md` — the dry object leaf resolves its class the same way the live leaf does; which typed error you get on which path.-- `docs/under-the-hood/distributed-content-generation.md` — reconstruction is the boundary answer and only that; the type bridge is kept in-process on purpose.+**`cocode` breaks on upgrade — still open, carried over from #1076, needs a follow-up PR in that repo.** `cocode/cocode/pipelines/doc_proofread/file_utils.py` carries `@pipe_func()` *and* a redundant module-level `func_registry.register_function(read_file_content, name="read_file_content")`. `cocode/cocode/swe/swe_cmd.py:18` dotted-imports that module at CLI startup, registering object **A**; `PIPELINE_LIBRARY_DIRS` then makes the same directory a library dir, so the boot scan re-imports the file under a path-mangled `sys.modules` key, the module-level call fires again with object **B**, and #1076's collision check raises. Every `cocode` command would die at first `load_libraries`. Shielded only by cocode's `pipelex==0.41.0` pin. The fix belongs in cocode and is a deletion: the `@pipe_func()` decorator already covers the registration. ⚠ `cocode/cocode/pipelines/text_utils.py:81` is *not* the same fix — it has no decorator, so its explicit call is its only registration.diff --git a/docs/errors/gateway-search-empty-result-error.md b/docs/errors/gateway-search-empty-result-error.mdnew file mode 100644index 000000000..b13df259a--- /dev/null+++ b/docs/errors/gateway-search-empty-result-error.md@@ -0,0 +1,19 @@+---+title: "Gateway search empty result"+description: "Reference for the `GatewaySearchEmptyResultError` Pipelex error class."+---++<!-- pipelex:generated -->++# Gateway search empty result++| Field | Value |+|---|---|+| `error_type` | `GatewaySearchEmptyResultError` |+| `title` | Gateway search empty result |+| `type_uri` | `https://docs.pipelex.com/latest/errors/gateway-search-empty-result-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.providers.gateway.gateway_exceptions` |+| Parent class | [`GatewayError`](gateway-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/inference-and-providers.md b/docs/errors/inference-and-providers.mdindex 5b6750b87..5975eccba 100644--- a/docs/errors/inference-and-providers.md+++ b/docs/errors/inference-and-providers.md@@ -59,6 +59,7 @@ own page. Classes are grouped by subsystem.- [`ModelReferenceParseError`](model-reference-parse-error.md) — Model reference parse- [`ModelWaterfallError`](model-waterfall-error.md) — Model waterfall- [`NeitherUrlNorDataError`](neither-url-nor-data-error.md) — Neither url nor data+- [`OutputStructureSchemaError`](output-structure-schema-error.md) — Output structure schema- [`PromptDocumentFactoryError`](prompt-document-factory-error.md) — Prompt document factory- [`PromptImageFactoryError`](prompt-image-factory-error.md) — Prompt image factory- [`PromptImageFormatError`](prompt-image-format-error.md) — Prompt image format@@ -88,9 +89,13 @@ own page. Classes are grouped by subsystem.- [`GatewayError`](gateway-error.md) — Gateway- [`GatewayExtractResponseError`](gateway-extract-response-error.md) — Gateway extract response- [`GatewayFactoryError`](gateway-factory-error.md) — Gateway factory+- [`GatewaySearchEmptyResultError`](gateway-search-empty-result-error.md) — Gateway search empty result- [`GatewaySearchResponseError`](gateway-search-response-error.md) — Gateway search response- [`GoogleImgGenWorkerError`](google-img-gen-worker-error.md) — Google img gen worker- [`GoogleLLMWorkerError`](google-llm-worker-error.md) — Google LLM worker+- [`LinkupError`](linkup-error.md) — Linkup+- [`LinkupSearchEmptyResultError`](linkup-search-empty-result-error.md) — Linkup search empty result+- [`LinkupSearchResponseError`](linkup-search-response-error.md) — Linkup search response- [`MistralExtractResponseError`](mistral-extract-response-error.md) — Mistral extract response- [`MistralModelListingError`](mistral-model-listing-error.md) — Mistral model listing- [`MistralPluginError`](mistral-plugin-error.md) — Mistral plugindiff --git a/docs/errors/linkup-error.md b/docs/errors/linkup-error.mdnew file mode 100644index 000000000..9373d0b59--- /dev/null+++ b/docs/errors/linkup-error.md@@ -0,0 +1,21 @@+---+title: "Linkup"+description: "Reference for the `LinkupError` Pipelex error class."+---++<!-- pipelex:generated -->++# Linkup++Base for every error this backend raises, so callers can catch the provider as a family.++| Field | Value |+|---|---|+| `error_type` | `LinkupError` |+| `title` | Linkup |+| `type_uri` | `https://docs.pipelex.com/latest/errors/linkup-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.providers.linkup.linkup_exceptions` |+| Parent class | [`CogtError`](cogt-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/linkup-search-empty-result-error.md b/docs/errors/linkup-search-empty-result-error.mdnew file mode 100644index 000000000..78bc71156--- /dev/null+++ b/docs/errors/linkup-search-empty-result-error.md@@ -0,0 +1,21 @@+---+title: "Linkup search empty result"+description: "Reference for the `LinkupSearchEmptyResultError` Pipelex error class."+---++<!-- pipelex:generated -->++# Linkup search empty result++The Linkup API answered a structured search with no object payload to fill the output structure.++| Field | Value |+|---|---|+| `error_type` | `LinkupSearchEmptyResultError` |+| `title` | Linkup search empty result |+| `type_uri` | `https://docs.pipelex.com/latest/errors/linkup-search-empty-result-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.providers.linkup.linkup_exceptions` |+| Parent class | [`LinkupError`](linkup-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/linkup-search-response-error.md b/docs/errors/linkup-search-response-error.mdnew file mode 100644index 000000000..8d3642925--- /dev/null+++ b/docs/errors/linkup-search-response-error.md@@ -0,0 +1,21 @@+---+title: "Linkup search response"+description: "Reference for the `LinkupSearchResponseError` Pipelex error class."+---++<!-- pipelex:generated -->++# Linkup search response++The Linkup API answered a structured search with a payload shape the leaf cannot validate.++| Field | Value |+|---|---|+| `error_type` | `LinkupSearchResponseError` |+| `title` | Linkup search response |+| `type_uri` | `https://docs.pipelex.com/latest/errors/linkup-search-response-error/` |+| `error_domain` | _(inherited from parent)_ |+| Defined in | `pipelex.providers.linkup.linkup_exceptions` |+| Parent class | [`LinkupError`](linkup-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/errors/output-structure-schema-error.md b/docs/errors/output-structure-schema-error.mdnew file mode 100644index 000000000..76065ed66--- /dev/null+++ b/docs/errors/output-structure-schema-error.md@@ -0,0 +1,21 @@+---+title: "Output structure schema"+description: "Reference for the `OutputStructureSchemaError` Pipelex error class."+---++<!-- pipelex:generated -->++# Output structure schema++Raised when an output structure class cannot produce the JSON schema a structured leaf needs.++| Field | Value |+|---|---|+| `error_type` | `OutputStructureSchemaError` |+| `title` | Output structure schema |+| `type_uri` | `https://docs.pipelex.com/latest/errors/output-structure-schema-error/` |+| `error_domain` | `input` |+| Defined in | `pipelex.cogt.content_generation.exceptions` |+| Parent class | [`PipelexError`](pipelex-error.md) |++[Back to Error Reference](index.md)diff --git a/docs/under-the-hood/distributed-content-generation.md b/docs/under-the-hood/distributed-content-generation.mdindex b4ec5fb10..3d16d7111 100644--- a/docs/under-the-hood/distributed-content-generation.md+++ b/docs/under-the-hood/distributed-content-generation.md@@ -102,18 +102,30 @@ Re-attaching after `kajson.loads()` ensures the source survives if the object cr### The type bridge-The class reconstructed on the worker is a structural match to the original, but a different Python class in memory — so `isinstance()` checks would fail. The caller bridges the gap with a `model_validate` round-trip (`pipelex/cogt/content_generation/content_generator.py`):+The class reconstructed on the worker is a structural match to the original, but a different Python class in memory — so `isinstance()` checks would fail. The caller bridges the gap with a `model_validate` round-trip, in `revalidate_leaf_object` (`pipelex/cogt/content_generation/object_revalidation.py`):```python-raw_obj = await llm_gen_object(object_assignment=object_assignment, object_class=object_class)-return object_class.model_validate(raw_obj.model_dump(serialize_as_any=True))+if isinstance(raw_obj, object_class):+ return raw_obj+return object_class.model_validate(raw_obj.model_dump(mode=dump_mode, serialize_as_any=True, by_alias=True))```-`model_dump(serialize_as_any=True)` produces a plain dict from the reconstructed object, and `model_validate()` rebuilds it as a proper instance of the original class, restoring type safety for downstream code. The bridge is kept on the in-process path too, where it becomes a same-type conversion: it is still the site that raises the typed dry-run fidelity error, and it is what makes the two paths return the same thing.+`model_dump(serialize_as_any=True)` produces a plain dict from the reconstructed object, and `model_validate()` rebuilds it as a proper instance of the original class, restoring type safety for downstream code.++`by_alias=True` is what keys that dict correctly. `model_json_schema()` emits **by alias**, so the schema's property names are what the original class accepts on the way back in — but the reconstructed class does not always name its fields that way. `datamodel-code-generator` renames any property that cannot be a field name (a python keyword, or a name shadowing a `BaseModel` attribute such as `json`, `copy`, `schema`, `construct`) and records the original as an alias. Dumping by field name would emit `construct_` for a field the original calls `construct`. Where nothing was renamed, the alias is the field name, so this is a no-op.++The short-circuit is what makes this a *boundary* conversion rather than a step on every path. In-process the leaf already worked from the caller's class, so the object is already one — note `isinstance`, not `type(...) is`: a provider library typically returns a *subclass* of the response model, not the class itself. Converting it anyway would run the caller's validators a second time on data they already normalized, which corrupts the output of any validator that transforms rather than merely rejects. A reconstructed class is never a subclass of the original, so the boundary path falls through to the conversion as before.++The helper is public so that both implementations of `ContentGeneratorProtocol` can share it — the in-process generator, which uses it today, and a host runtime's workflow arm, which still carries its own copy and adopts the shared one on its next release. The point of the single home is that the conversion, the short-circuit and the typed dry-run fidelity error stop being two copies that only agree until someone edits one. `dump_mode` is the one thing the two boundaries differ on: an object that crossed a payload boundary needs `mode="json"`, because some field types only round-trip cleanly through their json form.### Structured web search reuses the same mechanism-Structured web search (`PipeSearch` with a non-text output concept) faces the identical dynamic-class problem and solves it the same way. `SearchObjectAssignment` mirrors `ObjectAssignment` — it ships `output_class_name` + `output_class_schema` alongside the `SearchAssignment`, the activity reconstructs a throwaway class to drive the provider call, and returns the **raw result dict**. The submitter re-validates that dict against the original output class (`output_structure_class.model_validate(result_dict)`) — a pure, deterministic step that keeps the dynamic class on the submitter side and never ships it across the boundary. The sourced-answer path (`make_search_sourced_answer`) has no dynamic class at all: it returns a `SearchResultContent`, a native serializable model.+Structured web search (`PipeSearch` with a non-text output concept) faces the identical dynamic-class problem and splits the same way, with one twist: the boundary arm must keep the *result* serializable too.++- **At the boundary**, `SearchObjectAssignment` mirrors `ObjectAssignment` — it ships `output_class_name` + `output_class_schema` alongside the `SearchAssignment`, the activity reconstructs a throwaway class to drive the provider call, and `search_gen_structured` returns the **raw result dict**. The submitter re-validates that dict against the original output class — a pure, deterministic step that keeps the dynamic class on the submitter side and never ships it across the boundary.+- **In-process**, `search_gen_structured_object` takes the caller's class, hands it to the provider unchanged, and returns an instance of it. The validation happens once, at the leaf, next to the provider. Returning the instance rather than a dump of it is what keeps it once: the search leaf has no object to short-circuit on if its result has already become a dict.++The sourced-answer path (`make_search_sourced_answer`) has no dynamic class at all: it returns a `SearchResultContent`, a native serializable model.---diff --git a/docs/under-the-hood/dry-run-mock-generation.md b/docs/under-the-hood/dry-run-mock-generation.mdindex 33af6a396..061f29afd 100644--- a/docs/under-the-hood/dry-run-mock-generation.md+++ b/docs/under-the-hood/dry-run-mock-generation.md@@ -52,6 +52,7 @@ A dry run does not swap in a special content generator: `run_mode=DRY` rides `Co|---------|-------------|-----------------|| `pipelex validate` | `BundleValidator.validate_pipes()` | `WorkingMemoryFactory.make_mock_inputs()` || `PipeLLM` output in dry mode | `dry_llm_gen_object()` / `dry_llm_gen_object_list()` (cogt leaf, `dry_mock.py`) | `DryRunFactory` via the caller's class in-process, via the schema-reconstructed class on a worker |+| `PipeSearch` structured output in dry mode | `dry_search_gen_structured_object()` in-process / `dry_search_gen_structured()` on a worker (cogt leaf, `dry_mock.py`) | Same split as `PipeLLM`; the worker arm dumps its mock to a dict, because the leaf's result crosses the boundary as data || `PipeFunc` output in dry mode | `WorkingMemoryFactory.make_mock_content()` | `DryRunFactory` (with explicit field constraints) || `PipeCompose` in dry mode | `StructuredContentComposer.compose()` | Uses resolved values from working memory; falls back to a `DryRunFactory` mock of the output class only when a value error hits under mock inputs |diff --git a/pipelex/cogt/content_generation/content_generator.py b/pipelex/cogt/content_generation/content_generator.pyindex 8f0f57f7c..39f27c9ad 100644--- a/pipelex/cogt/content_generation/content_generator.py+++ b/pipelex/cogt/content_generation/content_generator.py@@ -1,6 +1,5 @@from typing import Any-from pydantic import BaseModel, ValidationErrorfrom typing_extensions import overridefrom pipelex import log@@ -11,18 +10,17 @@ from pipelex.cogt.content_generation.assignment_models import (ObjectAssignment,RenderPageViewsAssignment,SearchAssignment,- SearchObjectAssignment,TemplatingAssignment,)from pipelex.cogt.content_generation.cogt_run_params import CogtRunParamsfrom pipelex.cogt.content_generation.content_generator_protocol import ContentGeneratorProtocol, update_job_metadata-from pipelex.cogt.content_generation.exceptions import DryRunObjectFidelityErrorfrom pipelex.cogt.content_generation.extract_generate import extract_gen_pages_and_storefrom pipelex.cogt.content_generation.generated_content_factory import GeneratedContentFactoryfrom pipelex.cogt.content_generation.img_gen_generate import img_gen_image_list_and_store, img_gen_single_image_and_storefrom pipelex.cogt.content_generation.llm_generate import llm_gen_object, llm_gen_object_list, llm_gen_text+from pipelex.cogt.content_generation.object_revalidation import revalidate_leaf_objectfrom pipelex.cogt.content_generation.render_generate import render_page_views_and_store-from pipelex.cogt.content_generation.search_generate import search_gen_sourced_answer, search_gen_structured+from pipelex.cogt.content_generation.search_generate import search_gen_sourced_answer, search_gen_structured_objectfrom pipelex.cogt.content_generation.templating_generate import templating_gen_textfrom pipelex.cogt.extract.extract_input import ExtractInputfrom pipelex.cogt.extract.extract_job_components import ExtractJobConfig, ExtractJobParams@@ -41,50 +39,6 @@ from pipelex.tools.templating.templating_style import TemplatingStylefrom pipelex.tools.typing.pydantic_utils import BaseModelTypeVar-def _revalidate_against_object_class(- raw_obj: BaseModel,- *,- object_class: type[BaseModelTypeVar],- is_mock_built: bool,-) -> BaseModelTypeVar:- """Convert a leaf-generated object into ``object_class``, unless it already is one.-- On the in-process path the leaf worked from ``object_class``, so the object is already one — note- ``isinstance``, not ``type(...) is``: instructor does not hand back the class you gave it, it hands- back ``create_model(cls.__name__, __base__=(cls, OpenAISchema))``, a *subclass*. Either way it needs- no conversion — and re-validating it would run the caller's validators a **second** time, on data- they already normalized. A validator that transforms rather than merely rejects (``f"INV-{value}"``, a- list that gets a default appended) would corrupt its own output, and one that asserts its input is- not yet normalized would reject valid provider output. Returning it untouched is what makes the- caller's validator constrain the provider exactly once, which is the whole point of handing the live- class down.-- The conversion is still needed at the *boundary*: a leaf that ran on a worker holding only the- serialized assignment returns a plain ``BaseModel`` reconstructed from the JSON schema — never a- subclass of ``object_class`` — so re-validating its data makes the result the proper subtype (e.g.- ``StructuredContent``) the caller expects.-- Under the dry-run leaf mock (``run_mode=DRY``) that reconstruction is also what polyfactory built the- mock from, and it can drop invariants the original class enforces (custom validators,- ``json_schema_extra`` format/pattern hints datamodel-code-generator omits on round-trip). A- re-validation failure there is the known object-mock fidelity gap, so the ``ValidationError`` is- re-raised as a clear typed :class:`DryRunObjectFidelityError` naming the class and the- ``examples`` / ``mock_format`` remedy. That gap cannot occur in-process — the mock is built from the- real class, so an unsatisfiable invariant fails earlier and louder, as ``DryRunMockBuildError`` out of- ``build_mock_object``, and never reaches this function. The catch is scoped to the dry path only — a- LIVE provider's invalid output keeps its existing ``ValidationError``.- """- if isinstance(raw_obj, object_class):- return raw_obj- raw_data = raw_obj.model_dump(serialize_as_any=True)- if not is_mock_built:- return object_class.model_validate(raw_data)- try:- return object_class.model_validate(raw_data)- except ValidationError as exc:- raise DryRunObjectFidelityError.for_object_class(object_class.__name__) from exc--class ContentGenerator(ContentGeneratorProtocol):def __init__(self, generated_content_factory: GeneratedContentFactory) -> None:self._generated_content_factory = generated_content_factory@@ -146,7 +100,7 @@ class ContentGenerator(ContentGeneratorProtocol):)raw_obj = await llm_gen_object(object_assignment=object_assignment, object_class=object_class)log.verbose(f"{self.__class__.__name__} generated object direct: {raw_obj}")- return _revalidate_against_object_class(raw_obj, object_class=object_class, is_mock_built=cogt_run_params.run_mode.is_dry)+ return revalidate_leaf_object(raw_obj, object_class=object_class, is_mock_built=cogt_run_params.run_mode.is_dry)@override@update_job_metadata@@ -173,10 +127,7 @@ class ContentGenerator(ContentGeneratorProtocol):)raw_list = await llm_gen_object_list(object_assignment=object_assignment, object_class=object_class)log.verbose(f"{self.__class__.__name__} generated object list direct: {raw_list}")- return [- _revalidate_against_object_class(raw_obj, object_class=object_class, is_mock_built=cogt_run_params.run_mode.is_dry)- for raw_obj in raw_list- ]+ return [revalidate_leaf_object(raw_obj, object_class=object_class, is_mock_built=cogt_run_params.run_mode.is_dry) for raw_obj in raw_list]@override@update_job_metadata@@ -347,17 +298,8 @@ class ContentGenerator(ContentGeneratorProtocol):output_structure_class: type[BaseModelTypeVar],search_assignment: SearchAssignment,) -> BaseModelTypeVar:- result_dict = await search_gen_structured(- search_object_assignment=SearchObjectAssignment.make_for_class(- output_class=output_structure_class,- search_assignment=search_assignment,- ),- )- # Same fidelity guard as the object paths (D6): a mock-built dict that fails re-validation- # against the original class is the known schema-round-trip gap, not a provider fault.- if not search_assignment.cogt_run_params.run_mode.is_dry:- return output_structure_class.model_validate(result_dict)- try:- return output_structure_class.model_validate(result_dict)- except ValidationError as exc:- raise DryRunObjectFidelityError.for_object_class(output_structure_class.__name__) from exc+ # In-process, so the caller's class travels down to the leaf exactly as it does on the object+ # paths, and comes back as an instance of itself — validated once, next to the provider. No+ # `SearchObjectAssignment` is built here: that wire model ships the class's schema across a+ # boundary, and this arm has none to cross.+ return await search_gen_structured_object(search_assignment, output_class=output_structure_class)diff --git a/pipelex/cogt/content_generation/dry_mock.py b/pipelex/cogt/content_generation/dry_mock.pyindex 2a44d85e7..268fa55ef 100644--- a/pipelex/cogt/content_generation/dry_mock.py+++ b/pipelex/cogt/content_generation/dry_mock.py@@ -39,6 +39,7 @@ from typing import Any, Protocolfrom polyfactory.exceptions import FactoryExceptionfrom pydantic import BaseModel, ValidationError+from pydantic.errors import PydanticInvalidForJsonSchemafrom pipelex import logfrom pipelex.cogt.content_generation.assignment_models import (@@ -53,7 +54,7 @@ from pipelex.cogt.content_generation.assignment_models import ()from pipelex.cogt.content_generation.cogt_run_params import CogtRunParamsfrom pipelex.cogt.content_generation.dry_run_factory import DryRunFactory-from pipelex.cogt.content_generation.exceptions import DryRunMockBuildError+from pipelex.cogt.content_generation.exceptions import DryRunMockBuildError, OutputStructureSchemaErrorfrom pipelex.cogt.content_generation.object_class_resolution import resolve_object_classfrom pipelex.cogt.content_generation.schema_to_model_factory import SchemaToModelFactoryfrom pipelex.cogt.llm.llm_job import LLMJob@@ -416,14 +417,59 @@ def dry_search_gen_sourced_answer(search_assignment: SearchAssignment) -> Searchdef dry_search_gen_structured(search_object_assignment: SearchObjectAssignment) -> dict[str, Any]:- """Dry leaf for structured search: schema-built mock dumped to a dict, no provider.-- Returns a raw dict (the leaf contract) which the submitter re-validates against the original- output structure class, matching the live path.+ """Dry leaf for structured search at the *boundary*: schema-built mock dumped to a dict, no provider.++ Returns a raw dict — the wire contract of the boundary arm — which the submitter re-validates+ against the original output structure class, matching the live path. The mock is built from the+ schema-reconstructed class, so an invariant the round trip drops surfaces there as+ ``DryRunObjectFidelityError``.++ ``by_alias=True`` keys the dict by the schema's property names, which is what the live arm returns+ (the provider answers the schema it was given) and what the original class accepts. Without it, a+ property the class rebuild had to rename — a python keyword, or a name shadowing a ``BaseModel``+ attribute — would come back under the renamed key and fail re-validation; see+ :func:`~pipelex.cogt.content_generation.object_revalidation.revalidate_leaf_object`."""log.verbose(f"🤡 DRY RUN: search_gen_structured for '{search_object_assignment.output_class_name}'")- output_class = SchemaToModelFactory.make_from_json_schema(+ boundary_class = SchemaToModelFactory.make_from_json_schema(schema=search_object_assignment.output_class_schema,class_name=search_object_assignment.output_class_name,)- return build_mock_object(output_class).model_dump(mode="json")+ return build_mock_object(boundary_class).model_dump(mode="json", by_alias=True)+++def dry_search_gen_structured_object(+ search_assignment: SearchAssignment,+ *,+ output_class: type[BaseModelTypeVar],+) -> BaseModelTypeVar:+ """Dry leaf for structured search *in-process*: a mock built from the caller's own class, no provider.++ Returns the instance rather than a dump of it, and that is load-bearing rather than a convenience:+ ``build_mock_object`` runs the caller's validators, so dumping the mock for the submitter to+ re-validate would run them a second time on data they already normalized — a transforming validator+ would produce ``INV-INV-…``, the very defect the object path's ``isinstance`` short-circuit exists to+ prevent, and no short-circuit can catch it once the instance has become a dict.++ Because the mock is built from the real class, an invariant the schema round trip would have dropped+ is present at build time, so an unsatisfiable one fails earlier and louder as ``DryRunMockBuildError``+ instead of surviving into the boundary arm's ``DryRunObjectFidelityError``.++ The schema check is here because carrying the class down took away the one that used to ride along+ for free: the in-process arm built a ``SearchObjectAssignment``, whose factory called+ ``model_json_schema()`` before any run-mode branch. Polyfactory is happy to mock a class pydantic+ cannot describe, so without an explicit check ``pipelex validate`` would pass a method whose live run+ dies inside the worker on a bare ``PydanticInvalidForJsonSchema`` — and the *boundary* arm still+ builds the assignment, so a dry-run verdict would depend on how the method is deployed.+ """+ _validate_schema_is_generable(output_class=output_class)+ log.verbose(f"🤡 DRY RUN: search_gen_structured_object for '{output_class.__name__}' ({search_assignment.search_handle})")+ return build_mock_object(output_class)+++def _validate_schema_is_generable(*, output_class: type[BaseModel]) -> None:+ """Prove the output class can describe itself as JSON Schema, which every structured leaf requires."""+ try:+ output_class.model_json_schema()+ except PydanticInvalidForJsonSchema as exc:+ raise OutputStructureSchemaError.for_object_class(object_class_name=output_class.__name__, reason=str(exc)) from excdiff --git a/pipelex/cogt/content_generation/exceptions.py b/pipelex/cogt/content_generation/exceptions.pyindex eccaf65e7..56d6adb84 100644--- a/pipelex/cogt/content_generation/exceptions.py+++ b/pipelex/cogt/content_generation/exceptions.py@@ -42,6 +42,38 @@ class DryRunObjectFidelityError(PipelexError):)+class OutputStructureSchemaError(PipelexError):+ """Raised when an output structure class cannot produce the JSON schema a structured leaf needs.++ Every structured leaf ultimately describes the caller's output class to a provider as JSON Schema, so+ a class pydantic cannot describe cannot drive one — an ``arbitrary_types_allowed`` field, or an opaque+ type carrying only ``__get_pydantic_core_schema__``, makes ``model_json_schema()`` raise.++ The dry run has to be the place that says so. Polyfactory will happily mock such a class, so nothing+ else on the dry path notices, and pydantic's own ``PydanticInvalidForJsonSchema`` is a bare+ ``RuntimeError``: raised live, inside the worker, it carries no model attribution, no remedy and no+ error identity. Surfacing it here turns a mid-run crash into a ``pipelex validate`` failure that names+ the class.+ """++ # The caller's output concept uses a type pydantic cannot describe as JSON Schema; they fix it by+ # changing the field or teaching the type `__get_pydantic_json_schema__` — caller-fixable input.+ error_domain = ErrorDomain.INPUT+ # The message names the caller's own output concept class and the remedy, with no internal paths or+ # secrets, so it should survive STRICT disclosure intact.+ _authors_caller_facing_message = True++ @classmethod+ def for_object_class(cls, *, object_class_name: str, reason: str) -> "OutputStructureSchemaError":+ """Build the schema error for a named output object class (e.g. ``"InvoiceLine"``)."""+ return cls(+ f"The output structure '{object_class_name}' cannot produce a JSON schema, so it cannot be used as a "+ f"structured output: {reason}. Every structured leaf describes your output class to the provider as "+ "JSON Schema. Replace the field whose type pydantic cannot describe, or give that type a "+ "`__get_pydantic_json_schema__`."+ )++class DryRunMockBuildError(PipelexError):"""Raised when building a leaf mock object fails (polyfactory build or model validation).diff --git a/pipelex/cogt/content_generation/object_class_resolution.py b/pipelex/cogt/content_generation/object_class_resolution.pyindex 904a10cd6..ff9b65811 100644--- a/pipelex/cogt/content_generation/object_class_resolution.py+++ b/pipelex/cogt/content_generation/object_class_resolution.py@@ -11,6 +11,10 @@ In-process there is no boundary: the caller's real class is still on the stack,beside the assignment and is used as-is. ``None`` means "no class in hand", which is exactly what aworker entering from the boundary passes — so the distributed path keeps today's behaviour byconstruction, with no flag to set.++The structured-*search* leaf has no nullable arm to resolve: its in-process entry point carries the+caller's class outright, and its boundary arm always rebuilds — it calls ``SchemaToModelFactory``+directly."""from pydantic import BaseModeldiff --git a/pipelex/cogt/content_generation/object_revalidation.py b/pipelex/cogt/content_generation/object_revalidation.pynew file mode 100644index 000000000..56f7582a3--- /dev/null+++ b/pipelex/cogt/content_generation/object_revalidation.py@@ -0,0 +1,105 @@+"""Convert a structured-generation leaf's result into the caller's own class.++The return leg of :mod:`.object_class_resolution`: that module decides which class travels *down* to+the provider, this one decides what comes back *up* to the caller. Both implementations of+``ContentGeneratorProtocol`` need it — the in-process generator here and the workflow arm of our+distributed-execution plugin, which lives in another repo and so cannot reach a ``_``-private helper.+That is why these are public: one home for the ``isinstance``-not-``type`` reasoning and for the dry-run+fidelity-error contract, instead of two copies that only agree until someone edits one.++The two entry points differ by what the leaf handed back: an object (the LLM leaves) or already+serialized data (the structured-search leaf, whose dict-out contract is what keeps a dynamic class+off a distributed orchestrator's wire).+"""++from typing import Any, Literal++from pydantic import BaseModel, ValidationError++from pipelex.cogt.content_generation.exceptions import DryRunObjectFidelityError+from pipelex.tools.typing.pydantic_utils import BaseModelTypeVar+++def revalidate_leaf_object(+ raw_obj: BaseModel,+ *,+ object_class: type[BaseModelTypeVar],+ is_mock_built: bool,+ dump_mode: Literal["json", "python"] = "python",+) -> BaseModelTypeVar:+ """Convert a leaf-generated object into ``object_class``, unless it already is one.++ On the in-process path the leaf worked from ``object_class``, so the object is already one — note+ ``isinstance``, not ``type(...) is``: instructor does not hand back the class you gave it, it hands+ back ``create_model(cls.__name__, __base__=(cls, OpenAISchema))``, a *subclass*. Either way it needs+ no conversion — and re-validating it would run the caller's validators a **second** time, on data+ they already normalized. A validator that transforms rather than merely rejects (``f"INV-{value}"``, a+ list that gets a default appended) would corrupt its own output, and one that asserts its input is+ not yet normalized would reject valid provider output. Returning it untouched is what makes the+ caller's validator constrain the provider exactly once, which is the whole point of handing the live+ class down.++ The conversion is still needed at the *boundary*: a leaf that ran on a worker holding only the+ serialized assignment returns a plain ``BaseModel`` reconstructed from the JSON schema — never a+ subclass of ``object_class`` — so re-validating its data makes the result the proper subtype (e.g.+ ``StructuredContent``) the caller expects. The short-circuit never fires there today, and carrying it+ anyway is the point of sharing this: a boundary that ever *does* hand back the caller's real class+ (a local activity, an in-process shortcut, a converter change) cannot silently reinstate the double+ validation.++ ``by_alias=True`` is load-bearing, not cosmetic. The object being converted was built from+ ``object_class.model_json_schema()``, which pydantic emits **by alias**, so the schema's property+ names are what ``object_class`` accepts on the way back in. The rebuilt class does not always name+ its fields that way: ``datamodel-code-generator`` renames any property that is not a usable field+ name — a python keyword, or a name shadowing a ``BaseModel`` attribute (``json``, ``copy``,+ ``schema``, ``construct``) — and records the original as an alias. Dumping by field name then emits+ ``construct_`` for a field ``object_class`` calls ``construct``, and re-validation fails with a bare+ "Field required". Dumping by alias emits exactly the schema's property names, which is what the whole+ round trip is keyed on. Where nothing was renamed the alias *is* the field name, so this changes+ nothing for the models that were already fine.++ ``dump_mode`` is the one thing the two boundaries genuinely disagree on. It is+ :meth:`~pydantic.BaseModel.model_dump`'s own mode: an object that crossed a distributed+ orchestrator's payload boundary needs ``"json"``, because some field types only round-trip cleanly+ through their json form. In-process the default ``"python"`` is deliberate and must stay: json mode+ coerces values (``datetime`` → ``str`` and back), and there is no reason to pay that on a path that+ never left the process.++ ``is_mock_built`` carries the dry-run fidelity contract — see :func:`revalidate_leaf_data`.+ """+ if isinstance(raw_obj, object_class):+ return raw_obj+ return revalidate_leaf_data(+ raw_obj.model_dump(mode=dump_mode, serialize_as_any=True, by_alias=True),+ object_class=object_class,+ is_mock_built=is_mock_built,+ )+++def revalidate_leaf_data(+ raw_data: dict[str, Any],+ *,+ object_class: type[BaseModelTypeVar],+ is_mock_built: bool,+) -> BaseModelTypeVar:+ """Validate already-serialized leaf data into ``object_class``, with the dry-run fidelity guard.++ Data is never an instance of anything, so there is no short-circuit to make: this validation is the+ single one on its path, and the caller's validators run here exactly once.++ Under the dry-run leaf mock (``run_mode=DRY``) the data was built from a class reconstructed from the+ JSON schema, which can drop invariants the original class enforces (custom validators,+ ``json_schema_extra`` format/pattern hints datamodel-code-generator omits on round-trip), so+ polyfactory can fill a value the reconstructed class accepts but the original rejects. Set+ ``is_mock_built`` on that path and the ``ValidationError`` is re-raised as a clear typed+ :class:`DryRunObjectFidelityError` naming the class and the ``examples`` / ``mock_format`` remedy.+ That gap cannot occur when the mock was built from the real class — an unsatisfiable invariant fails+ earlier and louder, as ``DryRunMockBuildError`` out of ``build_mock_object``. The guard is scoped to+ the dry path only: a LIVE provider's invalid output keeps its existing ``ValidationError``.+ """+ try:+ return object_class.model_validate(raw_data)+ except ValidationError as exc:+ if is_mock_built:+ raise DryRunObjectFidelityError.for_object_class(object_class.__name__) from exc+ raisediff --git a/pipelex/cogt/content_generation/search_generate.py b/pipelex/cogt/content_generation/search_generate.pyindex 17b211f25..c28ffd22f 100644--- a/pipelex/cogt/content_generation/search_generate.py+++ b/pipelex/cogt/content_generation/search_generate.py@@ -6,12 +6,25 @@ worker from the model handle, and run it. The direct ``ContentGenerator`` calls``act_search_*`` activity calls them inside an activity so the result is recorded in workflow history andany failure is converted to a terminal ``ApplicationError`` (instead of running inline on the workflowloop, which left search failures hanging the submitter — see ``wip/`` brief).++The structured search has two entry points rather than one nullable parameter, because its two arms+genuinely return different things: in-process the caller's class travels down and an instance of it+comes back; at the boundary only the schema is available and the raw dict stays on the wire. Only the+boundary arm takes the ``SearchObjectAssignment`` wire model — in-process nothing crosses a boundary,+so there is no schema to ship and the plain ``SearchAssignment`` travels beside the class itself."""from typing import Any+from pydantic import BaseModel+from pipelex.cogt.content_generation.assignment_models import SearchAssignment, SearchObjectAssignment-from pipelex.cogt.content_generation.dry_mock import dry_search_gen_sourced_answer, dry_search_gen_structured+from pipelex.cogt.content_generation.dry_mock import (+ dry_search_gen_sourced_answer,+ dry_search_gen_structured,+ dry_search_gen_structured_object,+)+from pipelex.cogt.content_generation.object_revalidation import revalidate_leaf_datafrom pipelex.cogt.content_generation.schema_to_model_factory import SchemaToModelFactoryfrom pipelex.cogt.model_backends.model_type import ModelTypefrom pipelex.cogt.search.search_job import SearchJob@@ -20,6 +33,7 @@ from pipelex.cogt.search.search_worker_abstract import SearchWorkerAbstractfrom pipelex.cogt.search.search_worker_factory import SearchWorkerFactoryfrom pipelex.core.stuffs.search_result_content import SearchResultContentfrom pipelex.runtime_hub import get_model_deck, get_report_delegate+from pipelex.tools.typing.pydantic_utils import BaseModelTypeVardef _make_search_worker(search_assignment: SearchAssignment) -> SearchWorkerAbstract:@@ -52,19 +66,54 @@ async def search_gen_sourced_answer(search_assignment: SearchAssignment) -> Searasync def search_gen_structured(search_object_assignment: SearchObjectAssignment) -> dict[str, Any]:- """Run a structured search, returning the raw result dict.+ """Run a structured search at the *boundary*, returning the raw result dict.- The dict is re-validated against the original output structure class by the submitter- (``ContentGenerator`` / ``ContentGeneratorInWorkflow``) — that step is pure and deterministic,- which sidesteps shipping a dynamic output class across the Temporal boundary.+ This is the arm a worker enters with only the serialized assignment in hand: no class can travel to+ it, so the output structure is rebuilt from the JSON schema, and the result stays a dict — which is+ what keeps a dynamic class off a distributed orchestrator's wire. The submitter re-validates that+ dict against the original class, a step that is pure and deterministic.++ In-process, call :func:`search_gen_structured_object` instead: the caller's real class is still on+ the stack, and handing it down is what keeps its validators and schema hints from being lost."""search_assignment = search_object_assignment.search_assignmentif search_assignment.cogt_run_params.run_mode.is_dry:return dry_search_gen_structured(search_object_assignment)- worker = _make_search_worker(search_assignment)- search_job = _make_search_job(search_assignment)- output_class = SchemaToModelFactory.make_from_json_schema(+ boundary_class = SchemaToModelFactory.make_from_json_schema(schema=search_object_assignment.output_class_schema,class_name=search_object_assignment.output_class_name,)- return await worker.search_structured(search_job=search_job, schema=output_class)+ return await _run_structured_search(search_assignment, schema=boundary_class)+++async def search_gen_structured_object(+ search_assignment: SearchAssignment,+ *,+ output_class: type[BaseModelTypeVar],+) -> BaseModelTypeVar:+ """Run a structured search *in-process*, returning an instance of the caller's own output class.++ The class travels down to the provider unchanged, so the search is constrained by the schema the+ caller actually wrote — its custom validators are reflected in the hints and description the schema+ carries, rather than being erased by a JSON-schema rebuild. No ``SearchObjectAssignment`` is built+ on this arm: that wire model exists to ship the schema across a boundary, and here there is none.++ Returns an instance rather than a dict because the validation belongs here, next to the provider:+ doing it once at the leaf is what stops the caller's validators running a second time in the+ submitter. The two arms of this module therefore differ in return type on purpose — a dict is the+ wire's shape, an instance is the caller's.+ """+ if search_assignment.cogt_run_params.run_mode.is_dry:+ return dry_search_gen_structured_object(search_assignment, output_class=output_class)+ result_dict = await _run_structured_search(search_assignment, schema=output_class)+ # ``is_mock_built=False`` is a statement, not a formality: this data came from the provider, so a+ # failure here is a malformed response and keeps its ``ValidationError`` — it is not the dry-run+ # schema-round-trip gap, which cannot arise on an arm that never rebuilt the class.+ return revalidate_leaf_data(result_dict, object_class=output_class, is_mock_built=False)+++async def _run_structured_search(search_assignment: SearchAssignment, *, schema: type[BaseModel]) -> dict[str, Any]:+ """Resolve the worker and run the provider call — the part both arms share."""+ worker = _make_search_worker(search_assignment)+ search_job = _make_search_job(search_assignment)+ return await worker.search_structured(search_job=search_job, schema=schema)diff --git a/pipelex/cogt/search/search_worker_abstract.py b/pipelex/cogt/search/search_worker_abstract.pyindex 08c903a56..e8b2a27a3 100644--- a/pipelex/cogt/search/search_worker_abstract.py+++ b/pipelex/cogt/search/search_worker_abstract.py@@ -43,10 +43,16 @@ class SearchWorkerAbstract(InferenceWorkerAbstract):except CogtError as exc:exc.fill_model_and_provider(model_handle=self.inference_model.name, backend_name=self.inference_model.backend_name)raise-- search_job.search_job_after_complete()- if self.reporting_delegate:- self.reporting_delegate.report_inference_job(inference_job=search_job)+ finally:+ # Completion and reporting belong on *every* way out, not just the happy one. A backend's+ # response-shape guard raises after the provider already answered and after usage was+ # recorded, so that call is billed — reporting only on success would make the spend vanish+ # from the run's cost report. A failure that never reached the provider recorded no tokens+ # (`search_job_before_start` initialises `nb_tokens_by_category` empty), so it reports as the+ # zero-cost attempt it was rather than inventing a charge.+ search_job.search_job_after_complete()+ if self.reporting_delegate:+ self.reporting_delegate.report_inference_job(inference_job=search_job)return result@@ -67,10 +73,13 @@ class SearchWorkerAbstract(InferenceWorkerAbstract):except CogtError as exc:exc.fill_model_and_provider(model_handle=self.inference_model.name, backend_name=self.inference_model.backend_name)raise-- search_job.search_job_after_complete()- if self.reporting_delegate:- self.reporting_delegate.report_inference_job(inference_job=search_job)+ finally:+ # Reported on every way out, for the reason spelled out in `search_sourced_answer` — and it+ # bites hardest here, because this arm is the one whose response-shape guards reject a+ # payload the provider already charged for.+ search_job.search_job_after_complete()+ if self.reporting_delegate:+ self.reporting_delegate.report_inference_job(inference_job=search_job)return resultdiff --git a/pipelex/cogt/search/structured_search_payload.py b/pipelex/cogt/search/structured_search_payload.pynew file mode 100644index 000000000..5b256cb0b--- /dev/null+++ b/pipelex/cogt/search/structured_search_payload.py@@ -0,0 +1,60 @@+"""Extract the payload a structured search owes its leaf, whatever envelope it arrived in.++A structured search's contract is the structured payload alone: the leaf validates it against the+caller's output structure class, which has nowhere to put sources. But Linkup answers a structured+search *with* sources as a ``{data, sources}`` envelope, and whether the envelope arrives is a+provider-side flag — set directly on the direct backend, set by the relay on the gateway backend.++Neither backend can therefore assume its own request shape decided the response shape:++- the direct backend asks for ``include_sources=False`` and expects the bare payload, but a provider+ that ignores the flag would hand back the envelope, and validating an envelope against an output+ class whose fields all have defaults succeeds *silently* — pydantic's default ``extra="ignore"``+ drops ``data`` and ``sources`` and returns an all-defaults object. Silent wrong answers, no error;+- the gateway backend's relay asks for sources today and so returns the envelope, but the moment it+ stops, a worker that demands the envelope rejects every search — a two-sided deploy hazard.++Recognising the envelope *structurally* removes both. A response is the envelope only when it carries+exactly ``data`` and ``sources`` **and** the caller's own output structure does not declare those two+names itself — that last clause is what stops a legitimate ``{data, sources}`` output class from being+unwrapped into its own sub-object.+"""++from typing import Any, cast++from pydantic import BaseModel++_ENVELOPE_KEYS = frozenset({"data", "sources"})+++def extract_structured_search_payload(*, response: Any, schema: type[BaseModel]) -> dict[str, Any] | None:+ """Return the structured payload to hand the leaf, or ``None`` when the response carries none.++ ``None`` covers two cases the caller can still tell apart from ``response`` itself, because they+ deserve different advice: a response that is not a JSON object at all (malformed — the model is the+ suspect), and an envelope whose ``data`` is null or not an object (the search simply found nothing+ to fill the output structure with — the query is the suspect).+ """+ if not isinstance(response, dict):+ return None+ payload = cast("dict[str, Any]", response)+ if not _is_sources_envelope(payload=payload, schema=schema):+ return payload+ data = payload["data"]+ if not isinstance(data, dict):+ return None+ return cast("dict[str, Any]", data)+++def _is_sources_envelope(*, payload: dict[str, Any], schema: type[BaseModel]) -> bool:+ """Whether this object is Linkup's sources envelope rather than the structured payload itself.++ Field names *and* aliases are checked because the response is keyed by the schema's property names,+ which pydantic emits by alias — so an output structure that reaches the wire as ``{data, sources}``+ must be recognised as its own payload whichever way it spells those fields in Python.+ """+ if frozenset(payload) != _ENVELOPE_KEYS:+ return False+ declared = set(schema.model_fields)+ declared.update(field.alias for field in schema.model_fields.values() if field.alias)+ return not _ENVELOPE_KEYS.issubset(declared)diff --git a/pipelex/providers/gateway/gateway_exceptions.py b/pipelex/providers/gateway/gateway_exceptions.pyindex 3228bf203..a448666ac 100644--- a/pipelex/providers/gateway/gateway_exceptions.py+++ b/pipelex/providers/gateway/gateway_exceptions.py@@ -23,3 +23,7 @@ class GatewayExtractResponseError(GatewayError):class GatewaySearchResponseError(GatewayError):pass+++class GatewaySearchEmptyResultError(GatewayError):+ passdiff --git a/pipelex/providers/gateway/gateway_search_worker.py b/pipelex/providers/gateway/gateway_search_worker.pyindex 2d9fb0ebd..15a9cb4ce 100644--- a/pipelex/providers/gateway/gateway_search_worker.py+++ b/pipelex/providers/gateway/gateway_search_worker.py@@ -15,11 +15,12 @@ from pipelex.cogt.model_backends.model_spec import InferenceModelSpecfrom pipelex.cogt.search.search_depth import SearchDepthfrom pipelex.cogt.search.search_job import SearchJobfrom pipelex.cogt.search.search_worker_abstract import SearchWorkerAbstract+from pipelex.cogt.search.structured_search_payload import extract_structured_search_payloadfrom pipelex.cogt.usage.token_category import NbTokensByCategoryDict, TokenCategoryfrom pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.core.stuffs.search_result_content import SearchResultContentfrom pipelex.providers.gateway.gateway_deck import GatewayDeck-from pipelex.providers.gateway.gateway_exceptions import GatewaySearchResponseError+from pipelex.providers.gateway.gateway_exceptions import GatewaySearchEmptyResultError, GatewaySearchResponseErrorfrom pipelex.providers.gateway.gateway_search_schemas import GatewaySearchRequestParamsfrom pipelex.reporting.reporting_protocol import ReportingProtocolfrom pipelex.tools.typing.pydantic_utils import BaseModelTypeVar@@ -70,7 +71,19 @@ class GatewaySearchWorker(SearchWorkerAbstract):self._extract_usage(response=response, search_job=search_job)content_str = self._extract_content(response)- result_dict: dict[str, Any] = json.loads(content_str)+ relay_result = self._decode_relay_json(content_str=content_str)+ if not isinstance(relay_result, dict):+ msg = f"Gateway sourced-answer search returned a non-object payload of type '{type(relay_result).__name__}'"+ raise GatewaySearchResponseError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CHANGE_MODEL,+ detail="The Gateway returned a malformed search response — try a different model",+ ),+ provider_metadata=None,+ )+ result_dict = cast("dict[str, Any]", relay_result)sources = [DocumentContent(@@ -122,8 +135,60 @@ class GatewaySearchWorker(SearchWorkerAbstract):self._extract_usage(response=response, search_job=search_job)content_str = self._extract_content(response)- result: dict[str, Any] = json.loads(content_str)- return result+ relay_result = self._decode_relay_json(content_str=content_str)+ # The relay asks Linkup for sources alongside the structured payload, so its wire shape is a+ # {data, sources} envelope — but the contract of a structured search is the payload alone: it is+ # validated against the caller's output structure class, which has nowhere to put sources.+ # The envelope is recognised *structurally* rather than demanded: the day the relay stops asking+ # for sources, this worker keeps working on the bare payload it then returns, so the two repos do+ # not have to deploy in lockstep. Demanding it would make that a coordinated two-sided change.+ payload = extract_structured_search_payload(response=relay_result, schema=schema)+ if payload is not None:+ return payload+ if isinstance(relay_result, dict):+ # The response was an object but carried no structured payload: the search ran and found+ # nothing to fill the output structure with. That is the query's fault, not the model's.+ msg = "Gateway structured search returned an empty structured result"+ raise GatewaySearchEmptyResultError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CHANGE_INPUT,+ detail="The search found nothing to fill your output structure — try a broader query or a wider date range",+ ),+ provider_metadata=None,+ )+ msg = f"Gateway structured search returned a non-object payload of type '{type(relay_result).__name__}'"+ raise GatewaySearchResponseError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CHANGE_MODEL,+ detail="The Gateway returned a malformed structured search response — try a different model",+ ),+ provider_metadata=None,+ )++ def _decode_relay_json(self, *, content_str: str) -> Any:+ """Parse the relay's JSON content, classifying a malformed body instead of letting it escape raw.++ A relay answering with something that is not JSON is the likeliest way its contract breaks, and a+ bare ``JSONDecodeError`` is neither a ``CogtError`` nor annotated with the model — so it would slip+ past exactly the classification the rest of this path exists to provide.+ """+ try:+ return json.loads(content_str)+ except json.JSONDecodeError as exc:+ msg = "Gateway search response body is not valid JSON"+ raise GatewaySearchResponseError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CHANGE_MODEL,+ detail="The Gateway returned a malformed search response — try a different model",+ ),+ provider_metadata=None,+ ) from excdef _extract_usage(self, response: GenericResponse, *, search_job: SearchJob) -> None:"""Extract token usage from the GenericResponse and populate the search job report."""diff --git a/pipelex/providers/linkup/linkup_exceptions.py b/pipelex/providers/linkup/linkup_exceptions.pynew file mode 100644index 000000000..d1d1e10ee--- /dev/null+++ b/pipelex/providers/linkup/linkup_exceptions.py@@ -0,0 +1,13 @@+from pipelex.cogt.exceptions import CogtError+++class LinkupError(CogtError):+ """Base for every error this backend raises, so callers can catch the provider as a family."""+++class LinkupSearchResponseError(LinkupError):+ """The Linkup API answered a structured search with a payload shape the leaf cannot validate."""+++class LinkupSearchEmptyResultError(LinkupError):+ """The Linkup API answered a structured search with no object payload to fill the output structure."""diff --git a/pipelex/providers/linkup/linkup_search_worker.py b/pipelex/providers/linkup/linkup_search_worker.pyindex 77f069e38..4515d9e2e 100644--- a/pipelex/providers/linkup/linkup_search_worker.py+++ b/pipelex/providers/linkup/linkup_search_worker.py@@ -1,3 +1,4 @@+import jsonfrom datetime import datefrom typing import Any@@ -14,16 +15,19 @@ from linkup import ()from typing_extensions import override-from pipelex.cogt.inference.error_classification import extract_linkup_metadata+from pipelex.cogt.exceptions import InferenceErrorCategory+from pipelex.cogt.inference.error_classification import UserAction, UserActionKind, extract_linkup_metadatafrom pipelex.cogt.inference.error_classify import classify_inference_errorfrom pipelex.cogt.inference.error_render import InferenceErrorFamily, render_inference_errorfrom pipelex.cogt.model_backends.model_spec import InferenceModelSpecfrom pipelex.cogt.search.search_depth import SearchDepthfrom pipelex.cogt.search.search_job import SearchJobfrom pipelex.cogt.search.search_worker_abstract import SearchWorkerAbstract+from pipelex.cogt.search.structured_search_payload import extract_structured_search_payloadfrom pipelex.cogt.usage.token_category import TokenCategoryfrom pipelex.core.stuffs.document_content import DocumentContentfrom pipelex.core.stuffs.search_result_content import SearchResultContent+from pipelex.providers.linkup.linkup_exceptions import LinkupSearchEmptyResultError, LinkupSearchResponseErrorfrom pipelex.reporting.reporting_protocol import ReportingProtocolfrom pipelex.runtime_hub import get_secrets_providerfrom pipelex.tools.typing.pydantic_utils import BaseModelTypeVar@@ -116,20 +120,27 @@ class LinkupSearchWorker(SearchWorkerAbstract):job_params = search_job.job_paramssearch_setting = job_params.search_setting+ # The schema crosses as a JSON string, which is byte-for-byte what the SDK puts on the wire when+ # handed the class itself. Handing it the class would *also* make it instantiate that class from+ # the response — running the caller's validators inside the SDK, and then again when the leaf+ # validates the dict this returns. Serializing the schema here keeps the response raw and the+ # validation single, at the leaf, where the run mode and the fidelity contract live.+ schema_json = json.dumps(schema.model_json_schema())+depth_value = SearchDepth(self.inference_model.model_id.rsplit("/", 1)[-1])try:response = await self._linkup_client.async_search(query=search_job.query,depth=depth_value, # type: ignore[arg-type] # pyright: ignore[reportArgumentType]output_type="structured",- structured_output_schema=schema,+ structured_output_schema=schema_json,include_images=search_setting.include_images,max_results=search_setting.max_results,include_domains=job_params.include_domains,exclude_domains=job_params.exclude_domains,from_date=self._parse_date(job_params.from_date),to_date=self._parse_date(job_params.to_date),- include_sources=True,+ include_sources=False,)except (LinkupAuthenticationError,@@ -154,8 +165,40 @@ class LinkupSearchWorker(SearchWorkerAbstract):if search_tokens_usage := search_job.job_report.search_tokens_usage:search_tokens_usage.nb_tokens_by_category = {TokenCategory.INPUT: 1_000_000, TokenCategory.OUTPUT: 1_000_000}- # If response is a Pydantic model, convert to dict- if hasattr(response, "model_dump"):- result: dict[str, Any] = response.model_dump()- return result- return dict(response) # type: ignore[arg-type]+ # The contract of a structured search is the structured payload itself — it is validated against+ # the caller's output structure class, which has nowhere to put sources. Asking for them wraps the+ # payload in a {data, sources} envelope no output class could accept, so this asks for the payload+ # alone — but it does not *trust* that flag. A provider that ignored it would hand back the+ # envelope, and an output structure whose fields all carry defaults validates that envelope+ # *silently* into an all-defaults object (pydantic's default `extra="ignore"` drops both keys), so+ # the failure would be wrong answers rather than an error. The extractor recognises the envelope+ # structurally instead, which is also what lets both backends share one rule.+ # The schema crossed as a string, so the SDK did no validation of its own: `response` is the+ # provider's JSON verbatim, typed `Any`.+ payload = extract_structured_search_payload(response=response, schema=schema)+ if payload is not None:+ return payload+ if isinstance(response, dict):+ # The envelope was there but carried no object payload: the search ran and found nothing to+ # fill the output structure with. That is the query's fault, not the model's — advising a+ # model change here would send the user after the wrong thing.+ msg = "Linkup structured search returned an empty structured result"+ raise LinkupSearchEmptyResultError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CHANGE_INPUT,+ detail="The search found nothing to fill your output structure — try a broader query or a wider date range",+ ),+ provider_metadata=None,+ )+ msg = f"Linkup structured search returned a non-object payload of type '{type(response).__name__}'"+ raise LinkupSearchResponseError(+ msg,+ error_category=InferenceErrorCategory.UNKNOWN,+ user_action=UserAction(+ kind=UserActionKind.CHANGE_MODEL,+ detail="Linkup returned a malformed structured search response — try a different model",+ ),+ provider_metadata=None,+ )diff --git a/subject_grants.toml b/subject_grants.tomlindex 2f8d7c1e1..0ee2ea4b6 100644--- a/subject_grants.toml+++ b/subject_grants.toml@@ -1264,10 +1264,6 @@ rationale = "Factory from source: builds the result from the object_class; singlparam = "output_class"rationale = "Factory from source: builds the result from the output_class; single operand."-["pipelex/cogt/content_generation/content_generator.py::_revalidate_against_object_class"]-param = "raw_obj"-rationale = "Consumes the raw_obj; single operand."-["pipelex/cogt/content_generation/content_generator_protocol.py::ContentGeneratorProtocol.make_search_sourced_answer"]param = "search_assignment"rationale = "Factory from source: builds the result from the search_assignment; single operand."@@ -1336,6 +1332,10 @@ rationale = "Consumes the search_assignment; single operand."param = "search_object_assignment"rationale = "Consumes the search_object_assignment; single operand."+["pipelex/cogt/content_generation/dry_mock.py::dry_search_gen_structured_object"]+param = "search_assignment"+rationale = "Worker verb–object: processes the search_assignment; single operand."+["pipelex/cogt/content_generation/dry_mock.py::dry_templating_gen_text"]param = "templating_assignment"rationale = "Consumes the templating_assignment; single operand."@@ -1456,6 +1456,14 @@ rationale = "Processes the object assignment; single operand."param = "llm_assignment"rationale = "Processes the LLM assignment; single operand."+["pipelex/cogt/content_generation/object_revalidation.py::revalidate_leaf_data"]+param = "raw_data"+rationale = "Consumes the raw_data the leaf returned; single operand."++["pipelex/cogt/content_generation/object_revalidation.py::revalidate_leaf_object"]+param = "raw_obj"+rationale = "Consumes the raw_obj the leaf returned; single operand."+["pipelex/cogt/content_generation/render_generate.py::render_page_views_and_store"]param = "render_assignment"rationale = "Transforms/renders the render_assignment; single operand."@@ -1500,6 +1508,10 @@ rationale = "Factory from source: builds the result from the search_assignment;param = "search_assignment"rationale = "Factory from source: builds the result from the search_assignment; single operand."+["pipelex/cogt/content_generation/search_generate.py::_run_structured_search"]+param = "search_assignment"+rationale = "Worker verb–object: processes the search_assignment; single operand."+["pipelex/cogt/content_generation/search_generate.py::search_gen_sourced_answer"]param = "search_assignment"rationale = "Worker verb–object: processes the search_assignment; single operand."@@ -1508,6 +1520,10 @@ rationale = "Worker verb–object: processes the search_assignment; single operaparam = "search_object_assignment"rationale = "Worker verb–object: processes the search_object_assignment; single operand."+["pipelex/cogt/content_generation/search_generate.py::search_gen_structured_object"]+param = "search_assignment"+rationale = "Worker verb–object: processes the search_assignment; single operand."+["pipelex/cogt/content_generation/templating_generate.py::templating_gen_text"]param = "templating_assignment"rationale = "Processes the templating assignment; single operand."diff --git a/tests/data/errors/error_identity.txt b/tests/data/errors/error_identity.txtindex 788a312cd..340fb3f45 100644--- a/tests/data/errors/error_identity.txt+++ b/tests/data/errors/error_identity.txt@@ -98,6 +98,7 @@ GatewayDoNotTrackConflictError | Gateway do not track conflict | https://docs.piGatewayError | Gateway | https://docs.pipelex.com/latest/errors/gateway-error/GatewayExtractResponseError | Gateway extract response | https://docs.pipelex.com/latest/errors/gateway-extract-response-error/GatewayFactoryError | Gateway factory | https://docs.pipelex.com/latest/errors/gateway-factory-error/+GatewaySearchEmptyResultError | Gateway search empty result | https://docs.pipelex.com/latest/errors/gateway-search-empty-result-error/GatewaySearchResponseError | Gateway search response | https://docs.pipelex.com/latest/errors/gateway-search-response-error/GatewayTelemetryManagerInjectedError | Gateway telemetry manager injected | https://docs.pipelex.com/latest/errors/gateway-telemetry-manager-injected-error/GatewayTermsNotAcceptedError | Gateway terms not accepted | https://docs.pipelex.com/latest/errors/gateway-terms-not-accepted-error/@@ -149,6 +150,9 @@ LLMSettingsValidationError | LLM settings validation | https://docs.pipelex.com/LangfuseCredentialsError | Langfuse credentials | https://docs.pipelex.com/latest/errors/langfuse-credentials-error/LibraryError | Library error | https://docs.pipelex.com/latest/errors/library-error/LibraryLoadingError | Library loading | https://docs.pipelex.com/latest/errors/library-loading-error/+LinkupError | Linkup | https://docs.pipelex.com/latest/errors/linkup-error/+LinkupSearchEmptyResultError | Linkup search empty result | https://docs.pipelex.com/latest/errors/linkup-search-empty-result-error/+LinkupSearchResponseError | Linkup search response | https://docs.pipelex.com/latest/errors/linkup-search-response-error/ListWhereSingularError | List where singular | https://docs.pipelex.com/latest/errors/list-where-singular-error/MissingBundleValidatorError | Missing bundle validator | https://docs.pipelex.com/latest/errors/missing-bundle-validator-error/MissingDependencyError | Missing dependency | https://docs.pipelex.com/latest/errors/missing-dependency-error/@@ -176,6 +180,7 @@ NestedKeyConflictError | Nested key conflict | https://docs.pipelex.com/latest/eNullInputError | Null input | https://docs.pipelex.com/latest/errors/null-input-error/OpenAIClientFactoryError | OpenAI client factory error | https://docs.pipelex.com/latest/errors/open-ai-client-factory-error/OptionalValueAbsentError | Optional value absent | https://docs.pipelex.com/latest/errors/optional-value-absent-error/+OutputStructureSchemaError | Output structure schema | https://docs.pipelex.com/latest/errors/output-structure-schema-error/PipeBatchFactoryError | Pipe batch factory | https://docs.pipelex.com/latest/errors/pipe-batch-factory-error/PipeComposeError | Pipe compose | https://docs.pipelex.com/latest/errors/pipe-compose-error/PipeComposeFactoryError | Pipe compose factory | https://docs.pipelex.com/latest/errors/pipe-compose-factory-error/diff --git a/tests/integration/pipelex/cogt/content_generation/test_boundary_roundtrip_fidelity.py b/tests/integration/pipelex/cogt/content_generation/test_boundary_roundtrip_fidelity.pynew file mode 100644index 000000000..45ae2e65b--- /dev/null+++ b/tests/integration/pipelex/cogt/content_generation/test_boundary_roundtrip_fidelity.py@@ -0,0 +1,125 @@+"""What survives the boundary's rebuild → dump → validate round trip, over the models that actually cross it.++The boundary arm of `revalidate_leaf_object` converts a leaf result that was built from a class+*reconstructed from JSON schema* back into the caller's own class. That round trip is not+identity-preserving in general, and the audit behind this module found exactly one way it loses:++**A property the rebuild had to rename comes back under the renamed key.** `datamodel-code-generator`+cannot name a field `json`, `copy`, `schema` or `construct` — they shadow `BaseModel` attributes — so it+names it `json_` and records `json` as the alias. Dumping by field name then emits a key the original+class has never heard of, and re-validation fails with a bare "Field required" on a field the caller did+supply. Dumping by alias emits the schema's own property names, which is what both the round trip and+the provider are keyed on.++The rest of the audit's suspects turned out to be safe, and each has a test here so they stay that way:+plain aliases (the schema is emitted by alias, so the rebuilt field name *is* the alias), nested models+and lists, and `extra="allow"` components. Subclass erasure is unreachable rather than safe — the+rebuilt class is derived from the original's own schema, so it cannot carry a field the original lacks —+which is why there is no test for it: there is no way to construct the case through this path.++No provider and no worker are involved, so this needs no inference marker.+"""++from typing import Any, Literal++import pytest+from pydantic import BaseModel, Field++from pipelex.cogt.content_generation.object_revalidation import revalidate_leaf_object+from pipelex.cogt.content_generation.schema_to_model_factory import SchemaToModelFactory+from pipelex.core.stuffs.composite_content import CompositeContent+from pipelex.core.stuffs.document_content import DocumentContent+from pipelex.core.stuffs.image_content import ImageContent+from pipelex.core.stuffs.page_content import PageContent+from pipelex.core.stuffs.search_result_content import SearchResultContent+from pipelex.core.stuffs.structured_content import StructuredContent+from pipelex.core.stuffs.text_and_images_content import TextAndImagesContent+++class ShadowingNames(StructuredContent):+ """Field names a caller may legitimately choose that the class rebuild cannot keep.++ Each shadows a `BaseModel` attribute. Pydantic allows them (with a warning); the rebuild renames them.+ """++ construct: str # type: ignore[assignment] # pyright: ignore[reportIncompatibleMethodOverride]+ copy: str # type: ignore[assignment] # pyright: ignore[reportIncompatibleMethodOverride]+ json: str # type: ignore[assignment] # pyright: ignore[reportIncompatibleMethodOverride]+ schema: str # type: ignore[assignment] # pyright: ignore[reportIncompatibleMethodOverride]+++class AliasedOutput(StructuredContent):+ """A plain alias — a case the round trip already handled, kept so it keeps being handled.++ The schema ships by alias, so the rebuilt class's *field name* is `myField` with no alias of its own;+ dumping it by alias therefore emits `myField` either way, and the original validates it by alias.+ """++ my_field: str = Field(alias="myField")+++def _cross_the_boundary(original: type[BaseModel], *, values: dict[str, Any]) -> BaseModel:+ """Reproduce what a worker does: rebuild the class from the shipped schema, then build an instance."""+ rebuilt = SchemaToModelFactory.make_from_json_schema(+ schema=original.model_json_schema(),+ class_name=original.__name__,+ )+ return rebuilt.model_validate(values)+++class TestBoundaryRoundtripFidelity:+ def test_a_renamed_property_still_comes_back_under_its_own_name(self) -> None:+ """The one real loss the audit found: the rebuild renames, so the dump has to speak aliases."""+ values = {"construct": "a", "copy": "b", "json": "c", "schema": "d"}+ raw_obj = _cross_the_boundary(ShadowingNames, values=values)+ # The rebuild really did rename — without this the test could pass for the wrong reason.+ assert "construct_" in type(raw_obj).model_fields++ result = revalidate_leaf_object(raw_obj, object_class=ShadowingNames, is_mock_built=False)++ assert result.construct == "a"+ assert result.copy == "b"+ assert result.json == "c"+ assert result.schema == "d"++ @pytest.mark.parametrize("dump_mode", ["python", "json"])+ def test_the_renamed_property_survives_in_either_dump_mode(self, dump_mode: Literal["json", "python"]) -> None:+ """The distributed arm dumps in json mode, so the fix has to hold there too."""+ raw_obj = _cross_the_boundary(ShadowingNames, values={"construct": "a", "copy": "b", "json": "c", "schema": "d"})++ result = revalidate_leaf_object(raw_obj, object_class=ShadowingNames, is_mock_built=False, dump_mode=dump_mode)++ assert result.construct == "a"++ def test_a_plain_alias_round_trips(self) -> None:+ """No rename needed, so nothing to compensate for — asserted rather than assumed."""+ raw_obj = _cross_the_boundary(AliasedOutput, values={"myField": "v"})+ assert "myField" in type(raw_obj).model_fields++ result = revalidate_leaf_object(raw_obj, object_class=AliasedOutput, is_mock_built=False)++ assert result.my_field == "v"++ @pytest.mark.parametrize(+ ("original", "values"),+ [+ (ImageContent, {"url": "https://example.com/y.png", "width": 10, "height": 20}),+ (DocumentContent, {"url": "https://example.com/y.pdf", "title": "t"}),+ (TextAndImagesContent, {"text": {"text": "hi"}, "images": [{"url": "https://example.com/y.png"}]}),+ (SearchResultContent, {"answer": "a", "sources": [{"url": "https://example.com", "title": "t"}]}),+ (PageContent, {"text_and_images": {"text": {"text": "hi"}, "images": []}, "page_view": None}),+ (CompositeContent, {"a_component": {"text": "hi"}}),+ ],+ )+ def test_native_content_classes_round_trip_without_loss(self, original: type[BaseModel], values: dict[str, Any]) -> None:+ """The classes a leaf can actually be asked to produce, including nested, list and extra-allow shapes.++ `CompositeContent` is here because it keeps its components as pydantic extras (`extra="allow"`):+ the rebuild preserves that, so the components survive rather than being dropped as unknown keys.+ """+ raw_obj = _cross_the_boundary(original, values=values)++ result = revalidate_leaf_object(raw_obj, object_class=original, is_mock_built=False)++ assert isinstance(result, original)+ assert result.model_dump(mode="json") == original.model_validate(values).model_dump(mode="json")diff --git a/tests/integration/pipelex/cogt/content_generation/test_dry_run_object_fidelity.py b/tests/integration/pipelex/cogt/content_generation/test_dry_run_object_fidelity.pyindex e9c1e8b18..6344cd2a2 100644--- a/tests/integration/pipelex/cogt/content_generation/test_dry_run_object_fidelity.py+++ b/tests/integration/pipelex/cogt/content_generation/test_dry_run_object_fidelity.py@@ -20,10 +20,10 @@ import pytestfrom pipelex.cogt.content_generation.assignment_models import LLMAssignment, ObjectAssignmentfrom pipelex.cogt.content_generation.cogt_run_params import CogtRunParams-from pipelex.cogt.content_generation.content_generator import _revalidate_against_object_class # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]from pipelex.cogt.content_generation.content_generator_protocol import ContentGeneratorProtocolfrom pipelex.cogt.content_generation.dry_mock import dry_llm_gen_object, dry_llm_gen_object_listfrom pipelex.cogt.content_generation.exceptions import DryRunMockBuildError, DryRunObjectFidelityError+from pipelex.cogt.content_generation.object_revalidation import revalidate_leaf_objectfrom pipelex.cogt.llm.llm_prompt import LLMPromptfrom pipelex.cogt.llm.llm_setting import LLMSettingfrom pipelex.system.job_metadata import JobMetadata@@ -55,7 +55,7 @@ class TestDryRunObjectFidelity:raw_mock = dry_llm_gen_object(_boundary_assignment(job_metadata))with pytest.raises(DryRunObjectFidelityError) as exc_info:- _revalidate_against_object_class(raw_mock, object_class=ConstrainedName, is_mock_built=True)+ revalidate_leaf_object(raw_mock, object_class=ConstrainedName, is_mock_built=True)assert ConstrainedName.__name__ in str(exc_info.value)assert "mock_format" in str(exc_info.value)@@ -65,7 +65,7 @@ class TestDryRunObjectFidelity:# Same comprehension shape as ContentGenerator.make_object_list, so this is the real composition.with pytest.raises(DryRunObjectFidelityError):- _ = [_revalidate_against_object_class(raw_mock, object_class=ConstrainedName, is_mock_built=True) for raw_mock in raw_mocks]+ _ = [revalidate_leaf_object(raw_mock, object_class=ConstrainedName, is_mock_built=True) for raw_mock in raw_mocks]async def test_make_object_builds_the_mock_from_the_caller_class(self, job_metadata: JobMetadata, content_generator: ContentGeneratorProtocoldiff --git a/tests/integration/pipelex/cogt/content_generation/test_leaf_dry_object_mocks.py b/tests/integration/pipelex/cogt/content_generation/test_leaf_dry_object_mocks.pyindex 7d45a086a..2407505f9 100644--- a/tests/integration/pipelex/cogt/content_generation/test_leaf_dry_object_mocks.py+++ b/tests/integration/pipelex/cogt/content_generation/test_leaf_dry_object_mocks.py@@ -7,8 +7,10 @@ class (pre-flight decision 2), exercising real datamodel-code-generator codegen.(the object-mock fidelity pin mandated by pre-flight decision 2);- ``nb_items`` carried on ``ObjectAssignment`` controls the dry list length, falling back to``dry_run_config.nb_list_items`` (eng review D11);-- the structured-search dry leaf returns a dict that validates against the original class, and a hidden- invariant the schema round-trip drops there surfaces as ``DryRunObjectFidelityError`` (eng review D6).+- the structured-search dry leaf splits the same way the object leaf does: at the boundary it returns a+ dict built from the schema rebuild, where a dropped invariant surfaces as ``DryRunObjectFidelityError``+ (eng review D6); in-process it mocks the caller's real class, where that invariant is present at build+ time and an unsatisfiable one fails as ``DryRunMockBuildError`` instead.The object leaf's own fidelity arms live in ``test_dry_run_object_fidelity.py``, which separates theboundary case (still schema-rebuilt, still the fidelity error) from the in-process case (built from the@@ -18,12 +20,14 @@ No provider is ever called (the leaves short-circuit before any worker), so no i"""import pytest+from pydantic import ConfigDict, field_validatorfrom pipelex.cogt.content_generation.assignment_models import LLMAssignment, ObjectAssignment, SearchAssignment, SearchObjectAssignmentfrom pipelex.cogt.content_generation.cogt_run_params import CogtRunParamsfrom pipelex.cogt.content_generation.content_generator_protocol import ContentGeneratorProtocolfrom pipelex.cogt.content_generation.dry_mock import dry_llm_gen_object, dry_llm_gen_object_list-from pipelex.cogt.content_generation.exceptions import DryRunObjectFidelityError+from pipelex.cogt.content_generation.exceptions import DryRunMockBuildError, DryRunObjectFidelityError, OutputStructureSchemaError+from pipelex.cogt.content_generation.object_revalidation import revalidate_leaf_datafrom pipelex.cogt.content_generation.search_generate import search_gen_structuredfrom pipelex.cogt.llm.llm_prompt import LLMPromptfrom pipelex.cogt.llm.llm_setting import LLMSetting@@ -52,6 +56,30 @@ class StructuredAnswer(StructuredContent):confidence: float+class OpaqueWidget:+ """A type pydantic can hold but cannot describe as JSON Schema."""+++class UndescribableOutput(StructuredContent):+ """Output structure polyfactory can mock but no provider can be given a schema for."""++ model_config = ConfigDict(arbitrary_types_allowed=True)++ label: str+ widget: OpaqueWidget+++class NormalizedAnswer(StructuredContent):+ """Output structure whose validator *transforms* — the shape that exposes a double validation."""++ answer: str++ @field_validator("answer")+ @classmethod+ def _normalize(cls, value: str) -> str:+ return f"INV-{value}"++class SpecWithPipeCode(StructuredContent):"""Pipe-spec-shaped item: carries the ``pipe_code`` field the mock_main coordination targets."""@@ -134,28 +162,75 @@ class TestLeafDryObjectMocks:assert len(result) == 3assert all(isinstance(item, RepresentativeInvoiceLine) for item in result)- async def test_dry_search_structured_fidelity_gap_raises_typed_error(- self, job_metadata: JobMetadata, content_generator: ContentGeneratorProtocol- ) -> None:- """The structured-search path carries the same D6 fidelity guard as the object paths:- a schema-built dict that drops a hidden invariant surfaces as DryRunObjectFidelityError.+ async def test_boundary_dry_search_structured_fidelity_gap_raises_typed_error(self, job_metadata: JobMetadata) -> None:+ """The structured-search *boundary* carries the same D6 fidelity guard as the object paths.++ Scoped to the boundary composition — the leaf that holds only the serialized assignment, plus the+ submitter that re-validates its dict — exactly as the object path's fidelity test is. In-process+ the mock is built from the caller's real class, so this gap cannot occur there; the constrained+ class fails earlier and louder instead (see the test below)."""- search_assignment = SearchAssignment(- job_metadata=job_metadata,- cogt_run_params=CogtRunParams(run_mode=PipeRunMode.DRY),- query="what is pipelex?",- search_setting=SearchSetting(model="mock-search-handle"),+ search_object_assignment = SearchObjectAssignment.make_for_class(+ output_class=ConstrainedName,+ search_assignment=self._dry_search_assignment(job_metadata),)+ result_dict = await search_gen_structured(search_object_assignment=search_object_assignment)+with pytest.raises(DryRunObjectFidelityError) as exc_info:+ revalidate_leaf_data(result_dict, object_class=ConstrainedName, is_mock_built=True)+ assert ConstrainedName.__name__ in str(exc_info.value)++ async def test_in_process_dry_search_structured_builds_the_mock_from_the_caller_class(+ self, job_metadata: JobMetadata, content_generator: ContentGeneratorProtocol+ ) -> None:+ """In-process the invariant is present at build time, so the failure is a build error, not a fidelity gap."""+ with pytest.raises(DryRunMockBuildError) as exc_info:await content_generator.make_search_structured(output_structure_class=ConstrainedName,- search_assignment=search_assignment,+ search_assignment=self._dry_search_assignment(job_metadata),)assert ConstrainedName.__name__ in str(exc_info.value)+ assert "mock_format" in str(exc_info.value)++ async def test_in_process_dry_search_structured_rejects_an_output_class_with_no_json_schema(+ self, job_metadata: JobMetadata, content_generator: ContentGeneratorProtocol+ ) -> None:+ """The dry run has to be what catches a class no provider can be given a schema for.++ Polyfactory mocks such a class happily, so nothing else on the dry path notices — and carrying the+ caller's class down removed the ``model_json_schema()`` call that used to ride along inside+ ``SearchObjectAssignment.make_for_class``. Without this the live run would die inside the worker on+ a bare ``PydanticInvalidForJsonSchema``, which is a ``RuntimeError``: no model attribution, no+ remedy, no error identity. The boundary arm still builds the assignment, so skipping the check+ here would also make a dry-run verdict depend on how the method is deployed.+ """+ with pytest.raises(OutputStructureSchemaError) as exc_info:+ await content_generator.make_search_structured(+ output_structure_class=UndescribableOutput,+ search_assignment=self._dry_search_assignment(job_metadata),+ )+ assert UndescribableOutput.__name__ in str(exc_info.value)- async def test_dry_search_structured_dict_validates_against_original_class(self) -> None:- """The structured-search dry leaf returns a dict the original output class accepts."""+ async def test_in_process_dry_search_structured_runs_the_caller_validators_exactly_once(+ self, job_metadata: JobMetadata, content_generator: ContentGeneratorProtocol+ ) -> None:+ """The mock is built from the caller's class, so its validators must not run again on a dump of it.++ The search leaf is dict-out at the boundary, and dumping the in-process mock for the submitter to+ re-validate is exactly how a transforming validator would produce ``INV-INV-…`` here.+ """+ result = await content_generator.make_search_structured(+ output_structure_class=NormalizedAnswer,+ search_assignment=self._dry_search_assignment(job_metadata),+ )++ assert isinstance(result, NormalizedAnswer)+ assert result.answer.startswith("INV-")+ assert not result.answer.startswith("INV-INV-")++ async def test_boundary_dry_search_structured_dict_validates_against_original_class(self) -> None:+ """The structured-search dry boundary leaf returns a dict the original output class accepts."""search_assignment = SearchAssignment(job_metadata=JobMetadata(user_id="u", pipeline_run_id="run_dry_search_structured"),cogt_run_params=CogtRunParams(run_mode=PipeRunMode.DRY),@@ -172,3 +247,11 @@ class TestLeafDryObjectMocks:validated = StructuredAnswer.model_validate(result_dict)assert isinstance(validated.answer, str)assert isinstance(validated.confidence, float)++ def _dry_search_assignment(self, job_metadata: JobMetadata) -> SearchAssignment:+ return SearchAssignment(+ job_metadata=job_metadata,+ cogt_run_params=CogtRunParams(run_mode=PipeRunMode.DRY),+ query="what is pipelex?",+ search_setting=SearchSetting(model="mock-search-handle"),+ )diff --git a/tests/integration/pipelex/cogt/content_generation/test_object_class_passthrough.py b/tests/integration/pipelex/cogt/content_generation/test_object_class_passthrough.pyindex 4ae98a2ae..6f3ad83e8 100644--- a/tests/integration/pipelex/cogt/content_generation/test_object_class_passthrough.py+++ b/tests/integration/pipelex/cogt/content_generation/test_object_class_passthrough.py@@ -5,7 +5,7 @@ when the caller's real class was still on the stack. The rebuild is lossy — cu``json_schema_extra`` hints do not survive the round trip — so the provider was constrained by aweaker contract than the one the author wrote.-These tests pin both arms:+These tests pin both arms, on the object leaves and on the structured-search leaf:- in-process (a class is in hand): the provider receives *the same class object*, so every invariantis intact. Asserted with ``is``: a structural-equality assertion would pass against the bug, since@@ -13,7 +13,7 @@ These tests pin both arms:- at the boundary (only the serialized assignment): the class is still rebuilt from the schema, andthe loss is still real — which is what makes the first arm worth having.-The LLM worker is mocked, so no inference marker.+The workers are mocked, so no inference marker."""from typing import Any, get_args@@ -22,14 +22,16 @@ import pytestfrom pydantic import BaseModel, Field, ValidationError, create_model, field_validatorfrom pytest_mock import MockerFixture-from pipelex.cogt.content_generation.assignment_models import LLMAssignment, ObjectAssignment+from pipelex.cogt.content_generation.assignment_models import LLMAssignment, ObjectAssignment, SearchAssignment, SearchObjectAssignmentfrom pipelex.cogt.content_generation.cogt_run_params import CogtRunParams-from pipelex.cogt.content_generation.content_generator import _revalidate_against_object_class # noqa: PLC2701 # pyright: ignore[reportPrivateUsage]from pipelex.cogt.content_generation.content_generator_protocol import ContentGeneratorProtocolfrom pipelex.cogt.content_generation.dry_mock import dry_llm_gen_objectfrom pipelex.cogt.content_generation.llm_generate import llm_gen_object, llm_gen_object_list+from pipelex.cogt.content_generation.object_revalidation import revalidate_leaf_object+from pipelex.cogt.content_generation.search_generate import search_gen_structured, search_gen_structured_objectfrom pipelex.cogt.llm.llm_prompt import LLMPromptfrom pipelex.cogt.llm.llm_setting import LLMSetting+from pipelex.cogt.search.search_setting import SearchSettingfrom pipelex.core.stuffs.structured_content import StructuredContentfrom pipelex.system.job_metadata import JobMetadatafrom pipelex.system.pipe_run_mode import PipeRunMode@@ -96,6 +98,22 @@ def _dry_object_assignment() -> ObjectAssignment:return ObjectAssignment.make_for_class(object_class=SimpleName, llm_assignment=llm_assignment)+def _live_search_assignment() -> SearchAssignment:+ return SearchAssignment(+ job_metadata=JobMetadata(user_id="u", pipeline_run_id="run_search_class_passthrough"),+ cogt_run_params=CogtRunParams(run_mode=PipeRunMode.LIVE),+ query="make a name",+ search_setting=SearchSetting(model="mock-search-handle"),+ )+++def _live_search_object_assignment() -> SearchObjectAssignment:+ return SearchObjectAssignment.make_for_class(+ output_class=HintedName,+ search_assignment=_live_search_assignment(),+ )++def _patch_worker(mocker: MockerFixture, *, gen_object_result: BaseModel) -> Any:mock_worker = mocker.MagicMock()mock_worker.gen_object = mocker.AsyncMock(return_value=gen_object_result)@@ -103,6 +121,14 @@ def _patch_worker(mocker: MockerFixture, *, gen_object_result: BaseModel) -> Anyreturn mock_worker+def _patch_search_worker(mocker: MockerFixture, *, search_structured_result: dict[str, Any]) -> Any:+ mock_worker = mocker.MagicMock()+ mock_worker.search_structured = mocker.AsyncMock(return_value=search_structured_result)+ mocker.patch("pipelex.cogt.content_generation.search_generate._make_search_worker", return_value=mock_worker)+ mocker.patch("pipelex.cogt.content_generation.search_generate._make_search_job", return_value=mocker.MagicMock())+ return mock_worker++@pytest.mark.asyncio(loop_scope="class")class TestObjectClassPassthrough:async def test_live_leaf_hands_the_provider_the_caller_class_itself(self, mocker: MockerFixture) -> None:@@ -221,9 +247,28 @@ class TestObjectClassPassthrough:assert type(raw_obj) is not NormalizedReferenceassert isinstance(raw_obj, NormalizedReference)- result = _revalidate_against_object_class(raw_obj, object_class=NormalizedReference, is_mock_built=False)+ result = revalidate_leaf_object(raw_obj, object_class=NormalizedReference, is_mock_built=False)assert result.reference == "INV-123"+ async def test_live_search_leaf_hands_the_provider_the_caller_class_itself(self, mocker: MockerFixture) -> None:+ """The structured-search leaf carries the same contract as the object leaf, asserted the same way."""+ mock_worker = _patch_search_worker(mocker, search_structured_result={"name": "PFX_ok"})++ await search_gen_structured_object(_live_search_assignment(), output_class=HintedName)++ assert mock_worker.search_structured.await_args.kwargs["schema"] is HintedName++ async def test_boundary_search_leaf_still_rebuilds_from_the_schema(self, mocker: MockerFixture) -> None:+ """Control for the search arm: no class in hand still means a rebuilt class and a raw dict out."""+ mock_worker = _patch_search_worker(mocker, search_structured_result={"name": "no_prefix"})++ result = await search_gen_structured(search_object_assignment=_live_search_object_assignment())++ rebuilt_class = mock_worker.search_structured.await_args.kwargs["schema"]+ assert rebuilt_class is not HintedName+ assert rebuilt_class.__name__ == HintedName.__name__+ assert result == {"name": "no_prefix"}+async def test_dry_leaf_resolves_the_class_the_same_way_as_the_live_leaf(self) -> None:"""Both run modes take the same path — asserted directly, not inferred from two passing tests.diff --git a/tests/integration/pipelex/cogt/test_search.py b/tests/integration/pipelex/cogt/test_search.pyindex 3f1c39a08..fbb69c4d8 100644--- a/tests/integration/pipelex/cogt/test_search.py+++ b/tests/integration/pipelex/cogt/test_search.py@@ -67,11 +67,12 @@ class TestSearch:)result = await worker.search_structured(search_job=search_job, schema=TopicSummary)pretty_print(result, title=f"Structured Search Result ({topic})")+ # The result is the structured payload itself — what the leaf validates against the output+ # structure class — not an envelope around it.assert isinstance(result, dict), "Expected a dict result"- assert "data" in result, "Expected 'data' key in result"- assert "sources" in result, "Expected 'sources' key in result"- data = result["data"]- assert "title" in data, "Expected 'title' key in data"- assert "summary" in data, "Expected 'summary' key in data"- assert "key_points" in data, "Expected 'key_points' key in data"- assert len(result["sources"]) > 0, "Expected at least one source"+ assert "title" in result, "Expected 'title' key in result"+ assert "summary" in result, "Expected 'summary' key in result"+ assert "key_points" in result, "Expected 'key_points' key in result"+ validated = TopicSummary.model_validate(result)+ assert validated.title, "Expected a non-empty title"+ assert validated.key_points, "Expected at least one key point"diff --git a/tests/unit/pipelex/cogt/content_generation/test_object_revalidation.py b/tests/unit/pipelex/cogt/content_generation/test_object_revalidation.pynew file mode 100644index 000000000..8b471e677--- /dev/null+++ b/tests/unit/pipelex/cogt/content_generation/test_object_revalidation.py@@ -0,0 +1,101 @@+"""The shared leaf-result → caller-class conversion, including the arms only a distributed backend uses.++``object_revalidation`` is the single home of a contract both implementations of+``ContentGeneratorProtocol`` depend on — the in-process one in this repo and the workflow arm of our+distributed-execution plugin, which lives in another repo. The arms that repo exercises (the json dump+mode, and a LIVE ``ValidationError`` surviving untouched so the plugin can convert it to a terminal+error) have no in-tree caller, so they are pinned here rather than riding on nothing.++The in-process arms — the ``isinstance`` short-circuit and the dry fidelity error — are exercised+end-to-end in ``tests/integration/pipelex/cogt/content_generation/``; what this module adds is the+mode-independence of the short-circuit and the two error surfaces of the data arm.+"""++from typing import Literal++import pytest+from pydantic import BaseModel, ValidationError, field_serializer++from pipelex.cogt.content_generation.exceptions import DryRunObjectFidelityError+from pipelex.cogt.content_generation.object_revalidation import revalidate_leaf_data, revalidate_leaf_object+++class Marker(BaseModel):+ """The caller's class: what the leaf result must come back as."""++ marker: str+++class BoundaryMarker(BaseModel):+ """Stand-in for a leaf result that crossed a payload boundary.++ Its ``marker`` serializes differently in json mode, which is what makes the dump mode observable —+ the reason a distributed backend needs ``mode="json"`` at all is that some values only round-trip+ cleanly through their json form.+ """++ marker: str++ @field_serializer("marker", when_used="json")+ def _serialize_marker(self, value: str) -> str:+ return value.upper()+++class MarkerSubclass(Marker):+ """What an in-process leaf hands back: never the caller's class itself, always a subclass of it."""+++class TestObjectRevalidation:+ @pytest.mark.parametrize(+ ("dump_mode", "expected_marker"),+ [+ ("python", "boundary"),+ ("json", "BOUNDARY"),+ ],+ )+ def test_dump_mode_reaches_the_dump(self, dump_mode: Literal["json", "python"], expected_marker: str) -> None:+ """The mode is forwarded to model_dump, so a value that needs its json form gets it."""+ raw_obj = BoundaryMarker(marker="boundary")++ result = revalidate_leaf_object(raw_obj, object_class=Marker, is_mock_built=False, dump_mode=dump_mode)++ assert type(result) is Marker+ assert result.marker == expected_marker++ @pytest.mark.parametrize("dump_mode", ["python", "json"])+ def test_instance_short_circuits_in_either_dump_mode(self, dump_mode: Literal["json", "python"]) -> None:+ """An object that already is one is returned untouched whatever the mode — no dump, no second validation.++ The distributed arm never hits this today (a schema-rebuilt class is not a subclass of the+ caller's), and carrying it anyway is the point: a boundary that ever does hand back the real+ class cannot silently reinstate the double validation the in-process path had.+ """+ raw_obj = MarkerSubclass(marker="untouched")++ result = revalidate_leaf_object(raw_obj, object_class=Marker, is_mock_built=False, dump_mode=dump_mode)++ assert result is raw_obj++ def test_data_arm_validates_into_the_caller_class(self) -> None:+ """The data arm's validation is the single one on its path."""+ result = revalidate_leaf_data({"marker": "from-the-wire"}, object_class=Marker, is_mock_built=False)++ assert type(result) is Marker+ assert result.marker == "from-the-wire"++ def test_live_data_failure_keeps_its_validation_error(self) -> None:+ """A LIVE provider's malformed data keeps its ValidationError.++ Load-bearing for the distributed backend: it catches exactly this to convert it into a terminal+ typed error, because a bare ValidationError raised in workflow code retries forever.+ """+ with pytest.raises(ValidationError):+ revalidate_leaf_data({"marker": 123}, object_class=Marker, is_mock_built=False)++ def test_mock_built_data_failure_raises_the_typed_fidelity_error(self) -> None:+ """Mock-built data that fails is the known schema-round-trip gap, named as such with its remedy."""+ with pytest.raises(DryRunObjectFidelityError) as exc_info:+ revalidate_leaf_data({"marker": None}, object_class=Marker, is_mock_built=True)++ assert Marker.__name__ in str(exc_info.value)+ assert "mock_format" in str(exc_info.value)diff --git a/tests/unit/pipelex/providers/gateway/test_gateway_structured_search_contract.py b/tests/unit/pipelex/providers/gateway/test_gateway_structured_search_contract.pynew file mode 100644index 000000000..771312479--- /dev/null+++ b/tests/unit/pipelex/providers/gateway/test_gateway_structured_search_contract.py@@ -0,0 +1,123 @@+"""The gateway's structured search must hand the leaf the bare payload, not the relay's envelope.++The relay asks Linkup for sources alongside the structured payload, so its wire shape is a+``{data, sources}`` envelope — while the leaf validates the result against the caller's output+structure class, which has nowhere to put sources. The worker owes the leaf the unwrapped payload,+and owes a classified search error (not an opaque downstream ``ValidationError``) when the envelope+shape is not there.++No provider is called (the relay call is mocked), so this needs no inference marker.+"""++from __future__ import annotations++import json+from typing import TYPE_CHECKING, Any++import pytest+from pydantic import BaseModel++from pipelex.providers.gateway.gateway_exceptions import GatewaySearchEmptyResultError, GatewaySearchResponseError+from pipelex.providers.gateway.gateway_search_worker import GatewaySearchWorker++if TYPE_CHECKING:+ from pytest_mock import MockerFixture+++class TopicSummary(BaseModel):+ title: str+ summary: str+++class DataAndSources(BaseModel):+ """An output structure that legitimately spells its own fields the way the relay envelope does."""++ data: dict[str, str]+ sources: list[str]+++def _make_worker(mocker: MockerFixture, *, content: str) -> GatewaySearchWorker:+ worker = object.__new__(GatewaySearchWorker)+ mock_model = mocker.MagicMock()+ mock_model.desc = "test-gateway-search"+ mock_model.model_id = "linkup/standard"+ mock_model.name = "linkup-standard"+ mock_model.extra_headers = None+ worker.inference_model = mock_model+ mocker.patch.object(GatewaySearchWorker, "_call_relay", mocker.AsyncMock(return_value=mocker.MagicMock()))+ mocker.patch.object(GatewaySearchWorker, "_extract_usage", return_value=None)+ mocker.patch.object(GatewaySearchWorker, "_extract_content", return_value=content)+ return worker+++def _make_search_job(mocker: MockerFixture) -> Any:+ job = mocker.MagicMock()+ job.query = "test search query"+ job.job_params.search_setting.include_images = False+ job.job_params.search_setting.include_inline_citations = False+ job.job_params.search_setting.max_results = 10+ job.job_params.include_domains = None+ job.job_params.exclude_domains = None+ job.job_params.from_date = None+ job.job_params.to_date = None+ job.job_report.search_tokens_usage = None+ return job++[email protected](loop_scope="class")+class TestGatewayStructuredSearchContract:+ async def test_the_relay_envelope_is_unwrapped_to_the_bare_payload(self, mocker: MockerFixture) -> None:+ """The `{data, sources}` envelope arrives from the relay; the leaf gets the payload alone."""+ payload = {"title": "pipelex", "summary": "a language"}+ content = json.dumps({"data": payload, "sources": [{"name": "src", "url": "https://example.com", "snippet": "…"}]})+ worker = _make_worker(mocker, content=content)++ result = await worker._search_structured(search_job=_make_search_job(mocker), schema=TopicSummary) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]++ assert result == payload+ # The payload validates against the caller's output structure class — the envelope never could.+ validated = TopicSummary.model_validate(result)+ assert validated.title == "pipelex"++ async def test_a_bare_payload_passes_through_unwrapped(self, mocker: MockerFixture) -> None:+ """The relay dropping sources must not break this worker — the envelope is recognised, not demanded.++ Demanding it would make "relay stops asking Linkup for sources" a coordinated two-sided deploy:+ every gateway structured search would fail until both repos shipped together.+ """+ payload = {"title": "pipelex", "summary": "a language"}+ worker = _make_worker(mocker, content=json.dumps(payload))++ result = await worker._search_structured(search_job=_make_search_job(mocker), schema=TopicSummary) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]++ assert result == payload++ async def test_an_output_class_that_declares_data_and_sources_is_not_unwrapped(self, mocker: MockerFixture) -> None:+ """The one shape a positional `.get("data")` unwrap would silently corrupt."""+ payload = {"data": {"nested": "value"}, "sources": ["a"]}+ worker = _make_worker(mocker, content=json.dumps(payload))++ result = await worker._search_structured(search_job=_make_search_job(mocker), schema=DataAndSources) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]++ assert result == payload, "the caller's own {data, sources} output is its payload, not an envelope around one"++ async def test_an_envelope_carrying_no_payload_raises_an_empty_result_error(self, mocker: MockerFixture) -> None:+ """A search that found nothing is not a malformed response — it must not advise changing model."""+ worker = _make_worker(mocker, content=json.dumps({"data": None, "sources": []}))++ with pytest.raises(GatewaySearchEmptyResultError, match="empty structured result"):+ await worker._search_structured(search_job=_make_search_job(mocker), schema=TopicSummary) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]++ async def test_a_non_object_response_raises_a_classified_search_error(self, mocker: MockerFixture) -> None:+ """A response that is not a JSON object at all is malformed, and says so."""+ worker = _make_worker(mocker, content=json.dumps(["not", "an", "object"]))++ with pytest.raises(GatewaySearchResponseError, match="non-object payload"):+ await worker._search_structured(search_job=_make_search_job(mocker), schema=TopicSummary) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]++ async def test_a_non_json_body_raises_a_classified_search_error(self, mocker: MockerFixture) -> None:+ """The likeliest way the relay contract breaks must not escape as a bare JSONDecodeError."""+ worker = _make_worker(mocker, content="<html>502 Bad Gateway</html>")++ with pytest.raises(GatewaySearchResponseError, match="not valid JSON"):+ await worker._search_structured(search_job=_make_search_job(mocker), schema=TopicSummary) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]diff --git a/tests/unit/pipelex/providers/linkup/test_linkup_structured_search_contract.py b/tests/unit/pipelex/providers/linkup/test_linkup_structured_search_contract.pynew file mode 100644index 000000000..5908a4459--- /dev/null+++ b/tests/unit/pipelex/providers/linkup/test_linkup_structured_search_contract.py@@ -0,0 +1,146 @@+"""What a structured search must put on the wire, and what it must hand back.++The leaf validates the returned dict against the caller's output structure class, so the worker owes it+exactly that payload — and owes it *unvalidated*, because the leaf is where the run mode and the+dry-run fidelity contract live. Two things make that true, and both are invisible from the outside:++- the schema crosses as a JSON string, not as the class. Byte-for-byte the same request, but handing the+ SDK the class also makes it instantiate that class from the response, which would run the caller's+ validators inside the SDK and again at the leaf;+- sources are not requested, because a structured result has nowhere to put them and asking for them+ wraps the payload in an envelope no output class can accept.++No provider is called (the SDK client is mocked), so this needs no inference marker.+"""++from __future__ import annotations++import json+from typing import TYPE_CHECKING, Any++import pytest+from pydantic import BaseModel, Field, field_validator++from pipelex.providers.linkup.linkup_exceptions import LinkupSearchEmptyResultError, LinkupSearchResponseError+from pipelex.providers.linkup.linkup_search_worker import LinkupSearchWorker++if TYPE_CHECKING:+ from pytest_mock import MockerFixture+++class TopicSummary(BaseModel):+ """An output structure carrying invariants a JSON-schema rebuild would drop."""++ title: str = Field(json_schema_extra={"mock_format": "name"})+ summary: str++ @field_validator("title")+ @classmethod+ def _require_prefix(cls, value: str) -> str:+ return f"INV-{value}"+++class AllDefaults(BaseModel):+ """An output structure with no required field — the shape that makes a wrong payload validate silently."""++ title: str = "untitled"+ summary: str = ""+++def _make_worker(mocker: MockerFixture, *, sdk_result: Any) -> LinkupSearchWorker:+ worker = object.__new__(LinkupSearchWorker)+ mock_model = mocker.MagicMock()+ mock_model.desc = "test-linkup-search"+ mock_model.model_id = "linkup/standard"+ mock_model.name = "linkup-standard"+ worker.inference_model = mock_model+ mock_client = mocker.MagicMock()+ mock_client.async_search = mocker.AsyncMock(return_value=sdk_result)+ setattr(worker, "_linkup_client", mock_client) # noqa: B010+ return worker+++def _make_search_job(mocker: MockerFixture) -> Any:+ job = mocker.MagicMock()+ job.query = "test search query"+ job.job_params.search_setting.include_images = False+ job.job_params.search_setting.include_inline_citations = False+ job.job_params.search_setting.max_results = 10+ job.job_params.include_domains = None+ job.job_params.exclude_domains = None+ job.job_params.from_date = None+ job.job_params.to_date = None+ job.job_report.search_tokens_usage = None+ return job++[email protected](loop_scope="class")+class TestLinkupStructuredSearchContract:+ async def test_the_callers_own_schema_crosses_as_json_without_the_class(self, mocker: MockerFixture) -> None:+ """The request carries the caller's real schema, and the SDK gets no class to instantiate."""+ worker = _make_worker(mocker, sdk_result={"title": "pipelex", "summary": "a language"})+ client: Any = getattr(worker, "_linkup_client") # noqa: B009++ await worker._search_structured(search_job=_make_search_job(mocker), schema=TopicSummary) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]++ sent_schema = client.async_search.await_args.kwargs["structured_output_schema"]+ assert isinstance(sent_schema, str), "a class would make the SDK validate the response itself"+ assert json.loads(sent_schema) == TopicSummary.model_json_schema()+ # The hint a schema rebuild would have dropped is in the request, which is the point of+ # threading the caller's class this far down.+ assert json.loads(sent_schema)["properties"]["title"]["mock_format"] == "name"++ async def test_sources_are_not_requested(self, mocker: MockerFixture) -> None:+ """Asking for sources wraps the payload in an envelope the output structure class cannot accept."""+ worker = _make_worker(mocker, sdk_result={"title": "pipelex", "summary": "a language"})+ client: Any = getattr(worker, "_linkup_client") # noqa: B009++ await worker._search_structured(search_job=_make_search_job(mocker), schema=TopicSummary) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]++ assert client.async_search.await_args.kwargs["include_sources"] is False++ async def test_the_payload_comes_back_raw_and_validates_into_the_output_class(self, mocker: MockerFixture) -> None:+ """The dict is the structured payload itself, un-normalized: the leaf's validation is the first one."""+ worker = _make_worker(mocker, sdk_result={"title": "pipelex", "summary": "a language"})++ result = await worker._search_structured(search_job=_make_search_job(mocker), schema=TopicSummary) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]++ assert result == {"title": "pipelex", "summary": "a language"}+ # The caller's transforming validator has not run yet — it runs once, when the leaf validates.+ validated = TopicSummary.model_validate(result)+ assert validated.title == "INV-pipelex"++ async def test_an_unrequested_envelope_is_unwrapped_rather_than_silently_validated(self, mocker: MockerFixture) -> None:+ """Not requesting sources is not the same as not receiving them, and the difference is silent.++ Asking `include_sources=False` is a request, not a guarantee — the SDK's own source hedges on it+ ("we assume that include_sources will default to False, since the API output can be arbitrary").+ A provider that ignores the flag hands back the envelope, and an output structure whose fields all+ carry defaults validates that envelope *successfully* into an all-defaults object, because+ pydantic's default `extra="ignore"` drops both keys. That is wrong answers with no error, so the+ shape is recognised rather than assumed.+ """+ payload = {"title": "pipelex", "summary": "a language"}+ envelope = {"data": payload, "sources": [{"name": "src", "url": "https://example.com", "snippet": "…"}]}+ worker = _make_worker(mocker, sdk_result=envelope)++ result = await worker._search_structured(search_job=_make_search_job(mocker), schema=AllDefaults) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]++ assert result == payload+ # What the guard prevents: validating the envelope instead would have succeeded and thrown the+ # provider's real answer away.+ assert AllDefaults.model_validate(envelope).title == "untitled"++ async def test_an_envelope_carrying_no_payload_raises_an_empty_result_error(self, mocker: MockerFixture) -> None:+ """A search that found nothing is not a malformed response — it must not advise changing model."""+ worker = _make_worker(mocker, sdk_result={"data": None, "sources": []})++ with pytest.raises(LinkupSearchEmptyResultError, match="empty structured result"):+ await worker._search_structured(search_job=_make_search_job(mocker), schema=TopicSummary) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]++ async def test_a_non_object_payload_raises_a_classified_search_error(self, mocker: MockerFixture) -> None:+ """The SDK returns the provider's JSON verbatim, so a non-object payload must surface here as a classified error, not at the leaf."""+ worker = _make_worker(mocker, sdk_result=["not", "an", "object"])++ with pytest.raises(LinkupSearchResponseError, match="list"):+ await worker._search_structured(search_job=_make_search_job(mocker), schema=TopicSummary) # noqa: SLF001 # pyright: ignore[reportPrivateUsage]diff --git a/wip/refactoring/boundary-revalidation-round-trip-audit.md b/wip/refactoring/boundary-revalidation-round-trip-audit.mdnew file mode 100644index 000000000..31418e9d0--- /dev/null+++ b/wip/refactoring/boundary-revalidation-round-trip-audit.md@@ -0,0 +1,45 @@+# The boundary re-validation round trip, audited++Supersedes `boundary-revalidation-round-trip-is-unaudited.md` (deferred out of PR #1076). The audit was done, it found one real loss, the loss is fixed, and the parts that turned out to be safe now have tests so they stay that way. This note records what was established, what was corrected, and the two things still not established.++The conversion in question is the boundary arm of `revalidate_leaf_object` (`pipelex/cogt/content_generation/object_revalidation.py`): `object_class.model_validate(raw_obj.model_dump(mode=dump_mode, serialize_as_any=True, by_alias=True))`.++## Who actually reaches it++**Nothing in this repo.** Every branch of `ContentGenerator.make_object` / `make_object_list` returns an `isinstance` of `object_class`, so the short-circuit always fires and the conversion arm is dead code here:++- **DRY** — `dry_llm_gen_object` resolves the caller's class unchanged and `build_mock_object` builds through polyfactory, whose `build()` instantiates `__model__` itself. The result is exactly `object_class`.+- **LIVE** — every concrete LLM worker returns instructor's object untouched (`llm_worker_abstract.gen_object` only strips `_raw_response` and reports). Instructor's `prepare_response_model` wraps the class as `create_model(cls.__name__, __base__=(cls, OpenAISchema))`, a *subclass*, so `isinstance` holds. The Bedrock worker raises `LLMCapabilityError` instead of returning. Gateway / Portkey / Azure / OpenRouter are the OpenAI workers under a different factory, not separate classes.+- **The list path** wraps only the top-level `ListSchema`; its `items` are constructed by pydantic against `list[item_class]`, so each item is exactly `item_class`.++**The distributed boundary always reaches it.** The activity calls the leaves without a class, so the object is built from a `SchemaToModelFactory` rebuild; kajson re-execs that class from `__kajson_class_source__` on the workflow side and a per-call scoped registry makes the source-derived type win over the globally registered one. A rebuilt class is never a subclass of `object_class`, so the short-circuit cannot fire there — which is exactly the split the design intends.++## What crosses it++In production `object_class` is always a `StuffContent` subclass resolved **by name** from the class registry — the concept's `structure_class_name`. That registry holds the native content classes, the generated `<domain>__<Concept>` structure classes, everything `auto_register_all_subclasses(base_class=StructuredContent)` sweeps out of `sys.modules` (including the builder spec classes), and user classes from library folders. So the set is open: **any field name a user can write in a concept structure can cross this conversion.** That is what makes the loss below matter.++## The loss, and the fix++`datamodel-code-generator` cannot name a field `json`, `copy`, `schema` or `construct` — they shadow `BaseModel` attributes — nor can it use a python keyword. It renames the field (`construct_`) and records the schema's property name as the alias. Dumping **by field name** then emitted `construct_` for a field the caller's class calls `construct`, and re-validation failed with a bare `Field required` — on a field the caller had supplied.++Reproduced, fixed by dumping `by_alias=True`, and pinned by `tests/integration/pipelex/cogt/content_generation/test_boundary_roundtrip_fidelity.py` (which fails on every shadowing field without it, in both dump modes). The dump now emits exactly the schema's property names, which is what the round trip and the provider are both keyed on. Where nothing was renamed, the rebuilt class's alias *is* its field name, so nothing else changed — the native content classes are parametrized in that test as the control.++The same fix was needed on the structured-search dry boundary arm (`dry_search_gen_structured`), which dumps its mock for the wire.++**`PipeSearchSpec` / `PipeComposeSpec` were the models the old note worried about, and it had the mechanism wrong.** It supposed they survive thanks to `populate_by_name=True`. They do not: `PipeComposeSpec` **failed** this round trip before the fix, because its `construct` property is exactly a shadowed name — `populate_by_name` lets `construct_spec` through, but the dump emitted `construct_`, which matches neither the field name nor the alias. `PipeSearchSpec` survived only because its alias `query` is a legal field name that needed no rename.++## What the old note worried about that is genuinely safe++- **Plain aliases need no compensation.** `model_json_schema()` emits **by alias**, so the shipped schema's property names are the ones `object_class` accepts on the way in, and the rebuilt class's field name simply *is* the alias. This holds with or without `populate_by_name`. Pinned by `test_a_plain_alias_round_trips`.+- **Subclass erasure is structurally unreachable**, not merely unobserved. The object that crosses is built from `object_class`'s own schema, so it cannot carry a field `object_class` lacks; and the one object that *is* a subclass — instructor's — hits the short-circuit and is never dumped. Nested erasure would need a leaf that produces a subclass instance inside a declared field, which neither arm does. There is no test for this because there is no way to construct the case through this path.+- **`CompositeContent` survives.** Its `extra="allow"` config comes through the rebuild, so the components it keeps as pydantic extras are preserved rather than dropped as unknown keys. Parametrized in the round-trip test.+- **`DateContent` / `TimeContent`'s `mode="before"` validators are total over their own serialized output.** They are the closest thing on this path to a validator that would not be, and they only see json mode (the distributed arm): an ISO date survives both the numeric-string and the time-bearing-string rejection.++## Still not established++- **`Mode.PARALLEL_TOOLS` / `VERTEXAI_PARALLEL_TOOLS` would break the short-circuit's premise.** Instructor returns a *generator* in those modes, not an instance of the response model. They are reachable from `StructureMethod` but **no model in the shipped TOMLs selects them**, so this is a config-reachable hazard rather than a live one. If one is ever configured, `make_object` returns something that is neither an instance nor dumpable the way this helper expects — worth a guard at that point, not before.+- **Whether the json-mode round trip is lossless for every field type a user can write.** The audit covered the native content classes and the alias/rename mechanics; it did not enumerate arbitrary user field types under `mode="json"`. This is the residue of the original note, narrowed: it is now specifically about json-mode coercion on the distributed arm, not about the conversion in general.++## The fix the old note proposed, and why it was not needed++It suggested that if the audit found a real loss, the fix was "probably to have the boundary return raw data rather than a reconstructed instance, so there is one validation instead of a dump of one". That is a larger change — it alters what the object leaf returns across the payload boundary — and the loss found did not require it. Worth keeping in mind if the json-mode residue above ever turns up something `by_alias` cannot fix.diff --git a/wip/refactoring/boundary-revalidation-round-trip-is-unaudited.md b/wip/refactoring/boundary-revalidation-round-trip-is-unaudited.mddeleted file mode 100644index e7d752f5a..000000000--- a/wip/refactoring/boundary-revalidation-round-trip-is-unaudited.md+++ /dev/null@@ -1,31 +0,0 @@-# The boundary re-validation round trip is lossy in ways nobody has audited--Deferred out of PR #1076 (`refactor/Exec`). **Pre-existing, unchanged by that PR, and it must stay** — it is the boundary conversion. Recorded so the next person to touch it knows what has and has not been checked.--## What it is--`_revalidate_against_object_class` (`pipelex/cogt/content_generation/content_generator.py`) converts a leaf result into the caller's class with:--```python-object_class.model_validate(raw_obj.model_dump(serialize_as_any=True))-```--After #1076 this only runs on the **boundary** path — a worker that held only the serialized `ObjectAssignment` returns an instance of a class rebuilt from the JSON schema, which is never a subclass of `object_class`, so the `isinstance` short-circuit does not catch it. In-process the object is returned untouched.--## Why it is worth a look eventually--The dump→validate round trip is not identity-preserving in general, and the ways it can lose are not covered by any test:--- **Subclass erasure.** A dumped subclass instance revalidates as the declared class, silently dropping the subclass's extra fields and its type.-- **Dumped-by-field-name data has to revalidate cleanly.** This currently happens to work only because of compensating configuration elsewhere: `PipeSearchSpec` / `PipeComposeSpec` set `populate_by_name=True`, and `PipeComposeSpec` carries a `normalize_construct_field` before-validator. A new aliased model on this path would not automatically inherit that luck.-- **Validators run on the dumped form**, not the constructed form. For a model whose validators are not total over their own serialized output, that is a different input than the one they were written against.--None of these is currently reachable in-process (the short-circuit sees to that) and none has a known live trigger on the boundary path either — which is exactly why this is a note and not a change.--## What would close it--An audit of what actually crosses this conversion on the boundary path, plus a round-trip property test over the models that do. If the audit finds a real loss, the fix is probably to have the boundary return raw data rather than a reconstructed instance, so there is one validation instead of a dump of one.--## Related--- The in-process arm of this same function was a genuine double-validation regression, found by the PR bots on #1076 and fixed there with an `isinstance` short-circuit. See that PR's `TODOS.md` for the reasoning.diff --git a/wip/refactoring/func-registry-entries-outlive-their-library.md b/wip/refactoring/func-registry-entries-outlive-their-library.mdindex 58f651eb0..297aac353 100644--- a/wip/refactoring/func-registry-entries-outlive-their-library.md+++ b/wip/refactoring/func-registry-entries-outlive-their-library.md@@ -46,4 +46,4 @@ Do **not** "fix" it by weakening the collision check back to a silent overwrite## Related-- `wip/refactoring/structured-search-still-rebuilds-in-process.md`, `wip/refactoring/boundary-revalidation-round-trip-is-unaudited.md` — the other deferrals out of the same PR.+- The other deferrals out of the same PR are done: the shared revalidation helper and the structured-search class threading landed on `refactor/Follow-ups` (see that branch's `TODOS.md`), and the boundary round trip is now audited in `wip/refactoring/boundary-revalidation-round-trip-audit.md`. This one is the last of the four, and stays its own PR.diff --git a/wip/refactoring/leaf-conversion-and-search-follow-ups.md b/wip/refactoring/leaf-conversion-and-search-follow-ups.mdnew file mode 100644index 000000000..c8fbbcf46--- /dev/null+++ b/wip/refactoring/leaf-conversion-and-search-follow-ups.md@@ -0,0 +1,274 @@+# Leaf-conversion and structured-search follow-ups — what the review of `refactor/Follow-ups` left open++The items a full pre-landing `/review` of `refactor/Follow-ups` surfaced and **did not fix**. The branch itself carries the critical fixes that review found; this file is the residue.++Every claim below was re-verified against the tree on **2026-07-31 at `2cc27966a` plus the review's own fixes** — that is, *after* the critical work landed, so nothing here is a stale reading of the pre-review tree. The command that produced each measurement is inline, so a new session can re-take it rather than trust it.++**Stable ids:** cite these as **RF-1** … **RF-7**. They are deliberately not `FU-n`: that namespace belongs to the modularity track in [`modularity-review-follow-ups.md`](modularity-review-follow-ups.md), and the two docs sit in the same folder.++| id | one line | verdict | size | blocked on |+| --- | --- | --- | --- | --- |+| [RF-1](#rf-1--the-live-validationerror-contract-is-inconsistent-and-the-plugins-own-two-arms-disagree-about-it) | The live-`ValidationError` contract is inconsistent; the plugin's own two arms disagree | **design decision needed** | small code, real thinking | nothing — decide before the sweep |+| [RF-2](#rf-2--by_alias-and-dump_mode-reach-no-live-path-here-and-the-plugins-copy-diverges-on-the-announced-fix) | `by_alias` / `dump_mode` reach no live path here; the plugin's copy diverges on the announced fix | true, disclosed | small (a swap) | RF-1, then a `pipelex` release |+| [RF-3](#rf-3--the-test-gaps-this-branch-left) | Test gaps this branch left — one of them lets the headline fix be deleted silently | true | small | nothing |+| [RF-4](#rf-4--no-request-timeout-ever-reaches-the-linkup-sdk) | No request timeout ever reaches the Linkup SDK, so `LinkupTimeoutError` is unreachable | true, pre-existing | small + a config call | nothing |+| [RF-5](#rf-5--the-llm-paths-schema-check-is-implicit-and-a-plausible-optimisation-would-delete-it) | The LLM path's schema check is implicit, and a plausible optimisation deletes it | true | small | nothing |+| [RF-6](#rf-6--dry-search-leaves-report-no-usage) | Dry search leaves report no usage | true, pre-existing | small design | nothing |+| [RF-7](#rf-7--the-relays-envelope-contract-is-unpinned-on-the-producing-side) | The relay's envelope contract is unpinned on the producing side | true | small, cross-repo | a `pipelex-relay` PR |++**What the review already fixed, so you do not re-find it:** the direct Linkup backend silently validating a `{data, sources}` envelope into an all-defaults object; a billed search whose shape was rejected vanishing from the cost report; `pipelex validate` no longer catching an output class that cannot emit a JSON schema; the gateway's positional `.get("data")` unwrap; `JSONDecodeError` escaping unclassified; the misleading "try a different model" advice on an empty result; and `linkup/exceptions.py` not following the `<provider>_exceptions.py` convention.++---++## RF-1 — The live-`ValidationError` contract is inconsistent, and the plugin's own two arms disagree about it++**Not** "the plugin cannot adopt the shared helper" — it can, and on the object path it is a clean swap. The branch's review guide already frames the bare re-raise as deliberate, and that framing is right. What the review found is narrower and more interesting: **the intended adopter contradicts itself about whether a live `ValidationError` may escape workflow code**, and by its own comment the arm that lets it escape is the wrong one.++### Verified++The shared helper re-raises the bare `ValidationError` on the live path — `pipelex/cogt/content_generation/object_revalidation.py`:++```python+try:+ return object_class.model_validate(raw_data)+except ValidationError as exc:+ if is_mock_built:+ raise DryRunObjectFidelityError.for_object_class(object_class.__name__) from exc+ raise+```++The plugin's **object** arm does exactly the same — so it can adopt the helper as-is:++```bash+sed -n '52,78p' ../pipelex-temporal/pipelex_temporal/tprl_content_generation/content_generator_in_workflow.py+# ... Scoped to the dry path only — a LIVE provider's invalid output keeps its existing ``ValidationError``.+# raw_data = raw_obj.model_dump(mode="json", serialize_as_any=True)+# if not is_mock_built:+# return object_class.model_validate(raw_data)+```++Its **search** arm does the opposite, and says why:++```bash+sed -n '548,561p' ../pipelex-temporal/pipelex_temporal/tprl_content_generation/content_generator_in_workflow.py+# # ... a malformed structured response raises a bare ValidationError here in+# # workflow code. Left raw it is neither WorkflowExecutionError nor PipelexError, so Temporal+# # treats it as a workflow-task failure and retries forever, hanging the submitter — the exact+# # failure mode this seam exists to prevent.+# try:+# return output_structure_class.model_validate(result_dict)+# except ValidationError as exc:+# ...+# raise ContentGenerationError(msg) from exc+```++Both arms run in workflow code. If that comment is correct — and it has an integration test behind it — then the object arm has the same hang hazard and does nothing about it. If the object arm is fine, the search arm's conversion is unnecessary. They cannot both be right.++### Why this lands here and not only in that repo++The plugin sweep is already on the books as "swap the copies for the shared helper". Doing that swap **as written** propagates the inconsistency into the shared home: the helper would become the single documented source of a live-error contract that the plugin's search arm has to override anyway, without the helper saying so. Whoever does the sweep should resolve the disagreement first, not preserve it.++### There is a second half, in this repo++In-process, that same bare `ValidationError` is now the **primary live failure mode** of structured search — "the provider returned a payload that doesn't match your class" — and it escapes the Pipelex error taxonomy entirely: no `error_type`, no `error_domain`, no `type_uri`. Until this branch, structured search was broken on both backends, so that outcome was never reachable; it is now.++### Options++1. **Give the helper an explicit live-failure contract** — an `on_validation_error` callable, or a typed error class parameter. The plugin passes its `ContentGenerationError` on both arms; this repo passes a typed content-generation error. The disagreement resolves in one place and the in-repo taxonomy hole closes with it.+2. **Keep the bare `raise`, decide the plugin question separately.** Legitimate — but then the helper's docstring must say that a submitter running in workflow code MUST NOT let the bare error escape, because right now nothing in the shared home warns the next adopter.++Either way, the plugin's two arms need to agree before the sweep lands.++---++## RF-2 — `by_alias` and `dump_mode` reach no live path here, and the plugin's copy diverges on the announced fix++Disclosed in the CHANGELOG, so this is not a surprise — but the *shape* of the divergence is worse than "not adopted yet" and is worth stating plainly.++### Verified++The branch's own audit says nothing in this repo reaches the conversion arm ([`boundary-revalidation-round-trip-audit.md`](boundary-revalidation-round-trip-audit.md), "Who reaches the conversion"): every in-repo path hits the `isinstance` short-circuit. The boundary arm's only caller is out of repo:++```bash+grep -rn "await search_gen_structured(" ../pipelex-temporal/pipelex_temporal/+# .../tprl_content_generation/act_search_generate.py:23: return await search_gen_structured(search_object_assignment=search_object_assignment)+```++(Grep for `search_gen_structured\b` instead and the word boundary matches inside `act_search_gen_structured`, burying the one real call site under the activity's own name.)++And the plugin's copy of the conversion still dumps without `by_alias`:++```bash+grep -n "model_dump(mode=" ../pipelex-temporal/pipelex_temporal/tprl_content_generation/content_generator_in_workflow.py+# 71: raw_data = raw_obj.model_dump(mode="json", serialize_as_any=True)+```++`dump_mode` likewise has no production caller anywhere — only tests pass a non-default value.++### Why it matters more than "pending"++Before the extraction the two copies differed only in `dump_mode`. They now differ **on the exact defect the CHANGELOG announces as fixed**: a field named `json` / `copy` / `schema` / `construct` still breaks the round trip on the distributed arm, which is the *only* arm that reaches that code. The divergence is invisible to both repos' CI.++The one live path in this package that does get the fix is `dry_search_gen_structured` — reached only through the boundary arm, which again only the plugin calls.++**Do this together with RF-1**, in the plugin sweep, and re-read the CHANGELOG entry's framing when it lands.++---++## RF-3 — The test gaps this branch left++Priority order. The first one is the one that matters.++### (a) `by_alias=True` on the dry boundary search mock is untested++`pipelex/cogt/content_generation/dry_mock.py`:++```python+return build_mock_object(boundary_class).model_dump(mode="json", by_alias=True)+```++No test builds a `SearchObjectAssignment` from a class whose properties the rebuild renames, so **deleting `by_alias=True` here leaves the whole suite green** while re-introducing the `Field required` failure the branch set out to fix. The sibling fix in `revalidate_leaf_object` *is* pinned, which makes this an asymmetry rather than an accepted gap:++```bash+grep -rln "construct: str\|json: str" tests/+# tests/integration/pipelex/cogt/content_generation/test_boundary_roundtrip_fidelity.py ← only the object arm+```++Fix: a boundary-dry case in `test_leaf_dry_object_mocks.py` using a `StructuredContent` with shadowing field names, asserting the returned dict is keyed by the schema property names and validates back into the original class.++### (b) The live in-process search arm's return value is never asserted++`tests/integration/pipelex/cogt/content_generation/test_object_class_passthrough.py`:++```python+await search_gen_structured_object(_live_search_assignment(), output_class=HintedName)++assert mock_worker.search_structured.await_args.kwargs["schema"] is HintedName+```++The result is discarded. Its dry twin asserts the value, so the once-only-validation contract and the `is_mock_built=False` negative path (a malformed provider dict must raise `ValidationError`, never `DryRunObjectFidelityError`) are unpinned on the live arm.++### (c) The SDK-exception branch of `_search_structured` is untested on both backends++```bash+grep -c "_search_sourced_answer" tests/unit/pipelex/providers/linkup/test_linkup_search_worker_semantic.py # 1+grep -c "_search_structured" tests/unit/pipelex/providers/linkup/test_linkup_search_worker_semantic.py # 0+```++The semantic tests that parametrize every Linkup SDK exception only ever drive the sourced-answer arm. The structured arm's `try` now wraps a differently-shaped call (serialized schema, `include_sources=False`), so its error classification and `from exc` chaining ride on nothing. Parametrizing the existing tests over both arms is the cheap fix.++### (d) The gateway test never asserts the caller's schema reaches the relay++The Linkup contract test pins that the real schema — including a `json_schema_extra` hint a rebuild would drop — crosses the wire. Its gateway counterpart mocks `_call_relay` wholesale and never inspects what was sent, so item 2's contract is verified on one backend only, and the gateway is the one the hosted runner uses.++---++## RF-4 — No request timeout ever reaches the Linkup SDK++### Verified++```bash+grep -n "timeout" pipelex/providers/linkup/linkup_search_worker.py pipelex/providers/linkup/linkup_extract_worker.py+# (none)+```++The SDK's `async_search` takes `timeout: float | None = None` and passes it straight to `httpx`, whose docs say `timeout=None` disables timeouts entirely — connect, read, write and pool. So a slow or hung provider blocks the task indefinitely.++The design clearly assumes a timeout exists: the worker catches `LinkupTimeoutError` and classifies it. **The condition that raises it cannot be reached.**++Pre-existing, and it affects the sourced-answer and extract paths too — but the structured call site was rewritten on this branch, which is why it surfaced now.++Fix needs a decision, which is why it is deferred rather than patched: where does the value come from — a search setting, a provider config key, or a shared inference default? Once that is settled the code is one keyword argument per call site.++---++## RF-5 — The LLM path's schema check is implicit, and a plausible optimisation would delete it++This is a **trap**, recorded so the next person to "clean up" a redundant call does not spring it.++### Verified++`ObjectAssignment.make_for_class` computes a schema that the in-process path never reads:++```bash+grep -n "model_json_schema" pipelex/cogt/content_generation/assignment_models.py+# 95: object_class_schema=object_class.model_json_schema(),+# 184: output_class_schema=output_class.model_json_schema(),+```++`resolve_object_class` returns the live class immediately when one is in hand — which it always is from `ContentGenerator` — so `object_class_schema` is dead on both the live and the dry in-process LLM paths. It looks exactly like the waste this branch removed on the search arm by not building a `SearchObjectAssignment` at all. It measures around 290 µs per call for a modest nested model: noise beside a live LLM round trip, but roughly a fifth of the leaf's cost on the dry-run path `pipelex validate` walks per pipe.++### Why you cannot just delete it++That call is what still *incidentally* proves the output class can emit a JSON schema on the LLM path. The search arm now has an explicit check:++```bash+grep -rn "_validate_schema_is_generable" pipelex/+# dry_mock.py:465: _validate_schema_is_generable(output_class=output_class)+# dry_mock.py:470:def _validate_schema_is_generable(*, output_class: type[BaseModel]) -> None:+```++The LLM arm has none. Deleting the assignment's schema call without adding the explicit check there would re-open, on the LLM path, precisely the hole the review just closed on the search path: polyfactory mocks an undescribable class happily, `pipelex validate` passes, and the live run dies inside the worker on a bare `PydanticInvalidForJsonSchema` — a `RuntimeError`, so no model attribution, no remedy, no error identity.++**Do them together or not at all:** add `_validate_schema_is_generable` to the LLM dry arm first, then the optimisation is safe.++---++## RF-6 — Dry search leaves report no usage++Carried over from the branch's own deferral list, which recorded it with no durable home. This section is that home.++### Verified++None of `dry_search_gen_sourced_answer`, `dry_search_gen_structured`, `dry_search_gen_structured_object` emits a usage event, where the dry LLM leaves report a synthetic job via `report_dry_llm_job` / `report_mock_usage_llm_job`:++```bash+grep -n "report_dry_llm_job\|report_mock_usage_llm_job\|def dry_search" pipelex/cogt/content_generation/dry_mock.py+# 146:def report_dry_llm_job(...)+# 158:def report_mock_usage_llm_job(...)+# 411:def dry_search_gen_sourced_answer(...)+# 419:def dry_search_gen_structured(...)+# 441:def dry_search_gen_structured_object(...)+```++So a dry run's cost/usage report shows zero search calls for a method that will make one per run.++Pre-existing — dry search never reported — and not introduced by this branch.++Deferred because it is a small **design**, not a mechanical patch: it means choosing the synthetic-search-job conventions (model name / id placeholders, whether the per-request 1M-token cost convention applies, and the dry vs `is_mock_usage` variants), and improvising those would bake in a shape the cost report has to live with.++---++## RF-7 — The relay's envelope contract is unpinned on the producing side++Cross-repo; needs a `pipelex-relay` PR.++### Verified++The relay produces the envelope:++```bash+grep -n "include_sources" ../pipelex-relay/pipelex_relay/services/web_searcher.py+# 97: include_sources=True,+```++Its own unit test asserts the **opposite** shape — a bare payload:++```bash+grep -n "search_structured" ../pipelex-relay/tests/unit/pipelex_relay/api/test_web_search.py+# 32: mock_instance.search_structured = mocker.AsyncMock(return_value={"key": "value", "items": [1, 2, 3]})+```++So the contract the gateway worker consumes is encoded nowhere on the producing side, and the one test that touches it encodes something else.++### Why it is now lower-stakes than it was++The review changed the gateway worker to recognise the envelope **structurally** rather than demand it, so a relay that stops asking for sources no longer breaks every gateway structured search — the two sides are decoupled and this is no longer a coordinated deploy. What remains is that the relay could change its response shape with nothing to notice.++Worth doing anyway, and cheap: a relay-side regression test pinning `{data, sources}`, plus a line in the relay's README or CHANGELOG naming the shape. The hazard is amplified by this branch's own reasoning — it changed the *direct* backend to `include_sources=False` because "a structured result has nowhere to put sources", and someone applying that same reasoning to the relay is the likeliest way this moves.++---++## Provenance++Findings came from a `/review` pass on `refactor/Follow-ups`: specialist reviewers (testing, maintainability, security, performance, api-contract), a red-team pass, an independent fresh-context adversarial pass, and a Codex adversarial pass. Claims that survived were re-verified by hand — the silent-envelope corruption, the schema-generability regression and the `validate_by_alias` edge were each proven or disproven by running pydantic directly rather than by reading. Several confident-sounding findings did **not** survive and are deliberately absent: `by_alias=True` was attacked with `serialization_alias`≠`validation_alias`, `AliasChoices`, `AliasPath`, `extra="allow"` and the real spec classes without producing a regression, and the "json dump mode breaks strict types" claim is already the deliberately-deferred residue recorded in the branch's own notes.diff --git a/wip/refactoring/review-follow-ups.md b/wip/refactoring/modularity-review-follow-ups.mdsimilarity index 100%rename from wip/refactoring/review-follow-ups.mdrename to wip/refactoring/modularity-review-follow-ups.mddiff --git a/wip/refactoring/revalidate-against-object-class-is-duplicated-three-ways.md b/wip/refactoring/revalidate-against-object-class-is-duplicated-three-ways.mddeleted file mode 100644index 7682d099f..000000000--- a/wip/refactoring/revalidate-against-object-class-is-duplicated-three-ways.md+++ /dev/null@@ -1,39 +0,0 @@-# `_revalidate_against_object_class` exists three times, in two repos--Surfaced while reviewing PR #1076 (`refactor/Exec`). Not caused by that PR — but that PR made the copies **diverge**, which is what turns tolerable duplication into a trap.--## The three sites--| where | shape | dump |-|---|---|---|-| `pipelex/cogt/content_generation/content_generator.py` — `_revalidate_against_object_class` | `BaseModel` in | `model_dump(serialize_as_any=True)` |-| `pipelex-temporal` — `tprl_content_generation/content_generator_in_workflow.py:52` | `BaseModel` in | `model_dump(mode="json", serialize_as_any=True)` |-| `pipelex/cogt/content_generation/content_generator.py` — inlined in `make_search_structured` | `dict` in | n/a (already a dict) |--All three implement the same contract: validate the leaf's data against the caller's original class, and on the dry path re-raise a `ValidationError` as `DryRunObjectFidelityError` naming the class and the `examples` / `mock_format` remedy. The dry/live split, the `try`/`except`, and most of the explanatory docstring are duplicated verbatim.--## Why the copies exist--The first two are the two implementations of `ContentGeneratorProtocol` — the direct/inline backend and the workflow arm. The plugin could not reuse core's version for one reason only: it is `_`-private. It already imports `assignment_models`, `content_generator_protocol` and `exceptions` from that same package, so nothing else was in the way.--The one real difference is `mode="json"`, needed because the Temporal object crossed a payload boundary and some fields only round-trip cleanly in json mode. That is a parameter, not a reason for a second function.--## What #1076 changed, and why it matters now--Core's copy gained an `isinstance(raw_obj, object_class)` short-circuit, to stop the caller's validators running twice when the leaf already built from the real class. The Temporal copy did **not** get it.--That is correct today: across `workflow.execute_activity` the object is always an instance of the class rebuilt from `__kajson_class_source__`, never of `object_class`, so the conversion is always needed. But it is now a latent trap — if that path ever hands back the caller's real class (a local activity, an in-process shortcut, a converter change), it will double-validate exactly the way core's did before #1076, and nothing links the two files to make anyone notice. The reasoning about instructor returning a *subclass*, which is why the check is `isinstance` and not `type(...) is`, lives only in core's docstring.--## What doing it looks like--1. Promote one public helper into `pipelex.cogt.content_generation` — the plugin already imports from that package, so this needs no new boundary.-2. Give it the dump mode as a parameter rather than forking the function. **Do not** unify blindly on `mode="json"` for the in-process path: it coerces values (datetime → str and back) and the round-trip's edge cases are unaudited — see `wip/refactoring/boundary-revalidation-round-trip-is-unaudited.md`, which is about exactly this conversion.-3. Fold the `make_search_structured` inline into it, or give the dict-in case its own thin entry point on the same helper, so the fidelity-error contract has one home. The dict arm has no `isinstance` short-circuit (a dict is never an instance of the class), so its validation is the single one — and that shapes the search-path fix: see the dry-arm double-validation trap recorded in `wip/refactoring/structured-search-still-rebuilds-in-process.md`, which the helper's contract must accommodate.-4. Then delete the plugin's copy and have it call the shared one.--The prize is not line count — it is that the fidelity-error contract, and the `isinstance`-not-`type` reasoning, stop being things you have to already know to get right.--## Related--- `wip/refactoring/boundary-revalidation-round-trip-is-unaudited.md` — what the shared helper's boundary arm actually does, and what has not been checked about it.-- `wip/refactoring/structured-search-still-rebuilds-in-process.md` — the search path's other half of the same story.diff --git a/wip/refactoring/structured-search-still-rebuilds-in-process.md b/wip/refactoring/structured-search-still-rebuilds-in-process.mddeleted file mode 100644index 81f1a18b4..000000000--- a/wip/refactoring/structured-search-still-rebuilds-in-process.md+++ /dev/null@@ -1,44 +0,0 @@-# The in-process structured-search path still rebuilds the output class from its schema--Deferred out of PR #1076 (`refactor/Exec`). That PR fixed the same bug on the LLM object paths; this is the one instance it deliberately left.--## What it is--`ContentGenerator.make_search_structured` (`pipelex/cogt/content_generation/content_generator.py`) holds the caller's `output_structure_class` and never threads it down. `search_generate.search_gen_structured` and `dry_mock.dry_search_gen_structured` both still call `SchemaToModelFactory.make_from_json_schema` unconditionally.--So a `PipeSearch` with a structured (non-text) output still hands the provider a class rebuilt from JSON schema, which loses exactly what #1076 established the rebuild loses:--- custom `@field_validator` / `@model_validator` logic-- `json_schema_extra` format/pattern hints-- the output structure's own description (its class docstring)--It is the same defect, in the same shape, roughly four lines from being fixed.--## Why it was not done in #1076--Not because it is hard — because of what it drags with it. Threading the class down changes a *second* error-class surface the same way the object path's changed: the dry mock would then be built from the real class, so `test_dry_search_structured_fidelity_gap_raises_typed_error` stops producing `DryRunObjectFidelityError` and starts producing `DryRunMockBuildError`. That needs its own test re-scoping and its own review pass. #1076 was already at bot-clean state when this surfaced, and quietly widening it there would have landed an unreviewed behavior change on a second surface.--## ⚠ "Mirror the object path exactly" is not quite enough — the dry arm has a double-validation trap--The search leaf is **dict-out by contract** (`search_gen_structured -> dict[str, Any]`; that is what keeps the dynamic class off the Temporal wire), and `make_search_structured`'s inline re-validation of that dict is the *single* validation on the live path. That difference from the object path matters when threading the class down:--- **Dry arm (confirmed in code):** `dry_search_gen_structured` builds the mock and *dumps it to a dict*; the submitter then re-validates the dict. Hand the real class to `build_mock_object` naively and the caller's validators run at mock build **and again** on the dumped data — a transforming validator produces `INV-INV-…` in dry mode, the exact defect class #1076 fixed on the object path with the `isinstance` short-circuit. That short-circuit cannot apply as-is to a dict. So the fix needs one extra decision: either the in-process dry arm returns the mock *instance* (the leaf's in-process return widens to instance-or-dict and the shared helper's model arm short-circuits), or the submitter skips re-validation when the class was in hand at the leaf.-- **Live arm (unverified):** the workers pass the schema class into the provider SDK (`linkup_search_worker` hands it to `async_search(structured_output_schema=…)`). Check whether the SDK internally instantiates that class before returning the dict — if it does, threading the real class in makes the caller's validators run inside the SDK and again in the submitter, the same double-run.--This interacts with the shared-helper design in `wip/refactoring/revalidate-against-object-class-is-duplicated-three-ways.md` (the helper needs a dict arm without the short-circuit), which is one more reason to do that consolidation first.--## What doing it looks like--Mirror the object path — adjusted for the dict-out contract above:--1. `search_gen_structured(search_object_assignment, *, output_class: type[BaseModel] | None = None)`, same keyword-only shape, `None` = boundary.-2. Same for `dry_search_gen_structured`.-3. Resolve through `object_class_resolution.resolve_object_class`'s sibling (it currently takes an `ObjectAssignment`; `SearchObjectAssignment` carries the same two fields under different names, so either generalize the helper over the two field names or add a thin second entry point — do **not** duplicate the `SchemaToModelFactory` call).-4. `make_search_structured` passes `output_class=output_structure_class`.-5. Re-scope `test_dry_search_structured_fidelity_gap_raises_typed_error` to the boundary composition, exactly as `test_dry_run_object_fidelity.py` was.--`SearchObjectAssignment`'s wire shape must not change, for the same reason `ObjectAssignment`'s did not.--## Related--- `wip/refactoring/boundary-revalidation-round-trip-is-unaudited.md` — the other deferral out of the same PR.