@pipelex/sdk 0.46.1 → 0.47.0

package/README.md

@@ -42,6 +42,7 @@ See [`docs/cli.md`](./docs/cli.md) for every flag, the output, the exit codes an
 import { PipelexApiClient } from "@pipelex/sdk";
 
 // Base URL + key from PIPELEX_BASE_URL / PIPELEX_API_KEY, or pass them explicitly.
+// `requestTimeoutMs` sets the client's request ceiling, twenty minutes by default.
 const client = new PipelexApiClient({
   baseUrl: "https://api.pipelex.com",
   apiKey: process.env.PIPELEX_API_KEY,
@@ -113,6 +114,7 @@ A reference the runner cannot read at all (blank, a sigil alone, too long) or an
 The hosted management surface (catalog, account, billing) hangs off the same client. Every route maps a non-2xx `problem+json` to a typed `ApiResponseError` (see [Errors](#errors) for how to branch on it):
 
 ```ts
+import { listMethodTree } from "mthds";
 import { PipelexApiClient, ApiResponseError, parseMethodSelector } from "@pipelex/sdk";
 
 const client = new PipelexApiClient({ apiKey: process.env.PIPELEX_API_KEY });
@@ -124,13 +126,16 @@ const drafts = await client.listMethods({ published: false });
 for await (const method of client.iterateMethods()) {
   // follows the cursor for callers that genuinely want the whole catalog
 }
-const created = await client.createMethod({ name: "Greeter", mthds: "domain = 'demo'" });
+// A saved method is a method tree: list one from a directory, under the deployment's limits,
+// and the save sends it inline when small, or by hash after uploading the files it lacks.
+const tree = await listMethodTree("methods/greeter", { limits: await client.methodTreeLimits() });
+const created = await client.createMethod({ name: "Greeter", tree });
 
 // A saved method has a draft, written freely and never validated, and immutable published
-// versions. `updated_at` is the draft's token: echo it so no write or publish takes a draft
-// you have not seen.
+// versions. A draft write replaces the whole tree. `updated_at` is the draft's token: echo it so
+// no write or publish takes a draft you have not seen.
 const draft = await client.writeDraft(created.method_id, {
-  mthds: "domain = 'demo'\n",
+  contents: { "main.mthds": "domain = 'demo'\n" },
   expected_updated_at: created.updated_at,
 });
 const published = await client.publishMethod(created.method_id, {
@@ -140,6 +145,9 @@ if (published.outcome === "refused") console.error(published.message, published.
 else console.log(`version ${published.version.version}`); // "published" or "unchanged"
 const versions = await client.listMethodVersions(created.method_id); // newest first
 const { method_id, version } = parseMethodSelector("mt_abc123@3"); // the method routes take a bare id
+// A read lists the tree's files with short-lived links; write them to disk, checked (Node only).
+const detail = await client.getMethod(created.method_id);
+await client.writeMethodTree(detail.files, { destination: "greeter-draft" });
 
 // A saved example is a named set of inputs with the latest run of exactly those inputs. Record a
 // run against the revision whose inputs it used: an edit since answers `stale`, never an error.
@@ -244,6 +252,7 @@ These pages ship inside the published package, so a reader who has only installe
 | [`docs/artifact-download.md`](./docs/artifact-download.md) | Turning the `pipelex-storage://` references a run produced back into bytes: `locateArtifacts`, `collectArtifacts`, `resolveArtifacts`, `fetchArtifact`, `downloadArtifacts`, and how a saved file is named after the field it fills |
 | [`docs/input-preparation.md`](./docs/input-preparation.md) | The other direction — `uploadFile` and `prepareInputs`, which turn local files into references a run can take, and the upload grant a browser page sends a file with |
 | [`docs/bundle-resources.md`](./docs/bundle-resources.md) | Sending the files a bundle's steps read, such as a `PipeDocGen` step's template, as `resources` beside its `.mthds` contents: where they go, what is refused and by whom, and the template check's warnings |
+| [`docs/method-trees.md`](./docs/method-trees.md) | A saved method's tree: the three forms a save takes it in, how it travels inline or by hash and what is uploaded, the deployment's limits, the read's listing with its links, `writeMethodTree`, and `MethodFileTransferError` |
 | [`docs/method-examples.md`](./docs/method-examples.md) | A method's saved examples: the create, the paged list and its iterator, the edit that raises the input revision, the latest-run write and its `recorded` or `stale` verdict, how an integer past `Number.MAX_SAFE_INTEGER` in the inputs stays exact, and what is refused before sending |
 | [`docs/exact-integers.md`](./docs/exact-integers.md) | Which reads keep an integer past `Number.MAX_SAFE_INTEGER` exact, as a `bigint` (a run's inputs and outputs, an example's inputs), how a request body writes it back with its digits, and `parseExactJson` and `stringifyExactJson` for code showing such data as JSON text |
 | [`docs/crate-routes.md`](./docs/crate-routes.md) | `resolve`, `codegen` and `pipeIo` — the normalized crate, the stamped types, and a method's I/O artifacts without a validation — and the offline `runCodegenCheck` that guards a committed tree |

package/dist/cli/script.d.ts

@@ -15,7 +15,7 @@ import type { CommandIO } from "./io.js";
  * update notice and npm 12's run notices off the script's stderr, which carries the command's
  * own lines, while npm's warnings and errors still print.
  */
-export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.46.1";
+export declare const SCRIPT_RUNNER = "npx --yes --no-update-notifier --loglevel=warn @pipelex/sdk@0.47.0";
 export declare const SCRIPT_WRITER = "@pipelex/sdk";
 export declare const SCRIPT_NEEDS = "Node 22.12 or later";
 /** Run `pipelex-sdk script` and return its exit code. */

package/dist/client.d.ts

@@ -1,7 +1,8 @@
 import type { MTHDSProtocol, ModelCategory, ModelDeck, RunOptions, StartOptions, VersionInfo } from "mthds/protocol";
-import type { CodegenRequest, CodegenResponse, DictPipeOutput, FormatResponse, LintResponse, ModelCheckCategory, ModelReferenceVerdict, MthdsFileItem, PipeIORequest, PipeIOResponse, PipelexRunResultStart, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector } from "./models.js";
+import type { CodegenRequest, CodegenResponse, DictPipeOutput, FormatResponse, LintResponse, ModelCheckCategory, ModelReferenceVerdict, PipeIORequest, PipeIOResponse, PipelexRunResultStart, 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, MethodDraftInput, MethodExample, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunResult, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunPage, PlanView, ResolvedStorageUrl, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.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 { AppInfo } from "./user-agent.js";
 import type { UploadableAsset, UploadFileOptions, UploadRecord } from "./upload.js";
 import type { BundleResources } from "./bundle-resources.js";
@@ -203,6 +204,15 @@ export interface PipelexApiClientOptions {
      * beside the specs' tests.
      */
     appInfo?: AppInfo;
+    /**
+     * The client's request ceiling, in milliseconds: the time limit of a request given no
+     * `timeoutMs` of its own, the blocking `execute`, a `start` carrying its method and a save
+     * carrying a method's tree (`createMethod`, `writeDraft`) among them, and of each transfer of a method's file to or from storage, an upload before a save or a
+     * download by `writeMethodTree`. Defaults to 20 minutes, the runner's blocking execute ceiling.
+     * A positive number no larger than 2147483647, the longest delay a timer honours, else a
+     * `RangeError` at construction.
+     */
+    requestTimeoutMs?: number;
 }
 /** Hosted default — the client composes every endpoint as `{base}/v1/{endpoint}`. */
 export declare const DEFAULT_API_BASE_URL = "https://api.pipelex.com";
@@ -219,6 +229,14 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
     private readonly originUrl;
     /** 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.
+     */
+    private versionInfo;
+    /** The client's request ceiling (`PipelexApiClientOptions.requestTimeoutMs`). */
+    private readonly requestTimeoutMs;
     /**
      * The `User-Agent` sent on every API request, computed once at construction;
      * `undefined` in a browser, where no header may be set.
@@ -262,19 +280,18 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      */
     private requestProductObject;
     /**
-     * A methods-catalog route answering one stored method (`getMethod`, `createMethod`,
-     * `writeDraft`, `renameMethod`), parsed into the public shape by `readStoredSources`.
+     * A methods-catalog route answering one stored method (`createMethod`, `writeDraft`,
+     * `renameMethod`), read as `readObjectAnswer` reads it.
      */
     private requestMethodData;
     /**
-     * The stored sources of a method or of a published version, read from the answer `res`
-     * carried, into the public shape. A stored `mthds` that is neither a string nor absent (`null`
-     * stays "no source", which `getMethodClosure` reports), and a stored `python` the SDK cannot
-     * parse, are an answer it cannot read, so each throws an `ApiResponseError` built from that
-     * answer, the latter with `mthds`'s refusal as `cause`: `runtime`, not retryable, since no
-     * change to the call fixes it. `subject` names what carried them in the message.
+     * A route answering a saved tree's listing beside what names it (`getMethod`,
+     * `getMethodVersion`), read as `readObjectAnswer` reads it, then its `files` checked: a listing
+     * that is not an array of `{ path, sha256, size, url, expires_at }`, each a string but `size`, a
+     * non-negative integer, is an answer the SDK cannot read, since `writeMethodTree` would write
+     * from it. Throws the `ApiResponseError` `unreadableAnswer` builds, `subject` naming the answer.
      */
-    private readStoredSources;
+    private readSavedTree;
     /**
      * A verdict, the `200` a route answers discriminated on `outcome` with the object the verdict
      * is about as one `member`: `publishMethod`'s `method`, `recordMethodExampleLatestRun`'s
@@ -315,7 +332,10 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * member included.
      */
     private readMethodExample;
-    /** Issue a product request and return its 2xx answer, a non-2xx thrown as `ApiResponseError`. */
+    /**
+     * Issue a product request and return its 2xx answer, a non-2xx thrown as `ApiResponseError`.
+     * The request takes the poll timeout unless `options.timeoutMs` gives another.
+     */
     private requestProductAnswer;
     private throwApiResponseError;
     /** The JSON body of a `/v1` route's 2xx answer; see `readAnswerAt`. */
@@ -349,7 +369,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `API <method> <path> answered <status> with <what>`: the answer's status, its raw text as
      * `responseBody`, no hosted problem member but the `X-Request-ID` header, the failure that made it
      * unreadable as `cause`, and the verdict the fallback gives a 2xx, `runtime` and not retryable.
-     * On a request that may create a run, the run may have started: the server accepted it.
+     * An answer that carries signed links (`RawResponse.carriesLinks`) is held with every link
+     * hidden, and with no `cause`, which could quote one. On a request that may create a run, the run may have started: the server accepted it.
      */
     private unreadableAnswer;
     /**
@@ -864,10 +885,13 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      */
     iterateMethods(query?: Omit<ListMethodsQuery, "cursor">): AsyncGenerator<MethodSummary, void, undefined>;
     /**
-     * Read one method — `GET /v1/methods/{id}`: its identity, its draft (`mthds`, `python`,
-     * `input_data`) with the draft's token (`updated_at`) and digest (`draft_digest`), and its
-     * latest published version's summary (`latest_version`, `latest_published`), whatever the
-     * publish state. A method never published reads with both `null`, never as an error.
+     * Read one method with its draft's files — `GET /v1/methods/{id}`: its identity, its draft
+     * (`files`, `input_data`) with the draft's token (`updated_at`) and digest (`draft_digest`),
+     * and its latest published version's summary (`latest_version`, `latest_published`), whatever
+     * the publish state. A method never published reads with both `null`, never as an error.
+     * `files` lists the draft's tree in tree path order, each file with its SHA-256, its size and a
+     * link to its bytes valid for about fifteen minutes, and is empty for an empty draft;
+     * `writeMethodTree` brings the tree to disk.
      *
      * Takes a bare catalog id: the method routes address the method itself, never a version of
      * it. A caller holding `mt_…@3` strips the suffix with `parseMethodSelector` and reads that
@@ -875,64 +899,145 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * suffixed id, before any request, rather than read back the `404` the platform would answer,
      * and for an id that is empty, `.` or `..`, which the URL would resolve into another route's
      * path.
+     *
+     * Throws `ApiResponseError`: `404` `not_found` for an unknown or foreign-org method, `409`
+     * `method_being_deleted` while its erasure runs, and a `409` whose verdict is `runtime` for a
+     * method whose draft names a tree the platform holds no record of. An answer whose `files` is
+     * not a listing is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
      */
-    getMethod(methodId: string): Promise<MethodData>;
+    getMethod(methodId: string): Promise<MethodDetail>;
     /**
-     * Resolve a stored method's id into the runnable MTHDS closure of its DRAFT — a
-     * client-side semantic layer over `getMethod` (the platform has no route that
-     * returns a parsed closure). Fetches the method, parses its draft's polymorphic
-     * `mthds` source with `methodSourceToContents`, and labels each resulting file
-     * with the `method_id` as its `source` provenance.
+     * Create a method — `POST /v1/methods`. The new method holds its tree as its draft and has no
+     * published version, so its bare id answers `409 method_not_published` on the run and tooling
+     * routes until its first `publishMethod`; its draft runs as `mt_…@draft` at once.
      *
-     * **This is the draft, not what a bare id runs.** A run, a validation or a pipe I/O
-     * read by a bare `method_id` resolves to the latest PUBLISHED version, which the
-     * draft may be ahead of. For the closure of a version, read it with
-     * `getMethodVersion` and parse its `mthds` with `methodSourceToContents`.
+     * The tree is `files`, sent as given, or `tree` or `contents`, which the client sends inline
+     * when its inline map weighs 256 KiB or less, or when the platform keeps no blob store, and
+     * otherwise every file by hash, after asking `POST /v1/blobs/missing` which files the
+     * organization lacks and uploading those: a file uploaded once is never uploaded again. With
+     * none of the three, the draft is empty (see `docs/method-trees.md`).
      *
-     * This is the LOCAL expansion utility — for callers that want the files in
-     * hand (to edit, to diff, or to send to a bare runner, which has no catalog to
-     * resolve an id against). The operations that accept `method_id`
-     * natively (`execute`/`start`, `validate`/`resolve`/`codegen`/`pipeIo`, and
-     * `prepareInputs`, which composes a `pipeIo` of its own) take the id as a
-     * pass-through instead; nothing in this client expands an id behind your back.
-     *
-     * Takes a bare catalog id, as `getMethod` does. Requires an API key: the methods
-     * catalog is org-scoped to the key's org, so an unknown OR foreign-org id is a
-     * `getMethod` `404` (`ApiResponseError` `not_found`), which propagates unchanged. A
-     * real, in-org method whose draft parses to nothing throws `EmptyMethodSourceError`
-     * (distinct from the 404) — the row exists but has no runnable source yet.
+     * Throws `RequestArgumentError` for two forms of the tree, or `contents` holding no file, before
+     * any request; `MethodFileTransferError` when a file the organization lacks could not be
+     * uploaded, and nothing is saved. Throws `ApiResponseError`: `422` `invalid_method_files` for a
+     * map the standard refuses, with its `tree_refusal`; `422` `method_tree_too_large` for a tree
+     * past one of the deployment's limits, named in its `limit`; `422` `blob_mismatch` for a hash
+     * stated at another size than the one held; `422` `missing_blobs` for a hash entry whose bytes
+     * the organization does not hold; `413` `payload_too_large` for a method that would leave no
+     * room for a publish.
      */
-    getMethodClosure(methodId: string): Promise<MthdsFileItem[]>;
+    createMethod(input: MethodWriteInput): Promise<MethodData>;
     /**
-     * Create a method — `POST /v1/methods`. The new method holds the input as its draft and has
-     * no published version, so its bare id answers `409 method_not_published` on the run and
-     * tooling routes until its first `publishMethod`; its draft runs as `mt_…@draft` at once.
-     *
-     * Throws `ApiResponseError`: `413` `payload_too_large` for a method that would leave no room
-     * for a publish, measured as a draft write is, and `422` `validation_failed` for Python files
-     * no run could import or for text holding a lone surrogate.
+     * 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.
      */
-    createMethod(input: MethodWriteInput): Promise<MethodData>;
+    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`).
      *
      * The draft is never validated on write, and writing it changes nothing for the callers of
      * the method's bare id, who run the latest published version until the next `publishMethod`.
-     * `python` and `input_data` are three-way (see `MethodDraftInput`). With
+     * The write replaces the draft's whole tree, given in exactly one form: `files`, sent as given,
+     * `files: null` emptying the draft, or `tree` or `contents`, sent inline or by hash as
+     * `createMethod` sends them. `input_data` is three-way (see `MethodDraftInput`). With
      * `expected_updated_at`, the write is a compare-and-swap on the draft token: a draft that
      * moved since is refused with a `409` whose `code` is `method_update_conflict`, and nothing is
      * written. Without it, last writer wins.
      *
-     * Takes a bare catalog id, as `getMethod` does. Throws `ApiResponseError`: `404` `not_found`
-     * for an unknown or foreign-org method, `409` `method_being_deleted` while its erasure runs,
-     * `413` `payload_too_large` for a draft that would grow the method past the room a publish
-     * needs, which keeps a draft that saves publishable, `422` `validation_failed` for Python
-     * files no run could import or for text holding a lone surrogate, `403` for a read-only key,
-     * and a `503` that wrote nothing, safe to retry, when the method kept changing under the
-     * write.
+     * Takes a bare catalog id, as `getMethod` does. Throws `RequestArgumentError` for a draft that
+     * gives its tree in no form or in two, or `contents` holding no file, before any request;
+     * `MethodFileTransferError` when a file the organization lacks could not be uploaded. Throws
+     * `ApiResponseError`: `404` `not_found` for an unknown or foreign-org method, `409`
+     * `method_being_deleted` while its erasure runs, the `422` refusals of a tree `createMethod`
+     * lists, `413` `payload_too_large` for a draft that would grow the method past the room a
+     * publish needs, `403` for a read-only key, and a `503` that wrote nothing, safe to retry,
+     * when the method kept changing under the write.
      */
     writeDraft(methodId: string, input: MethodDraftInput): Promise<MethodData>;
+    /**
+     * 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:
+     *
+     * ```ts
+     * import { listMethodTree } from "mthds";
+     * const tree = await listMethodTree("methods/receipts", { limits: await client.methodTreeLimits() });
+     * await client.createMethod({ name: "Receipts", tree });
+     * ```
+     *
+     * 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.
+     */
+    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.
+     */
+    private cachedVersion;
+    /**
+     * 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.**
+     *
+     * Each file is downloaded through its link, at most eight at a time, with no credential of this
+     * client, and checked against the listing: its size and its SHA-256 must be the ones listed, so
+     * what lands on disk is the tree the method's digest names. The files are written into a fresh
+     * hidden directory beside the destination, which takes its name only once every file is
+     * written: an interrupted or failed write never leaves a partial tree under that name. The
+     * destination must not exist, or be an empty directory; one holding anything is refused rather
+     * than written into or replaced. An empty listing writes an empty directory.
+     *
+     * The links expire about fifteen minutes after the read that served them: write the tree soon
+     * after reading the method, and read it again for fresh links when a download is refused.
+     *
+     * Throws `RequestArgumentError` before any download when the destination exists and is not an
+     * empty directory, or the listing holds a path that is not a tree path, the same path twice, or
+     * paths that collide once case-folded or where one names a directory of another;
+     * `MethodFileTransferError` when a file could not be downloaded, or its bytes are not the file
+     * listed, and nothing is left under the destination.
+     */
+    writeMethodTree(files: readonly SavedMethodFile[], options: {
+        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;
+    /**
+     * 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.
+     */
+    private findMissingBlobs;
+    /**
+     * Upload each missing blob from the tree's bytes, a few at a time, stopping at the first
+     * failure. A blob the platform asks for that the tree does not hold, or holds at another size,
+     * 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.
+     */
+    private uploadMissing;
     /**
      * 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
@@ -979,7 +1084,7 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      */
     publishMethod(methodId: string, input: MethodPublishInput): Promise<MethodPublishResult>;
     /**
-     * One page of a method's published versions, newest first, without their sources —
+     * One page of a method's published versions, newest first, without their files —
      * `GET /v1/methods/{id}/versions`.
      *
      * Pass the page's `nextCursor` back as `cursor` to continue; `null` is the last page. A page
@@ -993,14 +1098,16 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      */
     listMethodVersions(methodId: string, query?: ListMethodVersionsQuery): Promise<MethodVersionPage>;
     /**
-     * One published version of a method, with its sources —
-     * `GET /v1/methods/{id}/versions/{n}`. Its `python` is parsed into `MethodFile[]` as a
-     * method's is.
+     * One published version of a method, with its files — `GET /v1/methods/{id}/versions/{n}`.
+     * `files` lists the version's tree as `getMethod` lists the draft's, each file with a link to
+     * its bytes valid for about fifteen minutes, which `writeMethodTree` writes to disk.
      *
      * Takes a bare catalog id, as `getMethod` does, and the version number. Throws
      * `RequestArgumentError` for a `version` that is not a positive integer, before any request.
      * Throws `ApiResponseError`: `404` `method_version_not_found` for a version the method never
-     * published, `404` `not_found` for an unknown method, `409` `method_being_deleted`.
+     * published, `404` `not_found` for an unknown method, `409` `method_being_deleted`, and `409`
+     * `conflict`, whose verdict is `runtime`, for a version stored before methods were trees and
+     * never rewritten as one, which names no tree to serve.
      */
     getMethodVersion(methodId: string, version: number): Promise<MethodVersion>;
     /**