@pipelex/sdk 0.39.0 → 0.41.0

package/dist/client.js

@@ -2,30 +2,80 @@
 // source combinations are legal is an invariant of `RunRequest` itself, so this
 // client and the MTHDS runners cannot disagree about what they reject.
 import { assertExclusiveRunSources, hasBundlePayload, parseMethodFiles, serializeMethodFiles, } from "mthds/protocol";
-import { assertArtifactSelection, assertWaitOptions, pollUntilResult, readRunDegradation, selectionIncludesMainStuff, throwIfAborted, } from "./runs.js";
+import { assertArtifactSelection, assertWaitOptions, pollUntilResult, readRunDegradation, RUN_STATUSES, runStatusFilter, selectionIncludesMainStuff, throwIfAborted, } from "./runs.js";
 import { ApiResponseError, ApiUnreachableError, EmptyMethodSourceError, MissingMainStuffError, PagingNotTerminatingError, PipelineExecuteTimeoutError, PipelineRequestError, RequestArgumentError, RunLifecycleUnavailableError, RunStillRunningError, } from "./errors.js";
 import { isPlainObject, isValidationItem, readFieldError, readMigration, readProviderMetadata, readRunErrorReport, } from "./error-models.js";
 import { methodSourceToContents } from "./method-source.js";
 import { buildUserAgent } from "./user-agent.js";
 import { uploadFile as uploadFileImpl } from "./upload.js";
+import { encodeBundleResources, hasBundleResources } from "./bundle-resources.js";
 import { prepareInputs as prepareInputsImpl } from "./prepare-inputs.js";
 import { downloadArtifacts as downloadArtifactsImpl, fetchArtifact as fetchArtifactImpl, resolveArtifacts as resolveArtifactsImpl, } from "./artifacts.js";
 import { PipelexExecuteResult, resultsFromExecute } from "./execute-result.js";
 import { MAX_TIMER_DELAY_MS, isTimerDelay } from "./timers.js";
-// A pure RUNAWAY guard on `iterateMethods`, deliberately not a coverage limit.
+// A pure RUNAWAY guard on the paged-list iterators (`iterateMethods`,
+// `iterateRuns`), deliberately not a coverage limit.
 //
 // It counts TOTAL pages, not empty ones. An earlier version capped consecutive
 // empty pages, which is the wrong axis: an empty page whose cursor ADVANCED is
-// real progress through the index — the platform applies `q` as a post-read
-// filter over a bounded slice per request, so a sparse match legitimately
-// yields runs of empty pages — and capping them turns a valid sparse search
-// into a thrown error. The stuck case is already caught by the no-progress
-// check (the server handing back the cursor we sent).
+// real progress through the index — the platform applies the list filters
+// (`q` and `published` on methods, `createdBy` and `status` on runs) after a
+// bounded read per request, so a sparse match legitimately yields runs of
+// empty pages — and capping them turns a valid sparse search into a thrown
+// error. The stuck case is already caught by the no-progress check (the
+// server handing back the cursor we sent).
 //
-// At the platform's 200-row maximum page size this is 2,000,000 methods, so it
+// At the platform's 200-row maximum page size this is 2,000,000 rows, so it
 // cannot fire on real data; it exists only so a server minting fresh cursors
 // forever cannot hang a caller indefinitely.
 const MAX_PAGES = 10_000;
+/**
+ * Follow a paged list's cursor until the server says there is no more, yielding every row —
+ * the one loop behind `iterateMethods` and `iterateRuns`, so the two cannot drift apart.
+ *
+ * It yields lazily: a caller that breaks early stops the requests. It stops when `nextCursor`
+ * is `null`, the normal end, and when the server hands back the cursor it was just sent, which
+ * is no progress and would repeat rows already yielded. It keeps going through an EMPTY page
+ * that carries a cursor, since a filtered page can hold no row and still not be the end; past
+ * `MAX_PAGES` pages it throws `PagingNotTerminatingError` rather than return a truncated list.
+ */
+async function* followCursor(route, readPage) {
+    let cursor;
+    let pages = 0;
+    for (;;) {
+        const page = await readPage(cursor);
+        // Checked BEFORE yielding: a server handing back the very cursor we sent
+        // has not advanced, so this page repeats rows already emitted — yielding
+        // first and stopping after would silently double-count them for anyone
+        // aggregating the stream (summing cost, counting runs). Cannot fire on the
+        // first request, where `cursor` is undefined.
+        if (cursor !== undefined && page.nextCursor === cursor)
+            return;
+        for (const item of page.items)
+            yield item;
+        // `nextCursor === null` is the NORMAL end of the list, and that page is
+        // real data, so it has to be emitted before this fires.
+        if (page.nextCursor === null)
+            return;
+        // An EMPTY page is NOT the end, and treating it as one was a bug. The
+        // platform filters after a bounded index read per request, so a sparse
+        // match legitimately returns `{items: [], nextCursor: "…"}` — "nothing
+        // matched in the slice I just read, keep going". Returning here dropped
+        // every later match silently, which is the exact truncation this
+        // pagination work exists to remove.
+        pages += 1;
+        if (pages >= MAX_PAGES) {
+            // THROW, do not return. A caller that asked for every row and got a
+            // partial answer with no error is back to the original bug one layer
+            // up; an error is the only honest response to a server that will not
+            // finish. Unreachable on real data — see MAX_PAGES. It also bounds a
+            // cursor that CYCLES (`c1 → c2 → c1`), which the adjacent check misses.
+            throw new PagingNotTerminatingError(`${route} did not terminate after ${MAX_PAGES} pages; refusing to keep paging. ` +
+                `This is a server-side fault, not a coverage limit.`, MAX_PAGES);
+        }
+        cursor = page.nextCursor;
+    }
+}
 /** Decoders of an answer's bytes: the strict one tells a body that is not UTF-8. */
 const STRICT_UTF8 = new TextDecoder("utf-8", { fatal: true });
 const LENIENT_UTF8 = new TextDecoder("utf-8");
@@ -464,6 +514,9 @@ export class PipelexApiClient {
         assertRunSourcesExclusive(options);
         assertMethodRefPairsWithNothing(options);
         assertLinkageMethodIdIsBare(options);
+        assertResourcesAccompanyABundle(options);
+        // No await when there are none: a request without them leaves on the tick it always did.
+        const resources = options.resources == null ? undefined : await encodeBundleResources(options.resources);
         const request = {
             pipe_code: options.pipe_code,
             mthds_contents: options.mthds_contents,
@@ -473,6 +526,7 @@ export class PipelexApiClient {
             dynamic_output_concept_ref: options.dynamic_output_concept_ref,
             files: nonEmptyFiles(options.files),
             bundle_b64: nonEmptyString(options.bundle_b64),
+            resources,
             ...api,
             ...hosted,
             ...extensions,
@@ -537,6 +591,9 @@ export class PipelexApiClient {
         assertRunSourcesExclusive(options);
         assertMethodRefPairsWithNothing(options);
         assertLinkageMethodIdIsBare(options);
+        assertResourcesAccompanyABundle(options);
+        // No await when there are none: a request without them leaves on the tick it always did.
+        const resources = options.resources == null ? undefined : await encodeBundleResources(options.resources);
         // `?? undefined` so JSON.stringify drops absent fields from the wire body.
         const request = {
             pipe_code: options.pipe_code ?? undefined,
@@ -547,6 +604,7 @@ export class PipelexApiClient {
             dynamic_output_concept_ref: options.dynamic_output_concept_ref ?? undefined,
             files: nonEmptyFiles(options.files),
             bundle_b64: nonEmptyString(options.bundle_b64),
+            resources,
             ...api,
             ...hosted,
             ...extensions,
@@ -554,16 +612,17 @@ export class PipelexApiClient {
         const url = this.url("start");
         // `start` returns a 202 fast, so the poll timeout normally fits — with
         // exceptions that get the blocking-execute ceiling instead. A method bundle,
-        // inline as `mthds_contents` or in `files`/`bundle_b64`, can make the
-        // request *body* multi-megabyte, and the whole upload is
-        // charged against this budget — the same payload must not time out on the
-        // durable path yet succeed on the fallback. And a `method_ref` start makes
-        // the server FETCH the package before the ack (provenance rides the 202),
-        // whose clone timeout runs well past 30s on a cold cache — aborting it here
-        // would surface as `ApiUnreachableError`, blaming the network for a healthy
-        // server that is still cloning.
+        // inline as `mthds_contents` or in `files`/`bundle_b64`, or the files its
+        // steps read (`resources`), can make the request *body* multi-megabyte, and
+        // the whole upload is charged against this budget — the same payload must
+        // not time out on the durable path yet succeed on the fallback. And a
+        // `method_ref` start makes the server FETCH the package before the ack
+        // (provenance rides the 202), whose clone timeout runs well past 30s on a
+        // cold cache — aborting it here would surface as `ApiUnreachableError`,
+        // blaming the network for a healthy server that is still cloning.
         const needsLongCeiling = hasBundlePayload(options) ||
             (options.mthds_contents?.length ?? 0) > 0 ||
+            resources !== undefined ||
             nonEmptyString(options.method_ref) !== undefined;
         const res = await this.requestRaw("POST", url, {
             body: request,
@@ -645,6 +704,15 @@ export class PipelexApiClient {
      * 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`.
+     *
      * A `{ method_ref }` source makes the server clone a repository before it
      * validates anything, and it needs no special budget here: this route already
      * defaults to the 20-minute execute ceiling, which clears the internal
@@ -682,6 +750,9 @@ export class PipelexApiClient {
                 throw new RequestArgumentError("mthds_sources labels inline mthds_contents; a method_ref / method_id validation gets " +
                     "its source labels from the package's (or the stored method's) real file names.");
             }
+            if (methodRef !== undefined && hasBundleResources(options.resources)) {
+                throw new RequestArgumentError("resources accompany inline mthds_contents; a method_ref's files are the package's own.");
+            }
             if (methodRef !== undefined)
                 body.method_ref = methodRef;
             if (methodId !== undefined)
@@ -691,6 +762,11 @@ export class PipelexApiClient {
         if (views !== undefined) {
             body.views = views;
         }
+        // No await when there are none: a request without them leaves on the tick it always did.
+        const resources = options.resources == null ? undefined : await encodeBundleResources(options.resources);
+        if (resources !== undefined) {
+            body.resources = resources;
+        }
         const res = await this.requestRaw("POST", this.url("validate"), {
             body,
             timeoutMs: options.timeoutMs,
@@ -719,6 +795,7 @@ export class PipelexApiClient {
             ? files.map((file, index) => file.uri ?? `inline://file-${index + 1}.mthds`)
             : undefined;
         return this.validate(mthdsContents, options.allowSignatures ?? false, mthdsSources, options.render, options.views, {
+            resources: options.resources,
             timeoutMs: options.timeoutMs,
             signal: options.signal,
         });
@@ -793,10 +870,11 @@ export class PipelexApiClient {
      * never on a message.
      *
      * All of these are static and inference-free, so they default to the management-call
-     * timeout. The one internal raise is the fetch-sized budget `crateRequestTimeoutMs`
-     * gives a crate route whose closure is a `method_ref`, because the server may clone a
-     * repository before it answers; it is matched to what the server does, not a
-     * caller-facing parameter.
+     * timeout. The internal raises are `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.
      *
      * **These routes deliberately expose no `timeoutMs` / `signal`, and that is not an
      * oversight to be "fixed" per route.** Automated reviewers have proposed adding them
@@ -807,8 +885,11 @@ export class PipelexApiClient {
      *    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 a request
-     *    at 16 `.mthds` files of 1 MiB each — and none of these routes runs inference.
+     * 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.
      * 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.
@@ -930,7 +1011,7 @@ export class PipelexApiClient {
      * see {@link PipelexHostedToolingExtensions}).
      */
     async resolve(request) {
-        return this.requestExtension("resolve", request, {
+        return this.requestExtension("resolve", await wireCrateRequest(request), {
             timeoutMs: crateRequestTimeoutMs(request),
         });
     }
@@ -950,7 +1031,7 @@ export class PipelexApiClient {
      * a malformed selector is a 422; a registry-form `method_ref` is a `501`.
      */
     async codegen(request) {
-        return this.requestExtension("codegen", request, {
+        return this.requestExtension("codegen", await wireCrateRequest(request), {
             timeoutMs: crateRequestTimeoutMs(request),
         });
     }
@@ -970,8 +1051,14 @@ export class PipelexApiClient {
      * 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`.
      *
+     * 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}).
+     *
      * Same 200-verdict discipline and same three-form closure selector as {@link resolve}
-     * (the request is posted verbatim, and the selector XOR is the server's to enforce).
+     * (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).
      * 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
@@ -979,13 +1066,14 @@ export class PipelexApiClient {
      * 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. 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, 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.
      */
     async pipeIo(request) {
-        return this.requestExtension("pipe-io", request, {
+        return this.requestExtension("pipe-io", await wireCrateRequest(request), {
             timeoutMs: crateRequestTimeoutMs(request),
         });
     }
@@ -1198,16 +1286,23 @@ export class PipelexApiClient {
      * Rows are `MethodSummary`: no `mthds`, no `python`, no `updated_at`. Reach
      * for `getMethod(id)` when you need a method's source.
      *
-     * `q` is applied server-side over the whole catalog, not over the page.
+     * `q` is applied server-side over the whole catalog, not over the page, and so is
+     * `published` (`true` for the methods with a published version, `false` for those never
+     * published). Each row carries the method's publish state (`latest_version`,
+     * `latest_published`, `draft_digest`). Both filters run after the index read, so a page can
+     * come back empty and still carry a `nextCursor`: keep following it until it is `null`.
      */
     async listMethods(query = {}) {
         const params = new URLSearchParams();
         // `!== undefined`, not truthiness — mirroring `listRuns`. Omission means
         // "the caller did not ask"; an explicit empty string is bad input and the
         // API should say so, rather than being silently dropped into an unfiltered
-        // query that returns everything and reads as working.
+        // query that returns everything and reads as working. `published: false`
+        // is a filter of its own, never omission.
         if (query.q !== undefined)
             params.set("q", query.q);
+        if (query.published !== undefined)
+            params.set("published", String(query.published));
         if (query.limit !== undefined)
             params.set("limit", String(query.limit));
         if (query.cursor !== undefined)
@@ -1233,43 +1328,14 @@ export class PipelexApiClient {
      * TRUNCATED list with no error — precisely the bug paging was introduced to
      * remove. If you truly want an array, `Array.fromAsync` makes that your
      * explicit choice.
+     *
+     * It keeps going **through an empty page that carries a cursor**: under `q` or `published`
+     * such a page means "nothing matched in the slice just read", not "done". It stops on a
+     * `null` cursor or on a cursor the server failed to advance, and throws
+     * `PagingNotTerminatingError` past a page ceiling no real catalog reaches.
      */
     async *iterateMethods(query = {}) {
-        let cursor;
-        let pages = 0;
-        for (;;) {
-            const page = await this.listMethods({ ...query, cursor });
-            // Checked BEFORE yielding: a server handing back the very cursor we sent
-            // has not advanced, so this page repeats rows already emitted. Cannot
-            // fire on the first request, where `cursor` is undefined.
-            if (cursor !== undefined && page.nextCursor === cursor)
-                return;
-            for (const method of page.items)
-                yield method;
-            // `nextCursor === null` is the NORMAL end of the catalog, and that page
-            // is real data, so it has to be emitted before this fires.
-            if (page.nextCursor === null)
-                return;
-            // An EMPTY page is NOT the end, and treating it as one was a bug. The
-            // platform applies `q` as a post-read filter over a bounded number of
-            // index pages per request, so a sparse match legitimately returns
-            // `{items: [], nextCursor: "…"}` — "nothing matched in the slice I just
-            // read, keep going". Returning here dropped every later match silently,
-            // which is the exact truncation this pagination work exists to remove.
-            // (`iterateRuns` can stop on an empty page because its date bounds are
-            // index KEY conditions, so a run page is never empty-with-a-cursor. The
-            // difference is the server, not the client.)
-            pages += 1;
-            if (pages >= MAX_PAGES) {
-                // THROW, do not return. A caller that asked for every method and got a
-                // partial answer with no error is back to the original bug one layer
-                // up; an error is the only honest response to a server that will not
-                // finish. Unreachable on real data — see MAX_PAGES.
-                throw new PagingNotTerminatingError(`listMethods did not terminate after ${MAX_PAGES} pages; refusing to keep paging. ` +
-                    `This is a server-side fault, not a coverage limit.`, MAX_PAGES);
-            }
-            cursor = page.nextCursor;
-        }
+        yield* followCursor("listMethods", (cursor) => this.listMethods({ ...query, cursor }));
     }
     /**
      * Read one method — `GET /v1/methods/{id}`: its identity, its draft (`mthds`, `python`,
@@ -1657,7 +1723,8 @@ export class PipelexApiClient {
      * Name the method exactly one of three ways, all server-resolved through the
      * one `pipeIo` call this composes:
      *
-     * - `files` — the inline MTHDS closure;
+     * - `files` — the inline MTHDS closure, with the `resources` its steps read
+     *   (a `PipeDocGen` step's `template_file`), keyed by the path a step names;
      * - `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).
@@ -1668,8 +1735,11 @@ export class PipelexApiClient {
      * position is a fact of the method, never a guess from the value's shape. It
      * needs an API serving `POST /v1/pipe-io`. See `docs/input-preparation.md`.
      *
-     * With `allowUploads: false` it uploads nothing and reads no file: a value that
-     * would need an upload throws `UploadNotAllowedError`, naming the input.
+     * A value at a file input that cannot be a file, such as a number or a
+     * `data:` URL that does not decode, throws `InvalidInputValueError`, naming the
+     * input. With `allowUploads: false` it uploads nothing and reads no file: a
+     * value that would need an upload throws `UploadNotAllowedError`, naming the
+     * input too.
      */
     async prepareInputs(request) {
         return prepareInputsImpl(this, request);
@@ -1696,6 +1766,13 @@ export class PipelexApiClient {
      * conditions, so a bounded page genuinely reads less. They are INSTANTS,
      * not days — see `ListRunsQuery`.
      *
+     * `createdBy: "me"` keeps the caller's own runs and `status` the runs in any of the given
+     * statuses, sent as `created_by=me` and one repeated `status=` parameter per status. Both are
+     * filters applied after the index read, so a filtered page can hold fewer runs than `limit`,
+     * or none, and still carry a `nextCursor`: an empty page is not the end, a `null` cursor is.
+     * An empty `status` list, or a name that is no `RunStatus`, is a `RequestArgumentError`
+     * before any request.
+     *
      * Takes a bare catalog id: the history files the runs of every version and
      * of the draft together under it, so `mt_…@3` names no history of its own
      * and the platform refuses it with a `400`. Strip a suffix with
@@ -1713,6 +1790,10 @@ export class PipelexApiClient {
             params.set("created_from", query.createdFrom);
         if (query.createdTo !== undefined)
             params.set("created_to", query.createdTo);
+        if (query.createdBy !== undefined)
+            params.set("created_by", query.createdBy);
+        for (const status of runStatusFilter(query.status) ?? [])
+            params.append("status", status);
         if (query.limit !== undefined)
             params.set("limit", String(query.limit));
         if (query.cursor !== undefined)
@@ -1742,33 +1823,15 @@ export class PipelexApiClient {
      * when to stop, and only one page is ever in memory. If you truly want an
      * array, `Array.fromAsync` makes that your explicit choice.
      *
+     * It keeps going **through an empty page that carries a cursor**: under `createdBy` or
+     * `status` such a page means "nothing matched in the slice just read", not "done". It stops on
+     * a `null` cursor or on a cursor the server failed to advance, and throws
+     * `PagingNotTerminatingError` past a page ceiling no real history reaches.
+     *
      * Takes a bare catalog id, as `listRuns` does.
      */
     async *iterateRuns(methodId, query = {}) {
-        let cursor;
-        for (;;) {
-            const page = await this.listRuns(methodId, { ...query, cursor });
-            // Checked BEFORE yielding. A server handing back the very cursor we sent
-            // has not advanced, so this page repeats rows already emitted — yielding
-            // first and stopping after would silently double-count them for anyone
-            // aggregating the stream (summing cost, counting runs). Cannot fire on
-            // the first request, where `cursor` is undefined.
-            if (cursor !== undefined && page.nextCursor === cursor)
-                return;
-            for (const run of page.items)
-                yield run;
-            // Checked AFTER: `nextCursor === null` is the NORMAL end of the history
-            // and that page is real data, so it has to be emitted first. The empty
-            // page catches a server that keeps minting fresh cursors while returning
-            // nothing, which would otherwise spin forever yielding nothing.
-            //
-            // Neither of these is a page cap. Both fire only on a server that is not
-            // making progress, so neither can truncate a healthy stream the way a
-            // `maxPages` limit silently did.
-            if (page.nextCursor === null || page.items.length === 0)
-                return;
-            cursor = page.nextCursor;
-        }
+        yield* followCursor("listRuns", (cursor) => this.listRuns(methodId, { ...query, cursor }));
     }
     /**
      * The whole record for one run — `GET /v1/runs/{id}`.
@@ -1808,6 +1871,8 @@ export class PipelexApiClient {
             // this path runs the same method as the durable one, or it runs nothing.
             files: options.files ?? undefined,
             bundle_b64: options.bundle_b64 ?? undefined,
+            // And so must the files its steps read, or the same method fails to load here.
+            resources: options.resources ?? undefined,
             method_ref: options.method_ref ?? undefined,
             method_id: options.method_id ?? undefined,
             extra: options.extra ?? undefined,
@@ -1888,12 +1953,13 @@ const PROTOCOL_REQUEST_KEYS = [
     "files",
     "bundle_b64",
 ];
-// The PIPELEX API's own request fields — the layer-2 extension the runner
-// resolves itself (`method_ref`, a run source in its own right). Reserved on
-// `extra` for the same reason the protocol fields are: `extra` merges last, so
-// a smuggled copy would overwrite the validated named option and bypass the
-// selector-exclusivity checks.
-const PIPELEX_API_REQUEST_KEYS = ["method_ref"];
+// The PIPELEX API's own request fields — the layer-2 extensions the runner
+// reads itself (`method_ref`, a run source in its own right, and `resources`,
+// the files the bundle's steps read). Reserved on `extra` for the same reason
+// the protocol fields are: `extra` merges last, so a smuggled copy would
+// overwrite the validated named option and bypass the selector-exclusivity and
+// path checks.
+const PIPELEX_API_REQUEST_KEYS = ["method_ref", "resources"];
 // The HOSTED API's own request fields — the layer-3 extensions this client
 // names itself. Reserved on `extra` for the same reason the protocol fields
 // are: `extra` merges last, so a smuggled copy would overwrite the validated
@@ -1956,10 +2022,20 @@ function buildExtensions(extra) {
 const METHOD_REF_FETCH_TIMEOUT_MS = 180_000; // 3 min — covers the server's clone + resolve
 /**
  * The internal request budget for a crate route's `CrateRequestBase` closure
- * (`resolve`, `codegen`, `pipeIo`): the static-route default, unless the closure
- * is a `method_ref` the server may have to fetch first.
+ * (`resolve`, `codegen`, `pipeIo`): the static-route default, unless the request
+ * is one the default would cut short through no fault of the server's.
+ *
+ * - **`resources`** make the request *body* as large as the runner's limits allow,
+ *   about 13 MiB of base64 by default, and the whole upload is charged against
+ *   this budget. They get the execute ceiling `start` gives a request carrying
+ *   them, and `validate` carries them under by default, so the same bundle and
+ *   files never time out on one route yet go through on another.
+ * - **A `method_ref`** may make the server clone a repository first, which gets
+ *   the fetch-sized budget.
  */
 function crateRequestTimeoutMs(request) {
+    if (hasBundleResources(request.resources))
+        return DEFAULT_REQUEST_TIMEOUT_MS;
     return nonEmptyString(request.method_ref) !== undefined ? METHOD_REF_FETCH_TIMEOUT_MS : undefined;
 }
 /**
@@ -2065,6 +2141,43 @@ function assertLinkageMethodIdIsBare(options) {
         "that did not. Send the bare id (parseMethodSelector(...).method_id), or drop the inline " +
         "source to run the version the selector names.");
 }
+/**
+ * Enforce the run routes' `resources` pairing, mirroring the runner's own `422`s
+ * so an illegal pairing fails before anything is encoded or sent. The files a
+ * bundle's steps read accompany that bundle: inline `mthds_contents` or a method
+ * bundle. Beside a `method_ref` they are refused, a published package's files
+ * being its own, and so they are with no source at all, where no step could read
+ * them. A hosted `method_id` without an inline source is left to the server: the
+ * platform resolves it into the bundle the runner then reads them with.
+ *
+ * Presence follows the other pairing checks: `resources` counts when it carries a
+ * file, `mthds_contents` when non-empty, a bundle when `hasBundlePayload` says so.
+ */
+function assertResourcesAccompanyABundle(options) {
+    if (!hasBundleResources(options.resources))
+        return;
+    if (nonEmptyString(options.method_ref) !== undefined) {
+        throw new RequestArgumentError("resources accompany inline mthds_contents or a method bundle; a method_ref's files are the package's own.");
+    }
+    const hasInlineSource = (options.mthds_contents != null && options.mthds_contents.length > 0) ||
+        hasBundlePayload(options);
+    if (!hasInlineSource && nonEmptyString(options.method_id) === undefined) {
+        throw new RequestArgumentError("resources accompany the bundle whose steps read them: send them with mthds_contents or a method bundle.");
+    }
+}
+/**
+ * A crate request as the wire takes it: the request as given, its `resources`
+ * encoded into the base64 map, the key left off when there is nothing to send.
+ * A request that carries no `resources` key is posted untouched.
+ */
+async function wireCrateRequest(request) {
+    if (typeof request !== "object" || request === null || !("resources" in request)) {
+        return request;
+    }
+    const { resources, ...rest } = request;
+    const encoded = await encodeBundleResources(resources);
+    return encoded === undefined ? rest : { ...rest, resources: encoded };
+}
 /**
  * Normalize a bundle encoding for the wire: an empty map / string is NOT a
  * runnable bundle, so it must not be sent (the runner rejects a zero-file
@@ -2191,16 +2304,6 @@ function parseRetryAfter(headers) {
     const seconds = Number(raw);
     return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
 }
-const KNOWN_RUN_STATUSES = [
-    "PENDING",
-    "STARTED",
-    "RUNNING",
-    "COMPLETED",
-    "FAILED",
-    "CANCELLED",
-    "TERMINATED",
-    "TIMED_OUT",
-];
 /** The response header the platform and the runner stamp the request's correlation id on. */
 const REQUEST_ID_HEADER = "x-request-id";
 /**
@@ -2249,7 +2352,7 @@ function withCheckedDegradation(run) {
     return { ...run, degradation: readRunDegradation(run.degradation) };
 }
 function knownRunStatus(value) {
-    return typeof value === "string" && KNOWN_RUN_STATUSES.includes(value)
+    return typeof value === "string" && RUN_STATUSES.includes(value)
         ? value
         : undefined;
 }