Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

334 KB
Raw Blame
# GENERATED FILE — do not edit by hand. Regenerate with `make openapi-export`.
openapi: 3.1.0
info:
  title: Pipelex API
  summary: The source-available Pipelex runner — implements MTHDS Protocol v2.0.0.
  description: 'This server implements the [MTHDS Protocol](https://mthds.ai) v2.0.0 (`POST /execute`, `POST /start`, `POST
    /validate`, `GET /models`, `GET /version` — marked `x-mthds-protocol: true`) plus the Pipelex API extensions: resolve
    and codegen (`/resolve`, `/codegen`), the pipe I/O route (`/pipe-io`), the model reference check (`/models/check`), and
    editor tooling (`/lint`, `/format`). Contract layering: MTHDS Protocol ⊂ Pipelex API (this server) ⊂ Pipelex hosted API.
    All endpoints are served under the `/v1` base path; every error is an RFC 7807 `application/problem+json` problem document,
    documented per operation as a `ProblemDocument`.'
  license:
    name: Elastic License 2.0
    identifier: Elastic-2.0
  version: 0.93.1
paths:
  /health:
    get:
      tags:
      - health
      summary: Liveness probe
      description: 'Report that this server process is up and serving. No auth required.


        A pure liveness probe for load balancers and orchestrators: it touches no

        dependency (no pipelex library load, no storage, no inference provider), so

        a 200 means "the process is serving", never "the deployment is correctly

        configured". It is mounted outside the `/v1` base path and outside the auth

        dependency, and cannot fail.'
      operationId: get_health_health_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
  /v1/version:
    get:
      tags:
      - discovery
      summary: Get Version
      description: 'Protocol and implementation versions (MTHDS Protocol `GET /version`).


        The handshake clients use for feature detection: `implementation`

        identifies this runner, `implementation_version` is this server package''s

        version, and `runtime_version` is the underlying pipelex runtime version.

        `blob_store` is true: this runner keeps a blob store over its storage

        provider and serves `POST /v1/blobs/missing` and `PUT /v1/blobs/{sha256}`,

        so a sender may name a file of `files` by its hash.'
      operationId: get_version_v1_version_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelexVersionInfo'
        '500':
          description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
            a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
            Report the `request_id`.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
      x-mthds-protocol: true
  /v1/blobs/{sha256}:
    put:
      tags:
      - blobs
      summary: Upload one blob's bytes to the target POST /blobs/missing named.
      description: 'Store one blob''s bytes under its SHA-256, as the upload target `POST /v1/blobs/missing` named (MTHDS
        Protocol).


        The body is the blob''s bytes and nothing else. A target whose signature does not hold, or that has expired, is a

        403 `auth.forbidden` whose `requirement` is a signed upload target, as is a query that is not one this runner signs,

        such as an expiry that is not a decimal integer; a body past `MAX_METHOD_TREE_FILE_KIB` a 413 `request.too_large`;

        and a body whose SHA-256 is not the path''s a 422 `request.invalid` naming the body. A blob is never changed:

        uploading bytes the runner already holds answers 204 and changes nothing, and uploading bytes whose hash names an

        object of another size, which only damaged storage could hold, is a 500 `pipelex.storage.damaged` that leaves the

        object as it is.'
      operationId: put_blob_v1_blobs__sha256__put
      parameters:
      - name: sha256
        in: path
        required: true
        schema:
          type: string
          pattern: ^[0-9a-f]{64}$
          description: The SHA-256 of the body, in lowercase hexadecimal.
          title: Sha256
        description: The SHA-256 of the body, in lowercase hexadecimal.
      - name: scope
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The blob store's scope, as the signed target names it.
          title: Scope
        description: The blob store's scope, as the signed target names it.
      - name: expires
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: When the target expires, in seconds since the epoch.
          title: Expires
        description: When the target expires, in seconds since the epoch.
      - name: signature
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: The target's signature.
          title: Signature
        description: The target's signature.
      responses:
        '204':
          description: Successful Response
        '403':
          description: '`auth.forbidden`, whose `params.requirement` is `signed_upload_target` — the upload does not carry
            the signed query an upload target of `POST /v1/blobs/missing` names, its signature does not hold for this hash
            and scope, or it has expired. Ask `POST /v1/blobs/missing` again for a fresh target.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
            byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
            both in bytes.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
            refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
            or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
            error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
            diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '500':
          description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
            a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
            Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
            blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
            verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
      x-mthds-protocol: true
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
  /v1/execute:
    post:
      tags:
      - run
      summary: Execute
      description: 'Execute a method synchronously and return its full output (MTHDS Protocol `POST /execute`).


        The backend is selected by the resolved `orchestration_mode` (deployment default + optional

        policy-gated per-request override via the `orchestration_mode` extra), symmetric with `/start` —

        not by `boot_orchestrator`. `/execute` is synchronous, so it dispatches with `BLOCKING` delivery

        regardless of backend (wait-semantics is endpoint-set, never requestable). Pipelex domain

        failures propagate untouched: the global `PipelexError` handler in `pipelex_api.exception_handlers`

        turns them into an RFC 7807 problem response.'
      operationId: execute_v1_execute_post
      requestBody:
        content:
          application/json:
            schema:
              $defs:
                Base64FileEntry:
                  properties:
                    base64:
                      type: string
                      title: Base64
                      description: The file's bytes in canonical padded standard Base64.
                  additionalProperties: false
                  type: object
                  required:
                  - base64
                  title: Base64FileEntry
                  description: A file entry carrying the file's bytes in canonical padded standard Base64.
                HashFileEntry:
                  properties:
                    sha256:
                      type: string
                      pattern: ^[0-9a-f]{64}$
                      title: Sha256
                      description: The SHA-256 of the file's bytes, in lowercase hexadecimal.
                    size:
                      type: integer
                      minimum: 0.0
                      title: Size
                      description: The file's size in bytes, an integer written with no fraction or exponent.
                  additionalProperties: false
                  type: object
                  required:
                  - sha256
                  - size
                  title: HashFileEntry
                  description: A file entry naming, by their SHA-256 and their size, bytes the receiver already holds in its
                    blob store.
                StuffContentAbstract:
                  properties: {}
                  type: object
                  title: StuffContentAbstract
              properties:
                pipe_code:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Pipe Code
                mthds_contents:
                  anyOf:
                  - items:
                      type: string
                    type: array
                  - type: 'null'
                  title: Mthds Contents
                  description: 'Being retired, and refused by a later release: send the method in `files`. The method''s `.mthds`
                    files as raw strings, always an array, even for a single file; with no `pipe_code`, a file must declare
                    `main_pipe`. Mutually exclusive with `files`, `bundle_b64` and `method_ref`.'
                inputs:
                  anyOf:
                  - additionalProperties:
                      anyOf:
                      - type: string
                      - items:
                          type: string
                        type: array
                      - $ref: '#/$defs/StuffContentAbstract'
                      - items:
                          $ref: '#/$defs/StuffContentAbstract'
                        type: array
                      - additionalProperties: true
                        type: object
                    type: object
                  - type: 'null'
                  title: Inputs
                output_name:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Output Name
                output_multiplicity:
                  anyOf:
                  - type: boolean
                  - type: integer
                  - type: 'null'
                  title: Output Multiplicity
                dynamic_output_concept_ref:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Dynamic Output Concept Ref
                bundle_b64:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Bundle B64
                  description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — base64-encoded zip of the method''s
                    folder, read as a map of its entries, so the archive''s names are judged by the method tree''s rule as
                    the keys of `files` are. The method packages it calls by address may travel with it under `.mthds/methods/<name>/`,
                    each with its `METHODS.toml`; they are searched before the runner''s installed copies, for this run alone.
                    Mutually exclusive with `files`. Custom `.py` is only honored on a sandbox-hosted deployment. Being retired
                    with `mthds_contents`, and refused by a later release: send the method in `files`.'
                files:
                  anyOf:
                  - additionalProperties:
                      anyOf:
                      - type: string
                      - $ref: '#/$defs/Base64FileEntry'
                      - $ref: '#/$defs/HashFileEntry'
                    type: object
                  - type: 'null'
                  title: Files
                  description: 'The method as a map of file entries, the MTHDS standard''s form of a method tree that travels:
                    each key is a tree path (relative, forward slashes, in Unicode NFC, no `.` or `..` segment, no segment
                    starting with a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or
                    `{"sha256": ..., "size": ...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing`
                    then `PUT /v1/blobs/{sha256}`). The map is read from the request''s JSON text: a key given twice, a key
                    the membership rule keeps out of every tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid`
                    whose `reason` is the refusal''s code and whose `path` names the first path, a key leaving the tree is
                    a 422 `security.input_path_refused`, a malformed entry is a 422 `request.invalid`, and hash entries the
                    runner does not hold are one 422 `request.blobs_missing` whose `missing_blobs` parameter lists every such
                    hash. Its `.mthds` files are the method''s bundles and every other file is one a step may read, such as
                    a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`, the run starts at the `main_pipe`
                    of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its bundles declare. Custom
                    `.py` is only honored on a sandbox-hosted deployment.'
                dependencies:
                  anyOf:
                  - additionalProperties:
                      additionalProperties:
                        anyOf:
                        - type: string
                        - $ref: '#/$defs/Base64FileEntry'
                        - $ref: '#/$defs/HashFileEntry'
                      type: object
                    type: object
                  - type: 'null'
                  title: Dependencies
                  description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the method packages the method calls
                    by address that this runner cannot fetch, such as one an author has not published, as `{"<address>": <map
                    of file entries>}`: each value is a tree of its own, read as `files` is, with a `METHODS.toml` at its
                    root declaring the address it is keyed by. They are searched before the runner''s installed copies, for
                    this request alone. Accompanies `files`.'
                method_ref:
                  anyOf:
                  - type: string
                    maxLength: 512
                    minLength: 1
                  - type: 'null'
                  title: Method Ref
                  description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — run a published method by reference
                    instead of inline source. Address form: `github.com/<owner>/<repo>[/<selector>][@<tag>]` (e.g. `github.com/Pipelex/methods/[email protected]`)
                    — resolved by THIS runner: 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 is recorded as `method_provenance`
                    on the response. Mutually exclusive with `mthds_contents` and with a method bundle (`bundle_b64` / `files`);
                    `pipe_code` may accompany it to override the manifest''s `main_pipe`. A package shipping custom Python
                    is only honored on a sandbox-hosted deployment, and a package declaring Python structure classes is always
                    refused — hosted execution accepts MTHDS concepts and sandboxed PipeFuncs, not in-process Python.'
                resources:
                  anyOf:
                  - additionalProperties:
                      type: string
                    type: object
                  - type: 'null'
                  title: Resources
                  description: 'The files submitted with the bundle that its steps read, such as a PipeDocGen step''s `template_file`
                    (an `.xlsx`, `.docx`, `.pptx` or `.html` template): a JSON object mapping each file''s bundle-relative
                    path, exactly as the step names it, to the file''s bytes in standard base64. A path must be relative and
                    written with forward slashes, with no `..` segment, backslash or colon. Beside inline `mthds_contents`,
                    every bundle of the request is read as sitting in one directory, and every file must be named by a step,
                    or the request is refused with a 422 `BundleResourceNotNamedError`. Beside a method tree, `files` or `bundle_b64`,
                    each file joins the tree at its path from the tree''s root, where a file the tree already holds must have
                    the same bytes. By default at most 32 files, 5120 KiB each and 10240 KiB in all, decoded; a deployment
                    sets its own with `MAX_RESOURCES_PER_REQUEST`, `MAX_RESOURCE_FILE_KIB` and `MAX_RESOURCES_TOTAL_KIB`.
                    The files make one method tree with the bundles, which the run names by its digest: no file''s bytes travel
                    with the run, each being read where a step uses it. Being retired with `mthds_contents`, and refused by
                    a later release: send these files in the method''s tree, in `files`.'
                orchestration_mode:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Orchestration Mode
                  description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — request the orchestration mode (the
                    backend) for this run. An OPEN string token: `direct` (in-process, the base default), `temporal`, and
                    any other plugin-provided token are accepted; an unregistered token is refused at dispatch. The delivery
                    axis (blocking vs fire-and-forget) is endpoint-set, never requestable. Honored ONLY when the deployment
                    sets `allow_request_orchestration_mode_override = true` in its `api.toml`; otherwise a token that differs
                    from the deployment default is refused with a 422 `pipelex.deployment.orchestration_override_forbidden`.
                    Omit it to use the deployment default.'
                storage_scope:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Storage Scope
                  description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied prefix every object
                    this run writes lands under. One to three path-safe segments (e.g. `tenant/run` or `org/method/run`);
                    the runtime composes its own leaves (`assets/`, `generated/`, `results/`, `payloads/`) onto it and never
                    interprets the value. Omit it and the run is scoped to the caller's own id, which is correct for a single-tenant
                    deployment and wrong for a multi-tenant one — a host serving many tenants MUST send this.
                read_scope:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Read Scope
                  description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied prefix every stored
                    object this run reads must lie under, and on a scoped run no local path is read at all. One to three path-safe
                    segments, which must be the `storage_scope` or one of its leading segments, since a run reads back what
                    it writes. Omit it and the run is scoped to the caller's own id when the deployment identifies callers,
                    and unscoped when it is single-tenant — a host serving many tenants MUST send this.
                analytics_groups:
                  anyOf:
                  - additionalProperties:
                      type: string
                    type: object
                  - type: 'null'
                  title: Analytics Groups
                  description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied groups this run''s
                    telemetry belongs to, as a mapping of group type to group key (e.g. `{"organization": "org_acme"}`). The
                    runtime never reads a key by name: it carries the mapping on the run as its `extras` and stamps it on
                    every span as `pipelex.run.extras`, so every OpenTelemetry exporter receives it, and the deployment''s
                    own PostHog stream, in `identified` mode, forwards it as the capture''s groups. Group types are lowercase
                    snake_case starting with a letter, at most 32 characters; group keys are 1 to 128 characters from `[A-Za-z0-9_-]`;
                    at most five entries. Omit it and the run belongs to no group, which is right for a single-tenant deployment.'
              additionalProperties: true
              type: object
              title: PipelexApiExecuteRequest
              description: 'Documented body of `POST /execute` — the protocol''s `RunRequest` plus THIS server''s run extensions.


                Used only to publish the OpenAPI request schema: `/execute` reads the body through the raw

                `Request` (plain JSON, parsed by the route), so FastAPI cannot infer the body type; this model documents the

                extensions the route actually honors (`orchestration_mode`, `storage_scope`, `read_scope`, `analytics_groups`,

                all parsed by `PipelineApiExtras`).'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelexApiExecuteResponse'
        '401':
          description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
            or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
            or trusts a proxy''s forwarded identity and the proxy forwarded none.'
          headers:
            WWW-Authenticate:
              description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
                or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
            byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
            both in bytes.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
            refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
            or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
            error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
            diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '500':
          description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
            a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
            Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
            blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
            verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '403':
          description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
            the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
            may read.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '404':
          description: '`method.not_found` — the `method_ref` repository was fetched, but no package in it matches the requested
            address by manifest identity.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '429':
          description: An upstream inference provider rate-limited the run. Passed through from the provider; `Retry-After`
            is set when the provider supplied a hint.
          headers:
            Retry-After:
              description: Seconds to wait before retrying, when the upstream provider supplied a hint.
              schema:
                type: integer
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '501':
          description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
            package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
            a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
            since the method''s author changes it.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
      x-mthds-protocol: true
  /v1/start:
    post:
      tags:
      - run
      summary: Start
      description: 'Start a method run and return its pipeline_run_id with a 202 ack (MTHDS Protocol `POST /start`).


        Answers `202 Accepted` with a `StartAck`. A client-supplied `pipeline_run_id` is

        honored (the protocol lets an implementation decline it; this runner accepts it, and

        `StartAck.pipeline_run_id` is always authoritative). Pipelex domain failures propagate untouched: the global

        `PipelexError` handler in `pipelex_api.exception_handlers` turns them into an

        RFC 7807 problem response.


        Fire-and-forget is a property of THIS endpoint (its delivery axis), honored only by an

        async-capable backend. A deployment configures the backend (`orchestration_mode`) once; `/start`

        sets `FIRE_AND_FORGET` delivery and checks the resolved orchestrator can honor it. A Temporal

        deployment (`orchestration_mode = "temporal"`) enqueues the run and returns immediately with a

        `workflow_id`. On the orchestrator-agnostic base (`orchestration_mode = "direct"`, the default)

        the in-process orchestrator is blocking-only, so `/start` is HONEST: it refuses with a `501`

        (`runtime.unsupported`) — use `/execute` — rather than silently blocking and acking.

        The completion callback (`callback_urls` / storage delivery) fires on the async path.'
      operationId: start_v1_start_post
      requestBody:
        content:
          application/json:
            schema:
              $defs:
                Base64FileEntry:
                  properties:
                    base64:
                      type: string
                      title: Base64
                      description: The file's bytes in canonical padded standard Base64.
                  additionalProperties: false
                  type: object
                  required:
                  - base64
                  title: Base64FileEntry
                  description: A file entry carrying the file's bytes in canonical padded standard Base64.
                HashFileEntry:
                  properties:
                    sha256:
                      type: string
                      pattern: ^[0-9a-f]{64}$
                      title: Sha256
                      description: The SHA-256 of the file's bytes, in lowercase hexadecimal.
                    size:
                      type: integer
                      minimum: 0.0
                      title: Size
                      description: The file's size in bytes, an integer written with no fraction or exponent.
                  additionalProperties: false
                  type: object
                  required:
                  - sha256
                  - size
                  title: HashFileEntry
                  description: A file entry naming, by their SHA-256 and their size, bytes the receiver already holds in its
                    blob store.
                StuffContentAbstract:
                  properties: {}
                  type: object
                  title: StuffContentAbstract
              properties:
                pipe_code:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Pipe Code
                mthds_contents:
                  anyOf:
                  - items:
                      type: string
                    type: array
                  - type: 'null'
                  title: Mthds Contents
                  description: 'Being retired, and refused by a later release: send the method in `files`. The method''s `.mthds`
                    files as raw strings, always an array, even for a single file; with no `pipe_code`, a file must declare
                    `main_pipe`. Mutually exclusive with `files`, `bundle_b64` and `method_ref`.'
                inputs:
                  anyOf:
                  - additionalProperties:
                      anyOf:
                      - type: string
                      - items:
                          type: string
                        type: array
                      - $ref: '#/$defs/StuffContentAbstract'
                      - items:
                          $ref: '#/$defs/StuffContentAbstract'
                        type: array
                      - additionalProperties: true
                        type: object
                    type: object
                  - type: 'null'
                  title: Inputs
                output_name:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Output Name
                output_multiplicity:
                  anyOf:
                  - type: boolean
                  - type: integer
                  - type: 'null'
                  title: Output Multiplicity
                dynamic_output_concept_ref:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Dynamic Output Concept Ref
                bundle_b64:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Bundle B64
                  description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — base64-encoded zip of the method''s
                    folder, read as a map of its entries, so the archive''s names are judged by the method tree''s rule as
                    the keys of `files` are. The method packages it calls by address may travel with it under `.mthds/methods/<name>/`,
                    each with its `METHODS.toml`; they are searched before the runner''s installed copies, for this run alone.
                    Mutually exclusive with `files`. Custom `.py` is only honored on a sandbox-hosted deployment. Being retired
                    with `mthds_contents`, and refused by a later release: send the method in `files`.'
                files:
                  anyOf:
                  - additionalProperties:
                      anyOf:
                      - type: string
                      - $ref: '#/$defs/Base64FileEntry'
                      - $ref: '#/$defs/HashFileEntry'
                    type: object
                  - type: 'null'
                  title: Files
                  description: 'The method as a map of file entries, the MTHDS standard''s form of a method tree that travels:
                    each key is a tree path (relative, forward slashes, in Unicode NFC, no `.` or `..` segment, no segment
                    starting with a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or
                    `{"sha256": ..., "size": ...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing`
                    then `PUT /v1/blobs/{sha256}`). The map is read from the request''s JSON text: a key given twice, a key
                    the membership rule keeps out of every tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid`
                    whose `reason` is the refusal''s code and whose `path` names the first path, a key leaving the tree is
                    a 422 `security.input_path_refused`, a malformed entry is a 422 `request.invalid`, and hash entries the
                    runner does not hold are one 422 `request.blobs_missing` whose `missing_blobs` parameter lists every such
                    hash. Its `.mthds` files are the method''s bundles and every other file is one a step may read, such as
                    a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`, the run starts at the `main_pipe`
                    of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its bundles declare. Custom
                    `.py` is only honored on a sandbox-hosted deployment.'
                dependencies:
                  anyOf:
                  - additionalProperties:
                      additionalProperties:
                        anyOf:
                        - type: string
                        - $ref: '#/$defs/Base64FileEntry'
                        - $ref: '#/$defs/HashFileEntry'
                      type: object
                    type: object
                  - type: 'null'
                  title: Dependencies
                  description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the method packages the method calls
                    by address that this runner cannot fetch, such as one an author has not published, as `{"<address>": <map
                    of file entries>}`: each value is a tree of its own, read as `files` is, with a `METHODS.toml` at its
                    root declaring the address it is keyed by. They are searched before the runner''s installed copies, for
                    this request alone. Accompanies `files`.'
                method_ref:
                  anyOf:
                  - type: string
                    maxLength: 512
                    minLength: 1
                  - type: 'null'
                  title: Method Ref
                  description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — run a published method by reference
                    instead of inline source. Address form: `github.com/<owner>/<repo>[/<selector>][@<tag>]` (e.g. `github.com/Pipelex/methods/[email protected]`)
                    — resolved by THIS runner: 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 is recorded as `method_provenance`
                    on the response. Mutually exclusive with `mthds_contents` and with a method bundle (`bundle_b64` / `files`);
                    `pipe_code` may accompany it to override the manifest''s `main_pipe`. A package shipping custom Python
                    is only honored on a sandbox-hosted deployment, and a package declaring Python structure classes is always
                    refused — hosted execution accepts MTHDS concepts and sandboxed PipeFuncs, not in-process Python.'
                resources:
                  anyOf:
                  - additionalProperties:
                      type: string
                    type: object
                  - type: 'null'
                  title: Resources
                  description: 'The files submitted with the bundle that its steps read, such as a PipeDocGen step''s `template_file`
                    (an `.xlsx`, `.docx`, `.pptx` or `.html` template): a JSON object mapping each file''s bundle-relative
                    path, exactly as the step names it, to the file''s bytes in standard base64. A path must be relative and
                    written with forward slashes, with no `..` segment, backslash or colon. Beside inline `mthds_contents`,
                    every bundle of the request is read as sitting in one directory, and every file must be named by a step,
                    or the request is refused with a 422 `BundleResourceNotNamedError`. Beside a method tree, `files` or `bundle_b64`,
                    each file joins the tree at its path from the tree''s root, where a file the tree already holds must have
                    the same bytes. By default at most 32 files, 5120 KiB each and 10240 KiB in all, decoded; a deployment
                    sets its own with `MAX_RESOURCES_PER_REQUEST`, `MAX_RESOURCE_FILE_KIB` and `MAX_RESOURCES_TOTAL_KIB`.
                    The files make one method tree with the bundles, which the run names by its digest: no file''s bytes travel
                    with the run, each being read where a step uses it. Being retired with `mthds_contents`, and refused by
                    a later release: send these files in the method''s tree, in `files`.'
                pipeline_run_id:
                  anyOf:
                  - type: string
                    maxLength: 128
                  - type: 'null'
                  title: Pipeline Run Id
                callback_urls:
                  anyOf:
                  - items:
                      type: string
                    type: array
                  - type: 'null'
                  title: Callback Urls
                  description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — completion webhooks. When the run
                    finishes, the runner POSTs a completion notice to each URL, with an X-Completion-Signature header holding
                    the HMAC-SHA256 of the run id (not of the body). The body carries `pipeline_run_id`, `state` (with the
                    legacy `status` alias), `result_url` (the storage key prefix of the stored results, when results were
                    stored) and `error` on failure; it does not carry the run's output. http/https only; private, loopback,
                    link-local and cloud-metadata hosts are rejected.
                orchestration_mode:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Orchestration Mode
                  description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — request the orchestration mode (the
                    backend) for this run. An OPEN string token: `direct` (in-process, the base default), `temporal`, and
                    any other plugin-provided token are accepted; an unregistered token is refused at dispatch. The delivery
                    axis (blocking vs fire-and-forget) is endpoint-set, never requestable. Honored ONLY when the deployment
                    sets `allow_request_orchestration_mode_override = true` in its `api.toml`; otherwise a token that differs
                    from the deployment default is refused with a 422 `pipelex.deployment.orchestration_override_forbidden`.
                    Omit it to use the deployment default.'
                storage_scope:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Storage Scope
                  description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied prefix every object
                    this run writes lands under. One to three path-safe segments (e.g. `tenant/run` or `org/method/run`);
                    the runtime composes its own leaves (`assets/`, `generated/`, `results/`, `payloads/`) onto it and never
                    interprets the value. Omit it and the run is scoped to the caller's own id, which is correct for a single-tenant
                    deployment and wrong for a multi-tenant one — a host serving many tenants MUST send this.
                read_scope:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Read Scope
                  description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied prefix every stored
                    object this run reads must lie under, and on a scoped run no local path is read at all. One to three path-safe
                    segments, which must be the `storage_scope` or one of its leading segments, since a run reads back what
                    it writes. Omit it and the run is scoped to the caller's own id when the deployment identifies callers,
                    and unscoped when it is single-tenant — a host serving many tenants MUST send this.
                analytics_groups:
                  anyOf:
                  - additionalProperties:
                      type: string
                    type: object
                  - type: 'null'
                  title: Analytics Groups
                  description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied groups this run''s
                    telemetry belongs to, as a mapping of group type to group key (e.g. `{"organization": "org_acme"}`). The
                    runtime never reads a key by name: it carries the mapping on the run as its `extras` and stamps it on
                    every span as `pipelex.run.extras`, so every OpenTelemetry exporter receives it, and the deployment''s
                    own PostHog stream, in `identified` mode, forwards it as the capture''s groups. Group types are lowercase
                    snake_case starting with a letter, at most 32 characters; group keys are 1 to 128 characters from `[A-Za-z0-9_-]`;
                    at most five entries. Omit it and the run belongs to no group, which is right for a single-tenant deployment.'
              additionalProperties: true
              type: object
              title: PipelexApiStartRequest
              description: 'Documented body of `POST /start` — the protocol''s `StartRequest` plus THIS server''s extensions.


                Used only to publish the OpenAPI request schema: the protocol model no

                longer advertises implementation extensions, so this server documents the

                ones it implements itself. Wire validation happens in `PipelineApiExtras`.'
        required: true
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelexApiStartResponse'
        '401':
          description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
            or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
            or trusts a proxy''s forwarded identity and the proxy forwarded none.'
          headers:
            WWW-Authenticate:
              description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
                or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
            byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
            both in bytes.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
            refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
            or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
            error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
            diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '500':
          description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
            a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
            Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
            blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
            verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '403':
          description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
            the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
            may read.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '404':
          description: '`method.not_found` — the `method_ref` repository was fetched, but no package in it matches the requested
            address by manifest identity.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '409':
          description: '`pipelex.run.already_exists` — the submitted `pipeline_run_id` is still registered for an in-flight
            run. Completed and failed runs free their id, so this only fires for genuinely concurrent duplicates.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '501':
          description: '`runtime.unsupported` — this deployment cannot honor fire-and-forget delivery: its orchestrator is
            blocking-only, or its async execution is not enabled. Permanent under the current deployment; use `POST /execute`
            instead. Or `pipelex.deployment.custom_code_requires_sandbox`, as on `POST /execute`.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
      x-mthds-protocol: true
  /v1/validate:
    post:
      tags:
      - validate
      summary: Validate Mthds
      description: "Validate MTHDS content by parsing, loading, and dry-running pipes (MTHDS Protocol `POST /validate`).\n\
        \n`/validate` is a **diagnostic endpoint**: any verdict the validator can produce — valid,\ninvalid, or valid-but-not-runnable\
        \ — rides a **200** discriminated in the body on `is_valid`.\nNon-2xx is reserved for the cases where *no verdict\
        \ could be produced*.\n\nResponse contract:\n\n- **Valid verdict (200, `is_valid: true`):** the `ValidReport` arm\
        \ — the canonical report\n  (primary `bundle_blueprint`, `pipe_io_contracts` keyed by namespaced `pipe_ref`, per-pipe\n\
        \  `validated_pipes` sweep outcomes, `pending_signatures` + `is_runnable` runnability verdict,\n  best-effort `graph_spec`)\
        \ plus the wire extras (`mthds_contents` echo, `message`,\n  `default_pipe_ref`). The graph is drawn from the pipe\
        \ a selector-less run of this request\n  would execute: on a `method_ref` request whose manifest names a `main_pipe`,\
        \ that pipe;\n  otherwise the primary blueprint's `main_pipe`. A bundle that declares no `main_pipe`, with\n  no manifest\
        \ naming one, validates fine and carries `graph_spec=null`, and so does a\n  manifest `main_pipe` the closure does\
        \ not resolve. Pending signatures are reported as `pending_signatures` +\n  `is_runnable: false`, never as an error.\
        \ `default_pipe_ref` names the pipe a selector-less\n  run of this same request would execute — on a `method_ref`\
        \ request that is the fetched\n  manifest's `main_pipe`, which the canonical report cannot see, so the field is the\
        \ only\n  signal a consumer can project a by-address entry signature from.\n  The opt-in `views` tokens `input_form`\
        \ and `output_form` additionally attach the per-pipe\n  input-form and output-form descriptors as same-named top-level\
        \ fields, keyed like\n  `pipe_io_contracts`; without a token the matching field is absent and the body is\n  byte-identical\
        \ to a request that omits `views`. They are separate tokens because they answer\n  separate questions — a caller building\
        \ a fill-in form wants the inputs, a caller rendering a\n  result or registering a tool signature with a return type\
        \ wants the output.\n- **Invalid verdict (200, `is_valid: false`):** the `InvalidReport` arm — `errors[]`, one problem\
        \ item per\n  error with its own code (incl. one located item per pipe whose dry run failed, with the failure's code),\
        \ the\n  items of the verdict's problem — + `message`, with the structural artifacts absent. The runner\n  returns\
        \ this as a value (a `BundleValidationFailure` with validation items) regardless of backend — the\n  in-process arm\
        \ from the bundle's `ValidateBundleError`, the dispatched arm recovered from the\n  worker — so the route maps it\
        \ to a 200 by matching validation diagnostics, never by catching an\n  exception. A returned failure without validation\
        \ diagnostics is a backend, configuration or runtime\n  fault, and its problem is answered as every raised failure's\
        \ is.\n- **Either arm:** a member with no value is absent rather than `null`, at the arm's top level and in its\n\
        \  problem items; the structured artifacts of the valid arm keep their own serialization.\n- **No verdict (non-2xx):**\
        \ a malformed request body, an `mthds_sources` length mismatch, or\n  more or fewer than one of `files` / `method_ref`\
        \ / `mthds_contents` is a request-shape **422**, and so is a forbidden\n  `orchestration_mode` override; a host-wiring\
        \ programmer error or a genuine orchestrator fault is a\n  **5xx**; auth is **401/403**. A `method_ref` **resolution\
        \ failure** is also a no-verdict condition —\n  never an `is_valid: false`: each answers the status its code declares,\
        \ such as a **422** for a\n  malformed reference, a **502** for a failed fetch, a **404** for no matching package\
        \ in the\n  repository and a **422** for the method's Python structure classes, and the custom-code sandbox gate\n\
        \  a **501**. All are `application/problem+json` documents carrying a registry `code`, rendered by the\n  global handlers\
        \ in `pipelex_api.exception_handlers` — routes never shape them."
      operationId: validate_mthds_v1_validate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ValidReport'
                - $ref: '#/components/schemas/InvalidReport'
                title: Response Validate Mthds V1 Validate Post
                discriminator:
                  propertyName: is_valid
                  mapping:
                    'True': '#/components/schemas/ValidReport'
                    'False': '#/components/schemas/InvalidReport'
        '401':
          description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
            or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
            or trusts a proxy''s forwarded identity and the proxy forwarded none.'
          headers:
            WWW-Authenticate:
              description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
                or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
            byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
            both in bytes.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
            refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
            or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
            error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
            diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '500':
          description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
            a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
            Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
            blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
            verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '403':
          description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
            the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
            may read.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '404':
          description: '`method.not_found` — the `method_ref` repository was fetched, but no package in it matches the requested
            address by manifest identity.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '501':
          description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
            package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
            a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
            since the method''s author changes it.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
      x-mthds-protocol: true
  /v1/resolve:
    post:
      tags:
      - resolve
      summary: Resolve Mthds
      description: "Resolve a method into its normalized crate (Pipelex API extension).\n\nResolution is a first-class language\
        \ operation alongside validation: read the method's tree\n(`files`, or the package a `method_ref` fetches) exactly\
        \ as `/validate` reads it, load + statically\nvalidate it as the caller's own library, and emit the **normalized library\
        \ crate** (fully\nqualified refs, refinement flattened, natives materialized, fingerprint set) — the artifact\nshape\
        \ the MTHDS standard specifies as the Library Crate Format. It runs no dry-run sweep —\nrunnability is `/validate`'s\
        \ vocabulary.\n\nResponse contract (the `/validate` discipline):\n\n- **Valid verdict (200, `is_valid: true`):** the\
        \ crate on the valid arm.\n- **Invalid verdict (200, `is_valid: false`):** the library could not be parsed, loaded,\
        \ or\n  validated — `errors[]`, one problem item per error.\n- **No verdict (non-2xx):** a malformed request body\
        \ (neither or both method selectors) is a\n  request-shape 422 `request.invalid`; a `files` map that is not a method\
        \ tree is a 422\n  `method.package_invalid`, and hash entries this runner does not hold a 422\n  `request.blobs_missing`;\
        \ custom Python on a deployment that is not sandbox-hosted is a 501\n  `pipelex.deployment.custom_code_requires_sandbox`,\
        \ and a Python structure class a 422\n  `pipelex.deployment.python_structures_refused`; a registry-form `method_ref`\
        \ is a 422\n  `request.unsupported` until server-side method registry resolution exists; auth is 401/403;\n  server\
        \ fault is 5xx. All `application/problem+json` documents with a registry `code`, via the\n  global handlers."
      operationId: resolve_mthds_v1_resolve_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MethodTreeRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ResolveValidReport'
                - $ref: '#/components/schemas/CrateInvalidReport'
                title: Response Resolve Mthds V1 Resolve Post
                discriminator:
                  propertyName: is_valid
                  mapping:
                    'True': '#/components/schemas/ResolveValidReport'
                    'False': '#/components/schemas/CrateInvalidReport'
        '401':
          description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
            or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
            or trusts a proxy''s forwarded identity and the proxy forwarded none.'
          headers:
            WWW-Authenticate:
              description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
                or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
            byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
            both in bytes.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
            refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
            or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
            error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
            diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '500':
          description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
            a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
            Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
            blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
            verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '403':
          description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
            the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
            may read.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '404':
          description: '`method.not_found` — the `method_ref` repository was fetched, but no package in it matches the requested
            address by manifest identity.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '501':
          description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
            package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
            a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
            since the method''s author changes it.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
  /v1/pipe-io:
    post:
      tags:
      - pipe-io
      summary: Pipe Io
      description: "Return a method's pipe I/O contracts, input form and output form, with no dry run (Pipelex API extension).\n\
        \nThe method is read as `/validate` reads a method tree and resolves through the static core\n`/resolve` rides, a\
        \ pipe is selected the way the per-pipe routes select one, and the three\nartifacts are derived with `build_pipe_io_artifacts`,\
        \ the builder `/validate` and every run call —\nso a call costs one load and one derivation where `/validate` dry-runs\
        \ every pipe.\n\nResponse contract (the `/validate` discipline):\n\n- **Valid verdict (200, `is_valid: true`):** the\
        \ three artifact maps keyed by qualified `pipe_ref`,\n  beside `pipe_ref`, `default_pipe_ref`, `pending_signatures`,\
        \ `is_runnable`, and `files` when\n  `include_files` is true.\n- **Invalid verdict (200, `is_valid: false`):** the\
        \ closure could not be parsed, loaded, or\n  statically validated — the crate verdict, carrying no artifact, no selection\
        \ and no files.\n- **No verdict (non-2xx):** a malformed body and neither or both method selectors are\n  request-shape\
        \ 422s (`request.invalid`); a `files` map that is not a method tree is a 422\n  `method.package_invalid`, and hash\
        \ entries this runner does not hold a 422\n  `request.blobs_missing`, as on `/validate`; custom Python on a deployment\
        \ that is not\n  sandbox-hosted is a 501 `pipelex.deployment.custom_code_requires_sandbox`, and a Python\n  structure\
        \ class a 422 `pipelex.deployment.python_structures_refused`; a selection refusal is an\n  input 422 named for its\
        \ failure, `request.pipe_not_found` for an unknown `pipe_ref` or a\n  single-pipe request whose chain finds no entry\
        \ pipe, `request.pipe_ambiguous` for an ambiguous\n  one or a chain that finds several; the `method_ref` fetch outcomes\
        \ are those of `/resolve` (404,\n  422); an artifact that cannot be derived (`PipeIOContractError`) is a 500. All\n\
        \  `application/problem+json` documents with a registry `code`, via the global handlers."
      operationId: pipe_io_v1_pipe_io_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PipeIORequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/PipeIOValidReport'
                - $ref: '#/components/schemas/CrateInvalidReport'
                title: Response Pipe Io V1 Pipe Io Post
                discriminator:
                  propertyName: is_valid
                  mapping:
                    'True': '#/components/schemas/PipeIOValidReport'
                    'False': '#/components/schemas/CrateInvalidReport'
        '401':
          description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
            or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
            or trusts a proxy''s forwarded identity and the proxy forwarded none.'
          headers:
            WWW-Authenticate:
              description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
                or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
            byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
            both in bytes.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
            refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
            or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
            error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
            diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '500':
          description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
            a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
            Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
            blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
            verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '403':
          description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
            the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
            may read.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '404':
          description: '`method.not_found` — the `method_ref` repository was fetched, but no package in it matches the requested
            address by manifest identity.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '501':
          description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
            package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
            a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
            since the method''s author changes it.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
  /v1/codegen:
    post:
      tags:
      - codegen
      summary: Codegen Mthds
      description: "Generate typed artifacts from a method (Pipelex API extension).\n\nResolves the method to its normalized\
        \ crate (exactly like `POST /resolve`), then projects it\nthrough the requested `kind`/`target` axes and returns the\
        \ **stamped** artifact set plus its\n`codegen.lock` — everything a client needs to materialize a byte-identical local\
        \ projection\nand run the offline drift check. There is deliberately **no** server-side check route: the\ncheck is\
        \ offline by design.\n\nResponse contract (the `/validate` discipline):\n\n- **Valid verdict (200, `is_valid: true`):**\
        \ the artifacts + lock on the valid arm.\n- **Invalid verdict (200, `is_valid: false`):** the library could not be\
        \ parsed, loaded, or\n  validated — `errors[]`, one problem item per error; no artifacts exist.\n- **No verdict (non-2xx):**\
        \ an unknown projection `kind`/`target`, a `pipe_ref` on a\n  concept-set-wide kind, or a malformed method selector\
        \ is a request-shape 422 problem+json; the\n  method's tree is refused as `/resolve` refuses it (a 422 `method.package_invalid`\
        \ or\n  `request.blobs_missing`, the Python policy's refusals, the `method_ref` fetch outcomes, a 422\n  `request.unsupported`\
        \ for a registry-form `method_ref`); auth is 401/403; server fault is 5xx."
      operationId: codegen_mthds_v1_codegen_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CodegenRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/CodegenValidReport'
                - $ref: '#/components/schemas/CrateInvalidReport'
                title: Response Codegen Mthds V1 Codegen Post
                discriminator:
                  propertyName: is_valid
                  mapping:
                    'True': '#/components/schemas/CodegenValidReport'
                    'False': '#/components/schemas/CrateInvalidReport'
        '401':
          description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
            or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
            or trusts a proxy''s forwarded identity and the proxy forwarded none.'
          headers:
            WWW-Authenticate:
              description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
                or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
            byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
            both in bytes.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
            refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
            or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
            error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
            diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '500':
          description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
            a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
            Report the `request_id`. Or `pipelex.storage.damaged`, naming the kind of storage as `params.scheme`: bytes the
            blob store holds under a hash the request names do not hash to it, a damaged object a retry reads again, so its
            verdict is not to retry. The operator removes the object, for the blob to be uploaded again.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '403':
          description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
            the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
            may read.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '404':
          description: '`method.not_found` — the `method_ref` repository was fetched, but no package in it matches the requested
            address by manifest identity.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '501':
          description: '`pipelex.deployment.custom_code_requires_sandbox` — the method (a bundle, or a fetched `method_ref`
            package, as `params.origin` says) ships custom Python and this deployment is not sandbox-hosted. The refusal of
            a method whose Python declares structure classes, `pipelex.deployment.python_structures_refused`, is a 422 instead,
            since the method''s author changes it.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
  /v1/lint:
    post:
      tags:
      - tools
      summary: Lint Mthds
      description: 'Lint one .mthds file with the embedded MTHDS schema.


        Malformed .mthds content is a produced diagnostic verdict and returns 200.

        Request-shape problems remain RFC 7807 422 responses through the global handlers.'
      operationId: lint_mthds_v1_lint_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LintRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LintResponse'
        '401':
          description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
            or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
            or trusts a proxy''s forwarded identity and the proxy forwarded none.'
          headers:
            WWW-Authenticate:
              description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
                or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
            byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
            both in bytes.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
            refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
            or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
            error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
            diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '500':
          description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
            a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
            Report the `request_id`.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
  /v1/format:
    post:
      tags:
      - tools
      summary: Format Mthds
      description: 'Format one .mthds file with the canonical MTHDS formatter.


        Syntax errors return 200 with diagnostics and unchanged content. Malformed

        formatter options are caller input errors and return a 422 `request.invalid`

        naming `options`.'
      operationId: format_mthds_v1_format_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FormatRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FormatResponse'
        '401':
          description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
            or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
            or trusts a proxy''s forwarded identity and the proxy forwarded none.'
          headers:
            WWW-Authenticate:
              description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
                or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
            byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
            both in bytes.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
            refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
            or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
            error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
            diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '500':
          description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
            a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
            Report the `request_id`.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
  /v1/models:
    get:
      tags:
      - agent
      summary: Get Models
      description: 'List the model deck this runner can route to (MTHDS Protocol `GET /models`).


        Answers the protocol `ModelDeck` as produced by `PipelexMTHDSProtocol.models` —

        the flat `models` list (`{name, type}` entries) plus this implementation''s

        category-keyed routing extensions (`aliases`, `waterfalls`). The `type` query

        param is a SINGLE protocol `ModelCategory` value: repeated `?type=` values

        and unknown categories are both 422 `request.invalid` naming `type`.'
      operationId: get_models_v1_models_get
      parameters:
      - name: type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter by model category: llm, extract, img_gen, search, judgment. Single value (protocol arity).'
          title: Type
        description: 'Filter by model category: llm, extract, img_gen, search, judgment. Single value (protocol arity).'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelexModelDeck'
        '401':
          description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
            or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
            or trusts a proxy''s forwarded identity and the proxy forwarded none.'
          headers:
            WWW-Authenticate:
              description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
                or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
            byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
            both in bytes.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
            refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
            or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
            error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
            diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '500':
          description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
            a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
            Report the `request_id`.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
      x-mthds-protocol: true
  /v1/models/check:
    get:
      tags:
      - agent
      summary: Check Model
      description: 'Check whether one model reference resolves on this runner, as what, to which model (Pipelex API extension).


        Answers from pipelex''s own reference parser and deck lookups, the ones a validation runs, so a

        reference found `resolved` in a category is one a pipe of that category may name, and one found

        `not_found` is one a validation refuses. A verdict is a `200` whatever the resolution, and on

        `not_found` it carries the suggestions a failing validation of the same reference offers. A

        request that cannot produce a verdict is an input `422` `request.invalid` naming the parameter: a

        missing or repeated `reference`, a repeated `type`, a reference that is blank, a sigil or a namespace

        alone, or too long, and an unknown `type`.'
      operationId: check_model_v1_models_check_get
      parameters:
      - name: reference
        in: query
        required: true
        schema:
          type: string
          description: 'The model reference as a method''s `model` field writes it: `$preset`, `@alias`, `~waterfall`, a bare
            model handle, or one of the namespaces `preset:`, `alias:`, `waterfall:` and `handle:`. Surrounding whitespace
            is ignored, and the trimmed reference holds at most 199 characters. Single value.'
          title: Reference
        description: 'The model reference as a method''s `model` field writes it: `$preset`, `@alias`, `~waterfall`, a bare
          model handle, or one of the namespaces `preset:`, `alias:`, `waterfall:` and `handle:`. Surrounding whitespace is
          ignored, and the trimmed reference holds at most 199 characters. Single value.'
      - name: type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'The category to check in: llm, extract, img_gen, search, judgment or doc_gen. When absent, the check
            is made in every one of them. Single value.'
          title: Type
        description: 'The category to check in: llm, extract, img_gen, search, judgment or doc_gen. When absent, the check
          is made in every one of them. Single value.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelReferenceVerdict'
        '401':
          description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
            or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
            or trusts a proxy''s forwarded identity and the proxy forwarded none.'
          headers:
            WWW-Authenticate:
              description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
                or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
            byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
            both in bytes.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
            refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
            or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
            error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
            diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '500':
          description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
            a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
            Report the `request_id`.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
  /v1/blobs/missing:
    post:
      tags:
      - blobs
      summary: Which of these blobs the runner lacks, and where to upload each.
      description: 'List every blob of the request this runner does not hold, each with a signed upload target (MTHDS Protocol).


        A blob it holds at the stated size is left out, and an empty list means there is nothing to upload; a hash held

        at another size than the one stated is listed too, and its upload tells the two cases apart: bytes of the size held

        change nothing, and bytes of another size mean the object held is damaged, a 500 `pipelex.storage.damaged`, since

        nothing writes over a blob. When the request names the tree the blobs

        make up by its `digest`, this runner has recorded that tree as held in full, which it does only after reading every

        file of a tree a request sent, and every listed blob is a file of that tree, the answer is an empty list at once.

        A hash given twice with different sizes is a 422 `request.invalid` naming `blobs`, and a blob or a set of blobs past

        this runner''s tree limits a 422 `method.package_invalid`, both refused before anything is uploaded. Each upload

        target is this runner''s own

        `PUT /v1/blobs/{sha256}`, at `PUBLIC_BASE_URL` when the deployment sets it, its query signed for that hash and

        the caller''s scope, valid for `BLOB_UPLOAD_URL_TTL_SECONDS`, to send with exactly the headers it names.'
      operationId: find_missing_blobs_v1_blobs_missing_post
      parameters:
      - name: read_scope
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'PIPELEX-API EXTENSION — the blob store''s scope, as a run''s `read_scope`: a multi-tenant host sends
            the one of the organization it serves. Omit it and the caller''s own id is the scope.'
          title: Read Scope
        description: 'PIPELEX-API EXTENSION — the blob store''s scope, as a run''s `read_scope`: a multi-tenant host sends
          the one of the organization it serves. Omit it and the caller''s own id is the scope.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MissingBlobsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MissingBlobsResult'
        '401':
          description: '`auth.missing_credential`, `auth.invalid_credential` or `auth.credential_expired` — a missing, refused
            or expired bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key` or `AUTH_MODE=jwt`),
            or trusts a proxy''s forwarded identity and the proxy forwarded none.'
          headers:
            WWW-Authenticate:
              description: Authentication challenge, `Bearer`, where the deployment reads a bearer token (`AUTH_MODE=api_key`
                or `AUTH_MODE=jwt`). Absent behind a trusted proxy, which reads no credential of the request.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: '`request.too_large` — the request, or a part of it such as a file it sends, exceeds one of the deployment''s
            byte limits (`MAX_REQUEST_BODY_MIB`, 100 MiB by default, for the body). `params.limit` and `params.size` give
            both in bytes.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a body that does not parse (`request.malformed`), fields the route
            refuses (`request.invalid`, one item in `errors` per refused field), a security rule''s refusal (such as `pipelex.security.reserved_key`
            or `security.input_url_refused`), a method tree the runner cannot read (`method.package_invalid`), or a pipelex
            error whose code the caller fixes (a `.mthds` bundle that does not validate, a missing input). Note that on the
            diagnostic routes an *invalid bundle* is a **200** verdict, not a 422 — see each route''s response contract.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '500':
          description: 'A failure the caller cannot fix: the runner''s own configuration (`runtime.misconfigured`, such as
            a missing env var), a bad TOML override, a backend fault, or an unexpected error answered as `runtime.unexpected`.
            Report the `request_id`.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '403':
          description: '`auth.forbidden`, whose `params.requirement` is `read_scope_under_caller` — on a `jwt` deployment,
            the request sent a `read_scope` that does not lie under the caller''s own `user_id`, the only scope its token
            may read.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
      x-mthds-protocol: true
  /:
    get:
      tags:
      - health
      summary: Service identity banner
      description: 'Identify the service answering on this origin. No auth required.


        A human-facing banner for someone who lands on the bare origin — not a

        liveness probe (that is `GET /health`) and not the protocol handshake

        (`GET /v1/version`). It reads nothing and can only succeed.'
      operationId: root__get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceIdentity'
components:
  schemas:
    AbsenceKind:
      type: string
      enum:
      - declared_absent
      - skipped
      - not_provided
      title: AbsenceKind
      description: "How a slot came to hold no value.\n\n- DECLARED_ABSENT: a producer with an optional (`?`) output declared\
        \ it produced nothing\n  (e.g. a PipeCondition `continue` outcome, or — phase 2 — an LLM maybe-wrapper), or a binding\n\
        \  step's path reached a field holding nothing.\n- SKIPPED: the producing pipe was lifted (skipped) because one of\
        \ its plain inputs was absent,\n  or a binding step was, because its root was.\n- NOT_PROVIDED: the caller omitted\
        \ an optional method input from the pipeline inputs."
    AbsenceRecord:
      properties:
        variable_name:
          type: string
          title: Variable Name
        kind:
          $ref: '#/components/schemas/AbsenceKind'
        reason:
          type: string
          title: Reason
        producing_pipe:
          anyOf:
          - type: string
          - type: 'null'
          title: Producing Pipe
        upstream:
          anyOf:
          - $ref: '#/components/schemas/AbsenceRecord'
          - type: 'null'
      additionalProperties: false
      type: object
      required:
      - variable_name
      - kind
      - reason
      title: AbsenceRecord
      description: 'A recorded fact that a named slot holds no value, with provenance (D2).


        Absence stays what it mechanically is — no Stuff under the name — but becomes a recorded

        fact: who produced it, why, and which upstream absence it chains to. Provenance is captured

        at the moment absence is produced, not reconstructed at failure time.'
    AliasMatch:
      properties:
        category:
          $ref: '#/components/schemas/ModelCheckCategory'
          description: The category this entry is about.
        resolves_to:
          anyOf:
          - type: string
          - type: 'null'
          title: Resolves To
          description: The model handle a run through the reference would call now in this category, or null when it would
            find none (a target on a backend the runner has not enabled, a waterfall none of whose usable steps the runner
            serves, an alias cycle).
        target:
          type: string
          title: Target
          description: The model the deck binds the alias to, as the deck writes it, which may itself be a reference.
      additionalProperties: false
      type: object
      required:
      - category
      - resolves_to
      - target
      title: AliasMatch
      description: What an alias reference is in one category.
    AspectRatio:
      type: string
      enum:
      - square
      - landscape_4_3
      - landscape_3_2
      - landscape_16_9
      - landscape_21_9
      - landscape_4_1
      - landscape_8_1
      - portrait_3_4
      - portrait_2_3
      - portrait_9_16
      - portrait_9_21
      - portrait_1_4
      - portrait_1_8
      title: AspectRatio
    Background:
      type: string
      enum:
      - transparent
      - opaque
      - auto
      title: Background
    Base64FileEntry:
      properties:
        base64:
          type: string
          title: Base64
          description: The file's bytes in canonical padded standard Base64.
      additionalProperties: false
      type: object
      required:
      - base64
      title: Base64FileEntry
      description: A file entry carrying the file's bytes in canonical padded standard Base64.
    BindingStepBlueprint:
      properties:
        from:
          type: string
          pattern: ^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z][A-Za-z0-9_]*)*$
          title: From
          description: 'The path to bind: a name in working memory followed by zero or more field names, separated by dots.'
        result:
          type: string
          pattern: ^[a-z][a-z0-9_]*$
          title: Result
          description: 'The name under which the bound value is stored in working memory: a plain input name.'
      additionalProperties: false
      type: object
      required:
      - from
      - result
      title: BindingStepBlueprint
      description: 'A PipeSequence step that binds the value at a path in working memory to a new name.


        `{ from = "invoice.total", result = "total_amount" }` stores a deep copy of the value at `invoice.total`

        under `total_amount`, as the concept the path derives through the declared structures. A binding step

        lives in a PipeSequence''s `steps` only, and carries exactly these two fields.'
    BlobRef:
      properties:
        sha256:
          type: string
          pattern: ^[0-9a-f]{64}$
          title: Sha256
          description: The SHA-256 of the bytes, in lowercase hexadecimal.
        size:
          type: integer
          minimum: 0.0
          title: Size
          description: The length of the bytes, a JSON integer written without a fraction or an exponent. A size written 13.0
            is refused, although JSON Schema's integer type admits it.
      additionalProperties: false
      type: object
      required:
      - sha256
      - size
      title: BlobRef
      description: A blob, named by its SHA-256 in lowercase hexadecimal and its length in bytes.
    BlockedEntry:
      properties:
        entry_id:
          type: string
          title: Entry Id
        to_schema_version:
          type: integer
          title: To Schema Version
        reason:
          $ref: '#/components/schemas/BlockedEntryReason'
        detail:
          type: string
          title: Detail
        guidance:
          anyOf:
          - type: string
          - type: 'null'
          title: Guidance
        applied_ops:
          items:
            oneOf:
            - $ref: '#/components/schemas/DeleteKeyOp'
            - $ref: '#/components/schemas/DeleteTableOp'
            - $ref: '#/components/schemas/RenameTableKeyOp'
            - $ref: '#/components/schemas/MoveKeyOp'
            - $ref: '#/components/schemas/RemapValueOp'
            discriminator:
              propertyName: kind
              mapping:
                delete_key: '#/components/schemas/DeleteKeyOp'
                delete_table: '#/components/schemas/DeleteTableOp'
                move_key: '#/components/schemas/MoveKeyOp'
                remap_value: '#/components/schemas/RemapValueOp'
                rename_table_key: '#/components/schemas/RenameTableKeyOp'
          type: array
          title: Applied Ops
        narrowed_paths:
          items:
            type: string
          type: array
          title: Narrowed Paths
      additionalProperties: false
      type: object
      required:
      - entry_id
      - to_schema_version
      - reason
      - detail
      title: BlockedEntry
      description: An entry that this file needs and the run would not apply.
    BlockedEntryReason:
      type: string
      enum:
      - unsafe
      - conflict
      - value_domain_narrowed
      title: BlockedEntryReason
      description: Why an entry could not be applied to this file.
    BooleanField:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: boolean
          title: Kind
          default: boolean
        name:
          type: string
          title: Name
      additionalProperties: false
      type: object
      required:
      - required
      - name
      title: BooleanField
      description: '`boolean` at a named position.'
    BooleanItem:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: boolean
          title: Kind
          default: boolean
      additionalProperties: false
      type: object
      required:
      - required
      title: BooleanItem
      description: '`boolean` — true or false.'
    CodegenRequest:
      properties:
        files:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/Base64FileEntry'
              - $ref: '#/components/schemas/HashFileEntry'
            type: object
          - type: 'null'
          title: Files
          description: 'The method as a map of file entries, the MTHDS standard''s form of a method tree that travels: each
            key is a tree path (relative, forward slashes, in Unicode NFC, no `.` or `..` segment, no segment starting with
            a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or `{"sha256": ..., "size":
            ...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing` then `PUT /v1/blobs/{sha256}`).
            The map is read from the request''s JSON text: a key given twice, a key the membership rule keeps out of every
            tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid` whose `reason` is the refusal''s
            code and whose `path` names the first path, a key leaving the tree is a 422 `security.input_path_refused`, a malformed
            entry is a 422 `request.invalid`, and hash entries the runner does not hold are one 422 `request.blobs_missing`
            whose `missing_blobs` parameter lists every such hash. Its `.mthds` files are the method''s bundles and every
            other file is one a step may read, such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`,
            the run starts at the `main_pipe` of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its
            bundles declare. Custom `.py` is only honored on a sandbox-hosted deployment. Exactly one of `files` / `method_ref`.'
        dependencies:
          anyOf:
          - additionalProperties:
              additionalProperties:
                anyOf:
                - type: string
                - $ref: '#/components/schemas/Base64FileEntry'
                - $ref: '#/components/schemas/HashFileEntry'
              type: object
            type: object
          - type: 'null'
          title: Dependencies
          description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the method packages the method calls by address
            that this runner cannot fetch, such as one an author has not published, as `{"<address>": <map of file entries>}`:
            each value is a tree of its own, read as `files` is, with a `METHODS.toml` at its root declaring the address it
            is keyed by. They are searched before the runner''s installed copies, for this request alone. Accompanies `files`.'
        method_ref:
          anyOf:
          - type: string
            maxLength: 512
            minLength: 1
          - type: 'null'
          title: Method Ref
          description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — a published method by reference, instead of
            its tree. Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is fetched and read as a `files` tree
            is, through the same path as a `method_ref` run; the registry form stays reserved (a 422 `request.unsupported`
            until a method registry exists). Exactly one of `files` / `method_ref`.
        resources:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Resources
          description: 'The files submitted with the bundle that its steps read, such as a PipeDocGen step''s `template_file`
            (an `.xlsx`, `.docx`, `.pptx` or `.html` template): a JSON object mapping each file''s bundle-relative path, exactly
            as the step names it, to the file''s bytes in standard base64. A path must be relative and written with forward
            slashes, with no `..` segment, backslash or colon. Beside inline `mthds_contents`, every bundle of the request
            is read as sitting in one directory, and every file must be named by a step, or the request is refused with a
            422 `BundleResourceNotNamedError`. Beside a method tree, `files` or `bundle_b64`, each file joins the tree at
            its path from the tree''s root, where a file the tree already holds must have the same bytes. By default at most
            32 files, 5120 KiB each and 10240 KiB in all, decoded; a deployment sets its own with `MAX_RESOURCES_PER_REQUEST`,
            `MAX_RESOURCE_FILE_KIB` and `MAX_RESOURCES_TOTAL_KIB`. The files make one method tree with the bundles, which
            the run names by its digest: no file''s bytes travel with the run, each being read where a step uses it. Being
            retired, and refused by a later release: a file the steps read travels inside the method''s tree, in `files`,
            at its path beside the bundle that names it.'
        read_scope:
          anyOf:
          - type: string
          - type: 'null'
          title: Read Scope
          description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the scope the request reads the method under,
            as a run''s `read_scope`: a multi-tenant host sends the one of the organization it serves. A hash entry of `files`
            resolves in that scope''s blob store, and the tree the request read is recorded there, so a later request can
            send it by hash. Omit it and a hash entry resolves in the caller''s own id''s store, and nothing is recorded.'
        kind:
          $ref: '#/components/schemas/CodegenRouteKind'
          description: What to project. `types` projects the crate's concept set into typed models.
        target:
          $ref: '#/components/schemas/CodegenTarget'
          description: 'For whom: `ts-zod` (zod schemas + inferred types), `python-pydantic` (self-contained BaseModels),
            or `python-structures` (runtime StructuredContent classes, for a Pipelex host).'
        pipe_ref:
          anyOf:
          - type: string
            maxLength: 512
          - type: 'null'
          title: Pipe Ref
          description: Pipe selector for per-pipe projection kinds. Not accepted for `types` (a concept-set-wide projection).
      type: object
      required:
      - kind
      - target
      title: CodegenRequest
      description: 'The codegen request: the crate routes'' method selector plus the two explicit projection axes.'
    CodegenRouteKind:
      type: string
      enum:
      - types
      title: CodegenRouteKind
      description: 'The projection kinds this route serves — the `kind` axis of the codegen request.


        Membership follows the **trust chain**: a kind is served here exactly when its artifacts are

        stamped and locked, so a client can write them verbatim and pass the offline `codegen check` —

        the promise this route''s valid arm makes by carrying a `lock`. Input templates are user-editable

        scaffolds, never stamped or locked, so they cannot make that promise: a client projects one from

        the input form `POST /pipe-io` serves, and `inputs` is therefore not a kind here. Future per-pipe kinds

        (`docs`, `tools`, `tests`) do emit tracked artifacts, so they join this enum and select their

        pipe via `pipe_ref`. An unknown kind is a request-shape 422 listing the served set.'
    CodegenTarget:
      type: string
      enum:
      - python-structures
      - python-pydantic
      - ts-zod
      title: CodegenTarget
      description: 'A codegen target flavor. All targets are Pipelex projections — the MTHDS standard specifies no

        type projection (see the codegen spec → "Ownership"). They differ in audience:

        `ts-zod` and `python-pydantic` emit idiom-neutral types any consumer can use; `python-structures`

        emits StructuredContent classes for a Pipelex runtime host.'
    CodegenValidReport:
      properties:
        is_valid:
          type: boolean
          const: true
          title: Is Valid
          default: true
        kind:
          $ref: '#/components/schemas/CodegenRouteKind'
          description: The projected kind (echo of the request).
        target:
          $ref: '#/components/schemas/CodegenTarget'
          description: The projection target (echo of the request).
        crate_fingerprint:
          type: string
          title: Crate Fingerprint
          description: Fingerprint of the normalized crate the artifacts were generated from.
        engine_version:
          type: string
          title: Engine Version
          description: The pipelex engine version that generated the artifacts.
        artifacts:
          items:
            $ref: '#/components/schemas/GeneratedArtifact'
          type: array
          title: Artifacts
          description: The stamped generated files.
        lock:
          type: string
          title: Lock
          description: The `codegen.lock` content (TOML) tracking the artifact set — write verbatim beside the artifacts.
        lock_filename:
          type: string
          title: Lock Filename
          description: Filename the lock content must be written as.
          default: codegen.lock
        message:
          type: string
          title: Message
          description: Status message
          default: Codegen artifacts generated successfully
      type: object
      required:
      - kind
      - target
      - crate_fingerprint
      - engine_version
      - lock
      title: CodegenValidReport
      description: 'The 200 **valid** arm: the stamped artifact set plus its lock.


        A client that writes each artifact and the lock verbatim reproduces a local

        `pipelex codegen types` run byte-for-byte — the same stamps, the same `codegen.lock` — so the

        offline `codegen check` passes on the written tree exactly as it would locally.'
    Concept:
      properties:
        code:
          type: string
          title: Code
        domain_code:
          type: string
          title: Domain Code
        description:
          type: string
          title: Description
        structure_class_name:
          type: string
          title: Structure Class Name
        refines:
          anyOf:
          - type: string
          - type: 'null'
          title: Refines
      additionalProperties: false
      type: object
      required:
      - code
      - domain_code
      - description
      - structure_class_name
      title: Concept
      description: 'A concept as the runtime holds it in memory: its name and its definition.


        The protocol model, `ConceptAbstract`, is a name and nothing more — `code`, `domain_code`

        and the `concept_ref` they form — because the standard keeps a concept''s definition in the

        library a method loads, never beside a stuff. The runtime needs the definition in memory to

        resolve a structure class, check compatibility and render a representation, so it declares

        those fields here, on its own subclass.


        The fields declared here never travel beside a stuff: `StuffAbstract` serializes `concept`

        as the ref string, so every dump of a `Stuff`, of a `WorkingMemory` and of a `PipeOutput`

        carries `{"concept": "<domain>.<Code>", "content": …}`. A reader of such a dump resolves the

        ref through the concept library the method loads, the way the input side does.'
    ConceptBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        description:
          type: string
          title: Description
        structure:
          anyOf:
          - type: string
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/ConceptStructureBlueprint'
            type: object
          - type: 'null'
          title: Structure
        refines:
          anyOf:
          - type: string
          - type: 'null'
          title: Refines
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
      additionalProperties: false
      type: object
      required:
      - description
      title: ConceptBlueprint
    ConceptStructureBlueprint:
      properties:
        description:
          type: string
          title: Description
        type:
          anyOf:
          - $ref: '#/components/schemas/ConceptStructureBlueprintFieldType'
          - type: 'null'
        key_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Type
        value_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Value Type
        item_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Item Type
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        item_concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Item Concept Ref
        choices:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Choices
        default_value:
          anyOf:
          - {}
          - type: 'null'
          title: Default Value
        required:
          type: boolean
          title: Required
          default: false
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
      additionalProperties: false
      type: object
      required:
      - description
      title: ConceptStructureBlueprint
      description: 'One field of a concept''s structure table. Unknown keys are rejected — the field table''s

        keys are strict, exactly like an input slot table''s; hint *content* stays lenient (unknown

        hint keys warn and are preserved, per intent-hints.md).'
    ConceptStructureBlueprintFieldType:
      type: string
      enum:
      - text
      - list
      - dict
      - integer
      - boolean
      - number
      - date
      - datetime
      - time
      - concept
      title: ConceptStructureBlueprintFieldType
    ConstructBlueprint:
      properties:
        fields:
          additionalProperties:
            $ref: '#/components/schemas/ConstructFieldBlueprint'
          type: object
          title: Fields
      additionalProperties: false
      type: object
      required:
      - fields
      title: ConstructBlueprint
      description: "Blueprint for composing a StructuredContent from working memory.\n\nParsed from `[pipe.name.construct]`\
        \ section in MTHDS files.\n\nAttributes:\n    fields: Dictionary mapping field names to their composition blueprints"
    ConstructFieldBlueprint:
      properties:
        method:
          $ref: '#/components/schemas/ConstructFieldMethod'
        fixed_value:
          anyOf:
          - {}
          - type: 'null'
          title: Fixed Value
        from_path:
          anyOf:
          - type: string
          - type: 'null'
          title: From Path
        template:
          anyOf:
          - type: string
          - type: 'null'
          title: Template
        nested:
          anyOf:
          - $ref: '#/components/schemas/ConstructBlueprint'
          - type: 'null'
        list_to_dict_keyed_by:
          anyOf:
          - type: string
          - type: 'null'
          title: List To Dict Keyed By
      additionalProperties: false
      type: object
      required:
      - method
      title: ConstructFieldBlueprint
      description: "Blueprint for composing a single field in a StructuredContent.\n\nDefines how a field value is composed\
        \ using one of 4 methods:\n1. Fixed value: literal string, number, bool, or list\n2. Variable reference (from): path\
        \ to variable in working memory\n3. Template: Jinja2 template string (with $ preprocessing)\n4. Nested construct:\
        \ recursive ConstructBlueprint\n\nAttributes:\n    method: The composition method to use\n    fixed_value: Literal\
        \ value (for FIXED method)\n    from_path: Variable path in working memory (for FROM_VAR method)\n    template: Jinja2\
        \ template string (for TEMPLATE method)\n    nested: Nested ConstructBlueprint (for NESTED method)\n    list_to_dict_keyed_by:\
        \ Optional modifier for FROM_VAR method that converts\n        a ListContent/list to dict keyed by the specified attribute\
        \ name"
    ConstructFieldMethod:
      type: string
      enum:
      - fixed
      - from_var
      - template
      - nested
      title: ConstructFieldMethod
      description: Method used to compose a field value.
    CrateInvalidReport:
      properties:
        is_valid:
          type: boolean
          const: false
          title: Is Valid
          default: false
        errors:
          items:
            $ref: '#/components/schemas/ProblemItem'
          type: array
          title: Errors
          description: One problem item per error, each with its own code, its parameters and its location — non-empty on
            every invalid verdict. The items of the verdict's problem, as a refusal's `errors` carry them.
        message:
          type: string
          title: Message
          description: Human-readable summary of the verdict.
          default: MTHDS library could not be resolved
      type: object
      title: CrateInvalidReport
      description: 'The 200 **invalid** arm shared by `/resolve`, `/codegen` and `/pipe-io` — the crate-verdict vocabulary.


        Same discipline as `/validate`''s `InvalidReport`: an invalid library is the *successful

        product* of a diagnostic call (the request was well-formed; the library was not), so it rides

        a 200 discriminated on `is_valid`, carrying the same problem items in `errors` that `/validate`

        emits for the identical failure.'
    DateField:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: date
          title: Kind
          default: date
        datetime:
          type: boolean
          title: Datetime
        name:
          type: string
          title: Name
      additionalProperties: false
      type: object
      required:
      - required
      - datetime
      - name
      title: DateField
      description: '`date` at a named position.'
    DateItem:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: date
          title: Kind
          default: date
        datetime:
          type: boolean
          title: Datetime
      additionalProperties: false
      type: object
      required:
      - required
      - datetime
      title: DateItem
      description: '`date` — a calendar date, or a point in time.'
    DeleteKeyOp:
      properties:
        table_path:
          items:
            type: string
          type: array
          title: Table Path
        kind:
          type: string
          const: delete_key
          title: Kind
          default: delete_key
        key:
          type: string
          title: Key
      additionalProperties: false
      type: object
      required:
      - table_path
      - key
      title: DeleteKeyOp
      description: Drop ``key`` from the addressed table.
    DeleteTableOp:
      properties:
        table_path:
          items:
            type: string
          type: array
          minItems: 1
          title: Table Path
        kind:
          type: string
          const: delete_table
          title: Kind
          default: delete_table
      additionalProperties: false
      type: object
      required:
      - table_path
      title: DeleteTableOp
      description: 'Drop the addressed table, including every chunk of one written out of order.


        ``table_path`` *is* the target rather than its parent, so it cannot be empty — deleting the

        document root is not a thing an op may express.'
    Diagnostic:
      properties:
        kind:
          type: string
          enum:
          - syntax
          - semantic
          - schema
          title: Kind
        severity:
          type: string
          title: Severity
        message:
          type: string
          title: Message
        location:
          anyOf:
          - type: string
          - type: 'null'
          title: Location
        range:
          anyOf:
          - $ref: '#/components/schemas/Range'
          - type: 'null'
      type: object
      required:
      - kind
      - severity
      - message
      - location
      - range
      title: Diagnostic
      description: Structured lint/format diagnostic returned by `pipelex-tools-py`.
    DiagnosticCause:
      properties:
        error_class:
          type: string
          title: Error Class
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
      additionalProperties: true
      type: object
      required:
      - error_class
      title: DiagnosticCause
      description: One error of a failure's cause chain, by its class and the code it carries by itself.
    DocGenFormat:
      type: string
      enum:
      - pdf
      - xlsx
      - docx
      - pptx
      title: DocGenFormat
      description: 'The file formats a `PipeDocGen` step can ask for.


        The tokens are MTHDS: a method names one, and it loads wherever the standard is read. Which of them a

        runtime prints depends on the document engines installed in it, each a model of the `doc_gen` family:

        open Pipelex prints a `pdf` laid out without a template, on `reportlab-pdf`, and the Pipelex document

        generation plugin prints the rest. HTML is not a format: `PipeCompose` already produces the native

        `Html`.'
    DocGenSetting:
      properties:
        model:
          type: string
          title: Model
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      additionalProperties: false
      type: object
      required:
      - model
      title: DocGenSetting
      description: 'The document engine a `PipeDocGen` step prints with: a model of the `doc_gen` family, such as `reportlab-pdf`.'
    DocumentField:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: document
          title: Kind
          default: document
        name:
          type: string
          title: Name
      additionalProperties: false
      type: object
      required:
      - required
      - name
      title: DocumentField
      description: '`document` at a named position.'
    DocumentItem:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: document
          title: Kind
          default: document
      additionalProperties: false
      type: object
      required:
      - required
      title: DocumentItem
      description: '`document` — a document supplied as a file or a URL.


        No accept-list and no upload affordance: what the value is rides `concept_ref` and `refines`,

        and how a renderer offers a file is the renderer''s decision.'
    DryRunStatus:
      type: string
      enum:
      - SUCCESS
      - FAILURE
      - SKIPPED
      title: DryRunStatus
    EdgeKind:
      type: string
      enum:
      - control
      - data
      - contains
      - selected_outcome
      - batch_item
      - batch_aggregate
      - parallel_combine
      title: EdgeKind
      description: Types of edges in the execution graph.
    EdgeSpec:
      properties:
        id:
          type: string
          title: Id
        source:
          type: string
          title: Source
        target:
          type: string
          title: Target
        kind:
          $ref: '#/components/schemas/EdgeKind'
        optional:
          type: boolean
          title: Optional
          default: false
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        source_stuff_digest:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Stuff Digest
        target_stuff_digest:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Stuff Digest
        meta:
          additionalProperties: true
          type: object
          title: Meta
      additionalProperties: false
      type: object
      required:
      - id
      - source
      - target
      - kind
      title: EdgeSpec
      description: Specification for an edge in the execution graph.
    ElaborationMetadata:
      properties:
        parent_pipe_code:
          type: string
          title: Parent Pipe Code
        step_role:
          $ref: '#/components/schemas/StepRole'
      type: object
      required:
      - parent_pipe_code
      - step_role
      title: ElaborationMetadata
      description: Side-table entry recording how a synthetic pipe was generated by the bundle elaborator.
    EnumField:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: enum
          title: Kind
          default: enum
        choices:
          items:
            type: string
          type: array
          title: Choices
        name:
          type: string
          title: Name
      additionalProperties: false
      type: object
      required:
      - required
      - choices
      - name
      title: EnumField
      description: '`enum` at a named position.'
    EnumItem:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: enum
          title: Kind
          default: enum
        choices:
          items:
            type: string
          type: array
          title: Choices
      additionalProperties: false
      type: object
      required:
      - required
      - choices
      title: EnumItem
      description: '`enum` — one of a fixed set of values.'
    ExtractSetting:
      properties:
        model:
          type: string
          title: Model
        max_nb_images:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Max Nb Images
        image_min_size:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Image Min Size
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      additionalProperties: false
      type: object
      required:
      - model
      title: ExtractSetting
    FileBlockedReason:
      type: string
      enum:
      - unreadable
      - unparseable
      - unsupported_schema_version
      - unwritable
      - changed_during_run
      - needs_a_hand_edit
      - state_uncertain
      title: FileBlockedReason
      description: 'Why a file could not be processed at all.


        One member per *state the file is in*, because that is what decides what the user does next —

        not one per exception the run happened to catch. Every member but `STATE_UNCERTAIN` leaves the

        file exactly as it was found; that one does not, and it says so.'
    FormatRequest:
      properties:
        content:
          type: string
          title: Content
          description: Single .mthds file content to lint or format.
        options:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Options
          description: Optional formatter options passed through to `pipelex_tools.format_mthds`, such as `column_width`.
            Malformed option values return a 422 problem response.
      type: object
      required:
      - content
      title: FormatRequest
      description: Body of `POST /format`.
    FormatResponse:
      properties:
        formatted:
          type: string
          title: Formatted
        changed:
          type: boolean
          title: Changed
        diagnostics:
          items:
            $ref: '#/components/schemas/Diagnostic'
          type: array
          title: Diagnostics
      type: object
      required:
      - formatted
      - changed
      - diagnostics
      title: FormatResponse
      description: Response body of `POST /format`.
    GeneratedArtifact:
      properties:
        path:
          type: string
          title: Path
          description: Artifact path, relative to the output root the client writes into.
        content:
          type: string
          title: Content
          description: Complete file content, stamp header included — write verbatim.
      type: object
      required:
      - path
      - content
      title: GeneratedArtifact
      description: 'One generated file: its path relative to the client''s chosen output root, and its full content.'
    GraphSpec:
      properties:
        graph_id:
          type: string
          title: Graph Id
        created_at:
          type: string
          format: date-time
          title: Created At
        pipeline_ref:
          $ref: '#/components/schemas/PipelineRef'
        nodes:
          items:
            $ref: '#/components/schemas/NodeSpec'
          type: array
          title: Nodes
        edges:
          items:
            $ref: '#/components/schemas/EdgeSpec'
          type: array
          title: Edges
        usage:
          anyOf:
          - $ref: '#/components/schemas/GraphUsageSpec'
          - type: 'null'
        meta:
          additionalProperties: true
          type: object
          title: Meta
        pipe_registry:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Pipe Registry
        concept_registry:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Concept Registry
      additionalProperties: false
      type: object
      required:
      - graph_id
      - created_at
      title: GraphSpec
      description: 'The canonical specification for a pipeline execution graph.


        This is the top-level model representing a complete run graph.

        It is versioned and designed for JSON serialization.'
    GraphUsageSpec:
      properties:
        total:
          $ref: '#/components/schemas/NodeUsageSpec'
        unattributed:
          $ref: '#/components/schemas/NodeUsageSpec'
      additionalProperties: false
      type: object
      required:
      - total
      - unattributed
      title: GraphUsageSpec
      description: 'Run-level inference usage for a whole GraphSpec.


        ``total`` covers every usage the run reported, attributed or not — it is the graph''s

        comparand for the cost report''s own total. ``unattributed`` is the part that named no

        live node (the ``UNATTRIBUTED_NODE_ID`` fallback, or a node that never emitted a

        start event): surfaced as its own bucket rather than dropped, so the graph''s total

        can never silently disagree with the cost report''s.


        Both reuse ``NodeUsageSpec`` — one usage shape in the contract, not two. Neither has

        a subtree distinct from itself, so their ``subtree_*`` fields repeat their own.'
    HandleMatch:
      properties:
        category:
          $ref: '#/components/schemas/ModelCheckCategory'
          description: The category this entry is about.
        resolves_to:
          anyOf:
          - type: string
          - type: 'null'
          title: Resolves To
          description: The model handle a run through the reference would call now in this category, or null when it would
            find none (a target on a backend the runner has not enabled, a waterfall none of whose usable steps the runner
            serves, an alias cycle).
        via:
          items:
            type: string
          type: array
          title: Via
          description: The presets, aliases and waterfalls of this category whose binding names the handle directly, each
            written as a reference.
      additionalProperties: false
      type: object
      required:
      - category
      - resolves_to
      - via
      title: HandleMatch
      description: What a bare handle reference is in one category.
    HashFileEntry:
      properties:
        sha256:
          type: string
          pattern: ^[0-9a-f]{64}$
          title: Sha256
          description: The SHA-256 of the file's bytes, in lowercase hexadecimal.
        size:
          type: integer
          minimum: 0.0
          title: Size
          description: The file's size in bytes, an integer written with no fraction or exponent.
      additionalProperties: false
      type: object
      required:
      - sha256
      - size
      title: HashFileEntry
      description: A file entry naming, by their SHA-256 and their size, bytes the receiver already holds in its blob store.
    HealthResponse:
      properties:
        status:
          type: string
          title: Status
          description: Always `ok` — the endpoint answers only when the process is serving.
        message:
          type: string
          title: Message
          description: Human-readable confirmation that the server is up.
      type: object
      required:
      - status
      - message
      title: HealthResponse
      description: Body of `GET /health`.
    IOMultiplicity:
      type: string
      enum:
      - single
      - variable
      - fixed
      title: IOMultiplicity
      description: 'How many items a slot takes or a pipe resolves to: one item, a variable-length list, or a fixed count.


        Read together with `item_count`, which is non-null exactly on the `fixed` arm. `Concept[1]`

        is `single` — one item, no list framing — because the language says so, so a `fixed` count on

        this wire is always greater than one.'
    IOSpec:
      properties:
        name:
          type: string
          title: Name
        concept:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
        preview:
          anyOf:
          - type: string
          - type: 'null'
          title: Preview
        size:
          anyOf:
          - type: integer
          - type: 'null'
          title: Size
        digest:
          anyOf:
          - type: string
          - type: 'null'
          title: Digest
        data:
          anyOf:
          - type: string
          - additionalProperties: true
            type: object
          - items:
              type: string
            type: array
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Data
        multiplicity:
          anyOf:
          - type: boolean
          - type: integer
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Multiplicity
        extra:
          additionalProperties: true
          type: object
          title: Extra
      additionalProperties: false
      type: object
      required:
      - name
      title: IOSpec
      description: 'Specification for an input or output variable.


        Previews are automatically truncated to MAX_PREVIEW_LENGTH to prevent

        accidental storage of large payloads or sensitive data.


        The optional `data` field can hold the full serialized content when

        full data capture is enabled (via --graph-full-data CLI option).


        `concept` is always the bare concept code; whether the stuff is a list is `multiplicity`,

        in the encoding the pipe registry uses for a stuff spec''s multiplicity: `True` for a

        variable-length list, a positive integer for a fixed count, `None` (or `False`) for a single

        value, a count of one reading as single. A reader takes absence as single.'
    ImageField:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: image
          title: Kind
          default: image
        name:
          type: string
          title: Name
      additionalProperties: false
      type: object
      required:
      - required
      - name
      title: ImageField
      description: '`image` at a named position.'
    ImageFormat:
      type: string
      enum:
      - png
      - jpeg
      - webp
      title: ImageFormat
    ImageItem:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: image
          title: Kind
          default: image
      additionalProperties: false
      type: object
      required:
      - required
      title: ImageItem
      description: '`image` — an image, which a renderer may preview.'
    ImageSize:
      properties:
        width:
          type: integer
          exclusiveMinimum: 0.0
          title: Width
        height:
          type: integer
          exclusiveMinimum: 0.0
          title: Height
      type: object
      required:
      - width
      - height
      title: ImageSize
    ImgGenSetting:
      properties:
        model:
          type: string
          title: Model
        quality:
          anyOf:
          - $ref: '#/components/schemas/Quality'
          - type: 'null'
        nb_steps:
          anyOf:
          - type: integer
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Nb Steps
        guidance_scale:
          anyOf:
          - type: number
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Guidance Scale
        is_moderated:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Moderated
        safety_tolerance:
          anyOf:
          - type: integer
            maximum: 6.0
            minimum: 1.0
          - type: 'null'
          title: Safety Tolerance
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      additionalProperties: false
      type: object
      required:
      - model
      title: ImgGenSetting
    InputSlotBlueprint:
      properties:
        concept:
          type: string
          title: Concept
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
      additionalProperties: false
      type: object
      required:
      - concept
      title: InputSlotBlueprint
      description: 'The expanded input-slot form: `name = { concept = "…", hints = { … } }` (spec: intent-hints.md).


        `concept` carries the full slot grammar of the string form (ref, optional multiplicity, optional

        presence marker). The form is deliberately closed (`extra="forbid"` implements the spec''s

        "unknown slot-table keys MUST be rejected") so future per-slot semantic keys land here without a

        second syntax. A slot table carrying no hints collapses to its plain string at parse time (see

        `PipeBlueprint.collapse_hint_free_slot_tables`), so a slot value that IS a table carries

        non-empty hints — hint-free bundles produce byte-identical blueprints to the string form.'
    InvalidReport:
      properties:
        is_valid:
          type: boolean
          const: false
          title: Is Valid
          default: false
        errors:
          items:
            $ref: '#/components/schemas/ProblemItem'
          type: array
          title: Errors
          description: One problem item per error, each with its own code, its parameters and its location — non-empty on
            every invalid verdict. The items of the verdict's problem, as a refusal's `errors` carry them.
        pending_signatures:
          items:
            type: string
          type: array
          title: Pending Signatures
          description: Best-effort outstanding signatures; empty on the invalid arm since no library was assembled.
        is_runnable:
          type: boolean
          const: false
          title: Is Runnable
          default: false
        message:
          type: string
          title: Message
          description: Human-readable summary of the verdict.
          default: MTHDS validation found errors
        rendered_markdown:
          anyOf:
          - type: string
          - type: 'null'
          title: Rendered Markdown
          description: 'Opt-in Pipelex-API presentation extra: a server-rendered Markdown view of the invalid verdict''s errors,
            present only when the request''s `render` includes `markdown`. Absent by default.'
      type: object
      title: InvalidReport
      description: 'The 200 **invalid** arm: a produced "invalid" verdict, discriminated on `is_valid: false`.


        An invalid bundle is the *successful product* of a diagnostic call, not a transport failure

        (the request was well-formed; the bundle was not), so it rides a **200** — the global

        `problem+json` 422/5xx is reserved for the no-verdict conditions (malformed request body,

        `mthds_sources` length mismatch, auth, server fault). The structural artifacts

        (`bundle_blueprint`, `pipe_io_contracts`, `graph_spec`, `validated_pipes`) do not exist when

        load/parse/wiring failed, so this arm omits them and carries only the per-error diagnostics,

        as the problem items of the verdict''s problem (`errors`), plus the runnability facts. The

        `input_form` and `output_form` views follow them into absence for the same reason — both derive

        from a crate that was never assembled — so neither is declared here and `views` has no effect

        on this arm (unlike `rendered_markdown`, which rides both arms because failure

        text is exactly what a human surface wants).'
    JudgeQuestionBlueprint:
      properties:
        question:
          type: string
          title: Question
        options:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Options
        levels:
          anyOf:
          - items:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/JudgeRatingLevel'
            type: array
          - type: 'null'
          title: Levels
        criteria:
          anyOf:
          - $ref: '#/components/schemas/JudgeYesNoCriteria'
          - type: 'null'
        threshold:
          anyOf:
          - type: number
          - type: 'null'
          title: Threshold
      additionalProperties: false
      type: object
      required:
      - question
      title: JudgeQuestionBlueprint
      description: 'One question of a PipeJudge asking several: what it asks, and the fields the single form sets on the pipe.


        Closed, as the standard requires: `question` is the instruction, a plain text template, and the kind

        is decided by which of `options` and `levels` the question declares, under the single form''s rules,

        which `PipeJudgeBlueprint` checks, since a refusal names the question and only its key in `questions`

        does. That key also names the output field holding its verdict.'
    JudgeRatingLevel:
      properties:
        label:
          anyOf:
          - type: string
          - type: 'null'
          title: Label
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      additionalProperties: false
      type: object
      title: JudgeRatingLevel
      description: 'A rating level written as a table: a `label` naming it in a few words, a `description` of the situation
        it stands for, or both.


        Closed, as the standard requires. A level written as a plain string is its description.'
    JudgeYesNoCriteria:
      properties:
        'yes':
          type: string
          title: 'Yes'
        'no':
          type: string
          title: 'No'
      additionalProperties: false
      type: object
      required:
      - 'yes'
      - 'no'
      title: JudgeYesNoCriteria
      description: 'What a yes and a no mean, for a yes/no question: both sides, each non-empty. Closed: a key other than
        `yes` or `no` is refused.


        The judging vendors silently ignore a criterion key they do not know, so this model is the only

        place a typo in one is caught. Both sides are required because a lone side cannot be carried with

        its meaning on every backend: one sends a single criterion as one of a pair of options, where the

        side left out would be a blank.'
    JudgmentSetting:
      properties:
        model:
          type: string
          title: Model
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      additionalProperties: false
      type: object
      required:
      - model
      title: JudgmentSetting
    LLMSetting:
      properties:
        model:
          type: string
          title: Model
        temperature:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Temperature
        max_tokens:
          anyOf:
          - type: integer
          - enum:
            - auto
          - type: 'null'
          title: Max Tokens
        image_detail:
          anyOf:
          - $ref: '#/components/schemas/PromptImageDetail'
          - type: 'null'
        reasoning_effort:
          anyOf:
          - $ref: '#/components/schemas/ReasoningEffort'
          - type: 'null'
        reasoning_budget:
          anyOf:
          - type: integer
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Reasoning Budget
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      additionalProperties: false
      type: object
      required:
      - model
      - temperature
      title: LLMSetting
    LiftablePipeEntry:
      properties:
        pipe_ref:
          type: string
          title: Pipe Ref
        within_pipe_ref:
          type: string
          title: Within Pipe Ref
        skipped_when_absent:
          items:
            type: string
          type: array
          title: Skipped When Absent
        absence_source:
          type: string
          title: Absence Source
      type: object
      required:
      - pipe_ref
      - within_pipe_ref
      - absence_source
      title: LiftablePipeEntry
      description: One pipe that may be skipped (lifted) when an optional slot resolves absent.
    LintRequest:
      properties:
        content:
          type: string
          title: Content
          description: Single .mthds file content to lint or format.
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
          description: Optional logical filename for the content. Accepted for parity with `pipelex_tools.lint_mthds`; current
            diagnostics do not yet include the filename.
      type: object
      required:
      - content
      title: LintRequest
      description: Body of `POST /lint`.
    LintResponse:
      properties:
        diagnostics:
          items:
            $ref: '#/components/schemas/Diagnostic'
          type: array
          title: Diagnostics
      type: object
      required:
      - diagnostics
      title: LintResponse
      description: Response body of `POST /lint`.
    ListField:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: list
          title: Kind
          default: list
        item:
          oneOf:
          - $ref: '#/components/schemas/TextItem'
          - $ref: '#/components/schemas/ProseItem'
          - $ref: '#/components/schemas/DateItem'
          - $ref: '#/components/schemas/NumberItem'
          - $ref: '#/components/schemas/BooleanItem'
          - $ref: '#/components/schemas/EnumItem'
          - $ref: '#/components/schemas/DocumentItem'
          - $ref: '#/components/schemas/ImageItem'
          - $ref: '#/components/schemas/ObjectItem'
          - $ref: '#/components/schemas/ListItem'
          - $ref: '#/components/schemas/UnknownItem'
          title: Item
          discriminator:
            propertyName: kind
            mapping:
              boolean: '#/components/schemas/BooleanItem'
              date: '#/components/schemas/DateItem'
              document: '#/components/schemas/DocumentItem'
              enum: '#/components/schemas/EnumItem'
              image: '#/components/schemas/ImageItem'
              list: '#/components/schemas/ListItem'
              number: '#/components/schemas/NumberItem'
              object: '#/components/schemas/ObjectItem'
              prose: '#/components/schemas/ProseItem'
              text: '#/components/schemas/TextItem'
              unknown: '#/components/schemas/UnknownItem'
        item_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Item Count
        name:
          type: string
          title: Name
      additionalProperties: false
      type: object
      required:
      - required
      - item
      - name
      title: ListField
      description: '`list` at a named position, recursing through a nameless `item`.'
    ListItem:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: list
          title: Kind
          default: list
        item:
          oneOf:
          - $ref: '#/components/schemas/TextItem'
          - $ref: '#/components/schemas/ProseItem'
          - $ref: '#/components/schemas/DateItem'
          - $ref: '#/components/schemas/NumberItem'
          - $ref: '#/components/schemas/BooleanItem'
          - $ref: '#/components/schemas/EnumItem'
          - $ref: '#/components/schemas/DocumentItem'
          - $ref: '#/components/schemas/ImageItem'
          - $ref: '#/components/schemas/ObjectItem'
          - $ref: '#/components/schemas/ListItem'
          - $ref: '#/components/schemas/UnknownItem'
          title: Item
          discriminator:
            propertyName: kind
            mapping:
              boolean: '#/components/schemas/BooleanItem'
              date: '#/components/schemas/DateItem'
              document: '#/components/schemas/DocumentItem'
              enum: '#/components/schemas/EnumItem'
              image: '#/components/schemas/ImageItem'
              list: '#/components/schemas/ListItem'
              number: '#/components/schemas/NumberItem'
              object: '#/components/schemas/ObjectItem'
              prose: '#/components/schemas/ProseItem'
              text: '#/components/schemas/TextItem'
              unknown: '#/components/schemas/UnknownItem'
        item_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Item Count
      additionalProperties: false
      type: object
      required:
      - required
      - item
      title: ListItem
      description: '`list` — an array of one element type, recursing through its `item`.


        An input slot authored `Concept[]` is a `list` with no `item_count`; one authored `Concept[N]`

        carries `item_count: N`. `Concept[1]` is single — no list framing — so a stated count is always

        at least 2. `concept_ref` and `refines` name the element concept, and the `item` carries the

        same `concept_ref`; on a plural node the merged `hints` ride both the list and its item.'
    MethodProvenance:
      properties:
        address:
          type: string
          title: Address
        tag:
          anyOf:
          - type: string
          - type: 'null'
          title: Tag
        commit_sha:
          type: string
          title: Commit Sha
        tree_digest:
          anyOf:
          - type: string
          - type: 'null'
          title: Tree Digest
          description: The digest of the package's method tree, `sha256:` and 64 lowercase hex characters, as read from the
            commit's git objects, set by a runner that reads the package as a tree, and null otherwise.
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
          description: The package's human-readable name, the `display_name` its `METHODS.toml` manifest declares at the fetched
            commit, for a host to name the run's method by, and null when the manifest declares none.
      type: object
      required:
      - address
      - commit_sha
      title: MethodProvenance
      description: 'What a fetched-method run must record: address, tag, the resolved commit SHA, and the name the package
        declares.'
    MethodTreeRequest:
      properties:
        files:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/Base64FileEntry'
              - $ref: '#/components/schemas/HashFileEntry'
            type: object
          - type: 'null'
          title: Files
          description: 'The method as a map of file entries, the MTHDS standard''s form of a method tree that travels: each
            key is a tree path (relative, forward slashes, in Unicode NFC, no `.` or `..` segment, no segment starting with
            a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or `{"sha256": ..., "size":
            ...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing` then `PUT /v1/blobs/{sha256}`).
            The map is read from the request''s JSON text: a key given twice, a key the membership rule keeps out of every
            tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid` whose `reason` is the refusal''s
            code and whose `path` names the first path, a key leaving the tree is a 422 `security.input_path_refused`, a malformed
            entry is a 422 `request.invalid`, and hash entries the runner does not hold are one 422 `request.blobs_missing`
            whose `missing_blobs` parameter lists every such hash. Its `.mthds` files are the method''s bundles and every
            other file is one a step may read, such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`,
            the run starts at the `main_pipe` of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its
            bundles declare. Custom `.py` is only honored on a sandbox-hosted deployment. Exactly one of `files` / `method_ref`.'
        dependencies:
          anyOf:
          - additionalProperties:
              additionalProperties:
                anyOf:
                - type: string
                - $ref: '#/components/schemas/Base64FileEntry'
                - $ref: '#/components/schemas/HashFileEntry'
              type: object
            type: object
          - type: 'null'
          title: Dependencies
          description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the method packages the method calls by address
            that this runner cannot fetch, such as one an author has not published, as `{"<address>": <map of file entries>}`:
            each value is a tree of its own, read as `files` is, with a `METHODS.toml` at its root declaring the address it
            is keyed by. They are searched before the runner''s installed copies, for this request alone. Accompanies `files`.'
        method_ref:
          anyOf:
          - type: string
            maxLength: 512
            minLength: 1
          - type: 'null'
          title: Method Ref
          description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — a published method by reference, instead of
            its tree. Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is fetched and read as a `files` tree
            is, through the same path as a `method_ref` run; the registry form stays reserved (a 422 `request.unsupported`
            until a method registry exists). Exactly one of `files` / `method_ref`.
        resources:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Resources
          description: 'The files submitted with the bundle that its steps read, such as a PipeDocGen step''s `template_file`
            (an `.xlsx`, `.docx`, `.pptx` or `.html` template): a JSON object mapping each file''s bundle-relative path, exactly
            as the step names it, to the file''s bytes in standard base64. A path must be relative and written with forward
            slashes, with no `..` segment, backslash or colon. Beside inline `mthds_contents`, every bundle of the request
            is read as sitting in one directory, and every file must be named by a step, or the request is refused with a
            422 `BundleResourceNotNamedError`. Beside a method tree, `files` or `bundle_b64`, each file joins the tree at
            its path from the tree''s root, where a file the tree already holds must have the same bytes. By default at most
            32 files, 5120 KiB each and 10240 KiB in all, decoded; a deployment sets its own with `MAX_RESOURCES_PER_REQUEST`,
            `MAX_RESOURCE_FILE_KIB` and `MAX_RESOURCES_TOTAL_KIB`. The files make one method tree with the bundles, which
            the run names by its digest: no file''s bytes travel with the run, each being read where a step uses it. Being
            retired, and refused by a later release: a file the steps read travels inside the method''s tree, in `files`,
            at its path beside the bundle that names it.'
        read_scope:
          anyOf:
          - type: string
          - type: 'null'
          title: Read Scope
          description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the scope the request reads the method under,
            as a run''s `read_scope`: a multi-tenant host sends the one of the organization it serves. A hash entry of `files`
            resolves in that scope''s blob store, and the tree the request read is recorded there, so a later request can
            send it by hash. Omit it and a hash entry resolves in the caller''s own id''s store, and nothing is recorded.'
      type: object
      title: MethodTreeRequest
      description: 'The method selector of the crate routes (`/resolve`, `/codegen`, `/pipe-io`): a tree sent in `files` XOR
        a `method_ref`.


        Exactly one of the two must be provided — both or neither is a request-shape 422. The tree is the MTHDS standard''s

        map of file entries, read from the request''s raw JSON text exactly as `/validate` and the run routes read it

        (`pipelex_api.method_tree_request`), with the `dependencies` it carries and the `resources` that join it. An

        **address-form** `method_ref` (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is resolved by this server through

        the run routes'' fetch path: the package''s tree is read from its commit''s git objects, with the packages it ships

        under `.mthds/methods/`. The **registry form** (any non-address reference) stays reserved, a 422

        `request.unsupported`, until server-side method-registry resolution exists. Either way the method is held to the run
        routes'' Python policy:

        custom `.py` only on a sandbox-hosted deployment, and no Python structure class at all.'
    MigrationErrorBlock:
      properties:
        remedy:
          type: string
          title: Remedy
        would_write:
          type: boolean
          title: Would Write
        needs_attention:
          type: boolean
          title: Needs Attention
        plans:
          items:
            $ref: '#/components/schemas/MigrationPlan'
          type: array
          title: Plans
      additionalProperties: false
      type: object
      required:
      - remedy
      - would_write
      - needs_attention
      - plans
      title: MigrationErrorBlock
      description: 'A pending configuration migration, reported alongside the error it explains.


        The structured half of the answer to *why does my configuration not load*, carried by the operator''s

        ``diagnostics.migration`` and present only when a scan of this machine''s configuration directories found something

        to say. **Consumers branch on its presence**, never on the message text: an absent block means the failure is not

        staleness. It describes the host''s own configuration directories, so only an operator reads it.


        ``plans`` is the same shape ``pipelex-agent migrate --dry-run --format json`` emits under its own ``plans`` key,

        deliberately: an agent that reads one has already parsed the other.


        > **No value read from a user''s file is ever rendered** here either. The plans carry paths, operation kinds and

        > ledger-supplied values, and nothing else.'
    MigrationPlan:
      properties:
        surface_id:
          type: string
          title: Surface Id
        file_path:
          type: string
          format: path
          title: File Path
        blocked_reason:
          anyOf:
          - $ref: '#/components/schemas/FileBlockedReason'
          - type: 'null'
        blocked_detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Blocked Detail
        steps:
          items:
            $ref: '#/components/schemas/MigrationStep'
          type: array
          title: Steps
        blocked:
          items:
            $ref: '#/components/schemas/BlockedEntry'
          type: array
          title: Blocked
        unexplained:
          items:
            $ref: '#/components/schemas/UnexplainedPath'
          type: array
          title: Unexplained
        backup_path:
          anyOf:
          - type: string
            format: path
          - type: 'null'
          title: Backup Path
        was_written:
          type: boolean
          title: Was Written
          default: false
      additionalProperties: false
      type: object
      required:
      - surface_id
      - file_path
      title: MigrationPlan
      description: What one file needs, and what this run did to it.
    MigrationSafety:
      type: string
      enum:
      - safe
      - unsafe
      title: MigrationSafety
      description: 'Whether the applier may act on an entry.


        Independent of `guidance`, which any entry may carry whatever its safety.'
    MigrationStep:
      properties:
        entry_id:
          type: string
          title: Entry Id
        to_schema_version:
          type: integer
          title: To Schema Version
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
        breaking:
          type: boolean
          title: Breaking
        safety:
          $ref: '#/components/schemas/MigrationSafety'
        applied_ops:
          items:
            oneOf:
            - $ref: '#/components/schemas/DeleteKeyOp'
            - $ref: '#/components/schemas/DeleteTableOp'
            - $ref: '#/components/schemas/RenameTableKeyOp'
            - $ref: '#/components/schemas/MoveKeyOp'
            - $ref: '#/components/schemas/RemapValueOp'
            discriminator:
              propertyName: kind
              mapping:
                delete_key: '#/components/schemas/DeleteKeyOp'
                delete_table: '#/components/schemas/DeleteTableOp'
                move_key: '#/components/schemas/MoveKeyOp'
                remap_value: '#/components/schemas/RemapValueOp'
                rename_table_key: '#/components/schemas/RenameTableKeyOp'
          type: array
          title: Applied Ops
      additionalProperties: false
      type: object
      required:
      - entry_id
      - to_schema_version
      - title
      - description
      - breaking
      - safety
      - applied_ops
      title: MigrationStep
      description: One ledger entry that changed this file, and the operations of it that fired.
    MissingBlob:
      properties:
        sha256:
          type: string
          pattern: ^[0-9a-f]{64}$
          title: Sha256
        size:
          type: integer
          minimum: 0.0
          title: Size
          description: The length of the bytes, a JSON integer written without a fraction or an exponent. A size written 13.0
            is refused, although JSON Schema's integer type admits it.
        upload:
          $ref: '#/components/schemas/UploadTarget'
      type: object
      required:
      - sha256
      - size
      - upload
      title: MissingBlob
      description: A blob the runner lacks, with where to upload it.
    MissingBlobsRequest:
      properties:
        blobs:
          items:
            $ref: '#/components/schemas/BlobRef'
          type: array
          title: Blobs
          description: The blobs to check, each hash listed once.
        digest:
          anyOf:
          - type: string
            pattern: ^sha256:[0-9a-f]{64}$
          - type: 'null'
          title: Digest
          description: The tree digest of the method tree the blobs make up (optional).
      additionalProperties: true
      type: object
      required:
      - blobs
      title: MissingBlobsRequest
      description: The blobs a sender is about to send by hash, and optionally the tree they make up.
    MissingBlobsResult:
      properties:
        missing:
          items:
            $ref: '#/components/schemas/MissingBlob'
          type: array
          title: Missing
      type: object
      required:
      - missing
      title: MissingBlobsResult
      description: The blobs of the request the runner does not hold.
    ModelCategory:
      type: string
      enum:
      - llm
      - extract
      - img_gen
      - search
      - judgment
      title: ModelCategory
      description: 'The protocol''s model categories: what a deck entry''s `type` reports and the `GET /models?type=` filter
        accepts.


        A category is a settings family of the language — the inline settings a model

        serves, and so the pipes that can name it: `llm` (`LLMSetting`, named by

        `PipeLLM` and `PipeStructure`), `extract` (`ExtractSetting`, `PipeExtract`),

        `img_gen` (`ImgGenSetting`, `PipeImgGen`), `search` (`SearchSetting`,

        `PipeSearch`) and `judgment` (`JudgmentSetting`, `PipeJudge`). A settings

        family the standard adds brings a category in the next protocol minor.'
    ModelCheckCategory:
      type: string
      enum:
      - llm
      - extract
      - img_gen
      - search
      - judgment
      - doc_gen
      title: ModelCheckCategory
      description: 'The categories the model reference check covers, in the order every list it returns follows.


        These are the MTHDS Protocol''s model categories, in the protocol''s order, then `doc_gen`, the family

        of `PipeDocGen`. The protocol defines no category for `doc_gen`, so the model listing leaves it out,

        but a method names a `doc_gen` model in its `model` field like any other, so the check covers it.'
    ModelInfo:
      properties:
        name:
          type: string
          title: Name
        type:
          anyOf:
          - $ref: '#/components/schemas/ModelCategory'
          - type: string
          - type: 'null'
          title: Type
      additionalProperties: true
      type: object
      required:
      - name
      title: ModelInfo
      description: 'One entry of the model deck (`ModelDeck.models[]`) — base fields + extensions.


        `type` is an open read of the entry''s category, under the protocol''s reader

        rule: "A client reading a model list MUST NOT fail it because an entry carries

        a category it does not recognize; it keeps that entry with its raw value or

        leaves it out." This package keeps it: a category it knows reads as its

        `ModelCategory` member, and one it does not — a category a runner of a later

        protocol minor reports — keeps its raw string, so a consumer handles the

        `str` case rather than the whole deck failing. The union is validated left to

        right on purpose: pydantic''s default smart mode would keep every string,

        known or not, as a plain `str`.'
    ModelReference:
      type: string
    ModelReferenceKind:
      type: string
      enum:
      - preset
      - alias
      - waterfall
      - handle
      title: ModelReferenceKind
      description: The kind of model reference.
    ModelReferenceResolution:
      type: string
      enum:
      - resolved
      - not_found
      title: ModelReferenceResolution
      description: Whether a reference resolves in a category in scope. Both values are definitive.
    ModelReferenceVerdict:
      properties:
        reference:
          type: string
          title: Reference
          description: The caller's reference, trimmed.
        kind:
          $ref: '#/components/schemas/ModelReferenceKind'
          description: What the reference names, from its parsing.
        name:
          type: string
          title: Name
          description: The reference without its sigil or namespace.
        category:
          anyOf:
          - $ref: '#/components/schemas/ModelCheckCategory'
          - type: 'null'
          description: The `type` asked, or null when none was.
        resolution:
          $ref: '#/components/schemas/ModelReferenceResolution'
          description: Whether the reference resolves in a category in scope.
        matches:
          items:
            anyOf:
            - $ref: '#/components/schemas/PresetMatch'
            - $ref: '#/components/schemas/AliasMatch'
            - $ref: '#/components/schemas/WaterfallMatch'
            - $ref: '#/components/schemas/HandleMatch'
          type: array
          title: Matches
          description: One entry per category in scope where the reference resolves, in the order of the categories the check
            covers.
        suggestions:
          items:
            type: string
          type: array
          title: Suggestions
          description: On `not_found`, the nearest names the caller may have meant; empty when it is `resolved`.
        other_kinds:
          items:
            type: string
          type: array
          title: Other Kinds
          description: On `not_found`, the same name under another kind, in the categories in scope; empty when it is `resolved`.
        other_categories:
          items:
            $ref: '#/components/schemas/ModelCheckCategory'
          type: array
          title: Other Categories
          description: On `not_found` with a `type`, the categories outside it where the same reference resolves; empty otherwise.
      additionalProperties: false
      type: object
      required:
      - reference
      - kind
      - name
      - category
      - resolution
      - matches
      - suggestions
      - other_kinds
      - other_categories
      title: ModelReferenceVerdict
      description: The verdict of the model reference check, discriminated on `resolution`.
    ModelUsageSpec:
      properties:
        inference_model_name:
          type: string
          title: Inference Model Name
        inference_model_id:
          type: string
          title: Inference Model Id
        model_type:
          type: string
          title: Model Type
        inference_calls:
          type: integer
          title: Inference Calls
          default: 0
        rated_inference_calls:
          type: integer
          title: Rated Inference Calls
          default: 0
        cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Cost
      additionalProperties: false
      type: object
      required:
      - inference_model_name
      - inference_model_id
      - model_type
      title: ModelUsageSpec
      description: 'What one inference model actually did for a node.


        This is the only place the graph records the model that **ran**. Everything else

        in a GraphSpec that names a model records what was *asked for*:

        ``execution_data.resolved_model`` holds the handle the pipe resolved to — which may

        still be an alias (``@default-premium``) — and the pipe blueprint holds the authored

        choice (``$writing-factual``). Those are three rungs of one ladder, and only this

        rung is the outcome: it survives alias resolution, deck defaults, and any fallback

        or retry that landed somewhere other than what was requested.


        A node genuinely uses more than one model in ordinary cases — a ``PipeLLM``''s text

        pass and its object-structuring pass resolve separately — so a node''s models are a

        LIST. Collapsing them to "the model" would be wrong in exactly the way a single

        ``cost`` for mixed rated/unrated calls is wrong.


        ``cost`` follows ``NodeUsageSpec`` invariant 2: ``None`` iff no call to this model

        carried a rate table.'
    MoveKeyOp:
      properties:
        table_path:
          items:
            type: string
          type: array
          title: Table Path
        kind:
          type: string
          const: move_key
          title: Kind
          default: move_key
        key:
          type: string
          title: Key
        new_table_path:
          items:
            type: string
          type: array
          title: New Table Path
        new_key:
          type: string
          title: New Key
      additionalProperties: false
      type: object
      required:
      - table_path
      - key
      - new_table_path
      - new_key
      title: MoveKeyOp
      description: 'Relocate ``key`` from the addressed table into ``new_table_path``, under ``new_key``.


        The moved key may be table-valued, in which case the whole subtree travels. Destination

        parents that do not exist are created, as block tables, as part of the operation. Position

        is preserved within a parent and never across parents — see ``docs/migration-ledger.md``

        for the placement rule and for what happens to a moved table''s introducing comment.'
    NextStep:
      properties:
        kind:
          anyOf:
          - $ref: '#/components/schemas/StepKind'
          - type: string
          title: Kind
        detail:
          type: string
          title: Detail
      additionalProperties: true
      type: object
      required:
      - kind
      - detail
      title: NextStep
      description: 'What the reader should do next: a kind from the protocol''s closed list, and the step in one sentence.'
    NodeIOSpec:
      properties:
        inputs:
          items:
            $ref: '#/components/schemas/IOSpec'
          type: array
          title: Inputs
        outputs:
          items:
            $ref: '#/components/schemas/IOSpec'
          type: array
          title: Outputs
      additionalProperties: false
      type: object
      title: NodeIOSpec
      description: Input/output specification for a node.
    NodeKind:
      type: string
      enum:
      - pipe_call
      - controller
      - operator
      - input
      - output
      - artifact
      - error
      - binding
      title: NodeKind
      description: Types of nodes in the execution graph.
    NodeSpec:
      properties:
        id:
          type: string
          title: Id
        path:
          anyOf:
          - type: string
          - type: 'null'
          title: Path
        kind:
          $ref: '#/components/schemas/NodeKind'
        pipe_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Pipe Code
        pipe_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Pipe Type
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        domain_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain Code
        status:
          $ref: '#/components/schemas/NodeStatus'
        skip_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Skip Reason
        timing:
          anyOf:
          - $ref: '#/components/schemas/TimingSpec'
          - type: 'null'
        io:
          $ref: '#/components/schemas/NodeIOSpec'
        error:
          anyOf:
          - $ref: '#/components/schemas/PipelexProblem'
          - type: 'null'
        error_stack:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Stack
        tags:
          additionalProperties:
            type: string
          type: object
          title: Tags
        metrics:
          additionalProperties:
            type: number
          type: object
          title: Metrics
        usage:
          anyOf:
          - $ref: '#/components/schemas/NodeUsageSpec'
          - type: 'null'
        execution_data:
          additionalProperties: true
          type: object
          title: Execution Data
      additionalProperties: false
      type: object
      required:
      - id
      - kind
      - status
      title: NodeSpec
      description: 'Specification for a node in the execution graph.


        Each node represents a pipe invocation during execution.'
    NodeStatus:
      type: string
      enum:
      - scheduled
      - running
      - succeeded
      - failed
      - skipped
      - canceled
      title: NodeStatus
      description: Execution status of a node.
    NodeUsageSpec:
      properties:
        inference_calls:
          type: integer
          title: Inference Calls
          default: 0
        rated_inference_calls:
          type: integer
          title: Rated Inference Calls
          default: 0
        nb_tokens_by_category:
          additionalProperties:
            type: integer
          type: object
          title: Nb Tokens By Category
        total_tokens:
          type: integer
          title: Total Tokens
          default: 0
        cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Cost
        cost_input:
          anyOf:
          - type: number
          - type: 'null'
          title: Cost Input
        cost_output:
          anyOf:
          - type: number
          - type: 'null'
          title: Cost Output
        by_model:
          items:
            $ref: '#/components/schemas/ModelUsageSpec'
          type: array
          title: By Model
        subtree_inference_calls:
          type: integer
          title: Subtree Inference Calls
          default: 0
        subtree_rated_inference_calls:
          type: integer
          title: Subtree Rated Inference Calls
          default: 0
        subtree_nb_tokens_by_category:
          additionalProperties:
            type: integer
          type: object
          title: Subtree Nb Tokens By Category
        subtree_total_tokens:
          type: integer
          title: Subtree Total Tokens
          default: 0
        subtree_cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Subtree Cost
        subtree_cost_input:
          anyOf:
          - type: number
          - type: 'null'
          title: Subtree Cost Input
        subtree_cost_output:
          anyOf:
          - type: number
          - type: 'null'
          title: Subtree Cost Output
        subtree_by_model:
          items:
            $ref: '#/components/schemas/ModelUsageSpec'
          type: array
          title: Subtree By Model
      additionalProperties: false
      type: object
      title: NodeUsageSpec
      description: "Inference usage attributed to one graph node.\n\nField names mirror the already-shipped client-facing\
        \ ``TokensUsageRecord``\n(``reporting/usage_records.py``) so the graph does not introduce a fifth vocabulary\nfor\
        \ numbers this codebase already names four ways (``TokenCategory``,\n``LLMTokenCostReportField``, ``GenAISpanAttr``,\
        \ ``PostHogAttr``).\n\nINVARIANTS — the UI and every other consumer branch on these, not on guesses about\nwhy a number\
        \ is missing:\n\n  1. ``NodeSpec.usage is None`` <=> no usage was reported anywhere in the run —\n     either usage\
        \ collection was off, or the run made zero inference calls. As soon\n     as ONE usage event was seen, EVERY node\
        \ carries a spec, zeroed where nothing\n     ran. A controller, a lifted pipe, and a PipeFunc all get ``inference_calls=0``,\n\
        \     never ``usage=None``. So the field is all-or-nothing across a graph: it never\n     distinguishes \"this node\
        \ was not measured\" from \"that node was\".\n\n  2. ``cost is None`` <=> ``rated_inference_calls == 0``. Nothing\
        \ else. \"Made no\n     call\" and \"made only unrated calls\" both land here and are told apart by\n     ``inference_calls``.\n\
        \n  3. ``inference_calls > rated_inference_calls > 0`` => ``cost`` is a LOWER BOUND,\n     not a total: some of this\
        \ node's calls carried no rate table. The UI must mark\n     it (a leading \"≥\").\n\n  4. ``total_tokens`` is input_joined\
        \ + output — the same definition as\n     ``AggregatedCosts.total_nb_tokens``. It is NOT the sum of\n     ``nb_tokens_by_category``:\
        \ ``input_cached`` is a SUBSET of ``input``, not\n     additive (see ``usage_records.py``), so summing double-counts.\
        \ Never sum the\n     dict; read this field.\n\n  5. ``cost_input`` + ``cost_output`` == ``cost`` (to float precision).\
        \ They are\n     the same number split by direction, not extra charges, and they are None on\n     exactly the same\
        \ condition.\n\n  6. ``by_model`` names the models that actually RAN, and its ``inference_calls``\n     sum to this\
        \ spec's own. It is a list because one node routinely uses more\n     than one model (a PipeLLM's text pass and its\
        \ object pass resolve\n     separately). Ordered by descending calls, then by name, so a consumer can\n     take the\
        \ first entry as the dominant model without sorting.\n\nThe same invariants hold for the ``subtree_*`` half, which\
        \ covers this node plus\nevery descendant (rolled up in the assembler, once, so no consumer re-derives it\nand disagrees)."
    NumberField:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: number
          title: Kind
          default: number
        integer:
          type: boolean
          title: Integer
        minimum:
          anyOf:
          - type: integer
          - type: number
          - type: 'null'
          title: Minimum
        maximum:
          anyOf:
          - type: integer
          - type: number
          - type: 'null'
          title: Maximum
        exclusive_minimum:
          anyOf:
          - type: integer
          - type: number
          - type: 'null'
          title: Exclusive Minimum
        exclusive_maximum:
          anyOf:
          - type: integer
          - type: number
          - type: 'null'
          title: Exclusive Maximum
        name:
          type: string
          title: Name
      additionalProperties: false
      type: object
      required:
      - required
      - integer
      - name
      title: NumberField
      description: '`number` at a named position.'
    NumberItem:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: number
          title: Kind
          default: number
        integer:
          type: boolean
          title: Integer
        minimum:
          anyOf:
          - type: integer
          - type: number
          - type: 'null'
          title: Minimum
        maximum:
          anyOf:
          - type: integer
          - type: number
          - type: 'null'
          title: Maximum
        exclusive_minimum:
          anyOf:
          - type: integer
          - type: number
          - type: 'null'
          title: Exclusive Minimum
        exclusive_maximum:
          anyOf:
          - type: integer
          - type: number
          - type: 'null'
          title: Exclusive Maximum
      additionalProperties: false
      type: object
      required:
      - required
      - integer
      title: NumberItem
      description: '`number` — an integer or a floating-point number, with its optional bounds.'
    ObjectField:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: object
          title: Kind
          default: object
        fields:
          items:
            oneOf:
            - $ref: '#/components/schemas/TextField'
            - $ref: '#/components/schemas/ProseField'
            - $ref: '#/components/schemas/DateField'
            - $ref: '#/components/schemas/NumberField'
            - $ref: '#/components/schemas/BooleanField'
            - $ref: '#/components/schemas/EnumField'
            - $ref: '#/components/schemas/DocumentField'
            - $ref: '#/components/schemas/ImageField'
            - $ref: '#/components/schemas/ObjectField'
            - $ref: '#/components/schemas/ListField'
            - $ref: '#/components/schemas/UnknownField'
            discriminator:
              propertyName: kind
              mapping:
                boolean: '#/components/schemas/BooleanField'
                date: '#/components/schemas/DateField'
                document: '#/components/schemas/DocumentField'
                enum: '#/components/schemas/EnumField'
                image: '#/components/schemas/ImageField'
                list: '#/components/schemas/ListField'
                number: '#/components/schemas/NumberField'
                object: '#/components/schemas/ObjectField'
                prose: '#/components/schemas/ProseField'
                text: '#/components/schemas/TextField'
                unknown: '#/components/schemas/UnknownField'
          type: array
          title: Fields
        name:
          type: string
          title: Name
      additionalProperties: false
      type: object
      required:
      - required
      - fields
      - name
      title: ObjectField
      description: '`object` at a named position, recursing through `fields` — themselves named.'
    ObjectItem:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: object
          title: Kind
          default: object
        fields:
          items:
            oneOf:
            - $ref: '#/components/schemas/TextField'
            - $ref: '#/components/schemas/ProseField'
            - $ref: '#/components/schemas/DateField'
            - $ref: '#/components/schemas/NumberField'
            - $ref: '#/components/schemas/BooleanField'
            - $ref: '#/components/schemas/EnumField'
            - $ref: '#/components/schemas/DocumentField'
            - $ref: '#/components/schemas/ImageField'
            - $ref: '#/components/schemas/ObjectField'
            - $ref: '#/components/schemas/ListField'
            - $ref: '#/components/schemas/UnknownField'
            discriminator:
              propertyName: kind
              mapping:
                boolean: '#/components/schemas/BooleanField'
                date: '#/components/schemas/DateField'
                document: '#/components/schemas/DocumentField'
                enum: '#/components/schemas/EnumField'
                image: '#/components/schemas/ImageField'
                list: '#/components/schemas/ListField'
                number: '#/components/schemas/NumberField'
                object: '#/components/schemas/ObjectField'
                prose: '#/components/schemas/ProseField'
                text: '#/components/schemas/TextField'
                unknown: '#/components/schemas/UnknownField'
          type: array
          title: Fields
      additionalProperties: false
      type: object
      required:
      - required
      - fields
      title: ObjectItem
      description: '`object` — a structured concept, recursing through its resolved payload fields.'
    PipeBatchBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        pipe_category:
          type: string
          const: PipeController
          title: Pipe Category
          default: PipeController
        type:
          type: string
          const: PipeBatch
          title: Type
          default: PipeBatch
        description:
          type: string
          title: Description
        inputs:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/InputSlotBlueprint'
            type: object
          - type: 'null'
          title: Inputs
        output:
          type: string
          title: Output
        branch_pipe_code:
          type: string
          title: Branch Pipe Code
        input_list_name:
          type: string
          title: Input List Name
        input_item_name:
          type: string
          title: Input Item Name
      additionalProperties: false
      type: object
      required:
      - description
      - output
      - branch_pipe_code
      - input_list_name
      - input_item_name
      title: PipeBatchBlueprint
    PipeComposeBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        pipe_category:
          type: string
          const: PipeOperator
          title: Pipe Category
          default: PipeOperator
        type:
          type: string
          const: PipeCompose
          title: Type
          default: PipeCompose
        description:
          type: string
          title: Description
        inputs:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/InputSlotBlueprint'
            type: object
          - type: 'null'
          title: Inputs
        output:
          type: string
          title: Output
        template:
          anyOf:
          - type: string
          - $ref: '#/components/schemas/TemplateBlueprint'
          - type: 'null'
          title: Template
        construct:
          anyOf:
          - $ref: '#/components/schemas/ConstructBlueprint'
          - type: 'null'
      additionalProperties: false
      type: object
      required:
      - description
      - output
      title: PipeComposeBlueprint
    PipeConditionBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        pipe_category:
          type: string
          const: PipeController
          title: Pipe Category
          default: PipeController
        type:
          type: string
          const: PipeCondition
          title: Type
          default: PipeCondition
        description:
          type: string
          title: Description
        inputs:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/InputSlotBlueprint'
            type: object
          - type: 'null'
          title: Inputs
        output:
          type: string
          title: Output
        expression_template:
          anyOf:
          - type: string
          - type: 'null'
          title: Expression Template
        expression:
          anyOf:
          - type: string
          - type: 'null'
          title: Expression
        outcomes:
          additionalProperties:
            type: string
          type: object
          title: Outcomes
          x-schema-required: true
        default_outcome:
          anyOf:
          - type: string
          - $ref: '#/components/schemas/SpecialOutcome'
          title: Default Outcome
        add_alias_from_expression_to:
          anyOf:
          - type: string
          - type: 'null'
          title: Add Alias From Expression To
      additionalProperties: false
      type: object
      required:
      - description
      - output
      - default_outcome
      title: PipeConditionBlueprint
    PipeDocGenBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        pipe_category:
          type: string
          const: PipeOperator
          title: Pipe Category
          default: PipeOperator
        type:
          type: string
          const: PipeDocGen
          title: Type
          default: PipeDocGen
        description:
          type: string
          title: Description
        inputs:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/InputSlotBlueprint'
            type: object
          - type: 'null'
          title: Inputs
        output:
          type: string
          title: Output
        format:
          $ref: '#/components/schemas/DocGenFormat'
        model:
          anyOf:
          - $ref: '#/components/schemas/DocGenSetting'
          - type: string
          - $ref: '#/components/schemas/ModelReference'
          - type: 'null'
          title: Model
        template:
          anyOf:
          - type: string
          - type: 'null'
          title: Template
        template_file:
          anyOf:
          - type: string
          - type: 'null'
          title: Template File
        filename:
          anyOf:
          - type: string
          - type: 'null'
          title: Filename
      additionalProperties: false
      type: object
      required:
      - description
      - output
      - format
      title: PipeDocGenBlueprint
      description: 'Generate a document file from a method''s structured result: a PDF, an Excel workbook, a Word document
        or a PowerPoint deck.


        It calls no AI model: it lays out or fills what its inputs already hold. With no template, the pipe lays its inputs

        out by itself (the auto-layout), for every format but `pptx`. `template` is an inline HTML and Jinja2 template, for

        `pdf` only; `template_file` is a path relative to the bundle''s file, inside its bundle and written with forward

        slashes: an `.html` for `pdf`, an `.xlsx` for `xlsx`, a

        `.docx` for `docx` and a `.pptx` for `pptx`, which `pptx` requires. `filename` is a Jinja expression over the

        inputs; the suffix is added. The output must be a single `Document`, or a concept refining it. `model` names the

        document engine that prints it, a model of the `doc_gen` family such as `reportlab-pdf` or, with the Pipelex

        document generation plugin, `pipelex-pdf`; without it, the model deck''s default for the format and source prints

        it. Which engines a runtime has depends on its plugins: open Pipelex prints a `pdf` without a template on

        `reportlab-pdf`, and a runtime without the engine a step needs refuses the method when it loads.'
    PipeExtractBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        pipe_category:
          type: string
          const: PipeOperator
          title: Pipe Category
          default: PipeOperator
        type:
          type: string
          const: PipeExtract
          title: Type
          default: PipeExtract
        description:
          type: string
          title: Description
        inputs:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/InputSlotBlueprint'
            type: object
          - type: 'null'
          title: Inputs
        output:
          type: string
          title: Output
        model:
          anyOf:
          - $ref: '#/components/schemas/ExtractSetting'
          - type: string
          - $ref: '#/components/schemas/ModelReference'
          - type: 'null'
          title: Model
        max_page_images:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Page Images
        page_image_captions:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Page Image Captions
        page_views:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Page Views
        page_views_dpi:
          anyOf:
          - type: integer
          - type: 'null'
          title: Page Views Dpi
        render_js:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Render Js
        include_raw_html:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Include Raw Html
      additionalProperties: false
      type: object
      required:
      - description
      - output
      title: PipeExtractBlueprint
    PipeFuncBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        pipe_category:
          type: string
          const: PipeOperator
          title: Pipe Category
          default: PipeOperator
        type:
          type: string
          const: PipeFunc
          title: Type
          default: PipeFunc
        description:
          type: string
          title: Description
        inputs:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/InputSlotBlueprint'
            type: object
          - type: 'null'
          title: Inputs
        output:
          type: string
          title: Output
        function_name:
          type: string
          pattern: ^[^.]+(\.[^.]+)+$
          title: Function Name
          description: 'The import path of the function to call, from the root of the method tree: the module''s dotted path,
            then the function''s name, such as ''funcs.totals.compute_totals'' for the function compute_totals of funcs/totals.py.
            The function must be a top-level def or async def of that module, decorated with @pipe_func().'
      additionalProperties: false
      type: object
      required:
      - description
      - output
      - function_name
      title: PipeFuncBlueprint
    PipeIOArtifacts:
      properties:
        pipe_io_contracts:
          additionalProperties:
            $ref: '#/components/schemas/PipeIOContract'
          type: object
          title: Pipe Io Contracts
        input_form:
          additionalProperties:
            $ref: '#/components/schemas/PipeInputFormDescriptor'
          type: object
          title: Input Form
        output_form:
          additionalProperties:
            $ref: '#/components/schemas/PipeOutputFormDescriptor'
          type: object
          title: Output Form
      additionalProperties: false
      type: object
      required:
      - pipe_io_contracts
      - input_form
      - output_form
      title: PipeIOArtifacts
      description: 'The validate report''s three I/O artifacts, under the report''s names and types.


        A grouping, not a new shape: each field is the standard''s artifact, keyed by `pipe_ref`.'
    PipeIOContract:
      properties:
        inputs:
          additionalProperties:
            $ref: '#/components/schemas/PipeInputContract'
          type: object
          title: Inputs
        output:
          $ref: '#/components/schemas/PipeOutputContract'
      additionalProperties: false
      type: object
      required:
      - inputs
      - output
      title: PipeIOContract
      description: 'The contract of one pipe — one `pipe_io_contracts` entry, with both members required.


        `inputs` is a map from authored input name to input contract, and it deliberately contracts no

        order: an ordered view of a pipe''s inputs is the input-form descriptor''s job, which keeps this

        artifact byte-stable whatever a renderer needs. A pipe with no declared inputs carries

        `inputs: {}` — a stated fact, never an omitted member. Closed shape (`extra="forbid"`).'
    PipeIORequest:
      properties:
        files:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/Base64FileEntry'
              - $ref: '#/components/schemas/HashFileEntry'
            type: object
          - type: 'null'
          title: Files
          description: 'The method as a map of file entries, the MTHDS standard''s form of a method tree that travels: each
            key is a tree path (relative, forward slashes, in Unicode NFC, no `.` or `..` segment, no segment starting with
            a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or `{"sha256": ..., "size":
            ...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing` then `PUT /v1/blobs/{sha256}`).
            The map is read from the request''s JSON text: a key given twice, a key the membership rule keeps out of every
            tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid` whose `reason` is the refusal''s
            code and whose `path` names the first path, a key leaving the tree is a 422 `security.input_path_refused`, a malformed
            entry is a 422 `request.invalid`, and hash entries the runner does not hold are one 422 `request.blobs_missing`
            whose `missing_blobs` parameter lists every such hash. Its `.mthds` files are the method''s bundles and every
            other file is one a step may read, such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`,
            the run starts at the `main_pipe` of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its
            bundles declare. Custom `.py` is only honored on a sandbox-hosted deployment. Exactly one of `files` / `method_ref`.'
        dependencies:
          anyOf:
          - additionalProperties:
              additionalProperties:
                anyOf:
                - type: string
                - $ref: '#/components/schemas/Base64FileEntry'
                - $ref: '#/components/schemas/HashFileEntry'
              type: object
            type: object
          - type: 'null'
          title: Dependencies
          description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the method packages the method calls by address
            that this runner cannot fetch, such as one an author has not published, as `{"<address>": <map of file entries>}`:
            each value is a tree of its own, read as `files` is, with a `METHODS.toml` at its root declaring the address it
            is keyed by. They are searched before the runner''s installed copies, for this request alone. Accompanies `files`.'
        method_ref:
          anyOf:
          - type: string
            maxLength: 512
            minLength: 1
          - type: 'null'
          title: Method Ref
          description: PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — a published method by reference, instead of
            its tree. Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is fetched and read as a `files` tree
            is, through the same path as a `method_ref` run; the registry form stays reserved (a 422 `request.unsupported`
            until a method registry exists). Exactly one of `files` / `method_ref`.
        resources:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Resources
          description: 'The files submitted with the bundle that its steps read, such as a PipeDocGen step''s `template_file`
            (an `.xlsx`, `.docx`, `.pptx` or `.html` template): a JSON object mapping each file''s bundle-relative path, exactly
            as the step names it, to the file''s bytes in standard base64. A path must be relative and written with forward
            slashes, with no `..` segment, backslash or colon. Beside inline `mthds_contents`, every bundle of the request
            is read as sitting in one directory, and every file must be named by a step, or the request is refused with a
            422 `BundleResourceNotNamedError`. Beside a method tree, `files` or `bundle_b64`, each file joins the tree at
            its path from the tree''s root, where a file the tree already holds must have the same bytes. By default at most
            32 files, 5120 KiB each and 10240 KiB in all, decoded; a deployment sets its own with `MAX_RESOURCES_PER_REQUEST`,
            `MAX_RESOURCE_FILE_KIB` and `MAX_RESOURCES_TOTAL_KIB`. The files make one method tree with the bundles, which
            the run names by its digest: no file''s bytes travel with the run, each being read where a step uses it. Being
            retired, and refused by a later release: a file the steps read travels inside the method''s tree, in `files`,
            at its path beside the bundle that names it.'
        read_scope:
          anyOf:
          - type: string
          - type: 'null'
          title: Read Scope
          description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the scope the request reads the method under,
            as a run''s `read_scope`: a multi-tenant host sends the one of the organization it serves. A hash entry of `files`
            resolves in that scope''s blob store, and the tree the request read is recorded there, so a later request can
            send it by hash. Omit it and a hash entry resolves in the caller''s own id''s store, and nothing is recorded.'
        pipe_ref:
          anyOf:
          - type: string
            maxLength: 256
            minLength: 1
          - type: 'null'
          title: Pipe Ref
          description: Qualified pipe ref (`domain.pipe_code`) to select. Optional — defaults to the `main_pipe` of the `METHODS.toml`
            at the method tree's root, else to the closure's declared `main_pipe`; a closure declaring none, or several, with
            no manifest `main_pipe` to settle it, requires it unless `all_pipes` is set.
        all_pipes:
          type: boolean
          title: All Pipes
          description: 'Describe every pipe the closure loads instead of the selected one. The artifact maps are then keyed
            by every pipe, and the route never refuses for want of an entry pipe: `pipe_ref` on the valid arm is the requested
            ref, else the method''s own entry pipe, else `null`.'
          default: false
        include_files:
          type: boolean
          title: Include Files
          description: 'Echo the method''s `.mthds` bundles on the valid arm, as a map of file entries in the request''s own
            `files` shape, each bundle''s tree path to its text: the bundles of the tree sent in `files`, whatever entry carried
            them, or those of the fetched package''s tree for a `method_ref`. Its other files and its dependencies are not
            echoed. Absent from the response unless true.'
          default: false
      type: object
      title: PipeIORequest
      description: 'The pipe I/O request: the crate routes'' method selector and pipe selector, plus the whole-method and
        echo opt-ins.


        The hosted catalog selector is replaced by `files` before the request reaches the runner, so this

        request has no field for it. It takes no `views` either, since the valid arm always carries all

        three artifacts.'
    PipeIOValidReport:
      properties:
        is_valid:
          type: boolean
          const: true
          title: Is Valid
          default: true
        pipe_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Pipe Ref
          description: The qualified `domain.pipe_code` the selection resolved, read back off the resolved pipe and never
            echoed from the request. `null` only under `all_pipes` when no pipe was requested and the method declares no single
            entry pipe.
        pipe_io_contracts:
          additionalProperties:
            $ref: '#/components/schemas/PipeIOContract'
          type: object
          title: Pipe Io Contracts
          description: The standard's pipe I/O contracts, keyed by qualified `pipe_ref`.
        input_form:
          additionalProperties:
            $ref: '#/components/schemas/PipeInputFormDescriptor'
          type: object
          title: Input Form
          description: The standard's input-form descriptors, keyed by qualified `pipe_ref`.
        output_form:
          additionalProperties:
            $ref: '#/components/schemas/PipeOutputFormDescriptor'
          type: object
          title: Output Form
          description: The standard's output-form descriptors, keyed by qualified `pipe_ref`.
        default_pipe_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Default Pipe Ref
          description: 'The method''s own entry pipe: the selection chain without the request''s `pipe_ref` — the fetched
            package manifest''s `main_pipe`, else the closure''s single `main_pipe` declaration. A stated `null` when that
            chain finds none or several. Not `/validate`''s field of the same name, which is the run default.'
        pending_signatures:
          items:
            type: string
          type: array
          title: Pending Signatures
          description: The qualified refs of every pipe of the closure still declared as a signature, exactly as on `/validate`.
        is_runnable:
          type: boolean
          title: Is Runnable
          description: '`not pending_signatures`, exactly as on `/validate`. No dry run backs it.'
        files:
          additionalProperties:
            type: string
          type: object
          title: Files
          description: 'The method''s `.mthds` bundles, each tree path to its text, a map of file entries as the request''s
            `files` is. Present only with `include_files: true`.'
      type: object
      required:
      - pipe_ref
      - pipe_io_contracts
      - input_form
      - output_form
      - default_pipe_ref
      - pending_signatures
      - is_runnable
      title: PipeIOValidReport
      description: 'The 200 **valid** arm: the method''s three I/O artifacts, with the selection and the runnability facts
        beside them.


        The three maps share one key set: the resolved `pipe_ref` alone by default, every pipe the

        closure loads under `all_pipes`. Each map is the standard''s artifact under its neutral name, and

        for a closure `/validate` also accepts it equals `/validate`''s same-named field restricted to the

        same keys — both routes call the one builder, and both dump without dropping null members.

        `is_valid: true` means what it means on `/resolve`: the closure parsed, loaded and passed static

        validation. No dry run ran; that verdict stays `/validate`''s.'
    PipeImgGenBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        pipe_category:
          type: string
          const: PipeOperator
          title: Pipe Category
          default: PipeOperator
        type:
          type: string
          const: PipeImgGen
          title: Type
          default: PipeImgGen
        description:
          type: string
          title: Description
        inputs:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/InputSlotBlueprint'
            type: object
          - type: 'null'
          title: Inputs
        output:
          type: string
          title: Output
        prompt:
          type: string
          title: Prompt
        negative_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Negative Prompt
        model:
          anyOf:
          - $ref: '#/components/schemas/ImgGenSetting'
          - type: string
          - $ref: '#/components/schemas/ModelReference'
          - type: 'null'
          title: Model
        aspect_ratio:
          anyOf:
          - $ref: '#/components/schemas/AspectRatio'
          - type: 'null'
        size:
          anyOf:
          - $ref: '#/components/schemas/SizeTier'
          - $ref: '#/components/schemas/ImageSize'
          - type: 'null'
          title: Size
        is_raw:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Raw
        seed:
          anyOf:
          - type: integer
          - type: string
            const: auto
          - type: 'null'
          title: Seed
        background:
          anyOf:
          - $ref: '#/components/schemas/Background'
          - type: 'null'
        output_format:
          anyOf:
          - $ref: '#/components/schemas/ImageFormat'
          - type: 'null'
      additionalProperties: false
      type: object
      required:
      - description
      - output
      - prompt
      title: PipeImgGenBlueprint
    PipeInputContract:
      properties:
        concept_ref:
          type: string
          title: Concept Ref
        presence:
          $ref: '#/components/schemas/PresenceMarker'
        multiplicity:
          $ref: '#/components/schemas/IOMultiplicity'
        item_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Item Count
        json_schema:
          additionalProperties: true
          type: object
          title: Json Schema
      additionalProperties: false
      type: object
      required:
      - concept_ref
      - presence
      - multiplicity
      - item_count
      - json_schema
      title: PipeInputContract
      description: 'One declared input slot: the concept it expects, its presence, its plurality and the JSON Schema of its
        content.


        Keyed in `PipeIOContract.inputs` by the authored input name, a plain name.

        Every member is required: `item_count` is always on the wire, `null` off the fixed arm.

        Closed shape (`extra="forbid"`): an unknown member is version drift, rejected at the parse.'
    PipeInputFormDescriptor:
      properties:
        fields:
          items:
            oneOf:
            - $ref: '#/components/schemas/TextField'
            - $ref: '#/components/schemas/ProseField'
            - $ref: '#/components/schemas/DateField'
            - $ref: '#/components/schemas/NumberField'
            - $ref: '#/components/schemas/BooleanField'
            - $ref: '#/components/schemas/EnumField'
            - $ref: '#/components/schemas/DocumentField'
            - $ref: '#/components/schemas/ImageField'
            - $ref: '#/components/schemas/ObjectField'
            - $ref: '#/components/schemas/ListField'
            - $ref: '#/components/schemas/UnknownField'
            discriminator:
              propertyName: kind
              mapping:
                boolean: '#/components/schemas/BooleanField'
                date: '#/components/schemas/DateField'
                document: '#/components/schemas/DocumentField'
                enum: '#/components/schemas/EnumField'
                image: '#/components/schemas/ImageField'
                list: '#/components/schemas/ListField'
                number: '#/components/schemas/NumberField'
                object: '#/components/schemas/ObjectField'
                prose: '#/components/schemas/ProseField'
                text: '#/components/schemas/TextField'
                unknown: '#/components/schemas/UnknownField'
          type: array
          title: Fields
      additionalProperties: false
      type: object
      required:
      - fields
      title: PipeInputFormDescriptor
      description: 'The input form of one pipe — one `input_form` entry.


        `fields` holds one descriptor per declared input slot, in authored input order: the order is why

        the descriptor is a sibling artifact of the contract rather than a decoration inside it. A pipe

        with no inputs maps to `{"fields": []}` — an empty form is a valid form, not an omitted entry.

        Closed shape (`extra="forbid"`).'
    PipeJudgeBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        pipe_category:
          type: string
          const: PipeOperator
          title: Pipe Category
          default: PipeOperator
        type:
          type: string
          const: PipeJudge
          title: Type
          default: PipeJudge
        description:
          type: string
          title: Description
        inputs:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/InputSlotBlueprint'
            type: object
          - type: 'null'
          title: Inputs
        output:
          type: string
          title: Output
        prompt:
          type: string
          title: Prompt
        question:
          anyOf:
          - type: string
          - type: 'null'
          title: Question
        questions:
          anyOf:
          - additionalProperties:
              $ref: '#/components/schemas/JudgeQuestionBlueprint'
            type: object
          - type: 'null'
          title: Questions
        model:
          anyOf:
          - $ref: '#/components/schemas/JudgmentSetting'
          - type: string
          - $ref: '#/components/schemas/ModelReference'
          - type: 'null'
          title: Model
        options:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Options
        levels:
          anyOf:
          - items:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/JudgeRatingLevel'
            type: array
          - type: 'null'
          title: Levels
        criteria:
          anyOf:
          - $ref: '#/components/schemas/JudgeYesNoCriteria'
          - type: 'null'
        threshold:
          anyOf:
          - type: number
          - type: 'null'
          title: Threshold
      additionalProperties: false
      type: object
      required:
      - description
      - output
      - prompt
      title: PipeJudgeBlueprint
      description: 'Asks a judging model closed questions about the evidence its prompt presents: yes/no, a choice, or a rating.


        `prompt` is the evidence template, rendered and checked as a PipeLLM''s prompt is, the images and

        documents it reads presented to the model as files. The single form asks one `question`, a plain

        text template, and produces its verdict native; the multi form asks the several `questions` of a

        table keyed by name over the same evidence in one request, and fills a structure whose fields are

        those names with one verdict each. A question''s kind is decided by which of `options` and `levels`

        it declares, never by a field of its own, and the single form declares them on the pipe. Every

        declared input is read by the prompt or by a question.'
    PipeLLMBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        pipe_category:
          type: string
          const: PipeOperator
          title: Pipe Category
          default: PipeOperator
        type:
          type: string
          const: PipeLLM
          title: Type
          default: PipeLLM
        description:
          type: string
          title: Description
        inputs:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/InputSlotBlueprint'
            type: object
          - type: 'null'
          title: Inputs
        output:
          type: string
          title: Output
        model:
          anyOf:
          - $ref: '#/components/schemas/LLMSetting'
          - type: string
          - $ref: '#/components/schemas/ModelReference'
          - type: 'null'
          title: Model
        model_to_structure:
          anyOf:
          - $ref: '#/components/schemas/LLMSetting'
          - type: string
          - $ref: '#/components/schemas/ModelReference'
          - type: 'null'
          title: Model To Structure
        system_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: System Prompt
        prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Prompt
        structuring_method:
          anyOf:
          - $ref: '#/components/schemas/StructuringMethod'
          - type: 'null'
        templating_style:
          anyOf:
          - $ref: '#/components/schemas/TagStyle'
          - $ref: '#/components/schemas/TemplatingStyle'
          - type: 'null'
          title: Templating Style
      additionalProperties: false
      type: object
      required:
      - description
      - output
      title: PipeLLMBlueprint
    PipeOutputContract:
      properties:
        concept_ref:
          type: string
          title: Concept Ref
        multiplicity:
          $ref: '#/components/schemas/IOMultiplicity'
        item_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Item Count
        optional:
          type: boolean
          title: Optional
        json_schema:
          additionalProperties: true
          type: object
          title: Json Schema
      additionalProperties: false
      type: object
      required:
      - concept_ref
      - multiplicity
      - item_count
      - optional
      - json_schema
      title: PipeOutputContract
      description: 'What the pipe resolves to: the concept it produces, how many items that is, whether it may be absent,
        and the shape of its payload.


        Deliberately asymmetric with the input side in exactly one place, and no longer in a second.

        An output carries a two-valued `optional` where an input carries a three-valued `presence`,

        because `!` MUST NOT appear on an output — a force marker is a use-site assertion about an

        input, so a three-valued output slot would have an arm nothing can ever produce. That

        asymmetry is a language fact and it stays.


        The schema asymmetry was not. An output used to carry none, on the reasoning that "the payload

        a run produces is the run''s own result" — which answers *what did this run produce?*, correctly

        not a contract''s business, rather than the question a consumer actually asks: *what shape will

        it be?* That is declared in the `.mthds` source and knowable before any run happens, exactly as

        it is on the input side. Withholding it left every consumer inferring a payload''s shape by

        inspecting it, which is guessing at the standard rather than reading it.


        Closed shape (`extra="forbid"`).'
    PipeOutputFormDescriptor:
      properties:
        field:
          oneOf:
          - $ref: '#/components/schemas/TextField'
          - $ref: '#/components/schemas/ProseField'
          - $ref: '#/components/schemas/DateField'
          - $ref: '#/components/schemas/NumberField'
          - $ref: '#/components/schemas/BooleanField'
          - $ref: '#/components/schemas/EnumField'
          - $ref: '#/components/schemas/DocumentField'
          - $ref: '#/components/schemas/ImageField'
          - $ref: '#/components/schemas/ObjectField'
          - $ref: '#/components/schemas/ListField'
          - $ref: '#/components/schemas/UnknownField'
          title: Field
          discriminator:
            propertyName: kind
            mapping:
              boolean: '#/components/schemas/BooleanField'
              date: '#/components/schemas/DateField'
              document: '#/components/schemas/DocumentField'
              enum: '#/components/schemas/EnumField'
              image: '#/components/schemas/ImageField'
              list: '#/components/schemas/ListField'
              number: '#/components/schemas/NumberField'
              object: '#/components/schemas/ObjectField'
              prose: '#/components/schemas/ProseField'
              text: '#/components/schemas/TextField'
              unknown: '#/components/schemas/UnknownField'
      additionalProperties: false
      type: object
      required:
      - field
      title: PipeOutputFormDescriptor
      description: 'The output form of one pipe — one `output_form` entry, carrying the single output node.


        Closed shape (`extra="forbid"`). The node itself is an `InputFormField`, so it is parsed by

        the same discriminated union every input node is, and a consumer narrows it the same way.'
    PipeOutputWire:
      properties:
        working_memory:
          $ref: '#/components/schemas/WorkingMemory'
        pipeline_run_id:
          type: string
          title: Pipeline Run Id
          default: untitled
        working_memory_raw:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Working Memory Raw
        graph_spec:
          anyOf:
          - $ref: '#/components/schemas/GraphSpec'
          - type: 'null'
        graph_assembly_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Graph Assembly Error
        pipe_io_artifacts:
          anyOf:
          - $ref: '#/components/schemas/PipeIOArtifacts'
          - type: 'null'
        pipe_io_artifacts_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Pipe Io Artifacts Error
        tokens_usages:
          anyOf:
          - items:
              $ref: '#/components/schemas/TokensUsageRecord'
            type: array
          - type: 'null'
          title: Tokens Usages
        usage_assembly_error:
          anyOf:
          - type: string
          - type: 'null'
          title: Usage Assembly Error
      additionalProperties: false
      type: object
      title: PipeOutputWire
      description: '`PipeOutput` as it crosses the client boundary: usages trimmed to wire records.


        The route applies pipelex''s `apply_tokens_usage_wire_shape` to the response dump, so

        `tokens_usages` carries flat `TokensUsageRecord`s — not the internal usage models with

        their `job_metadata` plumbing and `unit_costs` rate table.'
    PipeParallelBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        pipe_category:
          type: string
          const: PipeController
          title: Pipe Category
          default: PipeController
        type:
          type: string
          const: PipeParallel
          title: Type
          default: PipeParallel
        description:
          type: string
          title: Description
        inputs:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/InputSlotBlueprint'
            type: object
          - type: 'null'
          title: Inputs
        output:
          type: string
          title: Output
        branches:
          items:
            $ref: '#/components/schemas/SubPipeBlueprint'
          type: array
          title: Branches
        add_each_output:
          type: boolean
          title: Add Each Output
          default: false
      additionalProperties: false
      type: object
      required:
      - description
      - output
      - branches
      title: PipeParallelBlueprint
    PipeSearchBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        pipe_category:
          type: string
          const: PipeOperator
          title: Pipe Category
          default: PipeOperator
        type:
          type: string
          const: PipeSearch
          title: Type
          default: PipeSearch
        description:
          type: string
          title: Description
        inputs:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/InputSlotBlueprint'
            type: object
          - type: 'null'
          title: Inputs
        output:
          type: string
          title: Output
        prompt:
          type: string
          title: Prompt
        model:
          anyOf:
          - $ref: '#/components/schemas/SearchSetting'
          - type: string
          - $ref: '#/components/schemas/ModelReference'
          - type: 'null'
          title: Model
        include_images:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Include Images
        max_results:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Results
        from_date:
          anyOf:
          - type: string
          - type: 'null'
          title: From Date
        to_date:
          anyOf:
          - type: string
          - type: 'null'
          title: To Date
        include_domains:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Include Domains
        exclude_domains:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Exclude Domains
      additionalProperties: false
      type: object
      required:
      - description
      - output
      - prompt
      title: PipeSearchBlueprint
    PipeSequenceBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        pipe_category:
          type: string
          const: PipeController
          title: Pipe Category
          default: PipeController
        type:
          type: string
          const: PipeSequence
          title: Type
          default: PipeSequence
        description:
          type: string
          title: Description
        inputs:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/InputSlotBlueprint'
            type: object
          - type: 'null'
          title: Inputs
        output:
          type: string
          title: Output
        steps:
          items:
            oneOf:
            - $ref: '#/components/schemas/SubPipeBlueprint'
            - $ref: '#/components/schemas/BindingStepBlueprint'
          type: array
          title: Steps
      additionalProperties: false
      type: object
      required:
      - description
      - output
      - steps
      title: PipeSequenceBlueprint
    PipeSignatureBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        description:
          type: string
          title: Description
        inputs:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/InputSlotBlueprint'
            type: object
          - type: 'null'
          title: Inputs
        output:
          type: string
          title: Output
        signature_for:
          anyOf:
          - $ref: '#/components/schemas/PipeType'
          - type: 'null'
          description: Intended downstream pipe type when this signature is implemented (optional hint for agents).
      additionalProperties: false
      type: object
      required:
      - description
      - output
      title: PipeSignatureBlueprint
      description: 'Contract-only pipe blueprint.


        A `PipeSignature` declares inputs and output but has no implementation. It exists so

        that an in-progress pipeline can be validated (dry-run mocks the declared output)

        before all its pipes are implemented.'
    PipeStructureBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        pipe_category:
          type: string
          const: PipeOperator
          title: Pipe Category
          default: PipeOperator
        type:
          type: string
          const: PipeStructure
          title: Type
          default: PipeStructure
        description:
          type: string
          title: Description
        inputs:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/InputSlotBlueprint'
            type: object
          - type: 'null'
          title: Inputs
        output:
          type: string
          title: Output
        model:
          anyOf:
          - $ref: '#/components/schemas/LLMSetting'
          - type: string
          - $ref: '#/components/schemas/ModelReference'
          - type: 'null'
          title: Model
      additionalProperties: false
      type: object
      required:
      - description
      - output
      title: PipeStructureBlueprint
    PipeType:
      type: string
      enum:
      - PipeFunc
      - PipeImgGen
      - PipeCompose
      - PipeLLM
      - PipeExtract
      - PipeSearch
      - PipeStructure
      - PipeDocGen
      - PipeJudge
      - PipeBatch
      - PipeCondition
      - PipeParallel
      - PipeSequence
      title: PipeType
    PipelexApiExecuteResponse:
      properties:
        pipeline_run_id:
          type: string
          title: Pipeline Run Id
        pipe_output:
          $ref: '#/components/schemas/PipeOutputWire'
        created_at:
          type: string
          title: Created At
        state:
          $ref: '#/components/schemas/RunState'
        finished_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Finished At
        main_stuff_name:
          type: string
          title: Main Stuff Name
        crate_fingerprint:
          anyOf:
          - type: string
          - type: 'null'
          title: Crate Fingerprint
          description: PIPELEX EXTENSION (not part of the MTHDS Protocol) — the fingerprint of the library crate the run's
            method was loaded into, the identity of its concepts and pipes, which changes with their meaning and not with
            their formatting or comments. Null when the run was built from no crate.
        method_provenance:
          anyOf:
          - $ref: '#/components/schemas/MethodProvenance'
          - type: 'null'
          description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — provenance of a `method_ref` run: the package''s
            resolved full address, the requested tag (null for a bare address), the commit SHA that was actually fetched,
            the digest of the method tree the run loaded, and the `display_name` the package''s manifest declares (null when
            it declares none). The SHA is what keeps the run explainable when a tag moves. Absent (or null) for runs from
            inline source or a bundle.'
      additionalProperties: true
      type: object
      required:
      - pipeline_run_id
      - pipe_output
      - created_at
      - state
      - main_stuff_name
      title: PipelexApiExecuteResponse
      description: 'Documented 200 body of `POST /execute` — the run result with the wire-shaped `pipe_output`.


        Used only to publish the OpenAPI response schema. `/execute` returns a `JSONResponse`

        built from the trimmed dump, so FastAPI never serializes through this model; declaring it

        is what keeps the published artifact honest about what the route actually emits

        (`method_provenance` is attached to the dump by the route for `method_ref` runs, and is

        absent otherwise).'
    PipelexApiStartResponse:
      properties:
        pipeline_run_id:
          type: string
          title: Pipeline Run Id
        created_at:
          type: string
          title: Created At
        state:
          $ref: '#/components/schemas/RunState'
        finished_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Finished At
        workflow_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Workflow Id
        crate_fingerprint:
          anyOf:
          - type: string
          - type: 'null'
          title: Crate Fingerprint
          description: PIPELEX EXTENSION (not part of the MTHDS Protocol) — the fingerprint of the library crate the run's
            method was loaded into, the identity of its concepts and pipes, which changes with their meaning and not with
            their formatting or comments. Null when the run was built from no crate.
        method_provenance:
          anyOf:
          - $ref: '#/components/schemas/MethodProvenance'
          - type: 'null'
          description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — provenance of a `method_ref` run: the package''s
            resolved full address, the requested tag (null for a bare address), the commit SHA that was actually fetched,
            the digest of the method tree the run loaded, and the `display_name` the package''s manifest declares (null when
            it declares none). The SHA is what keeps the run explainable when a tag moves. Absent (or null) for runs from
            inline source or a bundle.'
      additionalProperties: true
      type: object
      required:
      - pipeline_run_id
      - created_at
      - state
      title: PipelexApiStartResponse
      description: 'The 202 body of `POST /start` — the protocol''s start ack plus this server''s `method_provenance` extension.


        Unlike its `/execute` counterpart this model IS what the route returns (FastAPI serializes

        through it): the ack is small, so wrapping it costs nothing and keeps the artifact and the

        wire in lockstep. `method_provenance` is populated for `method_ref` runs and null otherwise.'
    PipelexBundleBlueprint:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        domain:
          type: string
          title: Domain
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        system_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: System Prompt
        main_pipe:
          anyOf:
          - type: string
          - type: 'null'
          title: Main Pipe
        concept:
          anyOf:
          - additionalProperties:
              anyOf:
              - $ref: '#/components/schemas/ConceptBlueprint'
              - type: string
            type: object
          - type: 'null'
          title: Concept
        pipe:
          anyOf:
          - additionalProperties:
              oneOf:
              - $ref: '#/components/schemas/PipeFuncBlueprint'
              - $ref: '#/components/schemas/PipeImgGenBlueprint'
              - $ref: '#/components/schemas/PipeComposeBlueprint'
              - $ref: '#/components/schemas/PipeLLMBlueprint'
              - $ref: '#/components/schemas/PipeExtractBlueprint'
              - $ref: '#/components/schemas/PipeSearchBlueprint'
              - $ref: '#/components/schemas/PipeJudgeBlueprint'
              - $ref: '#/components/schemas/PipeStructureBlueprint'
              - $ref: '#/components/schemas/PipeDocGenBlueprint'
              - $ref: '#/components/schemas/PipeBatchBlueprint'
              - $ref: '#/components/schemas/PipeConditionBlueprint'
              - $ref: '#/components/schemas/PipeParallelBlueprint'
              - $ref: '#/components/schemas/PipeSequenceBlueprint'
              - $ref: '#/components/schemas/PipeSignatureBlueprint'
              discriminator:
                propertyName: type
                mapping:
                  PipeBatch: '#/components/schemas/PipeBatchBlueprint'
                  PipeCompose: '#/components/schemas/PipeComposeBlueprint'
                  PipeCondition: '#/components/schemas/PipeConditionBlueprint'
                  PipeDocGen: '#/components/schemas/PipeDocGenBlueprint'
                  PipeExtract: '#/components/schemas/PipeExtractBlueprint'
                  PipeFunc: '#/components/schemas/PipeFuncBlueprint'
                  PipeImgGen: '#/components/schemas/PipeImgGenBlueprint'
                  PipeJudge: '#/components/schemas/PipeJudgeBlueprint'
                  PipeLLM: '#/components/schemas/PipeLLMBlueprint'
                  PipeParallel: '#/components/schemas/PipeParallelBlueprint'
                  PipeSearch: '#/components/schemas/PipeSearchBlueprint'
                  PipeSequence: '#/components/schemas/PipeSequenceBlueprint'
                  PipeSignature: '#/components/schemas/PipeSignatureBlueprint'
                  PipeStructure: '#/components/schemas/PipeStructureBlueprint'
            type: object
          - type: 'null'
          title: Pipe
      additionalProperties: false
      type: object
      required:
      - domain
      title: PipelexBundleBlueprint
    PipelexModelDeck:
      properties:
        models:
          items:
            $ref: '#/components/schemas/ModelInfo'
          type: array
          title: Models
        aliases:
          additionalProperties:
            additionalProperties:
              type: string
            type: object
          type: object
          title: Aliases
        waterfalls:
          additionalProperties:
            additionalProperties:
              items:
                type: string
              type: array
            type: object
          type: object
          title: Waterfalls
      additionalProperties: true
      type: object
      title: PipelexModelDeck
      description: 'Pipelex''s model deck — the protocol base plus this implementation''s

        routing metadata (aliases, waterfalls), keyed by model category.


        The routing extensions are category-scoped on purpose: the same alias name

        (e.g. `default-small`) legitimately exists in several categories pointing at

        different models, so a flat map would silently lose entries on collision.'
    PipelexProblem:
      properties:
        type:
          type: string
          title: Type
        title:
          type: string
          title: Title
        status:
          anyOf:
          - type: integer
            ge: 100
            le: 599
          - type: 'null'
          title: Status
        detail:
          type: string
          title: Detail
        code:
          type: string
          pattern: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){1,2}$
          title: Code
        domain:
          anyOf:
          - $ref: '#/components/schemas/ProblemDomain'
          - type: string
          title: Domain
        retry:
          anyOf:
          - $ref: '#/components/schemas/RetryVerdict'
          - type: string
          title: Retry
        retry_after:
          anyOf:
          - anyOf:
            - type: integer
            - type: number
            ge: 0
          - type: 'null'
          title: Retry After
        next_step:
          $ref: '#/components/schemas/NextStep'
        params:
          anyOf:
          - $ref: '#/components/schemas/ProblemParams'
          - type: 'null'
        location:
          anyOf:
          - $ref: '#/components/schemas/ProblemLocation'
          - type: 'null'
        errors:
          anyOf:
          - items:
              $ref: '#/components/schemas/ProblemItem'
            type: array
            minItems: 1
          - type: 'null'
          title: Errors
        pipeline_run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Pipeline Run Id
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
        run_error:
          anyOf:
          - $ref: '#/components/schemas/PipelexProblem'
          - type: 'null'
        diagnostics:
          anyOf:
          - $ref: '#/components/schemas/ProblemDiagnostics'
          - type: 'null'
      additionalProperties: true
      type: object
      required:
      - type
      - title
      - detail
      - code
      - domain
      - retry
      - next_step
      title: PipelexProblem
      description: "The MTHDS problem document with Pipelex's members.\n\nAttributes:\n    request_id: The request that carried\
        \ the failure, when known.\n    run_error: On a read of a failed run's results, the run's own problem.\n    diagnostics:\
        \ What only an operator reads; present in the operator view alone."
    PipelexVersionInfo:
      properties:
        protocol_version:
          type: string
          title: Protocol Version
        runner_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Runner Version
        blob_store:
          type: boolean
          title: Blob Store
          default: false
        implementation:
          type: string
          title: Implementation
        implementation_version:
          type: string
          title: Implementation Version
        runtime_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Runtime Version
      additionalProperties: true
      type: object
      required:
      - protocol_version
      - implementation
      - implementation_version
      title: PipelexVersionInfo
      description: 'Pipelex''s version handshake — the protocol base plus this

        implementation''s identification.'
    PipelineRef:
      properties:
        domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
        main_pipe:
          anyOf:
          - type: string
          - type: 'null'
          title: Main Pipe
        entrypoint:
          anyOf:
          - type: string
          - type: 'null'
          title: Entrypoint
      additionalProperties: false
      type: object
      title: PipelineRef
      description: Reference to the pipeline that was executed.
    PresenceMarker:
      type: string
      enum:
      - plain
      - optional
      - force
      title: PresenceMarker
      description: 'The authored presence marker of a declared input slot, verbatim and three-valued.


        `plain` (no marker) and `force` (`!`) are the same requirement on the caller — the slot

        must be supplied — and differ only in what the author asserted; `optional` (`?`) means the

        caller may omit the slot and the pipe handles the absence itself. The distinction is kept on

        the wire because lint and graph surfaces read it, and a producer flattening it to a boolean

        would destroy it for every consumer at once. A consumer that only needs "may this be absent?"

        answers it as `is_optional`, in exactly one place.'
    PresetMatch:
      properties:
        category:
          $ref: '#/components/schemas/ModelCheckCategory'
          description: The category this entry is about.
        resolves_to:
          anyOf:
          - type: string
          - type: 'null'
          title: Resolves To
          description: The model handle a run through the reference would call now in this category, or null when it would
            find none (a target on a backend the runner has not enabled, a waterfall none of whose usable steps the runner
            serves, an alias cycle).
        target:
          type: string
          title: Target
          description: The model the deck binds the preset to, as the deck writes it, which may itself be a reference.
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: The preset's description, or null when the deck gives it none.
      additionalProperties: false
      type: object
      required:
      - category
      - resolves_to
      - target
      - description
      title: PresetMatch
      description: What a preset reference is in one category.
    ProblemDeleteKeyOp:
      properties:
        kind:
          type: string
          const: delete_key
          title: Kind
        table_path:
          items:
            type: string
          type: array
          title: Table Path
        key:
          type: string
          title: Key
      additionalProperties: true
      type: object
      required:
      - kind
      - table_path
      - key
      title: DeleteKeyOp
      description: Remove `key` from the table at `table_path`.
    ProblemDeleteTableOp:
      properties:
        kind:
          type: string
          const: delete_table
          title: Kind
        table_path:
          items:
            type: string
          type: array
          minItems: 1
          title: Table Path
      additionalProperties: true
      type: object
      required:
      - kind
      - table_path
      title: DeleteTableOp
      description: Remove the table at `table_path`, every part of it included.
    ProblemDiagnostics:
      properties:
        error_class:
          type: string
          title: Error Class
        message:
          type: string
          title: Message
        causes:
          anyOf:
          - items:
              $ref: '#/components/schemas/DiagnosticCause'
            type: array
          - type: 'null'
          title: Causes
        params:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Params
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
        provider:
          anyOf:
          - $ref: '#/components/schemas/ProviderDiagnostics'
          - type: 'null'
        migration:
          anyOf:
          - $ref: '#/components/schemas/MigrationErrorBlock'
          - type: 'null'
        runtime_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Runtime Version
        trace_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Trace Id
        span_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Span Id
      additionalProperties: true
      type: object
      required:
      - error_class
      - message
      title: ProblemDiagnostics
      description: "What only an operator reads of a problem: the operator view's ``diagnostics`` member.\n\nAttributes:\n\
        \    error_class: The class of the error the problem was built from, the identity ``error_type`` once was.\n    message:\
        \ The error's own message, capped.\n    causes: The errors below it on its cause chain, by class and code.\n    params:\
        \ The parameters the code declares operator-only.\n    model: The model a failed inference call addressed.\n    provider:\
        \ What the provider said about the call.\n    migration: A pending configuration migration that explains the failure.\n\
        \    runtime_version: The version of the Pipelex runtime that built the problem.\n    trace_id: The trace of the Pipelex\
        \ span the failure happened in.\n    span_id: That span."
    ProblemDocument:
      properties:
        type:
          type: string
          title: Type
          description: 'Stable URI of the documentation page of the error''s `code`: `https://mthds.ai/errors/<code>` for
            a core code, `https://docs.pipelex.com/errors/<code>` for a Pipelex code.'
        title:
          type: string
          title: Title
          description: 'Short, human-readable summary: the title of the error''s `code`.'
        status:
          type: integer
          title: Status
          description: 'HTTP status code, repeated in the body per RFC 9457: the status its `code` declares.'
        detail:
          type: string
          title: Detail
          description: 'Human-readable explanation of this specific failure, rendered from its code''s template and parameters.
            Never parsed: a program branches on `code`.'
        code:
          type: string
          title: Code
          description: 'Registry code of the error, what a client branches on: a core code of the MTHDS standard (e.g. `request.invalid`)
            or a Pipelex code (e.g. `pipelex.config.invalid`).'
        domain:
          type: string
          title: Domain
          description: 'Who must act, the code''s domain: `input`, `method`, `account`, `operator` or `runtime`.'
        retry:
          type: string
          title: Retry
          description: 'Whether repeating the request can succeed, the code''s verdict: `yes`, `no` or `outcome_unknown`.'
        retry_after:
          anyOf:
          - type: number
          - type: 'null'
          title: Retry After
          description: Seconds to wait before a retry, when known, on a code whose verdict is `yes`.
        next_step:
          $ref: '#/components/schemas/NextStep'
          description: 'What the reader should do next: a kind and a sentence, aimed at the caller, or at the operator in
            the operator view.'
        params:
          anyOf:
          - $ref: '#/components/schemas/ProblemParams'
          - type: 'null'
          description: The code's typed parameters, the ones its templates are rendered with.
        location:
          anyOf:
          - $ref: '#/components/schemas/ProblemLocation'
          - type: 'null'
          description: 'Where the failure happened: the failing pipe and its path from the entry pipe, an input, a field,
            a file.'
        errors:
          anyOf:
          - items:
              $ref: '#/components/schemas/ProblemItem'
            type: array
          - type: 'null'
          title: Errors
          description: One item per fault, for a refusal with several, such as a request whose fields the route refuses. On
            `/validate`, `/resolve`, `/codegen` and `/pipe-io` an invalid bundle is a **200** verdict instead, whose `errors`
            are items of this same shape.
        pipeline_run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Pipeline Run Id
          description: The run the failure belongs to.
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
          description: 'Correlation id, echoed in the `X-Request-ID` response header: the caller''s own when valid, else one
            the runner mints.'
        diagnostics:
          anyOf:
          - $ref: '#/components/schemas/ProblemDiagnostics'
          - type: 'null'
          description: 'What only the operator reads: the error''s class and message, its causes, the provider''s answer,
            the model. Present only when the request was authenticated as the operator''s (`AUTH_MODE=api_key`, or a trusted
            proxy).'
      additionalProperties: true
      type: object
      required:
      - type
      - title
      - status
      - detail
      - code
      - domain
      - retry
      - next_step
      title: ProblemDocument
      description: 'An RFC 9457 `application/problem+json` error body — the shape of every failure response.


        Every failure answers its problem document: the RFC''s members (`type`, `title`, `status`, `detail`), the MTHDS

        core''s (`code`, `domain`, `retry`, `next_step`, always present, and `retry_after`, `params`, `location`, `errors`,

        `pipeline_run_id` when they hold a value) and Pipelex''s (`request_id`, always present on a response of this server,

        and `diagnostics` in the operator view alone). No member is ever written as `null`: a member with no value is

        absent. `extra="allow"` mirrors RFC 9457''s open-ended extension-member rule.'
    ProblemDomain:
      type: string
      enum:
      - input
      - method
      - account
      - operator
      - runtime
      title: ProblemDomain
      description: 'Who must act: the protocol''s closed list of domains.'
    ProblemEnsureTableOp:
      properties:
        kind:
          type: string
          const: ensure_table
          title: Kind
        table_path:
          items:
            type: string
          type: array
          minItems: 1
          title: Table Path
      additionalProperties: true
      type: object
      required:
      - kind
      - table_path
      title: EnsureTableOp
      description: Create the table at `table_path` when it is absent.
    ProblemFixSafety:
      type: string
      enum:
      - safe
      - unsafe
      title: FixSafety
      description: Whether a suggested fix may be applied without asking anyone.
    ProblemItem:
      properties:
        code:
          type: string
          pattern: ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){1,2}$
          title: Code
        detail:
          type: string
          title: Detail
        params:
          anyOf:
          - $ref: '#/components/schemas/ProblemParams'
          - type: 'null'
        location:
          anyOf:
          - $ref: '#/components/schemas/ProblemLocation'
          - type: 'null'
        suggestions:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Suggestions
        suggested_fix:
          anyOf:
          - $ref: '#/components/schemas/ProblemSuggestedFix'
          - type: 'null'
      additionalProperties: true
      type: object
      required:
      - code
      - detail
      title: ProblemItem
      description: 'One fault of a problem with several, and one finding of a `/validate` verdict.


        An item carries its own code but no verdict; `effective_domain` reads its domain from its code,

        `code_spec` is the code''s registry entry and `params_as` reads the parameters as a model.'
    ProblemLocation:
      properties:
        pipe:
          anyOf:
          - type: string
          - type: 'null'
          title: Pipe
        path:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Path
        input:
          anyOf:
          - type: string
          - type: 'null'
          title: Input
        field:
          anyOf:
          - type: string
          - type: 'null'
          title: Field
        item:
          anyOf:
          - type: integer
            ge: 0
          - type: 'null'
          title: Item
        attempt:
          anyOf:
          - type: integer
            ge: 1
          - type: 'null'
          title: Attempt
        file:
          anyOf:
          - type: string
          - type: 'null'
          title: File
        line:
          anyOf:
          - type: integer
            ge: 1
          - type: 'null'
          title: Line
        column:
          anyOf:
          - type: integer
            ge: 1
          - type: 'null'
          title: Column
      additionalProperties: true
      type: object
      title: ProblemLocation
      description: Where the error happened, in the method, the request or the run; every member is optional.
    ProblemMoveKeyOp:
      properties:
        kind:
          type: string
          const: move_key
          title: Kind
        table_path:
          items:
            type: string
          type: array
          title: Table Path
        key:
          type: string
          title: Key
        new_table_path:
          items:
            type: string
          type: array
          title: New Table Path
        new_key:
          type: string
          title: New Key
      additionalProperties: true
      type: object
      required:
      - kind
      - table_path
      - key
      - new_table_path
      - new_key
      title: MoveKeyOp
      description: Move `key` from the table at `table_path` into the table at `new_table_path` under `new_key`.
    ProblemParams:
      properties:
        missing_blobs:
          anyOf:
          - items:
              type: string
              pattern: ^[0-9a-f]{64}$
            type: array
          - type: 'null'
          title: Missing Blobs
      additionalProperties: true
      type: object
      title: ProblemParams
      description: 'The typed facts a problem''s sentences were written from.


        Each code declares its own parameters, and the generated registry gives each core code a model of

        them (`CORE_CODE_SPECS[code].params_model`), which `Problem.params_as` validates into. This model

        types only the parameter the protocol types for every reader, `missing_blobs`; every other

        parameter rides `model_extra` as received.'
    ProblemRemapValueOp:
      properties:
        kind:
          type: string
          const: remap_value
          title: Kind
        table_path:
          items:
            type: string
          type: array
          title: Table Path
        key:
          type: string
          title: Key
        mapping:
          additionalProperties:
            type: string
          type: object
          minProperties: 1
          title: Mapping
      additionalProperties: true
      type: object
      required:
      - kind
      - table_path
      - key
      - mapping
      title: RemapValueOp
      description: Rewrite the string value of `key` in the table at `table_path` through `mapping`.
    ProblemRenameTableKeyOp:
      properties:
        kind:
          type: string
          const: rename_table_key
          title: Kind
        table_path:
          items:
            type: string
          type: array
          title: Table Path
        key:
          type: string
          title: Key
        new_key:
          type: string
          title: New Key
      additionalProperties: true
      type: object
      required:
      - kind
      - table_path
      - key
      - new_key
      title: RenameTableKeyOp
      description: Rename `key` to `new_key` within the table at `table_path`.
    ProblemSetKeyOp:
      properties:
        kind:
          type: string
          const: set_key
          title: Kind
        table_path:
          items:
            type: string
          type: array
          title: Table Path
        key:
          type: string
          title: Key
        value:
          anyOf:
          - type: boolean
          - type: integer
          - type: number
          - type: string
          - additionalProperties:
              anyOf:
              - type: boolean
              - type: integer
              - type: number
              - type: string
            type: object
          title: Value
      additionalProperties: true
      type: object
      required:
      - kind
      - table_path
      - key
      - value
      title: SetKeyOp
      description: Write `key = value` in the table at `table_path`.
    ProblemSuggestedFix:
      properties:
        fix_code:
          type: string
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          title: Fix Code
        description:
          type: string
          title: Description
        safety:
          anyOf:
          - $ref: '#/components/schemas/ProblemFixSafety'
          - type: string
          title: Safety
        file:
          anyOf:
          - type: string
          - type: 'null'
          title: File
        ops:
          items:
            oneOf:
            - $ref: '#/components/schemas/ProblemSetKeyOp'
            - $ref: '#/components/schemas/ProblemEnsureTableOp'
            - $ref: '#/components/schemas/ProblemDeleteKeyOp'
            - $ref: '#/components/schemas/ProblemDeleteTableOp'
            - $ref: '#/components/schemas/ProblemRenameTableKeyOp'
            - $ref: '#/components/schemas/ProblemMoveKeyOp'
            - $ref: '#/components/schemas/ProblemRemapValueOp'
            - $ref: '#/components/schemas/ProblemUnknownFixOp'
          type: array
          minItems: 1
          title: Ops
      additionalProperties: true
      type: object
      required:
      - fix_code
      - description
      - safety
      - ops
      title: SuggestedFix
      description: 'A deterministic fix for one fault: operations over a bundle of the method, addressed by TOML key path.'
    ProblemUnknownFixOp:
      properties:
        kind:
          type: string
          title: Kind
      additionalProperties: true
      type: object
      required:
      - kind
      title: UnknownFixOp
      description: 'The reader-side catch-all: an operation whose `kind` is none the protocol lists, which an applier never
        applies.'
    PromptImageDetail:
      type: string
      enum:
      - high
      - low
      - auto
      title: PromptImageDetail
    ProseField:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        min_length:
          anyOf:
          - type: integer
          - type: 'null'
          title: Min Length
        max_length:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Length
        pattern:
          anyOf:
          - type: string
          - type: 'null'
          title: Pattern
        format:
          anyOf:
          - type: string
          - type: 'null'
          title: Format
        kind:
          type: string
          const: prose
          title: Kind
          default: prose
        name:
          type: string
          title: Name
      additionalProperties: false
      type: object
      required:
      - required
      - name
      title: ProseField
      description: '`prose` at a named position.'
    ProseItem:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        min_length:
          anyOf:
          - type: integer
          - type: 'null'
          title: Min Length
        max_length:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Length
        pattern:
          anyOf:
          - type: string
          - type: 'null'
          title: Pattern
        format:
          anyOf:
          - type: string
          - type: 'null'
          title: Format
        kind:
          type: string
          const: prose
          title: Kind
          default: prose
      additionalProperties: false
      type: object
      required:
      - required
      title: ProseItem
      description: '`prose` — flowing free text.'
    ProviderDiagnostics:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        status:
          anyOf:
          - type: integer
          - type: 'null'
          title: Status
        code:
          anyOf:
          - type: string
          - type: 'null'
          title: Code
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
      additionalProperties: true
      type: object
      title: ProviderDiagnostics
      description: What the inference provider said about a failed call, for an operator.
    Quality:
      type: string
      enum:
      - low
      - medium
      - high
      title: Quality
    Range:
      properties:
        start_offset:
          type: integer
          title: Start Offset
        end_offset:
          type: integer
          title: End Offset
        start_line:
          type: integer
          title: Start Line
        start_col:
          type: integer
          title: Start Col
        end_line:
          type: integer
          title: End Line
        end_col:
          type: integer
          title: End Col
      type: object
      required:
      - start_offset
      - end_offset
      - start_line
      - start_col
      - end_line
      - end_col
      title: Range
      description: Byte offsets plus 1-based line/column coordinates from `pipelex-tools-py`.
    ReasoningEffort:
      type: string
      enum:
      - none
      - minimal
      - low
      - medium
      - high
      - xhigh
      - max
      title: ReasoningEffort
    RemapValueOp:
      properties:
        table_path:
          items:
            type: string
          type: array
          title: Table Path
        kind:
          type: string
          const: remap_value
          title: Kind
          default: remap_value
        key:
          type: string
          title: Key
        mapping:
          additionalProperties:
            type: string
          type: object
          minProperties: 1
          title: Mapping
      additionalProperties: false
      type: object
      required:
      - table_path
      - key
      - mapping
      title: RemapValueOp
      description: 'Rewrite ``key``''s value through ``mapping``, doing nothing when it is not a mapped value.


        Only string values are remapped: the operation exists for renamed enumerated values, whose

        TOML representation is always a string.


        ``key`` may be the wildcard segment, and this is the one kind for which it means anything:

        "each key of the addressed table". A mapping from the user''s own keys to an enumerated value

        — ``dict[str, LogLevel]`` — keeps its spellings under keys only the document can enumerate,

        so no fixed ``key`` reaches them and this is the only shape in which a member renamed beneath

        an open mapping can be repaired at all.'
    RenameTableKeyOp:
      properties:
        table_path:
          items:
            type: string
          type: array
          title: Table Path
        kind:
          type: string
          const: rename_table_key
          title: Kind
          default: rename_table_key
        key:
          type: string
          title: Key
        new_key:
          type: string
          title: New Key
      additionalProperties: false
      type: object
      required:
      - table_path
      - key
      - new_key
      title: RenameTableKeyOp
      description: Rename ``key`` to ``new_key`` in place within the addressed table, keeping its position.
    ResolveValidReport:
      properties:
        is_valid:
          type: boolean
          const: true
          title: Is Valid
          default: true
        crate:
          additionalProperties: true
          type: object
          title: Crate
          description: The normalized library crate (canonical JSON encoding, `fingerprint` included).
        message:
          type: string
          title: Message
          description: Status message
          default: MTHDS library resolved successfully
      type: object
      required:
      - crate
      title: ResolveValidReport
      description: 'The 200 **valid** arm: the normalized library crate, ready for any consumer''s emitter.


        The crate rides as the canonical JSON encoding''s object form (top-level maps key-sorted,

        non-semantic provenance dropped) — the same bytes `pipelex resolve --format json` prints, so a

        fingerprint computed from either surface agrees. Its `fingerprint` and `mthds_version` members

        ride inside the crate payload itself.'
    RetryVerdict:
      type: string
      enum:
      - 'no'
      - 'yes'
      - outcome_unknown
      title: RetryVerdict
      description: 'Whether repeating the operation can succeed: the protocol''s closed list of verdicts.'
    RunState:
      type: string
      enum:
      - STARTED
      - RUNNING
      - COMPLETED
      - FAILED
      - CANCELLED
      - ERROR
      title: RunState
      description: Run lifecycle state — a pipelex extension field on run responses (the protocol defines none).
    SearchSetting:
      properties:
        model:
          type: string
          title: Model
        include_images:
          type: boolean
          title: Include Images
          default: false
        include_inline_citations:
          type: boolean
          title: Include Inline Citations
          default: true
        max_results:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Max Results
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      additionalProperties: false
      type: object
      required:
      - model
      title: SearchSetting
    ServiceIdentity:
      properties:
        message:
          type: string
          title: Message
          description: Name of the service answering on this origin.
      type: object
      required:
      - message
      title: ServiceIdentity
      description: Body of `GET /` — the service identity banner.
    SizeTier:
      type: string
      enum:
      - 0.5k
      - 1k
      - 2k
      - 4k
      title: SizeTier
      description: 'Portable image size classes.


        A tier promises a pixel class at the pipe''s chosen aspect ratio, not identical

        pixel dimensions across providers: each provider maps the tier to its own grid

        or computed dimensions.'
    SpecialOutcome:
      type: string
      enum:
      - fail
      - continue
      title: SpecialOutcome
    StepKind:
      type: string
      enum:
      - retry
      - wait
      - read_run
      - refresh
      - change_input
      - change_method
      - change_model
      - check_credentials
      - request_access
      - check_account
      - fix_configuration
      - upgrade
      - contact_owner
      - report
      title: StepKind
      description: 'What the reader does next: the protocol''s closed list of step kinds.'
    StepRole:
      type: string
      enum:
      - draft_text
      - structure
      title: StepRole
      description: 'Role played by a synthetic pipe inside an elaborated bundle.


        DRAFT_TEXT: step-1 of a `preliminary_text` elaboration — the pipe that produces the draft Text.

        STRUCTURE: step-2 of a `preliminary_text` elaboration — the pipe that turns the draft Text into the structured concept.'
    StructuringMethod:
      type: string
      enum:
      - direct
      - preliminary_text
      title: StructuringMethod
    Stuff:
      properties:
        stuff_code:
          type: string
          title: Stuff Code
        stuff_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Stuff Name
        concept:
          type: string
        content:
          $ref: '#/components/schemas/StuffContent'
      additionalProperties: false
      type: object
      required:
      - stuff_code
      - concept
      - content
      title: Stuff
    StuffContent:
      properties: {}
      type: object
      title: StuffContent
    SubPipeBlueprint:
      properties:
        pipe:
          type: string
          title: Pipe
        result:
          anyOf:
          - type: string
          - type: 'null'
          title: Result
        nb_output:
          anyOf:
          - type: integer
          - type: 'null'
          title: Nb Output
        multiple_output:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Multiple Output
        batch_over:
          anyOf:
          - type: string
          - type: 'null'
          title: Batch Over
        batch_as:
          anyOf:
          - type: string
          - type: 'null'
          title: Batch As
      additionalProperties: false
      type: object
      required:
      - pipe
      title: SubPipeBlueprint
    TagStyle:
      type: string
      enum:
      - no_tag
      - ticks
      - xml
      - square_brackets
      title: TagStyle
    TemplateBlueprint:
      properties:
        template:
          type: string
          title: Template
          description: Raw template source
        templating_style:
          anyOf:
          - $ref: '#/components/schemas/TemplatingStyle'
          - type: 'null'
          description: How the tag and format filters render in this template; omit it to take the runtime default templating
            style
        category:
          $ref: '#/components/schemas/TemplateCategory'
          description: Category of the template (could also be HTML, MARKDOWN, MERMAID, etc.), influences template rendering
            rules
        extra_context:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Extra Context
          description: Additional context variables for template rendering
      additionalProperties: false
      type: object
      required:
      - template
      - category
      title: TemplateBlueprint
      description: 'The rich form of a template: its Jinja2 source and category, plus an optional templating style and extra
        context.'
    TemplateCategory:
      type: string
      enum:
      - basic
      - expression
      - html
      - markdown
      - mermaid
      - llm_prompt
      - img_gen_prompt
      title: TemplateCategory
    TemplatingStyle:
      properties:
        tag_style:
          $ref: '#/components/schemas/TagStyle'
        text_format:
          $ref: '#/components/schemas/TextFormat'
          default: plain
      additionalProperties: false
      type: object
      required:
      - tag_style
      title: TemplatingStyle
      description: 'How a pipe''s inputs are tagged and formatted into its prompt: a tag style and a text format.'
    TextField:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        min_length:
          anyOf:
          - type: integer
          - type: 'null'
          title: Min Length
        max_length:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Length
        pattern:
          anyOf:
          - type: string
          - type: 'null'
          title: Pattern
        format:
          anyOf:
          - type: string
          - type: 'null'
          title: Format
        kind:
          type: string
          const: text
          title: Kind
          default: text
        name:
          type: string
          title: Name
      additionalProperties: false
      type: object
      required:
      - required
      - name
      title: TextField
      description: '`text` at a named position — a top-level field or a structure field.'
    TextFormat:
      type: string
      enum:
      - plain
      - markdown
      - html
      - json
      title: TextFormat
    TextItem:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        min_length:
          anyOf:
          - type: integer
          - type: 'null'
          title: Min Length
        max_length:
          anyOf:
          - type: integer
          - type: 'null'
          title: Max Length
        pattern:
          anyOf:
          - type: string
          - type: 'null'
          title: Pattern
        format:
          anyOf:
          - type: string
          - type: 'null'
          title: Format
        kind:
          type: string
          const: text
          title: Kind
          default: text
      additionalProperties: false
      type: object
      required:
      - required
      title: TextItem
      description: '`text` — a short single-line string.'
    TimingSpec:
      properties:
        started_at:
          type: string
          format: date-time
          title: Started At
        ended_at:
          type: string
          format: date-time
          title: Ended At
        duration:
          type: number
          title: Duration
          description: Duration in seconds, included in JSON serialization.
          readOnly: true
      additionalProperties: false
      type: object
      required:
      - started_at
      - ended_at
      - duration
      title: TimingSpec
      description: Timing information for a node execution.
    TokensUsageRecord:
      properties:
        model_type:
          type: string
          title: Model Type
        inference_model_name:
          type: string
          title: Inference Model Name
        inference_model_id:
          type: string
          title: Inference Model Id
        pipe_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Pipe Code
        job_category:
          anyOf:
          - type: string
          - type: 'null'
          title: Job Category
        unit_job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Unit Job Id
        nb_tokens_by_category:
          additionalProperties:
            type: integer
          type: object
          title: Nb Tokens By Category
        cost:
          anyOf:
          - type: number
          - type: 'null'
          title: Cost
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
      additionalProperties: false
      type: object
      required:
      - model_type
      - inference_model_name
      - inference_model_id
      - nb_tokens_by_category
      title: TokensUsageRecord
      description: 'One client-facing usage record per inference call.


        ``extra="forbid"`` is deliberate: server-side emission is the shape authority, so an

        accidental new field fails loudly here instead of silently widening the contract.

        Enum-ish fields (``model_type``, ``job_category``, ``unit_job_id``, and the

        ``nb_tokens_by_category`` keys) are open sets on the wire, typed as plain strings —

        runtime enum churn is non-breaking for clients.'
    TreeFileRead:
      properties:
        tree_path:
          type: string
          title: Tree Path
          description: The file's path from the root of the step's method tree, such as `templates/invoice.html`.
        use:
          $ref: '#/components/schemas/TreeFileUse'
          description: 'What the step reads the file as: `template`, the template a PipeDocGen step fills; `template_asset`,
            an image, a stylesheet or a font its HTML template names; `python_module`, the module of the function a PipeFunc
            step calls.'
      additionalProperties: false
      type: object
      required:
      - tree_path
      - use
      title: TreeFileRead
      description: 'A file of its method tree a step reads: its tree path, and what the step reads it as.'
    TreeFileUse:
      type: string
      enum:
      - template
      - template_asset
      - python_module
      title: TreeFileUse
      description: What a step reads a file of its method tree as.
    UnexplainedPath:
      properties:
        path:
          type: string
          title: Path
        note:
          type: string
          title: Note
      additionalProperties: false
      type: object
      required:
      - path
      - note
      title: UnexplainedPath
      description: 'A path the current schema does not know and no ledger entry removes.


        Populated by the downgrade diagnosis, which lands with the commands: the file is either

        carrying a typo or was written by a newer pipelex than the one running.'
    UnknownField:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: unknown
          title: Kind
          default: unknown
        name:
          type: string
          title: Name
      additionalProperties: false
      type: object
      required:
      - required
      - name
      title: UnknownField
      description: '`unknown` at a named position.'
    UnknownItem:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        concept_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Ref
        refines:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Refines
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        required:
          type: boolean
          title: Required
        presence:
          anyOf:
          - $ref: '#/components/schemas/PresenceMarker'
          - type: 'null'
        gating:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Gating
        default_value:
          title: Default Value
        examples:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Examples
        hints:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Hints
        kind:
          type: string
          const: unknown
          title: Kind
          default: unknown
      additionalProperties: false
      type: object
      required:
      - required
      title: UnknownItem
      description: '`unknown` — not honestly describable as any other kind.


        The mandatory escape hatch that makes a total derivation truthful: a renderer falls back to raw

        entry against the slot''s `json_schema` in the pipe I/O contract.'
    UploadTarget:
      properties:
        method:
          type: string
          title: Method
          description: The HTTP method, such as PUT.
        url:
          type: string
          title: Url
          description: 'Where to send the bytes: this runner''s own `PUT /v1/blobs/{sha256}`, with a signed query.'
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
          description: The headers to send, exactly.
      type: object
      required:
      - method
      - url
      - headers
      title: UploadTarget
      description: 'Where to upload one blob: send its bytes as the whole body of a request with this method to this URL,
        with exactly these headers.'
    ValidReport:
      properties:
        is_valid:
          type: boolean
          const: true
          title: Is Valid
          default: true
        warnings:
          items:
            $ref: '#/components/schemas/ProblemItem'
          type: array
          title: Warnings
          description: 'Advisory findings on the valid bundle, one problem item each, with the code the finding''s type names:
            they never flip `is_valid`. The same item shape as the invalid arm''s `errors`.'
        bundle_blueprint:
          $ref: '#/components/schemas/PipelexBundleBlueprint'
        pipe_io_contracts:
          additionalProperties:
            $ref: '#/components/schemas/PipeIOContract'
          type: object
          title: Pipe Io Contracts
        input_form:
          additionalProperties:
            $ref: '#/components/schemas/PipeInputFormDescriptor'
          type: object
          title: Input Form
          description: 'Opt-in Pipelex-API structured view: per-pipe input-form descriptors keyed exactly like `pipe_io_contracts`,
            present only when the request''s `views` includes `input_form`. Absent by default — the structured contract fields
            remain the verdict; this is a projection of them.'
        output_form:
          additionalProperties:
            $ref: '#/components/schemas/PipeOutputFormDescriptor'
          type: object
          title: Output Form
          description: 'Opt-in Pipelex-API structured view: per-pipe output-form descriptors keyed exactly like `pipe_io_contracts`,
            present only when the request''s `views` includes `output_form`. Absent by default. Read with the output contract''s
            `json_schema`, which states the shape of the payload this descriptor describes.'
        liftable_pipes:
          items:
            $ref: '#/components/schemas/LiftablePipeEntry'
          type: array
          title: Liftable Pipes
        tree_files_read:
          additionalProperties:
            items:
              $ref: '#/components/schemas/TreeFileRead'
            type: array
          type: object
          title: Tree Files Read
          description: 'Per pipe, the files of the method''s tree the step reads, keyed by namespaced `pipe_ref` like `pipe_io_contracts`:
            each file by its tree path, with what the step reads it as. A PipeDocGen step reads its template and the images,
            stylesheets and fonts its HTML template names by literal relative URLs; a PipeFunc step reads the module of its
            function. A pipe that reads no file of the tree, a controller included, has an empty list.'
        tree_file_readers:
          additionalProperties:
            items:
              type: string
            type: array
          type: object
          title: Tree File Readers
          description: 'The per-file view of `tree_files_read`: each tree path a step reads, in sorted order, to the namespaced
            refs of the pipes that read it. A file of the method''s tree absent here is read by no step.'
        graph_spec:
          anyOf:
          - $ref: '#/components/schemas/GraphSpec'
          - type: 'null'
        validated_pipes:
          items:
            $ref: '#/components/schemas/ValidatedPipeEntry'
          type: array
          title: Validated Pipes
        pending_signatures:
          items:
            type: string
          type: array
          title: Pending Signatures
        is_runnable:
          type: boolean
          title: Is Runnable
          default: true
        mthds_contents:
          items:
            type: string
          type: array
          title: Mthds Contents
          description: 'The MTHDS contents that were validated: the request''s `mthds_contents`, or the texts of a method
            tree''s `.mthds` bundles in tree path order.'
        message:
          type: string
          title: Message
          description: Status message
          default: MTHDS content validated successfully
        default_pipe_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Default Pipe Ref
          description: 'The qualified `domain.pipe_code` a caller gets by omitting the pipe selector — the pipe a selector-less
            run of THIS request would execute. For a method tree (`files` or a `method_ref`) it is the tree''s entry pipe
            by the MTHDS protocol''s rule: the `main_pipe` of the `METHODS.toml` at its root, else the one `main_pipe` its
            bundles declare. For inline `mthds_contents` it is the closure''s primary blueprint''s `main_pipe` qualified by
            its domain. Absent when no entry pipe is determined, in which case a selector-less run would be refused too.'
        rendered_markdown:
          anyOf:
          - type: string
          - type: 'null'
          title: Rendered Markdown
          description: 'Opt-in Pipelex-API presentation extra: a server-rendered Markdown view of the valid verdict, present
            only when the request''s `render` includes `markdown`. Absent by default — the structured fields remain the contract;
            this is the view.'
      additionalProperties: true
      type: object
      required:
      - bundle_blueprint
      - mthds_contents
      title: ValidReport
      description: 'The 200 **valid** arm: the canonical `PipelexValidationReport` plus this server''s wire-only extras.


        The report fields are inherited — typed models, identical to what the local runtime

        returns for the same bundle, with `is_valid: Literal[True]` (from the report) as the union

        discriminant. The extras exist for HTTP clients only (the webapp reads back `mthds_contents`);

        they are NOT part of the canonical report and no in-process consumer should depend on them.


        `warnings` is re-declared as problem items: the canonical report holds the advisory findings as the validation

        items the local channels render, and the wire carries each as the problem item its type''s code makes

        (`pipelex.pipeline.validation_errors.warning_problem_items`), the item shape `errors` has on the invalid arm.


        Two inherited fields are deliberately re-declared: `input_form` and `output_form`. The canonical

        report requires both (a backend that forgets to derive one must fail loudly rather than ship an

        empty view), but on the wire each is an opt-in structured view gated by the request''s `views` —

        so both are re-declared with defaults here, keeping them out of the published schema''s `required`

        set. The values still always arrive from the report; the route pops each when its token was not

        requested. They are separate tokens rather than one because they answer separate questions: a

        caller building a fill-in form wants the inputs, a caller rendering a result or registering a

        tool signature wants the output, and neither should pay for the other.'
    ValidateRequest:
      properties:
        analytics_groups:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Analytics Groups
          description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the host-supplied groups the caller of this
            request belongs to, as a mapping of group type to group key (e.g. `{"organization": "org_acme"}`), exactly as
            a run request states them. The work this request does is not a run, but it still emits telemetry — the validation
            sweep''s `pipe_dry_run` event and its dry runs — and that telemetry is attributed to the caller: the authenticated
            user and these groups. Same rules and same 422 `InvalidAnalyticsGroups` refusal as on `/execute` and `/start`.
            Omit it and the caller belongs to no group.'
        mthds_contents:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 16
            minItems: 1
          - type: 'null'
          title: Mthds Contents
          description: 'Being retired, and refused by a later release: send the method in `files`. MTHDS contents to load
            (always an array, even for a single file). Exactly one of `mthds_contents` / `files` / `method_ref`.'
        files:
          anyOf:
          - additionalProperties:
              anyOf:
              - type: string
              - $ref: '#/components/schemas/Base64FileEntry'
              - $ref: '#/components/schemas/HashFileEntry'
            type: object
          - type: 'null'
          title: Files
          description: 'The method as a map of file entries, the MTHDS standard''s form of a method tree that travels: each
            key is a tree path (relative, forward slashes, in Unicode NFC, no `.` or `..` segment, no segment starting with
            a dot), and each value is the file''s UTF-8 text, `{"base64": ...}` holding its bytes, or `{"sha256": ..., "size":
            ...}` naming bytes this runner already holds (uploaded with `POST /v1/blobs/missing` then `PUT /v1/blobs/{sha256}`).
            The map is read from the request''s JSON text: a key given twice, a key the membership rule keeps out of every
            tree (`.mthds/` included) and colliding keys are a 422 `method.package_invalid` whose `reason` is the refusal''s
            code and whose `path` names the first path, a key leaving the tree is a 422 `security.input_path_refused`, a malformed
            entry is a 422 `request.invalid`, and hash entries the runner does not hold are one 422 `request.blobs_missing`
            whose `missing_blobs` parameter lists every such hash. Its `.mthds` files are the method''s bundles and every
            other file is one a step may read, such as a `PipeDocGen` template or a `PipeFunc` module. With no `pipe_code`,
            the run starts at the `main_pipe` of the `METHODS.toml` at the tree''s root, or else at the one `main_pipe` its
            bundles declare. Custom `.py` is only honored on a sandbox-hosted deployment. The whole tree is validated, its
            Python included, by syntax. Exactly one of `mthds_contents` / `files` / `method_ref`.'
        dependencies:
          anyOf:
          - additionalProperties:
              additionalProperties:
                anyOf:
                - type: string
                - $ref: '#/components/schemas/Base64FileEntry'
                - $ref: '#/components/schemas/HashFileEntry'
              type: object
            type: object
          - type: 'null'
          title: Dependencies
          description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the method packages the method calls by address
            that this runner cannot fetch, such as one an author has not published, as `{"<address>": <map of file entries>}`:
            each value is a tree of its own, read as `files` is, with a `METHODS.toml` at its root declaring the address it
            is keyed by. They are searched before the runner''s installed copies, for this request alone. Accompanies `files`.'
        method_ref:
          anyOf:
          - type: string
            maxLength: 512
            minLength: 1
          - type: 'null'
          title: Method Ref
          description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — validate a published method by reference
            instead of inline contents. Address form: `github.com/<owner>/<repo>[/<selector>][@<tag>]`, resolved by THIS runner
            through the same fetch path as a `method_ref` run; the package''s tree, read from its commit, is validated as
            a `files` tree is. Exactly one of `mthds_contents` / `files` / `method_ref`. A resolution failure (fetch, package
            location, the custom-Python policy) is a non-2xx `problem+json` — never an `is_valid: false` verdict, which is
            reserved for actual MTHDS content.'
        allow_signatures:
          type: boolean
          title: Allow Signatures
          description: When true, the validation sweep tolerates unimplemented pipe signatures instead of rejecting the bundle
            (signatures dry-run trivially by minting a mock). Defaults to false (strict).
          default: false
        mthds_sources:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Mthds Sources
          description: 'Being retired with `mthds_contents`, and refused by a later release: the bundles of a method sent
            in `files` are named by their tree paths. Optional per-file sources, parallel to `mthds_contents`. When provided,
            each entry is threaded onto the corresponding bundle''s `source` so server-side validation errors carry a `source`
            pointing at the owning file. Must match `mthds_contents` in length when present.'
        resources:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Resources
          description: 'The files submitted with the bundle that its steps read, such as a PipeDocGen step''s `template_file`
            (an `.xlsx`, `.docx`, `.pptx` or `.html` template): a JSON object mapping each file''s bundle-relative path, exactly
            as the step names it, to the file''s bytes in standard base64. A path must be relative and written with forward
            slashes, with no `..` segment, backslash or colon. Beside inline `mthds_contents`, every bundle of the request
            is read as sitting in one directory, and every file must be named by a step, or the request is refused with a
            422 `BundleResourceNotNamedError`. Beside a method tree, `files` or `bundle_b64`, each file joins the tree at
            its path from the tree''s root, where a file the tree already holds must have the same bytes. By default at most
            32 files, 5120 KiB each and 10240 KiB in all, decoded; a deployment sets its own with `MAX_RESOURCES_PER_REQUEST`,
            `MAX_RESOURCE_FILE_KIB` and `MAX_RESOURCES_TOTAL_KIB`. The files make one method tree with the bundles, which
            the run names by its digest: no file''s bytes travel with the run, each being read where a step uses it. Being
            retired with `mthds_contents`, and refused by a later release: send these files in the method''s tree, in `files`.'
        render:
          items:
            type: string
          type: array
          title: Render
          description: 'Opt-in Pipelex-API presentation extra: view formats to render server-side. A supported token (`markdown`)
            adds a `rendered_<format>` field (e.g. `rendered_markdown`) to the 200 verdict, on both the valid and invalid
            arms. Unknown/unsupported tokens are silently ignored (presentation hint, not part of the verdict contract); the
            default empty list renders nothing and the response is unchanged.'
        views:
          items:
            type: string
          type: array
          title: Views
          description: 'Opt-in Pipelex-API structured views: extra projections to attach to the 200 verdict. A supported token
            (`input_form`, `output_form`) adds a **same-named** top-level field to the valid arm only. Unknown/unsupported
            tokens are silently ignored (a view is a projection of facts the verdict already determined, not part of the verdict
            contract); the default empty list attaches nothing and the response is byte-identical to a request that omits
            the field. Independent of `render`: a request may carry both, each resolving its own tokens.'
        orchestration_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Orchestration Mode
          description: 'Optional per-request orchestration-mode (backend) override for the validation dispatch (same plumbing
            as `/start`). An OPEN string token: `direct` validates in-process; a `temporal` mode dispatches the whole job
            to a worker; any plugin-provided token is accepted and an unregistered one is refused at dispatch. Honored only
            when the deployment sets `allow_request_orchestration_mode_override = true` in its `api.toml`; otherwise a token
            that differs from the deployment default is refused with a 422 `pipelex.deployment.orchestration_override_forbidden`.
            Omitted → the default.'
        read_scope:
          anyOf:
          - type: string
          - type: 'null'
          title: Read Scope
          description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the scope the validation reads the method
            under, as a run''s `read_scope`: a multi-tenant host sends the one of the organization it serves. A hash entry
            of `files` resolves in that scope''s blob store, the tree the validation read is recorded there, and the runner
            hands the scope to its validator, so a validation dispatched to a worker hands it the method through that store.
            Omit it and a hash entry resolves in the caller''s own id''s store, but nothing is recorded and the validator
            is handed no scope, so a dry run without one leaves nothing stored.'
      type: object
      title: ValidateRequest
      description: 'The method to validate, in `files`, by `method_ref` or as `mthds_contents`, plus `allow_signatures` and
        optional per-file sources.


        `mthds_contents`, and the `mthds_sources` and `resources` that serve it, are being retired: a later release

        refuses them, and a method is sent in `files`, whose bundles are named by their tree paths.


        `mthds_sources`, when provided, pairs each `mthds_contents[i]` with a logical source (e.g. the

        file''s path relative to the submitted directory). The runner threads it onto

        `blueprint.source`, so the problem items in `errors` on a 200 `InvalidReport` carry a real

        `location.file` the client maps back to the owning file — without it the in-memory load path

        leaves the file unknown and cross-file diagnostics misfire. Omit it and behavior is unchanged.'
    ValidatedPipeEntry:
      properties:
        pipe_ref:
          type: string
          title: Pipe Ref
        status:
          $ref: '#/components/schemas/DryRunStatus'
      additionalProperties: true
      type: object
      required:
      - pipe_ref
      - status
      title: ValidatedPipeEntry
      description: 'One entry in the ``validated_pipes`` JSON envelope returned by the validate surfaces.


        The ``pipe_ref`` key carries the namespaced ``pipe_ref`` (``domain.code``) — never the bare code.

        ``status`` is a ``DryRunStatus`` (a ``StrEnum``), so it serializes to its plain string value.'
    WaterfallMatch:
      properties:
        category:
          $ref: '#/components/schemas/ModelCheckCategory'
          description: The category this entry is about.
        resolves_to:
          anyOf:
          - type: string
          - type: 'null'
          title: Resolves To
          description: The model handle a run through the reference would call now in this category, or null when it would
            find none (a target on a backend the runner has not enabled, a waterfall none of whose usable steps the runner
            serves, an alias cycle).
        fallbacks:
          items:
            type: string
          type: array
          title: Fallbacks
          description: The waterfall's steps, in order.
      additionalProperties: false
      type: object
      required:
      - category
      - resolves_to
      - fallbacks
      title: WaterfallMatch
      description: What a waterfall reference is in one category.
    WorkingMemory:
      properties:
        root:
          additionalProperties:
            $ref: '#/components/schemas/Stuff'
          type: object
          title: Root
        aliases:
          additionalProperties:
            type: string
          type: object
          title: Aliases
        absences:
          additionalProperties:
            $ref: '#/components/schemas/AbsenceRecord'
          type: object
          title: Absences
      additionalProperties: false
      type: object
      title: WorkingMemory