@pipelex/sdk 0.47.0 → 0.48.0

package/dist/client.d.ts

@@ -1,28 +1,19 @@
 import type { MTHDSProtocol, ModelCategory, ModelDeck, RunOptions, StartOptions, VersionInfo } from "mthds/protocol";
-import type { CodegenRequest, CodegenResponse, DictPipeOutput, FormatResponse, LintResponse, ModelCheckCategory, ModelReferenceVerdict, PipeIORequest, PipeIOResponse, PipelexRunResultStart, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector } from "./models.js";
+import type { CodegenRequest, CodegenResponse, CrateRouteOptions, DictPipeOutput, FormatResponse, LintResponse, ModelCheckCategory, ModelReferenceVerdict, PipeIORequest, PipeIOResponse, PipelexRunResultStart, PipelexValidateSource, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector } from "./models.js";
 import { type GetRunResultOptions, type RunProgress, type RunRead, type RunResults, type RunResultState, type StartAndWaitForResultOptions, type WaitForResultOptions } from "./runs.js";
 import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, InvoiceView, Membership, MembershipsResponse, ListMethodExamplesQuery, ListMethodsQuery, ListMethodVersionsQuery, MethodData, MethodDeletionAccepted, MethodDetail, MethodDraftInput, MethodExample, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunResult, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunPage, PlanView, ResolvedStorageUrl, SavedMethodFile, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
-import type { MethodTreeLimits } from "./method-trees.js";
+import type { MethodTreeForms, MethodTreeLimits } from "./method-trees.js";
 import type { AppInfo } from "./user-agent.js";
 import type { UploadableAsset, UploadFileOptions, UploadRecord } from "./upload.js";
-import type { BundleResources } from "./bundle-resources.js";
 import type { PrepareInputsRequest, PreparedInputs } from "./prepare-inputs.js";
 import type { BulkResolveStorageUrlsInput, BulkResolvedStorageUrls, DownloadArtifactsRequest, DownloadArtifactsResult, FetchArtifactOptions, ResolvedArtifact } from "./artifacts.js";
 import { PipelexExecuteResult } from "./execute-result.js";
-export interface MthdsFile {
-    /** File contents to validate. */
-    content: string;
-    /** Optional provenance URI threaded into validation diagnostics. */
-    uri?: string;
-}
 /**
- * The Pipelex API's own run arguments — the layer-2 arguments the RUNNER itself
- * reads, beside the protocol's inline sources (`mthds_contents` and the bundle
- * encodings): the `method_ref` run source, served by any pipelex-api >= 0.21.0
- * deployment, bare or hosted (on `api.pipelex.com`, once the platform deploy
- * carrying it lands), and the `resources` the bundle's steps read.
+ * The Pipelex API's own run argument — the layer-2 argument the RUNNER itself
+ * reads, beside the protocol's `files` map: the `method_ref` run source, served by
+ * any pipelex-api >= 0.21.0 deployment, bare or hosted.
  *
- * Named options rather than `extra` entries, for the same reason as the hosted
+ * A named option rather than an `extra` entry, for the same reason as the hosted
  * extensions below: `extra` remains the escape hatch for an extension this
  * client does not know about, never the way to pass one it does.
  */
@@ -34,32 +25,18 @@ export interface PipelexApiRunExtensions {
      * default branch at HEAD), the package is located by manifest identity, and
      * the resolved commit SHA comes back as `method_provenance` on the response.
      *
-     * A complete run source of its own — the fetched package carries its `.mthds`
-     * and its entry pipe — so it pairs with NOTHING: exclusive with inline
-     * `mthds_contents`, with a method bundle (`files` / `bundle_b64`), and with
-     * the hosted `method_id` (an address run has its own provenance and needs no
-     * linkage id). `pipe_code` beside it is fine — it overrides the manifest's
-     * `main_pipe` to pick which pipe in the fetched package to run. This client
-     * rejects the illegal pairings before anything hits the wire, mirroring the
-     * server's own 422s.
+     * A complete run source of its own — the fetched package carries its whole
+     * tree and its entry pipe — so it pairs with NOTHING: exclusive with the
+     * method's tree in any of its forms (`directory`, `contents`, `tree`, `files`)
+     * and with the hosted `method_id` (an address run has its own provenance and
+     * needs no linkage id). `pipe_code` beside it is fine — it overrides the
+     * manifest's `main_pipe` to pick which pipe in the fetched package to run. This
+     * client rejects the illegal pairings before anything hits the wire, mirroring
+     * the server's own 422s.
      *
      * An empty string is treated as absent and is not sent.
      */
     method_ref?: string | null;
-    /**
-     * The files the bundle's steps read, such as a `PipeDocGen` step's `template_file`, keyed
-     * by the path the step names (`templates/invoice.docx`), each as its bytes (a `Uint8Array`,
-     * a Node `Buffer` included, an `ArrayBuffer` or a `Blob`). The client sends them as the
-     * wire's `resources`, each file in standard base64; see `docs/bundle-resources.md`.
-     *
-     * They accompany the bundle whose steps read them: inline `mthds_contents` or a method
-     * bundle (`files` / `bundle_b64`), or a hosted `method_id` the platform resolves. Beside a
-     * `method_ref` (whose files are its package's own), or with no source at all, they are
-     * rejected client-side, mirroring the server's `422`. A key that cannot name a file inside
-     * the bundle (absolute, a `..` segment, a backslash, a colon) is rejected client-side too.
-     * An absent, `null` or empty map is not sent.
-     */
-    resources?: BundleResources | null;
 }
 /**
  * The hosted API's own run arguments — the layer-3 extensions this client adds
@@ -88,14 +65,14 @@ export interface PipelexHostedRunExtensions {
      *   for a version never published; `mt_…@draft` runs the draft. The suffix
      *   rides the string untouched, any other suffix is a `422`, and the answer's
      *   `method_version` says which version runs.
-     * - **Alongside an inline source** (`mthds_contents` / `files` / `bundle_b64`)
-     *   — the inline source is what RUNS (precedence), and the id is recorded as
+     * - **Alongside the method's tree** (`directory`, `contents`, `tree` or `files`)
+     *   — the tree is what RUNS (precedence), and the id is recorded as
      *   **run-history linkage** on the Run row. That linkage is what writes the
      *   index key `GET /v1/runs?method_id=` queries, so a run started without it
      *   is absent from its method's history permanently. The id must be bare
-     *   there: the inline source is what runs, so a suffix would claim a version
-     *   that did not, and a suffixed id is rejected client-side (a `422` on the
-     *   hosted API).
+     *   there: the tree is what runs, so a suffix would claim a version that did
+     *   not, and a suffixed id is rejected client-side (a `422` on the hosted
+     *   API).
      * - **Alongside `method_ref`** — rejected client-side (and a 422 on the
      *   hosted API): an address run carries its own provenance, so it takes no
      *   linkage id.
@@ -104,8 +81,21 @@ export interface PipelexHostedRunExtensions {
      */
     method_id?: string | null;
 }
-/** `execute()` options — the protocol's run arguments plus the Pipelex API and hosted extensions. */
-export type PipelexRunOptions = RunOptions & PipelexApiRunExtensions & PipelexHostedRunExtensions;
+/**
+ * `execute()` options — the protocol's run arguments, the method's tree in any of the four forms
+ * of `MethodTreeForms` (the protocol's `files` and `tree`, and this client's `directory` and
+ * `contents`), and the Pipelex API and hosted extensions.
+ *
+ * The tree is given in at most one form. `files` is sent as given; a `directory`, `contents` or
+ * `tree` is sent as the `files` map, inline when its inline map weighs 256 KiB or less and no more
+ * than the inline limit the API announces, or whatever its weight when the API keeps no blob store,
+ * and otherwise every file by hash, after uploading the files the API lacks (see
+ * `docs/method-trees.md`). A `directory` is listed by the `mthds` package's lister under the
+ * MTHDS standard's membership rule, so a run's inputs file (`inputs.json`, `inputs.toml`) never
+ * travels with the method. A `files` map, a `tree` or `contents` holding no file is refused, as
+ * the standard refuses a tree holding no file; an empty `directory` is absent.
+ */
+export type PipelexRunOptions = RunOptions & MethodTreeForms & PipelexApiRunExtensions & PipelexHostedRunExtensions;
 /**
  * What a run start sends beside its body: the request's own headers, which no run argument
  * reaches. Each is camelCase, since none of them is a wire field of the run request.
@@ -136,52 +126,32 @@ export interface PipelexStartRequestOptions {
  * `start()` / `startAndWaitForResult()` options — the same, for the durable path, plus the start
  * request's own `idempotencyKey`.
  */
-export type PipelexStartOptions = StartOptions & PipelexApiRunExtensions & PipelexHostedRunExtensions & PipelexStartRequestOptions;
+export type PipelexStartOptions = StartOptions & MethodTreeForms & PipelexApiRunExtensions & PipelexHostedRunExtensions & PipelexStartRequestOptions;
 /**
- * The method selector `validate()` takes in place of inline contents — declared
- * beside the other wire shapes in `./models.js` and re-exported here, the import
+ * The method selector `validate()` takes in place of the method's tree, and the whole of what it
+ * takes — declared beside the other wire shapes in `./models.js` and re-exported here, the import
  * path consumers have always used.
  */
-export type { ValidateMethodSelector };
-export interface ValidateFilesOptions {
-    /** Whether unresolved pipe signatures are accepted as pending instead of invalid. */
-    allowSignatures?: boolean;
-    /** Optional validate presentation hints, e.g. ["markdown"]. */
-    render?: string[];
-    /** Optional structured-view opt-in tokens, e.g. ["input_form", "output_form"]; sent only when given. */
-    views?: string[];
+export type { PipelexValidateSource, ValidateMethodSelector };
+/** `validate()`'s last argument: the presentation it asks for, and the call's own transport. */
+export interface ValidateOptions {
     /**
-     * The files the bundle's steps read, such as a `PipeDocGen` step's `template_file`, keyed by
-     * the path the step names, each as its bytes; sent as `resources` (see {@link ValidateOptions}).
+     * Validate presentation hints, a list of view-format tokens. The client always adds
+     * `"markdown"`, so both arms carry `rendered_markdown`.
      */
-    resources?: BundleResources | null;
+    render?: string[];
+    /** Structured-view opt-in tokens, e.g. `["input_form", "output_form"]`; sent only when given. */
+    views?: string[];
     /**
      * Per-call request ceiling; defaults to the 20-min execute ceiling. A positive number
      * no larger than 2147483647, the longest delay a timer honours, else a `RangeError`.
      */
     timeoutMs?: number;
-    /** Caller-driven cancellation; the abort reason propagates untouched. */
-    signal?: AbortSignal;
-}
-/** `validate()`'s last argument: what rides beside the method, and the call's own transport. */
-export interface ValidateOptions {
     /**
-     * The files the bundle's steps read, such as a `PipeDocGen` step's `template_file`, keyed by
-     * the path the step names (`templates/invoice.docx`), each as its bytes (a `Uint8Array`, a
-     * Node `Buffer` included, an `ArrayBuffer` or a `Blob`). Sent as the wire's `resources`, each
-     * file in standard base64; see `docs/bundle-resources.md`. They accompany inline contents, or
-     * a hosted `{ method_id }` the platform resolves; beside a `{ method_ref }` they are rejected
-     * client-side, mirroring the server's `422`. A step whose template file was not sent makes the
-     * verdict invalid, saying so; the dry run checks an office template file it was sent and adds
-     * its findings to the valid arm's `warnings` (`template_check_warning`).
+     * Caller-driven cancellation; the abort reason propagates untouched. It is also read between
+     * the steps a `directory`, `contents` or `tree` costs before the request (the listing, each
+     * read, the version handshake, the blob route and each upload).
      */
-    resources?: BundleResources | null;
-    /**
-     * Per-call request ceiling; defaults to the 20-min execute ceiling. A positive number
-     * no larger than 2147483647, the longest delay a timer honours, else a `RangeError`.
-     */
-    timeoutMs?: number;
-    /** Caller-driven cancellation; the abort reason propagates untouched. */
     signal?: AbortSignal;
 }
 export interface PipelexApiClientOptions {
@@ -230,11 +200,13 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
     /** Cached `/v1/version` handshake outcome — whether the durable lifecycle is served. */
     private lifecycleAvailable;
     /**
-     * The first `/v1/version` handshake that answered, kept for the client's lifetime: what a save
-     * reads from it (`blob_store`) and the tree limits it announces do not change while a client
-     * lives. A handshake that failed is not kept, so the next call asks again.
+     * The last `/v1/version` handshake that answered and when it was asked, kept for
+     * `HANDSHAKE_TTL_MS` as `mthds`'s `MthdsApiClient` keeps it: what sending a tree reads from it
+     * (`blob_store`, the tree limits) changes only with a deploy. A handshake that failed is not
+     * kept, so the next call asks again, and a refusal showing it stale drops it sooner
+     * (`forgetHandshake`).
      */
-    private versionInfo;
+    private versionCache;
     /** The client's request ceiling (`PipelexApiClientOptions.requestTimeoutMs`). */
     private readonly requestTimeoutMs;
     /**
@@ -424,8 +396,21 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      *
      * The answer is read with `parseExactJson`, so an integer past `Number.MAX_SAFE_INTEGER` in the
      * working memory, the main output included, is a `bigint` holding its exact digits.
+     *
+     * The method's tree, given as a `directory`, `contents` or `tree`, is prepared before the
+     * request: listed, read, and sent inline or by hash after uploading the files the API lacks (see
+     * `PipelexRunOptions`). A tree this client refuses (two forms, no file, a directory it cannot
+     * list) is a `RequestArgumentError`, and a file that fails to upload a `MethodFileTransferError`,
+     * each before the run is asked.
      */
     execute(options: PipelexRunOptions): Promise<PipelexExecuteResult>;
+    /**
+     * `execute`, stopped by `signal` before each step of the tree's preparation and right before the
+     * request is sent, never during it, since a request sent may have started a run. `sending` is
+     * the tree already prepared, which the blocking fallback of `startAndWaitForResult` sends as the
+     * start sent it rather than preparing it again.
+     */
+    private executeRun;
     /**
      * Start a method asynchronously — `POST /v1/start` (202, no output yet).
      *
@@ -445,33 +430,51 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `runMayHaveStarted` is true can be retried unchanged (see
      * `PipelexStartRequestOptions`). A malformed key is a `RequestArgumentError`
      * before anything is sent.
+     *
+     * The method's tree is prepared before the request as `execute` prepares it. The prepared body
+     * is the same for the same tree, so a start retried under its idempotency key sends the body the
+     * key was bound to. A start whose hash entries name a blob the API does not hold yet is refused
+     * with a `422` `missing_blobs`, which releases its key: send it again unchanged, which asks the
+     * blob route and uploads what is missing first.
      */
     start(options: PipelexStartOptions): Promise<PipelexRunResultStart>;
     /**
-     * Parse, validate, and dry-run an MTHDS bundle — `POST /v1/validate`.
+     * `start`, stopped by `signal` as `executeRun` is, `sending` being the tree already prepared.
+     */
+    private startRun;
+    /**
+     * Parse, validate, and dry-run a method — `POST /v1/validate`.
      *
      * `/validate` is a diagnostic endpoint: every produced verdict rides a **200**,
      * discriminated on `is_valid`. This returns the `PipelexValidationResult` union
      * verbatim — `is_valid: true` ⇒ the typed `PipelexValidationReport` (structural
      * artifacts), `is_valid: false` ⇒ a `PipelexInvalidReport` (`validation_errors[]`).
-     * An invalid bundle is NOT thrown — the caller pattern-matches `is_valid`. Only a
-     * *no-verdict* condition (a malformed request, an `mthds_sources` length mismatch,
-     * auth, a server fault) is non-2xx and surfaces as `ApiResponseError`.
-     *
-     * `source` selects WHAT is validated, in exactly one of three forms — the
-     * strict tooling XOR (the routes are stateless, so there is no linkage
-     * exception; a second selector is a request-shape `422`):
-     *
-     * - **inline contents** (a `string[]`) — the protocol's own envelope;
+     * An invalid method is NOT thrown — the caller pattern-matches `is_valid`. Only a
+     * *no-verdict* condition (a malformed request, a tree the route refuses, auth, a
+     * server fault) is non-2xx and surfaces as `ApiResponseError`.
+     *
+     * `source` names WHAT is validated, in exactly one form — the strict tooling XOR
+     * (the routes are stateless, so there is no linkage exception; a second selector
+     * is a request-shape `422`, refused here first with a `RequestArgumentError`):
+     *
+     * - **the method's tree**, in one of the four forms of `MethodTreeForms`: a
+     *   `directory` the `mthds` package's lister lists under the standard's
+     *   membership rule (Node only), `contents` by tree path, a listed `tree`, or the
+     *   protocol's `files` map, sent as given. A `directory`, `contents` or `tree` is
+     *   sent as the `files` map, inline or by hash, exactly as a run sends it (see
+     *   `PipelexRunOptions`). Every `.mthds` file of the tree is judged, named by its
+     *   tree path in the diagnostics' `source`, and every other file is one a step may
+     *   read, such as a `PipeDocGen` step's template file, whose template check's
+     *   findings ride the valid arm's `warnings`;
      * - **`{ method_ref }`** — a published method's address, resolved by the
      *   server (pipelex-api >= 0.21.0) through the same fetch path as a
-     *   `method_ref` run, the package's real file names feeding the diagnostics'
+     *   `method_ref` run, the package's real tree paths feeding the diagnostics'
      *   source labels;
      * - **`{ method_id }`** — a stored method's catalog id, hosted-only: the
-     *   platform resolves the version it names and injects that version's `.mthds`
-     *   files before the runner sees the request (a bare runner rejects the request
-     *   as carrying no source it understands). A bare `mt_…` validates the latest
-     *   published version, `mt_…@<n>` version `n` and `mt_…@draft` the draft.
+     *   platform resolves the version it names and sends that version's tree to the
+     *   runner (a bare runner rejects the request as carrying no source it
+     *   understands). A bare `mt_…` validates the latest published version,
+     *   `mt_…@<n>` version `n` and `mt_…@draft` the draft.
      *
      * A selector-resolution failure (fetch failure, no package at the address, an
      * unknown or foreign-org id, a bare id of a method never published, `409`
@@ -480,40 +483,23 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `ApiResponseError` — never an `is_valid: false` verdict, which is reserved
      * for actual MTHDS content.
      *
-     * `mthdsSources` (optional, parallel to inline contents) names each submitted
-     * content — a Pipelex-API extension threaded onto `blueprint.source`, so
-     * cross-file diagnostics name the owning file (an unnamed content yields
-     * `source: null`). The server 422s a length mismatch; this client sends the
-     * arrays verbatim and surfaces that as an `ApiResponseError`. It is an
-     * inline-contents companion only: a `method_ref` / `method_id` validation gets
-     * its source labels from the package's (or the stored method's) real file
-     * names, so supplying it beside a selector is rejected client-side.
-     *
-     * `render` is the Pipelex-API presentation hint — a list of view-format tokens.
-     * This client always asks for Markdown so both valid results and produced
-     * validation-error verdicts carry `rendered_markdown`; callers may add more
-     * tokens. Unknown tokens are server-side lenient-ignored (never a 422).
-     *
-     * `views` is the sibling opt-in for *structured* views where `render` carries
-     * *rendered text*. The two lists are independent, each resolving its own tokens
-     * against its own supported set, and each supported token adds a same-named
-     * top-level field to the valid arm — `input_form` and `output_form`. Unlike `render`,
-     * this client sends `views` ONLY when the caller asks: the point of an opt-in view
-     * is that the default response stays byte-identical, and the highest-frequency
-     * consumers (hook pipelines, CI gates, agent loops) never pay for bytes they
-     * discard. `pipelex-api` gates `input_form` on this token as of 0.18.0; a 0.17.0
-     * runner resolved no token (the key is silently ignored, never a 422) and emitted
-     * the field regardless — which is why `PipelexValidationReport.input_form` is typed
-     * optional rather than required.
-     *
-     * `options.resources` sends the files the bundle's steps read, such as a
-     * `PipeDocGen` step's `template_file`, keyed by the path the step names, each as
-     * its bytes (see {@link ValidateOptions}). A step whose template file was not sent
-     * is an `is_valid: false` verdict saying so, and a template check's findings in an
-     * office template file ride the valid arm's `warnings`. A key no step names, or
-     * files over the server's limits, are no-verdict refusals: a `422`
-     * `BundleResourceNotNamedError`, a `413` `PayloadTooLarge` or
-     * `BundleResourcesTooLargeError`.
+     * `allowSignatures` tolerates unimplemented pipe signatures, as the protocol's
+     * `validate(source, allowSignatures)` does: they surface as `pending_signatures`
+     * and `is_runnable`, never as an error.
+     *
+     * `options.render` is the Pipelex-API presentation hint — a list of view-format
+     * tokens. This client always asks for Markdown so both valid results and produced
+     * validation-error verdicts carry `rendered_markdown`; callers may add more tokens.
+     * Unknown tokens are server-side lenient-ignored (never a 422).
+     *
+     * `options.views` is the sibling opt-in for *structured* views where `render`
+     * carries *rendered text*. The two lists are independent, each resolving its own
+     * tokens against its own supported set, and each supported token adds a same-named
+     * top-level field to the valid arm — `input_form` and `output_form`. Unlike
+     * `render`, this client sends `views` ONLY when the caller asks: the point of an
+     * opt-in view is that the default response stays byte-identical, and the
+     * highest-frequency consumers (hook pipelines, CI gates, agent loops) never pay for
+     * bytes they discard.
      *
      * A `{ method_ref }` source makes the server clone a repository before it
      * validates anything, and it needs no special budget here: this route already
@@ -523,16 +509,7 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * exists to RAISE routes whose default is the ~30s poll ceiling; applying it here
      * would lower this one.
      */
-    validate(source: string[] | ValidateMethodSelector, allowSignatures?: boolean, mthdsSources?: string[], render?: string[], views?: string[], options?: ValidateOptions): Promise<PipelexValidationResult>;
-    /**
-     * Validate paired MTHDS files while preserving URI attribution for diagnostics.
-     *
-     * This adapter intentionally keeps the low-level `validate(...)` payload shape
-     * intact for existing consumers. When any file has a URI, every content gets a
-     * parallel source label; inline labels are deterministic so the server never
-     * sees a length-mismatched `mthds_sources` array.
-     */
-    validateFiles(files: MthdsFile[], options?: ValidateFilesOptions): Promise<PipelexValidationResult>;
+    validate(source: PipelexValidateSource, allowSignatures?: boolean, options?: ValidateOptions): Promise<PipelexValidationResult>;
     /**
      * Lint one `.mthds` file against the embedded MTHDS schema — `POST /v1/lint`.
      *
@@ -574,11 +551,10 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * never on a message.
      *
      * All of these are static and inference-free, so they default to the management-call
-     * timeout. The internal raises are `crateRequestTimeoutMs`'s: the fetch-sized budget a
+     * timeout. The internal raise is `crateRequestTimeoutMs`'s: the fetch-sized budget a
      * crate route gets when its closure is a `method_ref`, because the server may clone a
-     * repository before it answers, and the execute ceiling it gets when the request
-     * carries `resources`, whose upload alone can outlast the default. Each is matched to
-     * what the request costs, not a caller-facing parameter.
+     * repository before it answers. It is matched to what the request costs, not a
+     * caller-facing parameter.
      *
      * **These routes deliberately expose no `timeoutMs` / `signal`, and that is not an
      * oversight to be "fixed" per route.** Automated reviewers have proposed adding them
@@ -589,11 +565,11 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      *    ceiling and takes caller transport options; every extension route rides the
      *    static core. Giving one static route an override while its siblings lack one is
      *    the inconsistency.
-     * 2. The input is **bounded server-side** — the runner's `pipelex_api/limits.py` caps the
-     *    `.mthds` files of a request and the files sent with them in `resources`, each by a
-     *    count, a size per file and, for `resources`, a total, all configurable per
-     *    deployment — and none of these routes runs inference. The upload those limits allow
-     *    is what `crateRequestTimeoutMs` budgets for, not the server's work.
+     * 2. The input is **bounded server-side** — the deployment caps a request's tree by its
+     *    count of files, a size per file, a total and the bytes it carries inline, all
+     *    announced by its `/v1/version` handshake — and none of these routes runs inference.
+     *    The upload those limits allow is what `crateRequestTimeoutMs` budgets for, not the
+     *    server's work.
      * 3. On the hosted path an override would be **inert**: the gateway caps responses at
      *    ~30s (see `POLL_REQUEST_TIMEOUT_MS` above), so raising `timeoutMs` would still be
      *    cut off upstream, just with a less honest error.
@@ -601,6 +577,12 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * If a static route ever genuinely needs longer, give the WHOLE static family one
      * uniform transport-options parameter in a single pass — do not bolt it onto one
      * route.
+     *
+     * The one exception is the crate family's `signal` (`CrateRouteOptions`), given to all three
+     * crate routes at once: a `directory`, `tree` or `contents` can cost the listing, the version
+     * handshake, the blob route and uploads before the request, client-side work a caller such as
+     * `prepareInputs` must be able to stop. It is read between those steps and stops nothing in flight, so it is no
+     * transport option and the reasons above still hold.
      */
     private requestExtension;
     /** The model deck the runner can route to — `GET /v1/models[?type=]`. */
@@ -630,6 +612,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * The handshake for feature detection (hosted extensions or not).
      */
     version(): Promise<VersionInfo>;
+    /** `GET /v1/version`, as `version` asks it, stopped by `signal`. */
+    private requestVersion;
     /**
      * Resolve a closure into its normalized library crate — `POST /v1/resolve`.
      *
@@ -648,12 +632,22 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * (fetch failure, no package at the address, an unknown or foreign-org id) is
      * non-2xx too — never an `is_valid: false` verdict.
      *
-     * The closure arrives in exactly one of three forms: inline `files`, an
-     * address-form `method_ref` (server-resolved, pipelex-api >= 0.21.0; the
-     * registry form stays a `501`), or a hosted `method_id` (platform-resolved —
-     * see {@link PipelexHostedToolingExtensions}).
+     * The closure arrives in exactly one of three forms: the method's tree, as the
+     * protocol's `files` map or as a `directory`, `tree` or `contents` the client sends
+     * inline when small and by hash otherwise (see {@link CrateRequestBase}); an
+     * address-form `method_ref` (server-resolved, pipelex-api >= 0.21.0; the registry form
+     * stays a `501`); or a hosted `method_id` (platform-resolved — see
+     * {@link PipelexHostedToolingExtensions}). An empty map or string is absent.
+     *
+     * `options.signal` stops the call between the steps a `directory`, `tree` or `contents`
+     * costs before the request — the listing, the version handshake, the blob route, each
+     * read and upload of a missing blob — and before the request itself, throwing the
+     * abort; a request already sent runs to its end. A blob that fails to upload throws
+     * `MethodFileTransferError`, and a tree this client refuses to send (no file, two
+     * forms, a directory it cannot list, a `contents` value that is neither text nor
+     * bytes) `RequestArgumentError`, each before the route is asked.
      */
-    resolve(request: ResolveRequest): Promise<ResolveResponse>;
+    resolve(request: ResolveRequest, options?: CrateRouteOptions): Promise<ResolveResponse>;
     /**
      * Project a closure's crate into stamped typed artifacts — `POST /v1/codegen`.
      *
@@ -669,7 +663,7 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * unknown `kind`/`target`, a `pipe_ref` on the concept-set-wide `types` kind, or
      * a malformed selector is a 422; a registry-form `method_ref` is a `501`.
      */
-    codegen(request: CodegenRequest): Promise<CodegenResponse>;
+    codegen(request: CodegenRequest, options?: CrateRouteOptions): Promise<CodegenResponse>;
     /**
      * Read a method's three I/O artifacts — `POST /v1/pipe-io`.
      *
@@ -681,19 +675,20 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * dry-runs every pipe; a caller that shows a method, prepares its inputs or generates
      * types for it reads this, and one that needs the dry-run verdict stays on `validate`.
      *
-     * Selection: the request's qualified `pipe_ref`, else a fetched package's manifest
-     * `main_pipe`, else the closure's single `main_pipe` declaration. `all_pipes: true`
-     * describes every pipe instead, and never refuses for want of an entry pipe.
-     * `include_files: true` echoes the resolved closure's `.mthds` files as `files`.
+     * Selection: the request's qualified `pipe_ref`, else the `main_pipe` of the
+     * `METHODS.toml` at the tree's root, sent in the tree or fetched with a package, else the
+     * closure's single `main_pipe` declaration. `all_pipes: true` describes every pipe
+     * instead, and never refuses for want of an entry pipe. `include_files: true` echoes the
+     * method's own `.mthds` bundles as `files`, a map from tree path to each bundle's text,
+     * in the shape of the request's `files` map.
      *
-     * Beside inline `files`, `resources` sends the files the closure's steps read, such as a
-     * `PipeDocGen` step's `template_file`, keyed by the path the step names, each as its bytes;
-     * a step whose template file was not sent makes the closure invalid. `resolve` and `codegen`
-     * take it too (see {@link CrateRequestBase}).
+     * The files the closure's steps read, such as a `PipeDocGen` step's `template_file`, are
+     * files of the method's tree like any other; a step whose template file is not in the tree
+     * makes the closure invalid (see {@link CrateRequestBase}).
      *
-     * Same 200-verdict discipline and same three-form closure selector as {@link resolve}
-     * (the request is posted as given, its `resources` encoded to base64, and the selector XOR
-     * and the `resources` pairing are the server's to enforce).
+     * Same 200-verdict discipline, same three-form closure selector and same `options` as
+     * {@link resolve} (the request's members are posted as given, its `directory`, `tree` or
+     * `contents` as the `files` map, and the selector XOR is the server's to enforce).
      * Only a no-verdict condition throws `ApiResponseError`: a malformed selector and an
      * over-limit file are `ValidationError` `422`s; a selection the route refuses is a
      * `422` whose `errorType` is `EntryPipeNotFoundError` (an unknown `pipe_ref`, no entry
@@ -701,13 +696,35 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * candidates in its `serverMessage`; a registry-form `method_ref` is a `501`; a pipe
      * whose artifacts cannot be derived is a `500`.
      *
-     * A `method_ref` gets the fetch-sized budget, as on the other crate routes, and a
-     * request carrying `resources` the execute ceiling, since their upload alone can
-     * outlast the default. On the hosted API the gateway caps a request at about 30
-     * seconds whatever the client allows, so a cold `method_ref` clone can answer a `502`
-     * that a retry clears once the runner has cached the clone.
+     * A `method_ref` gets the fetch-sized budget, as on the other crate routes. On the
+     * hosted API the gateway caps a request at about 30 seconds whatever the client allows,
+     * so a cold `method_ref` clone can answer a `502` that a retry clears once the runner
+     * has cached the clone.
+     */
+    pipeIo(request: PipeIORequest, options?: CrateRouteOptions): Promise<PipeIOResponse>;
+    /**
+     * Post a crate request: its members as given, and its tree as the `files` map a save would
+     * send, each key left off when there is nothing to send. An empty map or string is absent, as in
+     * the Python SDK: `files: {}` or `null`, `contents: {}`, `directory: ""` and `dependencies: {}`
+     * are not sent, so an empty one never reaches the wire as a second selector; a `directory` that
+     * is not a string is refused, as on a run. A `directory`, `tree` or `contents` is prepared
+     * through the path every request and save sends a tree by (`postMethodRequest`), inline when
+     * small and by hash otherwise, uploading the files the API lacks first; the blob route is asked
+     * under the request's `read_scope`, the scope its hash entries are read in. `signal` is read
+     * before each step and right before the request (see `TreeSendOptions`). The request gets the
+     * budget `crateRequestTimeoutMs` gives it for the `files` it carries.
      */
-    pipeIo(request: PipeIORequest): Promise<PipeIOResponse>;
+    private crateRequest;
+    /**
+     * The request budget for a crate route's closure (`resolve`, `codegen`, `pipeIo`): the
+     * static-route default, unless the closure is a `method_ref`, which may make the server clone a
+     * repository first and gets the fetch-sized budget, or its `files` carry more inline than
+     * `INLINE_TREE_MAX_BYTES`, which gets the client's request ceiling (`requestTimeoutMs`): a tree
+     * sent to an API keeping no blob store travels inline whatever its weight, and so does a `files`
+     * map given as is, and the upload of the body is charged against the budget. A tree sent by
+     * hash keeps the default, its files uploaded before the request under the client's own ceiling.
+     */
+    private crateRequestTimeoutMs;
     /**
      * Fetch a run's status by bare id — `GET /v1/runs/{pipeline_run_id}/status`.
      *
@@ -798,6 +815,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * gzip stream, which `requestRaw` reports as an `ApiUnreachableError` carrying
      * the decompressor's code (see `isUndecodableBody`).
      *
+     * `signal` stops the handshake: its abort is thrown as is and nothing is cached.
+     *
      * @throws {ApiUnreachableError} The handshake got no answer. Nothing is cached,
      *   so the next call asks again, and no start is sent to a host that did not
      *   answer: sending it would wait a second time for the same silence.
@@ -818,9 +837,15 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * run, so the caller knows until then that none exists (see
      * `StartAndWaitForResultOptions`).
      *
-     * `pollOptions.signal` is also read before the run is created: a caller that aborts while the
-     * version handshake is in flight gets its abort, and neither the start nor the blocking execute
-     * is sent. Once one of them is sent, the abort stops only the wait.
+     * `pollOptions.signal` also stops everything before the run is created: the version handshake,
+     * the listing of a `directory`, and the reads, the blob route and the uploads of a tree sent by
+     * hash, each of them stopped in flight. It is read again right before the start and before the
+     * blocking execute, so a caller that aborts before then gets its abort and no run is created.
+     * Once one of them is sent, the abort stops only the wait.
+     *
+     * The method's tree is prepared once, before the start: when a runner turns out to lack the
+     * durable routes, the blocking execute sends the same `files` map, its blobs already uploaded,
+     * rather than listing, reading and hashing the tree again.
      *
      * An error from the start, or from the blocking execute, says whether that request may still
      * have started a run whose id never reached the caller (`runMayHaveStarted`); when it may have,
@@ -836,6 +861,12 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * malformed key is refused before the version handshake.
      */
     startAndWaitForResult(options: PipelexStartOptions, pollOptions?: StartAndWaitForResultOptions): Promise<RunResults>;
+    /**
+     * A run's tree prepared once for `startAndWaitForResult`, under `call`'s refusals: the run's
+     * arguments checked, the tree listed or read, and its `files` prepared, uploads included, under
+     * `signal`. A `files` map given as is, or no tree, needs no preparation.
+     */
+    private prepareRunTree;
     /** The authenticated user's profile — `GET /v1/me`. */
     getMe(): Promise<UserProfile>;
     /**
@@ -927,13 +958,6 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * room for a publish.
      */
     createMethod(input: MethodWriteInput): Promise<MethodData>;
-    /**
-     * The time limit of a save carrying `files`: the client's request ceiling, as for a `start`
-     * carrying its method, since a tree sent inline to a deployment with no blob store has no size
-     * bound and its whole upload is charged against the limit; the poll timeout for a save sending
-     * no tree.
-     */
-    private saveTimeout;
     /**
      * Replace a method's draft — `PUT /v1/methods/{id}/draft` — and return the method with the
      * draft's new token (`updated_at`) and digest (`draft_digest`).
@@ -957,11 +981,26 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * when the method kept changing under the write.
      */
     writeDraft(methodId: string, input: MethodDraftInput): Promise<MethodData>;
+    /**
+     * Send a save carrying a method's tree (`createMethod`, `writeDraft`) through the path every
+     * request sends a tree by (`postMethodRequest`), its body built by `bodyOf` from the `files`
+     * prepared, under `saveTimeoutMs`, and read the stored method it answers as
+     * `requestMethodData` reads it.
+     */
+    private saveMethodTree;
+    /**
+     * The time limit of a save carrying `files`: the client's request ceiling, as for a `start`
+     * carrying its method, since a tree sent inline to a deployment with no blob store weighs up to
+     * its `max_inline_bytes`, a `files` map given as is whatever it weighs, and the whole upload is
+     * charged against the limit; the poll timeout for a save sending no tree.
+     */
+    private saveTimeoutMs;
     /**
      * The limits the deployment holds a method's tree to — `GET /v1/version`, read from
      * `limits.method_tree` of the public handshake — in the shape the `mthds` package's
      * `listMethodTree` takes as its `limits` option, so a tree the platform would refuse is refused
-     * while it is listed, before any file is hashed:
+     * while it is listed, before any file is hashed. A `directory` given to any route is listed under
+     * them already; they serve a caller listing a tree of its own:
      *
      * ```ts
      * import { listMethodTree } from "mthds";
@@ -971,14 +1010,18 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      *
      * A limit the server does not announce is absent, so a bare runner, which announces none,
      * yields no limit, and none is ever assumed. A value that is not a positive integer is left out
-     * rather than trusted.
+     * rather than trusted. The inline limit, `max_inline_bytes`, is no listing limit: the client
+     * applies it itself when it chooses how a tree travels.
      */
     methodTreeLimits(): Promise<MethodTreeLimits>;
     /**
-     * The version handshake, asked once per client: the first answer is kept (see `versionInfo`),
-     * and a failure is thrown and not kept, so the next call asks again.
+     * The version handshake, asked once per `HANDSHAKE_TTL_MS`: an answer is kept that long (see
+     * `versionCache`), and a failure is thrown and not kept, so the next call asks again. `signal`
+     * stops the ask, its abort thrown as is.
      */
     private cachedVersion;
+    /** Drop the kept handshake, which a refusal has shown to be stale. */
+    private forgetHandshake;
     /**
      * Write a saved method's tree to disk: each file of a listing `getMethod` or `getMethodVersion`
      * served, at its tree path under `options.destination`. **Node only.**
@@ -1004,29 +1047,84 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
         destination: string;
     }): Promise<void>;
     /**
-     * The `files` a save sends: `files` as given, or `tree` or `contents` prepared, uploading what
-     * the organization lacks; `undefined` when the input gives none. Two forms are refused with
-     * `RequestArgumentError` before any request, naming `call`.
-     */
-    private methodTreeFiles;
-    /**
-     * The `files` map that sends `tree`: inline, or by hash once the organization holds every file.
-     *
-     * A tree whose inline map weighs `INLINE_TREE_MAX_BYTES` or less travels inline, with no round
-     * trip, measured as the request spends it, its JSON with no whitespace in UTF-8. A larger tree
-     * travels inline too when the version handshake declares no blob store; otherwise
-     * `POST /v1/blobs/missing` is asked which files the organization lacks, naming the tree's
-     * digest, each one it lacks is uploaded once, and every file travels by hash. A file read to be
-     * measured is uploaded from memory rather than read a second time. A tree holding no file is
-     * refused with `RequestArgumentError` before any request, `call` naming the caller's method.
-     */
-    private prepareTreeFiles;
+     * The method's tree a call was given, made ready to prepare: a `directory` listed, `contents`
+     * turned into a tree, a `tree` checked, `files` kept as given; `undefined` when the input gives
+     * none. Two forms are refused with `RequestArgumentError` before any request, naming `call`, and
+     * so are a `directory` that is not a string and a `tree` that is not a listed tree. A
+     * `directory` is listed by the `mthds` package's lister under the limits the deployment
+     * announces, so a tree past one is refused while it is listed, before any file is hashed; the
+     * handshake that announces them is asked under `signal`. It is listed once per call: a request
+     * sent again sends the tree this listing read.
+     */
+    private treeToSend;
+    /**
+     * Post a request carrying a method's tree, by `mthds`'s `MthdsApiClient` rule: prepare the
+     * tree's `files` (`prepareFiles`), hand them to `post`, which builds the body and sends it, and
+     * answer the two refusals that call for sending the same request once more, as `mthds` does.
+     *
+     * - A `422` coded `request.blobs_missing` whose `missing_blobs` the tree sent by hash holds, such
+     *   as a blob dropped since the check: the blob route is asked again for those, they are
+     *   uploaded, and the request is sent once more (`postWithBlobRetry`).
+     * - A `422` refusing a tree the client prepared as past one of the receiver's limits
+     *   (`isMethodTreeTooLarge`): the handshake that announced the limits may be stale, so it is
+     *   forgotten, and the tree prepared again on a fresh one and sent once more. A `files` map
+     *   given as is was not prepared, so it is never sent again; nor is a request whose
+     *   `options.retryTooLarge` is `false`, a start under an idempotency key, which the platform
+     *   binds to the refusal it stores.
+     *
+     * A `422` created nothing, so the request sent again is no repeat of one whose outcome is
+     * unknown. `initial`, when given, is the tree already prepared for the first send, with the
+     * bytes it read, so a caller sending one tree on two routes prepares it once. `options.signal`
+     * is read before each step of the preparation and before each send. Answers the last answer
+     * whole, its status unread, with the `files` it carried.
+     */
+    private postMethodRequest;
+    /**
+     * Send a request whose tree may have travelled by hash. When it did and the receiver answers a
+     * `422` coded `request.blobs_missing` whose `missing_blobs` the tree holds, the client asks the
+     * blob route where to upload them, uploads them and sends the same request once more, which the
+     * refusal left uncreated; any other answer, or a list naming a blob the tree does not hold, is
+     * answered as it came.
+     */
+    private postWithBlobRetry;
+    /**
+     * The `files` a request or a save sends for `source`: a `files` map as given, a tree prepared
+     * (`prepareTree`), or none.
+     */
+    private prepareFiles;
+    /**
+     * The `files` map that sends `tree`: inline, or by hash once the receiver holds every file —
+     * `mthds`'s `MthdsApiClient` rule, read from the version handshake the client keeps.
+     *
+     * When the handshake declares a blob store, a tree whose inline map weighs no more than the
+     * inline threshold travels inline, measured as the request spends it, its JSON with no
+     * whitespace in UTF-8; the threshold is the lower of 256 KiB (`INLINE_TREE_MAX_BYTES`) and the
+     * `max_inline_bytes` the handshake announces, and a tree whose files alone pass it is not read
+     * to be weighed. A heavier tree travels by hash: `POST /v1/blobs/missing` is asked which files
+     * the receiver lacks, naming the tree's digest, each one it lacks is uploaded once, and every
+     * file travels by hash. A `404` from the blob route says the handshake that declared the store
+     * is stale, so it is forgotten and the tree prepared once more on a fresh one. When the
+     * handshake declares no blob store, the whole tree travels inline whatever its weight, held to
+     * the announced `max_inline_bytes` (`inlineWithin`). Each file is read at most once into `read`,
+     * so a file read to be weighed is uploaded from memory. A tree holding no file is refused with
+     * `RequestArgumentError` before any request, `call` naming the caller's method.
+     * `options.readScope` is the scope the blob route is asked under, and `options.signal` is read
+     * before each read, the handshake, the blob route and each upload, and is passed to each of
+     * them, so an abort also stops a request or an upload under way.
+     */
+    private prepareTree;
     /**
      * Which of these blobs the organization lacks, and where to upload each —
      * `POST /v1/blobs/missing` — with the answer it was read from, which carries signed links. A
      * blob held is left out, and an empty `missing` means nothing to upload. An answer whose
      * `missing` is not a list of blobs, each with its upload target, is an answer the SDK cannot
      * read, thrown as an `ApiResponseError` holding the answer with its links hidden.
+     *
+     * `readScope`, a crate request's `read_scope`, is sent as the route's `read_scope` query, the
+     * Pipelex API's extension naming the blob store asked, so the blobs are uploaded into the store
+     * the request's hash entries are read from; each upload target is signed for that scope. The
+     * hosted platform's own route reads the caller's organization instead. `signal` stops the
+     * request, its abort thrown as is.
      */
     private findMissingBlobs;
     /**
@@ -1035,9 +1133,14 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * is the platform's fault, thrown before anything is sent as the `ApiResponseError` of an answer
      * the SDK cannot read. The bytes the tree reads for a blob are checked against it before they
      * are sent, since storage keeps a blob under the hash it is named by: bytes of another hash or
-     * size are refused with `RequestArgumentError`, and nothing more is uploaded.
+     * size are refused with `RequestArgumentError`, and nothing more is uploaded. `userSignal` is
+     * read before each blob's read and before its upload, and reaches each upload under way: once it
+     * has aborted, no further blob is read or sent, the uploads in flight are stopped, and the abort
+     * is thrown rather than a transfer failure.
      */
     private uploadMissing;
+    /** Read, check and upload one missing blob (see `uploadMissing`). */
+    private uploadOne;
     /**
      * Rename a method — `PATCH /v1/methods/{id}` — and return it. The name belongs to the method,
      * not to a version: a rename changes nothing else, moves no token, and never commits the
@@ -1386,8 +1489,9 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * Name the method exactly one of three ways, all server-resolved through the
      * one `pipeIo` call this composes:
      *
-     * - `files` — the inline MTHDS closure, with the `resources` its steps read
-     *   (a `PipeDocGen` step's `template_file`), keyed by the path a step names;
+     * - the method's tree — a `directory`, `contents`, a listed `tree` or the `files`
+     *   map, sent as `pipeIo` sends it, with the files its steps read (a `PipeDocGen`
+     *   step's `template_file`) among its files;
      * - `method_ref` — a published method's address, fetched by the runner;
      * - `method_id` — a stored method's catalog id, resolved by the platform
      *   (hosted only; requires an API key).
@@ -1474,9 +1578,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
     /**
      * The whole record for one run — `GET /v1/runs/{id}`.
      *
-     * The ONLY call that returns `mthds_contents` (what the run actually
-     * executed) and `inputs`. Kept off the status read, which pollers hit every
-     * few seconds. A failed run's stored report, `error`, is checked field by
+     * The ONLY call that returns what the run actually executed and its
+     * `inputs`. Kept off the status read, which pollers hit every few seconds. A failed run's stored report, `error`, is checked field by
      * field (see `RunErrorReport`).
      *
      * Read with `parseExactJson`, so an integer past `Number.MAX_SAFE_INTEGER` in the inputs is a
@@ -1486,6 +1589,14 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
     getRunDetail(runId: string): Promise<RunDetail>;
     /** Patch a run's status (admin/manual) — `PUT /v1/runs/{id}`. */
     updateRun(runId: string, input: UpdateRunInput): Promise<void>;
+    /**
+     * A run's arguments checked before anything is listed, read or sent, `call` naming the caller's
+     * method in each refusal: the generic `extra` passthrough, the Pipelex API's and the hosted
+     * API's own selectors, and the method's tree in its forms as the standard checks them; then the
+     * "something to run" precondition, the `method_ref` pairings and the linkage form's bare
+     * `method_id`.
+     */
+    private runParts;
     /**
      * Blocking `POST /v1/execute` adapted onto `RunResults` — the bare-runner
      * path. Forwards every protocol field PLUS every extension surface: the