# 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 v0.6.0.
  description: 'This server implements the [MTHDS Protocol](https://mthds.ai) v0.6.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`), build tooling (`/build/*`), 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.25.0
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.'
      operationId: get_version_v1_version_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelexVersionInfo'
        '500':
          description: A `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML
            override, a backend fault), or an unclassified error sanitized by the catch-all handler. Report the `request_id`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
      x-mthds-protocol: true
  /v1/build/inputs:
    post:
      tags:
      - build
      summary: Build Inputs
      description: "Generate an example inputs template for a pipe (the inputs projection, per pipe).\n\nRides the **same\
        \ static core** as `POST /resolve` and `POST /codegen`: the closure is resolved to\nits normalized crate, the requested\
        \ pipe is read live from the library that leaves loaded, and its\n*declared* inputs are rendered — the exact projection\
        \ `pipelex codegen inputs` writes, on both of\nits axes (`format`, `explicit`).\n\nStatic is the point: a template\
        \ is a read of the pipe's declared IO, so there is **no dry-run\nsweep** here (that is `/validate`'s vocabulary, and\
        \ `/build/runner`'s need). A valid verdict says\nthe closure is structurally sound and the template matches what the\
        \ pipe declares — it is *not* a\npromise the pipe runs. Ask `/validate` for that.\n\nThis projection is deliberately\
        \ **not** a `/codegen` kind: the templates are user-editable\nscaffolds, never stamped or locked, so they cannot ride\
        \ the trust chain `/codegen`'s valid arm\npromises (see `CodegenRouteKind`).\n\nResponse contract (the `/validate`\
        \ discipline):\n\n- **Valid verdict (200, `is_valid: true`):** the template, in `inputs` or `inputs_toml` per `format`.\n\
        - **Invalid verdict (200, `is_valid: false`):** the closure could not be parsed, loaded, or\n  validated — `validation_errors[]`\
        \ from pipelex's one shared builder; no template exists.\n- **No verdict (non-2xx):** an unknown pipe ref, an omitted\
        \ `pipe_ref` that nothing defaults (no\n  fetched-manifest `main_pipe`, and a closure declaring no — or several —\
        \ `main_pipe`), or a\n  malformed closure selector is a request-shape 422 problem+json; a registry-form `method_ref`\n\
        \  is a 501 until server-side method-registry resolution exists.\n\nAn omitted `pipe_ref` defaults the way a run by\
        \ address does: to the fetched package manifest's\n`main_pipe` on a `method_ref` request, else to the closure's own\
        \ declared `main_pipe`."
      operationId: build_inputs_v1_build_inputs_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildInputsRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/BuildInputsValidReport'
                - $ref: '#/components/schemas/CrateInvalidReport'
                title: Response Build Inputs V1 Build Inputs Post
                discriminator:
                  propertyName: is_valid
                  mapping:
                    'True': '#/components/schemas/BuildInputsValidReport'
                    'False': '#/components/schemas/CrateInvalidReport'
        '401':
          description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
            or `AUTH_MODE=jwt`).
          headers:
            WWW-Authenticate:
              description: Authentication challenge — always `Bearer`.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a malformed body, a field failing validation, or an `input`-domain
            pipelex error (a `.mthds` bundle the caller must fix). 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 `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML
            override, a backend fault), or an unclassified error sanitized by the catch-all handler. Report the `request_id`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '404':
          description: '`MethodPackageNotFoundError` — the `method_ref` repository was fetched, but no package in it matches
            the requested address by manifest identity. The message lists the packages the repository does contain.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '501':
          description: '`MethodRefNotSupported` — the request selected its closure by a **registry-form** `method_ref` (not
            a `github.com/...` address), and no server-side method registry resolves those yet. Use an address-form reference
            or submit inline `files[]` instead.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
  /v1/build/output:
    post:
      tags:
      - build
      summary: Build Output
      description: "Generate an example output representation for a pipe (the output projection, per pipe).\n\nRides the **same\
        \ static core** as `POST /resolve`, `POST /codegen` and `POST /build/inputs`: the\nclosure is resolved to its normalized\
        \ crate, the requested pipe is read live from the library that\nleaves loaded, and its *declared* output is rendered.\n\
        \nStatic is the point: the representation is a read of the pipe's declared IO, so there is **no\ndry-run sweep** here.\
        \ A valid verdict says the closure is structurally sound and the shape matches\nwhat the pipe declares — it is *not*\
        \ a promise the pipe runs. Ask `/validate` for that.\n\nResponse contract (the `/validate` discipline):\n\n- **Valid\
        \ verdict (200, `is_valid: true`):** the representation, in `output` or `output_python` per `format`.\n- **Invalid\
        \ verdict (200, `is_valid: false`):** the closure could not be parsed, loaded, or\n  validated — `validation_errors[]`;\
        \ no representation exists.\n- **No verdict (non-2xx):** an unknown pipe ref, an omitted `pipe_ref` that nothing defaults\
        \ (no\n  fetched-manifest `main_pipe`, and a closure declaring no — or several — `main_pipe`), a pipe\n  whose `native.Anything`\
        \ output has no determinable shape, or a malformed closure selector is a\n  request-shape 422 problem+json; a registry-form\
        \ `method_ref` is a 501 until server-side\n  method-registry resolution exists.\n\nAn omitted `pipe_ref` defaults\
        \ the way a run by address does: to the fetched package manifest's\n`main_pipe` on a `method_ref` request, else to\
        \ the closure's own declared `main_pipe`."
      operationId: build_output_v1_build_output_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildOutputRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/BuildOutputValidReport'
                - $ref: '#/components/schemas/CrateInvalidReport'
                title: Response Build Output V1 Build Output Post
                discriminator:
                  propertyName: is_valid
                  mapping:
                    'True': '#/components/schemas/BuildOutputValidReport'
                    'False': '#/components/schemas/CrateInvalidReport'
        '401':
          description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
            or `AUTH_MODE=jwt`).
          headers:
            WWW-Authenticate:
              description: Authentication challenge — always `Bearer`.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a malformed body, a field failing validation, or an `input`-domain
            pipelex error (a `.mthds` bundle the caller must fix). 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 `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML
            override, a backend fault), or an unclassified error sanitized by the catch-all handler. Report the `request_id`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '404':
          description: '`MethodPackageNotFoundError` — the `method_ref` repository was fetched, but no package in it matches
            the requested address by manifest identity. The message lists the packages the repository does contain.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '501':
          description: '`MethodRefNotSupported` — the request selected its closure by a **registry-form** `method_ref` (not
            a `github.com/...` address), and no server-side method registry resolves those yet. Use an address-form reference
            or submit inline `files[]` instead.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
  /v1/build/runner:
    post:
      tags:
      - build
      summary: Build Runner
      description: 'Generate a Python runner script for a pipe, riding the codegen types projection.


        The one `/build/*` projection that is **not** static: a runner script is a promise the pipe can

        actually run, so this route keeps the dry-run sweep its siblings dropped (and with it

        `allow_signatures`, which only ever parameterized that sweep). `validate_bundle` opens a single

        library, loads the closure, sweeps, and on success leaves the library loaded + current; on failure

        it tears it down itself. On the success path the crate is read from that library, the

        `python-structures` projection is emitted and stamped, and the runner script is generated with the

        **emitted** class names — the same flow as a local `pipelex build runner`.


        The sweep is scoped to the requested pipe, so unrelated broken siblings do not block a good pipe.

        When `pipe_ref` is omitted the scope is not settled before the closure loads, so the whole closure

        is swept and the pipe then defaults the way a run by address does — to the fetched package

        manifest''s `main_pipe` on a `method_ref` request, else to the closure''s own declared `main_pipe` —

        a stricter verdict, and the honest one for a caller who did not say which pipe they meant.


        Response contract (the `/validate` discipline): an invalid closure — including a failed dry-run of

        the requested pipe — is a produced verdict: a **200** `is_valid: false` with the structured

        `validation_errors[]`. Non-2xx is reserved for no-verdict conditions: a request-shape 422 (an

        unknown pipe ref, an omitted `pipe_ref` that nothing defaults — no fetched-manifest `main_pipe`,

        and a closure declaring no, or several, `main_pipe` — or a requested pipe whose cross-package

        dependencies are absent from the request), a 501 for a registry-form `method_ref`, auth, server

        fault — RFC 7807 via the global handlers.'
      operationId: build_runner_v1_build_runner_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildRunnerRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/BuildRunnerValidReport'
                - $ref: '#/components/schemas/CrateInvalidReport'
                title: Response Build Runner V1 Build Runner Post
                discriminator:
                  propertyName: is_valid
                  mapping:
                    'True': '#/components/schemas/BuildRunnerValidReport'
                    'False': '#/components/schemas/CrateInvalidReport'
        '401':
          description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
            or `AUTH_MODE=jwt`).
          headers:
            WWW-Authenticate:
              description: Authentication challenge — always `Bearer`.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a malformed body, a field failing validation, or an `input`-domain
            pipelex error (a `.mthds` bundle the caller must fix). 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 `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML
            override, a backend fault), or an unclassified error sanitized by the catch-all handler. Report the `request_id`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '404':
          description: '`MethodPackageNotFoundError` — the `method_ref` repository was fetched, but no package in it matches
            the requested address by manifest identity. The message lists the packages the repository does contain.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '501':
          description: '`MethodRefNotSupported` — the request selected its closure by a **registry-form** `method_ref` (not
            a `github.com/...` address), and no server-side method registry resolves those yet. Use an address-form reference
            or submit inline `files[]` instead.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
  /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 `api.exception_handlers`

        turns them into an RFC 7807 problem response.'
      operationId: execute_v1_execute_post
      requestBody:
        content:
          application/json:
            schema:
              $defs:
                StuffContentAbstract:
                  properties: {}
                  type: object
                  title: StuffContentAbstract
                WorkingMemoryAbstract_Any_:
                  properties:
                    root:
                      additionalProperties: true
                      type: object
                      title: Root
                    aliases:
                      additionalProperties:
                        type: string
                      type: object
                      title: Aliases
                  additionalProperties: false
                  type: object
                  title: WorkingMemoryAbstract[Any]
              properties:
                pipe_code:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Pipe Code
                mthds_contents:
                  anyOf:
                  - items:
                      type: string
                    type: array
                  - type: 'null'
                  title: Mthds Contents
                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
                  - $ref: '#/$defs/WorkingMemoryAbstract_Any_'
                  - 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 whole method
                    bundle (`.mthds` + `.py` + `structures/*.py` + `requirements.txt`), materialized into a temporary library
                    directory before the run so custom PipeFunc Python travels with the method. Mutually exclusive with `files`.
                    Custom `.py` is only honored on a sandbox-hosted deployment.
                files:
                  anyOf:
                  - additionalProperties:
                      type: string
                    type: object
                  - type: 'null'
                  title: Files
                  description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the method bundle as a `{relative_path:
                    text}` map (the unzipped equivalent of `bundle_b64`). Mutually exclusive with `bundle_b64`.'
                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/documents@v0.1.0`)
                    — 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.'
                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 403. 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.
              additionalProperties: true
              type: object
              title: PipelexApiExecuteRequest
              description: 'Documented body of `POST /execute` — the protocol''s `RunRequest` plus THIS server''s `orchestration_mode`
                extension.


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

                `Request` (kajson decoding), so FastAPI cannot infer the body type; this model documents the

                per-request `orchestration_mode` override the route actually honors (parsed by `PipelineApiExtras`).'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelexApiExecuteResponse'
        '401':
          description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
            or `AUTH_MODE=jwt`).
          headers:
            WWW-Authenticate:
              description: Authentication challenge — always `Bearer`.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a malformed body, a field failing validation, or an `input`-domain
            pipelex error (a `.mthds` bundle the caller must fix). 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 `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML
            override, a backend fault), or an unclassified error sanitized by the catch-all handler. Report the `request_id`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '403':
          description: 'A deployment-policy refusal: `OrchestrationModeOverrideForbidden` — the request asked for an `orchestration_mode`
            this deployment does not allow overriding per request (`allow_request_orchestration_mode_override = false`); `CustomCodeRequiresSandbox`
            — the method (a bundle, or a fetched `method_ref` package) ships custom Python and this deployment is not sandbox-hosted;
            or `MethodStructuresRefusedError` — a fetched package declares in-process Python structure classes, which hosted
            execution always refuses (express the types as MTHDS concepts instead).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '404':
          description: '`MethodPackageNotFoundError` — the `method_ref` repository was fetched, but no package in it matches
            the requested address by manifest identity. The message lists the packages the repository does contain.'
          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'
      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 `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 `400`

        (`StartRequiresAsyncOrchestration`) — 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:
                StuffContentAbstract:
                  properties: {}
                  type: object
                  title: StuffContentAbstract
                WorkingMemoryAbstract_Any_:
                  properties:
                    root:
                      additionalProperties: true
                      type: object
                      title: Root
                    aliases:
                      additionalProperties:
                        type: string
                      type: object
                      title: Aliases
                  additionalProperties: false
                  type: object
                  title: WorkingMemoryAbstract[Any]
              properties:
                pipe_code:
                  anyOf:
                  - type: string
                  - type: 'null'
                  title: Pipe Code
                mthds_contents:
                  anyOf:
                  - items:
                      type: string
                    type: array
                  - type: 'null'
                  title: Mthds Contents
                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
                  - $ref: '#/$defs/WorkingMemoryAbstract_Any_'
                  - 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 whole method
                    bundle (`.mthds` + `.py` + `structures/*.py` + `requirements.txt`), materialized into a temporary library
                    directory before the run so custom PipeFunc Python travels with the method. Mutually exclusive with `files`.
                    Custom `.py` is only honored on a sandbox-hosted deployment.
                files:
                  anyOf:
                  - additionalProperties:
                      type: string
                    type: object
                  - type: 'null'
                  title: Files
                  description: 'PIPELEX-API EXTENSION (not part of the MTHDS Protocol) — the method bundle as a `{relative_path:
                    text}` map (the unzipped equivalent of `bundle_b64`). Mutually exclusive with `bundle_b64`.'
                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/documents@v0.1.0`)
                    — 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.'
                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 the RunResult to each URL, HMAC-SHA256-signed via the X-Completion-Signature
                    header. 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 403. 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.
              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: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
            or `AUTH_MODE=jwt`).
          headers:
            WWW-Authenticate:
              description: Authentication challenge — always `Bearer`.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a malformed body, a field failing validation, or an `input`-domain
            pipelex error (a `.mthds` bundle the caller must fix). 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 `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML
            override, a backend fault), or an unclassified error sanitized by the catch-all handler. Report the `request_id`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '400':
          description: '`StartRequiresAsyncOrchestration` — this deployment''s orchestrator is blocking-only and cannot honor
            fire-and-forget delivery. Use `POST /execute` instead.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '403':
          description: 'A deployment-policy refusal: `OrchestrationModeOverrideForbidden` — the request asked for an `orchestration_mode`
            this deployment does not allow overriding per request (`allow_request_orchestration_mode_override = false`); `CustomCodeRequiresSandbox`
            — the method (a bundle, or a fetched `method_ref` package) ships custom Python and this deployment is not sandbox-hosted;
            or `MethodStructuresRefusedError` — a fetched package declares in-process Python structure classes, which hosted
            execution always refuses (express the types as MTHDS concepts instead).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '404':
          description: '`MethodPackageNotFoundError` — the `method_ref` repository was fetched, but no package in it matches
            the requested address by manifest identity. The message lists the packages the repository does contain.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '409':
          description: '`PipelineManagerAlreadyExistsError` — 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: '`AsyncExecutionNotEnabledError` — this deployment does not provide async pipeline execution. Permanent
            under the current deployment; do not retry.'
          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`). A bundle that declares no `main_pipe`\
        \ validates fine and carries\n  `graph_spec=null`. 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 — `validation_errors[]`\n  (the structured per-error diagnostics, built by pipelex's one shared builder, incl.\
        \ the\n  `dry_run` residual item) + `message`, with the structural artifacts absent. The runner\n  returns this as\
        \ a value (`ErrorReport` with `validation_errors`) 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. Returned `ErrorReport`s without validation diagnostics\
        \ are backend/config/runtime\n  faults and keep the global RFC 7807 problem response path.\n- **No verdict (non-2xx):**\
        \ a malformed request body, an `mthds_sources` length mismatch, or\n  both/neither of `mthds_contents` / `method_ref`\
        \ is a request-shape **422**; a forbidden\n  `orchestration_mode` override is a **403**; a host-wiring programmer\
        \ error or a genuine\n  orchestrator fault is a **5xx**; auth is **401/403**. A `method_ref` **resolution failure**\n\
        \  is also a no-verdict condition — never an `is_valid: false`: a malformed reference or a\n  failed fetch is a **422**,\
        \ no matching package in the repository a **404**, and the\n  custom-Python policy (the sandbox gate, the structures\
        \ refusal) a **403**, each with the\n  originating error class as `error_type`. All are RFC 7807 `application/problem+json`\n\
        \  rendered by the global handler in `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: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
            or `AUTH_MODE=jwt`).
          headers:
            WWW-Authenticate:
              description: Authentication challenge — always `Bearer`.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a malformed body, a field failing validation, or an `input`-domain
            pipelex error (a `.mthds` bundle the caller must fix). 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 `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML
            override, a backend fault), or an unclassified error sanitized by the catch-all handler. Report the `request_id`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '403':
          description: 'A deployment-policy refusal: `OrchestrationModeOverrideForbidden` — the request asked for an `orchestration_mode`
            this deployment does not allow overriding per request (`allow_request_orchestration_mode_override = false`); `CustomCodeRequiresSandbox`
            — the method (a bundle, or a fetched `method_ref` package) ships custom Python and this deployment is not sandbox-hosted;
            or `MethodStructuresRefusedError` — a fetched package declares in-process Python structure classes, which hosted
            execution always refuses (express the types as MTHDS concepts instead).'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '404':
          description: '`MethodPackageNotFoundError` — the `method_ref` repository was fetched, but no package in it matches
            the requested address by manifest identity. The message lists the packages the repository does contain.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
      x-mthds-protocol: true
  /v1/resolve:
    post:
      tags:
      - resolve
      summary: Resolve Mthds
      description: "Resolve a library closure into its normalized crate (Pipelex API extension).\n\nResolution is a first-class\
        \ language operation alongside validation: assemble the closure from\nthe inline `files[]`, load + statically validate\
        \ the library, and emit the **normalized\nlibrary crate** (fully qualified refs, refinement flattened, natives materialized,\
        \ fingerprint\nset) — the artifact shape the MTHDS standard specifies as the Library Crate Format. It runs no\ndry-run\
        \ sweep — runnability 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 — `validation_errors[]` from pipelex's one shared builder.\n\
        - **No verdict (non-2xx):** a malformed request body (neither/both closure selectors, an\n  over-limit file) is a\
        \ request-shape 422; `method_ref` is a 501 until server-side method\n  registry resolution exists; auth is 401/403;\
        \ server fault is 5xx. All RFC 7807\n  `application/problem+json` via the global handlers."
      operationId: resolve_mthds_v1_resolve_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MthdsFilesRequest'
        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: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
            or `AUTH_MODE=jwt`).
          headers:
            WWW-Authenticate:
              description: Authentication challenge — always `Bearer`.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a malformed body, a field failing validation, or an `input`-domain
            pipelex error (a `.mthds` bundle the caller must fix). 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 `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML
            override, a backend fault), or an unclassified error sanitized by the catch-all handler. Report the `request_id`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '404':
          description: '`MethodPackageNotFoundError` — the `method_ref` repository was fetched, but no package in it matches
            the requested address by manifest identity. The message lists the packages the repository does contain.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '501':
          description: '`MethodRefNotSupported` — the request selected its closure by a **registry-form** `method_ref` (not
            a `github.com/...` address), and no server-side method registry resolves those yet. Use an address-form reference
            or submit inline `files[]` instead.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
  /v1/codegen:
    post:
      tags:
      - codegen
      summary: Codegen Mthds
      description: "Generate typed artifacts from a library closure (Pipelex API extension).\n\nResolves the closure 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 — `validation_errors[]` from pipelex's one shared builder; 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 closure selector is a request-shape 422 problem+json;\n  `method_ref` is a 501 until server-side method\
        \ registry resolution exists; auth is 401/403;\n  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: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
            or `AUTH_MODE=jwt`).
          headers:
            WWW-Authenticate:
              description: Authentication challenge — always `Bearer`.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a malformed body, a field failing validation, or an `input`-domain
            pipelex error (a `.mthds` bundle the caller must fix). 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 `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML
            override, a backend fault), or an unclassified error sanitized by the catch-all handler. Report the `request_id`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '404':
          description: '`MethodPackageNotFoundError` — the `method_ref` repository was fetched, but no package in it matches
            the requested address by manifest identity. The message lists the packages the repository does contain.'
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '501':
          description: '`MethodRefNotSupported` — the request selected its closure by a **registry-form** `method_ref` (not
            a `github.com/...` address), and no server-side method registry resolves those yet. Use an address-form reference
            or submit inline `files[]` instead.'
          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: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
            or `AUTH_MODE=jwt`).
          headers:
            WWW-Authenticate:
              description: Authentication challenge — always `Bearer`.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a malformed body, a field failing validation, or an `input`-domain
            pipelex error (a `.mthds` bundle the caller must fix). 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 `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML
            override, a backend fault), or an unclassified error sanitized by the catch-all handler. 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 RFC 7807 422.'
      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: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
            or `AUTH_MODE=jwt`).
          headers:
            WWW-Authenticate:
              description: Authentication challenge — always `Bearer`.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a malformed body, a field failing validation, or an `input`-domain
            pipelex error (a `.mthds` bundle the caller must fix). 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 `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML
            override, a backend fault), or an unclassified error sanitized by the catch-all handler. 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

        (arity, `ValidationError`) and unknown categories (`InvalidModelCategory`) are

        both 422s (RFC 7807).'
      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. Single value (protocol arity).'
          title: Type
        description: 'Filter by model category: llm, extract, img_gen, search. Single value (protocol arity).'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelexModelDeck'
        '401':
          description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
            or `AUTH_MODE=jwt`).
          headers:
            WWW-Authenticate:
              description: Authentication challenge — always `Bearer`.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a malformed body, a field failing validation, or an `input`-domain
            pipelex error (a `.mthds` bundle the caller must fix). 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 `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML
            override, a backend fault), or an unclassified error sanitized by the catch-all handler. Report the `request_id`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
      x-mthds-protocol: true
  /v1/build/concept:
    post:
      tags:
      - agent
      summary: Build Concept
      description: 'Convert a JSON concept spec to TOML format.


        A malformed spec surfaces as a Pydantic `ValidationError` — an API-owned

        422. Pipelex domain failures propagate untouched to the global

        `PipelexError` handler in `api.exception_handlers`.


        Known gap (tracked as `pipelex-changes.md` item #11): a non-dict `structure`

        (`{"structure": "string"}`) or a `structure` field that is neither a string

        nor a dict (`{"structure": {"f": 42}}`) makes `parse_concept_spec` leak a

        bare `AttributeError`/`TypeError` instead of a typed error, so the request

        surfaces as an opaque 500. We deliberately don''t catch those here — they

        are also the signal of a real pipelex programming bug, and a broad route

        catch would mask both. The fix is upstream shape validation in

        `parse_concept_spec`.'
      operationId: build_concept_v1_build_concept_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildConceptRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildConceptResponse'
        '401':
          description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
            or `AUTH_MODE=jwt`).
          headers:
            WWW-Authenticate:
              description: Authentication challenge — always `Bearer`.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a malformed body, a field failing validation, or an `input`-domain
            pipelex error (a `.mthds` bundle the caller must fix). 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 `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML
            override, a backend fault), or an unclassified error sanitized by the catch-all handler. Report the `request_id`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
  /v1/build/pipe-spec:
    post:
      tags:
      - agent
      summary: Build Pipe Spec
      description: 'Convert a JSON pipe spec to TOML format.


        Two caller-mistake paths surface as a 422 here: a `ValidationError` from

        Pydantic when the spec shape doesn''t match the chosen pipe type, and a

        `ValueError` from `parse_pipe_spec` when `pipe_type` is not one of the

        known pipe types (documented in `parse_pipe_spec`''s docstring; raised at

        exactly one site). Pipelex domain failures propagate untouched to the

        global `PipelexError` handler in `api.exception_handlers`.'
      operationId: build_pipe_spec_v1_build_pipe_spec_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BuildPipeSpecRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuildPipeSpecResponse'
        '401':
          description: Missing or invalid bearer token. Only reachable when the deployment enables auth (`AUTH_MODE=api_key`
            or `AUTH_MODE=jwt`).
          headers:
            WWW-Authenticate:
              description: Authentication challenge — always `Bearer`.
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '413':
          description: Request body exceeds the deployment's size limit (`MAX_REQUEST_BODY_MIB`, 100 MiB by default).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
        '422':
          description: 'The request could not be processed: a malformed body, a field failing validation, or an `input`-domain
            pipelex error (a `.mthds` bundle the caller must fix). 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 `config`-domain or `runtime`-domain failure the caller cannot fix (a missing env var, a bad TOML
            override, a backend fault), or an unclassified error sanitized by the catch-all handler. Report the `request_id`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDocument'
  /:
    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).\n- SKIPPED:\
        \ the producing pipe was lifted (skipped) because one of its plain inputs was absent.\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.'
    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
    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.'
    BuildConceptRequest:
      properties:
        spec:
          additionalProperties: true
          type: object
          title: Spec
          description: JSON concept specification.
      type: object
      required:
      - spec
      title: BuildConceptRequest
    BuildConceptResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the operation was successful
          default: true
        concept_code:
          type: string
          title: Concept Code
          description: The concept code that was generated
        toml:
          type: string
          title: Toml
          description: Generated TOML content for the concept
      type: object
      required:
      - concept_code
      - toml
      title: BuildConceptResponse
    BuildInputsRequest:
      properties:
        files:
          anyOf:
          - items:
              $ref: '#/components/schemas/MthdsFileItem'
            type: array
            maxItems: 16
            minItems: 1
          - type: 'null'
          title: Files
          description: Inline MTHDS bundles forming the closure to resolve (content-passing — no server-side path reads).
        method_ref:
          anyOf:
          - type: string
            maxLength: 512
            minLength: 1
          - type: 'null'
          title: Method Ref
          description: Reference to a published method, resolving to its package's `.mthds` files. Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`)
            is fetched and resolved server-side; the registry form stays reserved (501 until a method registry exists).
        pipe_ref:
          anyOf:
          - type: string
            maxLength: 256
            minLength: 1
          - type: 'null'
          title: Pipe Ref
          description: Qualified pipe ref (`domain.pipe_code`) to project. Optional — defaults to the fetched package manifest's
            `main_pipe` on a `method_ref` request, else to the closure's declared `main_pipe`; a closure declaring none, or
            several, with no manifest `main_pipe` to settle it, requires it explicitly.
        format:
          $ref: '#/components/schemas/InputsTemplateFormat'
          description: Template encoding. `json` returns the parsed template in `inputs`; `toml` returns the raw text in `inputs_toml`.
          default: json
        explicit:
          type: boolean
          title: Explicit
          description: When true, emit the ceremonial `{concept, content}` envelope for every input. Defaults to false — the
            light, signature-driven shape that smart inputs accepts (a bare string for a Text input, and so on).
          default: false
      type: object
      title: BuildInputsRequest
      description: 'The inputs-template request: the shared closure + pipe selectors, plus the two rendering axes.


        Both axes mirror `pipelex codegen inputs` exactly — `--format` and `--explicit` — and every

        combination of them is served, as on the CLI.'
    BuildInputsValidReport:
      properties:
        is_valid:
          type: boolean
          const: true
          title: Is Valid
          default: true
        pipe_ref:
          type: string
          title: Pipe Ref
          description: The qualified pipe the template was generated for — the resolved selector.
        requested_pipe_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Requested Pipe Ref
          description: The `pipe_ref` as submitted. Absent when it was omitted and defaulted — to the fetched package manifest's
            `main_pipe` on a `method_ref` request, else to the closure's declared `main_pipe`.
        format:
          $ref: '#/components/schemas/InputsTemplateFormat'
          description: The template encoding (echo of the request).
        explicit:
          type: boolean
          title: Explicit
          description: Whether the ceremonial envelope shape was emitted (echo of the request).
        inputs:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Inputs
          description: The parsed inputs template — present exactly when `format` is `json`.
        inputs_toml:
          anyOf:
          - type: string
          - type: 'null'
          title: Inputs Toml
          description: The inputs template as TOML text — present exactly when `format` is `toml`.
        message:
          type: string
          title: Message
          description: Status message
          default: Inputs template generated successfully
      type: object
      required:
      - pipe_ref
      - format
      - explicit
      title: BuildInputsValidReport
      description: 'The 200 **valid** arm: the example inputs template for the requested pipe.


        The template rides **one of two fields, chosen by `format`** — `inputs` (parsed object) for

        `json`, `inputs_toml` (raw text) for `toml`. TOML cannot be carried as a parsed object without

        losing what makes it worth asking for (its concept comments and key order), and the JSON case

        must stay a real object, since that is what the deploy dialog and the SDKs consume. So the two

        are separate, honestly-typed fields, and the unused one is omitted from the body entirely.


        A pipe that declares no inputs is a *valid* verdict, not an error (the CLI likewise exits 0):

        the template is simply empty, and `message` says so.'
    BuildOutputRequest:
      properties:
        files:
          anyOf:
          - items:
              $ref: '#/components/schemas/MthdsFileItem'
            type: array
            maxItems: 16
            minItems: 1
          - type: 'null'
          title: Files
          description: Inline MTHDS bundles forming the closure to resolve (content-passing — no server-side path reads).
        method_ref:
          anyOf:
          - type: string
            maxLength: 512
            minLength: 1
          - type: 'null'
          title: Method Ref
          description: Reference to a published method, resolving to its package's `.mthds` files. Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`)
            is fetched and resolved server-side; the registry form stays reserved (501 until a method registry exists).
        pipe_ref:
          anyOf:
          - type: string
            maxLength: 256
            minLength: 1
          - type: 'null'
          title: Pipe Ref
          description: Qualified pipe ref (`domain.pipe_code`) to project. Optional — defaults to the fetched package manifest's
            `main_pipe` on a `method_ref` request, else to the closure's declared `main_pipe`; a closure declaring none, or
            several, with no manifest `main_pipe` to settle it, requires it explicitly.
        format:
          $ref: '#/components/schemas/ConceptRepresentationFormat'
          description: Representation to render. `schema` (JSON Schema) and `json` (example value) return a parsed object
            in `output`; `python` returns Python source in `output_python`.
          default: schema
      type: object
      title: BuildOutputRequest
      description: 'The output-representation request: the shared closure + pipe selectors, plus the format axis.'
    BuildOutputValidReport:
      properties:
        is_valid:
          type: boolean
          const: true
          title: Is Valid
          default: true
        pipe_ref:
          type: string
          title: Pipe Ref
          description: The qualified pipe the representation was generated for — the resolved selector.
        requested_pipe_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Requested Pipe Ref
          description: The `pipe_ref` as submitted. Absent when it was omitted and defaulted — to the fetched package manifest's
            `main_pipe` on a `method_ref` request, else to the closure's declared `main_pipe`.
        format:
          $ref: '#/components/schemas/ConceptRepresentationFormat'
          description: The representation format (echo of the request).
        output:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Output
          description: The parsed output representation — present exactly when `format` is `schema` or `json`.
        output_python:
          anyOf:
          - type: string
          - type: 'null'
          title: Output Python
          description: The output representation as Python source — present exactly when `format` is `python`.
        message:
          type: string
          title: Message
          description: Status message
          default: Output representation generated successfully
      type: object
      required:
      - pipe_ref
      - format
      title: BuildOutputValidReport
      description: 'The 200 **valid** arm: the example output representation for the requested pipe.


        The representation rides **one of two fields, chosen by `format`**, for the same reason

        `/build/inputs` splits `inputs` / `inputs_toml`: `schema` and `json` are objects, `python` is

        source text. (Before this split the route parsed *every* format as JSON, so `format=python` was a

        hard 500 — it fed Python source to `json.loads`.)'
    BuildPipeSpecRequest:
      properties:
        pipe_type:
          type: string
          maxLength: 128
          minLength: 1
          title: Pipe Type
          description: The pipe type (e.g. PipeLLM, PipeSequence, etc.).
        spec:
          additionalProperties: true
          type: object
          title: Spec
          description: JSON pipe specification.
      type: object
      required:
      - pipe_type
      - spec
      title: BuildPipeSpecRequest
    BuildPipeSpecResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the operation was successful
          default: true
        pipe_code:
          type: string
          title: Pipe Code
          description: The pipe code that was generated
        pipe_type:
          type: string
          title: Pipe Type
          description: The pipe type
        toml:
          type: string
          title: Toml
          description: Generated TOML content for the pipe
      type: object
      required:
      - pipe_code
      - pipe_type
      - toml
      title: BuildPipeSpecResponse
    BuildRunnerRequest:
      properties:
        files:
          anyOf:
          - items:
              $ref: '#/components/schemas/MthdsFileItem'
            type: array
            maxItems: 16
            minItems: 1
          - type: 'null'
          title: Files
          description: Inline MTHDS bundles forming the closure to resolve (content-passing — no server-side path reads).
        method_ref:
          anyOf:
          - type: string
            maxLength: 512
            minLength: 1
          - type: 'null'
          title: Method Ref
          description: Reference to a published method, resolving to its package's `.mthds` files. Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`)
            is fetched and resolved server-side; the registry form stays reserved (501 until a method registry exists).
        pipe_ref:
          anyOf:
          - type: string
            maxLength: 256
            minLength: 1
          - type: 'null'
          title: Pipe Ref
          description: Qualified pipe ref (`domain.pipe_code`) to project. Optional — defaults to the fetched package manifest's
            `main_pipe` on a `method_ref` request, else to the closure's declared `main_pipe`; a closure declaring none, or
            several, with no manifest `main_pipe` to settle it, requires it explicitly.
        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
      type: object
      title: BuildRunnerRequest
      description: 'The runner-script request: the shared closure + pipe selectors, plus the sweep''s `allow_signatures`.


        Alone among the `/build/*` projections this route keeps `allow_signatures`, because alone among

        them it still runs the dry-run sweep — the flag only ever parameterized that sweep.'
    BuildRunnerValidReport:
      properties:
        is_valid:
          type: boolean
          const: true
          title: Is Valid
          default: true
        pipe_ref:
          type: string
          title: Pipe Ref
          description: The qualified pipe the runner was generated for — the resolved selector.
        requested_pipe_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Requested Pipe Ref
          description: The `pipe_ref` as submitted. Absent when it was omitted and defaulted — to the fetched package manifest's
            `main_pipe` on a `method_ref` request, else to the closure's declared `main_pipe`.
        python_code:
          type: string
          title: Python Code
          description: Generated Python script for running the pipeline, imports spelled with the emitted class names.
        structures:
          $ref: '#/components/schemas/RunnerStructures'
          description: The typed-structures projection the script imports from.
        message:
          type: string
          title: Message
          description: Status message
          default: Runner code generated successfully
      type: object
      required:
      - pipe_ref
      - python_code
      - structures
      title: BuildRunnerValidReport
      description: 'The 200 **valid** arm: the runner script plus the structures projection it imports from.'
    CodegenRequest:
      properties:
        files:
          anyOf:
          - items:
              $ref: '#/components/schemas/MthdsFileItem'
            type: array
            maxItems: 16
            minItems: 1
          - type: 'null'
          title: Files
          description: Inline MTHDS bundles forming the closure to resolve (content-passing — no server-side path reads).
        method_ref:
          anyOf:
          - type: string
            maxLength: 512
            minLength: 1
          - type: 'null'
          title: Method Ref
          description: Reference to a published method, resolving to its package's `.mthds` files. Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`)
            is fetched and resolved server-side; the registry form stays reserved (501 until a method registry exists).
        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 shared closure 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; they ride

        `POST /build/inputs` instead 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
    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
    ConceptRepresentationFormat:
      type: string
      enum:
      - json
      - python
      - schema
      title: ConceptRepresentationFormat
      description: Output format for concept representations.
    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
        validation_errors:
          items:
            $ref: '#/components/schemas/ValidationErrorItem'
          type: array
          title: Validation Errors
          description: Per-error diagnostics, built by pipelex's one shared builder — non-empty on every invalid verdict.
        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` and `/codegen` — 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 structured `ValidationErrorItem`s the

        local CLI and `/validate` emit 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`.
    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.
    EnsureTableOp:
      properties:
        table_path:
          items:
            type: string
          type: array
          minItems: 1
          title: Table Path
        kind:
          type: string
          const: ensure_table
          title: Kind
          default: ensure_table
      additionalProperties: false
      type: object
      required:
      - table_path
      title: EnsureTableOp
      description: 'Create the addressed table when it is absent, leaving an existing one untouched.


        Here ``table_path`` addresses the table to create, not its parent, so it cannot be empty:

        the document root always exists.'
    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.'
    ErrorSpec:
      properties:
        error_type:
          type: string
          title: Error Type
        message:
          type: string
          title: Message
        stack:
          anyOf:
          - type: string
          - type: 'null'
          title: Stack
      additionalProperties: false
      type: object
      required:
      - error_type
      - message
      title: ErrorSpec
      description: 'Error information for failed nodes.


        Stack traces are automatically truncated to MAX_STACK_LENGTH.'
    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
    FixSafety:
      type: string
      enum:
      - safe
      - unsafe
      title: FixSafety
      description: Whether a fix is safe to auto-apply (SAFE) or requires explicit opt-in (UNSAFE).
    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.'
    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`.
    HintLintErrorType:
      type: string
      enum:
      - hint_unknown_key
      - hint_unknown_intent
      - hint_inapplicable_intent
      title: HintLintErrorType
      description: 'Advisory intent-hints lint findings (spec: intent-hints.md).


        Every member is advisory-only: it rides the validation report''s ``warnings`` array and never

        makes a verdict invalid — hints are non-normative, and well-formed unknown content is

        preserved, only warned about. A separate enum rather than new ``PipeValidationErrorType``

        members because hints attach to concepts and structure fields too, so the pipe enum is the

        wrong home.'
    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
        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).'
    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.'
    InputsTemplateFormat:
      type: string
      enum:
      - json
      - toml
      title: InputsTemplateFormat
      description: Serialization format for a generated inputs template.
    InvalidReport:
      properties:
        is_valid:
          type: boolean
          const: false
          title: Is Valid
          default: false
        validation_errors:
          items:
            $ref: '#/components/schemas/ValidationErrorItem'
          type: array
          title: Validation Errors
          description: Per-error diagnostics, built by pipelex's one shared builder — non-empty on every invalid verdict.
        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 `validation_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

        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).'
    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
      type: object
      required:
      - address
      - commit_sha
      title: MethodProvenance
      description: 'What a fetched-method run must record: address, tag, and the resolved commit SHA.'
    ModelCategory:
      type: string
      enum:
      - llm
      - extract
      - img_gen
      - search
      title: ModelCategory
      description: Model categories accepted by the protocol's `GET /models?type=` filter.
    ModelInfo:
      properties:
        name:
          type: string
          title: Name
        type:
          anyOf:
          - $ref: '#/components/schemas/ModelCategory'
          - type: 'null'
      additionalProperties: true
      type: object
      required:
      - name
      title: ModelInfo
      description: One entry of the model deck (`ModelDeck.models[]`) — base fields + extensions.
    ModelReference:
      type: string
    ModelReferenceKind:
      type: string
      enum:
      - preset
      - alias
      - waterfall
      - handle
      title: ModelReferenceKind
      description: The kind of model reference.
    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.'
    MthdsFileItem:
      properties:
        content:
          type: string
          title: Content
          description: MTHDS bundle content.
        source:
          anyOf:
          - type: string
            maxLength: 1024
          - type: 'null'
          title: Source
          description: Optional logical source for this bundle (e.g. its path relative to the submitted directory). Threaded
            onto the blueprint so server-side diagnostics carry a `source` pointing at the owning file.
      type: object
      required:
      - content
      title: MthdsFileItem
      description: 'One inline MTHDS bundle: its content plus an optional logical source for diagnostics.


        The `files[]` envelope pairs each content with its source in one entry (the shape the codegen

        spec pins for the resolve/codegen routes), unlike the legacy parallel

        `mthds_contents[]`/`mthds_sources[]` lists on `/validate`.'
    MthdsFilesRequest:
      properties:
        files:
          anyOf:
          - items:
              $ref: '#/components/schemas/MthdsFileItem'
            type: array
            maxItems: 16
            minItems: 1
          - type: 'null'
          title: Files
          description: Inline MTHDS bundles forming the closure to resolve (content-passing — no server-side path reads).
        method_ref:
          anyOf:
          - type: string
            maxLength: 512
            minLength: 1
          - type: 'null'
          title: Method Ref
          description: Reference to a published method, resolving to its package's `.mthds` files. Address form (`github.com/<owner>/<repo>[/<selector>][@<tag>]`)
            is fetched and resolved server-side; the registry form stays reserved (501 until a method registry exists).
      type: object
      title: MthdsFilesRequest
      description: 'Shared closure selector for the resolve/codegen routes: inline `files[]` XOR a `method_ref`.


        Exactly one of the two must be provided (spec''d envelope) — both or neither is a request-shape

        422. An **address-form** `method_ref` (`github.com/<owner>/<repo>[/<selector>][@<tag>]`) is

        resolved by this server: the repository is fetched at the tag, the package is located by

        manifest identity, and its `.mthds` files feed the closure with their real relative paths as

        per-file sources. The **registry form** (any non-address reference) stays reserved and answers

        501 until server-side method-registry resolution exists.'
    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
      title: NodeKind
      description: Types of nodes in the execution graph.
    NodeSpec:
      properties:
        id:
          type: string
          title: Id
        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/ErrorSpec'
          - type: 'null'
        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
    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
    PipeFactoryErrorType:
      type: string
      enum:
      - unknown_concept
      - unknown_factory_error
      title: PipeFactoryErrorType
      description: 'Types of pipe factory errors.


        These error types are raised during pipe creation from blueprints.'
    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
          title: Function Name
          description: The name of the function to call.
      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"`).'
    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, dotted names included.

        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"`).'
    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:
            $ref: '#/components/schemas/SubPipeBlueprint'
          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
      - PipeBatch
      - PipeCondition
      - PipeParallel
      - PipeSequence
      title: PipeType
    PipeValidationErrorType:
      type: string
      enum:
      - missing_input_variable
      - extraneous_input_variable
      - input_stuff_spec_mismatch
      - inadequate_output_concept
      - inadequate_output_multiplicity
      - circular_dependency_error
      - llm_output_cannot_be_image
      - invalid_pipe_code_syntax
      - unknown_pipe_type
      - missing_pipe_type
      - batch_item_name_collision
      - optional_marker_invalid
      - optional_not_handled
      - optional_output_required
      - optional_input_unguarded
      - optional_branch_required_field
      - optional_force_redundant
      - input_presence_vacuous
      - native_concept_redeclaration
      - unresolved_concept
      - unresolved_pipe_dependency
      - unknown_validation_error
      title: PipeValidationErrorType
      description: 'Types of pipe validation errors.


        These error types are raised during pipe validation from Pipe/Concept classes.'
    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
        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), and the commit SHA that was actually fetched.
            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
        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), and the commit SHA that was actually fetched.
            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/PipeStructureBlueprint'
              - $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'
                  PipeExtract: '#/components/schemas/PipeExtractBlueprint'
                  PipeFunc: '#/components/schemas/PipeFuncBlueprint'
                  PipeImgGen: '#/components/schemas/PipeImgGenBlueprint'
                  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.'
    PipelexVersionInfo:
      properties:
        protocol_version:
          type: string
          title: Protocol Version
        runner_version:
          anyOf:
          - type: string
          - type: 'null'
          title: Runner Version
        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.'
    ProblemDocument:
      properties:
        type:
          type: string
          title: Type
          description: 'Stable URI for the error class: `https://docs.pipelex.com/latest/errors/<kebab-class-name>/`.'
        title:
          type: string
          title: Title
          description: Short, human-readable summary of the error class.
        status:
          type: integer
          title: Status
          description: HTTP status code, repeated in the body per RFC 7807.
        detail:
          type: string
          title: Detail
          description: Human-readable explanation of this specific failure. Redacted under `ERROR_DISCLOSURE=strict`.
        instance:
          anyOf:
          - type: string
          - type: 'null'
          title: Instance
          description: Path of the request that failed.
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
          description: Correlation id, echoed in the `X-Request-ID` response header.
        error_type:
          type: string
          title: Error Type
          description: Stable class name of the originating error (e.g. `ValidateBundleError`, `Unauthenticated`).
        error_domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Domain
          description: '`input` (caller can fix it → 422), `config` or `runtime` (deployment must fix it → 500). Absent for
            domain-less errors.'
        retryable:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Retryable
          description: Whether retrying the same request can plausibly succeed. Always present on API-authored errors; on
            pipelex errors only when the originating error classifies it.
        error_category:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Category
          description: Finer classification, when the originating error provides one (inference errors).
        user_action:
          anyOf:
          - $ref: '#/components/schemas/UserAction'
          - type: 'null'
          description: Structured suggestion of what the caller should do next, when available.
        model:
          anyOf:
          - type: string
          - type: 'null'
          title: Model
          description: Inference model that failed. Stripped under `ERROR_DISCLOSURE=strict`.
        provider:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider
          description: Inference provider that failed. Stripped under `ERROR_DISCLOSURE=strict`.
        provider_metadata:
          anyOf:
          - $ref: '#/components/schemas/ProviderErrorMetadata'
          - type: 'null'
          description: Upstream provider error metadata. Stripped (bar a curated slice) under `ERROR_DISCLOSURE=strict`.
        validation_errors:
          anyOf:
          - items:
              $ref: '#/components/schemas/ValidationErrorItem'
            type: array
          - type: 'null'
          title: Validation Errors
          description: Structured per-error diagnostics, carried by a `ValidateBundleError`. Each item may carry a `suggested_fix`.
            Retained under `ERROR_DISCLOSURE=strict` — it describes the caller's own bundle, not server internals. On `/validate`,
            `/resolve`, `/codegen` and `/build/*` an invalid bundle is a **200** verdict instead, so the items ride the response
            body there rather than a problem document.
      additionalProperties: true
      type: object
      required:
      - type
      - title
      - status
      - detail
      - error_type
      title: ProblemDocument
      description: 'An RFC 7807 `application/problem+json` error body — the shape of every failure response.


        Standard RFC 7807 members (`type`, `title`, `status`, `detail`, `instance`)

        plus the extension members pipelex''s classification adds. Only `type`,

        `title`, `status`, `detail`, and `error_type` are always present: the rest

        ride along when the originating error populates them, so a consumer must

        treat them as optional. `extra="allow"` mirrors RFC 7807''s open-ended

        extension-member rule.'
    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.'
    ProviderErrorMetadata:
      properties:
        provider:
          $ref: '#/components/schemas/ProviderName'
        sdk_exception_type:
          type: string
          title: Sdk Exception Type
        message:
          type: string
          title: Message
          default: ''
        status_code:
          anyOf:
          - type: integer
          - type: 'null'
          title: Status Code
        request_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Request Id
        retry_after_seconds:
          anyOf:
          - type: number
          - type: 'null'
          title: Retry After Seconds
        provider_error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Error Code
      type: object
      required:
      - provider
      - sdk_exception_type
      title: ProviderErrorMetadata
      description: 'Structured SDK metadata attached to inference errors.


        Carries information downstream consumers (retry, temporal, CLI) need

        without having to scrape it back from the exception chain.'
    ProviderName:
      type: string
      enum:
      - openai
      - anthropic
      - google
      - mistral
      - azure
      - bedrock
      - fal
      - huggingface
      - gateway
      - linkup
      - docling
      - pypdfium2
      title: ProviderName
      description: Identifies the inference provider an SDK error originated from.
    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.'
    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).
    RunnerStructures:
      properties:
        directory:
          type: string
          title: Directory
          description: Directory (relative to the runner script) to write the artifacts and lock into.
          default: structures
        artifacts:
          items:
            $ref: '#/components/schemas/GeneratedArtifact'
          type: array
          title: Artifacts
          description: The stamped generated files (paths relative to `directory`).
        lock:
          type: string
          title: Lock
          description: The lock content (TOML) tracking the artifact set — write verbatim inside `directory`.
        lock_filename:
          type: string
          title: Lock Filename
          description: Filename the lock content must be written as.
          default: codegen.lock
      type: object
      required:
      - lock
      title: RunnerStructures
      description: 'The typed-structures projection the runner script imports from (`from structures.structures import ...`).


        The same stamped `python-structures` artifacts + `codegen.lock` a local `pipelex build runner`

        scaffolds into `<output>/structures/` — write `artifacts` and the lock under `directory` and

        the returned `python_code` runs against them, with the offline `codegen check` passing there.'
    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.
    SetKeyOp:
      properties:
        table_path:
          items:
            type: string
          type: array
          title: Table Path
        kind:
          type: string
          const: set_key
          title: Kind
          default: set_key
        key:
          type: string
          title: Key
        value:
          anyOf:
          - type: string
          - type: integer
          - type: number
          - type: boolean
          - additionalProperties:
              anyOf:
              - type: string
              - type: integer
              - type: number
              - type: boolean
            type: object
          title: Value
      additionalProperties: false
      type: object
      required:
      - table_path
      - key
      - value
      title: SetKeyOp
      description: Write ``key = value`` in the addressed table, whatever it currently holds.
    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
    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:
          $ref: '#/components/schemas/Concept'
        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
    SuggestedFix:
      properties:
        fix_code:
          type: string
          title: Fix Code
        description:
          type: string
          title: Description
        safety:
          $ref: '#/components/schemas/FixSafety'
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        ops:
          items:
            oneOf:
            - $ref: '#/components/schemas/SetKeyOp'
            - $ref: '#/components/schemas/EnsureTableOp'
            - $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'
                ensure_table: '#/components/schemas/EnsureTableOp'
                move_key: '#/components/schemas/MoveKeyOp'
                remap_value: '#/components/schemas/RemapValueOp'
                rename_table_key: '#/components/schemas/RenameTableKeyOp'
                set_key: '#/components/schemas/SetKeyOp'
          type: array
          title: Ops
      additionalProperties: false
      type: object
      required:
      - fix_code
      - description
      - safety
      - ops
      title: SuggestedFix
      description: 'A deterministic fix for one validation error, ready for a style-preserving applier.


        ``fix_code`` is the kebab-case rule id (e.g. ``"match-sequence-output"``). ``source`` is

        the file the ops target, when known (multi-file libraries) — an applier must only apply

        ops to the file they target.'
    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.'
    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.'
    UserAction:
      properties:
        kind:
          $ref: '#/components/schemas/UserActionKind'
        detail:
          type: string
          title: Detail
      type: object
      required:
      - kind
      - detail
      title: UserAction
      description: 'Structured user-facing advice attached to an inference error.


        ``kind`` discriminates the type of action, ``detail`` is the free-form

        provider-specific advice (e.g. a billing URL, a retry hint).'
    UserActionKind:
      type: string
      enum:
      - wait_and_retry
      - check_billing
      - check_credentials
      - change_input
      - change_model
      - contact_support
      - unknown
      title: UserActionKind
      description: 'Discrete categories of advice we surface to the user/agent.


        Lets the CLI render consistent guidance and agent JSON stay typed across

        providers. The free-form ``detail`` string carries provider-specific text.'
    ValidReport:
      properties:
        is_valid:
          type: boolean
          const: true
          title: Is Valid
          default: true
        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
        graph_spec:
          anyOf:
          - $ref: '#/components/schemas/GraphSpec'
          - type: 'null'
        validated_pipes:
          items:
            $ref: '#/components/schemas/ValidatedPipeEntry'
          type: array
          title: Validated Pipes
        warnings:
          items:
            $ref: '#/components/schemas/ValidationErrorItem'
          type: array
          title: Warnings
        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 (echo of the request)
        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. On a `method_ref` request it is the fetched package manifest''s `main_pipe`
            (the package author''s declared entry pipe, qualified against the closure); otherwise, and when the manifest declares
            none, it is the closure''s primary blueprint''s `main_pipe` qualified by its domain. `null` when no entry pipe
            is determined: no blueprint declares `main_pipe`, or a manifest names a pipe the closure does not declare (or
            declares ambiguously), in which case a selector-less run by this address would fail to resolve it 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.


        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:
        mthds_contents:
          anyOf:
          - items:
              type: string
            type: array
            maxItems: 16
            minItems: 1
          - type: 'null'
          title: Mthds Contents
          description: MTHDS contents to load (always an array, even for a single file). Exactly one of `mthds_contents` /
            `method_ref`.
        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 `.mthds` files feed the validation with their
            real relative paths as per-file sources. Exactly one of `mthds_contents` / `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: 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.
        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 403. Omitted → the default.'
      type: object
      title: ValidateRequest
      description: 'The shared `mthds_contents` + `allow_signatures` payload, plus optional per-file sources.


        `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 structured `validation_errors` on a 200 `InvalidReport` carry a real

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

        `source` null 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.'
    ValidationErrorCategory:
      type: string
      enum:
      - blueprint_validation
      - pipe_factory
      - pipe_validation
      - dry_run
      title: ValidationErrorCategory
      description: 'Which validation stage produced a :class:`ValidationErrorItem`.


        Mirrors the categorized error-data lists aggregated by ``ValidateBundleError``:

        blueprint validation (from the interpreter), pipe-factory failures (e.g. a

        missing concept), pipe/concept validation (e.g. a missing input variable

        or a type mismatch), and the ``dry_run`` residual — a dry-run failure with no

        structured locator (graph-level), carried as a single message-only item so an

        invalid verdict always surfaces a non-empty ``validation_errors[]`` (the

        structured-info invariant) instead of a bare ``detail``.'
    ValidationErrorItem:
      properties:
        category:
          $ref: '#/components/schemas/ValidationErrorCategory'
        message:
          type: string
          title: Message
        error_type:
          anyOf:
          - $ref: '#/components/schemas/PipeValidationErrorType'
          - $ref: '#/components/schemas/PipeFactoryErrorType'
          - $ref: '#/components/schemas/ValidationResidualErrorType'
          - $ref: '#/components/schemas/HintLintErrorType'
          - type: 'null'
          title: Error Type
        pipe_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Pipe Code
        concept_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Concept Code
        domain_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain Code
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        field_path:
          anyOf:
          - type: string
          - type: 'null'
          title: Field Path
        field_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Field Name
        variable_names:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Variable Names
        missing_concept_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Missing Concept Code
        missing_pipe_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Missing Pipe Code
        declared_concepts:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Declared Concepts
        suggested_fix:
          anyOf:
          - $ref: '#/components/schemas/SuggestedFix'
          - type: 'null'
      additionalProperties: false
      type: object
      required:
      - category
      - message
      title: ValidationErrorItem
      description: 'One structured bundle-validation error, projected onto the error wire.


        The typed wire item carried by :attr:`ErrorReport.validation_errors`. Its

        fields are the *union* across the three ``ValidateBundleError`` error-data

        models (``PipelexBundleBlueprintValidationErrorData``, ``PipeFactoryErrorData``,

        ``PipesAndConceptValidationErrorData``); a given item only populates the

        subset its :attr:`category` produces, and the unset fields drop out of the

        ``exclude_none`` wire projection.


        The error channel is built exclusively by

        ``pipelex.pipeline.validation_errors.build_validation_error_items``, which both the agent

        CLI (``extract_validation_errors``) and the API path

        (``ValidateBundleError.to_error_report``) call — so the CLI''s structured

        output and the API''s 422 ``validation_errors`` can never drift. The same

        item type also carries the report''s advisory ``warnings``, built by

        ``pipelex.pipeline.advisory_warnings``: a warning is the same shape of

        diagnostic, differing only in that it does not make the verdict invalid.


        ``source`` is the declaring file path (CLI) or the per-content source the API

        threads onto the in-memory load path — it hands a consumer the owning file

        for cross-file diagnostics. Lives here, alongside :class:`ErrorReport`,

        rather than next to the source error-data models because ``ErrorReport``

        references it as a typed field and ``base_exceptions`` must not import the

        ``pipelex.core`` error modules (which import back into this module).'
    ValidationResidualErrorType:
      type: string
      enum:
      - DryRunError
      title: ValidationResidualErrorType
      description: 'The ``error_type`` of a validation residual — a failure with no stage-level error data.


        A residual is what the wire projection emits when a bundle failed but no categorized

        validation stage produced structured data to report. There is exactly one residual that names

        itself: a dry-run failure surfaces a single message from a raised ``DryRunError`` / ``PipeRunError``,

        so the item is tagged with that exception''s own class name.


        The other residual — the parse-level one, for a bundle that could not be turned into a

        blueprint at all (a TOML-syntax error, an empty blueprint, an elaborator failure) — carries no

        ``error_type`` and therefore no member here. That is not an omission: it fires for several

        distinct underlying errors, and inventing one code for all of them would tell a consumer it

        knows which fault occurred when it does not. Its message is the authoritative diagnostic.'
    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