@pipelex/sdk 0.15.0 → 0.17.0

package/README.md

@@ -36,6 +36,15 @@ if (report.is_valid) {
   // also rides `pipe_output` on the blocking path).
   console.log(result.main_stuff);
 }
+
+// Or run a published method by address — resolved server-side (fetch at tag,
+// commit SHA recorded as provenance on the start ack). Requires pipelex-api >= 0.21.0;
+// on api.pipelex.com, availability follows the platform deploy that forwards it.
+const ack = await client.start({
+  method_ref: "github.com/Pipelex/methods/documents@v0.1.0",
+  inputs: { document: { url: "https://example.com/report.pdf" } },
+});
+console.log(ack.method_provenance); // { address, tag, commit_sha }
 ```
 
 ### Product routes

package/dist/client.d.ts

@@ -1,5 +1,5 @@
-import type { MTHDSProtocol, ModelCategory, ModelDeck, RunOptions, RunResultStart, StartOptions, VersionInfo } from "mthds/protocol";
-import type { BuildInputsRequest, BuildInputsResponse, BuildOutputRequest, BuildOutputResponse, BuildRunnerRequest, BuildRunnerResponse, CodegenRequest, CodegenResponse, ConceptRequest, ConceptResponse, DictPipeOutput, FormatResponse, InputsTemplateFormat, LintResponse, MthdsFileItem, PipeSpecRequest, PipeSpecResponse, PipelexValidationResult, ResolveRequest, ResolveResponse } from "./models.js";
+import type { MTHDSProtocol, ModelCategory, ModelDeck, RunOptions, StartOptions, VersionInfo } from "mthds/protocol";
+import type { BuildInputsRequest, BuildInputsResponse, BuildOutputRequest, BuildOutputResponse, BuildRunnerRequest, BuildRunnerResponse, CodegenRequest, CodegenResponse, ConceptRequest, ConceptResponse, DictPipeOutput, FormatResponse, LintResponse, MthdsFileItem, PipeSpecRequest, PipeSpecResponse, PipelexRunResultStart, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector } from "./models.js";
 import { type RunRead, type RunResults, type RunResultState, type WaitForResultOptions } from "./runs.js";
 import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, GatewayApiKey, GatewayApiKeyStatus, InvoiceView, Membership, MembershipsResponse, ListMethodsQuery, MethodData, MethodDeletionAccepted, MethodPage, MethodSummary, MethodWriteInput, OnboardingSubmission, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, PipelineRun, RunDetail, RunPage, PlanView, ResolvedStorageUrl, SubscriptionResponse, UpdateRunInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
 import type { UploadableAsset, UploadFileOptions, UploadRecord } from "./upload.js";
@@ -11,6 +11,37 @@ export interface MthdsFile {
     /** Optional provenance URI threaded into validation diagnostics. */
     uri?: string;
 }
+/**
+ * The Pipelex API's own run-source extension — the layer-2 argument the RUNNER
+ * itself resolves, beside the protocol's inline sources (`mthds_contents` and
+ * the bundle encodings). Served by any pipelex-api >= 0.21.0 deployment, bare
+ * or hosted (on `api.pipelex.com`, once the platform deploy carrying it lands).
+ *
+ * Named options rather than `extra` entries, for the same reason as the hosted
+ * extensions below: `extra` remains the escape hatch for an extension this
+ * client does not know about, never the way to pass one it does.
+ */
+export interface PipelexApiRunExtensions {
+    /**
+     * A published method's address — `github.com/<owner>/<repo>[/<selector>][@<tag>]`
+     * (e.g. `github.com/Pipelex/methods/documents@v0.1.0`). Resolved by the
+     * server: the repository is fetched at the tag (a bare address means the
+     * default branch at HEAD), the package is located by manifest identity, and
+     * the resolved commit SHA comes back as `method_provenance` on the response.
+     *
+     * A complete run source of its own — the fetched package carries its `.mthds`
+     * and its entry pipe — so it pairs with NOTHING: exclusive with inline
+     * `mthds_contents`, with a method bundle (`files` / `bundle_b64`), and with
+     * the hosted `method_id` (an address run has its own provenance and needs no
+     * linkage id). `pipe_code` beside it is fine — it overrides the manifest's
+     * `main_pipe` to pick which pipe in the fetched package to run. This client
+     * rejects the illegal pairings before anything hits the wire, mirroring the
+     * server's own 422s.
+     *
+     * An empty string is treated as absent and is not sent.
+     */
+    method_ref?: string | null;
+}
 /**
  * The hosted API's own run arguments — the layer-3 extensions this client adds
  * on top of the MTHDS Protocol's run-argument surface (`RunOptions` /
@@ -38,40 +69,30 @@ export interface PipelexHostedRunExtensions {
      *   **run-history linkage** on the Run row. That linkage is what writes the
      *   index key `GET /v1/runs?method_id=` queries, so a run started without it
      *   is absent from its method's history permanently.
+     * - **Alongside `method_ref`** — rejected client-side (and a 422 on the
+     *   hosted API): an address run carries its own provenance, so it takes no
+     *   linkage id.
      *
      * An empty string is treated as absent and is not sent.
      */
     method_id?: string | null;
 }
-/** `execute()` options — the protocol's run arguments plus the hosted extensions. */
-export type PipelexRunOptions = RunOptions & PipelexHostedRunExtensions;
+/** `execute()` options — the protocol's run arguments plus the Pipelex API and hosted extensions. */
+export type PipelexRunOptions = RunOptions & PipelexApiRunExtensions & PipelexHostedRunExtensions;
 /** `start()` / `startAndWaitForResult()` options — the same, for the durable path. */
-export type PipelexStartOptions = StartOptions & PipelexHostedRunExtensions;
+export type PipelexStartOptions = StartOptions & PipelexApiRunExtensions & PipelexHostedRunExtensions;
 /**
- * The by-id alternative to the wire model `BuildInputsRequest`: resolve the
- * closure from a stored method's `method_id` instead of inline `files`.
- *
- * Client-side sugar — `method_id` is resolved to `files` via `getMethodClosure`
- * before the request hits the wire, so it never travels as a wire field (and is
- * distinct from `BuildRequestBase.method_ref`, the reserved registry ref). Supply
- * a `method_id` OR inline `files`, never both.
+ * The method selector `validate()` takes in place of inline contents — declared
+ * beside the other wire shapes in `./models.js` and re-exported here, the import
+ * path consumers have always used.
  */
-export interface BuildInputsByMethodId {
-    /** A stored method's id — resolved client-side to its closure before the build call. Requires an API key. */
-    method_id: string;
-    files?: never;
-    method_ref?: never;
-    /** The pipe to project, as a qualified `domain.pipe_code`; omit to default to the closure's `main_pipe`. */
-    pipe_ref?: string;
-    format?: InputsTemplateFormat;
-    explicit?: boolean;
-}
+export type { ValidateMethodSelector };
 export interface ValidateFilesOptions {
     /** Whether unresolved pipe signatures are accepted as pending instead of invalid. */
     allowSignatures?: boolean;
     /** Optional validate presentation hints, e.g. ["markdown"]. */
     render?: string[];
-    /** Optional structured-view opt-in tokens, e.g. ["input_form"]; sent only when given. */
+    /** Optional structured-view opt-in tokens, e.g. ["input_form", "output_form"]; sent only when given. */
     views?: string[];
     /** Per-call request ceiling; defaults to the 20-min execute ceiling. */
     timeoutMs?: number;
@@ -159,14 +180,17 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
     /**
      * Start a method asynchronously — `POST /v1/start` (202, no output yet).
      *
-     * The hosted `method_id` is a named option (see `PipelexHostedRunExtensions`);
-     * `options.extra` stays the generic passthrough for extension args this client
-     * does not know about — the server you call defines and handles them
-     * (including a client-supplied run id where a server supports one). The
-     * returned `pipeline_run_id` is always authoritative; on a hosted deployment
-     * it is durable — poll `getRunStatus` / `getRunResult`.
+     * The `method_ref` address and the hosted `method_id` are named options (see
+     * `PipelexApiRunExtensions` / `PipelexHostedRunExtensions`); `options.extra`
+     * stays the generic passthrough for extension args this client does not know
+     * about — the server you call defines and handles them (including a
+     * client-supplied run id where a server supports one). The returned
+     * `pipeline_run_id` is always authoritative; on a hosted deployment it is
+     * durable — poll `getRunStatus` / `getRunResult`. A `method_ref` run's ack
+     * additionally carries `method_provenance` — the address, the tag, and the
+     * commit SHA that was actually fetched.
      */
-    start(options: PipelexStartOptions): Promise<RunResultStart>;
+    start(options: PipelexStartOptions): Promise<PipelexRunResultStart>;
     /**
      * Parse, validate, and dry-run an MTHDS bundle — `POST /v1/validate`.
      *
@@ -178,11 +202,32 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * *no-verdict* condition (a malformed request, an `mthds_sources` length mismatch,
      * auth, a server fault) is non-2xx and surfaces as `ApiResponseError`.
      *
-     * `mthdsSources` (optional, parallel to `mthdsContents`) names each submitted
+     * `source` selects WHAT is validated, in exactly one of three forms — the
+     * strict tooling XOR (the routes are stateless, so there is no linkage
+     * exception; a second selector is a request-shape `422`):
+     *
+     * - **inline contents** (a `string[]`) — the protocol's own envelope;
+     * - **`{ method_ref }`** — a published method's address, resolved by the
+     *   server (pipelex-api >= 0.21.0) through the same fetch path as a
+     *   `method_ref` run, the package's real file names feeding the diagnostics'
+     *   source labels;
+     * - **`{ method_id }`** — a stored method's catalog id, hosted-only: the
+     *   platform resolves it and injects the stored source before the runner sees
+     *   the request (a bare runner rejects the request as carrying no source it
+     *   understands).
+     *
+     * A selector-resolution failure (fetch failure, no package at the address, an
+     * unknown or foreign-org id) is a non-2xx `ApiResponseError` — never an
+     * `is_valid: false` verdict, which is reserved for actual MTHDS content.
+     *
+     * `mthdsSources` (optional, parallel to inline contents) names each submitted
      * content — a Pipelex-API extension threaded onto `blueprint.source`, so
      * cross-file diagnostics name the owning file (an unnamed content yields
      * `source: null`). The server 422s a length mismatch; this client sends the
-     * arrays verbatim and surfaces that as an `ApiResponseError`.
+     * arrays verbatim and surfaces that as an `ApiResponseError`. It is an
+     * inline-contents companion only: a `method_ref` / `method_id` validation gets
+     * its source labels from the package's (or the stored method's) real file
+     * names, so supplying it beside a selector is rejected client-side.
      *
      * `render` is the Pipelex-API presentation hint — a list of view-format tokens.
      * This client always asks for Markdown so both valid results and produced
@@ -192,7 +237,7 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * `views` is the sibling opt-in for *structured* views where `render` carries
      * *rendered text*. The two lists are independent, each resolving its own tokens
      * against its own supported set, and each supported token adds a same-named
-     * top-level field to the valid arm — today only `input_form`. Unlike `render`,
+     * top-level field to the valid arm — `input_form` and `output_form`. Unlike `render`,
      * this client sends `views` ONLY when the caller asks: the point of an opt-in view
      * is that the default response stays byte-identical, and the highest-frequency
      * consumers (hook pipelines, CI gates, agent loops) never pay for bytes they
@@ -200,8 +245,17 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * runner resolved no token (the key is silently ignored, never a 422) and emitted
      * the field regardless — which is why `PipelexValidationReport.input_form` is typed
      * optional rather than required.
+     *
+     * 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
+     * fetch-sized budget (`METHOD_REF_FETCH_TIMEOUT_MS`, three minutes) that
+     * `crateRequestTimeoutMs` gives the crate routes several times over. That budget
+     * exists to RAISE routes whose default is the ~30s poll ceiling; applying it here
+     * would lower this one — which is why `buildRunner`, on its own five-minute
+     * default, is excluded from it for the same reason.
      */
-    validate(mthdsContents: string[], allowSignatures?: boolean, mthdsSources?: string[], render?: string[], views?: string[], options?: {
+    validate(source: string[] | ValidateMethodSelector, allowSignatures?: boolean, mthdsSources?: string[], render?: string[], views?: string[], options?: {
         timeoutMs?: number;
         signal?: AbortSignal;
     }): Promise<PipelexValidationResult>;
@@ -251,7 +305,8 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * The mapping is what makes their no-verdict arms usable: a crate-family route
      * answers `422` for a request it cannot act on (an unresolvable pipe selector on the
      * build routes; an unknown `kind`/`target`, or a `pipe_ref` on the concept-set-wide
-     * `types` kind, on `codegen`) and `501` for the reserved `method_ref`. A caller
+     * `types` kind, on `codegen`) and `501` for the reserved registry-form `method_ref`
+     * (the address form is resolved server-side as of pipelex-api 0.21.0). A caller
      * branches on `ApiResponseError.status`, never on a message.
      *
      * All of these are inference-free, so they default to the management-call timeout.
@@ -298,10 +353,15 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * Returns a **200 verdict**: pattern-match `is_valid` before reading the arm — a
      * closure that does not parse/load/validate comes back as `is_valid: false` with
      * `validation_errors[]`, not as a thrown error. Only a no-verdict condition throws
-     * `ApiResponseError`: a malformed selector (neither or both of `files`/`method_ref`)
-     * is a 422, and the reserved `method_ref` is a `501` until the server-side method
-     * registry lands. To resolve a STORED method today, expand it first:
-     * `resolve({ files: await client.getMethodClosure(methodId) })`.
+     * `ApiResponseError`: a malformed selector (none, or more than one, of
+     * `files` / `method_ref` / `method_id`) is a 422; a selector-resolution failure
+     * (fetch failure, no package at the address, an unknown or foreign-org id) is
+     * non-2xx too — never an `is_valid: false` verdict.
+     *
+     * The closure arrives in exactly one of three forms: inline `files`, an
+     * address-form `method_ref` (server-resolved, pipelex-api >= 0.21.0; the
+     * registry form stays a `501`), or a hosted `method_id` (platform-resolved —
+     * see {@link PipelexHostedToolingExtensions}).
      */
     resolve(request: ResolveRequest): Promise<ResolveResponse>;
     /**
@@ -314,9 +374,10 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * local `pipelex codegen types` run, so the offline `pipelex codegen check` passes on
      * it; the SDK deliberately does not write files for you.
      *
-     * Same 200-verdict discipline as {@link resolve}. Only a no-verdict condition throws
-     * `ApiResponseError`: an unknown `kind`/`target`, a `pipe_ref` on the concept-set-wide
-     * `types` kind, or a malformed selector is a 422; `method_ref` is a `501`.
+     * Same 200-verdict discipline and same three-form closure selector as
+     * {@link resolve}. Only a no-verdict condition throws `ApiResponseError`: an
+     * unknown `kind`/`target`, a `pipe_ref` on the concept-set-wide `types` kind, or
+     * a malformed selector is a 422; a registry-form `method_ref` is a `501`.
      */
     codegen(request: CodegenRequest): Promise<CodegenResponse>;
     /**
@@ -331,14 +392,22 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * unresolvable closure comes back as `is_valid: false` with `validation_errors[]`,
      * not as a thrown error.
      *
-     * Accepts the closure as inline `files` (the wire model {@link BuildInputsRequest}),
-     * as a reserved `method_ref` (also on {@link BuildInputsRequest} — still `501`s,
-     * same as `buildOutput`/`buildRunner`), or as a stored {@link BuildInputsByMethodId}
-     * — the by-id form is resolved to `files` via {@link getMethodClosure} before the
-     * request hits the wire (an empty source throws `EmptyMethodSourceError`; an
-     * unknown/foreign id, the `getMethod` 404). Supply exactly one of the three.
+     * Accepts the closure as inline `files` or as a `method_ref` (both on the wire
+     * model {@link BuildInputsRequest}; the address form is server-resolved, the
+     * registry form `501`s) — exactly one of the two, like `buildOutput` /
+     * `buildRunner`. There is NO by-id form: the build routes take no `method_id`
+     * (the hosted tooling selector covers `validate`/`resolve`/`codegen` only), so a
+     * stored method is expanded first — `buildInputs({ files: await
+     * client.getMethodClosure(methodId) })`. That expansion stays the answer here
+     * because a `buildInputs` caller wants this route's template; it is not what
+     * `prepareInputs` does any more.
+     *
+     * Nothing inside this SDK calls this route: `prepareInputs` reads its signature
+     * from the input-form descriptor on the validate report. It survives for the
+     * consumers that still render a template over HTTP, and is retired with the rest
+     * of `/v1/build/*` once they project it client-side.
      */
-    buildInputs(request: BuildInputsRequest | BuildInputsByMethodId): Promise<BuildInputsResponse>;
+    buildInputs(request: BuildInputsRequest): Promise<BuildInputsResponse>;
     /**
      * Project a pipe's output concept — `POST /v1/build/output`. Same envelope and
      * same 200-verdict discipline as {@link buildInputs}. `format: "schema"` (the
@@ -463,6 +532,13 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * with `methodSourceToContents`, and labels each resulting file with the
      * `method_id` as its `source` provenance.
      *
+     * This is the LOCAL expansion utility — for callers that want the files in
+     * hand (to edit, to diff, to feed a route with no by-id form, the `/v1/build/*`
+     * family being the last of those). The operations that accept `method_id`
+     * natively (`execute`/`start`, `validate`/`resolve`/`codegen`, and
+     * `prepareInputs`, which composes a `validate` of its own) take the id as a
+     * pass-through instead; nothing in this client expands an id behind your back.
+     *
      * 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 source
@@ -573,10 +649,20 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
      * file-bearing assets, and return copy-on-write rewritten inputs (canonical
      * content carrying `pipelex-storage://` in `url`) plus one upload record per
      * prepared asset. HTTP(S) URLs and existing `pipelex-storage://` URIs pass
-     * through unchanged; all failures are raised before any run is created. The
-     * caller supplies the method closure EITHER as inline `files` OR as a stored
-     * `method_id` (resolved to its closure via `getMethodClosure` first; requires
-     * an API key). See `docs/input-preparation.md`.
+     * through unchanged; all failures are raised before any run is created.
+     *
+     * Name the method exactly one of three ways, all server-resolved through the
+     * one `validate` call this composes:
+     *
+     * - `files` — the inline MTHDS closure;
+     * - `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).
+     *
+     * The signature itself is the input-form descriptor on the validate report
+     * (`views: ["input_form", "output_form"]`), which states the kind of every input at every
+     * depth — so a file position is a fact of the method, never a guess from the
+     * value's shape. See `docs/input-preparation.md`.
      */
     prepareInputs(request: PrepareInputsRequest): Promise<PreparedInputs>;
     /**
@@ -633,12 +719,14 @@ export declare class PipelexApiClient implements MTHDSProtocol<DictPipeOutput> {
     updateRun(runId: string, input: UpdateRunInput): Promise<void>;
     /**
      * Blocking `POST /v1/execute` adapted onto `RunResults` — the bare-runner
-     * path. Forwards every protocol field PLUS both extension surfaces: the
-     * hosted `method_id` and the generic `extra` passthrough. An extension-only
-     * call (`{ extra }` with no pipe_code/bundle) or a vendor selector riding
-     * `extra` must survive this path, not just the durable one — and a hosted
-     * `method_id` must reach the server here too, so a runner that cannot resolve
-     * it says so (Rule 4) instead of the client silently dropping it.
+     * path. Forwards every protocol field PLUS every extension surface: the
+     * runner-resolved `method_ref`, the hosted `method_id`, and the generic
+     * `extra` passthrough. An extension-only call (`{ extra }` with no
+     * pipe_code/bundle) or a vendor selector riding `extra` must survive this
+     * path, not just the durable one — a `method_ref` run must run the same
+     * fetched package here, and a hosted `method_id` must reach the server too,
+     * so a runner that cannot resolve it says so (Rule 4) instead of the client
+     * silently dropping it.
      */
     private executeBlocking;
 }