@pipelex/sdk 0.51.0 → 0.53.0

package/dist/models.d.ts

@@ -3,12 +3,13 @@
  *
  * Holds the Dict-serialized protocol concretes (`DictStuff` / `DictWorkingMemory`
  * / `DictPipeOutput` and the default `RunResultExecute` binding), the Pipelex
- * `/v1/validate` surface (`PipelexValidationResult` + `ValidationErrorItem`), the
+ * `/v1/validate` surface (`PipelexValidationResult`, whose faults are the standard's
+ * `ProblemItem`s), the
  * request/response models of the tools routes and the crate routes, and the verdict of
  * the model reference check. Built on the protocol wire types imported from the
  * `mthds/protocol` subpath.
  */
-import type { InputForm, MethodFiles, MethodTreeSource, OutputForm, PipeIOContracts, RunResultExecute, RunResultStart } from "mthds/protocol";
+import type { InputForm, MethodFiles, ProblemItem, MethodTreeSource, OutputForm, PipeIOContracts, RunResultExecute, RunResultStart } from "mthds/protocol";
 import type { MethodTreeForm, NoMethodTree } from "./method-trees.js";
 export interface DictStuff {
     concept: string;
@@ -85,8 +86,8 @@ export interface PipelexRunResultStart extends RunResultStart {
  * one of inline source / `method_ref` / `method_id` per request — any second
  * selector is a request-shape `422`. An unknown or foreign-org id is a `404`
  * (indistinguishable by design); a bare id of a method never published is a `409`
- * `method_not_published`; a version never published is a `404`
- * `method_version_not_found`; a malformed suffix, or a stored method with no MTHDS
+ * `pipelex.catalog.not_published`; a version never published is a `404`
+ * `pipelex.catalog.not_found`; a malformed suffix, or a stored method with no MTHDS
  * source, is a `422`.
  */
 export interface PipelexHostedToolingExtensions {
@@ -301,17 +302,12 @@ export interface PipelexValidationReport {
     /** Per-pipe dry-run sweep outcomes. */
     validated_pipes: ValidatedPipeEntry[];
     /**
-     * Advisory findings on a VALID bundle — same item shape as `validation_errors[]`, so one
-     * parser serves both channels, but these never flip `is_valid`. Empty when there is
-     * nothing to report. Their `error_type`s come in families, always in this order: the
-     * useless-`!` lint (`optional_force_redundant`), the entry pipe's vacuous-presence lint
-     * (`input_presence_vacuous`), the intent-hint lints (`hint_unknown_key`,
-     * `hint_unknown_intent`, `hint_inapplicable_intent`, which ride here exclusively), then the
-     * findings a `PipeDocGen` step's template check made in its office template file during
-     * the dry run (`template_check_warning`, a `dry_run` item carrying `pipe_code`,
-     * `domain_code`, `template_file` and `template_location`).
+     * Advisory findings on a VALID bundle, one problem item each with the code its finding's
+     * type names: the same item shape as the invalid arm's `errors[]`, so one reader serves
+     * both, but these never flip `is_valid`. Empty when there is nothing to report. The client
+     * reads them member by member (`readProblemItems`).
      */
-    warnings: ValidationErrorItem[];
+    warnings: ProblemItem[];
     /** Qualified refs of pipes still declared as `PipeSignature`. */
     pending_signatures: string[];
     /** `not pending_signatures` — whether the validated library is complete enough to run. */
@@ -332,17 +328,20 @@ export interface PipelexValidationReport {
 }
 /**
  * Pipelex's `POST /v1/validate` 200 body for an INVALID bundle — the `is_valid: false`
- * arm of the response union, carrying the closed-vocabulary `ValidationErrorItem[]`.
- * The structural artifacts of the valid arm
- * are absent (they don't exist when load/parse/wiring failed); `validation_errors[]` is
- * non-empty on every invalid verdict (the structured-info invariant — even a parse-level
- * failure carries one source-less `blueprint_validation` residual).
+ * arm of the response union, listing its faults as problem items. The structural
+ * artifacts of the valid arm are absent (they don't exist when load/parse/wiring failed);
+ * `errors[]` is non-empty on every invalid verdict the server sends, and the client reads
+ * it member by member (`readProblemItems`), so an item whose `code` or `detail` is not a
+ * string is skipped and a malformed member is left out of its item.
  */
 export interface PipelexInvalidReport {
     /** Discriminant of the invalid arm. */
     is_valid: false;
-    /** Structured per-error diagnostics, built by pipelex's one shared builder. */
-    validation_errors: ValidationErrorItem[];
+    /**
+     * One problem item per fault, each with its own `code`, `detail`, `params`, `location`
+     * and, when the server has one, its `suggested_fix`.
+     */
+    errors: ProblemItem[];
     /** Outstanding signatures (best-effort; empty when no library could be assembled). */
     pending_signatures: string[];
     /** An invalid bundle is never runnable. */
@@ -351,8 +350,8 @@ export interface PipelexInvalidReport {
     message: string;
     /**
      * Opt-in Pipelex-API presentation extra: the server-rendered Markdown view of the
-     * invalid verdict (`# Validation failed` + the `validation_errors`), present only
-     * when the request asked for it (`render: ["markdown"]`). Absent by default.
+     * invalid verdict's errors, present only when the request asked for it
+     * (`render: ["markdown"]`). Absent by default.
      */
     rendered_markdown?: string;
 }
@@ -363,185 +362,6 @@ export interface PipelexInvalidReport {
  * answers, not narrowings of the protocol's (see the section's heading above).
  */
 export type PipelexValidationResult = PipelexValidationReport | PipelexInvalidReport;
-/**
- * Which validation stage produced a `ValidationErrorItem` — mirror of pipelex's
- * closed `ValidationErrorCategory` set. `pipe_factory` and graph-level `dry_run`
- * items carry no `source`; map those by `domain_code` / `pipe_code`. The other
- * categories carry `source` when the runtime can attribute one.
- */
-export type ValidationErrorCategory = "blueprint_validation" | "pipe_factory" | "pipe_validation" | "dry_run";
-/**
- * One structured bundle-validation error — mirror of pipelex's `ValidationErrorItem`.
- * Carried by `PipelexInvalidReport.validation_errors[]` on the **200** invalid arm of
- * `POST /v1/validate` (NOT a 422 — an invalid bundle is a produced verdict), by the
- * VALID arm's advisory `warnings[]`, by the crate routes' **200** invalid arm
- * (`CrateInvalidReport.validation_errors[]`), by the 422 problem body a run route answers
- * when the runner refuses the method for its validation errors
- * (`ApiResponseError.validationErrors`), and by a failed run's stored report.
- *
- * **The shape is the hosted plane's.** It is the item the runner sends today, which
- * predates the standard's problem items: from protocol 2.0.0 a verdict lists its faults
- * as `ProblemItem`s under a registry `code`, which the hosted plane does not send yet, so
- * this declaration is not the standard's and is not pinned to it. Its fix shares the
- * standard's operation and safety vocabularies, which `tests/validation-items.test.ts`
- * pins.
- *
- * Only `category` and `message` are always present; the rest are populated per
- * `category`. Every other member is `?: T | null` because the two channels serialize an
- * unset locator differently: the invalid arm and the crate routes drop the key
- * (`exclude_none` server-side) while the valid arm — which carries `warnings[]` — does
- * not, so the same item arrives with explicit `null`s there. A truthiness check reads
- * both; an `=== undefined` check would be wrong on one of them.
- *
- * `source` is the declaring file: its path (CLI), or its tree path in the tree the
- * request sent — the owning file for cross-file diagnostics.
- *
- * An `unknown_model` item (a model reference the runner's model deck does not know)
- * carries the reference as written, the kind of model the field takes and the close
- * matches, and, when there is exactly one close match, a `suggested_fix` that remaps
- * the reference to it.
- *
- * A `template_check_warning` item, on the valid arm's `warnings[]` only, is a finding of a
- * `PipeDocGen` step's template check in its office template file during the dry run, such
- * as a field of the template that matches no input: a `dry_run` item carrying the step's
- * `pipe_code` and `domain_code`, the template file as the step names it and the place in
- * it the engine's finding names.
- */
-export interface ValidationErrorItem {
-    category: ValidationErrorCategory;
-    message: string;
-    error_type?: string | null;
-    pipe_code?: string | null;
-    concept_code?: string | null;
-    domain_code?: string | null;
-    source?: string | null;
-    field_path?: string | null;
-    field_name?: string | null;
-    variable_names?: string[] | null;
-    missing_concept_code?: string | null;
-    /** The pipe a reference names that the bundle does not declare. */
-    missing_pipe_code?: string | null;
-    declared_concepts?: string[] | null;
-    /**
-     * On an `unknown_model` item: the model reference exactly as the author wrote it
-     * (`gpt-5.1`, `@best-sonet`, `$writting-factual`).
-     */
-    model_reference?: string | null;
-    /** On an `unknown_model` item: the kind of model the field takes (`llm`, `img_gen`, …). */
-    model_type?: string | null;
-    /**
-     * On an `unknown_model` item: the close matches of the same kind, each spelled as a
-     * reference the field accepts.
-     */
-    suggestions?: string[] | null;
-    /**
-     * On a `template_check_warning` item: the template file as the `PipeDocGen` step names it
-     * (`templates/invoice.xlsx`); `null` for a step of the server's own library, whose path is
-     * the server's and is never shown.
-     */
-    template_file?: string | null;
-    /**
-     * On a `template_check_warning` item: the place in the template file the finding names, in
-     * the engine's own words (a defined name, a table, a cell, a shape, a tag); `null` when the
-     * finding names none.
-     */
-    template_location?: string | null;
-    /** The server's deterministic repair proposal for this error, when it has one. */
-    suggested_fix?: SuggestedFix | null;
-}
-/** Whether a `SuggestedFix` is safe to auto-apply, or needs explicit opt-in. */
-export type FixSafety = "safe" | "unsafe";
-/** The semantic patch operations a `SuggestedFix` is composed of. */
-export type FixOpKind = "set_key" | "ensure_table" | "delete_key" | "delete_table" | "rename_table_key" | "move_key" | "remap_value";
-/** A TOML-representable scalar a `set_key` op can write. */
-export type TomlScalar = string | number | boolean;
-/**
- * What a `set_key` op writes: a scalar, or a flat scalar mapping for fixes that create
- * a whole table at once (written as an inline table). Deeper nesting is not modelled —
- * the server does not emit it.
- */
-export type TomlValue = TomlScalar | Record<string, TomlScalar>;
-/** `TomlValue` under the name `mthds` gives it, so either client's vocabulary reads here. */
-export type FixValue = TomlValue;
-/**
- * What every fix op carries: the table it acts in. `table_path` addresses the containing
- * table (e.g. `["pipe", "my_seq"]`), aligned with the `field_path` conventions of
- * `ValidationErrorItem`, and is empty for the document root.
- *
- * The segment `"*"` is the wildcard — "every entry of the open mapping at this node".
- * The server refuses it as a `key` on every kind but `remap_value`, the only one with a
- * per-key meaning for it.
- */
-interface FixOpBase {
-    table_path: string[];
-}
-/** Write `key = value` in the addressed table, whatever it currently holds. */
-export interface SetKeyOp extends FixOpBase {
-    kind: "set_key";
-    key: string;
-    value: TomlValue;
-}
-/** Create the addressed table when it is missing. `table_path` is never empty. */
-export interface EnsureTableOp extends FixOpBase {
-    kind: "ensure_table";
-}
-/** Remove `key` from the addressed table. */
-export interface DeleteKeyOp extends FixOpBase {
-    kind: "delete_key";
-    key: string;
-}
-/** Remove the addressed table entirely. `table_path` is never empty. */
-export interface DeleteTableOp extends FixOpBase {
-    kind: "delete_table";
-}
-/** Rename `key` to `new_key` within the addressed table. */
-export interface RenameTableKeyOp extends FixOpBase {
-    kind: "rename_table_key";
-    key: string;
-    new_key: string;
-}
-/** Move `key` out of the addressed table into `new_table_path`, under `new_key`. */
-export interface MoveKeyOp extends FixOpBase {
-    kind: "move_key";
-    key: string;
-    new_table_path: string[];
-    new_key: string;
-}
-/**
- * Rewrite `key`'s value through `mapping`, leaving an unmapped value untouched. The
- * unknown-model fix is one: it maps the reference as written to its one close match, so
- * it changes nothing once the author has edited the field.
- */
-export interface RemapValueOp extends FixOpBase {
-    kind: "remap_value";
-    key: string;
-    mapping: Record<string, string>;
-}
-/** One patch operation of a `SuggestedFix` — discriminated on `kind`. */
-export type FixOp = SetKeyOp | EnsureTableOp | DeleteKeyOp | DeleteTableOp | RenameTableKeyOp | MoveKeyOp | RemapValueOp;
-/**
- * A deterministic fix for one validation error, ready for a style-preserving applier —
- * mirror of pipelex's `SuggestedFix`. The ops are semantic patches over the `.mthds`
- * document, not a text diff, so an applier keeps the author's formatting.
- *
- * The shape is the hosted plane's, as `ValidationErrorItem`'s is: the standard's
- * `SuggestedFix` names the file `file` rather than `source` and is open to members it does
- * not declare. Its operation kinds, its safeties and the values a `set_key` writes are the
- * standard's (this SDK's `TomlValue` is the standard's `FixValue`), and a type-level test
- * pins them.
- */
-export interface SuggestedFix {
-    /** The kebab-case rule id, e.g. `"match-sequence-output"`. */
-    fix_code: string;
-    description: string;
-    safety: FixSafety;
-    /**
-     * The file the ops target, when known (multi-file libraries). An applier must only
-     * apply these ops to that file.
-     */
-    source?: string | null;
-    ops: FixOp[];
-}
 /** Which analysis produced a `Diagnostic` — mirror of `pipelex-tools`' closed kind set. */
 export type DiagnosticKind = "syntax" | "semantic" | "schema";
 /** Source span of a `Diagnostic` — byte offsets plus 1-based line/column coordinates. */
@@ -673,7 +493,11 @@ export interface CrateRouteOptions {
  */
 export interface CrateInvalidReport {
     is_valid: false;
-    validation_errors: ValidationErrorItem[];
+    /**
+     * One problem item per fault, the same items `/v1/validate` lists for the identical
+     * failure, read member by member (`readProblemItems`).
+     */
+    errors: ProblemItem[];
     message: string;
 }
 /**
@@ -787,12 +611,12 @@ export interface PipeIORequest extends CrateRequestBase, PipelexHostedToolingExt
      * The pipe to describe, as a QUALIFIED `domain.pipe_code` ref. Omit it and the
      * server's selection chain decides: the `main_pipe` of the `METHODS.toml` at the tree's
      * root, whether the tree was sent or fetched, 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`.
+     * declaration. A selection the server refuses is a problem coded by what went wrong, of
+     * the domain `input`, the candidates in its parameters where there are some:
+     * `request.pipe_not_found` for a ref that names no pipe, `request.pipe_unspecified` for
+     * (without `all_pipes`) a method with no entry pipe, `request.pipe_ambiguous` for a code that
+     * matches pipes in several domains or (without `all_pipes`) several `main_pipe` declarations.
+     * A malformed request is `request.malformed`.
      *
      * 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.
@@ -978,4 +802,3 @@ export interface HandleReferenceVerdict extends ModelReferenceVerdictBase {
  * matches of one verdict share its kind; no field is added to the wire to make it so.
  */
 export type ModelReferenceVerdict = PresetReferenceVerdict | AliasReferenceVerdict | WaterfallReferenceVerdict | HandleReferenceVerdict;
-export {};

package/dist/models.js

@@ -3,7 +3,8 @@
  *
  * Holds the Dict-serialized protocol concretes (`DictStuff` / `DictWorkingMemory`
  * / `DictPipeOutput` and the default `RunResultExecute` binding), the Pipelex
- * `/v1/validate` surface (`PipelexValidationResult` + `ValidationErrorItem`), the
+ * `/v1/validate` surface (`PipelexValidationResult`, whose faults are the standard's
+ * `ProblemItem`s), the
  * request/response models of the tools routes and the crate routes, and the verdict of
  * the model reference check. Built on the protocol wire types imported from the
  * `mthds/protocol` subpath.

package/dist/models.js.map

@@ -1 +1 @@
-{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/prepare-inputs.d.ts

@@ -180,8 +180,8 @@ export declare function inputFormFault(entry: unknown): InputFormFault | undefin
  * `MethodFileTransferError` before the route is asked. 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}. So
- * does an answer that breaks the route's contract, with a `runtime` verdict that
- * is not retryable: no boolean `is_valid`, an `input_form` that does not describe
+ * does an answer that breaks the route's contract, with the problem
+ * `client.response_unreadable`: no boolean `is_valid`, an `input_form` that does not describe
  * the selected pipe, or a descriptor that is malformed or names a kind this SDK
  * does not know, which is checked whole before anything is uploaded. Any other
  * failure from the route (a malformed selector, an unknown or foreign-org id, no

package/dist/prepare-inputs.js

@@ -30,9 +30,9 @@
  * dict. See `docs/input-preparation.md`, which `pipelex-sdk-python` mirrors case
  * for case.
  */
-import { isValidationItem } from "./error-models.js";
+import { readProblemItems } from "./problem-items.js";
 import { throwIfAborted } from "./runs.js";
-import { ApiResponseError, InputPreparationError, InvalidInputValueError, MethodLoadError, UploadNotAllowedError, } from "./errors.js";
+import { ApiResponseError, InputPreparationError, InvalidInputValueError, MethodLoadError, UploadNotAllowedError, argumentInvalidProblem, responseUnreadableProblem, } from "./errors.js";
 import { treeShapeFault } from "./method-trees.js";
 import { uploadFile, uploadKindFields } from "./upload.js";
 const PIPELEX_STORAGE_SCHEME = "pipelex-storage://";
@@ -59,18 +59,17 @@ const WALKED_KINDS = {
 };
 const KNOWN_KINDS = new Set(Object.keys(WALKED_KINDS));
 /**
- * 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`.
+ * The problem codes of the route's pipe-selection refusals, the only refusals `prepareInputs`
+ * turns into an `InputPreparationError`: a ref that names no pipe (`request.pipe_not_found`),
+ * several pipes it could mean (`request.pipe_ambiguous`), and no pipe named where the method has
+ * no entry pipe (`request.pipe_unspecified`). They are the run routes' vocabulary too. Every other
+ * refusal (a malformed body, an over-limit file, a fetched package with no `.mthds` file, a stored
+ * method with no source) stays an `ApiResponseError`.
  */
-const PIPE_SELECTION_ERROR_TYPES = new Set([
-    "EntryPipeNotFoundError",
-    "EntryPipeAmbiguousError",
+const PIPE_SELECTION_CODES = new Set([
+    "request.pipe_not_found",
+    "request.pipe_ambiguous",
+    "request.pipe_unspecified",
 ]);
 /** Strict plain-object test — excludes arrays, `Uint8Array`, `Blob`, and other exotics. */
 function isPlainObject(value) {
@@ -316,7 +315,7 @@ async function resolveNode(ctx, node, callerValue, at) {
         default: {
             // Unreachable: the descriptor was checked against WALKED_KINDS before the walk began.
             const unwalked = node;
-            throw new InputPreparationError(`Cannot prepare inputs: the walk has no arm for the kind ${described(unwalked.kind)}.`, { verdict: { errorDomain: "runtime", retryable: false } });
+            throw new InputPreparationError(`Cannot prepare inputs: the walk has no arm for the kind ${described(unwalked.kind)}.`, { problem: responseUnreadableProblem(200) });
         }
     }
 }
@@ -343,12 +342,12 @@ function refuseNonMap(name, value, holds, isValue) {
     if (value === undefined || value === null)
         return;
     if (!isPlainObject(value)) {
-        throw new InputPreparationError(`Cannot prepare inputs: \`${name}\` must be ${holds}, got ${describeNonMap(value)}.`);
+        throw new InputPreparationError(`Cannot prepare inputs: \`${name}\` must be ${holds}, got ${describeNonMap(value)}.`, { problem: argumentInvalidProblem(name, "not_a_map") });
     }
     for (const [key, entry] of Object.entries(value)) {
         if (!isValue(entry)) {
             throw new InputPreparationError(`Cannot prepare inputs: \`${name}\` must be ${holds}, and "${key}" holds ` +
-                `${entry === null ? "null" : describeNonMap(entry)}.`);
+                `${entry === null ? "null" : describeNonMap(entry)}.`, { problem: argumentInvalidProblem(name, "entry_mistyped") });
         }
     }
 }
@@ -365,11 +364,11 @@ function checkedTree(value) {
     if (fault !== undefined) {
         throw new InputPreparationError("Cannot prepare inputs: `tree` must be a listed method tree — its `files`, its `digest` and " +
             "a `readFile` — such as the `MethodTree` the client's `listMethodTree` returns, got " +
-            `${fault}.`);
+            `${fault}.`, { problem: argumentInvalidProblem("tree", "not_a_tree") });
     }
     const tree = value;
     if (tree.files.length === 0) {
-        throw new InputPreparationError("Cannot prepare inputs: `tree` holds no file, and a method tree holds at least one.");
+        throw new InputPreparationError("Cannot prepare inputs: `tree` holds no file, and a method tree holds at least one.", { problem: argumentInvalidProblem("tree", "empty") });
     }
     return tree;
 }
@@ -390,14 +389,14 @@ function resolveSelector(request) {
     const rawFiles = raw["files"];
     if (rawFiles !== undefined && rawFiles !== null && !isPlainObject(rawFiles)) {
         throw new InputPreparationError("Cannot prepare inputs: `files` must be the method's tree as a map from tree path to file " +
-            `entry, got ${Array.isArray(rawFiles) ? "a list" : typeof rawFiles}.`);
+            `entry, got ${Array.isArray(rawFiles) ? "a list" : typeof rawFiles}.`, { problem: argumentInvalidProblem("files", "not_a_map") });
     }
     refuseNonMap("contents", raw["contents"], "the method's files as a map from tree path to bytes or text", (entry) => typeof entry === "string" || entry instanceof Uint8Array);
     refuseNonMap("dependencies", raw["dependencies"], "the method packages as a map from package address to its map of file entries", isPlainObject);
     const rawDirectory = raw["directory"];
     if (rawDirectory !== undefined && rawDirectory !== null && typeof rawDirectory !== "string") {
         throw new InputPreparationError("Cannot prepare inputs: `directory` must be the method's directory as a path, got " +
-            `${describeNonMap(rawDirectory)}.`);
+            `${describeNonMap(rawDirectory)}.`, { problem: argumentInvalidProblem("directory", "not_a_string") });
     }
     const directory = typeof rawDirectory === "string" && rawDirectory !== "" ? rawDirectory : undefined;
     const files = nonEmptyMap(rawFiles);
@@ -417,7 +416,7 @@ function resolveSelector(request) {
         treeForms.push("`files`");
     if (treeForms.length > 1) {
         throw new InputPreparationError(`Cannot prepare inputs: the method's tree was given as ${treeForms.join(" and ")}. Give it ` +
-            "in one form — `directory`, `contents`, `tree` or `files`.");
+            "in one form — `directory`, `contents`, `tree` or `files`.", { problem: argumentInvalidProblem("files", "mutually_exclusive") });
     }
     const given = [...treeForms];
     if (methodRef !== undefined)
@@ -427,12 +426,12 @@ function resolveSelector(request) {
     if (given.length === 0) {
         throw new InputPreparationError("Cannot prepare inputs: no method selector. Supply exactly one of the method's tree " +
             "(`directory`, `contents`, `tree` or `files`), `method_ref` (a published method's address) or " +
-            "`method_id` (a stored method's catalog id).");
+            "`method_id` (a stored method's catalog id).", { problem: argumentInvalidProblem("files", "nothing_to_prepare") });
     }
     if (given.length > 1) {
         throw new InputPreparationError(`Cannot prepare inputs: ${given.join(" and ")} were ${given.length === 2 ? "both" : "all"} ` +
             "given. Supply exactly one method " +
-            "selector — the method's tree, `method_ref` or `method_id`.");
+            "selector — the method's tree, `method_ref` or `method_id`.", { problem: argumentInvalidProblem("files", "mutually_exclusive") });
     }
     if (treeForms.length === 1) {
         return {
@@ -447,7 +446,7 @@ function resolveSelector(request) {
     const owner = methodRef !== undefined ? "published" : "stored";
     if (dependencies !== undefined) {
         throw new InputPreparationError(`Cannot prepare inputs: \`dependencies\` accompany the method's own tree; a ${owner} ` +
-            "method's packages are its own.");
+            "method's packages are its own.", { problem: argumentInvalidProblem("dependencies", "without_a_tree") });
     }
     if (methodRef !== undefined)
         return { method_ref: methodRef };
@@ -472,11 +471,11 @@ function normalizePipeRef(raw) {
         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`.");
+            "Preparation covers the method's own pipes: name one as `domain.pipe_code`.", { problem: argumentInvalidProblem("pipe_ref", "dependency_pipe") });
     }
     if (!pipeRef.includes(".")) {
         throw new InputPreparationError(`Cannot prepare inputs: \`pipe_ref\` must be qualified (\`domain.pipe_code\`), got the bare ` +
-            `"${pipeRef}".`);
+            `"${pipeRef}".`, { problem: argumentInvalidProblem("pipe_ref", "not_qualified") });
     }
     return pipeRef;
 }
@@ -490,7 +489,7 @@ function resolveAllowUploads(raw) {
         return true;
     if (typeof raw === "boolean")
         return raw;
-    throw new InputPreparationError(`Cannot prepare inputs: \`allowUploads\` must be a boolean, got ${raw === null ? "null" : typeof raw}.`);
+    throw new InputPreparationError(`Cannot prepare inputs: \`allowUploads\` must be a boolean, got ${raw === null ? "null" : typeof raw}.`, { problem: argumentInvalidProblem("allowUploads", "not_a_bool") });
 }
 /**
  * The request's `upload`, checked once before any request as `uploadFile` checks its own: absent
@@ -502,7 +501,7 @@ function resolveUploadAs(raw) {
         return {};
     if (!isPlainObject(raw)) {
         throw new InputPreparationError("Cannot prepare inputs: `upload` must be an object of `kind` and `method_id`, got " +
-            `${describeNonMap(raw)}.`);
+            `${describeNonMap(raw)}.`, { problem: argumentInvalidProblem("upload", "not_upload_kind_options") });
     }
     return uploadKindFields(raw, "Cannot prepare inputs", "upload.");
 }
@@ -515,9 +514,9 @@ function resolveUploadAs(raw) {
  * 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. An answer with no boolean `is_valid`
- * is neither arm, so it fails the preparation with a `runtime` verdict, as an
+ * which it answers with a problem of one of {@link PIPE_SELECTION_CODES}; every
+ * other failure is re-thrown unchanged. An answer with no boolean `is_valid` is
+ * neither arm, so it fails the preparation with `client.response_unreadable`, as an
  * `input_form` that does not describe the selected pipe does, and one whose
  * descriptor is malformed where the walk reads it.
  */
@@ -528,12 +527,11 @@ async function fetchSignature(client, selector, pipeRef, signal) {
         result = await client.pipeIo(request, signal === undefined ? {} : { signal });
     }
     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 (error instanceof ApiResponseError && PIPE_SELECTION_CODES.has(error.code)) {
+            throw new InputPreparationError(`Cannot prepare inputs: ${error.problem.detail}`, {
+                cause: error,
+                problem: error.problem,
+            });
         }
         throw error;
     }
@@ -542,27 +540,26 @@ async function fetchSignature(client, selector, pipeRef, signal) {
         // An answer with no boolean discriminant is neither arm: the route broke its own contract,
         // which no change to the request fixes.
         throw new InputPreparationError("Cannot prepare inputs: the pipe I/O answer carries no boolean `is_valid`, so it says " +
-            "neither that the method loaded nor why it did not.", { verdict: { errorDomain: "runtime", retryable: false } });
+            "neither that the method loaded nor why it did not.", { problem: responseUnreadableProblem(200) });
     }
     if (!answer.is_valid) {
-        const items = answer.validation_errors;
-        throw new MethodLoadError(`Cannot prepare inputs: the method signature did not resolve — ${invalidReason(answer)}`, {
-            validationErrors: Array.isArray(items) ? items.filter(isValidationItem) : [],
+        const errors = readProblemItems(answer.errors);
+        throw new MethodLoadError(`Cannot prepare inputs: the method signature did not resolve — ${invalidReason(answer, errors)}`, {
+            errors,
             serverMessage: typeof answer.message === "string" ? answer.message : undefined,
         });
     }
     return result;
 }
 /**
- * Why an invalid pipe I/O answer says the closure did not load: its first validation item's
- * message, else its own `message`. Each is read only when it has its declared type, since the
- * answer is the server's, and an answer carrying neither still fails the preparation.
+ * Why an invalid pipe I/O answer says the closure did not load: its first problem item's `detail`,
+ * else its own `message`. Each is read only when it has its declared type, since the answer is the
+ * server's, and an answer carrying neither still fails the preparation.
  */
-function invalidReason(answer) {
-    const items = answer.validation_errors;
-    const first = Array.isArray(items) ? items[0] : undefined;
-    if (isPlainObject(first) && typeof first.message === "string")
-        return first.message;
+function invalidReason(answer, errors) {
+    const first = errors[0];
+    if (first !== undefined)
+        return first.detail;
     return typeof answer.message === "string" ? answer.message : "the answer gives no reason";
 }
 /**
@@ -581,7 +578,7 @@ function selectedDescriptor(report) {
             : "none";
         // The route broke its own contract, which no change to the request fixes.
         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: ${describedPipes}).`, { verdict: { errorDomain: "runtime", retryable: false } });
+            `but its \`input_form\` does not describe it (it describes: ${describedPipes}).`, { problem: responseUnreadableProblem(200) });
     }
     return checkedDescriptor(pipeRef, inputForm[pipeRef]);
 }
@@ -591,7 +588,7 @@ function selectedDescriptor(report) {
  * its first fault.
  *
  * A malformation is the route breaking its contract, at whatever depth and under
- * whichever input, so it is refused with a `runtime` verdict, not retryable. It is
+ * whichever input, so it is refused with `client.response_unreadable`. It is
  * never passed through: a node the SDK cannot read may be a file position, and
  * under the default mode passing it through would send the caller's local path to
  * the runner verbatim. A `kind` outside {@link WALKED_KINDS} is refused for the
@@ -601,7 +598,7 @@ function checkedDescriptor(pipeRef, entry) {
     const found = inputFormFault(entry);
     if (found !== undefined) {
         throw new InputPreparationError(`Cannot prepare inputs: the pipe I/O answer's \`input_form\` for "${pipeRef}" ` +
-            `is ${found.message}.`, { verdict: { errorDomain: "runtime", retryable: false } });
+            `is ${found.message}.`, { problem: responseUnreadableProblem(200) });
     }
     return entry;
 }
@@ -706,8 +703,8 @@ function described(value) {
  * `MethodFileTransferError` before the route is asked. 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}. So
- * does an answer that breaks the route's contract, with a `runtime` verdict that
- * is not retryable: no boolean `is_valid`, an `input_form` that does not describe
+ * does an answer that breaks the route's contract, with the problem
+ * `client.response_unreadable`: no boolean `is_valid`, an `input_form` that does not describe
  * the selected pipe, or a descriptor that is malformed or names a kind this SDK
  * does not know, which is checked whole before anything is uploaded. Any other
  * failure from the route (a malformed selector, an unknown or foreign-org id, no