openapi: 3.1.0
info:
  title: CI Lane Governance Logical Contract
  version: 1.0.0
  description: |
    Logical contract for Spec 210. This is not a public runtime API.
    It documents the semantics that checked-in Gitea workflows, repo-root wrappers,
    and test-governance support classes must satisfy together.
paths:
  /logical/ci/workflows/{workflowId}/execute:
    post:
      summary: Execute one governed CI workflow path
      operationId: executeWorkflowProfile
      parameters:
        - name: workflowId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowExecutionRequest'
      responses:
        '200':
          description: Workflow execution plan resolved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowExecutionResult'
  /logical/ci/lanes/{laneId}/evaluate-budget:
    post:
      summary: Evaluate one lane budget under a trigger-specific CI policy
      operationId: evaluateLaneBudget
      parameters:
        - name: laneId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BudgetEvaluationRequest'
      responses:
        '200':
          description: Budget evaluation returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetEvaluationResult'
  /logical/ci/lanes/{laneId}/stage-artifacts:
    post:
      summary: Stage lane artifacts into a deterministic upload directory
      operationId: stageLaneArtifacts
      parameters:
        - name: laneId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArtifactStagingRequest'
      responses:
        '200':
          description: Artifact staging completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArtifactStagingResult'
  /logical/ci/runs/{runId}/summary:
    get:
      summary: Read the normalized CI run summary for one governed lane execution
      operationId: readRunSummary
      parameters:
        - name: runId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Run summary returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CiRunSummary'
components:
  schemas:
    WorkflowExecutionRequest:
      type: object
      additionalProperties: false
      required:
        - triggerClass
        - gitRef
        - runnerLabel
      properties:
        triggerClass:
          type: string
          enum:
            - pull-request
            - mainline-push
            - scheduled
            - manual
        gitRef:
          type: string
        runnerLabel:
          type: string
        requestedLanes:
          type: array
          items:
            type: string
    WorkflowExecutionResult:
      type: object
      additionalProperties: false
      required:
        - workflowId
        - laneExecutions
      properties:
        workflowId:
          type: string
        laneExecutions:
          type: array
          items:
            $ref: '#/components/schemas/LaneExecutionPlan'
    LaneExecutionPlan:
      type: object
      additionalProperties: false
      required:
        - laneId
        - executionWrapper
        - requiredArtifacts
        - budgetPolicy
      properties:
        laneId:
          type: string
        executionWrapper:
          type: string
        reportWrapper:
          type: string
        requiredArtifacts:
          type: array
          items:
            type: string
        budgetPolicy:
          $ref: '#/components/schemas/BudgetPolicy'
    BudgetPolicy:
      type: object
      additionalProperties: false
      required:
        - thresholdSource
        - effectiveThresholdSeconds
        - enforcementMode
      properties:
        thresholdSource:
          type: string
          enum:
            - lane-budget
            - governance-contract
        effectiveThresholdSeconds:
          type: number
        varianceAllowanceSeconds:
          type: number
        enforcementMode:
          type: string
          enum:
            - hard-fail
            - soft-warn
            - trend-only
        lifecycleState:
          type: string
    BudgetEvaluationRequest:
      type: object
      additionalProperties: false
      required:
        - triggerClass
        - measuredSeconds
      properties:
        triggerClass:
          type: string
        measuredSeconds:
          type: number
    BudgetEvaluationResult:
      type: object
      additionalProperties: false
      required:
        - laneId
        - budgetStatus
        - blockingStatus
      properties:
        laneId:
          type: string
        budgetStatus:
          type: string
          enum:
            - within-budget
            - warning
            - over-budget
        blockingStatus:
          type: string
          enum:
            - blocking
            - non-blocking-warning
            - informational
        primaryFailureClassId:
          type:
            - string
            - 'null'
    ArtifactStagingRequest:
      type: object
      additionalProperties: false
      required:
        - workflowId
        - laneId
        - sourceDirectory
        - stagingDirectory
      properties:
        workflowId:
          type: string
        laneId:
          type: string
        sourceDirectory:
          type: string
        stagingDirectory:
          type: string
        sourcePatterns:
          type: array
          items:
            type: string
    ArtifactStagingResult:
      type: object
      additionalProperties: false
      required:
        - laneId
        - stagedArtifacts
        - complete
      properties:
        laneId:
          type: string
        stagedArtifacts:
          type: array
          items:
            $ref: '#/components/schemas/ArtifactRecord'
        complete:
          type: boolean
        primaryFailureClassId:
          type:
            - string
            - 'null'
    ArtifactRecord:
      type: object
      additionalProperties: false
      required:
        - artifactType
        - relativePath
      properties:
        artifactType:
          type: string
        relativePath:
          type: string
        required:
          type: boolean
    CiRunSummary:
      type: object
      additionalProperties: false
      required:
        - runId
        - workflowId
        - laneId
        - testStatus
        - artifactStatus
        - blockingStatus
      properties:
        runId:
          type: string
        workflowId:
          type: string
        laneId:
          type: string
        testStatus:
          type: string
          enum:
            - passed
            - failed
        artifactStatus:
          type: string
          enum:
            - complete
            - incomplete
        budgetStatus:
          type: string
          enum:
            - within-budget
            - warning
            - over-budget
        blockingStatus:
          type: string
          enum:
            - blocking
            - non-blocking-warning
            - informational
        primaryFailureClassId:
          type:
            - string
            - 'null'
        publishedArtifacts:
          type: array
          items:
            $ref: '#/components/schemas/ArtifactRecord'