TenantAtlas/specs/226-astrodeck-inventory-planning/contracts/astrodeck-inventory.logical.openapi.yaml

openapi: 3.1.0
info:
  title: AstroDeck Inventory Logical Contract
  version: 0.1.0
  description: >-
    Logical planning contract for publishing and querying AstroDeck primitive inventory
    used by website rebuild mapping specs. This contract defines artifact shapes only
    for planning governance and does not imply runtime implementation in this feature.    
servers:
  - url: https://planning.local
paths:
  /inventory/catalogs:
    post:
      summary: Publish a new inventory catalog snapshot
      operationId: publishInventoryCatalog
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryCatalogCreateRequest'
      responses:
        '201':
          description: Catalog created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryCatalog'
  /inventory/catalogs/{catalogId}:
    get:
      summary: Retrieve one inventory catalog with entries
      operationId: getInventoryCatalog
      parameters:
        - name: catalogId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Catalog found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryCatalog'
  /inventory/catalogs/{catalogId}/summary:
    get:
      summary: Retrieve suitability and risk summary
      operationId: getInventorySuitabilitySummary
      parameters:
        - name: catalogId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Summary found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuitabilitySummary'
  /inventory/catalogs/{catalogId}/entries:
    get:
      summary: List inventory entries with optional filters
      operationId: listInventoryEntries
      parameters:
        - name: catalogId
          in: path
          required: true
          schema:
            type: string
        - name: primitiveClass
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/PrimitiveClass'
        - name: suitabilityClass
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/SuitabilityClass'
        - name: marker
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/Marker'
      responses:
        '200':
          description: Entries returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/InventoryEntry'
                required: [data]
components:
  schemas:
    PrimitiveClass:
      type: string
      enum: [Page, Section, Component]
    SuitabilityClass:
      type: string
      enum: [A, B, C, D]
    TenantAtlasRelevance:
      type: string
      enum: [high, medium, low, none]
    Marker:
      type: string
      enum:
        - tenantatlas-likely
        - needs-heavy-adaptation
        - visual-risk
        - semantic-risk
        - demo-only
        - remove-likely
        - hero-candidate
        - trust-candidate
        - navigation-candidate
        - footer-candidate
        - contact-candidate
        - product-explainer-candidate
        - changelog-candidate
    InventoryEntry:
      type: object
      required:
        - entryId
        - identifier
        - primitiveClass
        - fileRef
        - functionalRole
        - defaultSemantics
        - defaultVisualCharacter
        - tenantatlasRelevance
        - suitabilityClass
      properties:
        entryId:
          type: string
        identifier:
          type: string
        primitiveClass:
          $ref: '#/components/schemas/PrimitiveClass'
        fileRef:
          type: string
        functionalRole:
          type: string
        defaultSemantics:
          type: string
        defaultVisualCharacter:
          type: string
        tenantatlasRelevance:
          $ref: '#/components/schemas/TenantAtlasRelevance'
        suitabilityClass:
          $ref: '#/components/schemas/SuitabilityClass'
        markers:
          type: array
          items:
            $ref: '#/components/schemas/Marker'
        notes:
          type: string
    SuitabilitySummary:
      type: object
      required:
        - countA
        - countB
        - countC
        - countD
        - riskVisualCount
        - riskSemanticCount
        - demoOnlyCount
        - surfaceCandidates
      properties:
        countA:
          type: integer
          minimum: 0
        countB:
          type: integer
          minimum: 0
        countC:
          type: integer
          minimum: 0
        countD:
          type: integer
          minimum: 0
        riskVisualCount:
          type: integer
          minimum: 0
        riskSemanticCount:
          type: integer
          minimum: 0
        demoOnlyCount:
          type: integer
          minimum: 0
        surfaceCandidates:
          type: object
          required:
            - homepage
            - hero
            - product
            - trust
            - changelog
            - contactDemo
            - navigation
            - footer
          properties:
            homepage:
              type: array
              items:
                type: string
            hero:
              type: array
              items:
                type: string
            product:
              type: array
              items:
                type: string
            trust:
              type: array
              items:
                type: string
            changelog:
              type: array
              items:
                type: string
            contactDemo:
              type: array
              items:
                type: string
            navigation:
              type: array
              items:
                type: string
            footer:
              type: array
              items:
                type: string
    InventoryCatalog:
      type: object
      required:
        - catalogId
        - scope
        - createdAt
        - sourceCommit
        - status
        - entries
        - summary
      properties:
        catalogId:
          type: string
        scope:
          type: string
          const: apps/website
        createdAt:
          type: string
          format: date-time
        sourceCommit:
          type: string
        status:
          type: string
          enum: [draft, reviewed, baselined]
        entries:
          type: array
          items:
            $ref: '#/components/schemas/InventoryEntry'
        summary:
          $ref: '#/components/schemas/SuitabilitySummary'
    InventoryCatalogCreateRequest:
      type: object
      required:
        - catalogId
        - sourceCommit
        - entries
      properties:
        catalogId:
          type: string
        sourceCommit:
          type: string
        entries:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/InventoryEntry'