@pipelex/sdk 0.26.0 → 0.27.0

package/dist/models.d.ts

@@ -64,7 +64,7 @@ export interface PipelexRunResultStart extends RunResultStart {
 }
 /**
  * The hosted tooling routes' own selector — the layer-3 extension the platform
- * adds on `POST /v1/validate`, `/v1/resolve`, and `/v1/codegen`: a stored
+ * adds on `POST /v1/validate`, `/v1/resolve`, `/v1/codegen`, and `/v1/pipe-io`: a stored
  * method's catalog id (`mt_…`), resolved server-side against the org's catalog
  * and injected as inline source before the runner sees the request. A **pass-
  * through to the hosted API**: nothing is expanded client-side, and it is
@@ -90,8 +90,9 @@ export interface PipelexHostedToolingExtensions {
  * exactly one of inline contents / `method_ref` / `method_id` per request.
  *
  * Lives here, beside the other wire shapes, rather than on the client: it is
- * the request's shape, and `prepareInputs` composes a `validate` call of its own
- * without importing the client back (which would close a module cycle).
+ * the request's shape, and a module that composes a `validate` call of its own
+ * can name it without importing the client back (which would close a module
+ * cycle).
  */
 export type ValidateMethodSelector = {
     method_ref: string;
@@ -207,7 +208,9 @@ export interface PipelexValidationReport extends ValidationReport {
      * `null` is the server's verdict that there is none, and a consumer stops there
      * rather than deriving one of its own; an ABSENT field means the server predates
      * the field, and only then does a blueprint-derived default stand. That is the rule
-     * `prepareInputs` applies and the one `pipelex-mcp` states in its `SPEC.md`.
+     * `pipelex-mcp` states in its `SPEC.md`. It is NOT `/v1/pipe-io`'s field of the same
+     * name ({@link PipeIOValidReport.default_pipe_ref}), which refuses to choose among
+     * several declaring domains where this one names the first.
      */
     default_pipe_ref?: string | null;
     /** Best-effort execution graph of the main pipe; `null` with no `main_pipe` or on degrade. */
@@ -479,7 +482,7 @@ export interface MthdsFileItem {
 }
 /**
  * The closure selector every crate-family route shares — `/v1/resolve`, `/v1/codegen`,
- * and `/v1/build/*` (mirror of the server's `MthdsFilesRequest`).
+ * `/v1/pipe-io`, and `/v1/build/*` (mirror of the server's `MthdsFilesRequest`).
  *
  * Supply the closure EITHER as inline `files` OR as a `method_ref` — never both, and
  * never neither (both arms are a request-shape `422`). An **address-form** `method_ref`
@@ -510,7 +513,7 @@ export interface BuildRequestBase extends CrateRequestBase {
     pipe_ref?: string;
     /**
      * The `/v1/build/*` projections take NO `method_id` — the hosted platform's
-     * tooling selector covers `validate`/`resolve`/`codegen` only, and the build
+     * tooling selector covers `validate`/`resolve`/`codegen`/`pipe-io` only, and the build
      * routes are deliberately excluded (they are frozen, being replaced by the
      * codegen surface). Pinned to `never` so a stored-method caller reaches for
      * `getMethodClosure` instead of a field no server resolves.
@@ -544,15 +547,16 @@ export interface PipeSpecRequest {
 }
 /**
  * The `is_valid: false` arm shared by every crate-family route — `/v1/build/*`,
- * `/v1/resolve`, and `/v1/codegen` (mirror of the server's one `CrateInvalidReport`).
+ * `/v1/resolve`, `/v1/codegen`, and `/v1/pipe-io` (mirror of the server's one
+ * `CrateInvalidReport`).
  *
  * They all follow `/validate`'s discipline: an unresolvable closure is the
  * *successful product* of the call (the request was well-formed, the library was
  * not), so it rides a **200** discriminated on `is_valid` — never a 4xx. Only a
  * no-verdict condition throws `ApiResponseError`: a request the route cannot act on
- * (an unknown `pipe_ref` on the build routes, an unknown `kind`/`target` on codegen),
- * the reserved `method_ref`, auth, a server fault. Branch on `is_valid`, never on the
- * transport.
+ * (an unknown `pipe_ref` on the build routes and `pipe-io`, an unknown `kind`/`target`
+ * on codegen), the reserved `method_ref`, auth, a server fault. Branch on `is_valid`,
+ * never on the transport.
  */
 export interface CrateInvalidReport {
     is_valid: false;
@@ -735,4 +739,90 @@ export interface CodegenValidReport {
 }
 /** The `POST /v1/codegen` 200 response — pattern-match `is_valid` before reading the arm. */
 export type CodegenResponse = CodegenValidReport | CrateInvalidReport;
+/**
+ * `POST /v1/pipe-io` request — the crate envelope plus the hosted `method_id` selector
+ * (exactly one of `files` / `method_ref` / `method_id`; see
+ * {@link PipelexHostedToolingExtensions}), a pipe selector, and two opt-ins.
+ *
+ * There is no `views` field: the valid arm always carries all three artifacts.
+ */
+export interface PipeIORequest extends CrateRequestBase, PipelexHostedToolingExtensions {
+    /**
+     * The pipe to describe, as a QUALIFIED `domain.pipe_code` ref. Omit it and the
+     * server's selection chain decides: a fetched package's manifest `main_pipe`, else
+     * the closure's single `main_pipe` declaration. A selection the server refuses is a
+     * `422` typed by what went wrong, with `error_domain: "input"` and the candidates, where
+     * there are some, in its `detail`: `EntryPipeNotFoundError` for a ref that names no pipe
+     * or (without `all_pipes`) a method with no entry pipe, `EntryPipeAmbiguousError` for a
+     * code that matches pipes in several domains or (without `all_pipes`) several `main_pipe`
+     * declarations. A malformed request stays a `ValidationError` `422`.
+     *
+     * The server does not refuse a bare code yet: a bare ref that matches one pipe is
+     * resolved across domains, and the valid arm reports the qualified ref.
+     */
+    pipe_ref?: string;
+    /**
+     * Describe every pipe the closure loads instead of the selected one. The artifact maps
+     * are then keyed by every pipe, and the route never refuses for want of an entry pipe:
+     * the valid arm's `pipe_ref` is the requested ref, else the method's own entry pipe,
+     * else `null`. Defaults to `false` server-side.
+     */
+    all_pipes?: boolean;
+    /**
+     * Echo the resolved closure's `.mthds` files on the valid arm as `files`, in the
+     * request's own `files[]` shape. Defaults to `false` server-side, and the field is then
+     * absent from the answer.
+     */
+    include_files?: boolean;
+}
+/**
+ * The `/v1/pipe-io` valid arm — a method's three I/O artifacts, with the selection and
+ * the runnability facts beside them.
+ *
+ * The three artifacts are the MTHDS standard's own types, imported from `mthds/protocol`
+ * and never restated here. The maps share one key set: the resolved `pipe_ref` alone by
+ * default, every pipe the closure loads under `all_pipes`. For a closure `/v1/validate`
+ * also accepts, each map equals validate's same-named field restricted to the same keys.
+ *
+ * `is_valid: true` means what it means on `/v1/resolve`: the closure parsed, loaded and
+ * passed static validation. No dry run ran; that verdict stays `validate`'s.
+ */
+export interface PipeIOValidReport {
+    is_valid: true;
+    /**
+     * The qualified ref the selection resolved, read off the resolved pipe and never echoed
+     * from the request. `null` only under `all_pipes` when no pipe was requested and the
+     * method declares no single entry pipe.
+     */
+    pipe_ref: string | null;
+    /** The standard's pipe I/O contracts, keyed by qualified `pipe_ref`. */
+    pipe_io_contracts: PipeIOContracts;
+    /** The standard's input-form descriptors, keyed by qualified `pipe_ref`. */
+    input_form: InputForm;
+    /** The standard's output-form descriptors, keyed by qualified `pipe_ref`. */
+    output_form: OutputForm;
+    /**
+     * The method's own entry pipe: the selection chain without the request's `pipe_ref` —
+     * the fetched manifest's `main_pipe`, else the closure's single declaration. A request
+     * that omits `pipe_ref` always answers `pipe_ref === default_pipe_ref`. A stated `null`
+     * when the chain finds none or several.
+     *
+     * NOT `PipelexValidationReport.default_pipe_ref`, which is the run default and names
+     * the first of several declaring domains where this chain refuses to choose.
+     */
+    default_pipe_ref: string | null;
+    /** Qualified refs of every pipe of the closure still declared as a signature, as on `validate`. */
+    pending_signatures: string[];
+    /** `pending_signatures` is empty, as on `validate`. No dry run backs it. */
+    is_runnable: boolean;
+    /**
+     * The resolved closure's `.mthds` files, in the request's `files[]` shape. Present only
+     * when the request passed `include_files: true`: the request's files for inline
+     * `files`, the fetched package's `.mthds` files under their package-relative paths for
+     * a `method_ref`, the stored files under their stored names for a hosted `method_id`.
+     */
+    files?: MthdsFileItem[];
+}
+/** The `POST /v1/pipe-io` 200 response — pattern-match `is_valid` before reading the arm. */
+export type PipeIOResponse = PipeIOValidReport | CrateInvalidReport;
 export {};

package/dist/prepare-inputs.d.ts

@@ -1,15 +1,17 @@
 /**
- * `prepareInputs` — signature-driven input preparation. Resolves the target
- * pipe's declared inputs from the **input-form descriptor** on the validate
- * report, interprets the caller's inputs top-down against it, uploads the
- * file-bearing values, and returns rewritten inputs (canonical content carrying
+ * `prepareInputs` — signature-driven input preparation. Reads the target pipe's
+ * declared inputs from the **input-form descriptor** `POST /v1/pipe-io` returns,
+ * interprets the caller's inputs top-down against it, uploads the file-bearing
+ * values, and returns rewritten inputs (canonical content carrying
  * `pipelex-storage://` in `url`) plus one upload record per prepared asset.
  *
  * The method is named the same three ways every other method-taking operation
  * takes it — inline `files`, a `method_ref` address, or a stored `method_id` —
- * exactly one per call. All three are pass-throughs to `POST /v1/validate`,
- * which resolves an address on the runner and an id on the platform, so nothing
- * is expanded client-side.
+ * exactly one per call. All three are pass-throughs to `POST /v1/pipe-io`, which
+ * resolves an address on the runner and an id on the platform, so nothing is
+ * expanded client-side. The route also SELECTS the pipe: the caller's qualified
+ * `pipe_ref`, else the method's own entry pipe, and the ref it answers with is
+ * the one prepared. It runs no dry run, so preparing inputs costs one static load.
  *
  * Per input, the caller may submit EITHER the **compact** value (a bare source /
  * canonical `{url}` content) OR the explicit `{ concept, content }` envelope —
@@ -19,26 +21,27 @@
  * `input_normalizer.py`).
  *
  * **The descriptor is the classifier, never the value's shape.** `input_form`
- * (the MTHDS standard's artifact, opted into with `views: ["input_form"]`)
- * states the kind at every depth — `document` / `image` mark a file position,
- * `object` recurses through `fields`, `list` through `item`, everything else
- * passes through. That is what makes an OPTIONAL nested file field prepare like
- * a required one, and a `text` field merely *named* `url` stay untouched: both
- * were misread while the signature came from the rendered inputs template, whose
- * file signal was a `url`-bearing dict. See `docs/input-preparation.md` and the
- * shared behavior matrix (`wip/upload/behavior-matrix.md`).
+ * (the MTHDS standard's artifact) states the kind at every depth — `document` /
+ * `image` mark a file position, `object` recurses through `fields`, `list`
+ * through `item`, everything else passes through. That is what makes an
+ * OPTIONAL nested file field prepare like a required one, and a `text` field
+ * merely *named* `url` stay untouched: both were misread while the signature
+ * came from the rendered inputs template, whose file signal was a `url`-bearing
+ * dict. See `docs/input-preparation.md`, which `pipelex-sdk-python` mirrors case
+ * for case.
  */
-import type { MthdsFileItem, PipelexValidationResult, ValidateMethodSelector } from "./models.js";
+import type { MthdsFileItem, PipeIORequest, PipeIOResponse } from "./models.js";
 import type { UploadCapableClient, UploadRecord } from "./upload.js";
 /** The shared half of the request: the target pipe and the caller's inputs. */
 export interface PrepareInputsBase {
     /**
      * The pipe to prepare inputs for, as a QUALIFIED `domain.pipe_code` ref. Omit
-     * it to default — see "Pipe selection" in `docs/input-preparation.md`. A bare
-     * `pipe_code` is refused: the descriptor is keyed by qualified refs, and search
-     * is a run-route affordance this helper deliberately does not grow. So is an
+     * it and the server picks the method's own entry pipe — see "Pipe selection" in
+     * `docs/input-preparation.md`. A bare `pipe_code` is refused before any request:
+     * a request names a pipe by its qualified ref, and search is a run-route
+     * affordance this helper deliberately does not grow. So is an
      * `alias->domain.pipe_code` ref: the alias names a dependency package's pipe,
-     * which the descriptor does not describe (it covers the method's own pipes).
+     * and preparation covers the method's own pipes.
      */
     pipe_ref?: string;
     /** The caller's inputs (variable name → value), compact or explicit-envelope per input. */
@@ -47,7 +50,7 @@ export interface PrepareInputsBase {
 /**
  * How the method is named — exactly one of the three selectors, each pinning the
  * other two to `never` so a second one is a compile error (the same XOR
- * `ValidateMethodSelector` states for the tooling routes). All three reach the
+ * `ValidateMethodSelector` states for `validate`). All three reach the
  * server as-is: `files` inline, `method_ref` resolved by the runner, `method_id`
  * resolved by the platform.
  */
@@ -74,15 +77,12 @@ export interface PreparedInputs {
     uploads: UploadRecord[];
 }
 /**
- * The client surface `prepareInputs` needs: raw `upload`, and `validate` as the
- * signature source. Typed as the client's own `validate` signature so
+ * The client surface `prepareInputs` needs: raw `upload`, and `pipeIo` as the
+ * signature source. Typed as the client's own `pipeIo` signature so
  * `PipelexApiClient` satisfies it structurally.
  */
 export interface PrepareCapableClient extends UploadCapableClient {
-    validate(source: string[] | ValidateMethodSelector, allowSignatures?: boolean, mthdsSources?: string[], render?: string[], views?: string[], options?: {
-        timeoutMs?: number;
-        signal?: AbortSignal;
-    }): Promise<PipelexValidationResult>;
+    pipeIo(request: PipeIORequest): Promise<PipeIOResponse>;
 }
 /**
  * Prepare a pipe's inputs: upload local/byte/data-URL assets at the signature's
@@ -90,12 +90,13 @@ export interface PrepareCapableClient extends UploadCapableClient {
  * records. HTTP(S) URLs and existing `pipelex-storage://` URIs pass through
  * unchanged. All failures are raised before any run is created.
  *
- * The signature comes from one `POST /v1/validate` with `views: ["input_form"]`,
- * whatever the selector — inline `files`, a `method_ref` the runner resolves, or
- * a `method_id` the platform resolves. A closure that does not load, an unknown
- * `pipe_ref`, no default pipe, or a report with no descriptor throw
- * {@link InputPreparationError}; a no-verdict condition from the route (a
- * malformed selector, an unknown or foreign-org id, no package at the address,
- * auth, a server fault) surfaces as `ApiResponseError`, unchanged.
+ * The pipe and its signature come from one `POST /v1/pipe-io`, whatever the
+ * selector — inline `files`, a `method_ref` the runner resolves, or a
+ * `method_id` the platform resolves. A bare or alias-qualified `pipe_ref`, a
+ * closure that does not load, and a selection the route refuses (an unknown
+ * `pipe_ref`, no entry pipe, several) throw {@link InputPreparationError}; any
+ * other failure from the route (a malformed selector, an unknown or foreign-org
+ * id, no package at the address, auth, a server fault, a deployment that does not
+ * serve the route) surfaces as `ApiResponseError`, unchanged.
  */
 export declare function prepareInputs(client: PrepareCapableClient, request: PrepareInputsRequest): Promise<PreparedInputs>;

package/dist/prepare-inputs.js

@@ -1,15 +1,17 @@
 /**
- * `prepareInputs` — signature-driven input preparation. Resolves the target
- * pipe's declared inputs from the **input-form descriptor** on the validate
- * report, interprets the caller's inputs top-down against it, uploads the
- * file-bearing values, and returns rewritten inputs (canonical content carrying
+ * `prepareInputs` — signature-driven input preparation. Reads the target pipe's
+ * declared inputs from the **input-form descriptor** `POST /v1/pipe-io` returns,
+ * interprets the caller's inputs top-down against it, uploads the file-bearing
+ * values, and returns rewritten inputs (canonical content carrying
  * `pipelex-storage://` in `url`) plus one upload record per prepared asset.
  *
  * The method is named the same three ways every other method-taking operation
  * takes it — inline `files`, a `method_ref` address, or a stored `method_id` —
- * exactly one per call. All three are pass-throughs to `POST /v1/validate`,
- * which resolves an address on the runner and an id on the platform, so nothing
- * is expanded client-side.
+ * exactly one per call. All three are pass-throughs to `POST /v1/pipe-io`, which
+ * resolves an address on the runner and an id on the platform, so nothing is
+ * expanded client-side. The route also SELECTS the pipe: the caller's qualified
+ * `pipe_ref`, else the method's own entry pipe, and the ref it answers with is
+ * the one prepared. It runs no dry run, so preparing inputs costs one static load.
  *
  * Per input, the caller may submit EITHER the **compact** value (a bare source /
  * canonical `{url}` content) OR the explicit `{ concept, content }` envelope —
@@ -19,19 +21,33 @@
  * `input_normalizer.py`).
  *
  * **The descriptor is the classifier, never the value's shape.** `input_form`
- * (the MTHDS standard's artifact, opted into with `views: ["input_form"]`)
- * states the kind at every depth — `document` / `image` mark a file position,
- * `object` recurses through `fields`, `list` through `item`, everything else
- * passes through. That is what makes an OPTIONAL nested file field prepare like
- * a required one, and a `text` field merely *named* `url` stay untouched: both
- * were misread while the signature came from the rendered inputs template, whose
- * file signal was a `url`-bearing dict. See `docs/input-preparation.md` and the
- * shared behavior matrix (`wip/upload/behavior-matrix.md`).
+ * (the MTHDS standard's artifact) states the kind at every depth — `document` /
+ * `image` mark a file position, `object` recurses through `fields`, `list`
+ * through `item`, everything else passes through. That is what makes an
+ * OPTIONAL nested file field prepare like a required one, and a `text` field
+ * merely *named* `url` stay untouched: both were misread while the signature
+ * came from the rendered inputs template, whose file signal was a `url`-bearing
+ * dict. See `docs/input-preparation.md`, which `pipelex-sdk-python` mirrors case
+ * for case.
  */
-import { InputPreparationError } from "./errors.js";
+import { ApiResponseError, InputPreparationError } from "./errors.js";
 import { uploadFile } from "./upload.js";
 const PIPELEX_STORAGE_SCHEME = "pipelex-storage://";
 const HTTP_URL_RE = /^https?:\/\//i;
+/**
+ * The `error_type`s of the route's pipe-selection refusals — the only `422`s
+ * `prepareInputs` turns into an `InputPreparationError`. They are the runtime's
+ * entry-lookup classes, the vocabulary the run routes speak too: a ref that names
+ * no pipe, or no entry pipe at all, is `EntryPipeNotFoundError`; a code that
+ * matches pipes in several domains, or several `main_pipe` declarations, is
+ * `EntryPipeAmbiguousError`. Every other `422` (a malformed body, an over-limit
+ * file, a fetched package with no `.mthds` file, a stored method with no source)
+ * shares the generic `ValidationError` type and stays an `ApiResponseError`.
+ */
+const PIPE_SELECTION_ERROR_TYPES = new Set([
+    "EntryPipeNotFoundError",
+    "EntryPipeAmbiguousError",
+]);
 /** Strict plain-object test — excludes arrays, `Uint8Array`, `Blob`, and other exotics. */
 function isPlainObject(value) {
     return Object.prototype.toString.call(value) === "[object Object]";
@@ -198,7 +214,7 @@ async function resolveNode(ctx, node, callerValue) {
  * Normalize and check the three selectors. Empty is absent (`files: []`,
  * `method_ref: ""`, `method_id: "  "`), mirroring the run options' rule and the
  * Python `CrateRequestBase` normalisers, and exactly one must remain — the check
- * lives here because this helper is the one that composes the `validate` call.
+ * lives here because this helper is the one that composes the `pipeIo` call.
  * The illegal shapes are compile errors for typed callers; this backs them up for
  * untyped (JS) ones with a typed `InputPreparationError`.
  */
@@ -222,7 +238,8 @@ function resolveSelector(request) {
             "catalog id).");
     }
     if (given.length > 1) {
-        throw new InputPreparationError(`Cannot prepare inputs: ${given.join(" and ")} were both given. Supply exactly one method ` +
+        throw new InputPreparationError(`Cannot prepare inputs: ${given.join(" and ")} were ${given.length === 2 ? "both" : "all"} ` +
+            "given. Supply exactly one method " +
             "selector — `files`, `method_ref` or `method_id`.");
     }
     if (files !== undefined)
@@ -232,113 +249,84 @@ function resolveSelector(request) {
     return { method_id: methodId };
 }
 /**
- * Ask `validate` for the signature, whatever the selector, and hand back the
- * valid report.
+ * Normalize the caller's `pipe_ref` and refuse, before any request, the two
+ * spellings preparation cannot honour. Empty is absent, so the route's selection
+ * chain decides.
  *
- * `allowSignatures: true` on purpose: preparation needs a pipe's DECLARED inputs,
- * and a bundle mid-authoring with an unresolved signature elsewhere must not be
- * refused inputs for a pipe whose inputs are declared. Whether the bundle runs is
- * the run's verdict, not preparation's. The `is_valid: false` arm still means the
- * closure does not load, which is a preparation failure.
+ * - A **bare** `pipe_code` is refused because a request names a pipe by its
+ *   qualified ref. The route will refuse it too once the runner's shared
+ *   selection enforces that rule; until then it would resolve a bare code across
+ *   domains, and preparation does not lean on that fallback.
+ * - An **`alias->domain.pipe_code`** ref is refused because the alias names a
+ *   dependency package's pipe, and preparation covers the method's own pipes: the
+ *   crate routes do not load an address-based dependency at all. The run route
+ *   takes such a ref; preparation refuses it, and that asymmetry is deliberate.
  */
-async function fetchSignature(client, selector) {
-    let result;
-    if ("files" in selector) {
-        const contents = selector.files.map((file) => file.content);
-        // `validateFiles`' rule: label every content once any file names a source, so
-        // the server never sees a length-mismatched `mthds_sources` array.
-        const hasAnySource = selector.files.some((file) => file.source !== undefined);
-        const sources = hasAnySource
-            ? selector.files.map((file, index) => file.source ?? `inline://file-${index + 1}.mthds`)
-            : undefined;
-        result = await client.validate(contents, true, sources, undefined, ["input_form"]);
+function normalizePipeRef(raw) {
+    const pipeRef = nonEmptyString(raw);
+    if (pipeRef === undefined)
+        return undefined;
+    if (pipeRef.includes("->")) {
+        throw new InputPreparationError(`Cannot prepare inputs: \`pipe_ref\` "${pipeRef}" names a dependency package's pipe. ` +
+            "Preparation covers the method's own pipes: name one as `domain.pipe_code`.");
     }
-    else {
-        result = await client.validate(selector, true, undefined, undefined, ["input_form"]);
+    if (!pipeRef.includes(".")) {
+        throw new InputPreparationError(`Cannot prepare inputs: \`pipe_ref\` must be qualified (\`domain.pipe_code\`), got the bare ` +
+            `"${pipeRef}".`);
     }
-    if (!result.is_valid) {
-        const first = result.validation_errors[0]?.message ?? result.message;
-        throw new InputPreparationError(`Cannot prepare inputs: the method signature did not resolve — ${first}`);
-    }
-    return result;
+    return pipeRef;
 }
 /**
- * Pick the pipe whose descriptor guides the walk, in the order
- * `docs/input-preparation.md` documents: an explicit qualified `pipe_ref`, then
- * the report's resolved default — read on the field's PRESENCE, never on its
- * truthiness — and, behind an ABSENT field only, the bundle's declared
- * `main_pipe` then the single pipe.
+ * Ask `POST /v1/pipe-io` for the pipe and its signature, whatever the selector,
+ * and hand back the valid report.
  *
- * `default_pipe_ref` answers the very question this function asks: the qualified
- * ref of the pipe a selector-less run of THIS request would execute. A stated
- * `null` is that answer too — the server determined no entry pipe, and such a run
- * is refused by the run route — so reading it as silence and falling through would
- * prepare a pipe the run will not execute. Only a field the report does not carry
- * at all (a runner predating it) leaves the blueprint and single-pipe arms
- * standing. A JSON body cannot carry an own property holding `undefined`, and the
- * parsed body is handed through untouched, so strict `=== undefined` is the whole
- * absence test.
+ * The route runs no dry run and does not refuse a method with pending
+ * signatures elsewhere: preparation needs a pipe's DECLARED inputs, and whether
+ * the method runs is the run's verdict, not preparation's. The `is_valid: false`
+ * arm means the closure does not load, which is a preparation failure. So is a
+ * selection the route refuses — an unknown `pipe_ref`, no entry pipe, several —
+ * which it answers with a `422` typed by one of {@link PIPE_SELECTION_ERROR_TYPES};
+ * every other failure is re-thrown unchanged.
  */
-function selectPipeRef(report, inputForm, requested) {
-    const refs = Object.keys(inputForm);
-    const candidates = refs.length > 0 ? refs.join(", ") : "(none — the closure declares no pipes)";
-    if (requested !== undefined) {
-        if (!requested.includes(".")) {
-            throw new InputPreparationError(`Cannot prepare inputs: \`pipe_ref\` must be qualified (\`domain.pipe_code\`), got the bare ` +
-                `"${requested}". The method declares: ${candidates}.`);
-        }
-        if (!(requested in inputForm)) {
-            throw new InputPreparationError(`Cannot prepare inputs: the method declares no pipe "${requested}". It declares: ${candidates}.`);
-        }
-        return requested;
+async function fetchSignature(client, selector, pipeRef) {
+    const request = pipeRef === undefined ? { ...selector } : { ...selector, pipe_ref: pipeRef };
+    let result;
+    try {
+        result = await client.pipeIo(request);
     }
-    // The resolved default, when the runner serves the field at all (manifest-aware
-    // for a `method_ref` package, which is why it outranks the blueprint read below).
-    if (report.default_pipe_ref !== undefined) {
-        const statedDefault = nonEmptyString(report.default_pipe_ref);
-        if (statedDefault === undefined) {
-            // A stated `null` — or anything else that is not a non-empty string — is the
-            // server's verdict, not a gap: no entry pipe was determined, so a run naming
-            // no pipe would not resolve one either. Neither fallback stands behind it.
-            throw new InputPreparationError(`Cannot prepare inputs: the server determined no entry pipe for this method, so a run that ` +
-                `names no pipe would not resolve one (no \`main_pipe\` is declared, or the package manifest ` +
-                `names a pipe the closure does not declare or declares in several domains). Pass ` +
-                `\`pipe_ref\`. It declares: ${candidates}.`);
+    catch (error) {
+        if (error instanceof ApiResponseError &&
+            error.status === 422 &&
+            error.errorType !== undefined &&
+            PIPE_SELECTION_ERROR_TYPES.has(error.errorType)) {
+            const detail = error.serverMessage ?? error.message;
+            throw new InputPreparationError(`Cannot prepare inputs: ${detail}`, { cause: error });
         }
-        if (!(statedDefault in inputForm)) {
-            // The default and the descriptor come from one report keyed by one pipe set, so
-            // a miss is the report contradicting itself — falling through would silently
-            // prepare a different pipe than the one the run would execute.
-            throw new InputPreparationError(`Cannot prepare inputs: the validate report names "${statedDefault}" as the default pipe, but ` +
-                `its \`input_form\` descriptor does not describe it. Pass \`pipe_ref\`. It declares: ${candidates}.`);
-        }
-        return statedDefault;
+        throw error;
+    }
+    if (!result.is_valid) {
+        const first = result.validation_errors[0]?.message ?? result.message;
+        throw new InputPreparationError(`Cannot prepare inputs: the method signature did not resolve — ${first}`);
     }
-    // Behind an ABSENT field only. `bundle_blueprint` is opaque transport in this SDK
-    // on purpose, so read it defensively and fall through rather than trust it.
-    const blueprintDefault = readBlueprintMainPipeRef(report.bundle_blueprint);
-    if (blueprintDefault !== undefined && blueprintDefault in inputForm)
-        return blueprintDefault;
-    if (refs.length === 1)
-        return refs[0];
-    throw new InputPreparationError(`Cannot prepare inputs: the method declares no single default pipe, so \`pipe_ref\` is required. ` +
-        `It declares: ${candidates}.`);
+    return result;
 }
 /**
- * The bundle blueprint's declared `main_pipe`, qualified by its `domain` when it
- * is authored bare. Every read is defensive: the blueprint is typed
- * `Record<string, unknown>` because its schema is the runtime's, not this SDK's.
+ * The descriptor of the pipe the route selected. The route answers a
+ * single-pipe request with `input_form` keyed by exactly the `pipe_ref` it
+ * resolved, so a missing ref or a missing key is the answer contradicting itself
+ * — preparing any other pipe would silently walk the wrong signature.
  */
-function readBlueprintMainPipeRef(blueprint) {
-    if (!isPlainObject(blueprint))
-        return undefined;
-    const mainPipe = nonEmptyString(blueprint["main_pipe"]);
-    if (mainPipe === undefined)
-        return undefined;
-    if (mainPipe.includes("."))
-        return mainPipe;
-    const domain = nonEmptyString(blueprint["domain"]);
-    return domain === undefined ? undefined : `${domain}.${mainPipe}`;
+function selectedDescriptor(report) {
+    const pipeRef = nonEmptyString(report.pipe_ref);
+    const inputForm = report.input_form;
+    if (pipeRef === undefined || !isPlainObject(inputForm) || !Object.hasOwn(inputForm, pipeRef)) {
+        const described = isPlainObject(inputForm)
+            ? Object.keys(inputForm).join(", ") || "none"
+            : "none";
+        throw new InputPreparationError(`Cannot prepare inputs: the pipe I/O answer selected ${pipeRef === undefined ? "no pipe" : `"${pipeRef}"`}, ` +
+            `but its \`input_form\` does not describe it (it describes: ${described}).`);
+    }
+    return inputForm[pipeRef];
 }
 /**
  * Prepare a pipe's inputs: upload local/byte/data-URL assets at the signature's
@@ -346,27 +334,20 @@ function readBlueprintMainPipeRef(blueprint) {
  * records. HTTP(S) URLs and existing `pipelex-storage://` URIs pass through
  * unchanged. All failures are raised before any run is created.
  *
- * The signature comes from one `POST /v1/validate` with `views: ["input_form"]`,
- * whatever the selector — inline `files`, a `method_ref` the runner resolves, or
- * a `method_id` the platform resolves. A closure that does not load, an unknown
- * `pipe_ref`, no default pipe, or a report with no descriptor throw
- * {@link InputPreparationError}; a no-verdict condition from the route (a
- * malformed selector, an unknown or foreign-org id, no package at the address,
- * auth, a server fault) surfaces as `ApiResponseError`, unchanged.
+ * The pipe and its signature come from one `POST /v1/pipe-io`, whatever the
+ * selector — inline `files`, a `method_ref` the runner resolves, or a
+ * `method_id` the platform resolves. A bare or alias-qualified `pipe_ref`, a
+ * closure that does not load, and a selection the route refuses (an unknown
+ * `pipe_ref`, no entry pipe, several) throw {@link InputPreparationError}; any
+ * other failure from the route (a malformed selector, an unknown or foreign-org
+ * id, no package at the address, auth, a server fault, a deployment that does not
+ * serve the route) surfaces as `ApiResponseError`, unchanged.
  */
 export async function prepareInputs(client, request) {
     const selector = resolveSelector(request);
-    const report = await fetchSignature(client, selector);
-    const inputForm = report.input_form;
-    if (inputForm === undefined) {
-        // Never a silent degrade to "no uploads": without the descriptor there is no
-        // signature to prepare against.
-        throw new InputPreparationError("Cannot prepare inputs: the validate report carries no `input_form` descriptor — the signature " +
-            'preparation reads. The descriptor rides `views: ["input_form"]` on pipelex-api >= 0.18.0; ' +
-            "point the client at a runner that serves it.");
-    }
-    const pipeRef = selectPipeRef(report, inputForm, nonEmptyString(request.pipe_ref));
-    const descriptor = inputForm[pipeRef];
+    const pipeRef = normalizePipeRef(request.pipe_ref);
+    const report = await fetchSignature(client, selector, pipeRef);
+    const descriptor = selectedDescriptor(report);
     const declared = new Map(descriptor.fields.map((field) => [field.name, field]));
     const ctx = { client, uploads: [], dedup: new Map() };
     const rewritten = { ...request.inputs };