"/cnc":
    get:
        tags: [CNC]
        operationId: cncHealth
        summary: CNC auth probe
        description: Health probe — returns the literal string `"OK"` if the caller's CNC credentials are valid.
        security:
            - cncMachineApiKey: []
              cncAccessToken: []
        responses:
            "200":
                description: Caller is authenticated.
                content:
                    text/plain:
                        schema:
                            type: string
                            example: OK
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [CncMachine, Fabricator]

"/cnc/next":
    put:
        tags: [CNC]
        operationId: cncStartNext
        summary: Pull the next CNC manufacturing job
        description: |
            Atomically claims the next available toolpath job for this CNC operator and
            returns the toolpath payload to execute on the machine.
        security:
            - cncMachineApiKey: []
              cncAccessToken: []
        responses:
            "200":
                description: Next manufacturing job's toolpath payload.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                jobId: { type: string }
                                toolPathId: { type: string }
                                waxId:
                                    type: string
                                    description: 20-bit BitField stamped on the wax block.
                                ipd: { type: integer }
                                gcode:
                                    type: string
                                    description: G-code body, filtered by the WaxId's bore bits.
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [CncMachine, Fabricator]

"/cnc/{toolPathId}":
    parameters:
        - in: path
          name: toolPathId
          required: true
          schema: { type: string }
          description: Toolpath id returned by `/cnc/next`.
    get:
        tags: [CNC]
        operationId: cncGetToolPathState
        summary: Read the current state of a toolpath
        description: Returns the persisted state of a toolpath job — used by the CNC operator to verify the server's view before reporting completion.
        security:
            - cncMachineApiKey: []
              cncAccessToken: []
        responses:
            "200":
                description: Current toolpath state record.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                id: { type: string }
                                jobId: { type: string }
                                state:
                                    type: string
                                    description: "e.g. `pending`, `started`, `paused`, `completed`, `error`."
                                waxId: { type: string }
                                operatorBigscreenAccountId: { type: string }
                                startedAt: { type: string, format: date-time }
                                completedAt: { type: [string, "null"], format: date-time }
                                lastUpdatedAt: { type: string, format: date-time }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [CncMachine, Fabricator]
    put:
        tags: [CNC]
        operationId: cncUpdateToolPathState
        summary: Update toolpath state from the CNC machine
        description: Reports state transitions from the CNC machine back to admin_api (started, paused, completed, error, etc.).
        security:
            - cncMachineApiKey: []
              cncAccessToken: []
        requestBody:
            required: false
            content:
                application/json:
                    schema:
                        type: object
                        additionalProperties: true
                        description: Free-form update payload — see handler at `FabricatorAdminApi.updateToolPathForCnc`.
        responses:
            "200":
                description: State updated.
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [CncMachine, Fabricator]
