ss-tools/specs/038-dashboard-scenario-model/contracts/scenario-api.openapi.yaml

openapi: 3.1.0
info:
  title: Dashboard Scenario Compiler API
  version: 0.1.0
servers:
  - url: /api/dashboard-testing
paths:
  /scenarios/compile:
    post:
      operationId: compileDashboardScenario
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CompileRequest' }
      responses:
        '200':
          description: Deterministic scenario plus validation
          content: { application/json: { schema: { $ref: '#/components/schemas/ScenarioResponse' } } }
        '422': { description: Invalid canonical inputs }
  /scenarios/validate:
    post:
      operationId: validateDashboardScenario
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: './dashboard-test-scenario.schema.json'
      responses:
        '200':
          description: Complete validation findings
          content: { application/json: { schema: { $ref: '#/components/schemas/ValidationResult' } } }
  /scenarios/{scenarioId}/resolve:
    post:
      operationId: resolveDashboardScenario
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: scenarioId, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ResolveRequest' }
      responses:
        '200':
          description: New immutable revision
          content: { application/json: { schema: { $ref: '#/components/schemas/ScenarioResponse' } } }
        '409': { description: Stale base revision }
        '422': { description: Invalid resolution }
  /scenarios/{scenarioId}/draft-pack:
    post:
      operationId: compileScenarioDraftPack
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: scenarioId, in: path, required: true, schema: { type: string } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [agent_run_id, revision_hash]
              properties:
                agent_run_id: { type: string, format: uuid }
                revision_hash: { type: string, pattern: '^[a-f0-9]{64}$' }
      responses:
        '201':
          description: Draft pack registered via feature 036
          content: { application/json: { schema: { $ref: '#/components/schemas/DraftPack' } } }
        '409': { description: Revision changed }
        '422': { description: Template, validation, or path failure }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }
  schemas:
    CompileRequest:
      type: object
      additionalProperties: false
      required: [agent_run_id, objective, query_model, checklist_catalog_version, baseline_version, capabilities, parameters]
      properties:
        agent_run_id: { type: string, format: uuid }
        objective:
          type: object
          required: [goal, selected_case_ids]
          properties:
            goal: { type: string, maxLength: 2000 }
            selected_case_ids: { type: array, items: { type: string } }
            rationale: { type: [string, 'null'], maxLength: 4000 }
        query_model: { type: object }
        checklist_catalog_version: { const: 1 }
        baseline_version: { type: string }
        capabilities: { type: object }
        parameters: { type: object }
    ValidationResult:
      type: object
      required: [valid, errors, warnings, blockers, coverage, topological_order, graph_hash]
      properties:
        valid: { type: boolean }
        errors: { type: array, items: { type: object } }
        warnings: { type: array, items: { type: object } }
        blockers: { type: array, items: { type: object } }
        coverage: { type: array, items: { type: object } }
        topological_order: { type: array, items: { type: string } }
        unresolved_parameters: { type: array, items: { type: string } }
        unresolved_selectors: { type: array, items: { type: string } }
        unresolved_baselines: { type: array, items: { type: string } }
        graph_hash: { type: string }
    ScenarioResponse:
      type: object
      required: [scenario, validation]
      properties:
        scenario: { $ref: './dashboard-test-scenario.schema.json' }
        validation: { $ref: '#/components/schemas/ValidationResult' }
    ResolveRequest:
      type: object
      additionalProperties: false
      required: [base_revision_hash, changes]
      properties:
        base_revision_hash: { type: string, pattern: '^[a-f0-9]{64}$' }
        changes:
          type: array
          items:
            type: object
            required: [kind, target, value]
            properties:
              kind: { enum: [parameter, selector, manual_conversion, remove_step] }
              target: { type: string }
              value: {}
              reason: { type: [string, 'null'] }
    DraftPack:
      type: object
      required: [scenario_revision_hash, template_version, status, manifest, artifacts, validation_summary, warnings]
      properties:
        scenario_revision_hash: { type: string }
        template_version: { type: string }
        status: { enum: [preview_only, save_eligible] }
        manifest: { type: object }
        artifacts: { type: array, items: { type: object } }
        validation_summary: { $ref: '#/components/schemas/ValidationResult' }
        warnings: { type: array, items: { type: object } }
    CaptureSpec:
      type: object
      required: [target, viewport, readiness, method]
      properties:
        target: { type: string, enum: [tab, viewport] }
        tab_identifier: { type: [string, 'null'] }
        viewport: { type: object, required: [width, height], properties: { width: { type: integer }, height: { type: integer } } }
        readiness: { type: string, enum: [canvas_stabilized, network_idle, fixed_wait] }
        readiness_timeout_ms: { type: integer, default: 15000 }
        mask_selectors: { type: array, items: { type: string } }
        method: { type: string, enum: [cdp, full_page, region] }
    VlmFinding:
      type: object
      required: [finding_id, source_artifact_id, severity, code, confidence, description, disposition, model_provenance]
      properties:
        finding_id: { type: string }
        source_artifact_id: { type: string, format: uuid }
        severity: { type: string, enum: [info, warning, error] }
        code: { type: string }
        region: { type: object }
        confidence: { type: number, minimum: 0, maximum: 1 }
        description: { type: string, maxLength: 1000 }
        disposition: { type: string, enum: [unresolved, confirmed, dismissed, inconclusive] }
        disposition_comment: { type: [string, 'null'], maxLength: 2000 }
        model_provenance:
          type: object
          required: [model_id, prompt_version, prompt_template_hash, analyzed_at]
          properties:
            model_id: { type: string }
            prompt_version: { type: string }
            prompt_template_hash: { type: string, pattern: '^[a-f0-9]{64}$' }
            analyzed_at: { type: string, format: date-time }