openapi: 3.1.0
info:
  title: Provider-neutral Artifact Source Taxonomy Logical Contract
  version: 0.1.0
  description: >-
    Logical GET surfaces and descriptor-first view models for the bounded 284
    artifact-source taxonomy slice.
paths:
  /logical/findings:
    get:
      summary: List findings with descriptor-first artifact summaries
      operationId: listFindingsWithArtifactSourceDescriptor
      responses:
        '200':
          description: Finding list page view model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindingListPage'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
  /logical/findings/{findingId}:
    get:
      summary: View one finding with descriptor-first artifact summary
      operationId: viewFindingWithArtifactSourceDescriptor
      parameters:
        - name: findingId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Finding detail view model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindingPage'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
  /logical/evidence-snapshots:
    get:
      summary: List evidence snapshots with descriptor-first summaries
      operationId: listEvidenceSnapshotsWithArtifactSourceDescriptor
      responses:
        '200':
          description: Evidence snapshot list page view model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvidenceSnapshotListPage'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
  /logical/evidence-snapshots/{snapshotId}:
    get:
      summary: View one evidence snapshot with descriptor-first item summaries
      operationId: viewEvidenceSnapshotWithArtifactSourceDescriptor
      parameters:
        - name: snapshotId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Evidence snapshot detail view model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EvidenceSnapshotPage'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
  /logical/stored-reports:
    get:
      summary: List stored reports with descriptor-first summaries
      operationId: listStoredReportsWithArtifactSourceDescriptor
      responses:
        '200':
          description: Stored report list page view model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredReportListPage'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
  /logical/stored-reports/{reportId}:
    get:
      summary: View one stored report with descriptor-first summary
      operationId: viewStoredReportWithArtifactSourceDescriptor
      parameters:
        - name: reportId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Stored report detail view model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoredReportPage'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
  /logical/inventory-items:
    get:
      summary: List inventory items with descriptor-first summaries
      operationId: listInventoryItemsWithArtifactSourceDescriptor
      responses:
        '200':
          description: Inventory item list page view model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryItemListPage'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
  /logical/inventory-items/{inventoryItemId}:
    get:
      summary: View one inventory item with canonical and provider type split
      operationId: viewInventoryItemWithArtifactSourceDescriptor
      parameters:
        - name: inventoryItemId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Inventory item detail view model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryItemPage'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
  /logical/tenant-reviews:
    get:
      summary: List tenant reviews with primary descriptor summaries
      operationId: listTenantReviewsWithArtifactSourceDescriptor
      responses:
        '200':
          description: Tenant review list page view model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantReviewListPage'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
  /logical/tenant-reviews/{reviewId}:
    get:
      summary: View one tenant review with descriptor-first artifact sections
      operationId: viewTenantReviewWithArtifactSourceSections
      parameters:
        - name: reviewId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Tenant review detail view model
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TenantReviewPage'
        '403':
          $ref: '#/components/responses/ForbiddenResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
components:
  responses:
    ForbiddenResponse:
      description: In-scope actor missing the required capability for the surface.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemResponse'
    NotFoundResponse:
      description: Workspace or managed-environment context is missing or out of scope for the actor.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemResponse'
  schemas:
    ProblemResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
        code:
          type:
            - string
            - 'null'
    ArtifactSourceDescriptor:
      type: object
      required:
        - workspace_id
        - tenant_id
        - source_family
        - source_kind
        - provider_key
        - managed_environment_id
        - source_target_kind
      properties:
        workspace_id:
          type: integer
          description: Derived workspace scope anchor for the artifact.
        tenant_id:
          type: integer
          description: Derived tenant scope anchor for the artifact.
        source_family:
          type: string
          enum:
            - finding
            - stored_report
            - evidence_snapshot
            - inventory
            - operation_run
        source_kind:
          type: string
          enum:
            - model_summary
            - stored_report
            - operation_rollup
            - inventory_projection
        provider_key:
          type: string
          description: Current repo truth emits `microsoft` only.
        provider_connection_id:
          type:
            - integer
            - 'null'
        managed_environment_id:
          type: integer
          description: Required managed-environment anchor inside the derived workspace and tenant scope.
        source_target_kind:
          type: string
          enum:
            - managed_environment
            - governed_subject
            - provider_connection
            - operation_run
        source_target_identifier:
          type:
            - string
            - 'null'
        detector_key:
          type:
            - string
            - 'null'
          description: >-
            Standardized field only. 284 does not define a closed detector
            catalog.
        control_key:
          type:
            - string
            - 'null'
        package_run_id:
          type:
            - integer
            - 'null'
          description: Optional future package hook. Remains null in current runtime.
    InventoryTypeDescriptor:
      type: object
      required:
        - canonical_type
        - provider_object_type
        - provider_display_type
      properties:
        canonical_type:
          type: string
        provider_object_type:
          type: string
        provider_display_type:
          type: string
        legacy_policy_type:
          type:
            - string
            - 'null'
    ArtifactProviderDetail:
      type: object
      properties:
        legacy_finding_type:
          type:
            - string
            - 'null'
        legacy_report_type:
          type:
            - string
            - 'null'
        legacy_policy_type:
          type:
            - string
            - 'null'
        provider_object_type:
          type:
            - string
            - 'null'
        provider_display_type:
          type:
            - string
            - 'null'
        detector_detail:
          type:
            - string
            - 'null'
    CanonicalControlSummary:
      type: object
      required:
        - control_key
      properties:
        control_key:
          type: string
        label:
          type:
            - string
            - 'null'
        status:
          type:
            - string
            - 'null'
    FreshnessSummary:
      type: object
      additionalProperties: true
      description: Existing freshness or timing metadata carried through descriptor-first summaries.
    FindingArtifactSummary:
      type: object
      required:
        - id
        - title
        - severity
        - status
        - source_descriptor
      properties:
        id:
          type: integer
        title:
          type: string
        severity:
          type: string
        status:
          type: string
        source_descriptor:
          $ref: '#/components/schemas/ArtifactSourceDescriptor'
        provider_detail:
          $ref: '#/components/schemas/ArtifactProviderDetail'
        control_summary:
          oneOf:
            - $ref: '#/components/schemas/CanonicalControlSummary'
            - type: 'null'
        freshness:
          oneOf:
            - $ref: '#/components/schemas/FreshnessSummary'
            - type: 'null'
    FindingListPage:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FindingArtifactSummary'
    FindingPage:
      type: object
      required:
        - finding
      properties:
        finding:
          $ref: '#/components/schemas/FindingArtifactSummary'
    EvidenceSnapshotListEntry:
      type: object
      required:
        - id
        - managed_environment_id
        - source_descriptor
      properties:
        id:
          type: integer
        managed_environment_id:
          type: integer
        source_descriptor:
          $ref: '#/components/schemas/ArtifactSourceDescriptor'
        control_summary:
          oneOf:
            - $ref: '#/components/schemas/CanonicalControlSummary'
            - type: 'null'
        freshness:
          oneOf:
            - $ref: '#/components/schemas/FreshnessSummary'
            - type: 'null'
    EvidenceSnapshotListPage:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/EvidenceSnapshotListEntry'
    EvidenceSnapshotItemViewModel:
      type: object
      required:
        - dimension_key
        - state
        - source_descriptor
      properties:
        dimension_key:
          type: string
        state:
          type: string
        source_descriptor:
          $ref: '#/components/schemas/ArtifactSourceDescriptor'
        provider_detail:
          $ref: '#/components/schemas/ArtifactProviderDetail'
        control_summary:
          oneOf:
            - $ref: '#/components/schemas/CanonicalControlSummary'
            - type: 'null'
        freshness:
          oneOf:
            - $ref: '#/components/schemas/FreshnessSummary'
            - type: 'null'
    EvidenceSnapshotPage:
      type: object
      required:
        - id
        - managed_environment_id
        - items
      properties:
        id:
          type: integer
        managed_environment_id:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/EvidenceSnapshotItemViewModel'
        freshness:
          oneOf:
            - $ref: '#/components/schemas/FreshnessSummary'
            - type: 'null'
    StoredReportPage:
      type: object
      required:
        - id
        - summary
        - source_descriptor
      properties:
        id:
          type: integer
        summary:
          type: string
        source_descriptor:
          $ref: '#/components/schemas/ArtifactSourceDescriptor'
        provider_detail:
          $ref: '#/components/schemas/ArtifactProviderDetail'
        control_summary:
          oneOf:
            - $ref: '#/components/schemas/CanonicalControlSummary'
            - type: 'null'
        freshness:
          oneOf:
            - $ref: '#/components/schemas/FreshnessSummary'
            - type: 'null'
    StoredReportListEntry:
      type: object
      required:
        - id
        - summary
        - source_descriptor
      properties:
        id:
          type: integer
        summary:
          type: string
        source_descriptor:
          $ref: '#/components/schemas/ArtifactSourceDescriptor'
        freshness:
          oneOf:
            - $ref: '#/components/schemas/FreshnessSummary'
            - type: 'null'
    StoredReportListPage:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/StoredReportListEntry'
    InventoryItemPage:
      type: object
      required:
        - id
        - display_name
        - type_descriptor
        - source_descriptor
      properties:
        id:
          type: integer
        display_name:
          type: string
        type_descriptor:
          $ref: '#/components/schemas/InventoryTypeDescriptor'
        source_descriptor:
          $ref: '#/components/schemas/ArtifactSourceDescriptor'
        provider_detail:
          $ref: '#/components/schemas/ArtifactProviderDetail'
    InventoryItemListEntry:
      type: object
      required:
        - id
        - display_name
        - type_descriptor
        - source_descriptor
      properties:
        id:
          type: integer
        display_name:
          type: string
        type_descriptor:
          $ref: '#/components/schemas/InventoryTypeDescriptor'
        source_descriptor:
          $ref: '#/components/schemas/ArtifactSourceDescriptor'
    InventoryItemListPage:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/InventoryItemListEntry'
    TenantReviewArtifactSection:
      type: object
      required:
        - section_key
        - headline
        - source_descriptor
      properties:
        section_key:
          type: string
        headline:
          type: string
        source_descriptor:
          $ref: '#/components/schemas/ArtifactSourceDescriptor'
        provider_detail:
          $ref: '#/components/schemas/ArtifactProviderDetail'
        control_summary:
          oneOf:
            - $ref: '#/components/schemas/CanonicalControlSummary'
            - type: 'null'
        freshness:
          oneOf:
            - $ref: '#/components/schemas/FreshnessSummary'
            - type: 'null'
    TenantReviewListEntry:
      type: object
      required:
        - id
        - status
        - source_descriptor
      properties:
        id:
          type: integer
        status:
          type: string
        source_descriptor:
          $ref: '#/components/schemas/ArtifactSourceDescriptor'
        freshness:
          oneOf:
            - $ref: '#/components/schemas/FreshnessSummary'
            - type: 'null'
    TenantReviewListPage:
      type: object
      required:
        - items
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TenantReviewListEntry'
    TenantReviewPage:
      type: object
      required:
        - id
        - status
        - sections
      properties:
        id:
          type: integer
        status:
          type: string
        sections:
          type: array
          items:
            $ref: '#/components/schemas/TenantReviewArtifactSection'