openapi: 3.0.3
info:
  title: Settings Foundation (097)
  version: 0.1.0
  description: |
    Conceptual contract for workspace settings read/write/reset.

    NOTE: The first implementation is expected to be driven via Filament/Livewire.
    This contract documents the expected domain behaviors (RBAC-UX 404/403 semantics,
    precedence, validation) for consistency and testability.

servers:
  - url: https://example.invalid

paths:
  /workspaces/{workspaceId}/settings/{domain}/{key}:
    get:
      summary: Resolve a setting value
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/Domain'
        - $ref: '#/components/parameters/Key'
        - name: tenantId
          in: query
          required: false
          schema:
            type: integer
          description: Optional tenant scope for tenant override resolution.
      responses:
        '200':
          description: Effective value (with source metadata)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvedSetting'
        '404':
          description: Not found (non-member workspace scope)
        '403':
          description: Forbidden (member without view capability)

    patch:
      summary: Set workspace override (manage capability required)
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/Domain'
        - $ref: '#/components/parameters/Key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettingWrite'
      responses:
        '200':
          description: Updated effective value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvedSetting'
        '422':
          description: Validation error (unknown key, wrong type, out-of-range)
        '404':
          description: Not found (non-member workspace scope)
        '403':
          description: Forbidden (member without manage capability)

    delete:
      summary: Reset workspace override to system default (manage capability required)
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/Domain'
        - $ref: '#/components/parameters/Key'
      responses:
        '204':
          description: Reset completed
        '404':
          description: Not found (non-member workspace scope)
        '403':
          description: Forbidden (member without manage capability)

  /workspaces/{workspaceId}/tenants/{tenantId}/settings/{domain}/{key}:
    patch:
      summary: Set tenant override (backend-ready)
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/Domain'
        - $ref: '#/components/parameters/Key'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SettingWrite'
      responses:
        '200':
          description: Updated effective value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResolvedSetting'
        '422':
          description: Validation error
        '404':
          description: Not found (non-member workspace scope or tenant/workspace mismatch)
        '403':
          description: Forbidden (member without manage capability)

components:
  parameters:
    WorkspaceId:
      name: workspaceId
      in: path
      required: true
      schema:
        type: integer
    TenantId:
      name: tenantId
      in: path
      required: true
      schema:
        type: integer
    Domain:
      name: domain
      in: path
      required: true
      schema:
        type: string
        example: backup
    Key:
      name: key
      in: path
      required: true
      schema:
        type: string
        example: retention_keep_last_default

  schemas:
    SettingWrite:
      type: object
      additionalProperties: false
      required: [value]
      properties:
        value:
          description: JSON-serializable value. Validated against the server-side registry.

    ResolvedSetting:
      type: object
      additionalProperties: false
      required: [domain, key, value, source]
      properties:
        domain:
          type: string
        key:
          type: string
        value:
          description: Effective value
        source:
          type: string
          enum: [system_default, workspace_override, tenant_override]
        system_default:
          description: The registry default for reference
        workspace_value:
          nullable: true
          description: The workspace override value if present
        tenant_value:
          nullable: true
          description: The tenant override value if present