openapi: '3.1.0'
info:
  title: MetaClaw Antenna and RFIC Workspace API
  version: '1.0.0'
  description: Public reference for a locally configured runtime. MetaHz hosts static documentation; solver execution occurs on the runtime and its configured compute. Requests and responses use application/yaml. No query parameters are accepted. Readiness, native completion, numerical convergence and physical qualification are distinct.
servers:
  - url: http://127.0.0.1:8505/api/antenna/live/workspace
    description: Default loopback runtime; use the running instance address.
security:
  - {}
  - RuntimeControlToken: []
paths:
  /catalog:
    get:
      operationId: getCatalog
      summary: Discover solver integrations and defaults
      parameters:
        - name: x-antenna-client-version
          in: header
          required: true
          schema:
            type: string
            const: '2'
      responses:
        '200':
          description: YAML response.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Catalog'
        '400':
          description: Invalid request or unsupported/not-ready job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid authentication.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Pairing, origin or local-access rejection.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown path or job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: YAML response excluded by Accept.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Antenna client version mismatch.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request too large.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Unsupported request encoding or media type.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Runtime service unavailable.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
  /readiness:
    post:
      operationId: checkReadiness
      summary: Check support and configured admission
      parameters:
        - name: x-antenna-client-version
          in: header
          required: true
          schema:
            type: string
            const: '2'
      responses:
        '200':
          description: YAML response.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Readiness'
        '400':
          description: Invalid request or unsupported/not-ready job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid authentication.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Pairing, origin or local-access rejection.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown path or job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: YAML response excluded by Accept.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Antenna client version mismatch.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request too large.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Unsupported request encoding or media type.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Runtime service unavailable.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              $ref: '#/components/schemas/SceneRequest'
  /preparations:
    post:
      operationId: prepareScene
      summary: Prepare resources as an asynchronous job
      parameters:
        - name: x-antenna-client-version
          in: header
          required: true
          schema:
            type: string
            const: '2'
      responses:
        '200':
          description: YAML response.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Invalid request or unsupported/not-ready job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid authentication.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Pairing, origin or local-access rejection.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown path or job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: YAML response excluded by Accept.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Antenna client version mismatch.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request too large.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Unsupported request encoding or media type.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Runtime service unavailable.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              $ref: '#/components/schemas/SceneRequest'
  /evaluations:
    post:
      operationId: evaluateCandidate
      summary: Start one fresh evaluation
      parameters:
        - name: x-antenna-client-version
          in: header
          required: true
          schema:
            type: string
            const: '2'
      responses:
        '202':
          description: Accepted asynchronous job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Invalid request or unsupported/not-ready job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid authentication.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Pairing, origin or local-access rejection.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown path or job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: YAML response excluded by Accept.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Antenna client version mismatch.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request too large.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Unsupported request encoding or media type.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Runtime service unavailable.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              $ref: '#/components/schemas/EvaluationRequest'
  /jobs:
    get:
      operationId: listJobs
      summary: List up to 50 recent runtime job summaries
      parameters:
        - name: x-antenna-client-version
          in: header
          required: true
          schema:
            type: string
            const: '2'
      responses:
        '200':
          description: YAML response.
          content:
            application/yaml:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items:
                      $ref: '#/components/schemas/JobSummary'
                    maxItems: 50
                required:
                  - jobs
                additionalProperties: false
        '400':
          description: Invalid request or unsupported/not-ready job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid authentication.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Pairing, origin or local-access rejection.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown path or job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: YAML response excluded by Accept.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Antenna client version mismatch.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request too large.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Unsupported request encoding or media type.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Runtime service unavailable.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: startSearch
      summary: Start bounded ADO or GA search
      parameters:
        - name: x-antenna-client-version
          in: header
          required: true
          schema:
            type: string
            const: '2'
      responses:
        '200':
          description: YAML response.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Invalid request or unsupported/not-ready job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid authentication.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Pairing, origin or local-access rejection.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown path or job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: YAML response excluded by Accept.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Antenna client version mismatch.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request too large.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Unsupported request encoding or media type.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Runtime service unavailable.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              $ref: '#/components/schemas/SearchRequest'
  '/jobs/{id}':
    get:
      operationId: getJob
      summary: Read job status and retained results
      parameters:
        - name: x-antenna-client-version
          in: header
          required: true
          schema:
            type: string
            const: '2'
        - name: id
          in: path
          required: true
          schema:
            type: string
            pattern: '^[a-f0-9]{32}$'
      responses:
        '200':
          description: YAML response.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Invalid request or unsupported/not-ready job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid authentication.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Pairing, origin or local-access rejection.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown path or job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: YAML response excluded by Accept.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Antenna client version mismatch.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request too large.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Unsupported request encoding or media type.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Runtime service unavailable.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
  '/jobs/{id}/cancel':
    post:
      operationId: cancelJob
      summary: Request cancellation of the owned job
      parameters:
        - name: x-antenna-client-version
          in: header
          required: true
          schema:
            type: string
            const: '2'
        - name: id
          in: path
          required: true
          schema:
            type: string
            pattern: '^[a-f0-9]{32}$'
      responses:
        '200':
          description: YAML response.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Invalid request or unsupported/not-ready job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid authentication.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Pairing, origin or local-access rejection.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Unknown path or job.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '406':
          description: YAML response excluded by Accept.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Antenna client version mismatch.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: Request too large.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '415':
          description: Unsupported request encoding or media type.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Runtime service unavailable.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              type: object
              additionalProperties: false
  /reduced/families:
    get:
      operationId: getPreparedFamilies
      summary: Discover harmonic and finite-window prepared families
      parameters:
      - name: x-antenna-client-version
        in: header
        required: true
        schema:
          type: string
          const: '2'
      responses:
        '200':
          description: YAML response; queued jobs must be polled for completion.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/PreparedFamilyCatalog'
        default:
          description: Request, pairing, origin, runtime readiness, active-job or admission failure.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
  /reduced/evaluations:
    post:
      operationId: evaluatePreparedFamily
      summary: Queue a fresh prepared-family evaluation with its required setup
      parameters:
      - name: x-antenna-client-version
        in: header
        required: true
        schema:
          type: string
          const: '2'
      responses:
        '200':
          description: YAML response; queued jobs must be polled for completion.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/PreparedResponseJob'
        default:
          description: Request, pairing, origin, runtime readiness, active-job or admission failure.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              $ref: '#/components/schemas/PreparedResponseRequest'
            examples:
              finiteWindow:
                summary: Input only. Replace family_id and copy its complete catalog frequency roster; no response values are invented.
                value:
                  query:
                    schema: metaclaw.harp-finite-window-query/1
                    family_id: prepared-family-id
                    width_mm: 10.0
                    frequencies_hz:
                    - 4000000000.0
                    - 4010000000.0
                    - 4020000000.0
                    - 4030000000.0
                    - 4040000000.0
                    - 4050000000.0
                    - 4060000000.0
                    - 4070000000.0
                    - 4080000000.0
                    - 4090000000.0
                    - 4100000000.0
                    - 4110000000.0
                    - 4120000000.0
                    - 4130000000.0
                    - 4140000000.0
                    - 4150000000.0
                    - 4160000000.0
                    - 4170000000.0
                    - 4180000000.0
                    - 4190000000.0
                    - 4200000000.0
                    - 4210000000.0
                    - 4220000000.0
                    - 4230000000.0
                    - 4240000000.0
                    - 4250000000.0
                    - 4260000000.0
                    - 4270000000.0
                    - 4280000000.0
                    - 4290000000.0
                    - 4300000000.0
                    - 4310000000.0
                    - 4320000000.0
                    - 4330000000.0
                    - 4340000000.0
                    - 4350000000.0
                    - 4360000000.0
                    - 4370000000.0
                    - 4380000000.0
                    - 4390000000.0
                    - 4400000000.0
                    - 4410000000.0
                    - 4420000000.0
                    - 4430000000.0
                    - 4440000000.0
                    - 4450000000.0
                    - 4460000000.0
                    - 4470000000.0
                    - 4480000000.0
                    - 4490000000.0
                    - 4500000000.0
                    - 4510000000.0
                    - 4520000000.0
                    - 4530000000.0
                    - 4540000000.0
                    - 4550000000.0
                    - 4560000000.0
                    - 4570000000.0
                    - 4580000000.0
                    - 4590000000.0
                    - 4600000000.0
                    - 4610000000.0
                    - 4620000000.0
                    - 4630000000.0
                    - 4640000000.0
                    - 4650000000.0
                    - 4660000000.0
                    - 4670000000.0
                    - 4680000000.0
                    - 4690000000.0
                    - 4700000000.0
                    - 4710000000.0
                    - 4720000000.0
                    - 4730000000.0
                    - 4740000000.0
                    - 4750000000.0
                    - 4760000000.0
                    - 4770000000.0
                    - 4780000000.0
                    - 4790000000.0
                    - 4800000000.0
                    - 4810000000.0
                    - 4820000000.0
                    - 4830000000.0
                    - 4840000000.0
                    - 4850000000.0
                    - 4860000000.0
                    - 4870000000.0
                    - 4880000000.0
                    - 4890000000.0
                    - 4900000000.0
                    - 4910000000.0
                    - 4920000000.0
                    - 4930000000.0
                    - 4940000000.0
                    - 4950000000.0
                    - 4960000000.0
                    - 4970000000.0
                    - 4980000000.0
                    - 4990000000.0
                    - 5000000000.0
                    - 5010000000.0
                    - 5020000000.0
                    - 5030000000.0
                    - 5040000000.0
                    - 5050000000.0
                    - 5060000000.0
                    - 5070000000.0
                    - 5080000000.0
                    - 5090000000.0
                    - 5100000000.0
                    - 5110000000.0
                    - 5120000000.0
                    - 5130000000.0
                    - 5140000000.0
                    - 5150000000.0
                    - 5160000000.0
                    - 5170000000.0
                    - 5180000000.0
                    - 5190000000.0
                    - 5200000000.0
                    - 5210000000.0
                    - 5220000000.0
                    - 5230000000.0
                    - 5240000000.0
                    - 5250000000.0
                    - 5260000000.0
                    - 5270000000.0
                    - 5280000000.0
                    - 5290000000.0
                    - 5300000000.0
                    - 5310000000.0
                    - 5320000000.0
                    - 5330000000.0
                    - 5340000000.0
                    - 5350000000.0
                    - 5360000000.0
                    - 5370000000.0
                    - 5380000000.0
                    - 5390000000.0
                    - 5400000000.0
                    - 5410000000.0
                    - 5420000000.0
                    - 5430000000.0
                    - 5440000000.0
                    - 5450000000.0
                    - 5460000000.0
                    - 5470000000.0
                    - 5480000000.0
                    - 5490000000.0
                    - 5500000000.0
                    - 5510000000.0
                    - 5520000000.0
                    - 5530000000.0
                    - 5540000000.0
                    - 5550000000.0
                    - 5560000000.0
                    - 5570000000.0
                    - 5580000000.0
                    - 5590000000.0
                    - 5600000000.0
                    - 5610000000.0
                    - 5620000000.0
                    - 5630000000.0
                    - 5640000000.0
                    - 5650000000.0
                    - 5660000000.0
                    - 5670000000.0
                    - 5680000000.0
                    - 5690000000.0
                    - 5700000000.0
                    - 5710000000.0
                    - 5720000000.0
                    - 5730000000.0
                    - 5740000000.0
                    - 5750000000.0
                    - 5760000000.0
                    - 5770000000.0
                    - 5780000000.0
                    - 5790000000.0
                    - 5800000000.0
                    - 5810000000.0
                    - 5820000000.0
                    - 5830000000.0
                    - 5840000000.0
                    - 5850000000.0
                    - 5860000000.0
                    - 5870000000.0
                    - 5880000000.0
                    - 5890000000.0
                    - 5900000000.0
                    - 5910000000.0
                    - 5920000000.0
                    - 5930000000.0
                    - 5940000000.0
                    - 5950000000.0
                    - 5960000000.0
                    - 5970000000.0
                    - 5980000000.0
                    - 5990000000.0
                    - 6000000000.0
                    - 6010000000.0
                    - 6020000000.0
                    - 6030000000.0
                    - 6040000000.0
                    - 6050000000.0
                    - 6060000000.0
                    - 6070000000.0
                    - 6080000000.0
                    - 6090000000.0
                    - 6100000000.0
                    - 6110000000.0
                    - 6120000000.0
                    - 6130000000.0
                    - 6140000000.0
                    - 6150000000.0
                    - 6160000000.0
                    - 6170000000.0
                    - 6180000000.0
                    - 6190000000.0
                    - 6200000000.0
                    - 6210000000.0
                    - 6220000000.0
                    - 6230000000.0
                    - 6240000000.0
                    - 6250000000.0
                    - 6260000000.0
                    - 6270000000.0
                    - 6280000000.0
                    - 6290000000.0
                    - 6300000000.0
                    - 6310000000.0
                    - 6320000000.0
                    - 6330000000.0
                    - 6340000000.0
                    - 6350000000.0
                    - 6360000000.0
                    - 6370000000.0
                    - 6380000000.0
                    - 6390000000.0
                    - 6400000000.0
                    - 6410000000.0
                    - 6420000000.0
                    - 6430000000.0
                    - 6440000000.0
                    - 6450000000.0
                    - 6460000000.0
                    - 6470000000.0
                    - 6480000000.0
                    - 6490000000.0
                    - 6500000000.0
                    - 6510000000.0
                    - 6520000000.0
                    - 6530000000.0
                    - 6540000000.0
                    - 6550000000.0
                    - 6560000000.0
                    - 6570000000.0
                    - 6580000000.0
                    - 6590000000.0
                    - 6600000000.0
                    - 6610000000.0
                    - 6620000000.0
                    - 6630000000.0
                    - 6640000000.0
                    - 6650000000.0
                    - 6660000000.0
                    - 6670000000.0
                    - 6680000000.0
                    - 6690000000.0
                    - 6700000000.0
                    - 6710000000.0
                    - 6720000000.0
                    - 6730000000.0
                    - 6740000000.0
                    - 6750000000.0
                    - 6760000000.0
                    - 6770000000.0
                    - 6780000000.0
                    - 6790000000.0
                    - 6800000000.0
                    - 6810000000.0
                    - 6820000000.0
                    - 6830000000.0
                    - 6840000000.0
                    - 6850000000.0
                    - 6860000000.0
                    - 6870000000.0
                    - 6880000000.0
                    - 6890000000.0
                    - 6900000000.0
                    - 6910000000.0
                    - 6920000000.0
                    - 6930000000.0
                    - 6940000000.0
                    - 6950000000.0
                    - 6960000000.0
                    - 6970000000.0
                    - 6980000000.0
                    - 6990000000.0
                    - 7000000000.0
                    - 7010000000.0
                    - 7020000000.0
                    - 7030000000.0
                    - 7040000000.0
                    - 7050000000.0
                    - 7060000000.0
                    - 7070000000.0
                    - 7080000000.0
                    - 7090000000.0
                    - 7100000000.0
                    - 7110000000.0
                    - 7120000000.0
                    - 7130000000.0
                    - 7140000000.0
                    - 7150000000.0
                    - 7160000000.0
                    - 7170000000.0
                    - 7180000000.0
                    - 7190000000.0
                    - 7200000000.0
                    - 7210000000.0
                    - 7220000000.0
                    - 7230000000.0
                    - 7240000000.0
                    - 7250000000.0
                    - 7260000000.0
                    - 7270000000.0
                    - 7280000000.0
                    - 7290000000.0
                    - 7300000000.0
                    - 7310000000.0
                    - 7320000000.0
                    - 7330000000.0
                    - 7340000000.0
                    - 7350000000.0
                    - 7360000000.0
                    - 7370000000.0
                    - 7380000000.0
                    - 7390000000.0
                    - 7400000000.0
                    - 7410000000.0
                    - 7420000000.0
                    - 7430000000.0
                    - 7440000000.0
                    - 7450000000.0
                    - 7460000000.0
                    - 7470000000.0
                    - 7480000000.0
                    - 7490000000.0
                    - 7500000000.0
                    - 7510000000.0
                    - 7520000000.0
                    - 7530000000.0
                    - 7540000000.0
                    - 7550000000.0
                    - 7560000000.0
                    - 7570000000.0
                    - 7580000000.0
                    - 7590000000.0
                    - 7600000000.0
                    - 7610000000.0
                    - 7620000000.0
                    - 7630000000.0
                    - 7640000000.0
                    - 7650000000.0
                    - 7660000000.0
                    - 7670000000.0
                    - 7680000000.0
                    - 7690000000.0
                    - 7700000000.0
                    - 7710000000.0
                    - 7720000000.0
                    - 7730000000.0
                    - 7740000000.0
                    - 7750000000.0
                    - 7760000000.0
                    - 7770000000.0
                    - 7780000000.0
                    - 7790000000.0
                    - 7800000000.0
                    - 7810000000.0
                    - 7820000000.0
                    - 7830000000.0
                    - 7840000000.0
                    - 7850000000.0
                    - 7860000000.0
                    - 7870000000.0
                    - 7880000000.0
                    - 7890000000.0
                    - 7900000000.0
                    - 7910000000.0
                    - 7920000000.0
                    - 7930000000.0
                    - 7940000000.0
                    - 7950000000.0
                    - 7960000000.0
                    - 7970000000.0
                    - 7980000000.0
                    - 7990000000.0
                    - 8000000000.0
                    accuracy_policy: validated_points
                    expected_evaluations: 5
                  settings:
                    harp_mode: adaptive
                    reduction_implementation: auto
                    seconds: 600
                    host_memory_bytes: 8589934592
                    device_memory_bytes: 8589934592
                    storage_bytes: 2147483648
      description: This HTTP route accepts the compact query only. It does not accept scene objects, model paths, device selection or shell commands. Finite-window execution uses four logical modes; the legacy harmonic schema remains separate. Runtime preparation is included in the asynchronous job, and compatible preparation may be reused.
  /reduced/jobs:
    get:
      operationId: listPreparedJobs
      summary: List the last 50 prepared-family jobs
      parameters:
      - name: x-antenna-client-version
        in: header
        required: true
        schema:
          type: string
          const: '2'
      responses:
        '200':
          description: YAML response; queued jobs must be polled for completion.
          content:
            application/yaml:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    maxItems: 50
                    items:
                      $ref: '#/components/schemas/PreparedResponseJobSummary'
                required:
                - jobs
                additionalProperties: false
        default:
          description: Request, pairing, origin, runtime readiness, active-job or admission failure.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
  /reduced/jobs/{id}:
    get:
      operationId: getPreparedJob
      summary: Read a saved prepared-family job and its bound result
      parameters:
      - name: x-antenna-client-version
        in: header
        required: true
        schema:
          type: string
          const: '2'
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-f0-9]{32}$
      responses:
        '200':
          description: YAML response; queued jobs must be polled for completion.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/PreparedResponseJob'
        default:
          description: Request, pairing, origin, runtime readiness, active-job or admission failure.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
  /reduced/jobs/{id}/cancel:
    post:
      operationId: cancelPreparedJob
      summary: Cancel the owned prepared-family job
      parameters:
      - name: x-antenna-client-version
        in: header
        required: true
        schema:
          type: string
          const: '2'
      - name: id
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-f0-9]{32}$
      responses:
        '200':
          description: YAML response; queued jobs must be polled for completion.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/PreparedResponseJob'
        default:
          description: Request, pairing, origin, runtime readiness, active-job or admission failure.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              type: object
              properties: {}
              required: []
              additionalProperties: false
  /rfic/array4x4/readiness:
    get:
      servers:
        - url: http://127.0.0.1:8505/api
          description: RFIC runtime base; separate from the antenna workspace base.
      operationId: getRficArrayReadiness
      summary: Discover RFIC editing operations and execution readiness
      description: No antenna-client-version header or query parameters. edit_operations is additive; omission on an older runtime means no advertised support for the four new technology operations. Existing capabilities.edit semantics remain unchanged. This route does not launch a numerical job.
      responses:
        '200':
          description: Current runtime capability readback; source documentation does not prove an installed runtime supports an operation.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/RficArrayReadiness'
        default:
          description: Pairing/origin/authentication, YAML negotiation or runtime error.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
  /rfic/array4x4/designs/{design_id}:
    get:
      servers:
        - url: http://127.0.0.1:8505/api
          description: RFIC runtime base; separate from the antenna workspace base.
      operationId: getRficArrayDesign
      summary: Read the canonical RFIC project, geometry and revision
      parameters:
        - name: design_id
          in: path
          required: true
          schema:
            enum: [design_monolithic_on_die, design_single_die_aip]
      responses:
        '200':
          description: Use project.revision.design_revision_id for the next transaction. Geometry is regenerated from the project; history includes current revision history.
          content:
            application/yaml:
              schema:
                type: object
                required: [project, physical_model, history]
                properties:
                  project: {type: object, additionalProperties: true}
                  physical_model: {type: object, additionalProperties: true}
                  history: {type: array, items: {type: object}}
        default:
          description: Unknown design, pairing/origin/authentication, YAML negotiation or runtime error.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
  /rfic/array4x4/designs/{design_id}/transactions:
    post:
      servers:
        - url: http://127.0.0.1:8505/api
          description: RFIC runtime base; separate from the antenna workspace base.
      operationId: transactRficArrayTechnology
      summary: Atomically change development materials and layers
      description: This section documents the four technology operations on the existing transaction endpoint. Existing component, requirement, band and operating-state operation contracts remain valid but are outside this request sub-contract. Check edit_operations first. Request limit 128 KiB; response limit 16 MiB. No numerical job starts. Invalid changes preserve the prior revision; valid changes regenerate solids, terminal paths and ports and invalidate affected products. Process-owned definitions and arbitrary port impedance edits are not admitted.
      parameters:
        - name: design_id
          in: path
          required: true
          schema:
            enum: [design_monolithic_on_die, design_single_die_aip]
      requestBody:
        required: true
        content:
          application/yaml:
            schema:
              $ref: '#/components/schemas/RficTechnologyTransaction'
            example:
              expected_revision_id: rev_0001
              idempotency_key: material-layer-example-1
              operations:
                - op: create_development_material
                  material_id: user_dielectric
                  material:
                    kind: dielectric
                    model: constant_complex
                    label: User development dielectric
                    relative_permittivity: 3.2
                    loss_tangent: 0.002
                    provenance: user_defined_development
                    validity: user_defined_unqualified_constant_model
                - op: assign_layer_material
                  layer_id: die_ild
                  material_id: user_dielectric
                - op: set_layer_thickness
                  layer_id: die_ild
                  thickness_m: 0.000012
      responses:
        '200':
          description: Applied or idempotently replayed; includes canonical project and regenerated physical_model. Reuse the same key only for the same operations.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/RficTransactionResult'
        '409':
          description: Expected revision conflict; inspect changed entities, reload and resolve the preserved draft. Transport/runtime failures may instead return Error.
          content:
            application/yaml:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/RficTransactionResult'
                  - $ref: '#/components/schemas/Error'
        '422':
          description: Rejected operation or resulting model; no partial commit. issues provides the exact field and repair action.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/RficTransactionResult'
        default:
          description: Malformed body, unknown design, pairing/origin/authentication, size or YAML-negotiation failure.
          content:
            application/yaml:
              schema:
                $ref: '#/components/schemas/Error'
components:
  securitySchemes:
    RuntimeControlToken:
      type: apiKey
      in: header
      name: X-MetaClaw-Control-Token
      description: Required for paired hosted clients and runtimes with authentication enabled. Direct local requests may use the runtime default loopback policy. Obtain the session token through runtime pairing; never publish it.
  schemas:
    RficArrayReadiness:
      type: object
      required: [schema, ready, designs, capabilities, operating_models, limitations, physical_rf_qualified]
      properties:
        schema: {const: metahz.rfic-array-readiness/1}
        ready: {type: boolean}
        designs: {type: array, items: {type: object, additionalProperties: true}}
        capabilities: {type: object, additionalProperties: true}
        operating_models: {type: array, items: {type: object, additionalProperties: true}}
        limitations: {type: array, items: {type: string}}
        physical_rf_qualified: {const: false}
        edit_operations:
          type: array
          uniqueItems: true
          items: {type: string}
          description: Optional additive operation names. Require all operations used by a transaction; never infer support from source version or capabilities.edit alone. Omission preserves old editing and disables new technology controls.
      additionalProperties: true
    RficIdentifier:
      type: string
      pattern: '^[A-Za-z][A-Za-z0-9_.:-]{0,119}$'
      maxLength: 120
    RficDevelopmentMaterial:
      description: Complete edited definition. Trim labels; only development stacks and development-owned materials may be changed. Existing kind/model is immutable on update. Source/validity explicitly record unqualified user input. At most 64 named materials per technology.
      oneOf:
        - type: object
          required: [kind, model, label, provenance, validity, conductivity_s_per_m]
          properties:
            kind: {const: conductor}
            model: {const: finite_conductivity}
            label: {type: string, minLength: 1, maxLength: 200}
            provenance: {const: user_defined_development}
            validity: {const: user_defined_unqualified_constant_model}
            conductivity_s_per_m: {type: number, exclusiveMinimum: 0}
          additionalProperties: false
        - type: object
          required: [kind, model, label, provenance, validity, relative_permittivity]
          properties:
            kind: {const: dielectric}
            model: {const: constant_complex}
            label: {type: string, minLength: 1, maxLength: 200}
            provenance: {const: user_defined_development}
            validity: {const: user_defined_unqualified_constant_model}
            relative_permittivity: {type: number, minimum: 1}
            conductivity_s_per_m: {type: number, minimum: 0}
            loss_tangent: {type: number, minimum: 0}
          additionalProperties: false
    RficTechnologyOperation:
      oneOf:
        - type: object
          required: [op, material_id, material]
          properties:
            op: {enum: [create_development_material, update_development_material]}
            material_id: {$ref: '#/components/schemas/RficIdentifier'}
            material: {$ref: '#/components/schemas/RficDevelopmentMaterial'}
          additionalProperties: false
          description: Create requires an unused ID; Update requires an existing development-owned material and preserves its kind/model. Update replaces the complete definition.
        - type: object
          required: [op, layer_id, material_id]
          properties:
            op: {const: assign_layer_material}
            layer_id: {$ref: '#/components/schemas/RficIdentifier'}
            material_id: {$ref: '#/components/schemas/RficIdentifier'}
          additionalProperties: false
          description: Assign an existing material matching the existing layer kind; affects all generated objects on that layer.
        - type: object
          required: [op, layer_id, thickness_m]
          properties:
            op: {const: set_layer_thickness}
            layer_id: {$ref: '#/components/schemas/RficIdentifier'}
            thickness_m: {type: number, exclusiveMinimum: 0}
          additionalProperties: false
          description: Metres; must align to the technology fabrication grid and span at least one cell. Reflows downstream layer elevations using exact-range integer grid coordinates, then regenerates geometry and ports. No automatic retuning.
    RficTechnologyTransaction:
      type: object
      required: [expected_revision_id, idempotency_key, operations]
      properties:
        expected_revision_id: {type: string, pattern: '^rev_[0-9]{4,}$'}
        idempotency_key: {type: string, minLength: 1, maxLength: 120}
        operations:
          type: array
          minItems: 1
          maxItems: 256
          items: {$ref: '#/components/schemas/RficTechnologyOperation'}
      additionalProperties: false
    RficTransactionResult:
      type: object
      required: [schema, status, scope, expected_revision_id, current_revision_id, new_revision_id, state_revision, changed_entity_ids, affected_channel_ids, invalidation, conflict, issues, project]
      properties:
        schema: {const: metahz.rfdesign-transaction-result/v1}
        status: {enum: [applied, replayed, conflict, rejected]}
        scope: {type: [string, 'null']}
        expected_revision_id: {type: [string, 'null']}
        current_revision_id: {type: string}
        new_revision_id: {type: [string, 'null']}
        state_revision: {type: integer, minimum: 0}
        changed_entity_ids: {type: array, items: {type: string}}
        affected_channel_ids: {type: array, items: {type: string}}
        invalidation:
          type: object
          required: [stale_products, reusable_products]
          properties:
            stale_products: {type: array, items: {type: string}}
            reusable_products: {type: array, items: {type: string}}
        conflict: {type: [object, 'null'], additionalProperties: true}
        issues: {type: array, items: {type: object, additionalProperties: true}}
        project: {type: [object, 'null'], additionalProperties: true}
        physical_model: {type: object, additionalProperties: true}
      additionalProperties: true
    Error:
      type: object
      properties:
        error:
          type: string
        code:
          type: string
      required:
        - error
      additionalProperties: true
    Solver:
      type: string
      enum:
        - harp_v1
        - witwin_maxwell
        - pngf
        - ansys_pyaedt
      description: Catalog identity. This reference focuses on the reusable HARP/WiTwin/PNGF routes. The separately managed HFSS route currently accepts only scalar material properties, the open boundary shorthand and the legacy implicit port drive; it rejects independent excitation objects and explicit face boundaries before native launch. Readiness governs the configured integration.
    Settings:
      type: object
      properties:
        seconds:
          type: integer
          minimum: 1
          maximum: 7200
          default: 600
        host_memory_bytes:
          type: integer
          minimum: 67108864
          maximum: 274877906944
          default: 34359738368
        device_memory_bytes:
          type: integer
          minimum: 67108864
          maximum: 137438953472
          default: 17179869184
        storage_bytes:
          type: integer
          minimum: 67108864
          maximum: 274877906944
          default: 68719476736
        time_steps:
          type: integer
          minimum: 100
          maximum: 500000
          default: 500000
        duration_ns:
          type: number
          minimum: 0.001
          maximum: 100
          default: 20
        harp_mode:
          type: string
          enum:
            - direct
            - hybrid
            - hybrid_response
            - adaptive
          description: HARP only. Device and precision are controlled by deployment configuration.
        native_timeout_seconds:
          type: integer
          minimum: 60
          maximum: 7200
          description: ansys_pyaedt only.
        hfss_setup:
          $ref: '#/components/schemas/HfssSetup'
      required: []
      additionalProperties: false
      description: Omitted controls use catalog defaults. hfss_setup and native_timeout_seconds are accepted only for ansys_pyaedt; other solvers reject them. Unknown settings and client-selected paths, commands or devices are rejected.
    HfssSetup:
      type: object
      description: Complete native HFSS Driven Modal adaptive setup, accepted only for ansys_pyaedt. The adaptive frequency must lie within scene.frequencies_hz endpoints. minimum_converged_passes must be at most minimum_passes, which must be at most maximum_passes. The runtime validates these relationships and preserves all seven fields in the saved request. Omitting the whole object retains the existing middle-frequency, 0.02 Delta-S, 2 minimum passes, 2 converged passes, 12 maximum passes, 30 percent refinement and first-order basis defaults. The frequency sweep remains the scene's exact Discrete roster. This is separate from the shared Yee mesh; no solve or convergence is implied by valid settings.
      properties:
        adaptive_frequency_hz:
          type: number
          exclusiveMinimum: 0
          maximum: 10000000000000
          description: HFSS adaptive solution frequency in Hz, within the requested band; it need not be one of the Discrete sweep samples.
        max_delta_s:
          type: number
          exclusiveMinimum: 0
          maximum: 1
          default: 0.02
        minimum_passes:
          type: integer
          minimum: 1
          maximum: 100
          default: 2
        minimum_converged_passes:
          type: integer
          minimum: 1
          maximum: 100
          default: 2
        maximum_passes:
          type: integer
          minimum: 1
          maximum: 100
          default: 12
        percent_refinement:
          type: number
          exclusiveMinimum: 0
          maximum: 100
          default: 30
        basis_order:
          type: integer
          enum:
            - 1
            - 2
          default: 1
      required:
        - adaptive_frequency_hz
        - max_delta_s
        - minimum_passes
        - minimum_converged_passes
        - maximum_passes
        - percent_refinement
        - basis_order
      additionalProperties: false
    Candidate:
      type: object
      properties:
        id:
          type: string
          pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'
        conductor_ids:
          type: array
          items:
            type: string
            pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'
          uniqueItems: true
          maxItems: 4096
      required:
        - id
        - conductor_ids
      additionalProperties: false
      description: Select only design-role conductor IDs. Fixed conductors always remain present. The source gap must remain open.
    Bounds:
      type: array
      items:
        type: number
      minItems: 6
      maxItems: 6
      description: '[xmin,xmax,ymin,ymax,zmin,zmax] in metres. A sheet has exactly one zero-width axis; a solid has positive volume.'
    Point:
      type: array
      items:
        type: number
      minItems: 3
      maxItems: 3
    Material:
      title: Materials — scalar or Cartesian-diagonal medium
      externalDocs:
        url: https://metahz.ai/docs/api#materials
      type: object
      properties:
        id:
          type: string
          pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'
        epsilon_r:
          description: Isotropic relative permittivity; choose this or epsilon_r_diagonal.
          type: number
          minimum: 1
          maximum: 1000
        epsilon_r_diagonal:
          description: Relative permittivity along the declared Cartesian x, y and z axes. HARP and WiTwin support this; PNGF rejects it.
          type: array
          items:
            type: number
            minimum: 1
            maximum: 1000
          minItems: 3
          maxItems: 3
        mu_r:
          description: Isotropic relative permeability; choose this or mu_r_diagonal. PNGF requires exactly 1.
          type: number
          minimum: 1
          maximum: 1000
        mu_r_diagonal:
          description: Relative permeability along x, y and z. HARP and WiTwin support this; PNGF rejects it.
          type: array
          items:
            type: number
            minimum: 1
            maximum: 1000
          minItems: 3
          maxItems: 3
        loss:
          oneOf:
            - type: object
              properties:
                kind:
                  const: conductivity
                sigma_s_m:
                  description: Bulk Conductivity in S/m. Use zero for a lossless dielectric.
                  type: number
                  minimum: 0
                  maximum: 100000000
              required:
                - kind
                - sigma_s_m
              additionalProperties: false
            - type: object
              properties:
                kind:
                  const: loss_tangent
                tan_delta:
                  description: Dielectric loss tangent. PNGF evaluates this at each requested frequency; time-domain HARP and WiTwin reject this declaration.
                  type: number
                  minimum: 0
                  maximum: 10
              required:
                - kind
                - tan_delta
              additionalProperties: false
      required:
        - id
        - loss
      allOf:
        - oneOf:
            - required: [epsilon_r]
            - required: [epsilon_r_diagonal]
        - oneOf:
            - required: [mu_r]
            - required: [mu_r_diagonal]
      additionalProperties: false
      description: Scalar or Cartesian-diagonal nondispersive material. Route admission is authoritative; PNGF currently requires scalar epsilon and nonmagnetic mu=1.
    Dielectric:
      title: Materials — volume assignment
      externalDocs:
        url: https://metahz.ai/docs/api#materials
      type: object
      properties:
        id:
          type: string
          pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'
        material_id:
          type: string
          pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'
        bounds_m:
          $ref: '#/components/schemas/Bounds'
      required:
        - id
        - material_id
        - bounds_m
      additionalProperties: false
      description: Positive-volume axis-aligned box. Material boxes must not overlap.
    Conductor:
      type: object
      properties:
        id:
          type: string
          pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'
        kind:
          enum:
            - sheet
            - solid
        role:
          enum:
            - fixed
            - design
        bounds_m:
          $ref: '#/components/schemas/Bounds'
      required:
        - id
        - kind
        - role
        - bounds_m
      additionalProperties: false
      description: Perfect E / PEC conductor geometry. Finite-conductivity and impedance boundaries are not supported in the shared evaluator.
    Port:
      title: Excitations — Lumped Port
      externalDocs:
        url: https://metahz.ai/docs/api#excitations
      type: object
      properties:
        id:
          type: string
          pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'
        type:
          const: lumped
        reference_ohm:
          const: 50
        positive_conductor_ids:
          type: array
          items:
            type: string
            pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'
          minItems: 1
          maxItems: 64
          uniqueItems: true
        negative_conductor_ids:
          type: array
          items:
            type: string
            pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'
          minItems: 1
          maxItems: 64
          uniqueItems: true
        sheet_bounds_m:
          $ref: '#/components/schemas/Bounds'
        integration_line_m:
          type: array
          items:
            $ref: '#/components/schemas/Point'
          minItems: 2
          maxItems: 2
        deembed_m:
          const: 0
      required:
        - id
        - type
        - reference_ohm
        - positive_conductor_ids
        - negative_conductor_ids
        - sheet_bounds_m
        - integration_line_m
        - deembed_m
      additionalProperties: false
      description: One finite 50-ohm port. Axis-aligned integration line is ordered positive to negative; endpoints contact distinct fixed conductor terminals.
    Excitation:
      title: Excitations — independent lumped drive
      externalDocs:
        url: https://metahz.ai/docs/api#excitations
      description: Exactly one drive references the declared port. A lumped_current source is Norton current in parallel with the port's 50-ohm resistance, equivalent to a Thevenin voltage of 50*amplitude_a. Phase is in radians.
      oneOf:
        - type: object
          properties:
            id: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$' }
            kind: { const: lumped_voltage }
            port_id: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$' }
            amplitude_v: { type: number, exclusiveMinimum: 0, maximum: 1000000 }
            phase_rad: { type: number, minimum: -3.141592653589793, maximum: 3.141592653589793 }
          required: [id, kind, port_id, amplitude_v, phase_rad]
          additionalProperties: false
        - type: object
          properties:
            id: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$' }
            kind: { const: lumped_current }
            port_id: { type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$' }
            amplitude_a: { type: number, exclusiveMinimum: 0, maximum: 1000000 }
            phase_rad: { type: number, minimum: -3.141592653589793, maximum: 3.141592653589793 }
          required: [id, kind, port_id, amplitude_a, phase_rad]
          additionalProperties: false
    Target:
      type: object
      properties:
        id:
          type: string
          pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'
        start_hz:
          type: number
        stop_hz:
          type: number
        max_s11_db:
          type: number
          minimum: -100
          maximum: 0
        weight:
          type: number
          exclusiveMinimum: 0
          maximum: 1000000
      required:
        - id
        - start_hz
        - stop_hz
        - max_s11_db
        - weight
      additionalProperties: false
    Mesh:
      title: Mesh — explicit Cartesian grid
      externalDocs:
        url: https://metahz.ai/docs/api#mesh
      type: object
      properties:
        axes_m:
          type: object
          properties:
            x:
              type: array
              items:
                type: number
              minItems: 5
              maxItems: 1025
            'y':
              type: array
              items:
                type: number
              minItems: 5
              maxItems: 1025
            z:
              type: array
              items:
                type: number
              minItems: 5
              maxItems: 1025
          required:
            - x
            - 'y'
            - z
          additionalProperties: false
        pml_cells:
          type: integer
          minimum: 1
          maximum: 32
      required:
        - axes_m
        - pml_cells
      additionalProperties: false
      description: Each axis strictly increases and has at least 2*pml_cells+3 nodes. Geometry must be outside PML; shared ceiling is 64 million cells, with route-specific admission below it.
    BoundaryFace:
      type: string
      enum: [pml, mur, pec, pmc, periodic]
      description: Per-face PML, Mur absorbing, perfect-electric, perfect-magnetic, or paired periodic condition. Native support varies by solver.
    Scene:
      type: object
      properties:
        schema:
          const: metaclaw.antenna-scene/1
        id:
          type: string
          pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'
        revision:
          type: integer
          minimum: 0
          maximum: 2147483647
        name:
          type: string
          minLength: 1
          maxLength: 200
        units:
          const: m
        provenance:
          type: object
        materials:
          type: array
          items:
            $ref: '#/components/schemas/Material'
          maxItems: 64
        dielectrics:
          type: array
          items:
            $ref: '#/components/schemas/Dielectric'
          maxItems: 4096
        conductors:
          type: array
          items:
            $ref: '#/components/schemas/Conductor'
          minItems: 2
          maxItems: 4096
        initial_conductor_ids:
          type: array
          items:
            type: string
            pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'
          uniqueItems: true
          maxItems: 4096
        ports:
          type: array
          items:
            $ref: '#/components/schemas/Port'
          minItems: 1
          maxItems: 1
        excitations:
          type: array
          items:
            $ref: '#/components/schemas/Excitation'
          minItems: 1
          maxItems: 1
        frequencies_hz:
          type: array
          items:
            type: number
            exclusiveMinimum: 0
            maximum: 10000000000000
          minItems: 1
          maxItems: 1024
        targets:
          type: array
          items:
            $ref: '#/components/schemas/Target'
          minItems: 1
          maxItems: 32
        mesh:
          $ref: '#/components/schemas/Mesh'
        boundary:
          title: Boundary conditions — open PML or explicit face assignment
          description: Explicit mesh axes set the Yee and PNGF domain extent. Padding sets the separately managed HFSS open-region size and is informational on the Yee and PNGF routes; it does not generate nodes. Each route admits only its implemented face types.
          externalDocs:
            url: https://metahz.ai/docs/api#boundaries
          oneOf:
            - type: object
              properties:
                type: { const: open }
                padding_m: { type: number, exclusiveMinimum: 0, maximum: 100 }
              required: [type, padding_m]
              additionalProperties: false
            - type: object
              properties:
                type: { const: faces }
                padding_m: { type: number, exclusiveMinimum: 0, maximum: 100 }
                faces:
                  type: object
                  properties:
                    x_low: { $ref: '#/components/schemas/BoundaryFace' }
                    x_high: { $ref: '#/components/schemas/BoundaryFace' }
                    y_low: { $ref: '#/components/schemas/BoundaryFace' }
                    y_high: { $ref: '#/components/schemas/BoundaryFace' }
                    z_low: { $ref: '#/components/schemas/BoundaryFace' }
                    z_high: { $ref: '#/components/schemas/BoundaryFace' }
                  required: [x_low, x_high, y_low, y_high, z_low, z_high]
                  additionalProperties: false
              required: [type, padding_m, faces]
              additionalProperties: false
      required:
        - schema
        - id
        - revision
        - name
        - units
        - provenance
        - materials
        - dielectrics
        - conductors
        - initial_conductor_ids
        - ports
        - frequencies_hz
        - targets
        - mesh
        - boundary
      additionalProperties: false
      description: One bounded scene (1 MiB). Native validation enforces geometry contacts, unique IDs, increasing samples, target coverage, mesh placement and supported physics beyond schema checks.
    SceneRequest:
      type: object
      properties:
        scene:
          $ref: '#/components/schemas/Scene'
        solver:
          $ref: '#/components/schemas/Solver'
        settings:
          $ref: '#/components/schemas/Settings'
      required:
        - scene
        - solver
        - settings
      additionalProperties: false
    EvaluationRequest:
      type: object
      properties:
        scene:
          $ref: '#/components/schemas/Scene'
        candidate:
          $ref: '#/components/schemas/Candidate'
        solver:
          $ref: '#/components/schemas/Solver'
        settings:
          $ref: '#/components/schemas/Settings'
      required:
        - scene
        - candidate
        - solver
        - settings
      additionalProperties: false
    SearchRequest:
      type: object
      properties:
        scene:
          $ref: '#/components/schemas/Scene'
        solver:
          $ref: '#/components/schemas/Solver'
        algorithm:
          enum:
            - ado
            - ga
        seed:
          type: integer
          minimum: 0
          maximum: 2147483647
        max_evaluations:
          type: integer
          minimum: 1
          maximum: 128
        max_seconds:
          type: integer
          minimum: 1
          maximum: 14400
        settings:
          $ref: '#/components/schemas/Settings'
        model:
          type: string
          minLength: 1
          maxLength: 256
        goal:
          type: string
          maxLength: 4000
      required:
        - scene
        - solver
        - algorithm
        - seed
        - max_evaluations
        - max_seconds
        - settings
      additionalProperties: false
    Readiness:
      type: object
      required:
        - solver
        - ready
        - requirements
        - settings
        - scene_id
        - scene_revision
      properties:
        solver:
          $ref: '#/components/schemas/Solver'
        ready:
          type: boolean
        requirements:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
            required:
              - code
              - message
            additionalProperties: false
        limits:
          type: object
        resource:
          type: object
        settings:
          $ref: '#/components/schemas/Settings'
        scene_id:
          type: string
          pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'
        scene_revision:
          type: integer
      description: ready confirms current admission only; physical convergence is separately qualified.
    ComplexPair:
      type: array
      items:
        type: number
      minItems: 2
      maxItems: 2
      description: '[real, imaginary]'
    Result:
      type: object
      required:
        - candidate
        - solver
        - frequencies_hz
        - s11
        - impedance_ohm
        - reference_ohm
        - evidence
        - resources
      properties:
        scene:
          $ref: '#/components/schemas/Scene'
        scene_ref:
          type: object
          properties:
            id:
              type: string
              pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$'
            revision:
              type: integer
          required:
            - id
            - revision
          additionalProperties: false
        candidate:
          $ref: '#/components/schemas/Candidate'
        solver:
          $ref: '#/components/schemas/Solver'
        frequencies_hz:
          type: array
          items:
            type: number
        s11:
          type: array
          items:
            $ref: '#/components/schemas/ComplexPair'
        impedance_ohm:
          type: array
          items:
            $ref: '#/components/schemas/ComplexPair'
        reference_ohm:
          const: 50
        evidence:
          type: object
        resources:
          type: object
      description: Public job records use scene_ref to the job scene. Exact frequency count/binding, finite complex data, passivity and S11/Z consistency are checked by native result admission. No synthetic RF example is supplied.
    Job:
      type: object
      required:
        - id
        - status
        - scene
        - solver
        - algorithm
        - candidates
        - progress
        - error
        - resources
      properties:
        id:
          type: string
          pattern: '^[a-f0-9]{32}$'
        status:
          enum:
            - queued
            - running
            - succeeded
            - failed
            - cancelled
            - interrupted
        scene:
          $ref: '#/components/schemas/Scene'
        solver:
          $ref: '#/components/schemas/Solver'
        algorithm:
          enum:
            - prepare
            - evaluate
            - ado
            - ga
        candidates:
          type: array
          items:
            type: object
            properties:
              candidate:
                $ref: '#/components/schemas/Candidate'
              result:
                $ref: '#/components/schemas/Result'
              score:
                type: object
            required:
              - candidate
              - result
              - score
            additionalProperties: true
        best_candidate_id:
          type:
            - string
            - 'null'
        progress:
          type: object
        error:
          type:
            - string
            - 'null'
        resources:
          type: object
      description: Durable job lifecycle record. Additional execution, budget, selection and provenance fields are retained.
    Catalog:
      type: object
      required:
        - schema
        - solvers
        - defaults
        - execution_defaults
        - metric_limits
      properties:
        schema:
          const: metaclaw.antenna-solvers/1
        solvers:
          type: array
          items:
            type: object
            properties:
              id:
                $ref: '#/components/schemas/Solver'
              label:
                type: string
              description:
                type: string
            required:
              - id
              - label
              - description
            additionalProperties: false
        defaults:
          type: object
        execution_defaults:
          $ref: '#/components/schemas/Settings'
        metric_limits:
          type: array
          items:
            type: string
        default_model:
          type:
            - string
            - 'null'
    JobSummary:
      type: object
      properties:
        id:
          type: string
          pattern: '^[a-f0-9]{32}$'
        solver:
          $ref: '#/components/schemas/Solver'
        algorithm:
          enum:
            - prepare
            - evaluate
            - ado
            - ga
        status:
          enum:
            - queued
            - running
            - succeeded
            - failed
            - cancelled
            - interrupted
        created_at:
          type: string
        best_candidate_id:
          type:
            - string
            - 'null'
      required:
        - id
        - solver
        - algorithm
        - status
        - created_at
        - best_candidate_id
      additionalProperties: false
    PreparedResourceSettings:
      type: object
      properties:
        seconds:
          type: integer
          minimum: 1
          maximum: 7200
          default: 600
        host_memory_bytes:
          type: integer
          minimum: 67108864
          maximum: 274877906944
          default: 34359738368
        device_memory_bytes:
          type: integer
          minimum: 67108864
          maximum: 137438953472
          default: 17179869184
        storage_bytes:
          type: integer
          minimum: 67108864
          maximum: 274877906944
          default: 68719476736
      required: []
      additionalProperties: false
      description: Bounded resources only. Executables, artifact paths, device and precision are trusted runtime configuration.
    FiniteWindowSettings:
      type: object
      properties:
        seconds:
          type: integer
          minimum: 1
          maximum: 7200
          default: 600
        host_memory_bytes:
          type: integer
          minimum: 67108864
          maximum: 274877906944
          default: 34359738368
        device_memory_bytes:
          type: integer
          minimum: 67108864
          maximum: 137438953472
          default: 17179869184
        storage_bytes:
          type: integer
          minimum: 67108864
          maximum: 274877906944
          default: 68719476736
        harp_mode:
          type: string
          enum:
          - direct
          - hybrid
          - reduced
          - adaptive
          default: reduced
        reduction_implementation:
          type: string
          enum:
          - auto
          - whole_device_window
          - local_response
          default: auto
          description: Within Reduced, auto uses the qualified whole-device finite-window model; local_response explicitly requests the native local reduction. Adaptive records all eligible alternatives and its actual selection.
      required: []
      additionalProperties: false
      description: No source, material, boundary, mesh, time-window, field-output or frequency override is accepted here. The selected prepared family fixes those inputs.
    FiniteWindowQuery:
      type: object
      properties:
        schema:
          const: metaclaw.harp-finite-window-query/1
        family_id:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$
        width_mm:
          type: number
          exclusiveMinimum: 0
        frequencies_hz:
          type: array
          minItems: 1
          maxItems: 10001
          items:
            type: number
            exclusiveMinimum: 0
          description: Copy the complete increasing frequency roster from the selected family catalog. It must match exactly.
        accuracy_policy:
          const: validated_points
        expected_evaluations:
          type: integer
          minimum: 1
          maximum: 1000000
          description: Expected number of complete evaluations of this same queried width. A changed width needs its own compatible plan.
      required:
      - schema
      - family_id
      - width_mm
      - frequencies_hz
      - accuracy_policy
      - expected_evaluations
      additionalProperties: false
      description: Path-free finite native-window request. Reduced admits exact measured passing widths only, not an interval or interpolated accuracy. The family fixes the physical model, source, window, precision and requested outputs. This is separate from the harmonic schema.
    HarmonicPreparedQuery:
      type: object
      properties:
        schema:
          const: metaclaw.harp-whole-device-query/1
        family_id:
          type: string
          pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$
        width_mm:
          type: number
          exclusiveMinimum: 0
        frequencies_hz:
          type: array
          minItems: 1
          maxItems: 10001
          items:
            type: number
            exclusiveMinimum: 0
          description: Copy the complete increasing frequency roster from the selected family catalog. It must match exactly.
        accuracy_policy:
          type: string
          enum:
          - diagnostic
          - engineering_validated_domain
          - certified_pointwise
      required:
      - schema
      - family_id
      - width_mm
      - frequencies_hz
      - accuracy_policy
      additionalProperties: false
      description: Existing continuous semidiscrete harmonic contract. Its policies require their own evidence and do not acquire finite-window qualification from this API extension.
    FiniteWindowRequest:
      type: object
      properties:
        query:
          $ref: '#/components/schemas/FiniteWindowQuery'
        settings:
          $ref: '#/components/schemas/FiniteWindowSettings'
      required:
      - query
      - settings
      additionalProperties: false
    HarmonicPreparedRequest:
      type: object
      properties:
        query:
          $ref: '#/components/schemas/HarmonicPreparedQuery'
        settings:
          $ref: '#/components/schemas/PreparedResourceSettings'
      required:
      - query
      - settings
      additionalProperties: false
    PreparedResponseRequest:
      oneOf:
      - $ref: '#/components/schemas/FiniteWindowRequest'
      - $ref: '#/components/schemas/HarmonicPreparedRequest'
    FiniteWindowContract:
      type: object
      properties:
        response_kind:
          const: native_staggered_rectangular_midpoint_finite_window
        dt_s:
          type: number
          exclusiveMinimum: 0
        sample_count:
          type: integer
          minimum: 1
        frequencies_hz:
          type: array
          minItems: 1
          maxItems: 10001
          items:
            type: number
            exclusiveMinimum: 0
          description: Copy the complete increasing frequency roster from the selected family catalog. It must match exactly.
        reference_impedance_ohm:
          type: number
          exclusiveMinimum: 0
        source_clock:
          const: (n+1/2)*dt
        window:
          const: rectangular
        dft_sign:
          const: negative
        precision:
          const: float64/complex128
        reduced_device:
          const: cpu
      required:
      - response_kind
      - dt_s
      - sample_count
      - frequencies_hz
      - reference_impedance_ohm
      - source_clock
      - window
      - dft_sign
      - precision
      - reduced_device
      description: The whole-device reduced response uses the saved finite-window source and exact projected native recurrence. Native local implementations report their own actual terminal clock separately. Numerical conditioning checks are not physical-convergence evidence.
      additionalProperties: true
    PreparedFamily:
      type: object
      properties:
        family_id:
          type: string
        available:
          type: boolean
        reason:
          type: string
        query_schema:
          type: string
          enum:
          - metaclaw.harp-finite-window-query/1
          - metaclaw.harp-whole-device-query/1
        model_id:
          type: string
        rank:
          type: integer
          minimum: 1
        full_dimension:
          type: integer
          minimum: 1
        width_bounds_mm:
          type: array
          items:
            type: number
          minItems: 2
          maxItems: 2
        frequencies_hz:
          type: array
          minItems: 1
          maxItems: 10001
          items:
            type: number
            exclusiveMinimum: 0
          description: Copy the complete increasing frequency roster from the selected family catalog. It must match exactly.
        qualified_widths_mm:
          type: array
          items:
            type: number
          description: Exact finite-window passing points; interval bounds do not qualify intermediate values.
        rejected_widths_mm:
          type: array
          items:
            type: number
        supported_modes:
          type: array
          items:
            type: string
            enum:
            - direct
            - hybrid
            - reduced
            - adaptive
        device:
          type: string
        window:
          $ref: '#/components/schemas/FiniteWindowContract'
        geometry:
          type: object
        accuracy_scope:
          oneOf:
          - type: string
          - type: object
        mode_readiness:
          type: object
          description: Availability of the prepared CPU model is distinct from admission and preparation of the configured native candidates.
      required:
      - family_id
      - available
      additionalProperties: true
      description: Unavailable entries retain a reason. Public metadata contains no trusted artifact paths or reference cases.
    PreparedFamilyCatalog:
      type: object
      properties:
        schema:
          const: metaclaw.harp-whole-device-families/1
        families:
          type: array
          items:
            $ref: '#/components/schemas/PreparedFamily'
      required:
      - schema
      - families
      additionalProperties: false
    FiniteWindowResult:
      type: object
      properties:
        schema:
          const: metaclaw.harp-finite-window-result/1
        query:
          $ref: '#/components/schemas/FiniteWindowQuery'
        actual_mode:
          type: string
          enum:
          - direct
          - hybrid
          - reduced
          - adaptive
        requested_mode:
          type: string
          enum:
          - direct
          - hybrid
          - reduced
          - adaptive
        implementation_mode:
          type: string
          enum:
          - direct
          - hybrid
          - hybrid_response
          - whole_device_window
        actual_device:
          type: string
          pattern: ^(cpu|cuda(:[0-9]+)?)$
          description: whole_device_window currently executes on CPU, including when Adaptive compares it with native CUDA candidates.
        precision:
          const: float64/complex128
        frequencies_hz:
          type: array
          minItems: 1
          maxItems: 10001
          items:
            type: number
            exclusiveMinimum: 0
          description: Copy the complete increasing frequency roster from the selected family catalog. It must match exactly.
        s11:
          type: array
          items:
            $ref: '#/components/schemas/ComplexPair'
        impedance_ohm:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/ComplexPair'
            - type: 'null'
          description: A flagged impedance pole is null; every unflagged value is a finite complex pair.
        impedance_pole:
          type: array
          items:
            type: boolean
        evidence:
          type: object
          properties:
            fresh_solve_count:
              type: integer
              minimum: 1
            planning_solve_count:
              type: integer
              minimum: 0
            production_solve_count:
              type: integer
              minimum: 0
            publication_origin:
              type: string
              enum:
              - fresh_production
              - fresh_selected_planning_trial
            physical_convergence:
              const: not_established
            mathematical_certificate:
              const: false
          required:
          - fresh_solve_count
          additionalProperties: true
        planning:
          type: object
          description: Measured candidate costs, actual selected implementation, exact-width cache provenance and retired owned-worker evidence. Required references and rejected alternatives stay charged to initial planning. A fresh selected planning trial may supply the first response; saved final results never supply a subsequent evaluation.
          additionalProperties: true
        timings_s:
          type: object
          additionalProperties:
            type: number
        accuracy_scope:
          type: object
          description: Empirical finite-window agreement is separate from temporal/spatial physical convergence.
        rank:
          type: integer
          minimum: 1
        full_dimension:
          type: integer
          minimum: 1
        model_id:
          type: string
        geometry:
          type: object
      required:
      - schema
      - query
      - actual_mode
      - implementation_mode
      - actual_device
      - precision
      - frequencies_hz
      - s11
      - impedance_ohm
      - impedance_pole
      - evidence
      - planning
      - timings_s
      - accuracy_scope
      - rank
      - full_dimension
      - model_id
      - geometry
      additionalProperties: true
      description: actual_mode is the requested logical mode; implementation_mode and actual_device identify executed work. Complete complex output is freshly calculated. No synthetic numerical response example is supplied.
    HarmonicPreparedResult:
      type: object
      properties:
        schema:
          const: metaclaw.harp-whole-device-result/1
        query:
          $ref: '#/components/schemas/HarmonicPreparedQuery'
        actual_mode:
          const: whole_device_rom
        actual_device:
          type: string
        frequencies_hz:
          type: array
          minItems: 1
          maxItems: 10001
          items:
            type: number
            exclusiveMinimum: 0
          description: Copy the complete increasing frequency roster from the selected family catalog. It must match exactly.
        s11:
          type: array
          items:
            $ref: '#/components/schemas/ComplexPair'
        impedance_ohm:
          type: array
          items:
            oneOf:
            - $ref: '#/components/schemas/ComplexPair'
            - type: 'null'
          description: A flagged impedance pole is null; every unflagged value is a finite complex pair.
        impedance_pole:
          type: array
          items:
            type: boolean
        evidence:
          type: object
          description: Includes the fresh solve count and harmonic reduced-only execution ledger.
      required:
      - schema
      - query
      - actual_mode
      - actual_device
      - frequencies_hz
      - s11
      - impedance_ohm
      - impedance_pole
      - evidence
      additionalProperties: true
    PreparedResponseJob:
      type: object
      properties:
        id:
          type: string
          pattern: ^[a-f0-9]{32}$
        status:
          type: string
          enum:
          - queued
          - running
          - succeeded
          - failed
          - cancelled
          - interrupted
        query:
          oneOf:
          - $ref: '#/components/schemas/FiniteWindowQuery'
          - $ref: '#/components/schemas/HarmonicPreparedQuery'
        settings:
          anyOf:
          - $ref: '#/components/schemas/FiniteWindowSettings'
          - $ref: '#/components/schemas/PreparedResourceSettings'
        result:
          oneOf:
          - $ref: '#/components/schemas/FiniteWindowResult'
          - $ref: '#/components/schemas/HarmonicPreparedResult'
          - type: 'null'
        error:
          type:
          - string
          - 'null'
        progress:
          type: object
        created_at:
          type: string
      required:
      - id
      - status
      - query
      - settings
      - result
      - error
      - progress
      additionalProperties: true
      description: Durable asynchronous job. Poll its status; a successful HTTP submission is not completion or scientific convergence. Restarted unfinished jobs become interrupted.
    PreparedResponseJobSummary:
      type: object
      properties:
        id:
          type: string
          pattern: ^[a-f0-9]{32}$
        status:
          type: string
          enum:
          - queued
          - running
          - succeeded
          - failed
          - cancelled
          - interrupted
        query:
          oneOf:
          - $ref: '#/components/schemas/FiniteWindowQuery'
          - $ref: '#/components/schemas/HarmonicPreparedQuery'
        settings:
          anyOf:
          - $ref: '#/components/schemas/FiniteWindowSettings'
          - $ref: '#/components/schemas/PreparedResourceSettings'
        created_at:
          type: string
        error:
          type:
          - string
          - 'null'
      required:
      - id
      - status
      - query
      - settings
      - created_at
      - error
      additionalProperties: false