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.

32.5 KB
Raw Blame
"""Tests for `POST /v1/pipe-io` — a method's three I/O artifacts off the resolved crate, with no dry run.

Pins `conformance/specs/pipelex-codegen.md#the-pipe-io-route`, in the `conformance` repo beside the
tests that verify it: the route takes the method's tree as the protocol's `files` map XOR a
`method_ref`, resolves it through the crate routes' static core, selects a pipe with the per-pipe
routes' chain, and returns `pipe_io_contracts`, `input_form` and `output_form` keyed by qualified
`pipe_ref`, beside `pipe_ref`, `default_pipe_ref`, `pending_signatures`, `is_runnable` and, on
request, the method's bundles. The pinning cases hold each artifact equal to `/v1/validate`'s
same-named view for the same tree and pipe; the teardown cases hold the loaded-on-success contract on
every exit.
"""

import base64
from collections.abc import Callable
from pathlib import Path
from typing import Any

import pytest
from fastapi import Depends, FastAPI
from fastapi.testclient import TestClient
from mthds.protocol.problem.registry import CoreCode
from pipelex.errors.problem import ProblemView, make_problem
from pipelex.interpreter_hub import get_library_manager
from pipelex.pipeline.exceptions import SCHEMA_UNRENDERABLE_FINDING, PipeIOContractError
from pytest_mock import MockerFixture

from pipelex_api.exception_handlers import register_exception_handlers
from pipelex_api.limits import MAX_PIPE_CODE_LEN
from pipelex_api.problem_view import mark_operator_request
from pipelex_api.routes import router as api_router
from tests.unit._constants import (
    COLLIDING_ECHO_LIST_MTHDS,
    HEADER_AND_DEFINITION_BATCH,
    INVALID_MAIN_PIPE_MTHDS,
    NO_MAIN_PIPE_MTHDS,
    SECOND_MAIN_PIPE_MTHDS,
    SHAPES_MTHDS,
    SIBLING_MTHDS,
    SIGNATURE_MTHDS,
    SIGNATURE_ONLY_BATCH,
    STUB_METHOD_ADDRESS,
    STUB_METHOD_MANIFEST_MAIN_PIPE_SHOUT,
    STUB_METHOD_MANIFEST_NO_MAIN_PIPE,
    STUB_METHOD_MANIFEST_NOMAIN_ENTRY,
    VALID_MTHDS,
)
from tests.unit._problems import assert_problem

PIPE_IO_PATH = "/v1/pipe-io"

# The address-form reference the stubbed clone (`install_method_package`) answers to.
STUB_METHOD_REF = f"{STUB_METHOD_ADDRESS}@v0.1.0"

# The three artifact maps the valid arm carries, sharing one key set.
ARTIFACT_FIELDS = ("pipe_io_contracts", "input_form", "output_form")

# The code of a malformed request's 422, which the runner authors itself; a pipe-selection refusal is answered under the
# code its failure names.
REQUEST_SHAPE_CODE = "request.invalid"

# Every field only the valid arm carries: the invalid arm is the crate verdict alone.
VALID_ARM_ONLY_FIELDS = ("pipe_ref", "default_pipe_ref", *ARTIFACT_FIELDS, "pending_signatures", "is_runnable", "files")


def _build_client(*, as_operator: bool = False) -> TestClient:
    """The routes behind the production handlers; `as_operator` marks each request as the operator's, who reads `diagnostics`."""
    app = FastAPI()
    app.include_router(api_router, prefix="/v1", dependencies=[Depends(mark_operator_request)] if as_operator else [])
    register_exception_handlers(app)
    return TestClient(app)


def _files(*contents: str) -> dict[str, str]:
    """A method tree holding each bundle at its own tree path, as text entries of a `files` map."""
    return {f"bundle_{index}.mthds": content for index, content in enumerate(contents)}


def _valid_arm(client: TestClient, payload: dict[str, Any]) -> dict[str, Any]:
    response = client.post(PIPE_IO_PATH, json=payload)
    assert response.status_code == 200, response.text
    body: dict[str, Any] = response.json()
    assert body["is_valid"] is True, response.text
    assert "errors" not in body
    return body


def _assert_keys(body: dict[str, Any], expected: set[str]) -> None:
    for field_name in ARTIFACT_FIELDS:
        assert set(body[field_name]) == expected, f"`{field_name}` keyed by {sorted(body[field_name])}, expected {sorted(expected)}"


def _assert_input_422(response: Any, *, code: str) -> dict[str, Any]:
    """Assert a runner-authored no-verdict input 422 of the given `code`, and return its problem."""
    problem = assert_problem(response, status=422, code=code)
    assert problem["domain"] == "input"
    assert "is_valid" not in problem
    return problem


def _assert_selection_refusal(response: Any, *, code: CoreCode, params: dict[str, Any]) -> dict[str, Any]:
    """Assert a no-verdict selection 422 is the problem of `code`, its sentences rendered from `params`, and return it.

    The response is compared whole with the problem the registry builds for the code and the parameters, in the view of
    the request's reader, so a missing parameter shows as the sentence it could not render.
    """
    assert response.status_code == 422, response.text
    assert response.headers["content-type"] == "application/problem+json"
    problem: dict[str, Any] = response.json()
    view = ProblemView.OPERATOR if "diagnostics" in problem else ProblemView.CALLER
    expected = make_problem(code=code, view=view, params=params).model_copy(update={"status": 422}).to_wire()
    assert {member: value for member, value in problem.items() if member != "diagnostics"} == expected
    return problem


class TestPipeIoRoute:
    def test_one_pipe_by_default(self):
        client = _build_client()
        body = _valid_arm(client, {"files": _files(VALID_MTHDS, SIBLING_MTHDS)})
        assert body["pipe_ref"] == "smoke.echo"
        assert body["default_pipe_ref"] == "smoke.echo", "an omitted pipe_ref always answers pipe_ref == default_pipe_ref"
        _assert_keys(body, {"smoke.echo"})
        assert body["pending_signatures"] == []
        assert body["is_runnable"] is True
        assert "files" not in body, "files is absent, not empty, without include_files"

    def test_a_named_pipe_is_described_beside_the_methods_own_entry_pipe(self):
        client = _build_client()
        body = _valid_arm(client, {"files": _files(VALID_MTHDS, SIBLING_MTHDS), "pipe_ref": "smoke.wrap_echo"})
        assert body["pipe_ref"] == "smoke.wrap_echo"
        assert body["default_pipe_ref"] == "smoke.echo"
        _assert_keys(body, {"smoke.wrap_echo"})

    def test_the_dump_keeps_null_members(self):
        # Never `exclude_none`: the contracts' `item_count: null` must survive, or the maps stop
        # equalling `/v1/validate`'s, which keeps it.
        client = _build_client()
        body = _valid_arm(client, {"files": _files(VALID_MTHDS)})
        output_contract = body["pipe_io_contracts"]["smoke.echo"]["output"]
        assert "item_count" in output_contract
        assert output_contract["item_count"] is None

    @pytest.mark.parametrize(
        ("contents", "request_fields", "expected_pipe_ref", "expected_default", "expected_keys"),
        [
            pytest.param(
                (VALID_MTHDS, SIBLING_MTHDS),
                {},
                "smoke.echo",
                "smoke.echo",
                {"smoke.echo", "smoke.wrap_echo"},
                id="with-entry-pipe",
            ),
            pytest.param(
                (VALID_MTHDS, SIBLING_MTHDS),
                {"pipe_ref": "smoke.wrap_echo"},
                "smoke.wrap_echo",
                "smoke.echo",
                {"smoke.echo", "smoke.wrap_echo"},
                id="with-entry-pipe-and-named-pipe",
            ),
            pytest.param((NO_MAIN_PIPE_MTHDS,), {}, None, None, {"nomain.echo"}, id="without-entry-pipe"),
            pytest.param((VALID_MTHDS, SECOND_MAIN_PIPE_MTHDS), {}, None, None, {"smoke.echo", "other.shout"}, id="with-several-entry-pipes"),
            pytest.param(
                (VALID_MTHDS, SECOND_MAIN_PIPE_MTHDS),
                {"pipe_ref": "other.shout"},
                "other.shout",
                None,
                {"smoke.echo", "other.shout"},
                id="with-several-entry-pipes-and-named-pipe",
            ),
        ],
    )
    def test_all_pipes_describes_every_pipe_and_never_demands_an_entry_pipe(
        self,
        contents: tuple[str, ...],
        request_fields: dict[str, Any],
        expected_pipe_ref: str | None,
        expected_default: str | None,
        expected_keys: set[str],
    ):
        client = _build_client()
        body = _valid_arm(client, {"files": _files(*contents), "all_pipes": True, **request_fields})
        assert "pipe_ref" in body
        assert body["pipe_ref"] == expected_pipe_ref
        assert "default_pipe_ref" in body
        assert body["default_pipe_ref"] == expected_default
        _assert_keys(body, expected_keys)

    @pytest.mark.parametrize(
        ("contents", "pipe_ref"),
        [
            pytest.param((NO_MAIN_PIPE_MTHDS,), "nomain.echo", id="no-main-pipe"),
            pytest.param((VALID_MTHDS, SECOND_MAIN_PIPE_MTHDS), "other.shout", id="several-main-pipes"),
        ],
    )
    def test_default_pipe_ref_is_a_stated_null_without_one_entry_pipe(self, contents: tuple[str, ...], pipe_ref: str):
        # Where several domains declare a `main_pipe`, `/v1/validate`'s run default names the first;
        # this route's chain refuses to choose, so its field is null rather than a guess.
        client = _build_client()
        body = _valid_arm(client, {"files": _files(*contents), "pipe_ref": pipe_ref})
        assert body["pipe_ref"] == pipe_ref
        assert "default_pipe_ref" in body
        assert body["default_pipe_ref"] is None
        _assert_keys(body, {pipe_ref})

    def test_default_pipe_ref_is_the_manifest_main_pipe(self, install_method_package: Callable[..., Path]):
        # The package's bundle declares no main_pipe; only its manifest names the entry pipe.
        install_method_package(files={"documents.mthds": NO_MAIN_PIPE_MTHDS}, manifest_toml=STUB_METHOD_MANIFEST_NOMAIN_ENTRY)
        client = _build_client()
        body = _valid_arm(client, {"method_ref": STUB_METHOD_REF})
        assert body["pipe_ref"] == "nomain.echo"
        assert body["default_pipe_ref"] == "nomain.echo"
        _assert_keys(body, {"nomain.echo"})

    def test_the_manifest_main_pipe_outranks_the_closures_declarations(self, install_method_package: Callable[..., Path]):
        # Two declaring domains would leave the closure without a default; the manifest settles it,
        # and it stays the default when the caller names another pipe.
        install_method_package(
            files={"smoke.mthds": VALID_MTHDS, "other.mthds": SECOND_MAIN_PIPE_MTHDS},
            manifest_toml=STUB_METHOD_MANIFEST_MAIN_PIPE_SHOUT,
        )
        client = _build_client()
        defaulted = _valid_arm(client, {"method_ref": STUB_METHOD_REF})
        assert defaulted["pipe_ref"] == "other.shout"
        assert defaulted["default_pipe_ref"] == "other.shout"
        named = _valid_arm(client, {"method_ref": STUB_METHOD_REF, "pipe_ref": "smoke.echo"})
        assert named["pipe_ref"] == "smoke.echo"
        assert named["default_pipe_ref"] == "other.shout"

    def test_a_manifest_main_pipe_the_closure_lacks_is_no_default_even_beside_a_declaration(self, install_method_package: Callable[..., Path]):
        # The chain stops at the manifest link: `echo` is not in the closure, and `other`'s own
        # declared `main_pipe` is not a fall-through. A whole-method request still answers.
        install_method_package(files={"other.mthds": SECOND_MAIN_PIPE_MTHDS})
        client = _build_client()
        body = _valid_arm(client, {"method_ref": STUB_METHOD_REF, "all_pipes": True})
        assert body["pipe_ref"] is None
        assert body["default_pipe_ref"] is None
        _assert_keys(body, {"other.shout"})
        response = _build_client(as_operator=True).post(PIPE_IO_PATH, json={"method_ref": STUB_METHOD_REF})
        # The author's manifest names a pipe the method lacks: the method's fault, not the caller's selector.
        # The refusal names the declaration that holds the reference, the manifest's `main_pipe`, and no pipe is near `echo`.
        problem = _assert_selection_refusal(
            response, code=CoreCode.METHOD_PIPE_UNRESOLVED, params={"pipe": "main_pipe", "missing": "echo", "candidates": []}
        )
        assert problem["domain"] == "method"
        assert problem["diagnostics"]["error_class"] == "EntryPipeNotFoundError"
        message = problem["diagnostics"]["message"]
        assert "manifest" in message
        assert "not found" in message

    def test_an_ambiguous_manifest_main_pipe_says_ambiguous(self, install_method_package: Callable[..., Path]):
        # The manifest names `echo`, declared by both `smoke` and `twin`: the selection refuses it as
        # ambiguous, naming both candidates, and a whole-method request states no default.
        install_method_package(files={"smoke.mthds": VALID_MTHDS, "twin.mthds": COLLIDING_ECHO_LIST_MTHDS})
        client = _build_client(as_operator=True)
        response = client.post(PIPE_IO_PATH, json={"method_ref": STUB_METHOD_REF})
        # The author's manifest names a pipe that exists twice: an ambiguous reference of the method, never a missing pipe.
        problem = _assert_selection_refusal(
            response, code=CoreCode.METHOD_REF_AMBIGUOUS, params={"ref": "echo", "candidates": ["smoke.echo", "twin.echo"]}
        )
        assert problem["domain"] == "method"
        assert problem["detail"] == "The reference 'echo' matches several declarations: smoke.echo, twin.echo."
        assert "does not exist" not in problem["title"]
        assert problem["diagnostics"]["error_class"] == "EntryPipeAmbiguousError"
        message = problem["diagnostics"]["message"]
        assert "manifest" in message
        assert "several domains" in message
        assert "smoke.echo" in message
        assert "twin.echo" in message
        assert "not found" not in message, f"an ambiguous selector must not read as a missing pipe: {message}"
        body = _valid_arm(client, {"method_ref": STUB_METHOD_REF, "all_pipes": True})
        assert body["pipe_ref"] is None
        assert body["default_pipe_ref"] is None

    @pytest.mark.parametrize("all_pipes", [False, True], ids=["one-pipe", "all-pipes"])
    def test_an_ambiguous_pipe_ref_says_ambiguous(self, all_pipes: bool):
        client = _build_client()
        payload = {"files": _files(VALID_MTHDS, COLLIDING_ECHO_LIST_MTHDS), "pipe_ref": "echo", "all_pipes": all_pipes}
        response = client.post(PIPE_IO_PATH, json=payload)
        # The caller reads which pipes its selector matched, in the code's own sentence.
        problem = _assert_selection_refusal(
            response, code=CoreCode.REQUEST_PIPE_AMBIGUOUS, params={"pipe": "echo", "candidates": ["smoke.echo", "twin.echo"]}
        )
        assert "smoke.echo" in problem["detail"]
        assert "twin.echo" in problem["detail"]

    def test_runnability_facts_match_validate(self):
        client = _build_client()
        body = _valid_arm(client, {"files": _files(SIGNATURE_MTHDS)})
        assert body["pipe_ref"] == "sig_api.caller_seq"
        assert body["pending_signatures"] == ["sig_api.summary_sig"]
        assert body["is_runnable"] is False

        validate_response = client.post("/v1/validate", json={"mthds_contents": [SIGNATURE_MTHDS], "allow_signatures": True})
        assert validate_response.status_code == 200, validate_response.text
        validate_body = validate_response.json()
        assert body["pending_signatures"] == validate_body["pending_signatures"]
        assert body["is_runnable"] == validate_body["is_runnable"]

    @pytest.mark.parametrize("include_files", [False, None], ids=["declined", "omitted"])
    def test_files_are_absent_unless_requested(self, include_files: bool | None):
        client = _build_client()
        payload: dict[str, Any] = {"files": _files(VALID_MTHDS)}
        if include_files is not None:
            payload["include_files"] = include_files
        body = _valid_arm(client, payload)
        assert "files" not in body

    def test_include_files_echoes_the_trees_bundles_as_a_map_of_text_entries(self):
        # The echo is the request's own shape, a map of file entries: each bundle as text under its tree path, whatever
        # entry carried it, and none of the tree's other files.
        client = _build_client()
        files: dict[str, Any] = {
            "main.mthds": VALID_MTHDS,
            "steps/wrap.mthds": {"base64": base64.b64encode(SIBLING_MTHDS.encode("utf-8")).decode("ascii")},
            "notes.txt": "Not a bundle",
        }
        body = _valid_arm(client, {"files": files, "include_files": True})
        assert body["files"] == {"main.mthds": VALID_MTHDS, "steps/wrap.mthds": SIBLING_MTHDS}

    def test_include_files_echoes_a_method_refs_bundles_under_their_tree_paths(self, install_method_package: Callable[..., Path]):
        # Only the package's `.mthds` files travel, each under its path relative to the package root.
        install_method_package(files={"documents.mthds": VALID_MTHDS, "steps/wrap.mthds": SIBLING_MTHDS, "README.md": "# Not a bundle\n"})
        client = _build_client()
        body = _valid_arm(client, {"method_ref": STUB_METHOD_REF, "include_files": True})
        assert body["files"] == {"documents.mthds": VALID_MTHDS, "steps/wrap.mthds": SIBLING_MTHDS}

    def test_a_manifest_sent_in_the_tree_names_the_default_pipe(self):
        # A `METHODS.toml` at the root of a sent tree is the method's manifest, as a fetched package's is.
        client = _build_client()
        files = {"METHODS.toml": STUB_METHOD_MANIFEST_NOMAIN_ENTRY, "documents.mthds": NO_MAIN_PIPE_MTHDS}
        body = _valid_arm(client, {"files": files})
        assert body["pipe_ref"] == "nomain.echo"
        assert body["default_pipe_ref"] == "nomain.echo"

    @pytest.mark.parametrize("all_pipes", [False, True])
    def test_a_manifest_that_does_not_parse_refuses_only_a_request_naming_no_pipe(self, all_pipes: bool):
        """A request naming its pipe never reads the manifest to select it, so a broken one only leaves the default unstated."""
        client = _build_client()
        files = {"METHODS.toml": "not toml [", "main.mthds": VALID_MTHDS}

        named = _valid_arm(client, {"files": files, "pipe_ref": "smoke.echo", "all_pipes": all_pipes})
        assert named["pipe_ref"] == "smoke.echo"
        assert "default_pipe_ref" in named
        assert named["default_pipe_ref"] is None

        unnamed = client.post(PIPE_IO_PATH, json={"files": files, "all_pipes": all_pipes})
        assert unnamed.status_code == 422, unnamed.text
        assert unnamed.headers["content-type"] == "application/problem+json"
        problem = unnamed.json()
        assert problem["code"] == CoreCode.METHOD_PACKAGE_INVALID, unnamed.text
        assert "is_valid" not in problem

    @pytest.mark.parametrize(
        "request_fields",
        [
            pytest.param({}, id="default-selection"),
            pytest.param({"pipe_ref": "broken.not_a_pipe", "include_files": True}, id="unknown-ref-and-files"),
            pytest.param({"all_pipes": True, "include_files": True}, id="all-pipes-and-files"),
        ],
    )
    def test_invalid_closure_is_the_crate_verdict_carrying_nothing_else(self, request_fields: dict[str, Any]):
        # The closure is resolved before any pipe is selected, so even a pipe_ref naming nothing
        # answers the invalid verdict rather than a 422.
        client = _build_client()
        response = client.post(PIPE_IO_PATH, json={"files": {"broken.mthds": INVALID_MAIN_PIPE_MTHDS}, **request_fields})
        assert response.status_code == 200, response.text
        body = response.json()
        assert body["is_valid"] is False
        assert body["errors"]
        assert body["errors"][0]["location"]["file"] == "broken.mthds"
        assert body["message"]
        for field_name in VALID_ARM_ONLY_FIELDS:
            assert field_name not in body, f"the invalid arm never carries `{field_name}`"

    @pytest.mark.parametrize(
        ("contents", "request_fields", "code", "params", "operator_reads"),
        [
            pytest.param(
                (VALID_MTHDS,),
                {"pipe_ref": "smoke.not_a_pipe"},
                CoreCode.REQUEST_PIPE_NOT_FOUND,
                {"pipe": "smoke.not_a_pipe", "suggestions": []},
                ("EntryPipeNotFoundError", "not found"),
                id="unknown-ref",
            ),
            pytest.param(
                (VALID_MTHDS,),
                {"pipe_ref": "smoke.not_a_pipe", "all_pipes": True},
                CoreCode.REQUEST_PIPE_NOT_FOUND,
                {"pipe": "smoke.not_a_pipe", "suggestions": []},
                ("EntryPipeNotFoundError", "not found"),
                id="unknown-ref-under-all-pipes",
            ),
            pytest.param(
                (NO_MAIN_PIPE_MTHDS,),
                {},
                # The caller may select any pipe the method declares.
                CoreCode.REQUEST_PIPE_UNSPECIFIED,
                {"candidates": ["nomain.echo"]},
                ("EntryPipeNotFoundError", "declares no `main_pipe`"),
                id="no-entry-pipe",
            ),
            pytest.param(
                (VALID_MTHDS, SECOND_MAIN_PIPE_MTHDS),
                {},
                # No selector to name: the caller is told to pick one of the declared entry pipes.
                CoreCode.REQUEST_PIPE_UNSPECIFIED,
                {"candidates": ["other.shout", "smoke.echo"]},
                ("EntryPipeAmbiguousError", "several `main_pipe`s"),
                id="several-entry-pipes",
            ),
        ],
    )
    def test_selection_refusals_carry_their_code_and_params(
        self,
        contents: tuple[str, ...],
        request_fields: dict[str, Any],
        code: CoreCode,
        params: dict[str, Any],
        operator_reads: tuple[str, str],
    ):
        # A selection refusal is an input 422 like a malformed request, but under the registry code that names the
        # miss, so a client branches on it: its `type` names the selection, its `params` the selector and the
        # candidates, and its step the fix for this very miss. The operator reads the entry-lookup class that refused
        # and its message, `operator_reads`.
        client = _build_client(as_operator=True)
        response = client.post(PIPE_IO_PATH, json={"files": _files(*contents), **request_fields})
        problem = _assert_selection_refusal(response, code=code, params=params)
        assert problem["type"] == f"https://mthds.ai/errors/{code}"
        assert problem["type"] != client.post(PIPE_IO_PATH, json={}).json()["type"], "a selection refusal must not share the request-shape type"
        assert problem["next_step"]["kind"] == "change_input"
        entry_lookup_class, message_fragment = operator_reads
        assert problem["diagnostics"]["error_class"] == entry_lookup_class
        assert message_fragment in problem["diagnostics"]["message"]

    @pytest.mark.parametrize(
        "payload",
        [
            pytest.param({}, id="neither"),
            pytest.param({"pipe_ref": "smoke.echo"}, id="neither-with-pipe-ref"),
            pytest.param({"files": {"main.mthds": VALID_MTHDS}, "method_ref": STUB_METHOD_REF}, id="both"),
        ],
    )
    def test_closure_selector_xor_is_a_request_shape_422(self, payload: dict[str, Any]):
        client = _build_client()
        _assert_input_422(client.post(PIPE_IO_PATH, json=payload), code=REQUEST_SHAPE_CODE)

    def test_an_out_of_bounds_pipe_ref_is_a_request_shape_422(self):
        client = _build_client()
        payload = {"files": {"main.mthds": VALID_MTHDS}, "pipe_ref": "x" * (MAX_PIPE_CODE_LEN + 1)}
        _assert_input_422(client.post(PIPE_IO_PATH, json=payload), code=REQUEST_SHAPE_CODE)

    @pytest.mark.parametrize(
        ("files", "code"),
        [
            pytest.param({}, "method.package_invalid", id="empty-map"),
            pytest.param([], "request.invalid", id="empty-list"),
            pytest.param([{"content": VALID_MTHDS, "source": "main.mthds"}], "request.invalid", id="the-retired-list-shape"),
        ],
    )
    def test_a_files_member_that_is_no_method_tree_is_refused_as_validate_refuses_it(self, files: Any, code: str):
        # Refused by the standard's reader as on `/v1/validate`: a map that is no tree is the method's, a list is no map.
        client = _build_client()
        problem = assert_problem(client.post(PIPE_IO_PATH, json={"files": files}), status=422, code=code)
        validate_problem = assert_problem(client.post("/v1/validate", json={"files": files}), status=422, code=code)
        assert problem.get("params") == validate_problem.get("params")

    def test_a_bare_pipe_code_resolves_but_is_answered_qualified(self):
        # The engine's entry lookup still accepts a bare request code, falling back across domains, until
        # `resolve_requested_pipe` refuses one as the pipe-selector ruling asks; that change flips this
        # test. Meanwhile the valid arm promises a qualified ref, so the answer is read off the resolved
        # pipe, never echoed from the request's own bare spelling.
        client = _build_client()
        body = _valid_arm(client, {"files": _files(VALID_MTHDS, SIBLING_MTHDS), "pipe_ref": "wrap_echo"})
        assert body["pipe_ref"] == "smoke.wrap_echo"
        _assert_keys(body, {"smoke.wrap_echo"})

    def test_a_manifest_without_main_pipe_falls_through_to_the_closures_declaration(self, install_method_package: Callable[..., Path]):
        # A manifest may declare no `main_pipe`; the chain then falls through to the closure's own
        # declaration, the default inline `files[]` get, rather than refusing.
        install_method_package(files={"documents.mthds": VALID_MTHDS}, manifest_toml=STUB_METHOD_MANIFEST_NO_MAIN_PIPE)
        client = _build_client()
        body = _valid_arm(client, {"method_ref": STUB_METHOD_REF})
        assert body["pipe_ref"] == "smoke.echo"
        assert body["default_pipe_ref"] == "smoke.echo"

    def test_a_method_with_no_entry_pipe_anywhere_is_still_a_422(self, install_method_package: Callable[..., Path]):
        # The whole chain empty: no `pipe_ref`, a manifest with no `main_pipe`, a closure declaring
        # none. The manifest only ever adds a default, so the closure arm's refusal stands.
        install_method_package(files={"documents.mthds": NO_MAIN_PIPE_MTHDS}, manifest_toml=STUB_METHOD_MANIFEST_NO_MAIN_PIPE)
        client = _build_client()
        response = client.post(PIPE_IO_PATH, json={"method_ref": STUB_METHOD_REF})
        _assert_selection_refusal(response, code=CoreCode.REQUEST_PIPE_UNSPECIFIED, params={"candidates": ["nomain.echo"]})

    @pytest.mark.parametrize(
        ("contents", "request_fields"),
        [
            pytest.param((VALID_MTHDS,), {}, id="entry-pipe"),
            pytest.param((VALID_MTHDS, SIBLING_MTHDS), {"pipe_ref": "smoke.wrap_echo"}, id="named-pipe"),
            pytest.param((VALID_MTHDS, SIBLING_MTHDS), {"all_pipes": True}, id="all-pipes"),
            pytest.param((VALID_MTHDS, SECOND_MAIN_PIPE_MTHDS), {"all_pipes": True}, id="several-main-pipes"),
            pytest.param((NO_MAIN_PIPE_MTHDS,), {"pipe_ref": "nomain.echo"}, id="no-main-pipe"),
            pytest.param((SHAPES_MTHDS,), {}, id="multiplicity-and-structure"),
            pytest.param((SIGNATURE_MTHDS,), {"all_pipes": True}, id="pending-signature"),
            pytest.param(tuple(SIGNATURE_ONLY_BATCH), {"all_pipes": True}, id="signature-only-batch"),
            pytest.param(tuple(HEADER_AND_DEFINITION_BATCH), {"all_pipes": True}, id="header-and-definition"),
        ],
    )
    def test_artifacts_equal_validate_views(self, contents: tuple[str, ...], request_fields: dict[str, Any]):
        # The pinning test: each map equals `/v1/validate`'s same-named view restricted to the same
        # keys, for the same tree. Validate is asked first, so a tree it would refuse fails here rather
        # than passing vacuously; `allow_signatures` lets it accept the signature trees this route accepts.
        files = _files(*contents)
        client = _build_client()
        validate_response = client.post(
            "/v1/validate",
            json={"files": files, "views": ["input_form", "output_form"], "allow_signatures": True},
        )
        assert validate_response.status_code == 200, validate_response.text
        validate_body = validate_response.json()
        assert validate_body["is_valid"] is True, validate_response.text

        body = _valid_arm(client, {"files": files, **request_fields})
        self._assert_maps_equal_validate(body, validate_body)

    def test_artifacts_equal_validate_views_by_method_ref(self, install_method_package: Callable[..., Path]):
        # The stub package holds `.mthds` files alone, so validate by `method_ref` loads exactly the
        # closure this route reads (validate would also load a package's other files).
        install_method_package(files={"documents.mthds": VALID_MTHDS, "steps/wrap.mthds": SIBLING_MTHDS})
        client = _build_client()
        validate_response = client.post("/v1/validate", json={"method_ref": STUB_METHOD_REF, "views": ["input_form", "output_form"]})
        assert validate_response.status_code == 200, validate_response.text
        validate_body = validate_response.json()
        assert validate_body["is_valid"] is True, validate_response.text

        body = _valid_arm(client, {"method_ref": STUB_METHOD_REF, "all_pipes": True})
        _assert_keys(body, {"smoke.echo", "smoke.wrap_echo"})
        self._assert_maps_equal_validate(body, validate_body)

    def _assert_maps_equal_validate(self, body: dict[str, Any], validate_body: dict[str, Any]) -> None:
        keys = set(body["pipe_io_contracts"])
        assert keys, "the valid arm describes at least one pipe"
        _assert_keys(body, keys)
        for field_name in ARTIFACT_FIELDS:
            validate_map = validate_body[field_name]
            assert keys <= set(validate_map), f"`{field_name}` names pipes /v1/validate does not: {sorted(keys - set(validate_map))}"
            assert body[field_name] == {ref: validate_map[ref] for ref in keys}, f"`{field_name}` diverges from /v1/validate's view"

    @pytest.mark.parametrize(
        ("payload", "expected_status"),
        [
            pytest.param({"files": {"main.mthds": VALID_MTHDS}}, 200, id="valid-arm"),
            pytest.param({"files": {"main.mthds": NO_MAIN_PIPE_MTHDS}, "all_pipes": True, "include_files": True}, 200, id="all-pipes"),
            pytest.param({"files": {"main.mthds": VALID_MTHDS}, "pipe_ref": "smoke.not_a_pipe"}, 422, id="selection-422"),
            pytest.param({"files": {"main.mthds": NO_MAIN_PIPE_MTHDS}}, 422, id="no-entry-pipe-422"),
            # A manifest that does not parse is the method entry rule's refusal, as on a run naming no pipe.
            pytest.param({"files": {"METHODS.toml": "not toml [", "main.mthds": VALID_MTHDS}}, 422, id="invalid-manifest-422"),
            pytest.param(
                {"files": {"METHODS.toml": "not toml [", "main.mthds": VALID_MTHDS}, "pipe_ref": "smoke.echo"}, 200, id="invalid-manifest-named-pipe"
            ),
        ],
    )
    def test_every_exit_tears_its_library_down(self, mocker: MockerFixture, payload: dict[str, Any], expected_status: int):
        # The engine core leaves the library loaded + current on success; the route owns teardown on
        # every exit after it, a selection refusal included. Conservation: opens == teardowns.
        library_manager = get_library_manager()
        open_spy = mocker.spy(library_manager, "open_library")
        teardown_spy = mocker.spy(library_manager, "teardown")

        client = _build_client()
        response = client.post(PIPE_IO_PATH, json=payload)

        assert response.status_code == expected_status, response.text
        assert open_spy.call_count == 1
        created_library_id, _ = open_spy.spy_return
        teardown_spy.assert_called_once_with(library_id=created_library_id)

    def test_an_underivable_artifact_is_a_no_verdict_problem_and_still_tears_down(self, mocker: MockerFixture):
        # `PipeIOContractError` is left to the global handler, exactly as on `/v1/validate`: no verdict,
        # a problem document carrying `method.concept_invalid`, since a concept's structure cannot be
        # described. The library is still torn down.
        mocker.patch(
            "pipelex_api.routes.pipelex.pipe_io.build_pipe_io_artifacts",
            side_effect=PipeIOContractError(message="Failed to render the JSON Schema for the output of pipe 'smoke.echo'").with_params(
                concept="native.Text", finding=SCHEMA_UNRENDERABLE_FINDING
            ),
        )
        library_manager = get_library_manager()
        open_spy = mocker.spy(library_manager, "open_library")
        teardown_spy = mocker.spy(library_manager, "teardown")

        client = _build_client()
        response = client.post(PIPE_IO_PATH, json={"files": {"main.mthds": VALID_MTHDS}})

        assert response.status_code == 422, response.text
        assert response.headers["content-type"] == "application/problem+json"
        assert "is_valid" not in response.json()
        assert response.json()["code"] == "method.concept_invalid"
        assert open_spy.call_count == 1
        assert teardown_spy.call_count == 1