@pipelex/sdk 0.16.0 → 0.18.0

package/dist/errors.d.ts

@@ -5,6 +5,7 @@
  */
 import { PipelineRequestError } from "mthds/protocol";
 import type { ValidationErrorItem } from "./models.js";
+import type { ArtifactScope, DownloadArtifactsResult } from "./artifacts.js";
 export { PipelineRequestError };
 export declare class ClientAuthenticationError extends Error {
     constructor(message: string);
@@ -21,9 +22,11 @@ export declare class InputPreparationError extends PipelineRequestError {
     });
 }
 /**
- * The stored method resolved by `getMethodClosure` (and by-id `prepareInputs` /
- * `buildInputs`) has no MTHDS source yet — its `MethodData.mthds` parses to an
- * empty closure (a blank string, a JSON `[]`, or an all-blank file array).
+ * The stored method resolved by `getMethodClosure` has no MTHDS source yet — its
+ * `MethodData.mthds` parses to an empty closure (a blank string, a JSON `[]`, or
+ * an all-blank file array). `getMethodClosure` is the only raiser: the operations
+ * that take a `method_id` natively — `prepareInputs` among them — pass the id to
+ * the server, which answers a sourceless method with a `422`.
  *
  * Distinct from a transport failure: the `getMethod` fetch succeeded (`200`) and
  * the id is real and in-org; the row simply carries no runnable source. A missing
@@ -87,6 +90,69 @@ export declare class UploadTransportError extends InputPreparationError {
         cause?: unknown;
     });
 }
+/**
+ * Base class for the failures the artifact operations raise on their own
+ * (`fetchArtifact` / `downloadArtifacts`) — the download twin of
+ * `InputPreparationError`. Catch this to handle any artifact failure; catch a
+ * subclass to branch on the category. A per-reference failure inside a
+ * `downloadArtifacts` verdict is a value on the item, never one of these: the
+ * operation throws only when it can produce no verdict at all. Transport
+ * failures on the resolve route (`ApiResponseError`, `ApiUnreachableError`)
+ * and the run-lifecycle errors propagate unchanged, so they are not subclasses.
+ */
+export declare class ArtifactOperationError extends PipelineRequestError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The scope `downloadArtifacts` was asked to walk has no artifact on the run's
+ * results: `main_stuff` or `working_memory` is `null`, or the key is missing
+ * from the body altogether. Distinct from an empty walk over a present scope,
+ * which is a produced verdict with no artifacts. `scope` names the scope,
+ * `runId` the run.
+ */
+export declare class ScopeUnavailableError extends ArtifactOperationError {
+    readonly scope: ArtifactScope;
+    readonly runId: string;
+    constructor(scope: ArtifactScope, runId: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * One reference could not be turned into a bounded response by `fetchArtifact`.
+ * `code` says why, in a closed vocabulary the download verdict shares for its
+ * per-item errors: the resolve route's own per-reference codes
+ * (`invalid_storage_uri`, `forbidden`), then the fetch boundary's —
+ * `unsupported_url`, `plain_http_refused`, `redirect_refused`, `store_refused`
+ * (a 401/403 from the object store), `not_found` (404/410), `store_error`
+ * (any other non-2xx), `too_large`, `timeout`, `network`. `status` is the
+ * store's HTTP status when one was received. `downloadArtifacts` never lets
+ * this escape: it becomes the item's `error`.
+ */
+export declare class ArtifactFetchError extends ArtifactOperationError {
+    readonly uri: string;
+    readonly code: string;
+    readonly status: number | undefined;
+    constructor(message: string, uri: string, code: string, status?: number, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * The resolve route refused the caller's credential (`401` / `403`) during a
+ * `downloadArtifacts` call. No further reference can be resolved with it, so
+ * the download stops — but the files already saved are real, and `verdict`
+ * carries the result as it stood: every item saved before the refusal, and
+ * the rest marked `aborted`. `status` is the route's status; the wrapped
+ * `ApiResponseError` is reachable via `cause`.
+ */
+export declare class ArtifactAuthenticationError extends ArtifactOperationError {
+    readonly status: number;
+    readonly verdict: DownloadArtifactsResult;
+    constructor(message: string, status: number, verdict: DownloadArtifactsResult, options?: {
+        cause?: unknown;
+    });
+}
 /**
  * Thrown when the Pipelex API host cannot be reached at all (DNS failure,
  * connection refused, TLS handshake failure, request timeout). The HTTP

package/dist/errors.js

@@ -24,9 +24,11 @@ export class InputPreparationError extends PipelineRequestError {
     }
 }
 /**
- * The stored method resolved by `getMethodClosure` (and by-id `prepareInputs` /
- * `buildInputs`) has no MTHDS source yet — its `MethodData.mthds` parses to an
- * empty closure (a blank string, a JSON `[]`, or an all-blank file array).
+ * The stored method resolved by `getMethodClosure` has no MTHDS source yet — its
+ * `MethodData.mthds` parses to an empty closure (a blank string, a JSON `[]`, or
+ * an all-blank file array). `getMethodClosure` is the only raiser: the operations
+ * that take a `method_id` natively — `prepareInputs` among them — pass the id to
+ * the server, which answers a sourceless method with a `422`.
  *
  * Distinct from a transport failure: the `getMethod` fetch succeeded (`200`) and
  * the id is real and in-org; the row simply carries no runnable source. A missing
@@ -101,6 +103,81 @@ export class UploadTransportError extends InputPreparationError {
         this.name = "UploadTransportError";
     }
 }
+/**
+ * Base class for the failures the artifact operations raise on their own
+ * (`fetchArtifact` / `downloadArtifacts`) — the download twin of
+ * `InputPreparationError`. Catch this to handle any artifact failure; catch a
+ * subclass to branch on the category. A per-reference failure inside a
+ * `downloadArtifacts` verdict is a value on the item, never one of these: the
+ * operation throws only when it can produce no verdict at all. Transport
+ * failures on the resolve route (`ApiResponseError`, `ApiUnreachableError`)
+ * and the run-lifecycle errors propagate unchanged, so they are not subclasses.
+ */
+export class ArtifactOperationError extends PipelineRequestError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ArtifactOperationError";
+    }
+}
+/**
+ * The scope `downloadArtifacts` was asked to walk has no artifact on the run's
+ * results: `main_stuff` or `working_memory` is `null`, or the key is missing
+ * from the body altogether. Distinct from an empty walk over a present scope,
+ * which is a produced verdict with no artifacts. `scope` names the scope,
+ * `runId` the run.
+ */
+export class ScopeUnavailableError extends ArtifactOperationError {
+    scope;
+    runId;
+    constructor(scope, runId, options) {
+        super(`Run "${runId}" carries no "${scope}" artifact to walk for produced files — ` +
+            "it is null or absent from the results body.", options);
+        this.name = "ScopeUnavailableError";
+        this.scope = scope;
+        this.runId = runId;
+    }
+}
+/**
+ * One reference could not be turned into a bounded response by `fetchArtifact`.
+ * `code` says why, in a closed vocabulary the download verdict shares for its
+ * per-item errors: the resolve route's own per-reference codes
+ * (`invalid_storage_uri`, `forbidden`), then the fetch boundary's —
+ * `unsupported_url`, `plain_http_refused`, `redirect_refused`, `store_refused`
+ * (a 401/403 from the object store), `not_found` (404/410), `store_error`
+ * (any other non-2xx), `too_large`, `timeout`, `network`. `status` is the
+ * store's HTTP status when one was received. `downloadArtifacts` never lets
+ * this escape: it becomes the item's `error`.
+ */
+export class ArtifactFetchError extends ArtifactOperationError {
+    uri;
+    code;
+    status;
+    constructor(message, uri, code, status, options) {
+        super(message, options);
+        this.name = "ArtifactFetchError";
+        this.uri = uri;
+        this.code = code;
+        this.status = status;
+    }
+}
+/**
+ * The resolve route refused the caller's credential (`401` / `403`) during a
+ * `downloadArtifacts` call. No further reference can be resolved with it, so
+ * the download stops — but the files already saved are real, and `verdict`
+ * carries the result as it stood: every item saved before the refusal, and
+ * the rest marked `aborted`. `status` is the route's status; the wrapped
+ * `ApiResponseError` is reachable via `cause`.
+ */
+export class ArtifactAuthenticationError extends ArtifactOperationError {
+    status;
+    verdict;
+    constructor(message, status, verdict, options) {
+        super(message, options);
+        this.name = "ArtifactAuthenticationError";
+        this.status = status;
+        this.verdict = verdict;
+    }
+}
 /**
  * Thrown when the Pipelex API host cannot be reached at all (DNS failure,
  * connection refused, TLS handshake failure, request timeout). The HTTP

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAItD,OAAO,EAAE,oBAAoB,EAAE,CAAC;AAEhC,MAAM,OAAO,yBAA0B,SAAQ,KAAK;IAClD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,qBAAsB,SAAQ,oBAAoB;IAC7D,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,sBAAuB,SAAQ,qBAAqB;IAC/C,QAAQ,CAAS;IAEjC,YAAY,QAAgB,EAAE,OAA6B;QACzD,KAAK,CAAC,WAAW,QAAQ,4BAA4B,EAAE,OAAO,CAAC,CAAC;QAChE,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,uBAAwB,SAAQ,qBAAqB;IAChD,MAAM,CAAS;IAE/B,YAAY,OAAe,EAAE,MAAc,EAAE,OAA6B;QACxE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,qBAAqB;IAC3C,QAAQ,CAAS;IACjB,MAAM,CAAS;IAE/B,YAAY,OAAe,EAAE,QAAgB,EAAE,MAAc,EAAE,OAA6B;QAC1F,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,gCAAiC,SAAQ,qBAAqB;IACzE,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,kCAAkC,CAAC;IACjD,CAAC;CACF;AAED,uEAAuE;AACvE,MAAM,OAAO,yBAA0B,SAAQ,qBAAqB;IAClD,MAAM,CAAS;IAE/B,YAAY,OAAe,EAAE,MAAc,EAAE,OAA6B;QACxE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;QACxC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,oBAAqB,SAAQ,qBAAqB;IAC7D,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,sBAAuB,SAAQ,oBAAoB;IAC9D,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;IACvC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,qBAAsB,SAAQ,sBAAsB;IAC/C,KAAK,CAAgB;IACrB,KAAK,CAAS;IAE9B,YAAY,KAAoB,EAAE,KAAa,EAAE,OAA6B;QAC5E,KAAK,CACH,QAAQ,KAAK,iBAAiB,KAAK,0CAA0C;YAC3E,6CAA6C,EAC/C,OAAO,CACR,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,kBAAmB,SAAQ,sBAAsB;IAC5C,GAAG,CAAS;IACZ,IAAI,CAAS;IACb,MAAM,CAAqB;IAE3C,YACE,OAAe,EACf,GAAW,EACX,IAAY,EACZ,MAAe,EACf,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,OAAO,2BAA4B,SAAQ,sBAAsB;IACrD,MAAM,CAAS;IACf,OAAO,CAA0B;IAEjD,YACE,OAAe,EACf,MAAc,EACd,OAAgC,EAChC,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;QAC1C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,mBAAoB,SAAQ,oBAAoB;IAC3C,MAAM,CAAS;IACf,IAAI,CAAqB;IAEzC,YACE,OAAe,EACf,MAAc,EACd,IAAwB,EACxB,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,2BAA4B,SAAQ,oBAAoB;IACnD,SAAS,CAAS;IAElC,YAAY,SAAiB,EAAE,OAA6B;QAC1D,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;QAC7C,KAAK,CACH,oFAAoF,OAAO,KAAK;YAC9F,kFAAkF;YAClF,uFAAuF,EACzF,OAAO,CACR,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;QAC1C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,cAAe,SAAQ,oBAAoB;IACtC,KAAK,CAAS;IACd,MAAM,CAAS;IAE/B,YAAY,OAAe,EAAE,KAAa,EAAE,MAAc,EAAE,OAA6B;QACvF,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,qBAAsB,SAAQ,oBAAoB;IAC7C,KAAK,CAAS;IAE9B,YAAY,OAAe,EAAE,KAAa;QACxC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,eAAgB,SAAQ,oBAAoB;IACvC,KAAK,CAAS;IACd,SAAS,CAAS;IAElC,YAAY,OAAe,EAAE,KAAa,EAAE,SAAiB;QAC3D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,oBAAqB,SAAQ,oBAAoB;IAC5C,KAAK,CAAS;IACd,iBAAiB,CAAgB;IACjC,QAAQ,CAAgB;IAExC,YACE,OAAe,EACf,KAAa,EACb,oBAAmC,IAAI,EACvC,WAA0B,IAAI,EAC9B,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;QAC3C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,4BAA6B,SAAQ,oBAAoB;IACpD,MAAM,CAAS;IAE/B,YAAY,OAAe,EAAE,MAAc,EAAE,OAA6B;QACxE,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;QAC3C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,gBAAiB,SAAQ,oBAAoB;IACxC,MAAM,CAAS;IACf,MAAM,CAAS;IACf,UAAU,CAAS;IACnB,YAAY,CAAS;IACrB,SAAS,CAAqB;IAC9B,aAAa,CAAqB;IAClC,IAAI,CAAqB;IACzC;;;;;;;;;;;;OAYG;IACa,gBAAgB,CAAoC;IAEpE,YACE,OAAe,EACf,MAAc,EACd,MAAc,EACd,UAAkB,EAClB,YAAoB,EACpB,SAA6B,EAC7B,aAAiC,EACjC,gBAAmD,EACnD,IAAwB,EACxB,OAA6B;QAE7B,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF"}

package/dist/index.d.ts

@@ -7,18 +7,22 @@
  * errors. Consumers should import everything they need from `@pipelex/sdk`.
  */
 /** Package version. Kept in sync with `package.json` — enforced by `tests/index.test.ts`. */
-export declare const SDK_VERSION = "0.16.0";
+export declare const SDK_VERSION = "0.18.0";
 export * from "mthds/protocol";
 export { PipelexApiClient, DEFAULT_API_BASE_URL } from "./client.js";
 export type { MthdsFile, PipelexApiRunExtensions, PipelexHostedRunExtensions, PipelexRunOptions, PipelexStartOptions, ValidateMethodSelector, ValidateFilesOptions, PipelexApiClientOptions, } from "./client.js";
 export { methodSourceToContents } from "./method-source.js";
 export { PipelexExecuteResult } from "./execute-result.js";
 export type { UploadableAsset, UploadFileOptions, UploadRecord } from "./upload.js";
-export type { PrepareInputsRequest, PreparedInputs } from "./prepare-inputs.js";
+export type { PrepareInputsBase, PrepareInputsClosure, PrepareInputsRequest, PreparedInputs, } from "./prepare-inputs.js";
+export { collectArtifacts, artifactFilename, PIPELEX_STORAGE_SCHEME, BULK_RESOLVE_MAX_URIS, DEFAULT_ARTIFACT_MAX_BYTES, DEFAULT_ARTIFACT_TIMEOUT_MS, DEFAULT_DOWNLOAD_MAX_TOTAL_BYTES, DEFAULT_DOWNLOAD_CONCURRENCY, } from "./artifacts.js";
+export type { ArtifactItemError, ArtifactScope, BulkResolveStorageUrlsInput, BulkResolvedStorageUrls, DownloadArtifactsOptions, DownloadArtifactsRequest, DownloadArtifactsResult, DownloadedArtifact, FetchArtifactOptions, ResolvedArtifact, } from "./artifacts.js";
 export type { DiagnosticKind, DiagnosticRange, Diagnostic, LintResponse, FormatResponse, DictStuff, DictWorkingMemory, DictPipeOutput, DictRunResultExecute, MethodProvenance, PipelexRunResultStart, PipelexHostedToolingExtensions, DryRunStatus, ValidatedPipeEntry, LiftablePipeEntry, PipelexValidationReport, PipelexInvalidReport, PipelexValidationResult, ValidationErrorCategory, ValidationErrorItem, FixSafety, FixOpKind, TomlScalar, TomlValue, SetKeyOp, EnsureTableOp, DeleteKeyOp, DeleteTableOp, RenameTableKeyOp, MoveKeyOp, RemapValueOp, FixOp, SuggestedFix, ConceptRepresentationFormat, InputsTemplateFormat, MthdsFileItem, CrateRequestBase, BuildRequestBase, BuildInputsRequest, BuildOutputRequest, BuildRunnerRequest, ConceptRequest, PipeSpecRequest, CrateInvalidReport, BuildInputsValidReport, BuildOutputValidReport, BuildRunnerValidReport, GeneratedArtifact, RunnerStructures, BuildInputsResponse, BuildOutputResponse, BuildRunnerResponse, ConceptResponse, PipeSpecResponse, ResolveRequest, ResolveValidReport, ResolveResponse, CodegenKind, CodegenTarget, CodegenRequest, CodegenValidReport, CodegenResponse, } from "./models.js";
 export { runCodegenCheck, isStampableArtifactPath, STAMPABLE_ARTIFACT_SUFFIXES, CodegenLockError, } from "./codegen-check.js";
 export type { CodegenCheckInput, CodegenCheckReport, CodegenDrift, CodegenDriftCategory, CodegenTreeFile, } from "./codegen-check.js";
 export type { UserProfile, ListMethodsQuery, MethodData, MethodDeletionAccepted, MethodDeletionState, MethodPage, MethodSummary, MethodWriteInput, Membership, MembershipsResponse, SubscriptionResponse, PlanView, InvoiceView, CheckoutResponse, ChangePlanResponse, BillingPortalResponse, PipelexApiKey, PipelexApiKeyCreated, PipelexApiKeyList, GatewayApiKey, GatewayApiKeyStatus, OnboardingRole, OnboardingCurrentTool, OnboardingInputType, OnboardingHeardFrom, OnboardingSubmission, ResolvedStorageUrl, UploadInput, UploadedFile, PipeStatus, ListRunsQuery, PipelineRun, RunDetail, RunErrorReport, RunPage, UpdateRunInput, } from "./product-models.js";
 export { isTerminalRunStatus, isSuccessRunStatus } from "./runs.js";
 export type { RunStatus, RunPublic, RunRead, RunResults, RunResultState, TokensUsageRecord, WaitForResultOptions, } from "./runs.js";
-export { ApiResponseError, ApiUnreachableError, ClientAuthenticationError, MissingMainStuffError, PipelineExecuteTimeoutError, RunFailedError, RunTimeoutError, RunStillRunningError, RunLifecycleUnavailableError, InputPreparationError, EmptyMethodSourceError, InvalidLocalSourceError, RejectedAssetError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, } from "./errors.js";
+export { summarizeUsage } from "./usage.js";
+export type { PipeUsageSummary, RunUsagePair, UsageSummary, UsageSummaryState, UsageTokenTotals, } from "./usage.js";
+export { ApiResponseError, ApiUnreachableError, ClientAuthenticationError, MissingMainStuffError, PipelineExecuteTimeoutError, RunFailedError, RunTimeoutError, RunStillRunningError, RunLifecycleUnavailableError, InputPreparationError, EmptyMethodSourceError, InvalidLocalSourceError, RejectedAssetError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, ArtifactOperationError, ArtifactAuthenticationError, ArtifactFetchError, ScopeUnavailableError, } from "./errors.js";

package/dist/index.js

@@ -7,7 +7,7 @@
  * errors. Consumers should import everything they need from `@pipelex/sdk`.
  */
 /** Package version. Kept in sync with `package.json` — enforced by `tests/index.test.ts`. */
-export const SDK_VERSION = "0.16.0";
+export const SDK_VERSION = "0.18.0";
 // ── Pure MTHDS Protocol surface (re-exported from the `mthds/protocol` subpath) ──
 // The standard's interface, wire models, request/options surface, abstract domain
 // shapes, and the protocol-base `PipelineRequestError`. Re-exported so apps have a
@@ -19,6 +19,11 @@ export { PipelexApiClient, DEFAULT_API_BASE_URL } from "./client.js";
 export { methodSourceToContents } from "./method-source.js";
 // The blocking `execute()` result — a `DictRunResultExecute` with a resolved `.main_stuff`.
 export { PipelexExecuteResult } from "./execute-result.js";
+// ── Artifacts (the download twin of input preparation) ──────────────
+// `collectArtifacts` and `artifactFilename` are pure and standalone; the network
+// operations (`resolveArtifacts` / `fetchArtifact` / `downloadArtifacts`) are client
+// methods, and only their public types and bounds travel with the barrel.
+export { collectArtifacts, artifactFilename, PIPELEX_STORAGE_SCHEME, BULK_RESOLVE_MAX_URIS, DEFAULT_ARTIFACT_MAX_BYTES, DEFAULT_ARTIFACT_TIMEOUT_MS, DEFAULT_DOWNLOAD_MAX_TOTAL_BYTES, DEFAULT_DOWNLOAD_CONCURRENCY, } from "./artifacts.js";
 // ── Offline codegen drift check (pure — no filesystem, no network, no key) ──
 // The CI half of the codegen trust chain: hand it a committed tree plus its
 // `codegen.lock` and it returns the structured drift verdict. Regeneration needs
@@ -26,6 +31,8 @@ export { PipelexExecuteResult } from "./execute-result.js";
 export { runCodegenCheck, isStampableArtifactPath, STAMPABLE_ARTIFACT_SUFFIXES, CodegenLockError, } from "./codegen-check.js";
 // ── Run lifecycle (hosted extension — NOT part of the protocol) ──────
 export { isTerminalRunStatus, isSuccessRunStatus } from "./runs.js";
+// ── Usage summary (pure — folds a run's usage pair into one null-aware reading) ──
+export { summarizeUsage } from "./usage.js";
 // ── Typed errors (PipelineRequestError rides the protocol re-export above) ──
-export { ApiResponseError, ApiUnreachableError, ClientAuthenticationError, MissingMainStuffError, PipelineExecuteTimeoutError, RunFailedError, RunTimeoutError, RunStillRunningError, RunLifecycleUnavailableError, InputPreparationError, EmptyMethodSourceError, InvalidLocalSourceError, RejectedAssetError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, } from "./errors.js";
+export { ApiResponseError, ApiUnreachableError, ClientAuthenticationError, MissingMainStuffError, PipelineExecuteTimeoutError, RunFailedError, RunTimeoutError, RunStillRunningError, RunLifecycleUnavailableError, InputPreparationError, EmptyMethodSourceError, InvalidLocalSourceError, RejectedAssetError, UnsupportedUploadCapabilityError, UploadAuthenticationError, UploadTransportError, ArtifactOperationError, ArtifactAuthenticationError, ArtifactFetchError, ScopeUnavailableError, } from "./errors.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6FAA6F;AAC7F,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC;AAEpC,oFAAoF;AACpF,kFAAkF;AAClF,mFAAmF;AACnF,wBAAwB;AACxB,cAAc,gBAAgB,CAAC;AAE/B,wEAAwE;AACxE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAYrE,+FAA+F;AAC/F,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,4FAA4F;AAC5F,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAyE3D,+EAA+E;AAC/E,4EAA4E;AAC5E,iFAAiF;AACjF,0EAA0E;AAC1E,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAiD5B,wEAAwE;AACxE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAWpE,+EAA+E;AAC/E,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,EACrB,2BAA2B,EAC3B,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,gCAAgC,EAChC,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,6FAA6F;AAC7F,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAC;AAEpC,oFAAoF;AACpF,kFAAkF;AAClF,mFAAmF;AACnF,wBAAwB;AACxB,cAAc,gBAAgB,CAAC;AAE/B,wEAAwE;AACxE,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAYrE,+FAA+F;AAC/F,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,4FAA4F;AAC5F,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAY3D,uEAAuE;AACvE,iFAAiF;AACjF,qFAAqF;AACrF,0EAA0E;AAC1E,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,qBAAqB,EACrB,0BAA0B,EAC1B,2BAA2B,EAC3B,gCAAgC,EAChC,4BAA4B,GAC7B,MAAM,gBAAgB,CAAC;AAgFxB,+EAA+E;AAC/E,4EAA4E;AAC5E,iFAAiF;AACjF,0EAA0E;AAC1E,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,2BAA2B,EAC3B,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAiD5B,wEAAwE;AACxE,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAWpE,oFAAoF;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAS5C,+EAA+E;AAC/E,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,qBAAqB,EACrB,2BAA2B,EAC3B,cAAc,EACd,eAAe,EACf,oBAAoB,EACpB,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,gCAAgC,EAChC,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,EACtB,2BAA2B,EAC3B,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,aAAa,CAAC"}

package/dist/models.d.ts

@@ -7,7 +7,7 @@
  * the `/v1/build/*` request/response models. Built on the protocol wire types
  * imported from the `mthds/protocol` subpath.
  */
-import type { InputForm, InvalidValidationReport, PipeIOContracts, RunResultExecute, RunResultStart, ValidationReport } from "mthds/protocol";
+import type { InputForm, OutputForm, InvalidValidationReport, PipeIOContracts, RunResultExecute, RunResultStart, ValidationReport } from "mthds/protocol";
 export interface DictStuff {
     concept: string;
     content: unknown;
@@ -82,6 +82,24 @@ export interface PipelexHostedToolingExtensions {
     /** A stored method's catalog id (`mt_…`) — hosted-only, resolved server-side. */
     method_id?: string;
 }
+/**
+ * The method selector the tooling routes take in place of inline contents: a
+ * `method_ref` address (server-resolved by the runner through the same fetch
+ * path as a `method_ref` run) OR a hosted `method_id` (platform-resolved) —
+ * never both. The tooling routes are stateless, so the strict XOR applies:
+ * exactly one of inline contents / `method_ref` / `method_id` per request.
+ *
+ * Lives here, beside the other wire shapes, rather than on the client: it is
+ * the request's shape, and `prepareInputs` composes a `validate` call of its own
+ * without importing the client back (which would close a module cycle).
+ */
+export type ValidateMethodSelector = {
+    method_ref: string;
+    method_id?: never;
+} | {
+    method_id: string;
+    method_ref?: never;
+};
 /** Per-pipe dry-run verdict in `validated_pipes[]` — mirror of pipelex's `DryRunStatus`. */
 export type DryRunStatus = "SUCCESS" | "FAILURE" | "SKIPPED";
 /** One entry of `PipelexValidationReport.validated_pipes` — `{pipe_ref, status}`. */
@@ -156,8 +174,38 @@ export interface PipelexValidationReport extends ValidationReport {
      * single call site that opts in.
      */
     input_form?: InputForm;
+    /**
+     * Per-pipe OUTPUT-form descriptors — the standard's `OutputForm` artifact, the twin of
+     * `input_form` on the other side of the pipe. One `field` rather than a list of them,
+     * carrying no `presence` and no `gating`, because a result is not a slot a caller
+     * fills. Keyed over the same `pipe_ref` set as `pipe_io_contracts`.
+     *
+     * Paired with that contract's `output.json_schema` it is everything a renderer needs to
+     * lay a run's result out without inspecting the payload — the descriptor says what the
+     * result IS, the schema names the property it arrives under. A consumer holding one but
+     * not the other is back to inferring the other from the value, which is the guessing
+     * these artifacts exist to end.
+     *
+     * OPTIONAL for the same reason as `input_form`: an opt-in structured view, requested
+     * through `views: ["output_form"]` and absent from any verdict that did not ask.
+     */
+    output_form?: OutputForm;
     /** Pipes the runtime may skip when an optional slot resolves absent. */
     liftable_pipes: LiftablePipeEntry[];
+    /**
+     * The qualified `pipe_ref` a caller gets by omitting the pipe selector on the run
+     * and build routes — the bundle's declared `main_pipe` qualified by its domain and,
+     * for a `method_ref` package, the manifest's `main_pipe` the way the runner's
+     * `resolve_requested_pipe` reads it. `null` when the closure declares none or
+     * several.
+     *
+     * OPTIONAL because it is younger than the report: a server that predates it sends
+     * nothing, and a consumer that needs a default (`prepareInputs`) reads it when
+     * present and falls back to the opaque `bundle_blueprint.main_pipe`. It exists so
+     * that descriptor consumers stop reading a blueprint this SDK types opaque on
+     * purpose.
+     */
+    default_pipe_ref?: string | null;
     /** Best-effort execution graph of the main pipe; `null` with no `main_pipe` or on degrade. */
     graph_spec: unknown;
     /** Per-pipe dry-run sweep outcomes. */

package/dist/prepare-inputs.d.ts

@@ -1,44 +1,71 @@
 /**
  * `prepareInputs` — signature-driven input preparation. Resolves the target
- * pipe's declared inputs via the explicit inputs template, interprets the
- * caller's inputs top-down against it, uploads the file-bearing values, and
- * returns rewritten inputs (canonical content carrying `pipelex-storage://` in
- * `url`) plus one upload record per prepared asset.
+ * pipe's declared inputs from the **input-form descriptor** on the validate
+ * report, interprets the caller's inputs top-down against it, uploads the
+ * file-bearing values, and returns rewritten inputs (canonical content carrying
+ * `pipelex-storage://` in `url`) plus one upload record per prepared asset.
+ *
+ * The method is named the same three ways every other method-taking operation
+ * takes it — inline `files`, a `method_ref` address, or a stored `method_id` —
+ * exactly one per call. All three are pass-throughs to `POST /v1/validate`,
+ * which resolves an address on the runner and an id on the platform, so nothing
+ * is expanded client-side.
  *
  * Per input, the caller may submit EITHER the **compact** value (a bare source /
- * canonical `{url}` content) OR the explicit `{ concept, content }` envelope that
- * `buildInputs({ explicit: true })` hands back — its `content` is interpreted
- * exactly as the compact value would be, and the envelope is preserved on output
- * (the `concept` annotation rides through; the runtime accepts it — see
- * `pipelex`'s `input_shaper.py` `_is_explicit` / `input_normalizer.py`).
+ * canonical `{url}` content) OR the explicit `{ concept, content }` envelope —
+ * its `content` is interpreted exactly as the compact value would be, and the
+ * envelope is preserved on output (the `concept` annotation rides through; the
+ * runtime accepts it — see `pipelex`'s `input_shaper.py` `_is_explicit` /
+ * `input_normalizer.py`).
  *
- * The classification mirrors the runtime: `pipelex`'s `input_normalizer` walks
- * Image/Document contents (recognized by their `url`-bearing shape, incl. nested
- * in structured content) and `resolve_uri` decides upload vs pass-through. The
- * declared signature comes from the explicit template (`buildInputs`,
- * `explicit: true`), whose canonical content shape is the classifier — the file
- * signal is a value that is a dict containing a `url` key. See the shared
- * behavior matrix (`wip/upload/behavior-matrix.md`) and `docs/input-preparation.md`.
+ * **The descriptor is the classifier, never the value's shape.** `input_form`
+ * (the MTHDS standard's artifact, opted into with `views: ["input_form"]`)
+ * states the kind at every depth — `document` / `image` mark a file position,
+ * `object` recurses through `fields`, `list` through `item`, everything else
+ * passes through. That is what makes an OPTIONAL nested file field prepare like
+ * a required one, and a `text` field merely *named* `url` stay untouched: both
+ * were misread while the signature came from the rendered inputs template, whose
+ * file signal was a `url`-bearing dict. See `docs/input-preparation.md` and the
+ * shared behavior matrix (`wip/upload/behavior-matrix.md`).
  */
-import type { BuildInputsResponse, MthdsFileItem } from "./models.js";
+import type { MthdsFileItem, PipelexValidationResult, ValidateMethodSelector } from "./models.js";
 import type { UploadCapableClient, UploadRecord } from "./upload.js";
-/**
- * What `prepareInputs` takes: the method closure (inline `files` — the
- * signature source), the target pipe, and the caller's compact inputs.
- *
- * `files` is the ONLY closure form here: preparation is a client-side walk over
- * the closure's signature, so there is no by-id (or by-address) leg to
- * delegate to a server. A stored method is expanded first —
- * `prepareInputs({ files: await client.getMethodClosure(methodId), … })`.
- */
-export interface PrepareInputsRequest {
-    /** The method closure — inline MTHDS files. This is the signature source. */
-    files: MthdsFileItem[];
-    /** The pipe to prepare inputs for, as a qualified `domain.pipe_code`; omit to default to the closure's `main_pipe`. */
+/** The shared half of the request: the target pipe and the caller's inputs. */
+export interface PrepareInputsBase {
+    /**
+     * The pipe to prepare inputs for, as a QUALIFIED `domain.pipe_code` ref. Omit
+     * it to default — see "Pipe selection" in `docs/input-preparation.md`. A bare
+     * `pipe_code` is refused: the descriptor is keyed by qualified refs, and search
+     * is a run-route affordance this helper deliberately does not grow. So is an
+     * `alias->domain.pipe_code` ref: the alias names a dependency package's pipe,
+     * which the descriptor does not describe (it covers the method's own pipes).
+     */
     pipe_ref?: string;
-    /** The caller's compact inputs (variable name → value). */
+    /** The caller's inputs (variable name → value), compact or explicit-envelope per input. */
     inputs: Record<string, unknown>;
 }
+/**
+ * How the method is named — exactly one of the three selectors, each pinning the
+ * other two to `never` so a second one is a compile error (the same XOR
+ * `ValidateMethodSelector` states for the tooling routes). All three reach the
+ * server as-is: `files` inline, `method_ref` resolved by the runner, `method_id`
+ * resolved by the platform.
+ */
+export type PrepareInputsClosure = {
+    files: MthdsFileItem[];
+    method_ref?: never;
+    method_id?: never;
+} | {
+    method_ref: string;
+    files?: never;
+    method_id?: never;
+} | {
+    method_id: string;
+    files?: never;
+    method_ref?: never;
+};
+/** What `prepareInputs` takes: one method selector, the target pipe, the caller's inputs. */
+export type PrepareInputsRequest = PrepareInputsBase & PrepareInputsClosure;
 /** The result of `prepareInputs`: rewritten inputs (copy-on-write) plus upload records. */
 export interface PreparedInputs {
     /** A copy of `inputs` with each file-bearing value rewritten to canonical content carrying `pipelex-storage://` in `url`. */
@@ -47,16 +74,15 @@ export interface PreparedInputs {
     uploads: UploadRecord[];
 }
 /**
- * The client surface `prepareInputs` needs: raw `upload` and the `buildInputs`
- * signature source.
+ * The client surface `prepareInputs` needs: raw `upload`, and `validate` as the
+ * signature source. Typed as the client's own `validate` signature so
+ * `PipelexApiClient` satisfies it structurally.
  */
 export interface PrepareCapableClient extends UploadCapableClient {
-    buildInputs(request: {
-        files: MthdsFileItem[];
-        pipe_ref?: string;
-        format?: "json";
-        explicit?: boolean;
-    }): Promise<BuildInputsResponse>;
+    validate(source: string[] | ValidateMethodSelector, allowSignatures?: boolean, mthdsSources?: string[], render?: string[], views?: string[], options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<PipelexValidationResult>;
 }
 /**
  * Prepare a pipe's inputs: upload local/byte/data-URL assets at the signature's
@@ -64,9 +90,12 @@ export interface PrepareCapableClient extends UploadCapableClient {
  * records. HTTP(S) URLs and existing `pipelex-storage://` URIs pass through
  * unchanged. All failures are raised before any run is created.
  *
- * The declared signature is resolved from the closure; a closure that does not
- * resolve throws {@link InputPreparationError}. No-verdict conditions from the
- * signature route (unknown `pipe_ref`, auth, server fault) surface as the build
- * route's `ApiResponseError`.
+ * The signature comes from one `POST /v1/validate` with `views: ["input_form"]`,
+ * whatever the selector — inline `files`, a `method_ref` the runner resolves, or
+ * a `method_id` the platform resolves. A closure that does not load, an unknown
+ * `pipe_ref`, no default pipe, or a report with no descriptor throw
+ * {@link InputPreparationError}; a no-verdict condition from the route (a
+ * malformed selector, an unknown or foreign-org id, no package at the address,
+ * auth, a server fault) surfaces as `ApiResponseError`, unchanged.
  */
 export declare function prepareInputs(client: PrepareCapableClient, request: PrepareInputsRequest): Promise<PreparedInputs>;