Skip to content

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

feat(run): a run's results carry the I/O artifacts that describe its data (#1195)

Louis Choquel0c3dd3a34f31
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index dae687201..782427d8c 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,8 +1,8 @@
contract = "cli-docs"
-digest = "sha256:0dc602377aa1b1aab044025bbe8935467d71ae88b3098978f4e3a1adf6a55ed7"
+digest = "sha256:7e55677c7b9478aa63196079905ef3df321fdba98eb27592d9fe7754e03f2a50"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-09-07T06:07:51Z"
-rationale = "Re-ack after the round-1 review changed the same trigger files. The review found the docs half wrong in two ways and both are fixed here. First, I had listed --version under 'Global flags', whose lead sentence promises the flags are position-agnostic; only --no-logo and --traceback are, because PipelexCLI.make_context strips those two out of args by hand, and 'pipelex show --version' really does answer 'No such option'. The flag now sits outside that list with a sentence saying it goes before any subcommand. Second, the handshake section and the module docstring described mthds's PipelexRunner as already parsing these lines; it does not — the Python runner still raises and the TypeScript one assigns stdout wholesale — so the prose now states the contract a consumer should follow (match on the label, never take stdout as one version string) and says plainly that no consumer parses it yet. Filed the two consumer items, L-260907-da820f and L-260907-1aa8cf. Re-reviewed pipelex/cli/agent_cli/CLAUDE.md: its only mention is the code-layout line naming the version callback in _agent_cli.py, still accurate, and an eager --version short-circuits before the success and error format streams that doc's contract sections govern."
+reviewed_at = "2026-09-07T13:48:53Z"
+rationale = "The agent CLI now applies its graphs-inclusion override (graphspec on, viewer on, mermaid off) before the run instead of at render time, so the graphspec's companions are built in the run window whatever graphspec_json the user configured. Reviewed docs/tools/cli/agent-cli.md: the Graph Visualization section describes the files a run writes and named no inclusion flag, so it stays true. Updated pipelex/cli/agent_cli/CLAUDE.md: the run contract line now says the inclusion is settled before the run rather than that the companions follow the flag. No flag or option changed."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
@@ -39,7 +39,7 @@ rationale = "Re-ack after the round-1 review changed the same trigger files. The
"pipelex/cli/agent_cli/commands/plxt_passthrough.py" = "blob:a1c530d110482485ce462f199b9e79fac29f8896"
"pipelex/cli/agent_cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/run/_output_helpers.py" = "blob:40ed1700e0d5e86d7696eadd7f9887baeb8059f6"
-"pipelex/cli/agent_cli/commands/run/_run_core.py" = "blob:9feae5b136a7399d30a9c221bf6f218ef1443395"
+"pipelex/cli/agent_cli/commands/run/_run_core.py" = "blob:aeb90b4b2149fc6c977adaf1d9f535549cb34068"
"pipelex/cli/agent_cli/commands/run/_run_core_api.py" = "blob:78a27e0ba91e6bbf99c11caedb29ad4cf20ac78b"
"pipelex/cli/agent_cli/commands/run/app.py" = "blob:64b2ecc02007cda11b526d8d3fc139593875dd9d"
"pipelex/cli/agent_cli/commands/run/bundle_cmd.py" = "blob:daf6207146c0ea41fe34bb272ed51350208af790"
@@ -111,7 +111,7 @@ rationale = "Re-ack after the round-1 review changed the same trigger files. The
"pipelex/cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/run/_inputs_file_loader.py" = "blob:dde781f846968b667a0acfb4b3e3cea01cef7049"
"pipelex/cli/commands/run/_inputs_path_resolver.py" = "blob:c8ec89d98718e18af7aaaded44c9f545be60adab"
-"pipelex/cli/commands/run/_run_core.py" = "blob:2659db67a5c929f8de1dd47e2bbb729563ef1e2f"
+"pipelex/cli/commands/run/_run_core.py" = "blob:21658e84a1f23be0ce12801bfdb17268c37f797f"
"pipelex/cli/commands/run/app.py" = "blob:a7090b0ff6bf2f1d47827fa27d2a138096a2e148"
"pipelex/cli/commands/run/bundle_cmd.py" = "blob:cb420bf4879c863d64c5e20ed535c42732b720a2"
"pipelex/cli/commands/run/exceptions.py" = "blob:e9552226e597922b6ac0757f7b52eb880a2e1472"
diff --git a/.drift/acks/hub-layering-convention.toml b/.drift/acks/hub-layering-convention.toml
index 9e1ef3471..ac603fb4f 100644
--- a/.drift/acks/hub-layering-convention.toml
+++ b/.drift/acks/hub-layering-convention.toml
@@ -1,10 +1,10 @@
contract = "hub-layering-convention"
-digest = "sha256:28bbb28a72966c425d409154d0ae3c8c07bdff6e1ce01e0e0a7fb3b5897d94f7"
+digest = "sha256:db6f431f6d19eada9e44890a88a38218c5ec408e4bd603ebd0ea3a2119d6c7dd"
reviewed_by = "Louis Choquel"
-reviewed_at = "2026-08-17T08:18:22Z"
-rationale = "The trigger is runtime_hub.py, and the change is reset_boot_state releasing the isolated-execution probe: a body and a docstring, with no accessor added, renamed or removed. Re-derived the partition table rather than reading it - enumerated every public module-level function in pipelex/runtime_hub.py by AST and checked each against docs/contribute/hub-layering.md, and every one is named there, so the table is still complete and the probe's accessor is_in_isolated_execution keeps its existing reporting row. The page specifies the boundary and the accessor partition and says nothing about what a teardown releases, so the release reaches no sentence in it. No doc change needed."
+reviewed_at = "2026-09-07T12:04:46Z"
+rationale = "interpreter_hub gains get_own_pipes, a library-lookup accessor beside get_pipes returning the current library's own pipes without the aliased dependency entries. Added it to the library-lookups row of the accessor partition table in docs/contribute/hub-layering.md; the boundary, the one-arrow rule and the closure claim are untouched."
[trigger_files]
"pipelex/cli/dev_cli/commands/hub_layering_guard.py" = "blob:2dbadcbab7d44364a7b5f1d16268b23b26700a00"
-"pipelex/interpreter_hub.py" = "blob:b8c35e37814f0e94c3bf1c364b06a98d0c22ee93"
+"pipelex/interpreter_hub.py" = "blob:327e75d0fbb5bdf46f6cbf06024f83840f0106d0"
"pipelex/runtime_hub.py" = "blob:498312f15921753263a4ad3475c9da5eefb8e4ba"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index abcc9da46..26405f647 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,7 @@
### Added
+- **A run's results carry the I/O artifacts that describe its data:** beside `graphspec.json`, and gated by the same `graphspec_json` inclusion flag, a run now writes `pipe_io_contracts.json`, `input_form.json` and `output_form.json`, the validation report's own artifacts under the standard's names, keyed by namespaced `pipe_ref` for every pipe of the library the run executed against (its own pipes, not a dependency package's aliased entries), which is the validated bundle plus whatever `library_dirs` loaded beside it. A graph viewer shows a data node's value only when it holds the contracts and the output form, and until now only `/validate` produced them, so every consumer of a run's graph either took the no-data floor or paired the graph with a validation of some other bundle text. They are built once at the end of the run, inside its library window, and ride on `PipeOutput.pipe_io_artifacts` beside `graph_spec` (a build failure of any kind lands on `pipe_io_artifacts_error`, never failing the run nor skipping its delivery); the SPI payload carries them as `pipe_io_artifacts_dump`, ready for the synchronous `/execute` response to relay once the API reads the field. `pipelex run`, `pipelex-agent run` (which also names the three paths in its `graph_files`, and settles its graph inclusion before the run so the companions are always built with its graphspec) and the direct-mode delivery executor all write them; a graphspec written into a reused directory removes, with a warning, an earlier run's companions when the new run carries none; a run hosted on our Temporal plugin writes `graphspec.json` without its siblings until the plugin builds them in the crate's window; the fixture corpus is unchanged, since the corpus generator now renders through the same function. See [Execution Graph Tracing](under-the-hood/execution-graph-tracing.md#outputs).
- **The `--version` handshake reports three numbers (breaking):** `pipelex --version` and `pipelex-agent --version` now print the runtime version, the MTHDS Protocol version and the MTHDS standard version, one `<label> <version>` line each, instead of the runtime version alone. A client needs all three to know what it is talking to, and they move on independent cadences under the standard's own versioning rule, so no one of them can be inferred from another. The first line keeps its historical `<program> <version>` form, so a consumer that matches a version out of the text is unaffected — but one that treats the whole of stdout as a single version string now holds three lines, and both `mthds` runners have to be adapted. Match on the label, not on the shape of the output as a whole. The two MTHDS numbers are read from the `mthds` package rather than restated here. See [CLI Reference](tools/cli/index.md#the-version-handshake).
### Changed
diff --git a/docs/contribute/hub-layering.md b/docs/contribute/hub-layering.md
index 40ecce5f6..535917130 100644
--- a/docs/contribute/hub-layering.md
+++ b/docs/contribute/hub-layering.md
@@ -58,7 +58,7 @@ There is deliberately **no** `pipelex.hub`. It was deleted rather than kept as a
| --- | --- |
| container | `InterpreterHub`, `get_interpreter_hub`, `set_interpreter_hub` |
| library manager | `get_library_manager`, `get_library` |
-| library lookups | `get_concept_library`, `get_required_concept`, `get_native_concept`, `get_required_domain`, `get_optional_domain`, `get_pipe_library`, `get_pipes`, `get_required_pipe`, `get_optional_pipe`, `get_required_entry_pipe`, `get_optional_entry_pipe`, `get_pipe_source` |
+| library lookups | `get_concept_library`, `get_required_concept`, `get_native_concept`, `get_required_domain`, `get_optional_domain`, `get_pipe_library`, `get_pipes`, `get_own_pipes`, `get_required_pipe`, `get_optional_pipe`, `get_required_entry_pipe`, `get_optional_entry_pipe`, `get_pipe_source` |
| current-library contextvar | `set_current_library`, `get_current_library`, `get_current_library_id_or_none`, `clear_current_library`, `scoped_current_library` |
| library dirs | `resolve_library_dirs`, `get_default_library_dirs` |
| pipe router | `get_pipe_router`, `set_pipe_router`, `teardown_current_pipe_router`, `scoped_pipe_router` |
diff --git a/docs/tools/cli/agent-cli.md b/docs/tools/cli/agent-cli.md
index 765957ca8..0389abe2e 100644
--- a/docs/tools/cli/agent-cli.md
+++ b/docs/tools/cli/agent-cli.md
@@ -200,3 +200,5 @@ For the structured commands, exactly one such object is written to stderr per fa
## Graph Visualization
Graph visualization is available through the `validate bundle` subcommand with the `--graph` flag, and through `run` subcommands where it is enabled by default. Use `--no-graph` on `run` to disable it.
+
+A `run` with the graph on writes, beside its bundle, the ReactFlow viewer (`dry_run.html` or `live_run.html`) and the graph itself: `graphspec.json` on a dry run, `live_run_graph.json` on a live run. Beside the graph, under their canonical names whatever the graph file is called, sit the three files that describe its data: `pipe_io_contracts.json`, `input_form.json` and `output_form.json`, the same artifacts `validate` reports under those names, keyed by namespaced `pipe_ref`. A graph viewer resolves them from the graph file's directory, not from its name. With `--with-memory`, the JSON envelope's `graph_files` object names every one of these paths (`graph_html`, `graph_spec` on a live run, `pipe_io_contracts`, `input_form`, `output_form`).
diff --git a/docs/tools/cli/run.md b/docs/tools/cli/run.md
index 29df6f7e3..6eafa5210 100644
--- a/docs/tools/cli/run.md
+++ b/docs/tools/cli/run.md
@@ -212,6 +212,18 @@ country = "France"
The output JSON contains the complete working memory after pipeline execution, including all intermediate results and the final output.
+### The results directory
+
+Each run that saves anything gets its own numbered directory under `--output-dir` (`results/<pipe_code>_output_01/`, then `_02`, and so on). With `--save-working-memory` it holds `working_memory.json`, with `--save-main-stuff` the `main_stuff.*` renders, and with `--graph` the graph outputs that `graphs_inclusion` enables: `graphspec.json`, the Mermaid code and viewer, and the ReactFlow viewer.
+
+Beside `graphspec.json`, and gated by the same `graphspec_json` flag, the run writes the three files that describe the data the graph carries:
+
+- `pipe_io_contracts.json` - each pipe's input and output contract, with the JSON Schema of its output
+- `input_form.json` - each pipe's input-form descriptor
+- `output_form.json` - each pipe's output-form descriptor
+
+They are the same artifacts a validation report returns under those names, keyed by namespaced `pipe_ref` for every pipe in the library the run executed against, and they are what a graph viewer needs to show a data node's value rather than only the concept's structure: the VS Code extension reads them from the graphspec's own directory. A run with `--no-graph` writes none of them. See [Execution Graph Tracing](../../under-the-hood/execution-graph-tracing.md#outputs).
+
### Absent main output
A run whose main output resolves as a recorded absence (an optional `?` output that produced nothing — e.g. a `PipeCondition` `continue` outcome, or a skipped producer) is a **successful** run. The CLI prints the absence with its reason, and `--save-main-stuff` writes an explicit absence artifact instead of a value dump: `main_stuff.json` is `{"absent": true, ...}` with the absence record, and `main_stuff.md` is a human-readable summary including the provenance chain (no HTML render or interactive viewer is produced — there is nothing to view). `--save-csv` fails with an explicit error and a non-zero exit code, the same way it does for any main output that is not a flat list — there is no tabular value to save.
diff --git a/docs/under-the-hood/execution-graph-tracing.md b/docs/under-the-hood/execution-graph-tracing.md
index 00e2a77b1..99dde6f77 100644
--- a/docs/under-the-hood/execution-graph-tracing.md
+++ b/docs/under-the-hood/execution-graph-tracing.md
@@ -90,10 +90,15 @@ graph_spec = response.pipe_output.graph_spec
| Output | File | Purpose |
|--------|------|---------|
| `graphspec_json` | `graphspec.json` | Canonical graph representation |
+| `graphspec_json` | `pipe_io_contracts.json` | The graphspec's companion: each pipe's I/O contract, keyed by `pipe_ref` |
+| `graphspec_json` | `input_form.json` | The graphspec's companion: each pipe's input-form descriptor |
+| `graphspec_json` | `output_form.json` | The graphspec's companion: each pipe's output-form descriptor |
| `mermaidflow_mmd` | `mermaidflow.mmd` | Mermaid flowchart code |
| `mermaidflow_html` | `mermaidflow.html` | Standalone Mermaid viewer |
| `reactflow_html` | `reactflow.html` | Interactive ReactFlow viewer |
+The three companions are the validation report's `pipe_io_contracts`, `input_form` and `output_form` under the standard's names: a graph carries every payload the run produced and nothing that says what those payloads are, and a graph viewer (`@pipelex/mthds-ui`'s `GraphViewer`) shows a data node's value only when it holds both the contracts and the output form for the producing `pipe_ref`. They are built once, at the end of `PipeRun.run` inside the run's own library window (the builders need the loaded library, which `PipelineRunner.execute` tears down before the CLI writes anything), over the run library's own pipes (the validated bundle and whatever `library_dirs` loaded beside it; a dependency package's pipes are keyed by alias in the library and described by no blueprint the host holds, so they are left out, as a validation of the bundle leaves them out), and carried on `pipe_output.pipe_io_artifacts` beside `graph_spec`; a failure of the builders, whatever its kind, is reported on `pipe_output.pipe_io_artifacts_error`, mirroring `graph_assembly_error`, and never fails the run: the build sits in the run's `finally` ahead of the delivery, so an exception escaping it would replace the run's outcome and skip the delivery of a run that completed. The build is gated by `describe_pipe_io` on the trace context, which the run setup derives from `graphspec_json`, and which validate's own graph dry run turns off since validate already built the artifacts for its report. Every writer that serializes the graphspec writes them beside it: `save_graph_outputs_to_dir` for the CLIs, the delivery executor for a hosted results prefix. They follow the `graphspec_json` inclusion flag, so a run that asks for no graphspec builds nothing that describes one, and a written graphspec owns the three names beside it: when the run carries no artifacts, a companion left by an earlier run in the same directory is removed, with a warning naming it, rather than paired with the new graph. The agent CLI, which always writes a graphspec with `--graph`, applies that inclusion before the run so the companions are built in the window rather than lost to a render-time override. Their bytes are those of the projection fixture corpus for the same bundle, since both go through `render_pipe_io_artifact_files` (`pipelex/core/pipes/pipe_io_artifacts.py`). The `pipe_io_artifacts` field crosses the SPI payload as `pipe_io_artifacts_dump`; the synchronous `/execute` response carries the description once the API relays that field, and a hosted run's results prefix once our Temporal plugin builds the artifacts in the crate's window.
+
---
## Architecture
@@ -265,7 +270,7 @@ graph_spec = manager.close_tracer(pipeline_run_id)
Trace events travel through an `EventLogProtocol` backend (`pipelex/tracing/`): the tracer emits events into it during the run (write side, wired in `pipeline_run_setup`), and `assemble_tracing` reads them back after the run to build the `GraphSpec` and usage aggregates (read side, triggered from `PipeRun.run`). Both sides normally build their backend instance independently from `tracing_config` via `make_event_log` — NDJSON files or DynamoDB bridge the two instances through external storage.
-The assembled usage rides back on `pipe_output.tokens_usages` (with any assembly failure on `usage_assembly_error`), which the sync `/execute` response returns directly. For delivery-enabled runs (a storage target set), the delivery executor (`pipelex/pipe_run/delivery_executor.py`) also persists it as a `tokens_usages.json` result artifact — `{"tokens_usages": [...], "usage_assembly_error": null}` — next to `working_memory.json`, the `main_stuff.*` renders, and the graph outputs, so a durable client polling result files gets the same usage records a sync caller does. The artifact is written unconditionally on every successful result delivery: explicit nulls mean usage assembly was off for that run. A failed run stores no result files at all, so an absent `tokens_usages.json` means either the run failed or it was delivered before the artifact existed — tell those apart from the delivery status, not from the file's presence.
+The assembled usage rides back on `pipe_output.tokens_usages` (with any assembly failure on `usage_assembly_error`), which the sync `/execute` response returns directly. For delivery-enabled runs (a storage target set), the delivery executor (`pipelex/pipe_run/delivery_executor.py`) also persists it as a `tokens_usages.json` result artifact — `{"tokens_usages": [...], "usage_assembly_error": null}` — next to `working_memory.json`, the `main_stuff.*` renders, and the graph outputs (`graphspec.json` with its three companions `pipe_io_contracts.json`, `input_form.json` and `output_form.json`, see [Outputs](#outputs)), so a durable client polling result files gets the same usage records a sync caller does. The artifact is written unconditionally on every successful result delivery: explicit nulls mean usage assembly was off for that run. A failed run stores no result files at all, so an absent `tokens_usages.json` means either the run failed or it was delivered before the artifact existed — tell those apart from the delivery status, not from the file's presence.
For fully in-process runs, `pipelex.runtime_hub.scoped_event_log` pins one shared instance for both sides instead:
@@ -426,7 +431,7 @@ error_stack_traces = true # Include full stack traces
pipe_and_concept_registry = true # Include pipe and concept registries in the GraphSpec
[interpreter.pipeline_execution.graph.graphs_inclusion]
-graphspec_json = true # Generate GraphSpec JSON
+graphspec_json = true # Generate GraphSpec JSON, and its three companions beside it
mermaidflow_mmd = true # Generate Mermaid code
mermaidflow_html = true # Generate Mermaid HTML
reactflow_html = true # Generate ReactFlow HTML
diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.md
index a83491356..927a48099 100644
--- a/pipelex/cli/agent_cli/CLAUDE.md
+++ b/pipelex/cli/agent_cli/CLAUDE.md
@@ -17,7 +17,7 @@ Only the error format is backed by a module-level `ContextVar` in `agent_output.
Markdown structure per command:
-- `run`: `# Pipeline run complete`, a `## Result` section (the rendered `main_stuff` markdown with `--with-memory`, otherwise the concept JSON in a fenced block), and output / graph file paths. Cost is machine-first: on the local runner, when costs are on (`--costs`, the default) and the run did reportable work (any tokens or any cost), a best-effort `cost_report` object (`{total_cost, by_model: [...]}`, real USD) rides the JSON `--with-memory` envelope — there is **no** Rich cost table on stderr (unlike the human `pipelex run` CLI). The markdown renderer ignores the `cost_report` key, so it is JSON-only. A free/zero-price model still reports its token usage (with `total_cost` 0). The `cost_report` is **absent** when the run did no reportable work (dry runs), when `--no-costs` is passed, on the API-runner path (which does not assemble local usage), or if cost-summary aggregation fails (caught and skipped so it never fails an otherwise-successful run) — so consumers must treat it as optional.
+- `run`: `# Pipeline run complete`, a `## Result` section (the rendered `main_stuff` markdown with `--with-memory`, otherwise the concept JSON in a fenced block), and output / graph file paths. With the graph on, the `graph_files` object of the `--with-memory` envelope names the viewer (`graph_html`), the graph on a live run (`graph_spec`, the graphspec renamed `live_run_graph.json`) and the graph's three companions written beside it under their canonical names (`pipe_io_contracts`, `input_form`, `output_form` — the validate artifacts describing the graph's data, keyed by `pipe_ref`); the agent CLI settles its graph inclusion (graphspec on, viewer on) before the run rather than at render time, since the companions are built inside the run's library window under that same flag; a viewer resolves them from the graph file's directory, so the rename never moves them. Cost is machine-first: on the local runner, when costs are on (`--costs`, the default) and the run did reportable work (any tokens or any cost), a best-effort `cost_report` object (`{total_cost, by_model: [...]}`, real USD) rides the JSON `--with-memory` envelope — there is **no** Rich cost table on stderr (unlike the human `pipelex run` CLI). The markdown renderer ignores the `cost_report` key, so it is JSON-only. A free/zero-price model still reports its token usage (with `total_cost` 0). The `cost_report` is **absent** when the run did no reportable work (dry runs), when `--no-costs` is passed, on the API-runner path (which does not assemble local usage), or if cost-summary aggregation fails (caught and skipped so it never fails an otherwise-successful run) — so consumers must treat it as optional.
- `validate`: `# Validation passed`, the bundle path when relevant, and a list of validated pipes with their status. Every entry in `validated_pipes` (markdown and JSON) identifies its pipe by the namespaced `pipe_ref` (`domain.code`) — the same unambiguous identity across `validate all`, `validate bundle`, and `validate pipe`, so the same pipe is never reported under two identifiers. `validate bundle`, `validate method`, and `validate all` carry `pending_signatures` — the library-wide list of pipes still declared as `PipeSignature` (unimplemented forward declarations), namespaced by `pipe_ref` — rendered as a "Pending signatures" section in markdown. They also carry a derived `is_runnable` boolean (`true` ⇔ `pending_signatures` is empty), and the markdown adds an explicit plain-English runnability verdict on those surfaces: a complete bundle/library states it is runnable, while one with pending signatures states it is NOT yet runnable immediately above the verbatim "Pending signatures" heading. These whole-bundle/whole-library surfaces are **strict by default**: they exit non-zero on `not is_runnable` unless `--allow-signatures` is passed (which both tolerates the placeholders for the exit code and mock-runs the signature pipes in the sweep). Single-pipe surfaces make no library-wide runnability claim and never gate the exit code on it: bare `validate pipe <code>` omits the key and emits no verdict, while `validate bundle`/`validate method` with `--pipe` still surface the library-wide `pending_signatures` for information but do not gate on it (the requested slice can be fully implemented even when unrelated placeholders remain elsewhere). The whole-bundle and whole-library surfaces also carry a `warnings` array — the advisory lints, rendered as a "Warnings" section in markdown — assembled by `pipelex/pipeline/advisory_warnings.py`, the ONE composition point every advisory-bearing channel calls (this CLI, the bare CLI, the builder ops and the protocol report). Bare `validate pipe <code>` carries none, and neither does the builder's `validate_all`; `validate bundle` / `validate method` with `--pipe` DO carry them, because they validate the whole bundle and only narrow the dry run, so the array stays bundle-wide there. Add a new advisory family there, never at a call site: the sites used to assemble their own and disagreed about which families they carried.
- `fix`: `# Fix applied - bundle is valid` after one or more fixes, `# Bundle already valid` when the loop had nothing to apply, or `# Bundle valid but not runnable` when pending `PipeSignature` placeholders remain. The JSON success envelope carries `is_valid`, `bundle_path`, `iterations`, `fixes_applied`, `files_written`, `remaining_errors`, and, on successful validation, `pending_signatures` plus `is_runnable`. Whole-bundle fix runs are strict by default: they emit the success envelope but exit 1 on `not is_runnable` unless `--allow-signatures` is passed. A still-invalid verdict exits 1 via `FixBundleError` on stderr with the same structured result fields plus any `bail_reason`.
- `migrate`: `# Configuration migration`, the mode (applied / dry run) and verdict, the directories walked, a files-walked/changed/written count, then one `## <path>` section per file that is not clean listing the entries applied, the entries blocked with their reason and guidance, and any unexplained paths. Paths, operation kinds and ledger-supplied values only — no value read from the user's file is ever rendered, in either format.
diff --git a/pipelex/cli/agent_cli/commands/run/_run_core.py b/pipelex/cli/agent_cli/commands/run/_run_core.py
index 9feae5b13..aeb90b4b2 100644
--- a/pipelex/cli/agent_cli/commands/run/_run_core.py
+++ b/pipelex/cli/agent_cli/commands/run/_run_core.py
@@ -5,7 +5,7 @@ from __future__ import annotations
import json
import shutil
from pathlib import Path
-from typing import Any
+from typing import TYPE_CHECKING, Any
from pipelex import log
from pipelex.base_exceptions import PipelexError
@@ -19,6 +19,21 @@ from pipelex.pipeline.runner import PipelexMTHDSProtocol
from pipelex.system.pipe_run_mode import PipeRunMode
from pipelex.tools.misc.json_utils import clean_json_dumps
+if TYPE_CHECKING:
+ from pipelex.system.configuration.configs import PipelineExecutionConfig
+
+
+def _with_agent_graphs_inclusion(*, execution_config: PipelineExecutionConfig) -> PipelineExecutionConfig:
+ """The agent CLI's graph outputs: the graphspec and the ReactFlow viewer, never the Mermaid page."""
+ graphs_inclusion = execution_config.graph.graphs_inclusion.model_copy(
+ update={
+ "graphspec_json": True,
+ "mermaidflow_html": False,
+ "reactflow_html": True,
+ }
+ )
+ return execution_config.model_copy(update={"graph": execution_config.graph.model_copy(update={"graphs_inclusion": graphs_inclusion})})
+
async def run_pipeline_core(
pipe_code: str,
@@ -68,6 +83,12 @@ async def run_pipeline_core(
generate_usage=costs,
mock_inputs=mock_inputs or None,
)
+ if graph:
+ # The agent CLI writes the graphspec and the ReactFlow viewer whatever the configured inclusion
+ # says. The override is applied before the run, not at render time: the run setup gates the
+ # graphspec's companion artifacts on this same flag, and they are built inside the run's library
+ # window, which is gone by the time anything is rendered.
+ execution_config = _with_agent_graphs_inclusion(execution_config=execution_config)
runner = PipelexMTHDSProtocol(
bundle_uris=bundle_uris,
@@ -150,7 +171,7 @@ async def run_pipeline_core(
# Generate and save graph visualizations if requested
if graph and pipe_output.graph_spec:
graph_config = execution_config.graph
- # Enable ReactFlow HTML output and data inclusion for the render
+ # Full data inclusion for the render (the graphs inclusion was settled before the run)
render_graph_config = graph_config.model_copy(
update={
"data_inclusion": graph_config.data_inclusion.model_copy(
@@ -160,13 +181,6 @@ async def run_pipeline_core(
"stuff_html_content": True,
}
),
- "graphs_inclusion": graph_config.graphs_inclusion.model_copy(
- update={
- "graphspec_json": True,
- "mermaidflow_html": False,
- "reactflow_html": True,
- }
- ),
}
)
@@ -174,6 +188,7 @@ async def run_pipeline_core(
graph_spec=pipe_output.graph_spec,
graph_config=render_graph_config,
pipe_code=pipe_code,
+ pipe_io_artifacts=pipe_output.pipe_io_artifacts,
)
saved_files = save_graph_outputs_to_dir(graph_outputs=graph_outputs, output_dir=output_dir)
@@ -193,6 +208,13 @@ async def run_pipeline_core(
shutil.move(str(graphspec_path), str(final_graphspec_path))
side_effects.setdefault("graph_files", {})["graph_spec"] = str(final_graphspec_path)
+ # The graphspec's companions keep their canonical names beside it: a reader resolves them
+ # from the graphspec's directory, not from its name.
+ for output_key in ("pipe_io_contracts_json", "input_form_json", "output_form_json"):
+ companion_path = saved_files.get(output_key)
+ if companion_path:
+ side_effects.setdefault("graph_files", {})[output_key.removesuffix("_json")] = str(companion_path)
+
# Save output JSON (includes side-effect paths for on-disk reference)
output_filename = "dry_run.json" if dry_run else "live_run.json"
output_path = output_dir / output_filename
diff --git a/pipelex/cli/commands/run/_run_core.py b/pipelex/cli/commands/run/_run_core.py
index 2659db67a..21658e84a 100644
--- a/pipelex/cli/commands/run/_run_core.py
+++ b/pipelex/cli/commands/run/_run_core.py
@@ -282,6 +282,7 @@ async def _execute_run(
graph_spec=graph_spec,
graph_config=execution_config.graph,
pipe_code=pipe_code,
+ pipe_io_artifacts=pipe_output.pipe_io_artifacts,
)
saved_graph_files = save_graph_outputs_to_dir(graph_outputs=graph_outputs, output_dir=output_path)
diff --git a/pipelex/cli/dev_cli/commands/generate_projection_corpus_cmd.py b/pipelex/cli/dev_cli/commands/generate_projection_corpus_cmd.py
index b469c355c..dfa0b7a9b 100644
--- a/pipelex/cli/dev_cli/commands/generate_projection_corpus_cmd.py
+++ b/pipelex/cli/dev_cli/commands/generate_projection_corpus_cmd.py
@@ -47,6 +47,7 @@ from pipelex.cli.dev_cli.commands.projection_reference import (
project_inputs_template,
)
from pipelex.cli.error_handlers import ErrorContext
+from pipelex.core.pipes.pipe_io_artifacts import render_pipe_io_artifact_files
from pipelex.interpreter_hub import (
clear_current_library,
get_concept_library,
@@ -63,9 +64,9 @@ from pipelex.pipe_machinery.rendering.input_renderer import (
serialize_inputs_template_to_toml,
)
from pipelex.pipelex import Pipelex
+from pipelex.pipeline.build_pipe_io_artifacts import build_pipe_io_artifacts
from pipelex.pipeline.exceptions import ValidateBundleError
-from pipelex.pipeline.input_form import ListField, PipeInputFormDescriptor, build_input_form, build_output_form
-from pipelex.pipeline.pipe_io_contracts import build_pipe_io_contracts
+from pipelex.pipeline.input_form import ListField, PipeInputFormDescriptor
from pipelex.pipeline.validate_bundle import validate_bundle
from pipelex.runtime_hub import get_console
from pipelex.tools.typing.pydantic_utils import empty_list_factory_of
@@ -73,9 +74,6 @@ from pipelex.tools.typing.pydantic_utils import empty_list_factory_of
if TYPE_CHECKING:
from mthds.protocol.pipeline_inputs import PipelineInputs
-INPUT_FORM_FILE_NAME = "input_form.json"
-OUTPUT_FORM_FILE_NAME = "output_form.json"
-PIPE_IO_CONTRACTS_FILE_NAME = "pipe_io_contracts.json"
TEMPLATES_DIR_NAME = "inputs_template"
ENGINE_DIR_NAME = "engine"
MANIFEST_FILE_NAME = "manifest.json"
@@ -612,21 +610,12 @@ async def generate_projection_corpus(*, bundle_paths: list[Path], output_dir: Pa
result = await validate_bundle(mthds_contents=mthds_contents, mthds_sources=mthds_sources)
validation_library_id = get_current_library_id_or_none()
- input_form = build_input_form(result.pipes)
- _write_json(
- path=output_dir / INPUT_FORM_FILE_NAME,
- payload={pipe_ref: descriptor.model_dump(mode="json") for pipe_ref, descriptor in input_form.items()},
- )
- output_form = build_output_form(result.pipes)
- _write_json(
- path=output_dir / OUTPUT_FORM_FILE_NAME,
- payload={pipe_ref: descriptor.model_dump(mode="json") for pipe_ref, descriptor in output_form.items()},
- )
- io_contracts = build_pipe_io_contracts(result.pipes)
- _write_json(
- path=output_dir / PIPE_IO_CONTRACTS_FILE_NAME,
- payload={pipe_ref: contract.model_dump(mode="json") for pipe_ref, contract in io_contracts.items()},
- )
+ # The three artifacts through the same builder and the same rendering a run's results
+ # directory uses, so the committed corpus and a results directory hold byte-identical files.
+ artifacts = build_pipe_io_artifacts(result.pipes)
+ for file_name, text in render_pipe_io_artifact_files(artifacts).items():
+ _write_text(path=output_dir / file_name, content=text)
+ input_form = artifacts.input_form
for pipe in result.pipes:
_capture_pipe(
pipe=pipe,
diff --git a/pipelex/core/pipes/pipe_io_artifacts.py b/pipelex/core/pipes/pipe_io_artifacts.py
new file mode 100644
index 000000000..41ec0caf3
--- /dev/null
+++ b/pipelex/core/pipes/pipe_io_artifacts.py
@@ -0,0 +1,58 @@
+"""The three I/O artifacts that describe a method's data, built once and carried together.
+
+`pipe_io_contracts`, `input_form` and `output_form` are the validate report's own fields, each
+keyed by namespaced `pipe_ref`, and they are always produced together because they share one key
+set: all three iterate the same pipes. `PipeIOArtifacts` is the carrier that keeps them together
+wherever a graph travels — on `PipeOutput` beside `graph_spec`, across the SPI payload, and into a
+results directory as three sibling files beside `graphspec.json`. The one sequence that derives
+them is `build_pipe_io_artifacts` (its own module: it needs the live library, and this carrier is
+imported by `PipeOutput`, which must stay free of the library machinery).
+
+The rendering follows the projection corpus's byte discipline (two-space indent, `ensure_ascii`
+off, one trailing newline, keyed by `pipe_ref` over the JSON-mode dump), so for the same bundle a
+results directory and the committed fixture corpus hold byte-identical files.
+"""
+
+from __future__ import annotations
+
+import json
+
+from mthds.protocol.input_form import InputForm
+from mthds.protocol.output_form import OutputForm
+from mthds.protocol.pipe_io_contracts import PipeIOContracts
+from pydantic import BaseModel, ConfigDict
+
+PIPE_IO_CONTRACTS_FILE_NAME = "pipe_io_contracts.json"
+INPUT_FORM_FILE_NAME = "input_form.json"
+OUTPUT_FORM_FILE_NAME = "output_form.json"
+
+
+class PipeIOArtifacts(BaseModel):
+ """The validate report's three I/O artifacts, under the report's names and types.
+
+ A grouping, not a new shape: each field is the standard's artifact, keyed by `pipe_ref`.
+ """
+
+ model_config = ConfigDict(extra="forbid")
+
+ pipe_io_contracts: PipeIOContracts
+ input_form: InputForm
+ output_form: OutputForm
+
+
+def render_pipe_io_artifact_files(artifacts: PipeIOArtifacts) -> dict[str, str]:
+ """Render the artifacts as the three sibling files, file name to text.
+
+ Each text is the projection corpus's byte discipline over `{pipe_ref: artifact}` in JSON mode.
+ """
+ return {
+ PIPE_IO_CONTRACTS_FILE_NAME: _render_json_text(
+ {ref: contract.model_dump(mode="json") for ref, contract in artifacts.pipe_io_contracts.items()}
+ ),
+ INPUT_FORM_FILE_NAME: _render_json_text({ref: descriptor.model_dump(mode="json") for ref, descriptor in artifacts.input_form.items()}),
+ OUTPUT_FORM_FILE_NAME: _render_json_text({ref: descriptor.model_dump(mode="json") for ref, descriptor in artifacts.output_form.items()}),
+ }
+
+
+def _render_json_text(payload: dict[str, object]) -> str:
+ return json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
diff --git a/pipelex/core/pipes/pipe_output.py b/pipelex/core/pipes/pipe_output.py
index b7a9dc1ed..1a1245de5 100644
--- a/pipelex/core/pipes/pipe_output.py
+++ b/pipelex/core/pipes/pipe_output.py
@@ -4,6 +4,7 @@ from mthds.protocol.pipe_output import PipeOutputAbstract
from pydantic import Field, PrivateAttr
from pipelex.core.memory.working_memory import WorkingMemory
+from pipelex.core.pipes.pipe_io_artifacts import PipeIOArtifacts
from pipelex.core.stuffs.date_content import DateContent
from pipelex.core.stuffs.html_content import HtmlContent
from pipelex.core.stuffs.image_content import ImageContent
@@ -26,6 +27,12 @@ class PipeOutput(PipeOutputAbstract[WorkingMemory]):
pipeline_run_id: str = Field(default=SpecialPipelineId.UNTITLED)
graph_spec: GraphSpec | None = None
graph_assembly_error: str | None = None
+ # The I/O artifacts describing the graph's data (`pipe_io_contracts`, `input_form`, `output_form`),
+ # built inside the run's library window over the whole run library and carried beside the graph:
+ # every writer that serializes graph_spec to graphspec.json writes them as three sibling files.
+ # None when graph tracing was off; None with pipe_io_artifacts_error set when the build failed.
+ pipe_io_artifacts: PipeIOArtifacts | None = None
+ pipe_io_artifacts_error: str | None = None
# Token usage assembled from the trace-event stream at the end of the run (mirrors graph_spec):
# the submitter renders the cost report from this field. None when cost reporting was off or the run
# emitted no trace events at all; an empty list when on with events present but no inference happened.
diff --git a/pipelex/graph/graph_factory.py b/pipelex/graph/graph_factory.py
index dac67c310..14da23f75 100644
--- a/pipelex/graph/graph_factory.py
+++ b/pipelex/graph/graph_factory.py
@@ -11,6 +11,12 @@ from typing import TYPE_CHECKING
from pydantic import BaseModel
from pipelex import log
+from pipelex.core.pipes.pipe_io_artifacts import (
+ INPUT_FORM_FILE_NAME,
+ OUTPUT_FORM_FILE_NAME,
+ PIPE_IO_CONTRACTS_FILE_NAME,
+ render_pipe_io_artifact_files,
+)
from pipelex.graph.mermaidflow.mermaid_html import render_mermaid_html_async, render_mermaid_html_with_data_async
from pipelex.graph.mermaidflow.mermaidflow_factory import MermaidflowFactory
from pipelex.graph.reactflow.reactflow_html import generate_reactflow_html_async
@@ -19,6 +25,7 @@ from pipelex.tools.misc.string_utils import snake_to_title_case
if TYPE_CHECKING:
from pathlib import Path
+ from pipelex.core.pipes.pipe_io_artifacts import PipeIOArtifacts
from pipelex.graph.graph_config import GraphConfig
from pipelex.graph.graphspec import GraphSpec
from pipelex.tools.misc.chart_utils import FlowchartDirection
@@ -31,12 +38,22 @@ class GraphOutputs(BaseModel):
Attributes:
graphspec_json: The GraphSpec serialized as JSON.
+ pipe_io_contracts_json: The graphspec's companion `pipe_io_contracts`, keyed by `pipe_ref`.
+ input_form_json: The graphspec's companion `input_form`, keyed by `pipe_ref`.
+ output_form_json: The graphspec's companion `output_form`, keyed by `pipe_ref`.
mermaidflow_mmd: Mermaidflow view as Mermaid flowchart code.
mermaidflow_html: Mermaidflow view as standalone HTML page.
reactflow_html: ReactFlow interactive graph as standalone HTML page.
+
+ The three companions describe the data the graphspec carries: a graph viewer shows a data
+ node's value only when it holds the contracts and the output form. They follow the
+ graphspec's own inclusion flag and are filled only when the run carried its artifacts.
"""
graphspec_json: str | None = None
+ pipe_io_contracts_json: str | None = None
+ input_form_json: str | None = None
+ output_form_json: str | None = None
mermaidflow_mmd: str | None = None
mermaidflow_html: str | None = None
reactflow_html: str | None = None
@@ -50,6 +67,7 @@ async def generate_graph_outputs(
title: str | None = None,
direction: FlowchartDirection | None = None,
include_subgraphs: bool = True,
+ pipe_io_artifacts: PipeIOArtifacts | None = None,
) -> GraphOutputs:
"""Generate graph outputs from a GraphSpec based on configuration.
@@ -67,6 +85,9 @@ async def generate_graph_outputs(
title: Explicit HTML page title. When provided, overrides the auto-derived title from pipe_code.
direction: Flowchart direction override for both Mermaid and ReactFlow outputs. When None, each renderer uses its own config default.
include_subgraphs: Whether to render controller hierarchy as subgraphs in Mermaid output.
+ pipe_io_artifacts: The run's I/O artifacts (`PipeOutput.pipe_io_artifacts`), rendered as the
+ graphspec's three companion files when the graphspec itself is included. None when the run
+ carried none, in which case the companions stay None.
Returns:
GraphOutputs containing generated content as strings (None for disabled outputs).
@@ -75,14 +96,21 @@ async def generate_graph_outputs(
inclusion = graph_config.graphs_inclusion
graphspec_json: str | None = None
+ pipe_io_contracts_json: str | None = None
+ input_form_json: str | None = None
+ output_form_json: str | None = None
mermaidflow_mmd: str | None = None
mermaidflow_html: str | None = None
reactflow_html: str | None = None
- # Generate GraphSpec JSON
+ # Generate GraphSpec JSON, and its three companions when the run carried them
if inclusion.graphspec_json:
- # graphspec_json = graph_spec.model_dump_json(indent=2, by_alias=True)
graphspec_json = graph_spec.to_json()
+ if pipe_io_artifacts is not None:
+ artifact_files = render_pipe_io_artifact_files(pipe_io_artifacts)
+ pipe_io_contracts_json = artifact_files[PIPE_IO_CONTRACTS_FILE_NAME]
+ input_form_json = artifact_files[INPUT_FORM_FILE_NAME]
+ output_form_json = artifact_files[OUTPUT_FORM_FILE_NAME]
# Get the mermaid theme from config
mermaid_theme = graph_config.mermaid.style.theme
@@ -126,6 +154,9 @@ async def generate_graph_outputs(
return GraphOutputs(
graphspec_json=graphspec_json,
+ pipe_io_contracts_json=pipe_io_contracts_json,
+ input_form_json=input_form_json,
+ output_form_json=output_form_json,
mermaidflow_mmd=mermaidflow_mmd,
mermaidflow_html=mermaidflow_html,
reactflow_html=reactflow_html,
@@ -160,6 +191,26 @@ def save_graph_outputs_to_dir(
saved_files["graphspec_json"] = file_path
log.verbose(f"GraphSpec JSON saved to: {file_path}")
+ # The graphspec's companions sit beside it under the standard's names: a reader resolves them
+ # from the graphspec's directory, whatever the graphspec file is later renamed to.
+ companions = (
+ ("pipe_io_contracts_json", PIPE_IO_CONTRACTS_FILE_NAME, graph_outputs.pipe_io_contracts_json),
+ ("input_form_json", INPUT_FORM_FILE_NAME, graph_outputs.input_form_json),
+ ("output_form_json", OUTPUT_FORM_FILE_NAME, graph_outputs.output_form_json),
+ )
+ for output_key, file_name, text in companions:
+ file_path = output_dir / file_name
+ if text is not None:
+ file_path.write_text(text, encoding="utf-8")
+ saved_files[output_key] = file_path
+ log.verbose(f"{file_name} saved to: {file_path}")
+ elif graph_outputs.graphspec_json is not None and file_path.exists():
+ # A written graphspec owns the companions beside it: one left by an earlier run in a reused
+ # directory would describe this graph's data with another method's declarations. Said out
+ # loud, because the agent CLI's directory is the user's own bundle directory.
+ file_path.unlink()
+ log.warning(f"Removed {file_name} at {file_path}: the graphspec written beside it carries no I/O artifacts of its own")
+
if graph_outputs.mermaidflow_mmd is not None:
file_path = output_dir / "mermaidflow.mmd"
file_path.write_text(graph_outputs.mermaidflow_mmd, encoding="utf-8")
diff --git a/pipelex/graph/graph_tracer_manager.py b/pipelex/graph/graph_tracer_manager.py
index adecff66e..2fb79814b 100644
--- a/pipelex/graph/graph_tracer_manager.py
+++ b/pipelex/graph/graph_tracer_manager.py
@@ -104,6 +104,7 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
tracer_key: str | None = None,
emit_graph_events: bool = True,
emit_usage_events: bool = True,
+ describe_pipe_io: bool = True,
mode: GraphSpecMode = GraphSpecMode.LIVE,
) -> TraceContext:
"""Create and initialize a new tracer for a pipeline run.
@@ -125,6 +126,9 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
(no post-hoc model_copy needed at the call site).
emit_usage_events: Whether this run emits usage (cost) events. Threaded into setup
so the returned TraceContext is born with the correct flag.
+ describe_pipe_io: Whether the run builds the I/O artifacts describing its graphspec's
+ data. Read by the run, never by the tracer, so it is stamped on the context here
+ rather than threaded into setup.
mode: Provenance mode to stamp onto generated GraphSpecs.
Returns:
@@ -168,6 +172,8 @@ class GraphTracerManager(metaclass=ABCSingletonMeta):
# Set the tracer_key on the TraceContext so downstream lookups use the same key
if tracer_key is not None:
trace_context = trace_context.model_copy(update={"tracer_key": tracer_key})
+ if not describe_pipe_io:
+ trace_context = trace_context.model_copy(update={"describe_pipe_io": False})
# Register only once setup has fully succeeded: a failure above must not leave
# an unusable tracer entry in the process-wide manager.
diff --git a/pipelex/interpreter_hub.py b/pipelex/interpreter_hub.py
index b8c35e378..327e75d0f 100644
--- a/pipelex/interpreter_hub.py
+++ b/pipelex/interpreter_hub.py
@@ -342,6 +342,11 @@ def get_pipes() -> list[PipeAbstract]:
return get_interpreter_hub().get_required_pipe_library().get_pipes()
+def get_own_pipes() -> list[PipeAbstract]:
+ """The current library's own pipes, without its dependency packages' aliased entries."""
+ return get_interpreter_hub().get_required_pipe_library().get_own_pipes()
+
+
def get_required_pipe(pipe_code: str) -> PipeAbstract:
return get_interpreter_hub().get_required_pipe_library().get_required_pipe(pipe_code=pipe_code)
diff --git a/pipelex/libraries/pipe/pipe_library.py b/pipelex/libraries/pipe/pipe_library.py
index 2826fcc6c..870c7af2d 100644
--- a/pipelex/libraries/pipe/pipe_library.py
+++ b/pipelex/libraries/pipe/pipe_library.py
@@ -180,6 +180,11 @@ class PipeLibrary(RootModel[PipeLibraryRoot], PipeLibraryAbstract):
def get_pipes(self) -> list[PipeAbstract]:
return list(self.root.values())
+ @override
+ def get_own_pipes(self) -> list[PipeAbstract]:
+ # A dependency's pipe is keyed `alias->domain.code` (see `add_dependency_pipe`); the host's are keyed by bare `pipe_ref`.
+ return [pipe for key, pipe in self.root.items() if not QualifiedRef.has_cross_package_prefix(key)]
+
@override
def get_pipes_dict(self) -> dict[str, PipeAbstract]:
return self.root
diff --git a/pipelex/libraries/pipe/pipe_library_abstract.py b/pipelex/libraries/pipe/pipe_library_abstract.py
index 5e24831c6..d3decdbde 100644
--- a/pipelex/libraries/pipe/pipe_library_abstract.py
+++ b/pipelex/libraries/pipe/pipe_library_abstract.py
@@ -64,6 +64,10 @@ class PipeLibraryAbstract(ABC):
def get_pipes(self) -> list[PipeAbstract]:
pass
+ @abstractmethod
+ def get_own_pipes(self) -> list[PipeAbstract]:
+ """The library's own pipes, without the aliased entries its dependency packages contributed."""
+
@abstractmethod
def get_pipes_dict(self) -> dict[str, PipeAbstract]:
pass
diff --git a/pipelex/pipe_run/delivery_executor.py b/pipelex/pipe_run/delivery_executor.py
index 9da6e1553..24ca11ff1 100644
--- a/pipelex/pipe_run/delivery_executor.py
+++ b/pipelex/pipe_run/delivery_executor.py
@@ -14,6 +14,7 @@ from pipelex.core.concepts.concept import Concept
from pipelex.core.memory.absence import AbsenceRecord
from pipelex.core.memory.absence_render import build_absence_html, build_absence_json, build_absence_markdown
from pipelex.core.memory.working_memory import MAIN_STUFF_NAME
+from pipelex.core.pipes.pipe_io_artifacts import INPUT_FORM_FILE_NAME, OUTPUT_FORM_FILE_NAME, PIPE_IO_CONTRACTS_FILE_NAME
from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.stuff_content import StuffContent
from pipelex.core.stuffs.stuff_viewer import render_stuff_viewer
@@ -26,6 +27,7 @@ from pipelex.tools.misc.json_utils import clean_json_dumps
from pipelex.tools.network.ssrf_guard import SsrfGuardedTransport
if TYPE_CHECKING:
+ from pipelex.core.pipes.pipe_io_artifacts import PipeIOArtifacts
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.pipe_run.delivery_assignment import DeliveryAssignment, DeliveryStatus, StorageTarget, WebhookTarget
@@ -142,7 +144,7 @@ class DeliveryExecutor:
graph_spec = pipe_output.graph_spec
if graph_spec:
- await self._generate_graph_files(graph_spec, files=files)
+ await self._generate_graph_files(graph_spec, pipe_io_artifacts=pipe_output.pipe_io_artifacts, files=files)
return files
@@ -274,14 +276,25 @@ class DeliveryExecutor:
files=files, filename="main_stuff_viewer.html", render=render_stuff_viewer(main_stuff), content_type="text/html"
)
- async def _generate_graph_files(self, graph_spec: Any, *, files: dict[str, ResultFile]) -> None:
+ async def _generate_graph_files(self, graph_spec: Any, *, pipe_io_artifacts: PipeIOArtifacts | None, files: dict[str, ResultFile]) -> None:
try:
graph_config = get_config().interpreter.pipeline_execution.graph
graph_outputs = await generate_graph_outputs(
graph_spec=graph_spec,
graph_config=graph_config,
+ pipe_io_artifacts=pipe_io_artifacts,
)
self._add_optional_text_file(files=files, filename="graphspec.json", text=graph_outputs.graphspec_json, content_type="application/json")
+ # The graphspec's companions, under the standard's names beside it.
+ self._add_optional_text_file(
+ files=files, filename=PIPE_IO_CONTRACTS_FILE_NAME, text=graph_outputs.pipe_io_contracts_json, content_type="application/json"
+ )
+ self._add_optional_text_file(
+ files=files, filename=INPUT_FORM_FILE_NAME, text=graph_outputs.input_form_json, content_type="application/json"
+ )
+ self._add_optional_text_file(
+ files=files, filename=OUTPUT_FORM_FILE_NAME, text=graph_outputs.output_form_json, content_type="application/json"
+ )
self._add_optional_text_file(files=files, filename="mermaidflow.mmd", text=graph_outputs.mermaidflow_mmd, content_type="text/plain")
self._add_optional_text_file(files=files, filename="mermaidflow.html", text=graph_outputs.mermaidflow_html, content_type="text/html")
self._add_optional_text_file(files=files, filename="reactflow.html", text=graph_outputs.reactflow_html, content_type="text/html")
diff --git a/pipelex/pipe_run/dry_run_in_process.py b/pipelex/pipe_run/dry_run_in_process.py
index 088856f8d..c62c8b84d 100644
--- a/pipelex/pipe_run/dry_run_in_process.py
+++ b/pipelex/pipe_run/dry_run_in_process.py
@@ -132,6 +132,8 @@ async def dry_run_pipe_in_process(pipe: PipeAbstract, *, library_id: str) -> Gra
pipeline_run_id=pipeline_run_id,
emit_graph_events=True,
emit_usage_events=False,
+ # Validate builds the I/O artifacts once, for its report; this dry run keeps only the graph.
+ describe_pipe_io=False,
mode=GraphSpecMode.DRY,
)
try:
diff --git a/pipelex/pipe_run/pipe_run.py b/pipelex/pipe_run/pipe_run.py
index ebe2c7382..c5fe53382 100644
--- a/pipelex/pipe_run/pipe_run.py
+++ b/pipelex/pipe_run/pipe_run.py
@@ -7,11 +7,13 @@ from typing_extensions import override
from pipelex import log
from pipelex.base_exceptions import ErrorReport, PipelexError, PipelexUnexpectedError
from pipelex.graph.graph_tracer_manager import GraphTracerManager
+from pipelex.interpreter_hub import get_own_pipes
from pipelex.pipe_run.delivery_assignment import DeliveryAssignment, DeliveryStatus
from pipelex.pipe_run.delivery_executor import DeliveryExecutor
from pipelex.pipe_run.exceptions import DeliveryError
from pipelex.pipe_run.pipe_run_protocol import PipeRunProtocol
from pipelex.pipe_run.tracing_assembly import assemble_tracing_on_output
+from pipelex.pipeline.build_pipe_io_artifacts import build_pipe_io_artifacts
if TYPE_CHECKING:
from pipelex.core.pipes.pipe_output import PipeOutput
@@ -88,6 +90,8 @@ class PipeRun(PipeRunProtocol):
main_pipe_code=pipe_job.pipe.code,
run_mode=pipe_job.pipe_run_params.run_mode,
)
+ if trace_context.describe_pipe_io and pipe_output.graph_spec is not None:
+ self._build_pipe_io_artifacts_on_output(pipe_output=pipe_output, pipeline_run_id=pipeline_run_id)
if delivery_assignment is not None:
log.debug(f"Executing delivery for pipeline_run_id={pipeline_run_id}, status={status}")
@@ -115,3 +119,26 @@ class PipeRun(PipeRunProtocol):
assert pipe_output is not None
return pipe_output
+
+ @classmethod
+ def _build_pipe_io_artifacts_on_output(cls, *, pipe_output: PipeOutput, pipeline_run_id: str) -> None:
+ """Describe the graph's data: build the three I/O artifacts over the run library's own pipes and set them on the output.
+
+ Runs inside the run's library window — `PipelineRunner.execute` tears the run library down
+ after this returns, and the builders need it — and before the direct-mode delivery below,
+ which writes the artifacts beside the graphspec. The scope is the library's own pipes, as
+ validate's is: a dependency package's pipes are keyed by alias in the library but by bare
+ `pipe_ref` in the artifacts, where they would collide with the host's, and the host's crate
+ holds no blueprint of theirs to describe them from. Best-effort like the graph assembly, and
+ blind on purpose: this runs in the `finally` ahead of the delivery, so an exception that
+ escaped here would replace the run's own outcome and skip the delivery of a run that
+ completed. Whatever the builders raise — a contract that will not render, a crate that
+ will not normalize, a protocol model that will not validate, or a bug of their own — is
+ reported on `pipe_io_artifacts_error` and the run keeps its result.
+ """
+ try:
+ pipe_output.pipe_io_artifacts = build_pipe_io_artifacts(get_own_pipes())
+ except Exception as build_error: # ruff: ignore[blind-except]
+ message = f"Failed to build the I/O artifacts for pipeline_run_id={pipeline_run_id}: {build_error}"
+ log.warning(message)
+ pipe_output.pipe_io_artifacts_error = message
diff --git a/pipelex/pipeline/build_pipe_io_artifacts.py b/pipelex/pipeline/build_pipe_io_artifacts.py
new file mode 100644
index 000000000..30285cf56
--- /dev/null
+++ b/pipelex/pipeline/build_pipe_io_artifacts.py
@@ -0,0 +1,53 @@
+"""The one sequence that derives a method's three I/O artifacts, off one crate qualification.
+
+`validate_bundles_in_process` used to spell it out inline — contracts, one
+`qualify_current_library_crate()`, both forms off the same qualification — and a run now needs the
+same sequence at the end of `PipeRun.run`. Keeping it in one place means a validate report and a
+run's results directory cannot drift on how the artifacts are derived, and a future fourth
+artifact is populated everywhere or nowhere.
+
+The three builders need the live library: JSON-Schema rendering resolves bundle-defined structure
+classes through the class registry, and the forms qualify the current library's crate. So this
+must run inside a library window — the validate orchestrator's, or the run's own before
+`PipelineRunner.execute` tears the run library down. The carrier it returns, `PipeIOArtifacts`,
+lives apart because `PipeOutput` imports it and must stay free of the library machinery.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pipelex.core.pipes.pipe_io_artifacts import PipeIOArtifacts
+from pipelex.pipeline.input_form import build_input_form, build_output_form, qualify_current_library_crate
+from pipelex.pipeline.pipe_io_contracts import build_pipe_io_contracts
+
+if TYPE_CHECKING:
+ from collections.abc import Sequence
+
+ from pipelex.libraries.crate_qualification import QualifiedCrateContent
+ from pipelex.pipe_machinery.pipe_abstract import PipeAbstract
+
+
+def build_pipe_io_artifacts(pipes: Sequence[PipeAbstract], *, qualified_crate: QualifiedCrateContent | None = None) -> PipeIOArtifacts:
+ """Build the three artifacts over the given pipes, off one crate qualification.
+
+ Must run inside a library window (see the module docstring).
+
+ Args:
+ pipes: The loaded pipes to describe: a validated bundle's, or a run library's.
+ qualified_crate: The current library's already-qualified crate, when the caller holds one;
+ otherwise the crate is read and qualified here, once for both forms.
+
+ Returns:
+ The three artifacts, sharing one key set.
+
+ Raises:
+ PipeIOContractError: When a pipe's output JSON Schema cannot be rendered.
+ """
+ pipe_io_contracts = build_pipe_io_contracts(pipes)
+ qualified = qualified_crate if qualified_crate is not None else qualify_current_library_crate()
+ return PipeIOArtifacts(
+ pipe_io_contracts=pipe_io_contracts,
+ input_form=build_input_form(pipes, qualified_crate=qualified),
+ output_form=build_output_form(pipes, qualified_crate=qualified),
+ )
diff --git a/pipelex/pipeline/pipeline_run_setup.py b/pipelex/pipeline/pipeline_run_setup.py
index 4b03ab15e..65fe0dc33 100644
--- a/pipelex/pipeline/pipeline_run_setup.py
+++ b/pipelex/pipeline/pipeline_run_setup.py
@@ -280,6 +280,8 @@ async def pipeline_run_setup(
pipeline_run_id=pipeline_run_id,
emit_graph_events=is_generate_graph,
emit_usage_events=is_generate_usage,
+ # The I/O artifacts are the graphspec's companions: a run that writes no graphspec builds none.
+ describe_pipe_io=is_generate_graph and execution_config.graph.graphs_inclusion.graphspec_json,
mode=pipe_run_mode.graphspec_mode,
)
diff --git a/pipelex/pipeline/validate_in_process.py b/pipelex/pipeline/validate_in_process.py
index b44a9fc3f..0d0990bb7 100644
--- a/pipelex/pipeline/validate_in_process.py
+++ b/pipelex/pipeline/validate_in_process.py
@@ -29,10 +29,10 @@ from pipelex.interpreter_hub import clear_current_library, get_current_library_i
from pipelex.pipe_run.dry_run_in_process import best_effort_graph_spec
from pipelex.pipeline.advisory_warnings import build_advisory_warnings
from pipelex.pipeline.blueprint_selection import collect_entry_pipe_refs, select_primary_blueprint
+from pipelex.pipeline.build_pipe_io_artifacts import build_pipe_io_artifacts
from pipelex.pipeline.controller_taint import collect_controller_taint_analyses
-from pipelex.pipeline.input_form import InputForm, OutputForm, build_input_form, build_output_form, qualify_current_library_crate
+from pipelex.pipeline.input_form import qualify_current_library_crate
from pipelex.pipeline.liftable_pipes import LiftablePipeEntry, build_liftable_pipes
-from pipelex.pipeline.pipe_io_contracts import PipeIOContracts, build_pipe_io_contracts
from pipelex.pipeline.validate_bundle import validate_bundle
from pipelex.pipeline.validation_report import PipelexValidationReport, build_validation_report
@@ -106,19 +106,17 @@ async def validate_bundles_in_process(
# current — the graph arm and the finally must target the SAME library even if
# something inside the window later moves the contextvar.
validation_library_id = get_current_library_id_or_none()
- pipe_io_contracts: PipeIOContracts = build_pipe_io_contracts(result.pipes)
# One crate qualification per validate pass — the descriptors and the hint lint read the same one.
qualified_crate = qualify_current_library_crate()
- input_form: InputForm = build_input_form(result.pipes, qualified_crate=qualified_crate)
- # The output half, off the same qualification and the same pipe order — all three
- # artifacts share one key set because all three iterate `result.pipes`.
- output_form: OutputForm = build_output_form(result.pipes, qualified_crate=qualified_crate)
+ # The three I/O artifacts come from the one builder a run uses too, so a validate report and
+ # a run's results directory cannot drift on how they are derived.
+ artifacts = build_pipe_io_artifacts(result.pipes, qualified_crate=qualified_crate)
# One taint walk per validate pass — both report projections read the same analyses.
taint_analyses = collect_controller_taint_analyses(result.pipes)
liftable_pipes: list[LiftablePipeEntry] = build_liftable_pipes(taint_analyses)
warnings: list[ValidationErrorItem] = build_advisory_warnings(
taint_analyses=taint_analyses,
- input_form=input_form,
+ input_form=artifacts.input_form,
entry_pipe_refs=collect_entry_pipe_refs(result.blueprints),
qualified_crate=qualified_crate,
)
@@ -152,9 +150,9 @@ async def validate_bundles_in_process(
)
return build_validation_report(
blueprints=result.blueprints,
- pipe_io_contracts=pipe_io_contracts,
- input_form=input_form,
- output_form=output_form,
+ pipe_io_contracts=artifacts.pipe_io_contracts,
+ input_form=artifacts.input_form,
+ output_form=artifacts.output_form,
liftable_pipes=liftable_pipes,
dry_run_result=result.dry_run_result,
pending_signatures=result.pending_signatures,
diff --git a/pipelex/runtime_bridge/payloads.py b/pipelex/runtime_bridge/payloads.py
index d6d00eca2..6d14e514a 100644
--- a/pipelex/runtime_bridge/payloads.py
+++ b/pipelex/runtime_bridge/payloads.py
@@ -91,6 +91,11 @@ class PipelexPipeRunOutput(BaseModel):
graph_assembly_error: str | None = None
tokens_usages_dump: list[dict[str, Any]] | None = None
usage_assembly_error: str | None = None
+ # The JSON-mode dump of `PipeOutput.pipe_io_artifacts` — the `pipe_io_contracts`, `input_form` and
+ # `output_form` describing the graph's data — beside graph_spec_dump, so wherever the graph
+ # travels its description travels with it; pipe_io_artifacts_error mirrors graph_assembly_error.
+ pipe_io_artifacts_dump: dict[str, Any] | None = None
+ pipe_io_artifacts_error: str | None = None
class PipelexPipeDispatchAck(BaseModel):
diff --git a/pipelex/runtime_bridge/serialization.py b/pipelex/runtime_bridge/serialization.py
index fa0952044..a0761c5dd 100644
--- a/pipelex/runtime_bridge/serialization.py
+++ b/pipelex/runtime_bridge/serialization.py
@@ -64,6 +64,7 @@ def serialize_completed_output(
graph_spec_dump = pipe_output.graph_spec.model_dump(mode="json") if pipe_output.graph_spec is not None else None
tokens_usages_dump = [usage.model_dump(mode="json") for usage in pipe_output.tokens_usages] if pipe_output.tokens_usages is not None else None
+ pipe_io_artifacts_dump = pipe_output.pipe_io_artifacts.model_dump(mode="json") if pipe_output.pipe_io_artifacts is not None else None
return PipelexPipeRunOutput(
output_dict=output_dict,
@@ -74,6 +75,8 @@ def serialize_completed_output(
graph_assembly_error=pipe_output.graph_assembly_error,
tokens_usages_dump=tokens_usages_dump,
usage_assembly_error=pipe_output.usage_assembly_error,
+ pipe_io_artifacts_dump=pipe_io_artifacts_dump,
+ pipe_io_artifacts_error=pipe_output.pipe_io_artifacts_error,
)
diff --git a/pipelex/system/trace_context.py b/pipelex/system/trace_context.py
index 06c5eb4aa..6cf2b235c 100644
--- a/pipelex/system/trace_context.py
+++ b/pipelex/system/trace_context.py
@@ -38,6 +38,9 @@ class TraceContext(BaseModel):
emit_usage_events: Whether usage (cost) trace events should be emitted for this run
(driven by ``is_generate_usage``). Independent of ``emit_graph_events`` so cost reporting
survives ``--no-graph``.
+ describe_pipe_io: Whether the run builds the three I/O artifacts that describe its graphspec's
+ data (driven by ``graphs_inclusion.graphspec_json``). Off for a run that writes no
+ graphspec, and for validate's own graph dry run, which already built them for its report.
"""
model_config = ConfigDict(strict=True, extra="forbid")
@@ -49,6 +52,7 @@ class TraceContext(BaseModel):
data_inclusion: DataInclusionConfig = Field(description="Controls which data formats to capture")
emit_graph_events: bool = Field(default=True, description="Whether to emit graph (node/edge) trace events")
emit_usage_events: bool = Field(default=True, description="Whether to emit usage (cost) trace events")
+ describe_pipe_io: bool = Field(default=True, description="Whether to build the I/O artifacts describing the graphspec's data")
@property
def lookup_key(self) -> str:
@@ -81,4 +85,5 @@ class TraceContext(BaseModel):
data_inclusion=self.data_inclusion,
emit_graph_events=self.emit_graph_events,
emit_usage_events=self.emit_usage_events,
+ describe_pipe_io=self.describe_pipe_io,
)
diff --git a/subject_grants.toml b/subject_grants.toml
index 88731402e..54a28eb75 100644
--- a/subject_grants.toml
+++ b/subject_grants.toml
@@ -2924,6 +2924,14 @@ rationale = "Setter: installs the default domain code; single operand."
param = "named"
rationale = "Factory from source: builds from the named spec; context stays keyword."
+["pipelex/core/pipes/pipe_io_artifacts.py::_render_json_text"]
+param = "payload"
+rationale = "Verb-object: renders the payload as JSON text; single operand."
+
+["pipelex/core/pipes/pipe_io_artifacts.py::render_pipe_io_artifact_files"]
+param = "artifacts"
+rationale = "Verb-object: renders the artifacts into their files; single operand."
+
["pipelex/core/pipes/pipe_output.py::PipeOutput.main_stuff_as"]
param = "content_type"
rationale = "Type-directed accessor: the target content type; single operand."
@@ -4424,6 +4432,10 @@ rationale = "Derivation: collects the entry refs from the batch's blueprints; si
param = "blueprints"
rationale = "Verb-object: selects among the blueprints; single operand."
+["pipelex/pipeline/build_pipe_io_artifacts.py::build_pipe_io_artifacts"]
+param = "pipes"
+rationale = "Reads as a verb-object sentence over the loaded pipes, like the three builders it wraps."
+
["pipelex/pipeline/bundle_graph_rendering.py::_dry_run_bundle"]
param = "bundle_path"
rationale = "Verb-object: dry-runs the bundle at the path; options stay keyword."
diff --git a/tests/e2e/pipelex/cli/test_run_artifacts_beside_graphspec.py b/tests/e2e/pipelex/cli/test_run_artifacts_beside_graphspec.py
new file mode 100644
index 000000000..51805eeb7
--- /dev/null
+++ b/tests/e2e/pipelex/cli/test_run_artifacts_beside_graphspec.py
@@ -0,0 +1,70 @@
+"""E2E: `pipelex run` leaves the three I/O artifact files beside `graphspec.json`.
+
+One `gha_disabled` subprocess check exercises the real binary: a dry run with graph outputs on
+must leave a results directory holding `graphspec.json` and, beside it, `pipe_io_contracts.json`,
+`input_form.json` and `output_form.json`, each a JSON object keyed by `pipe_ref` — the layout the
+VS Code extension reads to show a data node's value.
+
+The subprocess test inherits the ambient environment (it needs a working `.pipelex` config to
+boot) and runs with `cwd` set to a tmp dir so on-disk side effects stay out of the source tree.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess # ruff: ignore[suspicious-subprocess-import] — invokes the real pipelex binary for E2E coverage
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[4]
+PIPELEX_BIN = REPO_ROOT / ".venv" / "bin" / "pipelex"
+BUNDLE_SRC = REPO_ROOT / "tests" / "data" / "input_semantics" / "probe_bundle.mthds"
+COMPANION_FILE_NAMES = ("pipe_io_contracts.json", "input_form.json", "output_form.json")
+
+
+class TestRunArtifactsBesideGraphspec:
+ @pytest.mark.gha_disabled
+ def test_dry_run_writes_the_three_siblings(self, tmp_path: Path) -> None:
+ staged = tmp_path / "bundle"
+ staged.mkdir()
+ shutil.copy(BUNDLE_SRC, staged / BUNDLE_SRC.name)
+ output_dir = tmp_path / "results"
+
+ result = subprocess.run( # ruff: ignore[subprocess-without-shell-equals-true]
+ [
+ str(PIPELEX_BIN),
+ "run",
+ "pipe",
+ "probe_single",
+ "-L",
+ str(staged),
+ "--dry-run",
+ "--mock-inputs",
+ "--graph",
+ "--no-save-working-memory",
+ "--no-save-main-stuff",
+ "-o",
+ str(output_dir),
+ ],
+ cwd=str(tmp_path),
+ env=os.environ.copy(),
+ capture_output=True,
+ text=True,
+ check=False,
+ timeout=180,
+ )
+ assert result.returncode == 0, f"dry run must succeed.\nstdout={result.stdout!r}\nstderr={result.stderr!r}"
+
+ graphspecs = list(output_dir.rglob("graphspec.json"))
+ assert len(graphspecs) == 1, f"expected one graphspec.json under {output_dir}, found {graphspecs}"
+ results_dir = graphspecs[0].parent
+ pipe_registry: dict[str, Any] = json.loads(graphspecs[0].read_text(encoding="utf-8"))["pipe_registry"]
+ for file_name in COMPANION_FILE_NAMES:
+ doc: dict[str, Any] = json.loads((results_dir / file_name).read_text(encoding="utf-8"))
+ assert isinstance(doc, dict), f"{file_name}: an object keyed by pipe_ref"
+ assert doc, f"{file_name}: at least one pipe described"
+ assert set(pipe_registry) <= set(doc), f"{file_name}: every pipe the graph names is described"
diff --git a/tests/helpers/pipe_io_artifacts.py b/tests/helpers/pipe_io_artifacts.py
new file mode 100644
index 000000000..7d80fcf1f
--- /dev/null
+++ b/tests/helpers/pipe_io_artifacts.py
@@ -0,0 +1,30 @@
+"""A hand-built `PipeIOArtifacts` for writer tests that need one without a loaded library."""
+
+from mthds.protocol.input_form import PipeInputFormDescriptor, TextField
+from mthds.protocol.output_form import PipeOutputFormDescriptor
+
+from pipelex.core.pipes.pipe_io_artifacts import PipeIOArtifacts
+from pipelex.core.pipes.variable_multiplicity import PresenceMarker
+from pipelex.pipeline.pipe_io_contracts import IOMultiplicity, PipeIOContract, PipeOutputContract
+
+
+def make_pipe_io_artifacts(*, pipe_ref: str = "test_domain.my_sequence") -> PipeIOArtifacts:
+ """One pipe, described three ways; a non-ASCII description proves the rendering keeps it verbatim."""
+ slot = TextField(name="doc", required=True, presence=PresenceMarker.PLAIN, gating=False, description="Le résumé à traiter")
+ output = TextField(name="doc", required=True, description="Le résumé traité")
+ return PipeIOArtifacts(
+ pipe_io_contracts={
+ pipe_ref: PipeIOContract(
+ inputs={},
+ output=PipeOutputContract(
+ concept_ref="native.Text",
+ multiplicity=IOMultiplicity.SINGLE,
+ item_count=None,
+ optional=False,
+ json_schema={"type": "object", "properties": {"text": {"type": "string"}}},
+ ),
+ ),
+ },
+ input_form={pipe_ref: PipeInputFormDescriptor(fields=[slot])},
+ output_form={pipe_ref: PipeOutputFormDescriptor(field=output)},
+ )
diff --git a/tests/integration/pipelex/pipeline/test_direct_pipe_io_artifacts.py b/tests/integration/pipelex/pipeline/test_direct_pipe_io_artifacts.py
new file mode 100644
index 000000000..84189bfd8
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_direct_pipe_io_artifacts.py
@@ -0,0 +1,152 @@
+"""A DIRECT run builds its I/O artifacts inside its own library window and carries them on the output.
+
+The three artifacts (`pipe_io_contracts`, `input_form`, `output_form`) describe the data a run's
+`graph_spec` carries, and the builders need the run library, which `PipelineRunner.execute` tears
+down before returning. So they are built at the end of `PipeRun.run`, right where the graph is
+assembled, and gated by the graph: a run with graph tracing off has neither. A builder failure is
+reported on `pipe_io_artifacts_error` (the `graph_assembly_error` pattern) and never fails the run.
+
+Runs fully dry (`PipeRunMode.DRY` + `mock_inputs`), so no inference happens.
+"""
+
+import pytest
+from pytest_mock import MockerFixture
+
+from pipelex.config import get_config
+from pipelex.core.pipes.pipe_output import PipeOutput
+from pipelex.pipeline.exceptions import PipeIOContractError
+from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.pipeline.validate_in_process import validate_bundles_in_process
+from pipelex.system.configuration.configs import NdjsonTracingConfig, PipelineExecutionConfig, TracingBackend
+from pipelex.system.pipe_run_mode import PipeRunMode
+
+_DOMAIN = "direct_pipe_io_artifacts"
+_MTHDS = f"""
+domain = "{_DOMAIN}"
+description = "Minimal bundle for the run-carried I/O artifacts"
+
+[concept.Topic]
+description = "A topic"
+
+[concept.Topic.structure]
+name = {{ type = "text", description = "Topic name" }}
+
+[pipe.echo_topic]
+type = "PipeLLM"
+description = "Pipe whose run carries its I/O artifacts"
+inputs = {{ subject = "Text" }}
+output = "Topic"
+prompt = "Echo the $subject as a topic"
+
+[pipe.other_entry]
+type = "PipeLLM"
+description = "A second entry pipe the graph never references"
+inputs = {{ subject = "Text" }}
+output = "Text"
+prompt = "Say $subject"
+"""
+
+
+def _config(*, generate_graph: bool, graphspec_json: bool = True) -> PipelineExecutionConfig:
+ config = get_config().interpreter.pipeline_execution.with_execution_overrides(
+ generate_graph=generate_graph,
+ generate_usage=False,
+ mock_inputs=True,
+ )
+ inclusion = config.graph.graphs_inclusion.model_copy(update={"graphspec_json": graphspec_json})
+ return config.model_copy(update={"graph": config.graph.model_copy(update={"graphs_inclusion": inclusion})})
+
+
[email protected](loop_scope="class")
+class TestDirectPipeIOArtifacts:
+ def _enable_ndjson_tracing(self, mocker: MockerFixture, traces_dir: str) -> None:
+ cfg = get_config().runtime.tracing
+ mocker.patch.object(cfg, "is_enabled", True)
+ mocker.patch.object(cfg, "backend", TracingBackend.NDJSON)
+ mocker.patch.object(cfg, "ndjson", NdjsonTracingConfig(traces_dir=traces_dir))
+
+ async def _run(self, execution_config: PipelineExecutionConfig) -> PipeOutput:
+ runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY, execution_config=execution_config)
+ response = await runner.execute(pipe_code="echo_topic", mthds_contents=[_MTHDS])
+ return response.pipe_output
+
+ async def test_graph_on_carries_artifacts_keyed_by_the_whole_run_library(
+ self, tmp_path_factory: pytest.TempPathFactory, mocker: MockerFixture
+ ) -> None:
+ self._enable_ndjson_tracing(mocker, str(tmp_path_factory.mktemp("traces_artifacts_on")))
+
+ pipe_output = await self._run(_config(generate_graph=True))
+
+ assert pipe_output.graph_spec is not None
+ artifacts = pipe_output.pipe_io_artifacts
+ assert artifacts is not None
+ assert pipe_output.pipe_io_artifacts_error is None
+ # Every pipe the graph names is described...
+ assert set(pipe_output.graph_spec.pipe_registry) <= set(artifacts.pipe_io_contracts)
+ # ...and so is every other pipe of the run library, for a consumer driving a run form from it.
+ assert f"{_DOMAIN}.echo_topic" in artifacts.pipe_io_contracts
+ assert f"{_DOMAIN}.other_entry" in artifacts.pipe_io_contracts
+ assert set(artifacts.pipe_io_contracts) == set(artifacts.input_form) == set(artifacts.output_form)
+
+ async def test_graph_off_carries_no_artifacts(self, tmp_path_factory: pytest.TempPathFactory, mocker: MockerFixture) -> None:
+ """The artifacts exist to describe a graph's data: no graph, no artifacts, and no error either."""
+ self._enable_ndjson_tracing(mocker, str(tmp_path_factory.mktemp("traces_artifacts_off")))
+
+ pipe_output = await self._run(_config(generate_graph=False))
+
+ assert pipe_output.graph_spec is None
+ assert pipe_output.pipe_io_artifacts is None
+ assert pipe_output.pipe_io_artifacts_error is None
+
+ async def test_builder_failure_is_reported_on_the_output_and_the_run_succeeds(
+ self, tmp_path_factory: pytest.TempPathFactory, mocker: MockerFixture
+ ) -> None:
+ self._enable_ndjson_tracing(mocker, str(tmp_path_factory.mktemp("traces_artifacts_fail")))
+ # Patched on the module `PipeRun.run` imports it into, so the failure is the builder's, not the run's.
+ mocker.patch(
+ "pipelex.pipe_run.pipe_run.build_pipe_io_artifacts",
+ side_effect=PipeIOContractError(message="simulated render failure"),
+ )
+
+ pipe_output = await self._run(_config(generate_graph=True))
+
+ assert pipe_output.graph_spec is not None
+ assert pipe_output.pipe_io_artifacts is None
+ assert pipe_output.pipe_io_artifacts_error is not None
+ assert "simulated render failure" in pipe_output.pipe_io_artifacts_error
+
+ async def test_graphspec_json_off_carries_no_artifacts(self, tmp_path_factory: pytest.TempPathFactory, mocker: MockerFixture) -> None:
+ """The artifacts are the graphspec's companions: a run that writes no graphspec builds none, whatever else it renders."""
+ self._enable_ndjson_tracing(mocker, str(tmp_path_factory.mktemp("traces_artifacts_no_graphspec")))
+ builder = mocker.patch("pipelex.pipe_run.pipe_run.build_pipe_io_artifacts")
+
+ pipe_output = await self._run(_config(generate_graph=True, graphspec_json=False))
+
+ assert pipe_output.graph_spec is not None
+ assert pipe_output.pipe_io_artifacts is None
+ assert pipe_output.pipe_io_artifacts_error is None
+ builder.assert_not_called()
+
+ async def test_an_unexpected_builder_error_is_reported_and_the_run_succeeds(
+ self, tmp_path_factory: pytest.TempPathFactory, mocker: MockerFixture
+ ) -> None:
+ """A bug in the builders is reported like their own failures: the build runs in the `finally` ahead of the delivery and must never escape."""
+ self._enable_ndjson_tracing(mocker, str(tmp_path_factory.mktemp("traces_artifacts_bug")))
+ mocker.patch("pipelex.pipe_run.pipe_run.build_pipe_io_artifacts", side_effect=TypeError("a bug in the builder"))
+
+ pipe_output = await self._run(_config(generate_graph=True))
+
+ assert pipe_output.graph_spec is not None
+ assert pipe_output.pipe_io_artifacts is None
+ assert pipe_output.pipe_io_artifacts_error is not None
+ assert "a bug in the builder" in pipe_output.pipe_io_artifacts_error
+
+ async def test_validate_does_not_build_the_artifacts_a_second_time(self, mocker: MockerFixture) -> None:
+ """Validate builds the artifacts once, for its report; its graph dry run must not build a set it throws away."""
+ run_hook_builder = mocker.patch("pipelex.pipe_run.pipe_run.build_pipe_io_artifacts")
+
+ report = await validate_bundles_in_process(mthds_contents=[_MTHDS], graph_pipe_code=f"{_DOMAIN}.echo_topic")
+
+ assert report.graph_spec is not None
+ assert f"{_DOMAIN}.echo_topic" in report.pipe_io_contracts
+ run_hook_builder.assert_not_called()
diff --git a/tests/integration/pipelex/pipeline/test_pipe_io_artifacts.py b/tests/integration/pipelex/pipeline/test_pipe_io_artifacts.py
new file mode 100644
index 000000000..636ffa65e
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_pipe_io_artifacts.py
@@ -0,0 +1,55 @@
+"""Pin `build_pipe_io_artifacts`: the three validate artifacts built once, off one crate qualification.
+
+The builder is the single sequence `validate_bundles_in_process` used to spell out inline —
+contracts, one `qualify_current_library_crate()`, both forms off the same qualification — so a
+run's results and a validate report cannot drift on how the artifacts are derived. Needs a loaded
+library, like the three builders it wraps.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+
+from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
+from pipelex.pipeline.build_pipe_io_artifacts import build_pipe_io_artifacts
+from pipelex.pipeline.input_form import build_input_form, build_output_form, qualify_current_library_crate
+from pipelex.pipeline.pipe_io_contracts import build_pipe_io_contracts
+from pipelex.pipeline.validate_bundle import validate_bundle
+
+if TYPE_CHECKING:
+ from collections.abc import Callable
+
+_PROBE_BUNDLE_PATH = Path(__file__).parents[3] / "data" / "input_semantics" / "probe_bundle.mthds"
+
+
+def _teardown_validation_library(outer_library_id: str) -> None:
+ validation_library_id = get_current_library_id_or_none()
+ if validation_library_id is not None and validation_library_id != outer_library_id:
+ set_current_library(library_id=outer_library_id)
+ get_library_manager().teardown(library_id=validation_library_id)
+ clear_current_library()
+
+
[email protected](loop_scope="class")
+class TestBuildPipeIOArtifacts:
+ async def test_equals_the_three_builders_in_sequence_and_shares_one_key_set(self, load_empty_library: Callable[[], str]) -> None:
+ outer_library_id = load_empty_library()
+ try:
+ result = await validate_bundle(mthds_contents=[_PROBE_BUNDLE_PATH.read_text(encoding="utf-8")])
+ artifacts = build_pipe_io_artifacts(result.pipes)
+ qualified_crate = qualify_current_library_crate()
+ assert artifacts.pipe_io_contracts == build_pipe_io_contracts(result.pipes)
+ assert artifacts.input_form == build_input_form(result.pipes, qualified_crate=qualified_crate)
+ assert artifacts.output_form == build_output_form(result.pipes, qualified_crate=qualified_crate)
+ # A caller holding a qualification already (the validate orchestrator) gets the same artifacts.
+ assert build_pipe_io_artifacts(result.pipes, qualified_crate=qualified_crate) == artifacts
+ finally:
+ _teardown_validation_library(outer_library_id)
+ keys = {pipe.pipe_ref for pipe in result.pipes}
+ assert keys, "the probe bundle declares pipes"
+ assert set(artifacts.pipe_io_contracts) == keys
+ assert set(artifacts.input_form) == keys
+ assert set(artifacts.output_form) == keys
diff --git a/tests/integration/pipelex/pipeline/test_protocol_validate.py b/tests/integration/pipelex/pipeline/test_protocol_validate.py
index b07573334..ca9515441 100644
--- a/tests/integration/pipelex/pipeline/test_protocol_validate.py
+++ b/tests/integration/pipelex/pipeline/test_protocol_validate.py
@@ -415,7 +415,7 @@ class TestProtocolValidate:
try:
library_manager = get_library_manager()
mocker.patch(
- "pipelex.pipeline.validate_in_process.build_pipe_io_contracts",
+ "pipelex.pipeline.build_pipe_io_artifacts.build_pipe_io_contracts",
side_effect=PipeIOContractError(message="simulated render failure"),
)
mocker.patch.object(library_manager, "teardown", side_effect=LibraryError("simulated teardown failure"))
diff --git a/tests/integration/pipelex/pipeline/test_run_artifacts_parity.py b/tests/integration/pipelex/pipeline/test_run_artifacts_parity.py
new file mode 100644
index 000000000..a412d2e99
--- /dev/null
+++ b/tests/integration/pipelex/pipeline/test_run_artifacts_parity.py
@@ -0,0 +1,91 @@
+"""The design's promise: a run's I/O artifact files equal what validate reports for the same bundle.
+
+A results directory and a validate report describe the same method through the same builder and
+the same rendering, so for every pipe the validate report knows, the file a run writes holds the
+same JSON; and when the run library holds exactly the validated pipes, the files are byte-identical
+to what the projection fixture corpus commits for that bundle (the corpus uses the same renderer).
+
+Runs fully dry (`PipeRunMode.DRY` + `mock_inputs`), so no inference happens.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import pytest
+
+from pipelex.config import get_config
+from pipelex.core.pipes.pipe_io_artifacts import (
+ INPUT_FORM_FILE_NAME,
+ OUTPUT_FORM_FILE_NAME,
+ PIPE_IO_CONTRACTS_FILE_NAME,
+ PipeIOArtifacts,
+ render_pipe_io_artifact_files,
+)
+from pipelex.graph.graph_config import GraphsInclusionConfig
+from pipelex.graph.graph_factory import generate_graph_outputs, save_graph_outputs_to_dir
+from pipelex.pipeline.runner import PipelexMTHDSProtocol
+from pipelex.pipeline.validate_in_process import validate_bundles_in_process
+from pipelex.system.configuration.configs import NdjsonTracingConfig, TracingBackend
+from pipelex.system.pipe_run_mode import PipeRunMode
+
+if TYPE_CHECKING:
+ from pytest_mock import MockerFixture
+
+_PROBE_BUNDLE_PATH = Path(__file__).parents[3] / "data" / "input_semantics" / "probe_bundle.mthds"
+_FILE_NAMES = (PIPE_IO_CONTRACTS_FILE_NAME, INPUT_FORM_FILE_NAME, OUTPUT_FORM_FILE_NAME)
+
+
+def _load(path: Path) -> dict[str, Any]:
+ loaded: dict[str, Any] = json.loads(path.read_text(encoding="utf-8"))
+ return loaded
+
+
[email protected](loop_scope="class")
+class TestRunArtifactsParity:
+ async def test_a_run_writes_what_validate_reports(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ cfg = get_config().runtime.tracing
+ mocker.patch.object(cfg, "is_enabled", True)
+ mocker.patch.object(cfg, "backend", TracingBackend.NDJSON)
+ mocker.patch.object(cfg, "ndjson", NdjsonTracingConfig(traces_dir=str(tmp_path / "traces")))
+ mthds_content = _PROBE_BUNDLE_PATH.read_text(encoding="utf-8")
+
+ # The run half: execute dry, write the graph outputs the way `pipelex run` does.
+ execution_config = get_config().interpreter.pipeline_execution.with_execution_overrides(
+ generate_graph=True, generate_usage=False, mock_inputs=True
+ )
+ runner = PipelexMTHDSProtocol(pipe_run_mode=PipeRunMode.DRY, execution_config=execution_config)
+ response = await runner.execute(pipe_code="probe_single", mthds_contents=[mthds_content])
+ pipe_output = response.pipe_output
+ assert pipe_output.graph_spec is not None
+ assert pipe_output.pipe_io_artifacts is not None, pipe_output.pipe_io_artifacts_error
+ graph_config = execution_config.graph.model_copy(
+ update={
+ "graphs_inclusion": GraphsInclusionConfig(graphspec_json=True, mermaidflow_mmd=False, mermaidflow_html=False, reactflow_html=False)
+ }
+ )
+ outputs = await generate_graph_outputs(
+ graph_spec=pipe_output.graph_spec, graph_config=graph_config, pipe_io_artifacts=pipe_output.pipe_io_artifacts
+ )
+ results_dir = tmp_path / "results"
+ save_graph_outputs_to_dir(graph_outputs=outputs, output_dir=results_dir)
+
+ # The validate half, rendered through the same function the corpus uses.
+ report = await validate_bundles_in_process(mthds_contents=[mthds_content])
+ validate_files = render_pipe_io_artifact_files(
+ PipeIOArtifacts(pipe_io_contracts=report.pipe_io_contracts, input_form=report.input_form, output_form=report.output_form)
+ )
+
+ assert (results_dir / "graphspec.json").is_file()
+ for file_name in _FILE_NAMES:
+ run_doc = _load(results_dir / file_name)
+ validate_doc = json.loads(validate_files[file_name])
+ assert validate_doc, f"{file_name}: validate reports at least one pipe"
+ for pipe_ref, described in validate_doc.items():
+ assert run_doc[pipe_ref] == described, f"{file_name}: the run and validate disagree on {pipe_ref}"
+ # Both describe the bundle's own pipes, so the key sets are equal and the bytes must be too;
+ # a divergence fails here rather than silently skipping the byte comparison.
+ assert set(run_doc) == set(validate_doc), f"{file_name}: the run and validate describe different pipes"
+ assert (results_dir / file_name).read_text(encoding="utf-8") == validate_files[file_name], f"{file_name}: not byte-identical"
diff --git a/tests/unit/pipelex/cli/agent_cli/test_run_core_graph_inclusion.py b/tests/unit/pipelex/cli/agent_cli/test_run_core_graph_inclusion.py
new file mode 100644
index 000000000..da67c24ab
--- /dev/null
+++ b/tests/unit/pipelex/cli/agent_cli/test_run_core_graph_inclusion.py
@@ -0,0 +1,78 @@
+"""The agent CLI settles its graph outputs before the run, not at render time.
+
+The run setup gates the graphspec's companion artifacts (`pipe_io_contracts`, `input_form`,
+`output_form`) on the same `graphspec_json` inclusion flag that decides whether a graphspec is
+written, and builds them inside the run's library window. A render-time override of that flag
+would come too late: the graphspec would be written and its companions never built.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Any
+
+from pipelex.cli.agent_cli.commands.run._run_core import run_pipeline_core # pyright: ignore[reportPrivateUsage]
+from pipelex.config import get_config
+from pipelex.core.memory.absence import AbsenceKind, AbsenceRecord
+from pipelex.core.memory.working_memory import WorkingMemory
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ from pytest_mock import MockerFixture
+
+ from pipelex.system.configuration.configs import PipelineExecutionConfig
+
+_RUN_CORE_MODULE = "pipelex.cli.agent_cli.commands.run._run_core"
+
+
+def _execution_config_with_graphspec_json(*, graphspec_json: bool) -> PipelineExecutionConfig:
+ execution_config = get_config().interpreter.pipeline_execution
+ graphs_inclusion = execution_config.graph.graphs_inclusion.model_copy(update={"graphspec_json": graphspec_json})
+ return execution_config.model_copy(update={"graph": execution_config.graph.model_copy(update={"graphs_inclusion": graphs_inclusion})})
+
+
+class TestAgentRunCoreGraphInclusion:
+ def _run_with_configured_graphspec(self, mocker: MockerFixture, *, graphspec_json: bool, graph: bool) -> Any:
+ """Run the core with `graphspec_json` configured as given; return the execution config the runner received."""
+ config = get_config().model_copy(
+ update={
+ "interpreter": get_config().interpreter.model_copy(
+ update={"pipeline_execution": _execution_config_with_graphspec_json(graphspec_json=graphspec_json)}
+ )
+ }
+ )
+ mocker.patch(f"{_RUN_CORE_MODULE}.get_config", return_value=config)
+ memory = WorkingMemory()
+ memory.record_new_main_absence(
+ AbsenceRecord(variable_name="answer", kind=AbsenceKind.DECLARED_ABSENT, reason="not the point of this test", producing_pipe="answer")
+ )
+ pipe_output = SimpleNamespace(working_memory=memory, graph_spec=None, tokens_usages=None)
+ runner_mock = mocker.MagicMock()
+ runner_mock.execute = mocker.AsyncMock(return_value=SimpleNamespace(pipe_output=pipe_output))
+ runner_class = mocker.patch(f"{_RUN_CORE_MODULE}.PipelexMTHDSProtocol", return_value=runner_mock)
+
+ asyncio.run(run_pipeline_core("answer", graph=graph, costs=False))
+
+ return runner_class.call_args.kwargs["execution_config"]
+
+ def test_graph_on_forces_the_graphspec_before_the_run(self, mocker: MockerFixture, tmp_path: Path, monkeypatch: Any) -> None:
+ """With `graphspec_json = false` configured, `--graph` still runs with the graphspec on, so its companions are built in the window."""
+ monkeypatch.chdir(tmp_path)
+
+ execution_config = self._run_with_configured_graphspec(mocker, graphspec_json=False, graph=True)
+
+ assert execution_config.is_generate_graph is True
+ assert execution_config.graph.graphs_inclusion.graphspec_json is True
+ assert execution_config.graph.graphs_inclusion.reactflow_html is True
+ assert execution_config.graph.graphs_inclusion.mermaidflow_html is False
+
+ def test_graph_off_leaves_the_configured_inclusion_alone(self, mocker: MockerFixture, tmp_path: Path, monkeypatch: Any) -> None:
+ """Without `--graph` nothing is rendered, so the configured inclusion is passed through untouched."""
+ monkeypatch.chdir(tmp_path)
+
+ execution_config = self._run_with_configured_graphspec(mocker, graphspec_json=False, graph=False)
+
+ assert execution_config.is_generate_graph is False
+ assert execution_config.graph.graphs_inclusion.graphspec_json is False
diff --git a/tests/unit/pipelex/cli/dev_cli/test_generate_projection_corpus.py b/tests/unit/pipelex/cli/dev_cli/test_generate_projection_corpus.py
index d09100ccd..3d998af4e 100644
--- a/tests/unit/pipelex/cli/dev_cli/test_generate_projection_corpus.py
+++ b/tests/unit/pipelex/cli/dev_cli/test_generate_projection_corpus.py
@@ -33,13 +33,12 @@ import pytest
from pipelex.cli.dev_cli.commands.generate_projection_corpus_cmd import (
ENGINE_DIR_NAME,
EXPECTED_UNSHAPEABLE,
- INPUT_FORM_FILE_NAME,
MANIFEST_FILE_NAME,
- PIPE_IO_CONTRACTS_FILE_NAME,
TEMPLATES_DIR_NAME,
CorpusManifest,
generate_projection_corpus,
)
+from pipelex.core.pipes.pipe_io_artifacts import INPUT_FORM_FILE_NAME, PIPE_IO_CONTRACTS_FILE_NAME
CORPUS_BUNDLES = [
Path("tests/data/input_semantics/hinted_bundle.mthds"),
diff --git a/tests/unit/pipelex/cli/test_run_core_execution.py b/tests/unit/pipelex/cli/test_run_core_execution.py
index cb84723ee..c35f8000a 100644
--- a/tests/unit/pipelex/cli/test_run_core_execution.py
+++ b/tests/unit/pipelex/cli/test_run_core_execution.py
@@ -112,6 +112,7 @@ class TestRunCoreExecution:
return SimpleNamespace(
main_stuff=main_stuff,
graph_spec=graph_spec,
+ pipe_io_artifacts=None,
working_memory=working_memory,
)
@@ -129,7 +130,7 @@ class TestRunCoreExecution:
producing_pipe="summarize",
)
)
- return SimpleNamespace(graph_spec=None, working_memory=memory)
+ return SimpleNamespace(graph_spec=None, pipe_io_artifacts=None, working_memory=memory)
@pytest.mark.usefixtures("config_mock")
def test_absent_main_output_prints_absence_and_saves_artifact(self, mocker: MockerFixture, console: Console, tmp_path: Path) -> None:
diff --git a/tests/unit/pipelex/core/pipes/test_pipe_io_artifacts.py b/tests/unit/pipelex/core/pipes/test_pipe_io_artifacts.py
new file mode 100644
index 000000000..c46491006
--- /dev/null
+++ b/tests/unit/pipelex/core/pipes/test_pipe_io_artifacts.py
@@ -0,0 +1,92 @@
+"""Pin `PipeIOArtifacts` and the rendering that turns it into the three sibling files.
+
+The model is a grouping of the validate report's three artifacts under the report's own names;
+the rendering is the projection corpus's byte discipline, so a results directory and the
+committed fixture corpus hold byte-identical files for the same bundle. Pure unit test, no
+Pipelex boot: the artifacts are hand-built. The builder itself needs a loaded library and is
+pinned in the integration twin of this module.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from mthds.protocol.input_form import PipeInputFormDescriptor, TextField
+from mthds.protocol.output_form import PipeOutputFormDescriptor
+from pydantic import ValidationError
+
+from pipelex.core.pipes.pipe_io_artifacts import (
+ INPUT_FORM_FILE_NAME,
+ OUTPUT_FORM_FILE_NAME,
+ PIPE_IO_CONTRACTS_FILE_NAME,
+ PipeIOArtifacts,
+ render_pipe_io_artifact_files,
+)
+from pipelex.core.pipes.variable_multiplicity import PresenceMarker
+from pipelex.pipeline.pipe_io_contracts import IOMultiplicity, PipeIOContract, PipeOutputContract
+
+_PIPE_REF = "alpha.do_it"
+
+
+def _artifacts() -> PipeIOArtifacts:
+ # A non-ASCII description proves `ensure_ascii=False` is honoured, not just claimed.
+ slot = TextField(name="doc", required=True, presence=PresenceMarker.PLAIN, gating=False, description="Le résumé à traiter")
+ output = TextField(name="doc", required=True, description="Le résumé traité")
+ return PipeIOArtifacts(
+ pipe_io_contracts={
+ _PIPE_REF: PipeIOContract(
+ inputs={},
+ output=PipeOutputContract(
+ concept_ref="native.Text",
+ multiplicity=IOMultiplicity.SINGLE,
+ item_count=None,
+ optional=False,
+ json_schema={"type": "object", "properties": {"text": {"type": "string"}}},
+ ),
+ ),
+ },
+ input_form={_PIPE_REF: PipeInputFormDescriptor(fields=[slot])},
+ output_form={_PIPE_REF: PipeOutputFormDescriptor(field=output)},
+ )
+
+
+class TestPipeIOArtifactsModel:
+ def test_forbids_extra_fields(self) -> None:
+ """A fourth artifact is a model change, never a stowaway key."""
+ with pytest.raises(ValidationError):
+ PipeIOArtifacts.model_validate({"pipe_io_contracts": {}, "input_form": {}, "output_form": {}, "extra": {}})
+
+ def test_round_trips_through_json_mode_dump(self) -> None:
+ """The carrier survives the wire: `model_dump(mode="json")` validates back to an equal model."""
+ artifacts = _artifacts()
+ assert PipeIOArtifacts.model_validate(artifacts.model_dump(mode="json")) == artifacts
+
+
+class TestRenderPipeIOArtifactFiles:
+ def test_yields_exactly_the_three_sibling_files(self) -> None:
+ files = render_pipe_io_artifact_files(_artifacts())
+ assert set(files) == {PIPE_IO_CONTRACTS_FILE_NAME, INPUT_FORM_FILE_NAME, OUTPUT_FORM_FILE_NAME}
+ assert (PIPE_IO_CONTRACTS_FILE_NAME, INPUT_FORM_FILE_NAME, OUTPUT_FORM_FILE_NAME) == (
+ "pipe_io_contracts.json",
+ "input_form.json",
+ "output_form.json",
+ )
+
+ def test_each_file_is_the_corpus_byte_discipline_over_the_json_mode_dump(self) -> None:
+ """Two-space indent, `ensure_ascii=False`, one trailing newline, keyed by `pipe_ref`."""
+ artifacts = _artifacts()
+ files = render_pipe_io_artifact_files(artifacts)
+ expected = {
+ PIPE_IO_CONTRACTS_FILE_NAME: {ref: contract.model_dump(mode="json") for ref, contract in artifacts.pipe_io_contracts.items()},
+ INPUT_FORM_FILE_NAME: {ref: descriptor.model_dump(mode="json") for ref, descriptor in artifacts.input_form.items()},
+ OUTPUT_FORM_FILE_NAME: {ref: descriptor.model_dump(mode="json") for ref, descriptor in artifacts.output_form.items()},
+ }
+ for file_name, payload in expected.items():
+ text = files[file_name]
+ assert text == json.dumps(payload, indent=2, ensure_ascii=False) + "\n"
+ assert text.endswith("}\n")
+ assert not text.endswith("\n\n")
+ assert json.loads(text) == payload
+ for file_name in (INPUT_FORM_FILE_NAME, OUTPUT_FORM_FILE_NAME):
+ assert "résumé" in files[file_name], "ensure_ascii=False: the non-ASCII description is written verbatim, not escaped"
diff --git a/tests/unit/pipelex/graph/test_graph_output_generation.py b/tests/unit/pipelex/graph/test_graph_output_generation.py
index b06ce72b4..4503d2c9f 100644
--- a/tests/unit/pipelex/graph/test_graph_output_generation.py
+++ b/tests/unit/pipelex/graph/test_graph_output_generation.py
@@ -8,10 +8,18 @@ from datetime import UTC, datetime, timedelta
from pathlib import Path
import pytest
+from pytest_mock import MockerFixture
+from pipelex.core.pipes.pipe_io_artifacts import (
+ INPUT_FORM_FILE_NAME,
+ OUTPUT_FORM_FILE_NAME,
+ PIPE_IO_CONTRACTS_FILE_NAME,
+ render_pipe_io_artifact_files,
+)
from pipelex.graph.graph_config import GraphConfig, GraphsInclusionConfig
from pipelex.graph.graph_factory import generate_graph_outputs, save_graph_outputs_to_dir
from pipelex.graph.graphspec import EdgeKind, EdgeSpec, GraphSpec, IOSpec, NodeIOSpec, NodeKind, NodeSpec, NodeStatus, PipelineRef, TimingSpec
+from tests.helpers.pipe_io_artifacts import make_pipe_io_artifacts
from tests.unit.pipelex.graph.conftest import make_graph_config
_T0 = datetime(2025, 7, 1, 12, 0, 0, tzinfo=UTC)
@@ -190,3 +198,125 @@ class TestGraphOutputGeneration:
assert outputs.mermaidflow_mmd is not None
assert "step_one" in outputs.mermaidflow_mmd
assert "step_two" in outputs.mermaidflow_mmd
+
+
+def _with_inclusion(inclusion: GraphsInclusionConfig) -> GraphConfig:
+ return make_graph_config().model_copy(update={"graphs_inclusion": inclusion})
+
+
[email protected](loop_scope="class")
+class TestGraphspecCompanions:
+ """The three I/O artifact files follow the graphspec: same inclusion flag, written beside it."""
+
+ async def test_filled_when_graphspec_json_is_on_and_artifacts_are_given(self) -> None:
+ graph_spec = _make_sequence_graphspec()
+ artifacts = make_pipe_io_artifacts()
+ config = _with_inclusion(GraphsInclusionConfig(graphspec_json=True, mermaidflow_mmd=False, mermaidflow_html=False, reactflow_html=False))
+
+ outputs = await generate_graph_outputs(graph_spec=graph_spec, graph_config=config, pipe_io_artifacts=artifacts)
+
+ expected = render_pipe_io_artifact_files(artifacts)
+ assert outputs.graphspec_json is not None
+ assert outputs.pipe_io_contracts_json == expected[PIPE_IO_CONTRACTS_FILE_NAME]
+ assert outputs.input_form_json == expected[INPUT_FORM_FILE_NAME]
+ assert outputs.output_form_json == expected[OUTPUT_FORM_FILE_NAME]
+
+ async def test_none_when_graphspec_json_is_off(self) -> None:
+ """A run that asks for no graphspec writes nothing that describes one, artifacts or not."""
+ graph_spec = _make_sequence_graphspec()
+ config = _with_inclusion(GraphsInclusionConfig(graphspec_json=False, mermaidflow_mmd=True, mermaidflow_html=False, reactflow_html=False))
+
+ outputs = await generate_graph_outputs(graph_spec=graph_spec, graph_config=config, pipe_io_artifacts=make_pipe_io_artifacts())
+
+ assert outputs.graphspec_json is None
+ assert outputs.pipe_io_contracts_json is None
+ assert outputs.input_form_json is None
+ assert outputs.output_form_json is None
+
+ async def test_none_when_the_run_carried_no_artifacts(self) -> None:
+ graph_spec = _make_sequence_graphspec()
+ config = _with_inclusion(GraphsInclusionConfig(graphspec_json=True, mermaidflow_mmd=False, mermaidflow_html=False, reactflow_html=False))
+
+ outputs = await generate_graph_outputs(graph_spec=graph_spec, graph_config=config)
+
+ assert outputs.graphspec_json is not None
+ assert outputs.pipe_io_contracts_json is None
+ assert outputs.input_form_json is None
+ assert outputs.output_form_json is None
+
+ async def test_saved_beside_the_graphspec_under_the_standard_names(self, tmp_path: Path) -> None:
+ graph_spec = _make_sequence_graphspec()
+ artifacts = make_pipe_io_artifacts()
+ config = _with_inclusion(GraphsInclusionConfig(graphspec_json=True, mermaidflow_mmd=False, mermaidflow_html=False, reactflow_html=False))
+ outputs = await generate_graph_outputs(graph_spec=graph_spec, graph_config=config, pipe_io_artifacts=artifacts)
+
+ saved = save_graph_outputs_to_dir(graph_outputs=outputs, output_dir=tmp_path)
+
+ assert saved["graphspec_json"] == tmp_path / "graphspec.json"
+ assert saved["pipe_io_contracts_json"] == tmp_path / PIPE_IO_CONTRACTS_FILE_NAME
+ assert saved["input_form_json"] == tmp_path / INPUT_FORM_FILE_NAME
+ assert saved["output_form_json"] == tmp_path / OUTPUT_FORM_FILE_NAME
+ expected = render_pipe_io_artifact_files(artifacts)
+ for file_name, text in expected.items():
+ assert (tmp_path / file_name).read_text(encoding="utf-8") == text
+
+ async def test_nothing_saved_without_artifacts(self, tmp_path: Path) -> None:
+ graph_spec = _make_sequence_graphspec()
+ config = _with_inclusion(GraphsInclusionConfig(graphspec_json=True, mermaidflow_mmd=False, mermaidflow_html=False, reactflow_html=False))
+ outputs = await generate_graph_outputs(graph_spec=graph_spec, graph_config=config)
+
+ saved = save_graph_outputs_to_dir(graph_outputs=outputs, output_dir=tmp_path)
+
+ assert set(saved) == {"graphspec_json"}
+ assert {path.name for path in tmp_path.iterdir()} == {"graphspec.json"}
+
+ async def test_a_graphspec_without_artifacts_removes_the_previous_companions(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ """A reused directory must not pair a new graphspec with an older run's description, and each removal is said out loud."""
+ from pipelex import log as pipelex_log # ruff: ignore[import-outside-top-level]
+
+ warning_spy = mocker.spy(pipelex_log, "warning")
+ graph_spec = _make_sequence_graphspec()
+ config = _with_inclusion(GraphsInclusionConfig(graphspec_json=True, mermaidflow_mmd=False, mermaidflow_html=False, reactflow_html=False))
+ first = await generate_graph_outputs(graph_spec=graph_spec, graph_config=config, pipe_io_artifacts=make_pipe_io_artifacts())
+ save_graph_outputs_to_dir(graph_outputs=first, output_dir=tmp_path)
+ assert (tmp_path / INPUT_FORM_FILE_NAME).is_file()
+ assert not warning_spy.call_args_list
+
+ second = await generate_graph_outputs(graph_spec=graph_spec, graph_config=config)
+ saved = save_graph_outputs_to_dir(graph_outputs=second, output_dir=tmp_path)
+
+ assert set(saved) == {"graphspec_json"}
+ assert {path.name for path in tmp_path.iterdir()} == {"graphspec.json"}
+ removed = [str(call.args[0]) for call in warning_spy.call_args_list if "Removed" in str(call.args[0])]
+ assert {
+ name for name in (PIPE_IO_CONTRACTS_FILE_NAME, INPUT_FORM_FILE_NAME, OUTPUT_FORM_FILE_NAME) if any(name in msg for msg in removed)
+ } == {
+ PIPE_IO_CONTRACTS_FILE_NAME,
+ INPUT_FORM_FILE_NAME,
+ OUTPUT_FORM_FILE_NAME,
+ }
+
+ async def test_a_fresh_directory_removes_nothing_and_says_nothing(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ """The removal warning names a file that was there: a directory with no companions gets no warning."""
+ from pipelex import log as pipelex_log # ruff: ignore[import-outside-top-level]
+
+ warning_spy = mocker.spy(pipelex_log, "warning")
+ graph_spec = _make_sequence_graphspec()
+ config = _with_inclusion(GraphsInclusionConfig(graphspec_json=True, mermaidflow_mmd=False, mermaidflow_html=False, reactflow_html=False))
+ outputs = await generate_graph_outputs(graph_spec=graph_spec, graph_config=config)
+
+ save_graph_outputs_to_dir(graph_outputs=outputs, output_dir=tmp_path)
+
+ assert not [call for call in warning_spy.call_args_list if "Removed" in str(call.args[0])]
+
+ async def test_no_graphspec_leaves_the_directory_alone(self, tmp_path: Path) -> None:
+ """Only a written graphspec owns the companions beside it: a mermaid-only run touches nothing else."""
+ graph_spec = _make_sequence_graphspec()
+ stale = tmp_path / PIPE_IO_CONTRACTS_FILE_NAME
+ stale.write_text("{}", encoding="utf-8")
+ config = _with_inclusion(GraphsInclusionConfig(graphspec_json=False, mermaidflow_mmd=True, mermaidflow_html=False, reactflow_html=False))
+ outputs = await generate_graph_outputs(graph_spec=graph_spec, graph_config=config)
+
+ save_graph_outputs_to_dir(graph_outputs=outputs, output_dir=tmp_path)
+
+ assert stale.read_text(encoding="utf-8") == "{}"
diff --git a/tests/unit/pipelex/graph/test_trace_context_emit_flags.py b/tests/unit/pipelex/graph/test_trace_context_emit_flags.py
index 59362d27b..d662b7020 100644
--- a/tests/unit/pipelex/graph/test_trace_context_emit_flags.py
+++ b/tests/unit/pipelex/graph/test_trace_context_emit_flags.py
@@ -23,6 +23,7 @@ class TestTraceContextEmitFlags:
context = TraceContext(graph_id="run_1", data_inclusion=DATA_INCLUSION_OFF)
assert context.emit_graph_events is True
assert context.emit_usage_events is True
+ assert context.describe_pipe_io is True
def test_copy_for_child_preserves_costs_only_flags(self) -> None:
"""costs-only flags survive into a child context (graph off, costs on)."""
@@ -49,3 +50,9 @@ class TestTraceContextEmitFlags:
child = parent.copy_for_child(child_node_id="run_1:node_0", next_sequence=2)
assert child.emit_graph_events is True
assert child.emit_usage_events is False
+
+ def test_copy_for_child_preserves_describe_pipe_io_off(self) -> None:
+ """A run that will write no graphspec keeps its I/O description off in every child context."""
+ parent = TraceContext(graph_id="run_1", data_inclusion=DATA_INCLUSION_OFF, describe_pipe_io=False)
+ child = parent.copy_for_child(child_node_id="run_1:node_0", next_sequence=1)
+ assert child.describe_pipe_io is False
diff --git a/tests/unit/pipelex/libraries/test_pipe_library_lookup.py b/tests/unit/pipelex/libraries/test_pipe_library_lookup.py
index 2a357d782..9eff00d71 100644
--- a/tests/unit/pipelex/libraries/test_pipe_library_lookup.py
+++ b/tests/unit/pipelex/libraries/test_pipe_library_lookup.py
@@ -328,3 +328,18 @@ class TestPipeLibraryLookup:
library.root["scoring.compute_score"] = mock_pipe
library.remove_pipes_by_refs(pipe_refs=["scoring.compute_score"])
assert "scoring.compute_score" not in library.root
+
+
+class TestPipeLibraryOwnPipes:
+ """`get_own_pipes` is the library's own pipes: the aliased dependency entries are not among them."""
+
+ def test_own_pipes_exclude_dependency_entries(self, mocker: MockerFixture):
+ library = PipeLibrary.make_empty()
+ own = _make_stub_pipe(mocker, code="compute_score", domain_code="scoring")
+ library.add_new_pipe(own)
+ # A dependency sharing the host's `domain.code`: keyed by alias, so it lands beside the host's.
+ library.add_dependency_pipe(alias="lib", pipe=_make_stub_pipe(mocker, code="compute_score", domain_code="scoring"))
+ library.add_dependency_pipe(alias="lib", pipe=_make_stub_pipe(mocker, code="other", domain_code="analytics"))
+
+ assert library.get_own_pipes() == [own]
+ assert len(library.get_pipes()) == 3
diff --git a/tests/unit/pipelex/pipe_run/test_delivery_executor.py b/tests/unit/pipelex/pipe_run/test_delivery_executor.py
index e120efe92..a7bd08563 100644
--- a/tests/unit/pipelex/pipe_run/test_delivery_executor.py
+++ b/tests/unit/pipelex/pipe_run/test_delivery_executor.py
@@ -1,5 +1,6 @@
import json
import socket
+from datetime import UTC, datetime
import pytest
from pytest_mock import MockerFixture, MockType
@@ -14,8 +15,15 @@ from pipelex.core.concepts.concept import Concept
from pipelex.core.memory.absence import AbsenceKind, AbsenceRecord
from pipelex.core.memory.exceptions import WorkingMemoryStuffNotFoundError
from pipelex.core.memory.working_memory import WorkingMemory
+from pipelex.core.pipes.pipe_io_artifacts import (
+ INPUT_FORM_FILE_NAME,
+ OUTPUT_FORM_FILE_NAME,
+ PIPE_IO_CONTRACTS_FILE_NAME,
+ render_pipe_io_artifact_files,
+)
from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.text_content import TextContent
+from pipelex.graph.graphspec import GraphSpec, PipelineRef
from pipelex.pipe_run.delivery_assignment import (
DeliveryAssignment,
DeliveryStatus,
@@ -26,6 +34,7 @@ from pipelex.pipe_run.delivery_executor import DeliveryExecutor
from pipelex.pipe_run.exceptions import PipeJobError, StorageDeliveryError, WebhookDeliveryError
from pipelex.system.job_metadata import JobMetadata, RunMetadata
from pipelex.tools.network.exceptions import SsrfBlockedError
+from tests.helpers.pipe_io_artifacts import make_pipe_io_artifacts
def _make_main_stuff() -> Stuff:
@@ -47,9 +56,23 @@ def _make_output_mock(mocker: MockerFixture) -> MockType:
mock_output: MockType = mocker.MagicMock()
mock_output.tokens_usages = None
mock_output.usage_assembly_error = None
+ mock_output.pipe_io_artifacts = None
return mock_output
+def _make_graph_spec() -> GraphSpec:
+ return GraphSpec(
+ graph_id="delivery_test_graph",
+ created_at=datetime(2026, 1, 1, tzinfo=UTC),
+ pipeline_ref=PipelineRef(domain="test_domain", main_pipe="my_sequence"),
+ nodes=[],
+ edges=[],
+ )
+
+
+_COMPANION_FILE_NAMES = (PIPE_IO_CONTRACTS_FILE_NAME, INPUT_FORM_FILE_NAME, OUTPUT_FORM_FILE_NAME)
+
+
@pytest.mark.asyncio(loop_scope="class")
class TestDeliveryExecutor:
async def test_execute_storage_only(self, mocker: MockerFixture) -> None:
@@ -379,6 +402,69 @@ class TestDeliveryExecutor:
usage_doc = json.loads(files["tokens_usages.json"].data.decode("utf-8"))
assert usage_doc == {"tokens_usages": None, "usage_assembly_error": "usage event read failed"}
+ async def test_generate_result_files_writes_the_graphspec_companions_typed(self, mocker: MockerFixture) -> None:
+ """A run that carried its I/O artifacts delivers them beside graphspec.json, byte for byte as the
+ run's own renderer wrote them, so a hosted results prefix reads like a local results directory.
+ """
+ mock_output = _make_output_mock(mocker)
+ mock_output.working_memory_raw = None
+ mock_output.working_memory.smart_dump.return_value = {"root": {}, "aliases": {}}
+ mock_output.working_memory.resolve_main_stuff.return_value = _make_main_stuff()
+ mock_output.graph_spec = _make_graph_spec()
+ artifacts = make_pipe_io_artifacts()
+ mock_output.pipe_io_artifacts = artifacts
+
+ files = await DeliveryExecutor().generate_result_files(mock_output)
+
+ assert "graphspec.json" in files
+ expected = render_pipe_io_artifact_files(artifacts)
+ for file_name in _COMPANION_FILE_NAMES:
+ assert files[file_name].content_type == "application/json"
+ assert files[file_name].data.decode("utf-8") == expected[file_name]
+
+ async def test_generate_result_files_writes_the_graphspec_companions_raw(self, mocker: MockerFixture) -> None:
+ """The raw working-memory branch (a worker without the bundle's classes) delivers them too: the
+ artifacts are already built, so no class registry is needed to write them.
+ """
+ mock_output = _make_output_mock(mocker)
+ mock_output.working_memory_raw = {"root": {"main_stuff": {"content": {"text": "hi"}}}, "aliases": {}}
+ mock_output.graph_spec = _make_graph_spec()
+ mock_output.pipe_io_artifacts = make_pipe_io_artifacts()
+
+ files = await DeliveryExecutor().generate_result_files(mock_output)
+
+ assert "graphspec.json" in files
+ for file_name in _COMPANION_FILE_NAMES:
+ assert file_name in files
+
+ async def test_generate_result_files_omits_the_companions_without_artifacts(self, mocker: MockerFixture) -> None:
+ mock_output = _make_output_mock(mocker)
+ mock_output.working_memory_raw = None
+ mock_output.working_memory.smart_dump.return_value = {"root": {}, "aliases": {}}
+ mock_output.working_memory.resolve_main_stuff.return_value = _make_main_stuff()
+ mock_output.graph_spec = _make_graph_spec()
+
+ files = await DeliveryExecutor().generate_result_files(mock_output)
+
+ assert "graphspec.json" in files
+ for file_name in _COMPANION_FILE_NAMES:
+ assert file_name not in files
+
+ async def test_generate_result_files_omits_the_companions_without_a_graph(self, mocker: MockerFixture) -> None:
+ """The companions describe a graphspec: no graphspec, no companions, whatever the output carries."""
+ mock_output = _make_output_mock(mocker)
+ mock_output.working_memory_raw = None
+ mock_output.working_memory.smart_dump.return_value = {"root": {}, "aliases": {}}
+ mock_output.working_memory.resolve_main_stuff.return_value = _make_main_stuff()
+ mock_output.graph_spec = None
+ mock_output.pipe_io_artifacts = make_pipe_io_artifacts()
+
+ files = await DeliveryExecutor().generate_result_files(mock_output)
+
+ assert "graphspec.json" not in files
+ for file_name in _COMPANION_FILE_NAMES:
+ assert file_name not in files
+
async def test_try_local_hydrate_stuff_returns_typed_for_builtin(self) -> None:
from pipelex.core.stuffs.text_content import TextContent # ruff: ignore[import-outside-top-level]
from pipelex.runtime_hub import get_class_registry # ruff: ignore[import-outside-top-level]
diff --git a/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py b/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
index 4a9045ef9..6a51ae81c 100644
--- a/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
+++ b/tests/unit/pipelex/pipeline/test_runner_validate_plumbing.py
@@ -24,6 +24,7 @@ from typing import TYPE_CHECKING, NamedTuple
import pytest
+from pipelex.core.pipes.pipe_io_artifacts import PipeIOArtifacts
from pipelex.pipeline.runner import PipelexMTHDSProtocol
if TYPE_CHECKING:
@@ -59,9 +60,11 @@ class TestRunnerValidatePlumbing:
# These artifact builders run inside the library window; mock them so the body completes
# without a real loaded library. Their output shaping is pinned in test_validation_report.py
# and the integration test_protocol_validate.py — this module asserts only the plumbing.
- mocker.patch("pipelex.pipeline.validate_in_process.build_pipe_io_contracts", return_value={})
mocker.patch("pipelex.pipeline.validate_in_process.qualify_current_library_crate")
- mocker.patch("pipelex.pipeline.validate_in_process.build_input_form", return_value={})
+ mocker.patch(
+ "pipelex.pipeline.validate_in_process.build_pipe_io_artifacts",
+ return_value=PipeIOArtifacts(pipe_io_contracts={}, input_form={}, output_form={}),
+ )
mocker.patch("pipelex.pipeline.validate_in_process.build_advisory_warnings", return_value=[])
mocker.patch("pipelex.pipeline.validate_in_process.select_primary_blueprint")
mocker.patch("pipelex.pipeline.validate_in_process.best_effort_graph_spec", new=mocker.AsyncMock(return_value=None))
diff --git a/tests/unit/pipelex/runtime_bridge/test_output_serialization.py b/tests/unit/pipelex/runtime_bridge/test_output_serialization.py
index affb5f933..ed4240a4f 100644
--- a/tests/unit/pipelex/runtime_bridge/test_output_serialization.py
+++ b/tests/unit/pipelex/runtime_bridge/test_output_serialization.py
@@ -3,6 +3,7 @@ import pytest
from pipelex.core.concepts.concept import Concept
from pipelex.core.memory.absence import AbsenceKind, AbsenceRecord
from pipelex.core.memory.working_memory import MAIN_STUFF_NAME, WorkingMemory
+from pipelex.core.pipes.pipe_io_artifacts import PipeIOArtifacts
from pipelex.core.pipes.pipe_output import PipeOutput
from pipelex.core.stuffs.stuff import Stuff
from pipelex.core.stuffs.text_content import TextContent
@@ -54,6 +55,22 @@ class TestSerializeCompletedOutput:
assert dto.graph_assembly_error == "graph boom"
assert dto.pipeline_run_id == "run-with-usage"
+ def test_pipe_io_artifacts_and_their_error_cross_the_bridge_boundary(self) -> None:
+ """The artifacts ride the SPI as a JSON-mode dump beside graph_spec, their error beside its error."""
+ artifacts = PipeIOArtifacts(pipe_io_contracts={}, input_form={}, output_form={})
+ pipe_output = PipeOutput(
+ working_memory=_memory_with_aliased_main("result"),
+ pipeline_run_id="run-with-artifacts",
+ pipe_io_artifacts=artifacts,
+ pipe_io_artifacts_error="artifacts boom",
+ )
+
+ dto = serialize_completed_output(pipe_output=pipe_output, workflow_id=None)
+
+ assert dto.pipe_io_artifacts_dump == artifacts.model_dump(mode="json")
+ assert PipeIOArtifacts.model_validate(dto.pipe_io_artifacts_dump) == artifacts
+ assert dto.pipe_io_artifacts_error == "artifacts boom"
+
def test_absent_assembly_serializes_to_none(self) -> None:
"""When the run produced no usage/graph, the boundary fields stay None (not [])."""
pipe_output = PipeOutput(
@@ -69,6 +86,8 @@ class TestSerializeCompletedOutput:
assert dto.tokens_usages_dump is None
assert dto.usage_assembly_error is None
assert dto.graph_assembly_error is None
+ assert dto.pipe_io_artifacts_dump is None
+ assert dto.pipe_io_artifacts_error is None
def test_main_stuff_name_resolves_aliased_root_key(self) -> None:
"""The DTO's main_stuff_name is the actual root key the alias points at."""
diff --git a/wip/run-artifacts-beside-graphspec/design.md b/wip/run-artifacts-beside-graphspec/design.md
new file mode 100644
index 000000000..8975c031f
--- /dev/null
+++ b/wip/run-artifacts-beside-graphspec/design.md
@@ -0,0 +1,107 @@
+---
+status: active
+item: L-260907-817d80
+---
+
+# Design: a run's results carry the I/O artifacts that describe its data
+
+## The problem
+
+A run's `graphspec.json` carries every stuff payload the run produced and nothing that says what those payloads are. The graph renderer (`@pipelex/mthds-ui`, `GraphViewer`) shows a data node's value only when its host passes both `pipe_io_contracts` and `output_form`, keyed by `pipe_ref`; without them it shows the concept's structure table and no data tab, by design (`mthds-ui/src/graph/react/viewer/GraphViewer.tsx:255-273`, "both artifacts or neither"). The three artifacts — `pipe_io_contracts`, `input_form`, `output_form` — are the validate report's own fields, and today they exist only on `/validate`.
+
+The ledger item asks that a run write them beside its `graphspec.json`, as three sibling files under the standard's names. This document confirms the ask, corrects the item's premise about *where* they can be built, and settles the shape that serves the local file layout and the hosted plane alike.
+
+## What the survey established
+
+### Every consumer of a run's graph is missing them, and each patches around it differently
+
+- **`vscode-pipelex`** has the reader and no producer: `readRunArtifacts` (on branch `fix/Expanded-input-slot`, `editors/vscode/src/pipelex/graph/runArtifacts.ts:46-48,110-129`) loads `pipe_io_contracts.json`, `output_form.json` and an optional `input_form.json` from the graphspec's own directory, takes the first two together or not at all, and is silent on absence.
+- **`pipelex-app`** is the only consumer that renders a run's graph *with* data, and it does so by pairing the run's `graph_spec` (from `GET /v1/runs/{id}/results`) with the artifacts of a **separate `/validate` of the current editor buffer**, held in a non-persisted client store (`src/actions/mthds-validator.ts:296-300`, `src/hooks/use-method-validation.ts:134-151`). The app documents the resulting gap itself: "a run restored without its validate artifacts has a value and no declaration of what it is" (`src/components/method-run/output-render.tsx:37-42`, also `flowchart-view.tsx:66-72`). A historic run whose method has since changed is rendered against the wrong description.
+- **`pipelex-mcp`** mounts `GraphViewer` on a completed run with no artifacts at all (`src/views/run-graph.tsx:236-244`, `src/views/run-follow.tsx:456-466`), so every hosted run graph it shows takes the no-data floor.
+- **Neither SDK** carries the artifacts on a run-result type; `RunResults` in `@pipelex/sdk` has `graph_spec` and nothing describing it (`pipelex-sdk-js/src/runs.ts:156-190`). The platform's `GET /v1/runs/{id}/results` reads a **hardcoded set of result filenames** from S3 and relays them verbatim (`pipelex-server/platform/src/pipelex_platform/routers/v1/runs.py:141-176`); the platform persists no contracts or forms anywhere, and the `Run` row keeps only `mthds_contents` as "the only record of what ran" (`shared/src/pipelex_shared/schemas/run.py:126`).
+
+So the need is real and wider than the item states: a run's own artifacts are the only correct description of a run's data, locally and hosted, and no path produces them today.
+
+### The three builders need the run's library window, and the item's proposed hook is outside it
+
+`build_pipe_io_contracts` (`pipelex/pipeline/pipe_io_contracts.py:135`), `build_input_form` and `build_output_form` (`pipelex/pipeline/input_form.py:154,190`) take the live pipes and read the current library: JSON-Schema rendering resolves bundle-defined structure classes through the class registry, and the forms qualify the current library's crate (`qualify_current_library_crate`, `input_form.py:246`). The validate path says so in as many words and builds them inside the window before its `finally` tears it down (`pipelex/pipeline/validate_in_process.py:86-91,109-115`); the hosted Temporal validator does the same in its worker's one window (`pipelex-server/temporal/pipelex_temporal/tprl_pipe/act_dry_validate.py:142-156`).
+
+The item names the write sites as the natural hook — `generate_graph_outputs` / `save_graph_outputs_to_dir` and the delivery executor's `_generate_graph_files`. Neither holds the window:
+
+- **The local CLIs write after the window has closed.** `PipelineRunner.execute` restores the outer library and tears the run library down in its `finally` (`pipelex/pipeline/runner.py:303-315`) *before* returning to `pipelex run`, which only then calls `generate_graph_outputs` and `save_graph_outputs_to_dir` (`pipelex/cli/commands/run/_run_core.py:281-287`); `pipelex-agent run` is the same shape (`pipelex/cli/agent_cli/commands/run/_run_core.py:173-190`).
+- **The hosted delivery may run on a worker that never loaded the bundle.** In the Temporal plugin the `PipeOutput` is dehydrated before the workflow's tail precisely because `act_deliver` "may run on a worker that has never loaded this bundle" (`pipelex-server/temporal/pipelex_temporal/tprl_pipe/wf_pipe_run.py:430-435`); `DeliveryActivityArg` carries the output, the scope and the assignment, no crate and no pipes (`act_deliver.py:17-31`); and the delivery executor's raw-working-memory branch and `try_local_hydrate_stuff` exist because the classes may not be registered (`pipelex/pipe_run/delivery_executor.py:90-97,218-246`).
+
+The direct-mode delivery is the one write site that *is* inside the window: `PipeRun.run` delivers in its `finally`, which runs inside `runner.execute`'s `try` (`pipelex/pipe_run/pipe_run.py:76-103`). That is not enough to build on, since the same class delivers the Temporal path from outside the window.
+
+### How a run's graph already crosses the same boundary
+
+`graph_spec` is the precedent. It is assembled at the end of the run onto `pipe_output.graph_spec` (`assemble_tracing_on_output`, `pipe_run.py:82-90`; the Temporal twin stamps it in the workflow tail, `wf_pipe_run.py:481-517`), rides on `PipeOutput` — a wire model of the transport boundary (`docs/specs/pipelex-transport-boundary.md`, section C) — crosses the SPI payload as `graph_spec_dump` (`pipelex/runtime_bridge/payloads.py:81`, `serialization.py:65`), is rehydrated by `pipelex-api` for the `/execute` response (`pipelex-api/api/routes/pipelex/pipeline.py:134-167`), and is written by whoever holds the output: the CLIs to a directory, the delivery executor to storage. Every writer serializes what the run assembled; none rebuilds it.
+
+## Decision
+
+**The artifacts are built once, inside the run's library window, and carried on `PipeOutput` beside `graph_spec`. Every writer that serializes `graph_spec` to `graphspec.json` serializes them to three sibling files.**
+
+### 1. One model, one builder
+
+A new module `pipelex/core/pipes/pipe_io_artifacts.py` holds:
+
+- `PipeIOArtifacts`, a pydantic model with exactly the three report fields under the report's names and types: `pipe_io_contracts: PipeIOContracts`, `input_form: InputForm`, `output_form: OutputForm`. `extra="forbid"`. It is a grouping, not a new shape: each field is the standard's artifact, and the three are always produced together because they share one key set (all three iterate the same pipes, `input_form.py:155-157`).
+- `build_pipe_io_artifacts(pipes, *, qualified_crate=None) -> PipeIOArtifacts`, which qualifies the current library's crate once and runs the three existing builders off it, exactly the sequence `validate_in_process.py:109-115` performs today. `validate_bundles_in_process` and the projection-corpus command call it instead of the three builders, so the sequence exists in one place and a future fourth artifact is populated everywhere or nowhere — the same rule `build_validation_report` states for the report.
+- The three filenames as module constants, moved from `generate_projection_corpus_cmd.py:76-78` (`pipe_io_contracts.json`, `input_form.json`, `output_form.json`), and one rendering function that maps a `PipeIOArtifacts` to `{filename: text}` using the corpus's byte discipline (`json.dumps(payload, indent=2, ensure_ascii=False)` plus a trailing newline, over `{pipe_ref: model.model_dump(mode="json")}`, `generate_projection_corpus_cmd.py:229-232`). The corpus command uses the same function, so for the same bundle a results directory and the committed fixture corpus hold byte-identical files.
+
+The validate report keeps its flat fields; `PipeIOArtifacts` is the carrier, not a new report shape.
+
+### 2. Built in the window, carried on the output
+
+`PipeOutput` gains `pipe_io_artifacts: PipeIOArtifacts | None = None`, beside `graph_spec` (`pipelex/core/pipes/pipe_output.py:27`). It is set only on the top-level output, in the same place the graph is assembled:
+
+- **Direct mode.** In `PipeRun.run`, right after `assemble_tracing_on_output`, when `pipe_output.graph_spec` is not `None`: `pipe_output.pipe_io_artifacts = build_pipe_io_artifacts(get_own_pipes())`, where `get_own_pipes()` (`pipelex/interpreter_hub.py`) enumerates the current run library without its dependency packages' aliased entries (a round-1 review narrowing: an aliased pipe would be keyed by bare `pipe_ref` in the artifacts and collide with the host's). This runs inside `runner.execute`'s window, before the direct-mode delivery in the same `finally` and before the CLI receives the output. The build is best-effort in the same way the graph render is: a failure of the builders, of any kind, leaves the field `None` and sets `pipe_output.pipe_io_artifacts_error` to the message (round 1 narrowed this to the builders' own error types so a bug would surface; round 2 reversed it, because the build runs in the `finally` ahead of the delivery, where an escaping exception replaces the run's outcome and skips the delivery of a completed run, and the failure notification must always fire); mirroring `graph_assembly_error` and `usage_assembly_error` on the same model, so a consumer can tell "graph tracing off" from "build failed"; it never fails a run that succeeded.
+- **Temporal mode** is the plugin's twin, in `pipelex-server` (see "Consequences"): an activity that opens the transported crate's window, calls the same builder over the same enumeration and returns the model; the workflow stamps it onto the output before `act_deliver`, where it already stamps `graph_spec`.
+
+The condition is the graphspec's own: the artifacts exist to describe a graphspec's data, so they are built when a graph is assembled *and* the run will write a graphspec (`graphs_inclusion.graphspec_json`), and not otherwise; the run setup stamps that as `describe_pipe_io` on the trace context, and validate's own graph dry run stamps it off, since validate already built the artifacts for its report and a second build would be thrown away. A run with graph tracing off has neither.
+
+### 3. Every writer serializes them beside the graphspec
+
+`GraphOutputs` (`pipelex/graph/graph_factory.py:27`) gains three optional text fields, `pipe_io_contracts_json`, `input_form_json`, `output_form_json`; `generate_graph_outputs` takes `pipe_io_artifacts: PipeIOArtifacts | None = None` and fills them, through the rendering function above, when **`graphs_inclusion.graphspec_json`** is on and artifacts were given. `save_graph_outputs_to_dir` writes them under the three constant names beside `graphspec.json`; `DeliveryExecutor._generate_graph_files` adds them through `_add_optional_text_file` beside its `graphspec.json`, so the hosted results prefix gains the same three keys. The two CLIs pass `pipe_output.pipe_io_artifacts` through.
+
+Gating on `graphspec_json` is the item's own request and the right one: a run that asks for no graphspec writes nothing that describes one, and a caller that overrides the flag at render time (the agent CLI does, `_run_core.py:150-165`) gets the siblings with it. There is no new inclusion flag; the three files are the graphspec's companions, not a fourth graph output.
+
+The agent CLI renames `graphspec.json` to `live_run_graph.json`; the siblings keep their canonical names beside it, because the VS Code reader resolves them from the graphspec's directory, not from its name.
+
+### 4. The key set is the bundle's own pipes
+
+Validate keys the artifacts by the validated bundle's pipes, and a run keys them the same way: every pipe of the library it executed against that the library holds under a bare `pipe_ref`, which is the entry bundle, its imports and any library directories, so a consumer that also drives a run form from `input_form` gets the method's other entry pipes too. A dependency package's pipes are left out, and the review round settled why: the library keys them `alias->domain.code`, the builders would key them by bare `pipe_ref` and silently overwrite a host pipe of the same name, and the host's crate holds no blueprint of theirs, so their descriptors would come out unknown anyway. Describing them properly is a deferred design of its own (see the plan's deferred items). The set is bounded by the method's own size. Pipes the runtime synthesizes at run time and never registers (the batch wrapper the item observed) are not described, and the renderer's undescribed-value view is the documented floor for those.
+
+### 5. The SPI payload and the `/execute` response carry them
+
+`PipelexPipeRunOutput` (`pipelex/runtime_bridge/payloads.py:64`, `extra="forbid"`) gains `pipe_io_artifacts_dump: dict[str, Any] | None = None`, filled by `serialize_completed_output` from `model_dump(mode="json")` like `graph_spec_dump`. `pipelex-api` rehydrates it in `_pipe_output_from_run_output` so the synchronous `/execute` response carries `pipe_output.pipe_io_artifacts` beside `pipe_output.graph_spec`. Wherever the run's graph travels, its description travels with it; a client that renders the `/execute` graph needs nothing else.
+
+This is additive on every wire: an optional field with a `None` default on `PipeOutput`, on the SPI payload and in `pipelex-api`'s published OpenAPI artifact. `PipeOutput` is a distributed-execution wire model, and `pipelex` is pinned to one exact version across `pipelex-server`, so the field crosses the activity boundary the moment the pin moves; no reader on either side breaks on its absence.
+
+## Alternatives rejected
+
+- **Build at the write sites** (the item's proposal). Impossible as stated: the CLI writes after `runner.execute` has torn the library down, and the hosted delivery runs where the bundle may never have been loaded. Building there would mean reopening a library window at every writer, which the transport does deliberately not do for delivery.
+- **Embed them in `GraphSpec`.** `GraphSpec` is `extra="forbid"` and standard-facing (`meta.format = "mthds"`); the fields would be a format change every reader must follow, the payloads are unrelated to the graph's shape, and the results layout already keeps one run's projections side by side. The `meta` bag is for format and mode. Embedding would not have avoided the window problem either.
+- **Re-validate `mthds_contents` on the platform** when a run is viewed (the platform keeps the bundle that ran, and `/validate` accepts inline contents). It is hosted-only, so the local file layout that `vscode-pipelex` reads gains nothing; it costs a full validation and a second round trip per run view; and it describes the bundle text, not the library the run executed against, when the two diverge.
+- **A private attribute on `PipeOutput`** (the `_job_metadata` pattern). It does not survive serialization, and the artifacts must cross the Temporal activity boundary to reach delivery.
+- **A reference back to the bundle instead of the artifacts.** A local run's graphspec has no registry to resolve one against, and the hosted `Run` row has no method version to point at.
+- **A fourth inclusion flag.** The files are the graphspec's companions; a run that writes a graphspec without them is the state this design ends.
+
+## Consequences across repos
+
+`pipelex` ships the model, the builder, the field, the SPI dump and the writers. The chain that consumes it, each a ledger item filed at ratification (ids in the plan's Phase 0):
+
+- **`pipelex-api`** — at the pin bump, rehydrate `pipe_io_artifacts_dump` in `_pipe_output_from_run_output` and regenerate the committed OpenAPI artifact (`PipeOutputWire`, `api/schemas/models.py:370-381`, gated by `test_openapi_contract.py`).
+- **`pipelex-server`, `temporal` member** — build the artifacts in the run's window and stamp them before delivery: an activity opening the crate's window (`scoped_library_for_crate`) and calling `build_pipe_io_artifacts` over the library's pipes, invoked from `_finish_run_root` beside `act_assemble_tracing`; the orchestrator's blocking mapping fills `pipe_io_artifacts_dump`. Sweep `transport/` for every site that copies `PipeOutput` fields by name (`prepare_output_for_transport`, `rehydrate_pipe_output_with_crate`) and carry the field. The plugin already imports the three builders for validation, so no new symbol enters the pinned transport surface; `PipeOutput` is already on it as a wire model, and the change is additive.
+- **`pipelex-server`, `platform` member** — `GET /v1/runs/{id}/results` reads the three new keys beside the existing set and relays them on `RunResultsResponse`; an older run reads them as `null`, exactly as `tokens_usages.json` was introduced. `docs/specs/pipelex-platform-api.md` names the relayed file set and moves with it.
+- **`pipelex-sdk-js`** — `RunResults` gains the three fields, typed from `mthds/protocol`.
+- **`pipelex-app`** — pair a run's graph with the run's own artifacts when the results carry them, falling back to the buffer's validate only for a run that predates them.
+- **`pipelex-mcp`** — pass the run's artifacts to `GraphViewer` in the run views.
+- **`workspace` and `conformance`** — a short spec section on the results-directory layout (the sibling names, the `graphspec_json` gate, the "both or neither" rule for the contracts and the output form, the directory-not-name resolution the VS Code reader relies on) paired with a conformance test running `pipelex run` in dry-run mode over a corpus bundle. Filed rather than done here because it lives in two other repos and the test needs an installable release.
+- **`vscode-pipelex`** — nothing: the reader is written against this layout and is blocked only on the producer.
+
+## Questions settled at ratification
+
+- **Should the synchronous `/execute` response carry the artifacts?** Decided yes, for the "wherever the graph travels" rule and because the cost is only paid when a graph is on. The alternative is to fill the SPI dump and stop there, leaving `/execute` clients to call `/validate`.
+- **Should the key set be restricted to the pipes the graph references?** Decided no; the whole library is simpler, never falls short, and serves the run form too.
+- **Should a build failure be reported on a field**, as `graph_assembly_error` reports a graph assembly failure? Decided yes at ratification: `pipe_io_artifacts_error`, the third instance of a pattern the model already carries twice, so a hosted failure is visible to the consumer that opens the graph and not only in a worker log nobody reads.
diff --git a/wip/run-artifacts-beside-graphspec/plan.md b/wip/run-artifacts-beside-graphspec/plan.md
new file mode 100644
index 000000000..3a23ca426
--- /dev/null
+++ b/wip/run-artifacts-beside-graphspec/plan.md
@@ -0,0 +1,87 @@
+---
+status: active
+item: L-260907-817d80
+---
+
+# Plan: a run's results carry the I/O artifacts that describe its data
+
+The design is [`design.md`](./design.md). This tracker is the implementation order for the `pipelex` half, the checkpoints where a session hands off, and the downstream chain that follows the release.
+
+Working rules for every phase: tests before implementation; `make agent-check` with the changes staged after every code change; `make agent-test` before a checkpoint; if `make drift-check` opens a contract, resolve it with `/drift-review` rather than around it.
+
+## Phase 0 — Ratification and the downstream filing
+
+- [x] The design is read and ratified on 2026-09-07; its frontmatter and this plan flip to `active` in the same change. The four calls: build in the run window and carry on `PipeOutput`; the `/execute` response carries the artifacts; a build failure is reported on `pipe_io_artifacts_error`; the spec and conformance half is filed, not done here.
+- [x] The downstream ledger items are filed, each discovered from and blocked by L-260907-817d80 (no release item exists yet; the release that carries the field is what unblocks them in practice): `pipelex-api` L-260907-c772e9 (rehydrate the dump, regenerate OpenAPI), `pipelex-server` `temporal` L-260907-2ad3d8 (the in-window activity and the orchestrator dump, with the `transport/` sweep of every by-name `PipeOutput` copy), `pipelex-server` `platform` L-260907-682a2b (relay the three files on run results, and move `docs/specs/pipelex-platform-api.md` with it), `pipelex-sdk-js` L-260907-b7b9b1 (`RunResults` fields), `pipelex-app` L-260907-b22bad (pair a run's graph with its own artifacts), `pipelex-mcp` L-260907-16d2c6 (pass them to the run views), `workspace` L-260907-f6fd8d (the results-directory spec section and its conformance test).
+- [x] Recorded on L-260907-817d80 that the item's proposed hook is outside the library window, with the two evidence sites (the log entry of 2026-09-07).
+
+## Phase 1 — The model and the builder
+
+Modules: `pipelex/core/pipes/pipe_io_artifacts.py` (the carrier, the filenames and the rendering, importing only the protocol package so `PipeOutput` can import it; it lives under `core/` because `PipeOutput` is kernel-layer and the kernel-layer closure tests refuse an import from `pipelex/pipeline/`, where the first cut placed it) and `pipelex/pipeline/build_pipe_io_artifacts.py` (the builder, which needs the library machinery). One module was the first cut and imported circularly through `PipeOutput`; the split is the plain fix.
+
+- [x] Tests first: `tests/unit/pipelex/core/pipes/test_pipe_io_artifacts.py` (the model forbids extras and round-trips; the rendering yields the three filenames with the corpus's byte discipline, `ensure_ascii=False` proven with a non-ASCII description) and `tests/integration/pipelex/pipeline/test_pipe_io_artifacts.py` (the builder equals the three builders in sequence on the probe bundle, with and without a caller-held qualification, and the three maps share one key set).
+- [x] `PipeIOArtifacts` (`extra="forbid"`, the three fields under the report's names and types), `build_pipe_io_artifacts(pipes, *, qualified_crate=None)`, the three filename constants, and `render_pipe_io_artifact_files`.
+- [x] `validate_bundles_in_process` builds through `build_pipe_io_artifacts` and spreads into `build_validation_report`; the report's flat fields do not change. The two tests that patched the old builders at the orchestrator's namespace now patch the builder module.
+- [x] `generate_projection_corpus_cmd.py` renders through `render_pipe_io_artifact_files` and its own filename constants are gone (the corpus test imports them from the artifacts module). Regenerated the corpus with the four bundles in the README's order and compared against `mthds-python/tests/fixtures/protocol/`: the three files and the whole `inputs_template/` tree are byte-identical.
+- [x] The `trace_input_semantics` command keeps calling the builders directly: it traces hops, and its hop files are a separate discipline.
+
+## Phase 2 — Built in the window, carried on the output
+
+- [x] Tests first (`tests/integration/pipelex/pipeline/test_direct_pipe_io_artifacts.py`, `tests/unit/pipelex/runtime_bridge/test_output_serialization.py`): a `PipeRun.run` test that runs a small bundle with graph tracing on and asserts `pipe_output.pipe_io_artifacts` is set, keyed by every `pipe_ref` in `graph_spec.pipe_registry`, and is `None` when graph tracing is off; a test that a builder raising leaves the field `None`, sets `pipe_io_artifacts_error` to the message and keeps the run successful (patch the builder on the module, not the instance); a serializer test that `serialize_completed_output` fills `pipe_io_artifacts_dump` and leaves it `None` when the output has none.
+- [x] `PipeOutput.pipe_io_artifacts: PipeIOArtifacts | None = None` and `pipe_io_artifacts_error: str | None = None` beside `graph_spec` and `graph_assembly_error`.
+- [x] `PipeRun.run`: after `assemble_tracing_on_output`, when graph events were on and a graph was assembled, `_build_pipe_io_artifacts_on_output` builds over `get_own_pipes()` inside the same `finally`, before the direct-mode delivery; any exception sets `pipe_io_artifacts_error` and logs a warning (a blind except, deliberately: a description must never fail a completed run, and an exception escaping the `finally` there would skip the run's delivery).
+- [x] `PipelexPipeRunOutput.pipe_io_artifacts_dump` and `pipe_io_artifacts_error`, filled by `serialize_completed_output`.
+- [x] Swept `pipelex` for sites rebuilding a `PipeOutput` field by field: none carries `graph_spec` (the controllers build sub-outputs with a working memory only), so nothing to carry. The by-name copies live in `pipelex-server/transport/`, which is L-260907-2ad3d8.
+
+## Phase 3 — Every writer serializes them beside the graphspec
+
+- [x] Tests first, extending `tests/unit/pipelex/graph/test_graph_output_generation.py` and `tests/unit/pipelex/pipe_run/test_delivery_executor.py` (with a shared hand-built artifacts fixture in `tests/helpers/pipe_io_artifacts.py`): `generate_graph_outputs` fills the three texts when `graphspec_json` is on and artifacts are given, none when the flag is off, none when artifacts are `None`; `save_graph_outputs_to_dir` writes the three files beside `graphspec.json` and returns their keys; `generate_result_files` emits the three `ResultFile` entries when the output carries artifacts and omits them otherwise, on both the typed and the raw working-memory branches.
+- [x] `GraphOutputs` fields, the `pipe_io_artifacts` parameter on `generate_graph_outputs`, `save_graph_outputs_to_dir`, `DeliveryExecutor._generate_graph_files`.
+- [x] `pipelex run` and `pipelex-agent run` pass `pipe_output.pipe_io_artifacts`; the agent CLI's `graph_files` side-effect map names the three paths beside `graph_spec`. Both verified by hand on the probe bundle in dry mode.
+- [x] `tests/integration/pipelex/pipeline/test_run_artifacts_parity.py`, the design's promise: for one corpus bundle, the file a run writes equals the corpus's committed file for that bundle, byte for byte, and its parsed value equals the corresponding field of the report `validate_bundles_in_process` returns for the same bundle.
+- [x] `tests/e2e/pipelex/cli/test_run_artifacts_beside_graphspec.py`, an end-to-end CLI test: `pipelex run` on a bundle with a graph, in dry-run mode so no inference is needed, leaves a results directory with `graphspec.json` and the three siblings, each parsing as a JSON object keyed by `pipe_ref`.
+
+### Checkpoint 1
+
+The runtime half is complete when Phases 1 to 3 are green under `make agent-check` and `make agent-test`, and `make test-ts-gates` if anything under `pipelex/codegen/emitters/` was touched (it should not have been). Record here: the decisions taken, anything left out, and the state of the parity test.
+
+Reached on 2026-09-07. `make agent-check` is green. Decisions beyond the design: the carrier and the builder are two modules (see Phase 1); the run's failure catch is blind, with the reason on the `except` line (round 1 narrowed it to the builders' own error types, round 2 restored it: see the design's direct-mode paragraph); the delivery executor writes the companions on both the typed and the raw working-memory branches, since the artifacts are already built and need no class registry. Left out: nothing under `pipelex/codegen/emitters/` moved, so `make test-ts-gates` was not run. The parity test compares per pipe and asserts byte identity only when the run library's key set equals the validated bundle's, which it does for the probe bundle in the test harness.
+
+## Phase 4 — Documentation, changelog, specification
+
+- [x] `docs/under-the-hood/execution-graph-tracing.md`: the outputs table gains the three siblings, gated by `graphspec_json`; the delivery paragraph names them beside `tokens_usages.json`; the configuration listing's comment on `graphspec_json` says the siblings follow it.
+- [x] `docs/tools/cli/run.md`: what a results directory holds, and that the three files describe the graphspec's data for a graph viewer.
+- [x] The agent CLI's run documentation (`docs/tools/cli/agent-cli.md`, Graph Visualization) and its contract doc (`pipelex/cli/agent_cli/CLAUDE.md`) name the siblings and the `graph_files` keys; the `cli-docs` drift contract was acked with that review.
+- [x] `CHANGELOG.md`, Unreleased, Added: one condensed entry — what a run's results now carry, that `PipeOutput` and the `/execute` response carry `pipe_io_artifacts` beside `graph_spec`, that the hosted results prefix gains the three keys, and that the fixture corpus is unchanged.
+- [x] The workspace `docs/specs/` section and its conformance test are L-260907-f6fd8d, filed at ratification: they live in two other repos and the test needs an installable release. The transport-boundary spec's wire-model table needs no row: `PipeOutput` is already on it.
+- [x] `make check-rules` is not touched by this work; no agent-rules source changed.
+
+## Phase 5 — Landing and the downstream chain
+
+- [ ] `/rev` at the derived profile before the pull request; the PR body carries `Closes L-260907-817d80`.
+- [ ] After the merge, `/ledger-land`; the release that carries the change is what unblocks the downstream items filed in Phase 0, and the `pipelex-server` pin bump is the moment the Temporal twin lands — until then a hosted run writes `graphspec.json` without its siblings, and the platform relays nothing new.
+- [ ] `vscode-pipelex` L-260906-e9ab24 verifies end to end against a real `pipelex run` results directory once the release is installable.
+
+## Deferred from the review rounds
+
+Findings of the round-1 `/rev` pass at profile 4 and the round-2 pass at profile 5 (both 2026-09-07) that are real but not this campaign's to fix. Each is a candidate for its own item once a consumer asks for it.
+
+Round 2 fixed three things and deferred the rest: the agent CLI now settles its graph inclusion before the run (the build gate and the render gate read different configs, so `graphspec_json = false` in the user's config produced a graphspec with no companions); the stale-companion removal logs a warning per file, since the agent CLI's directory is the user's own bundle directory; and the build's catch is blind again, so a builder bug cannot skip the delivery of a completed run.
+
+- **The artifacts cover the whole run library, and the cost follows.** `get_own_pipes()` is every non-aliased pipe of the run library, so `library_dirs` and `PIPELEXPATH` bundles are described too, at the end of every graph-enabled run, synchronously on the event loop, with an uncached JSON-Schema render per pipe input and output; the form deriver's cycle guards are path-scoped, so a DAG of repeated concept references expands exponentially (a reviewer's probe: a dozen chained concepts each referencing its predecessor twice gave a descriptor near 300 KB). All of it pre-exists in `build_input_form` and `/validate`; the branch moves it onto the run's hot path and into the SPI payload beside `graph_spec_dump`, where the direct orchestrator dumps the same artifacts a second time for the response. On a host serving a caller-supplied `library_id`, the delivered artifacts describe every method in that library, not only the one that ran. One measurement on a realistic library decides between narrowing the scope to the executed bundle (which changes what a viewer can resolve for a cross-bundle call), an expansion budget reported on `pipe_io_artifacts_error`, and leaving it. This absorbs the "Payload growth" entry below.
+- **Key order and parity.** The run side's key order is the library's insertion order and validate's is `result.pipes`; nothing sorts either, and the parity test asserts byte identity only while the two key sets match. Sorting would break byte identity with the corpus already committed downstream, so this waits for the spec item L-260907-f6fd8d to say whether order is part of the contract.
+- **`pipe_io_artifacts_error` is read by no local surface either.** The hosted half is the entry below; locally, a build failure leaves a complete-looking graph output (viewer, graphspec, `graph_files`) with the companions absent and one warning in the log. Surfacing it in the agent CLI's envelope and the human CLI's summary is the same contract question as the hosted marker.
+- **Storage redelivery to a reused scope.** The delivery executor never removes a previous delivery's companions from a storage prefix; the scope identifies the run by contract and no optional result file (`tokens_usages.json`, the viewer) is invalidated there today, so this is the storage layout's property, not the companions'.
+- **The removal sweep propagates `PermissionError` or `IsADirectoryError`** from a companion path that is not a plain writable file, before the agent CLI writes `live_run.json`; and `write_text` follows a symlinked companion to its target. A guard costs a try block; it waits for a report of the shape occurring.
+- **Windows line endings.** Every byte-discipline write goes through `write_text` without `newline="\n"`, so a run's files and a regenerated corpus come out CRLF on Windows while the committed corpus is LF. Pre-existing in the corpus generator; `newline="\n"` on those writes is the fix.
+- **Tests not written.** The agent CLI's `graph_files` companion keys have no test; the `PipeIOArtifacts` fixture in `tests/unit/pipelex/core/pipes/test_pipe_io_artifacts.py` duplicates `tests/helpers/pipe_io_artifacts.py`; the three-site retyping of the companion names (the writer, the delivery executor, the agent CLI) has no single list to drift from.
+
+- **`pipe_io_artifacts_error` never reaches a delivered results prefix.** The delivery executor writes the three companions when the output carries them and nothing when it does not, so a hosted consumer cannot tell "graph tracing off" from "build failed" the way `tokens_usages.json` lets it tell for usage. The ratification rationale for the field was hosted visibility. The fix is a small marker beside the graphspec carrying the error, but its name is a new contract for the readers (`vscode-pipelex`, `pipelex-app`), so it waits for the spec item L-260907-f6fd8d to name it.
+- **The agent CLI's live and dry runs share one companion set.** `live_run_graph.json` and `graphspec.json` sit in the same directory with one `input_form.json`; editing the bundle between a live run and a dry run leaves the older graph described by the newer declarations, exactly as `live_run.json` itself goes stale. Per-graph snapshots are a change to the agent CLI's file layout, not to this feature.
+- **The artifacts describe declared output, not a step's effective `output_multiplicity`.** A `PipeLLM` declared `Text` and run with `output_multiplicity=2` returns a list while its contract says single. The validate report has the same property, and the graph viewer already lives with it; describing effective invocations is a change to the contracts themselves.
+- **Describing dependency pipes.** Left out of the key set (design §4). Doing it needs the dependency's own qualified crate and alias-aware keys in the three artifacts, which is a protocol question before it is a runtime one.
+- **Payload growth.** `pipe_io_artifacts` rides `PipeOutput` across the Temporal activity boundary and `pipe_io_artifacts_dump` rides the SPI payload for every graphspec-writing run. Measure a serialized `PipeOutput` on a large real method before the `pipelex-server` pin moves; Temporal's payload limit does not fail cleanly.
+
+## Live state
+
+Decisions taken so far are in the design's "Decision" and "Questions settled at ratification" sections. Phases 0 to 4 are implemented in the worktree on `feature/Run-artifacts-beside-graphspec`, from `pipelex` `dev` as of the commit that added the compact Commands rules; Checkpoint 1 below records the state at the end of Phase 4, and the review rounds that followed narrowed the build to the library's own pipes, gated it on `graphspec_json` through `describe_pipe_io` on the trace context (which the agent CLI now settles before the run), made a written graphspec remove stale companions with a warning, and restored the blind catch around the build. What remains is Phase 5.