@pipelex/sdk 0.62.0 → 0.64.0

package/README.md

@@ -178,10 +178,34 @@ const copy = await client.copyMethod(
 );
 if (copy.outcome === "copied") console.log(copy.method.copied_from); // the original it names
 
+// Store a layout a producer designed for one pipe of a published version, over that version's
+// tree; a write of the same tree, pipe, catalog and prompt hash replaces it. A validate by
+// method_id naming `layouts` then carries the layouts beside the descriptor, newest first, and
+// leaves `layouts` out when there are none: render the plain form then.
+const v1 = await client.getMethodVersion(created.method_id, 1);
+const layoutKey = crypto.randomUUID(); // one key per layout, sent again unchanged on each retry
+await client.storeMethodLayout(created.method_id, 1, {
+  tree_digest: v1.tree_digest!,
+  pipe_ref: "greeting.greet",
+  catalog: "composer",
+  prompt_hash: "a1b2c3d4e5f6",
+  jsonl: '{"op":"add","path":"/root","value":"page"}',
+  provenance: { producer: "pipelex-method", model: "claude-4.8-opus", style: "editorial" },
+}, { idempotencyKey: layoutKey });
+const laidOut = await client.validate({ method_id: `${created.method_id}@1` }, false, {
+  views: ["input_form", "layouts"],
+});
+if (laidOut.is_valid) console.log(laidOut.layouts?.map((layout) => layout.catalog) ?? "plain form");
+
 // The template catalog: the public methods every organization reads, in the platform's order, with
-// the categories that have a template and each card's thumbnails behind short-lived links.
+// the categories that have a template and each card's thumbnails behind short-lived links. A
+// category's `labels` name it by language tag and may lack a language, in which case a client
+// shows `label`, the English one.
 const templates = await client.listMethodTemplates({ category: "human-resources", limit: 8 });
-for (const tab of templates.categories) console.log(tab.slug, tab.label);
+for (const tab of templates.categories) console.log(tab.slug, tab.labels.fr ?? tab.label);
+// The catalog's whole list of categories, a category no template shows included.
+const { categories } = await client.listMethodCategories();
+console.log(categories.map((category) => category.slug));
 // Another organization's public method reads in a narrower shape, its latest published version
 // and no draft: `updated_at` is what tells it from one of your own.
 const first = templates.items[0];
@@ -297,7 +321,8 @@ These pages ship inside the published package, so a reader who has only installe
 | [`docs/files.md`](./docs/files.md) | An organization's files: `listFiles` and `iterateFiles`, the row, the whole record and its provenance, the query and its repeated filters, paging through filtered pages, one file and its uses, the records of an address, the rename rule, links that name the file, a zip of files and its caps, a run's files, the copy into a method's draft, and an upload recorded as a method's test file with the refusals that come with it |
 | [`docs/method-examples.md`](./docs/method-examples.md) | A method's saved examples: the create, the paged list and its iterator, the edit that raises the input revision, the latest-run write and its `recorded` or `stale` verdict, the build assistant's save and its `kept` or `created` verdict, how an integer past `Number.MAX_SAFE_INTEGER` in the inputs stays exact, and what is refused before sending |
 | [`docs/method-copy.md`](./docs/method-copy.md) | Copying a method into another organization or duplicating it: what a copy holds and the stored files it copies, the `copied` or `refused` verdict, every refusal, the copy's idempotency key, and `copied_from` |
-| [`docs/public-methods.md`](./docs/public-methods.md) | Public methods and the template catalog: `listMethodTemplates` and its iterator, the ordering, the categories and the thumbnails' links, another organization's public method read in its narrower shape, the copy of a public method, `visibility` and `categories` on a method, and the refusals a public method's publish adds |
+| [`docs/method-layouts.md`](./docs/method-layouts.md) | A method's stored layouts: `storeMethodLayout`, which stores a layout designed for one pipe of a published version, its closed body and its refusals, the layout and its provenance, and the `layouts` a validate by `method_id` carries when `views` names `layouts`, absent when there are none |
+| [`docs/public-methods.md`](./docs/public-methods.md) | Public methods and the template catalog: `listMethodTemplates` and its iterator, the ordering, the categories with their labels by language and `listMethodCategories`, the thumbnails' links, another organization's public method read in its narrower shape, the copy of a public method, `visibility` and `categories` on a method, and the refusals a public method's publish adds |
 | [`docs/organization-branding.md`](./docs/organization-branding.md) | An organization's logos, colours, app style and typeface, and its white-label entitlement: `getBranding`, which every member and API key reads, `updateOrganizationBranding`, a write by the `admin` or the `member` role that sets, clears or keeps each key, and how a refused logo, colour, style or typeface names its field so a settings screen shows the sentence under it |
 | [`docs/exact-integers.md`](./docs/exact-integers.md) | Which reads keep an integer past `Number.MAX_SAFE_INTEGER` exact, as a `bigint` (a run's inputs and outputs, an example's inputs), how a request body writes it back with its digits, and `parseExactJson` and `stringifyExactJson` for code showing such data as JSON text |
 | [`docs/crate-routes.md`](./docs/crate-routes.md) | `resolve`, `codegen` and `pipeIo` — the method's tree as the protocol's `files` map, with its dependencies, the normalized crate, the stamped types, and a method's I/O artifacts without a validation — and the offline `runCodegenCheck` that guards a committed tree |

package/dist/cli/script.d.ts

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

package/dist/client.d.ts

@@ -1,7 +1,8 @@
 import type { MTHDSProtocol, ModelCategory, ModelDeck, RunOptions, StartOptions, VersionInfo } from "mthds/protocol";
-import type { CodegenRequest, CodegenResponse, CrateRouteOptions, DictPipeOutput, FormatResponse, LintResponse, ModelCheckCategory, ModelReferenceVerdict, PipeIORequest, PipeIOResponse, PipelexRunResultStart, PipelexValidateSource, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector } from "./models.js";
+import type { CodegenRequest, CodegenResponse, CrateRouteOptions, DictPipeOutput, FormatResponse, LintResponse, ModelCheckCategory, ModelReferenceVerdict, PipeIORequest, PipeIOResponse, PipelexRunResultStart, PipelexValidateSource, PipelexValidationResult, ResolveRequest, ResolveResponse, ValidateMethodSelector, ValidateView } from "./models.js";
+import type { MethodLayout, MethodLayoutInput } from "./method-layouts.js";
 import { type GetRunResultOptions, type RunProgress, type RunRead, type RunResults, type RunResultState, type StartAndWaitForResultOptions, type WaitForResultOptions } from "./runs.js";
-import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, DraftFileFromFileInput, DraftFileFromFileResult, FileArchive, FileArchiveRequest, FileDetail, FileLinkTarget, FileLinksResult, FilePage, FileRecord, FileRecordList, FileRenameInput, FileSummary, GetFileQuery, GetFilesByUriOptions, InvoiceView, Membership, MembershipsResponse, OrganizationBranding, OrganizationBrandingUpdate, ListFilesQuery, ListMethodExamplesQuery, ListMethodsQuery, ListMethodTemplatesQuery, ListMethodVersionsQuery, ListRunFilesQuery, MethodCopyInput, MethodCopyResult, MethodData, MethodDeletionAccepted, MethodDetail, MethodDraftInput, MethodExample, MethodExampleAssistantSaveInput, MethodExampleAssistantSaveResult, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunResult, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodTemplate, MethodTemplatePage, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PublicMethodDetail, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunFilesPage, RunPage, PlanView, ResolvedStorageUrl, SavedMethodFile, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
+import type { BillingPortalResponse, ChangePlanResponse, CheckoutResponse, DraftFileFromFileInput, DraftFileFromFileResult, FileArchive, FileArchiveRequest, FileDetail, FileLinkTarget, FileLinksResult, FilePage, FileRecord, FileRecordList, FileRenameInput, FileSummary, GetFileQuery, GetFilesByUriOptions, InvoiceView, Membership, MembershipsResponse, OrganizationBranding, OrganizationBrandingUpdate, ListFilesQuery, ListMethodExamplesQuery, ListMethodsQuery, ListMethodTemplatesQuery, ListMethodVersionsQuery, ListRunFilesQuery, MethodCategoryList, MethodCopyInput, MethodCopyResult, MethodData, MethodDeletionAccepted, MethodDetail, MethodDraftInput, MethodExample, MethodExampleAssistantSaveInput, MethodExampleAssistantSaveResult, MethodExampleCreateInput, MethodExampleLatestRunInput, MethodExampleLatestRunResult, MethodExamplePage, MethodExampleUpdateInput, MethodPage, MethodPublishInput, MethodPublishResult, MethodRenameInput, MethodSummary, MethodTemplate, MethodTemplatePage, MethodVersion, MethodVersionPage, MethodWriteInput, OnboardingSubmission, PublicMethodDetail, PipelexApiKeyCreated, PipelexApiKeyList, ListRunsQuery, RunHistoryItem, RunDetail, RunFilesPage, RunPage, PlanView, ResolvedStorageUrl, SavedMethodFile, SubscriptionResponse, UpdateRunInput, UploadGrant, UploadGrantInput, UploadInput, UploadedFile, UserProfile } from "./product-models.js";
 import type { MethodTreeForms, MethodTreeLimits } from "./method-trees.js";
 import type { AppInfo } from "./user-agent.js";
 import type { WebhookDeliveryDetail, WebhookDeliveryList, WebhookReplayAccepted, WebhookReplayOptions, WebhookSecret, WebhookSecretRotateOptions } from "./webhooks.js";
@@ -173,6 +174,32 @@ export interface MethodCopyRequestOptions {
      */
     idempotencyKey?: string | null;
 }
+/** Options for `storeMethodLayout`. */
+export interface MethodLayoutWriteOptions {
+    /**
+     * The write's idempotency key, sent as the `Idempotency-Key` header of
+     * `POST /v1/methods/{id}/versions/{n}/layouts`, and not sent at all when absent or `null`.
+     * Generate one per layout the caller means to store (a `crypto.randomUUID()` is a good key), and
+     * keep it, with the arguments unchanged, across that write's retries.
+     *
+     * A write sent again without a key runs again: it stamps the layout with a new `stored_at`, which
+     * moves it ahead of every layout stored since in the newest-first order, and applies the bound
+     * again, so a layout another producer stored meanwhile, a newer prompt of the same pipe and
+     * catalog included, can be the one removed. Under the same key the hosted API answers the retry
+     * with the first write's stored answer and runs nothing, so a write whose answer was lost, as on
+     * a client timeout, can be sent again unchanged. The write's `200` and its `4xx` refusals are
+     * stored alike; a `5xx` and a refusal for its timing (a `408`, `425` or `429`) are not, so the
+     * same key sends the write afresh. The same key with a different body is refused (`409`
+     * `request.idempotency_conflict`, whose `retry` is `no`), as is a key whose earlier request is
+     * still being handled (`409` `request.idempotency_key_in_use`, whose `retry` is `yes`); these
+     * two are the key's own answers and are never stored, so a retry after the second runs as the
+     * key's first request would.
+     *
+     * A key is held to the rule a start's is (`PipelexStartRequestOptions.idempotencyKey`): 1 to
+     * 255 visible ASCII characters, anything else a `RequestArgumentError` before any request.
+     */
+    idempotencyKey?: string | null;
+}
 /**
  * `start()` / `startAndWaitForResult()` options — the same, for the durable path, plus the start
  * request's own `idempotencyKey`.
@@ -191,8 +218,13 @@ export interface ValidateOptions {
      * `"markdown"`, so both arms carry `rendered_markdown`.
      */
     render?: string[];
-    /** Structured-view opt-in tokens, e.g. `["input_form", "output_form"]`; sent only when given. */
-    views?: string[];
+    /**
+     * Structured-view opt-in tokens, e.g. `["input_form", "output_form"]`, or
+     * `["input_form", "layouts"]` for a stored method's descriptor and the layouts over it; sent
+     * verbatim, and only when given. A token this SDK does not know (`ValidateView`) is sent as its
+     * raw string.
+     */
+    views?: (ValidateView | (string & {}))[];
     /**
      * Per-call request ceiling; defaults to the 20-min execute ceiling. A positive number
      * no larger than 2147483647, the longest delay a timer honours, else a `RangeError`.
@@ -284,8 +316,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `url` is a fully resolved absolute URL. `mayStartRun` marks a request that may create a run,
      * whose errors then say whether it may have (see `RunCreation`).
      * `idempotencyKey`, already checked by `idempotencyKeyOf`, is sent as the
-     * `Idempotency-Key` header; only `start`, `copyMethod`, `rotateWebhookSecret` and
-     * `replayRunWebhookDelivery` pass one.
+     * `Idempotency-Key` header; only `start`, `copyMethod`, `storeMethodLayout`,
+     * `rotateWebhookSecret` and `replayRunWebhookDelivery` pass one.
      */
     private requestRaw;
     /**
@@ -565,7 +597,10 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * `options.views` is the sibling opt-in for *structured* views where `render`
      * carries *rendered text*. The two lists are independent, each resolving its own
      * tokens against its own supported set, and each supported token adds a same-named
-     * top-level field to the valid arm — `input_form` and `output_form`. Unlike
+     * top-level field to the valid arm — `input_form` and `output_form`, and on a hosted
+     * validate by `method_id`, `layouts`, the layouts stored for the resolved tree
+     * (`PipelexValidationReport.layouts`, absent when there are none), each entry read as
+     * `storeMethodLayout`'s answer is and one that does not read as a layout left out. 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
@@ -996,8 +1031,8 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * unknown or malformed name serves `default`, and the page's `ordering` names the one served,
      * `null` when there is none. `category` keeps one category's templates, by slug, in the same
      * order; an unknown slug keeps none. Whatever the filter, the page's `categories` names, with its
-     * label, every category at least one template shows, in the catalog's order, so no tab drawn
-     * from it is ever empty.
+     * labels, every category at least one template shows, in the catalog's order, so no tab drawn
+     * from it is ever empty; `listMethodCategories` reads the whole list.
      *
      * Each `MethodTemplate` carries the method's id and name, its latest published version's number,
      * description and categories, its organization's display name and each thumbnail with its size
@@ -1007,17 +1042,18 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * Pass the page's `nextCursor` back as `cursor` with the same `ordering` and `category`, which the
      * cursor does not hold; `null` is the last page. `iterateMethodTemplates` follows it for you.
      *
-     * Throws `ApiResponseError`: `422` `request.invalid` for a `limit` outside 1 to 200 or a cursor of
-     * another listing, `422` `request.malformed` for a cursor that does not decode, `500`
-     * `runtime.misconfigured` when the templates organization the deployment names has no record or
-     * a link cannot be signed, and `503` `runtime.unavailable`, safe to retry. A page whose `items`
-     * or `categories` is not an array, whose `next_cursor` or `ordering` is neither a string nor
-     * `null`, a template lacking a member a card is drawn from (a string `method_id`, `name` and
-     * `organization_name`, a `description` that is a string or `null`, a positive integer
-     * `latest_version`, an array of string `categories`, and `thumbnails` each with a string `path`,
-     * `media_type`, `sha256`, `url` and `expires_at` and a positive integer `width` and `height`), and a
-     * category without a string `slug` and `label` are an answer the SDK cannot read, thrown as an
-     * `ApiResponseError` too, its links redacted.
+     * Throws `ApiResponseError`: `403` `pipelex.org.required` without an active organization, `422`
+     * `request.invalid` for a `limit` outside 1 to 200 or a cursor of another listing, `422`
+     * `request.malformed` for a cursor that does not decode, `500` `runtime.misconfigured` when the
+     * templates organization the deployment names has no record or a link cannot be signed, and
+     * `503` `runtime.unavailable`, safe to retry. A page whose `items` or `categories` is not an
+     * array, whose `next_cursor` or `ordering` is neither a string nor `null`, a template lacking a
+     * member a card is drawn from (a string `method_id`, `name` and `organization_name`, a
+     * `description` that is a string or `null`, a positive integer `latest_version`, an array of
+     * string `categories`, and `thumbnails` each with a string `path`, `media_type`, `sha256`, `url`
+     * and `expires_at` and a positive integer `width` and `height`), and a category without a string
+     * `slug` and `label` or whose `labels` is not an object of strings are an answer the SDK cannot
+     * read, thrown as an `ApiResponseError` too, its links redacted.
      */
     listMethodTemplates(query?: ListMethodTemplatesQuery): Promise<MethodTemplatePage>;
     /**
@@ -1028,6 +1064,23 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * read one page with `listMethodTemplates` when you need them.
      */
     iterateMethodTemplates(query?: Omit<ListMethodTemplatesQuery, "cursor">): AsyncGenerator<MethodTemplate, void, undefined>;
+    /**
+     * The catalog's whole list of categories — `GET /v1/method-categories`: every category an admin
+     * of the platform put on it, in the catalog's order, whether or not a template shows it, the same
+     * for every caller. Each `MethodCategory` carries its `slug`, the one a manifest declares, its
+     * English `label`, and its `labels` by language tag, which may lack a language the platform
+     * added after the category was stored; show `labels[locale] ?? label`.
+     *
+     * A template shows under the categories its manifest declares that are on this list, so this is
+     * the list a method's categories are picked from. `listMethodTemplates` names, on every page, only
+     * the categories some template shows, for the tabs a client draws.
+     *
+     * Throws `ApiResponseError`: `403` `pipelex.org.required` without an active organization, and
+     * `503` `runtime.unavailable`, safe to retry. An answer whose `categories` is not an array, or
+     * holds a category without a string `slug` and `label` or whose `labels` is not an object of
+     * strings, is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
+     */
+    listMethodCategories(): Promise<MethodCategoryList>;
     /**
      * Read one method with its files — `GET /v1/methods/{id}`. One of the caller's organization's
      * methods answers a `MethodDetail`: its identity, its draft
@@ -1354,6 +1407,51 @@ export declare class PipelexApiClient implements HostedProtocolSurface {
      * one, which names no tree to serve.
      */
     getMethodVersion(methodId: string, version: number): Promise<MethodVersion>;
+    /**
+     * Store a layout designed for one pipe of a published version of a method —
+     * `POST /v1/methods/{id}/versions/{n}/layouts` — and answer it as stored, with the `stored_at` the
+     * platform stamped.
+     *
+     * A layout is a data file a producer designed over the version's input-form descriptor, in the
+     * vocabulary of a catalog of components. The platform stores it beside the method, keyed by the
+     * content it was designed for, and hands it back on every validate of the method by `method_id`
+     * that names `layouts` among its `views` and resolves the same tree
+     * (`PipelexValidationReport.layouts`). It never produces, parses or judges one.
+     *
+     * `layout.tree_digest` must be the digest of the tree `version` holds, its
+     * `MethodVersionSummary.tree_digest`: a producer designs over the descriptor of the version it was
+     * handed. **A write of the same identity replaces the layout**, the identity being `tree_digest`,
+     * `pipe_ref`, `catalog` and `prompt_hash`, and is answered the same `200` whether it stored a new
+     * layout or replaced one. `options.idempotencyKey` is sent as the `Idempotency-Key` header, so a
+     * write whose answer was lost is sent again under the same key and answered as the first was; sent
+     * again without one, it runs again, with a new `stored_at` and the bound applied again
+     * (`MethodLayoutWriteOptions`). A content keeps at most 16
+     * layouts, every pipe, catalog and prompt hash together; past the bound a write removes first what
+     * newer prompts of the same pipe and catalog superseded (see `docs/method-layouts.md`).
+     *
+     * The write changes the method, so it takes an `admin` or a `member` of the method's
+     * organization. Takes a bare catalog id, as `getMethod` does, and the version number. Sends the
+     * members of `MethodLayoutInput` and nothing else, the route's body being closed at both levels,
+     * and leaves out each optional provenance member that is `null` or omitted, for the platform's
+     * default. Throws `RequestArgumentError` before any request for a `version` that is not a positive
+     * integer and for a `layout` or a `provenance` that is not an object; every other member is sent
+     * as given. Throws `ApiResponseError` when the platform refuses the write, which stores nothing:
+     * `422` `request.invalid` for a member breaking its shape or bound, naming it in `params.field`
+     * and `location.field` (`provenance.<member>` for one of the provenance's), and, naming
+     * `tree_digest`, for a digest that is not the tree the version holds; `403` `auth.forbidden`
+     * naming the `member` requirement for a `runner` or a caller with no recognised role; `404`
+     * `pipelex.catalog.not_found` for an unknown method or another organization's, its
+     * `params.resource` `method`, and for a version the method never published, its
+     * `params.resource` `version`; `409` `pipelex.catalog.being_deleted` while the method's erasure is
+     * pending, under way or stopped; and `500` `runtime.unexpected` for a version stored before
+     * methods were trees, which names no tree. Under an idempotency key, `409`
+     * `request.idempotency_conflict` for the key sent with a different body and `409`
+     * `request.idempotency_key_in_use` while its earlier request is still being handled; a key that is
+     * not 1 to 255 visible ASCII characters is a `RequestArgumentError` before any request. An answer
+     * that does not read as a layout (`methodLayoutFault`) is an answer the SDK cannot read, thrown as
+     * an `ApiResponseError` too.
+     */
+    storeMethodLayout(methodId: string, version: number, layout: MethodLayoutInput, options?: MethodLayoutWriteOptions): Promise<MethodLayout>;
     /**
      * Copy a method into an organization the caller may change methods in —
      * `POST /v1/methods/{id}/copy`: the method's own organization for a duplicate, another team, or

package/dist/client.js

@@ -2,6 +2,7 @@
 // source combinations are legal is an invariant of `RunRequest` itself, so this
 // client and the MTHDS runners cannot disagree about what they reject.
 import { assertOneMethodSource, buildProblem, isProblem, parseJsonBody, readProblemBody, } from "mthds/protocol";
+import { LAYOUT_INPUT_MEMBERS, PROVENANCE_INPUT_MEMBERS, methodLayoutFault, readMethodLayout, readMethodLayouts, } from "./method-layouts.js";
 import { assertArtifactSelection, assertWaitOptions, pollUntilResult, readRunDegradation, RUN_STATUSES, runProgressFault, runStatusFilter, selectionIncludesMainStuff, throwIfAborted, withCheckedProgressHealth, } from "./runs.js";
 import { ABORT_TIMEOUT, ApiResponseError, argumentInvalidProblem, ApiUnreachableError, MissingMainStuffError, PagingNotTerminatingError, PipelineExecuteTimeoutError, ProblemError, RequestArgumentError, RunLifecycleUnavailableError, RunStillRunningError, } from "./errors.js";
 import { isPlainObject } from "./records.js";
@@ -326,6 +327,19 @@ const COPY_DRAFT_TOKEN_ARGUMENT = {
     what: "an expected_draft_updated_at, the draft token the caller last read, the method's " +
         "`updated_at`, a string, or none",
 };
+/** What each argument of a layout write is, as a refusal of it names it. */
+const LAYOUT_VERSION_ARGUMENT = {
+    name: "version",
+    what: "a version number, the published version the layout was designed for, a positive integer",
+};
+const LAYOUT_ARGUMENT = {
+    name: "layout",
+    what: "the layout to store as an object, a MethodLayoutInput",
+};
+const LAYOUT_PROVENANCE_ARGUMENT = {
+    name: "provenance",
+    what: "the layout's provenance as an object naming at least its producer and its model",
+};
 /**
  * The refusal of an argument a call cannot take, worded as every such refusal is:
  * `<call>() takes <what>; got <got>.`, with what made it unusable as `cause` when there is one.
@@ -374,12 +388,16 @@ function requireNameAndInputs(name, inputs, call, needs) {
 }
 /**
  * A caller's value as the refusal of a number argument names it: a number by its value, anything
- * else by its type, as `requireNonEmptyId` names a value, and `null` as itself. Never by `String`,
- * which throws for an object with no prototype and would replace the refusal with a `TypeError`.
+ * else by its type, as `requireNonEmptyId` names a value, `null` as itself and an array as one, so
+ * a refusal of a value that is not an object never answers an array with "got object". Never by
+ * `String`, which throws for an object with no prototype and would replace the refusal with a
+ * `TypeError`.
  */
 function describeNumberArgument(value) {
     if (typeof value === "number")
         return String(value);
+    if (Array.isArray(value))
+        return "an array";
     return value === null ? "null" : typeof value;
 }
 /**
@@ -582,8 +600,8 @@ export class PipelexApiClient {
      * `url` is a fully resolved absolute URL. `mayStartRun` marks a request that may create a run,
      * whose errors then say whether it may have (see `RunCreation`).
      * `idempotencyKey`, already checked by `idempotencyKeyOf`, is sent as the
-     * `Idempotency-Key` header; only `start`, `copyMethod`, `rotateWebhookSecret` and
-     * `replayRunWebhookDelivery` pass one.
+     * `Idempotency-Key` header; only `start`, `copyMethod`, `storeMethodLayout`,
+     * `rotateWebhookSecret` and `replayRunWebhookDelivery` pass one.
      */
     async requestRaw(method, url, options = {}) {
         const hasBody = options.body !== undefined;
@@ -1181,7 +1199,10 @@ export class PipelexApiClient {
      * `options.views` is the sibling opt-in for *structured* views where `render`
      * carries *rendered text*. The two lists are independent, each resolving its own
      * tokens against its own supported set, and each supported token adds a same-named
-     * top-level field to the valid arm — `input_form` and `output_form`. Unlike
+     * top-level field to the valid arm — `input_form` and `output_form`, and on a hosted
+     * validate by `method_id`, `layouts`, the layouts stored for the resolved tree
+     * (`PipelexValidationReport.layouts`, absent when there are none), each entry read as
+     * `storeMethodLayout`'s answer is and one that does not read as a layout left out. 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
@@ -1239,7 +1260,7 @@ export class PipelexApiClient {
         if (res.status < 200 || res.status >= 300) {
             this.throwApiResponseError("POST", "validate", res);
         }
-        return withVerdictItems(this.readObjectAnswer("POST", "validate", res));
+        return withReadLayouts(withVerdictItems(this.readObjectAnswer("POST", "validate", res)));
     }
     // ── Tools extensions (Pipelex API — `/v1/lint`, `/v1/format`) ─────────
     //
@@ -1943,8 +1964,8 @@ export class PipelexApiClient {
      * unknown or malformed name serves `default`, and the page's `ordering` names the one served,
      * `null` when there is none. `category` keeps one category's templates, by slug, in the same
      * order; an unknown slug keeps none. Whatever the filter, the page's `categories` names, with its
-     * label, every category at least one template shows, in the catalog's order, so no tab drawn
-     * from it is ever empty.
+     * labels, every category at least one template shows, in the catalog's order, so no tab drawn
+     * from it is ever empty; `listMethodCategories` reads the whole list.
      *
      * Each `MethodTemplate` carries the method's id and name, its latest published version's number,
      * description and categories, its organization's display name and each thumbnail with its size
@@ -1954,17 +1975,18 @@ export class PipelexApiClient {
      * Pass the page's `nextCursor` back as `cursor` with the same `ordering` and `category`, which the
      * cursor does not hold; `null` is the last page. `iterateMethodTemplates` follows it for you.
      *
-     * Throws `ApiResponseError`: `422` `request.invalid` for a `limit` outside 1 to 200 or a cursor of
-     * another listing, `422` `request.malformed` for a cursor that does not decode, `500`
-     * `runtime.misconfigured` when the templates organization the deployment names has no record or
-     * a link cannot be signed, and `503` `runtime.unavailable`, safe to retry. A page whose `items`
-     * or `categories` is not an array, whose `next_cursor` or `ordering` is neither a string nor
-     * `null`, a template lacking a member a card is drawn from (a string `method_id`, `name` and
-     * `organization_name`, a `description` that is a string or `null`, a positive integer
-     * `latest_version`, an array of string `categories`, and `thumbnails` each with a string `path`,
-     * `media_type`, `sha256`, `url` and `expires_at` and a positive integer `width` and `height`), and a
-     * category without a string `slug` and `label` are an answer the SDK cannot read, thrown as an
-     * `ApiResponseError` too, its links redacted.
+     * Throws `ApiResponseError`: `403` `pipelex.org.required` without an active organization, `422`
+     * `request.invalid` for a `limit` outside 1 to 200 or a cursor of another listing, `422`
+     * `request.malformed` for a cursor that does not decode, `500` `runtime.misconfigured` when the
+     * templates organization the deployment names has no record or a link cannot be signed, and
+     * `503` `runtime.unavailable`, safe to retry. A page whose `items` or `categories` is not an
+     * array, whose `next_cursor` or `ordering` is neither a string nor `null`, a template lacking a
+     * member a card is drawn from (a string `method_id`, `name` and `organization_name`, a
+     * `description` that is a string or `null`, a positive integer `latest_version`, an array of
+     * string `categories`, and `thumbnails` each with a string `path`, `media_type`, `sha256`, `url`
+     * and `expires_at` and a positive integer `width` and `height`), and a category without a string
+     * `slug` and `label` or whose `labels` is not an object of strings are an answer the SDK cannot
+     * read, thrown as an `ApiResponseError` too, its links redacted.
      */
     async listMethodTemplates(query = {}) {
         const search = productQuery({
@@ -2010,6 +2032,35 @@ export class PipelexApiClient {
     async *iterateMethodTemplates(query = {}) {
         yield* followCursor("listMethodTemplates", (cursor) => this.listMethodTemplates({ ...query, cursor }));
     }
+    /**
+     * The catalog's whole list of categories — `GET /v1/method-categories`: every category an admin
+     * of the platform put on it, in the catalog's order, whether or not a template shows it, the same
+     * for every caller. Each `MethodCategory` carries its `slug`, the one a manifest declares, its
+     * English `label`, and its `labels` by language tag, which may lack a language the platform
+     * added after the category was stored; show `labels[locale] ?? label`.
+     *
+     * A template shows under the categories its manifest declares that are on this list, so this is
+     * the list a method's categories are picked from. `listMethodTemplates` names, on every page, only
+     * the categories some template shows, for the tabs a client draws.
+     *
+     * Throws `ApiResponseError`: `403` `pipelex.org.required` without an active organization, and
+     * `503` `runtime.unavailable`, safe to retry. An answer whose `categories` is not an array, or
+     * holds a category without a string `slug` and `label` or whose `labels` is not an object of
+     * strings, is an answer the SDK cannot read, thrown as an `ApiResponseError` too.
+     */
+    async listMethodCategories() {
+        const endpoint = "method-categories";
+        const res = await this.requestProductAnswer("GET", endpoint, undefined);
+        const list = this.readObjectAnswer("GET", endpoint, res);
+        const { categories } = list;
+        const fault = Array.isArray(categories)
+            ? methodCategoriesFault(categories)
+            : "`categories` is not an array";
+        if (fault !== null) {
+            throw this.unreadableAnswer("GET", `/${API_PREFIX}/${endpoint}`, res, `a list of categories whose ${fault}`);
+        }
+        return list;
+    }
     /**
      * Read one method with its files — `GET /v1/methods/{id}`. One of the caller's organization's
      * methods answers a `MethodDetail`: its identity, its draft
@@ -2605,6 +2656,66 @@ export class PipelexApiClient {
         const res = await this.requestProductAnswer("GET", endpoint, undefined);
         return this.readSavedTree("GET", endpoint, withLinks(res), "a published version");
     }
+    /**
+     * Store a layout designed for one pipe of a published version of a method —
+     * `POST /v1/methods/{id}/versions/{n}/layouts` — and answer it as stored, with the `stored_at` the
+     * platform stamped.
+     *
+     * A layout is a data file a producer designed over the version's input-form descriptor, in the
+     * vocabulary of a catalog of components. The platform stores it beside the method, keyed by the
+     * content it was designed for, and hands it back on every validate of the method by `method_id`
+     * that names `layouts` among its `views` and resolves the same tree
+     * (`PipelexValidationReport.layouts`). It never produces, parses or judges one.
+     *
+     * `layout.tree_digest` must be the digest of the tree `version` holds, its
+     * `MethodVersionSummary.tree_digest`: a producer designs over the descriptor of the version it was
+     * handed. **A write of the same identity replaces the layout**, the identity being `tree_digest`,
+     * `pipe_ref`, `catalog` and `prompt_hash`, and is answered the same `200` whether it stored a new
+     * layout or replaced one. `options.idempotencyKey` is sent as the `Idempotency-Key` header, so a
+     * write whose answer was lost is sent again under the same key and answered as the first was; sent
+     * again without one, it runs again, with a new `stored_at` and the bound applied again
+     * (`MethodLayoutWriteOptions`). A content keeps at most 16
+     * layouts, every pipe, catalog and prompt hash together; past the bound a write removes first what
+     * newer prompts of the same pipe and catalog superseded (see `docs/method-layouts.md`).
+     *
+     * The write changes the method, so it takes an `admin` or a `member` of the method's
+     * organization. Takes a bare catalog id, as `getMethod` does, and the version number. Sends the
+     * members of `MethodLayoutInput` and nothing else, the route's body being closed at both levels,
+     * and leaves out each optional provenance member that is `null` or omitted, for the platform's
+     * default. Throws `RequestArgumentError` before any request for a `version` that is not a positive
+     * integer and for a `layout` or a `provenance` that is not an object; every other member is sent
+     * as given. Throws `ApiResponseError` when the platform refuses the write, which stores nothing:
+     * `422` `request.invalid` for a member breaking its shape or bound, naming it in `params.field`
+     * and `location.field` (`provenance.<member>` for one of the provenance's), and, naming
+     * `tree_digest`, for a digest that is not the tree the version holds; `403` `auth.forbidden`
+     * naming the `member` requirement for a `runner` or a caller with no recognised role; `404`
+     * `pipelex.catalog.not_found` for an unknown method or another organization's, its
+     * `params.resource` `method`, and for a version the method never published, its
+     * `params.resource` `version`; `409` `pipelex.catalog.being_deleted` while the method's erasure is
+     * pending, under way or stopped; and `500` `runtime.unexpected` for a version stored before
+     * methods were trees, which names no tree. Under an idempotency key, `409`
+     * `request.idempotency_conflict` for the key sent with a different body and `409`
+     * `request.idempotency_key_in_use` while its earlier request is still being handled; a key that is
+     * not 1 to 255 visible ASCII characters is a `RequestArgumentError` before any request. An answer
+     * that does not read as a layout (`methodLayoutFault`) is an answer the SDK cannot read, thrown as
+     * an `ApiResponseError` too.
+     */
+    async storeMethodLayout(methodId, version, layout, options = {}) {
+        const call = "storeMethodLayout";
+        if (!Number.isSafeInteger(version) || version < 1) {
+            throw argumentRefusal(call, LAYOUT_VERSION_ARGUMENT, describeNumberArgument(version), "not_a_positive_integer");
+        }
+        const endpoint = `${methodPath(methodId, call)}/versions/${version}/layouts`;
+        const body = methodLayoutBody(layout, call);
+        const idempotencyKey = idempotencyKeyOf(options, "store the layout");
+        const res = await this.requestProductAnswer("POST", endpoint, body, { idempotencyKey });
+        const answer = this.readObjectAnswer("POST", endpoint, res);
+        const stored = readMethodLayout(answer);
+        if (stored === null) {
+            throw this.unreadableAnswer("POST", `/${API_PREFIX}/${endpoint}`, res, `a layout ${methodLayoutFault(answer) ?? "that is not one"}`);
+        }
+        return stored;
+    }
     /**
      * Copy a method into an organization the caller may change methods in —
      * `POST /v1/methods/{id}/copy`: the method's own organization for a duplicate, another team, or
@@ -4372,13 +4483,14 @@ const MAX_IDEMPOTENCY_KEY_LENGTH = 255;
  */
 const VISIBLE_ASCII = /^[\x21-\x7E]+$/;
 /**
- * The idempotency key a start, a method copy, a secret rotation or a delivery replay sends, or
+ * The idempotency key a start, a method copy, a layout write, a secret rotation or a delivery
+ * replay sends, or
  * `undefined` when the options carry none (absent or `null`). A key that is not a string of 1 to
  * 255 visible ASCII characters is refused with a `RequestArgumentError` rather than dropped, an
  * empty one included, since a request sent without the key its caller gave would lose the
  * protection the caller asked for without a word. `request` says what the request does, as the
- * refusal's last sentence names it ("start the run", "copy the method", "rotate the secret",
- * "replay the delivery"). The message never quotes the key, which a caller may derive from
+ * refusal's last sentence names it ("start the run", "copy the method", "store the layout",
+ * "rotate the secret", "replay the delivery"). The message never quotes the key, which a caller may derive from
  * something private. The Python SDK holds a key to the same rule, in the same words.
  */
 function idempotencyKeyOf(options, request = "start the run") {
@@ -4604,7 +4716,10 @@ function methodTemplatesFault(items) {
     }
     return null;
 }
-/** Why the catalog's categories are not ones the SDK reads, or `null`: each a string `slug` and `label`. */
+/**
+ * Why the catalog's categories are not ones the SDK reads, or `null`: each a string `slug` and
+ * `label`, and `labels`, an object whose every value is a string.
+ */
 function methodCategoriesFault(categories) {
     for (let index = 0; index < categories.length; index += 1) {
         const category = categories[index];
@@ -4613,6 +4728,11 @@ function methodCategoriesFault(categories) {
             typeof category.label !== "string") {
             return `\`categories\` holds an entry without a string \`slug\` and \`label\`, at [${index}]`;
         }
+        const labels = category.labels;
+        if (!isPlainObject(labels) ||
+            !Object.values(labels).every((label) => typeof label === "string")) {
+            return `\`categories\` holds an entry whose \`labels\` is not an object of strings, at [${index}]`;
+        }
     }
     return null;
 }
@@ -4733,6 +4853,52 @@ function withVerdictItems(answer) {
         read.warnings = readProblemItems(answer.warnings);
     return read;
 }
+/**
+ * A valid verdict with its `layouts` read entry by entry (`readMethodLayouts`), only when the
+ * answer carries the key: each entry that reads as a layout is kept, in the answer's order, and a
+ * list left with none is removed, so `layouts` is either absent or holds at least one layout, as
+ * the platform sends it. Any other answer is returned as it came.
+ */
+function withReadLayouts(answer) {
+    if (!isPlainObject(answer) || answer.is_valid !== true || !Object.hasOwn(answer, "layouts")) {
+        return answer;
+    }
+    const read = { ...answer };
+    const layouts = readMethodLayouts(answer.layouts);
+    if (layouts.length === 0)
+        delete read.layouts;
+    else
+        read.layouts = layouts;
+    return read;
+}
+/**
+ * The body `storeMethodLayout` sends for `layout`: the members of `MethodLayoutInput` and nothing
+ * else, since the route's body is closed at both levels, each provenance member that is `null` or
+ * omitted left out for the platform's default. The members are `LAYOUT_INPUT_MEMBERS` and
+ * `PROVENANCE_INPUT_MEMBERS`, which the build holds to the interfaces. A layout or a provenance that is not an object is
+ * refused with `RequestArgumentError` before anything is sent; every other member is sent as given,
+ * for the platform to hold to its shapes, its `422` naming the member it refuses.
+ */
+function methodLayoutBody(layout, call) {
+    if (!isPlainObject(layout)) {
+        throw argumentRefusal(call, LAYOUT_ARGUMENT, describeNumberArgument(layout), "not_an_object");
+    }
+    const provenance = layout.provenance;
+    if (!isPlainObject(provenance)) {
+        throw argumentRefusal(call, LAYOUT_PROVENANCE_ARGUMENT, describeNumberArgument(provenance), "not_an_object");
+    }
+    const sentProvenance = {};
+    for (const [member, presence] of Object.entries(PROVENANCE_INPUT_MEMBERS)) {
+        const value = provenance[member];
+        if (presence === "required" || value != null)
+            sentProvenance[member] = value;
+    }
+    const body = {};
+    for (const member of Object.keys(LAYOUT_INPUT_MEMBERS))
+        body[member] = layout[member];
+    body.provenance = sentProvenance;
+    return body;
+}
 /**
  * A run record with its `error` kept only when it is a problem document, and read as `null`
  * otherwise. Only when the record carries the `error` key, so a server that does not serve it