openapi.yaml

# OpenWatch — Stage-0 OpenAPI manifest.
#
# Self-contained 3-endpoint surface that oapi-codegen turns into typed
# Go server stubs. The full 14-domain manifest lives in openapi.full.yaml
# for Stage 2+ reference.
#
# Endpoints:
#   GET  /api/v1/health                — anonymous liveness probe
#   POST /api/v1/diagnostics:echo      — exercises idempotency + audit
#   GET  /api/v1/audit/events          — cursor-paginated audit list
#
# Specs:
#   app/specs/api/health.spec.yaml
#   app/specs/api/diagnostics-echo.spec.yaml
#   app/specs/api/audit-events-query.spec.yaml

openapi: 3.0.3

info:
  title: OpenWatch (Stage 0)
  version: 0.1.0-alpha.1
  description: |
    Stage 0 walking-skeleton surface — three endpoints that exercise the
    foundation stack (correlation, idempotency, audit, error envelope).

servers:
  - url: https://localhost:8443
    description: Local development

paths:

  /api/v1/auth/login:
    post:
      operationId: postAuthLogin
      summary: Username/password login with optional TOTP
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/AuthLoginRequest'}
      responses:
        '200':
          description: Login succeeded; tokens issued
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AuthLoginResponse'}
        '401':
          description: Invalid credentials or MFA required
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/auth/logout:
    post:
      operationId: postAuthLogout
      summary: Revoke the calling session
      responses:
        '204':
          description: Session revoked

  /api/v1/auth/refresh:
    post:
      operationId: postAuthRefresh
      summary: Rotate the refresh token; mint a new access+refresh pair
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/AuthRefreshRequest'}
      responses:
        '200':
          description: New token pair issued
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AuthLoginResponse'}
        '401':
          description: Refresh token invalid, expired, or reused (cascade revoke triggered)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/auth/refresh-cookie:
    post:
      operationId: postAuthRefreshCookie
      summary: Rotate the refresh cookie and mint a new session (browser flow)
      description: >
        Reads the HttpOnly `openwatch_refresh` cookie, rotates the underlying
        refresh token, mints a new session, and Set-Cookies both the rotated
        refresh cookie and a fresh `openwatch_session`. Used by the browser
        API client as the transparent on-401 retry hook so users with a live
        refresh window don't get bounced to /login on every inactivity timeout.
      security: []
      responses:
        '200':
          description: Cookies rotated; identity returned
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AuthMeResponse'}
        '401':
          description: Refresh cookie missing, invalid, expired, or reused. Both auth cookies are cleared.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/auth/me:
    get:
      operationId: getAuthMe
      summary: Return the calling identity
      responses:
        '200':
          description: Identity
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AuthMeResponse'}
        '401':
          description: No valid session or bearer
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/users/me/preferences:
    get:
      operationId: getUsersMePreferences
      summary: Return the calling user's UI preferences
      description: >
        Per-user UI preferences (e.g. the /hosts grid-vs-table default).
        Self-scoped — any authenticated identity reads its own; no special
        permission. Unset keys are simply absent (the client falls back to
        its defaults). Spec system-user-preferences + api-user-preferences.
      responses:
        '200':
          description: The caller's stored preferences
          content:
            application/json:
              schema: {$ref: '#/components/schemas/UserPreferences'}
        '401':
          description: No valid session or bearer
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    patch:
      operationId: patchUsersMePreferences
      summary: Merge a partial update into the calling user's UI preferences
      description: >
        Shallow-merges the provided keys into the caller's stored
        preferences and returns the merged result. Only the keys present in
        the body are changed; omitted keys are retained. Self-scoped.
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/UserPreferences'}
      responses:
        '200':
          description: The merged preferences
          content:
            application/json:
              schema: {$ref: '#/components/schemas/UserPreferences'}
        '400':
          description: Malformed body
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '401':
          description: No valid session or bearer
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/auth/mfa:enroll:
    post:
      operationId: postAuthMFAEnroll
      summary: Enroll the calling user in TOTP MFA
      responses:
        '200':
          description: Provisioning URI returned for the authenticator app
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AuthMFAEnrollResponse'}

  /api/v1/auth/mfa:verify:
    post:
      operationId: postAuthMFAVerify
      summary: Confirm an enrolled MFA secret by verifying a generated OTP
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/AuthMFAVerifyRequest'}
      responses:
        '204':
          description: MFA verified
        '401':
          description: MFA OTP invalid or replayed
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/auth/password:change:
    post:
      operationId: postAuthPasswordChange
      summary: Change the calling user's password
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/AuthPasswordChangeRequest'}
      responses:
        '204':
          description: Password updated
        '401':
          description: Current password wrong
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '400':
          description: New password rejected by policy
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/health:
    get:
      operationId: getHealth
      summary: Liveness + readiness probe (anonymous)
      security: []
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HealthResponse'}
        '503':
          description: Service is degraded or unavailable
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/version:
    get:
      operationId: getVersion
      summary: Build/version metadata (anonymous)
      security: []
      responses:
        '200':
          description: Version metadata for this deployment
          content:
            application/json:
              schema: {$ref: '#/components/schemas/VersionResponse'}

  /api/v1/diagnostics:echo:
    post:
      operationId: postDiagnosticsEcho
      summary: Echo the request message; exercises idempotency + audit
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: {type: string, minLength: 1, maxLength: 255}
        - name: X-Correlation-Id
          in: header
          required: false
          schema: {type: string}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/EchoRequest'}
      responses:
        '200':
          description: Echo succeeded
          content:
            application/json:
              schema: {$ref: '#/components/schemas/EchoResponse'}
        '400':
          $ref: '#/components/responses/BadRequest'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '409':
          description: Idempotency-Key reused with different body
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/license:
    get:
      operationId: getLicense
      summary: Get the current license state (tier, features, quotas, status)
      responses:
        '200':
          description: License state
          content:
            application/json:
              schema: {$ref: '#/components/schemas/LicenseStateResponse'}

  /api/v1/admin/license:verify:
    post:
      operationId: postAdminLicenseVerify
      summary: Dry-run validate a JWT license without installing it
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/LicenseVerifyRequest'}
      responses:
        '200':
          description: Verification result (success or typed failure)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/LicenseVerifyResponse'}

  /api/v1/diagnostics:premium-echo:
    post:
      operationId: postDiagnosticsPremiumEcho
      summary: License-gated echo; requires premium_diagnostics feature
      x-required-feature: premium_diagnostics
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: {type: string, minLength: 1, maxLength: 255}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/EchoRequest'}
      responses:
        '200':
          description: Echoed
          content:
            application/json:
              schema: {$ref: '#/components/schemas/EchoResponse'}
        '402':
          description: License does not include premium_diagnostics feature
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/diagnostics:require-host-read:
    post:
      operationId: postDiagnosticsRequireHostRead
      summary: Stage-0 RBAC demo; requires host:read permission
      x-required-permission: host:read
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: {type: string, minLength: 1, maxLength: 255}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/EchoRequest'}
      responses:
        '200':
          description: Echoed (caller holds host:read)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/EchoResponse'}
        '403':
          description: Caller lacks host:read
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/diagnostics:require-host-write:
    post:
      operationId: postDiagnosticsRequireHostWrite
      summary: Stage-0 RBAC demo; requires host:write permission
      x-required-permission: host:write
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: {type: string, minLength: 1, maxLength: 255}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/EchoRequest'}
      responses:
        '200':
          description: Echoed (caller holds host:write)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/EchoResponse'}
        '403':
          description: Caller lacks host:write
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/diagnostics:evaluate-alert:
    post:
      operationId: postDiagnosticsEvaluateAlert
      summary: Stage-0 policy demo; evaluates the alert_thresholds policy
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/EvaluateAlertRequest'}
      responses:
        '200':
          description: Policy decision
          content:
            application/json:
              schema: {$ref: '#/components/schemas/PolicyDecisionResponse'}

  /api/v1/diagnostics:enqueue-test-job:
    post:
      operationId: postDiagnosticsEnqueueTestJob
      summary: Stage-0 queue demo; enqueues a no-op job processed by the in-process worker
      responses:
        '202':
          description: Job accepted; worker will drain
          content:
            application/json:
              schema: {$ref: '#/components/schemas/EnqueueTestJobResponse'}

  /api/v1/admin/policies:reload:
    post:
      operationId: postAdminPoliciesReload
      summary: Reload signed policy files from the configured directory
      x-required-permission: policy:reload
      responses:
        '200':
          description: Per-type reload outcomes
          content:
            application/json:
              schema: {$ref: '#/components/schemas/PoliciesReloadResponse'}
        '403':
          description: Caller lacks policy:reload
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/diagnostics:require-remediation-execute:
    post:
      operationId: postDiagnosticsRequireRemediationExecute
      summary: Stage-0 RBAC+license demo; requires remediation:execute (RBAC) + premium_diagnostics (license)
      x-required-permission: remediation:execute
      x-required-feature: premium_diagnostics
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: {type: string, minLength: 1, maxLength: 255}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/EchoRequest'}
      responses:
        '200':
          description: Echoed
          content:
            application/json:
              schema: {$ref: '#/components/schemas/EchoResponse'}
        '402':
          description: License does not include remediation_execution
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks remediation:execute
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/auth/me/permissions:
    get:
      operationId: getAuthMePermissions
      summary: Effective permissions for the calling identity
      responses:
        '200':
          description: Permission list
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AuthMePermissionsResponse'}

  /api/v1/auth/permissions:registry:
    get:
      operationId: getAuthPermissionsRegistry
      summary: Full RBAC registry (categories, permissions, built-in roles)
      responses:
        '200':
          description: Registry
          content:
            application/json:
              schema: {$ref: '#/components/schemas/PermissionsRegistryResponse'}

  /api/v1/users:
    get:
      operationId: getUsers
      summary: List users
      x-required-permission: user:read
      responses:
        '200':
          description: User list
          content:
            application/json:
              schema: {$ref: '#/components/schemas/UsersListResponse'}
        '403':
          description: Caller lacks user:read
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    post:
      operationId: postUsers
      summary: Create a user
      x-required-permission: user:write
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/UserCreateRequest'}
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema: {$ref: '#/components/schemas/UserResponse'}
        '400':
          description: Validation or policy failure
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks user:write
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/users/{id}:
    get:
      operationId: getUserByID
      summary: Fetch a user
      x-required-permission: user:read
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200':
          description: User
          content:
            application/json:
              schema: {$ref: '#/components/schemas/UserResponse'}
        '404':
          description: User not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    delete:
      operationId: deleteUserByID
      summary: Soft-delete a user
      x-required-permission: user:delete
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '204':
          description: Deleted
        '404':
          description: User not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/users/{id}/roles:assign:
    post:
      operationId: postUserRolesAssign
      summary: Assign a role to a user
      x-required-permission: role:assign
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/UserRoleAssignRequest'}
      responses:
        '204':
          description: Role assigned
        '400':
          description: Unknown role id
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/users/{id}/roles:unassign:
    post:
      operationId: postUserRolesUnassign
      summary: Remove a role from a user
      x-required-permission: role:assign
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/UserRoleAssignRequest'}
      responses:
        '204':
          description: Role removed (idempotent)

  /api/v1/users/{id}:reset-password:
    post:
      operationId: postUserResetPassword
      summary: Admin-reset a user's password (own or another's)
      description: |
        Sets a user's password on administrator authority - no current
        password required. The new password runs through the role-aware
        policy + breach screen; the target's active sessions are revoked so
        they must re-authenticate. RBAC: admin:user_manage. Spec api-users.
      x-required-permission: admin:user_manage
      x-audit-events: [admin.user.password_reset]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/UserPasswordResetRequest'}
      responses:
        '204':
          description: Password reset; the target's sessions were revoked
        '400':
          description: New password rejected by policy (too short/long/breached)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks admin:user_manage permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: User not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/users/{id}:disable:
    post:
      operationId: postUserDisable
      summary: Disable a user account
      description: |
        Marks the account disabled: it can no longer authenticate (login is
        rejected) and the user's active sessions are revoked immediately. An
        admin cannot disable their own account (lockout prevention, 409).
        RBAC: admin:user_manage. Spec api-users.
      x-required-permission: admin:user_manage
      x-audit-events: [admin.user.disabled]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200':
          description: The disabled user
          content:
            application/json:
              schema: {$ref: '#/components/schemas/UserResponse'}
        '403':
          description: Caller lacks admin:user_manage permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: User not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Cannot disable your own account
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/users/{id}:enable:
    post:
      operationId: postUserEnable
      summary: Re-enable a disabled user account
      description: |
        Clears the disabled flag so the user can authenticate again with a
        fresh login (sessions revoked while disabled stay dead). RBAC:
        admin:user_manage. Spec api-users.
      x-required-permission: admin:user_manage
      x-audit-events: [admin.user.enabled]
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200':
          description: The re-enabled user
          content:
            application/json:
              schema: {$ref: '#/components/schemas/UserResponse'}
        '403':
          description: Caller lacks admin:user_manage permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: User not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/roles:create:
    post:
      operationId: postRolesCreate
      summary: Create a custom role
      x-required-permission: role:write
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CustomRoleCreateRequest'}
      responses:
        '201':
          description: Custom role created
          content:
            application/json:
              schema: {$ref: '#/components/schemas/CustomRoleResponse'}
        '400':
          description: Permission unknown
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Role id taken
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/roles:
    get:
      operationId: getRoles
      summary: List built-in roles
      x-required-permission: role:read
      responses:
        '200':
          description: Role list
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AdminRolesResponse'}
        '403':
          description: Caller lacks role:read
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/credentials:
    get:
      operationId: getCredentials
      summary: List credentials (metadata only)
      x-required-permission: credential:read
      responses:
        '200':
          description: Credential metadata list
          content:
            application/json:
              schema: {$ref: '#/components/schemas/CredentialListResponse'}
        '403':
          description: Caller lacks credential:read
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    post:
      operationId: postCredentials
      summary: Create a credential
      x-required-permission: credential:write
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CredentialCreateRequest'}
      responses:
        '201':
          description: Credential created
          content:
            application/json:
              schema: {$ref: '#/components/schemas/CredentialResponse'}
        '400':
          description: Validation, invalid scope, host not found, or invalid SSH key
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Multiple system defaults
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/credentials/{id}:
    get:
      operationId: getCredentialByID
      summary: Fetch a credential's metadata
      x-required-permission: credential:read
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200':
          description: Credential metadata
          content:
            application/json:
              schema: {$ref: '#/components/schemas/CredentialResponse'}
        '404':
          description: Credential not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    patch:
      operationId: patchCredentialByID
      summary: Update a credential in place
      description: >
        Partial update of an existing active credential. Only the fields
        present in the body change; omitted fields are left untouched.
        Secret material (password, private_key, private_key_passphrase)
        is re-encrypted only when a non-empty value is supplied — omitting
        a secret keeps the stored ciphertext, so metadata can be edited
        without re-entering the key or password. scope and scope_id are
        immutable. Setting is_default=true on a system credential atomically
        demotes the previous system default.
      x-required-permission: credential:write
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CredentialUpdateRequest'}
      responses:
        '200':
          description: Updated credential metadata
          content:
            application/json:
              schema: {$ref: '#/components/schemas/CredentialResponse'}
        '400':
          description: Validation failure (unknown auth_method, missing required secret)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Credential not found or already soft-deleted
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: is_default=true collides with an existing system default
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    delete:
      operationId: deleteCredentialByID
      summary: Soft-delete a credential
      x-required-permission: credential:delete
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '204':
          description: Deleted (is_active=false)
        '404':
          description: Credential not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/credentials/{id}:clone:
    post:
      operationId: postCredentialClone
      summary: Clone a credential into a new scope (system → host or host → host)
      description: >
        Copies the source credential's encrypted secret material verbatim
        into a new row with the target scope/scope_id. Used by the bulk
        import flow to attach a chosen credential template to each newly
        imported host without re-prompting for the secret material.
      x-required-permission: credential:write
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CredentialCloneRequest'}
      responses:
        '201':
          description: Clone created
          content:
            application/json:
              schema: {$ref: '#/components/schemas/CredentialResponse'}
        '400':
          description: Invalid scope, host not found, or validation failure
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Source credential not found or already soft-deleted
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: is_default=true collides with an existing system default
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts:
    get:
      operationId: getHosts
      summary: List hosts
      x-required-permission: host:read
      parameters:
        - {name: environment, in: query, required: false, schema: {type: string}}
        - {name: tag, in: query, required: false, schema: {type: string}}
      responses:
        '200':
          description: Host list
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HostListResponse'}
        '403':
          description: Caller lacks host:read
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    post:
      operationId: postHosts
      summary: Create a host
      x-required-permission: host:write
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/HostCreateRequest'}
      responses:
        '201':
          description: Host created
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HostResponse'}
        '400':
          description: Validation failure (bad hostname, ip, port, etc.)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Hostname already exists in environment
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{id}:
    get:
      operationId: getHostByID
      summary: Fetch a host with liveness + compliance enrichment
      x-required-permission: host:read
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
        - name: framework
          in: query
          description: Filter compliance_summary to host_rule_state rows whose framework_refs contains this key (v1.2.0). Liveness is unaffected.
          schema: {type: string}
      responses:
        '200':
          description: Host detail (includes liveness + compliance_summary)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HostDetailResponse'}
        '404':
          description: Host not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    patch:
      operationId: patchHostByID
      summary: Update mutable host fields
      x-required-permission: host:write
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/HostUpdateRequest'}
      responses:
        '200':
          description: Host updated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HostResponse'}
        '400':
          description: Validation failure
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Host not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    delete:
      operationId: deleteHostByID
      summary: Soft-delete a host
      x-required-permission: host:delete
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '204':
          description: Deleted (deleted_at set)
        '404':
          description: Host not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{host_id}/credentials:resolve:
    post:
      operationId: postHostCredentialsResolve
      summary: Resolve the credential that will be used for a host
      x-required-permission: credential:read
      parameters:
        - {name: host_id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200':
          description: Resolved credential metadata
          content:
            application/json:
              schema: {$ref: '#/components/schemas/CredentialResponse'}
        '404':
          description: No credential available for host or system default
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{host_id}/maintenance:
    put:
      operationId: putHostMaintenance
      summary: Pause/resume liveness probes for a single host
      description: >
        Toggling maintenance_mode=true causes listProbeTargets to skip
        the host on every subsequent tick. The host_liveness row is left
        untouched, so resuming maintenance picks up from the last
        recorded state. v1.3.0.
      x-required-permission: host:write
      parameters:
        - {name: host_id, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/HostMaintenanceRequest'}
      responses:
        '200':
          description: Updated host
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HostResponse'}
        '404':
          description: Host not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{host_id}/monitoring/history:
    get:
      operationId: getHostMonitoringHistory
      summary: Tail the host's monitoring-history rows (most recent first)
      description: >
        Returns up to `limit` most-recent host_monitoring_history rows
        for diagnostics. Each row captures the per-layer pass/fail flags
        the multi-layer probe recorded. v1.3.0.
      x-required-permission: host:read
      parameters:
        - {name: host_id, in: path, required: true, schema: {type: string, format: uuid}}
        - name: limit
          in: query
          required: false
          schema: {type: integer, minimum: 1, maximum: 500, default: 50}
      responses:
        '200':
          description: History rows newest-first
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HostMonitoringHistoryResponse'}
        '404':
          description: Host not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/audit/events:
    get:
      operationId: getAuditEvents
      summary: List audit events (cursor-paginated, newest first)
      parameters:
        - name: action
          in: query
          schema: {type: string}
        - name: correlation_id
          in: query
          schema: {type: string}
        - name: actor_type
          in: query
          schema: {type: string}
        - name: resource_type
          in: query
          description: Filter to events whose resource_type matches (e.g. "host"). Pair with resource_id for a single resource's audit trail.
          schema: {type: string}
        - name: resource_id
          in: query
          description: Filter to events whose resource_id matches (e.g. a host UUID). Typically paired with resource_type.
          schema: {type: string}
        - name: since
          in: query
          schema: {type: string, format: date-time}
        - name: until
          in: query
          schema: {type: string, format: date-time}
        - name: cursor
          in: query
          schema: {type: string}
        - name: limit
          in: query
          schema: {type: integer, minimum: 1, maximum: 200, default: 50}
      responses:
        '200':
          description: Page of audit events
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AuditEventsPage'}
        '400':
          $ref: '#/components/responses/BadRequest'

  /api/v1/audit/events/export:
    get:
      operationId: getAuditEventsExport
      summary: Export the filtered audit events as a downloadable CSV or JSON file
      description: >
        Downloads the audit trail matching the same filters as the list
        endpoint, as a CSV or JSON attachment (NIST 800-53 AU-7 audit
        reduction + report generation). audit:read gated. Unlike the
        paginated list it returns the whole filtered set in one file, capped
        at 10000 rows newest-first (a larger window is paginated via the list
        endpoint). CSV columns: occurred_at, action, message, severity,
        actor_type, actor_label, actor_id, resource_type, resource_id,
        correlation_id.
      x-required-permission: audit:read
      parameters:
        - name: format
          in: query
          description: Output format. Defaults to csv.
          schema: {type: string, enum: [csv, json], default: csv}
        - name: action
          in: query
          schema: {type: string}
        - name: actor_type
          in: query
          schema: {type: string}
        - name: resource_type
          in: query
          schema: {type: string}
        - name: resource_id
          in: query
          schema: {type: string}
        - name: since
          in: query
          schema: {type: string, format: date-time}
        - name: until
          in: query
          schema: {type: string, format: date-time}
      responses:
        '200':
          description: Audit export file (CSV or JSON attachment)
          content:
            text/csv:
              schema: {type: string}
            application/json:
              schema:
                type: array
                items: {$ref: '#/components/schemas/AuditEvent'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks audit:read
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  # Spec: app/specs/api/fleet-observability.spec.yaml (v1.1.0)
  /api/v1/fleet/score:
    get:
      operationId: getFleetScore
      summary: Fleet-wide compliance score (passing/total)
      parameters:
        - name: framework
          in: query
          description: Filter to host_rule_state rows whose framework_refs contains this key (v1.1.0).
          schema: {type: string}
      responses:
        '200':
          description: Fleet score
          content:
            application/json:
              schema: {$ref: '#/components/schemas/FleetScore'}
        '401':
          description: Authentication required
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks system:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/fleet/liveness:
    get:
      operationId: getFleetLiveness
      summary: Host counts by reachability status
      responses:
        '200':
          description: Liveness rollup
          content:
            application/json:
              schema: {$ref: '#/components/schemas/FleetLiveness'}
        '401':
          description: Authentication required
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks system:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/fleet/top-failing-rules:
    get:
      operationId: getFleetTopFailingRules
      summary: Rules with the most failing hosts (descending)
      parameters:
        - name: framework
          in: query
          description: Filter to host_rule_state rows whose framework_refs contains this key (v1.1.0).
          schema: {type: string}
        - name: limit
          in: query
          schema: {type: integer, minimum: 1, maximum: 1000, default: 50}
      responses:
        '200':
          description: Ranked rule failures
          content:
            application/json:
              schema: {$ref: '#/components/schemas/FleetTopFailingRules'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401':
          description: Authentication required
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks system:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/fleet/top-failing-hosts:
    get:
      operationId: getFleetTopFailingHosts
      summary: Hosts with the most failing rules (descending)
      parameters:
        - name: framework
          in: query
          description: Filter to host_rule_state rows whose framework_refs contains this key (v1.1.0).
          schema: {type: string}
        - name: limit
          in: query
          schema: {type: integer, minimum: 1, maximum: 1000, default: 50}
      responses:
        '200':
          description: Ranked host failures
          content:
            application/json:
              schema: {$ref: '#/components/schemas/FleetTopFailingHosts'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401':
          description: Authentication required
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks system:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/fleet/recent-changes:
    get:
      operationId: getFleetRecentChanges
      summary: Recent transactions (state changes), newest first
      parameters:
        - name: framework
          in: query
          description: Filter to transactions whose framework_refs contains this key (v1.1.0).
          schema: {type: string}
        - name: since
          in: query
          description: Filter to transactions strictly newer than this RFC3339 timestamp
          schema: {type: string, format: date-time}
        - name: limit
          in: query
          schema: {type: integer, minimum: 1, maximum: 1000, default: 50}
      responses:
        '200':
          description: Recent transaction page
          content:
            application/json:
              schema: {$ref: '#/components/schemas/FleetRecentChanges'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401':
          description: Authentication required
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks system:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/fleet/connectivity/breakdown:
    get:
      operationId: getFleetConnectivityBreakdown
      summary: 4-state connectivity breakdown (online/degraded/critical/down/never_probed)
      description: |
        Derived per-state host counts for the Settings → Scanning &
        monitoring page. Bands come from `consecutive_failures`
        hysteresis: online=reachable+consec=0, degraded=reachable+consec>=1,
        critical=unreachable+consec<3, down=consec>=3, never_probed=no row.
        Counts sum to active host count. Spec api-fleet-connectivity-breakdown.
      responses:
        '200':
          description: Per-state counts
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ConnectivityBreakdown'}
        '403':
          description: Caller lacks system:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/system/connectivity/config:
    get:
      operationId: getSystemConnectivityConfig
      summary: Read the connectivity-monitor runtime config + baked-in defaults
      responses:
        '200':
          description: Current config + defaults sub-object
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ConnectivityConfigResponse'}
        '403':
          description: Caller lacks system:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    put:
      operationId: putSystemConnectivityConfig
      summary: Update connectivity-monitor runtime config
      description: |
        Persists the new config, signals the in-process liveness service
        to Reload, and emits system.config.changed. Bounds are validated
        at the handler boundary — out-of-range values return 400.
        Spec api-system-connectivity.
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ConnectivityConfig'}
      responses:
        '200':
          description: Updated config snapshot
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ConnectivityConfig'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403':
          description: Caller lacks system:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/system/intelligence/config:
    get:
      operationId: getSystemIntelligenceConfig
      summary: Read the OS Intelligence scheduler runtime config + baked-in defaults
      description: |
        Returns the persisted IntelligenceConfig (or DefaultIntelligence
        when no row exists) PLUS the baked-in defaults sub-object so the
        UI can render a "reset to defaults" affordance without a
        round-trip. Mirrors api-system-connectivity v1.0.
        Spec api-system-intelligence-config.
      responses:
        '200':
          description: Current config + defaults sub-object
          content:
            application/json:
              schema: {$ref: '#/components/schemas/IntelligenceConfigResponse'}
        '403':
          description: Caller lacks system:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    put:
      operationId: putSystemIntelligenceConfig
      summary: Update OS Intelligence scheduler runtime config
      description: |
        Persists the new config (interval_sec 300..86400, rate_limit
        1..200, maintenance_global boolean). Emits
        system.config.changed in the same write transaction. The
        in-process scheduler picks up the new values at the top of
        its next cycle — no hot-reload signal needed.
        Spec api-system-intelligence-config.
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/IntelligenceConfig'}
      responses:
        '200':
          description: Updated config snapshot
          content:
            application/json:
              schema: {$ref: '#/components/schemas/IntelligenceConfig'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403':
          description: Caller lacks system:config:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/system/discovery/config:
    get:
      operationId: getSystemDiscoveryConfig
      summary: Read the OS discovery scheduler runtime config + baked-in defaults
      description: |
        Returns the persisted DiscoveryConfig (or DefaultDiscovery when
        no row exists) PLUS the baked-in defaults sub-object so the UI
        can render a "reset to defaults" affordance without a round-trip.
        Mirrors api-system-intelligence-config v1.0.
        Spec api-system-discovery-config.
      responses:
        '200':
          description: Current config + defaults sub-object
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DiscoveryConfigResponse'}
        '403':
          description: Caller lacks system:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    put:
      operationId: putSystemDiscoveryConfig
      summary: Update OS discovery scheduler runtime config
      description: |
        Persists the new config (interval_sec 3600..604800, rate_limit
        1..500, detect_on_first_contact boolean, maintenance_global
        boolean). Emits system.config.changed in the same write
        transaction. The in-process scheduler picks up the new values
        at the top of its next tick — no hot-reload signal needed.
        Spec api-system-discovery-config.
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/DiscoveryConfig'}
      responses:
        '200':
          description: Updated config snapshot
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DiscoveryConfig'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403':
          description: Caller lacks system:config:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/system/discovery/sweep:
    post:
      operationId: postSystemDiscoverySweep
      summary: Enqueue a host.discovery job for every host with NULL os_discovered_at
      description: |
        One-off manual sweep used by the "Run now" affordance on the
        Settings page. Enqueues host.discovery jobs for non-deleted,
        non-maintenance hosts whose hosts.os_discovered_at IS NULL.
        Hosts already discovered are NOT re-enqueued — this is a
        catch-up, not a forced re-fingerprint. Returns the count of
        jobs enqueued so the UI can confirm the action.
        Spec api-system-discovery-config.
      responses:
        '200':
          description: Sweep dispatched
          content:
            application/json:
              schema: {$ref: '#/components/schemas/DiscoverySweepResponse'}
        '403':
          description: Caller lacks system:config:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/system/scan/config:
    get:
      operationId: getSystemScanConfig
      summary: Read the adaptive compliance scan scheduler config + baked-in defaults
      description: |
        Returns the persisted ScanConfig (or DefaultScan when no row
        exists) PLUS the baked-in defaults sub-object so the UI can
        render a "reset to defaults" affordance without a round-trip.
        The six per-state intervals are the adaptive scheduler's tier
        ladder (scan plan decision #4: systemconfig, not a policy file).
        Spec api-system-scan-config.
      responses:
        '200':
          description: Current config + defaults sub-object
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ScanConfigResponse'}
        '403':
          description: Caller lacks system:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    put:
      operationId: putSystemScanConfig
      summary: Update the adaptive compliance scan scheduler config
      description: |
        Persists the new config. Ladder minutes are CLAMPED into
        [5, 2880] and rate_limit into [1, 100] rather than rejected
        (the response echoes the clamped values); emits
        system.config.changed in the same write transaction. The
        in-process scheduler refreshes the config at the top of its
        next 60s tick. Spec api-system-scan-config.
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ScanConfig'}
      responses:
        '200':
          description: Updated (clamped) config snapshot
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ScanConfig'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403':
          description: Caller lacks system:config:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/system/scan/schedule-preview:
    get:
      operationId: getSystemScanSchedulePreview
      summary: 24h forward projection of the compliance scan schedule
      description: |
        Read-only projection of host_compliance_schedule over the next
        24 hours (NOT a dry-run dispatch): per-hour due counts for the
        Settings schedule strip, the soonest next_scheduled_scan, the
        count of hosts already due, and the live scan queue depth.
        Spec api-system-scan-config.
      responses:
        '200':
          description: Schedule projection
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ScanSchedulePreview'}
        '403':
          description: Caller lacks system:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/fleet/compliance/states:
    get:
      operationId: getFleetComplianceStates
      summary: Fleet host counts per compliance state
      description: |
        One row per ComplianceState in ladder order (critical,
        non_compliant, partial, mostly_compliant, compliant, unknown)
        with the count of live hosts whose host_compliance_schedule
        row is in that state. States with zero hosts are still listed
        so the Settings steppers can render a stable six-row layout.
        Spec api-system-scan-config.
      responses:
        '200':
          description: Per-state host counts
          content:
            application/json:
              schema: {$ref: '#/components/schemas/FleetComplianceStates'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/system/scan/variables:
    get:
      operationId: getSystemScanVariables
      summary: List the corpus-used kensa rule-template variables with defaults and overrides
      description: |
        One entry per variable the installed rule corpus actually
        references (kensa ships more built-in defaults than the corpus
        uses; unused ones are not listed). Each entry carries the
        built-in default, the operator override when set, the count
        and ids of affected rules, and the configure_me flag marking
        organization-specific placeholder defaults
        (rsyslog_remote_server, chrony_ntp_pool, banner_text) that
        operators should always review. Spec api-system-scan-config.
      responses:
        '200':
          description: Corpus-used variables sorted by name
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ScanVariablesResponse'}
        '403':
          description: Caller lacks system:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    put:
      operationId: putSystemScanVariables
      summary: Replace the operator variable overrides
      description: |
        PUT replaces the FULL override map (absent names revert to the
        built-in defaults). Unknown variable names (not used by the
        installed corpus) are rejected with 400 naming the offending
        key; overrides equal to the built-in default are dropped at
        write time. Emits system.config.changed. The scan path reloads
        the rule corpus with the merged variables on the next scan.
        Spec api-system-scan-config.
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ScanVariableOverrides'}
      responses:
        '200':
          description: The normalized override map that was persisted
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ScanVariableOverrides'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403':
          description: Caller lacks system:config:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{id}/exceptions:
    get:
      operationId: getHostExceptions
      summary: List a host's compliance exceptions
      description: |
        Per-host exception list for the Compliance tab + Watchlist row.
        By default returns open rows (requested + approved); ?history=true
        returns every row. RBAC: exception:read. Spec
        api-compliance-exceptions.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: history
          in: query
          required: false
          schema: {type: boolean, default: false}
      responses:
        '200':
          description: Exceptions, newest first
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ExceptionList'}
        '404':
          description: Unknown or deleted host
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks exception:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    post:
      operationId: postHostException
      summary: Request a compliance exception (rule waiver) on a host
      description: |
        Submits a requested exception for a host+rule. One open
        (requested or approved) exception is allowed per host+rule; a
        duplicate returns 409. The requester is the authenticated user.
        RBAC: exception:request. Spec api-compliance-exceptions.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ExceptionRequest'}
      responses:
        '201':
          description: The requested exception
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Exception'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '404':
          description: Unknown or deleted host
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks exception:request permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: An open exception already exists for this host and rule
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/compliance/exceptions:
    get:
      operationId: getComplianceExceptions
      summary: Fleet-wide compliance exception queue
      description: |
        Fleet exception list, optionally filtered by status (requested,
        approved, rejected, revoked, expired). Newest first, capped at
        500. RBAC: exception:read. Spec api-compliance-exceptions.
      parameters:
        - name: status
          in: query
          required: false
          schema: {type: string, enum: [requested, approved, rejected, revoked, expired]}
        - name: limit
          in: query
          required: false
          schema: {type: integer, default: 200}
      responses:
        '200':
          description: Exceptions, newest first
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ExceptionList'}
        '403':
          description: Caller lacks exception:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/exceptions/{xid}:approve:
    post:
      operationId: postExceptionApprove
      summary: Approve a requested exception
      description: |
        requested -> approved. The reviewer must differ from the
        requester (separation of duties, 409). RBAC: exception:approve.
        Spec api-compliance-exceptions.
      parameters:
        - name: xid
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ExceptionReview'}
      responses:
        '200':
          description: The approved exception
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Exception'}
        '403':
          description: Caller lacks exception:approve permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Exception not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Not in the requested state, or reviewer is the requester
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/exceptions/{xid}:reject:
    post:
      operationId: postExceptionReject
      summary: Reject a requested exception
      description: |
        requested -> rejected. The reviewer must differ from the
        requester (409). RBAC: exception:approve. Spec
        api-compliance-exceptions.
      parameters:
        - name: xid
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ExceptionReview'}
      responses:
        '200':
          description: The rejected exception
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Exception'}
        '403':
          description: Caller lacks exception:approve permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Exception not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Not in the requested state, or reviewer is the requester
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/exceptions/{xid}:revoke:
    post:
      operationId: postExceptionRevoke
      summary: Revoke an active exception before its expiry
      description: |
        approved -> revoked. RBAC: exception:revoke (dangerous). Spec
        api-compliance-exceptions.
      parameters:
        - name: xid
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ExceptionReview'}
      responses:
        '200':
          description: The revoked exception
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Exception'}
        '403':
          description: Caller lacks exception:revoke permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Exception not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Not in the approved state
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  # ===========================================================================
  # Remediation (Phase 7). Free core: request -> approve | reject + projected
  # lift (see-and-govern). The act verbs (:dry-run, :execute, :rollback) are
  # OpenWatch+ licensed (remediation_execution) and return 402 on the free
  # tier. Spec api-remediation; plan docs/engineering/remediation_core_plan.md.
  # ===========================================================================
  /api/v1/remediation/requests:
    get:
      operationId: listRemediationRequests
      summary: List remediation requests (fleet or filtered)
      description: |
        Remediation request queue, newest first, optionally filtered by
        status, host_id, or rule_id; capped at limit (default 200). RBAC:
        remediation:read. Spec api-remediation.
      x-required-permission: remediation:read
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [pending_approval, approved, rejected, dry_run_complete, executing, executed, rolled_back, failed]
        - name: host_id
          in: query
          required: false
          schema: {type: string, format: uuid}
        - name: rule_id
          in: query
          required: false
          schema: {type: string}
        - name: limit
          in: query
          required: false
          schema: {type: integer, default: 200}
      responses:
        '200':
          description: Remediation requests, newest first
          content:
            application/json:
              schema: {$ref: '#/components/schemas/RemediationRequestList'}
        '403':
          description: Caller lacks remediation:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    post:
      operationId: requestRemediation
      summary: Request a remediation (fix) for a failing rule on a host
      description: |
        Submits a pending_approval remediation request for a host+rule and
        records the projected per-framework compliance lift. One open request
        is allowed per host+rule; a duplicate returns 409. The requester is
        the authenticated user. This NEVER contacts the host. RBAC:
        remediation:request. Spec api-remediation.
      x-required-permission: remediation:request
      x-audit-events: [remediation.requested]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/RemediationRequestCreate'}
      responses:
        '201':
          description: The created remediation request (pending approval)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/RemediationRequest'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '404':
          description: Unknown or deleted host
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks remediation:request permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: An open remediation request already exists for this host and rule
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/remediation/requests/{rid}:
    get:
      operationId: getRemediationRequest
      summary: Get a remediation request
      description: 'RBAC: remediation:read. Spec api-remediation.'
      x-required-permission: remediation:read
      parameters:
        - name: rid
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '200':
          description: The remediation request
          content:
            application/json:
              schema: {$ref: '#/components/schemas/RemediationRequest'}
        '404':
          description: Remediation request not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks remediation:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/remediation/requests/{rid}/steps:
    get:
      operationId: listRemediationSteps
      summary: List a remediation request's transaction journal (steps)
      description: |
        Per-step Kensa transaction journal (Capture/Apply/Validate/Commit
        outcomes). Empty until the request is executed (executing is the
        OpenWatch+ licensed track). RBAC: remediation:read. Spec
        api-remediation.
      x-required-permission: remediation:read
      parameters:
        - name: rid
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '200':
          description: Steps, in apply order
          content:
            application/json:
              schema: {$ref: '#/components/schemas/RemediationStepList'}
        '404':
          description: Remediation request not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks remediation:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/remediation/requests/{rid}:approve:
    post:
      operationId: approveRemediation
      summary: Approve a pending remediation request
      description: |
        pending_approval -> approved. The reviewer must differ from the
        requester (separation of duties, 409). RBAC: remediation:approve.
        Spec api-remediation.
      x-required-permission: remediation:approve
      x-audit-events: [remediation.approved]
      parameters:
        - name: rid
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        content:
          application/json:
            schema: {$ref: '#/components/schemas/RemediationReview'}
      responses:
        '200':
          description: The approved remediation request
          content:
            application/json:
              schema: {$ref: '#/components/schemas/RemediationRequest'}
        '403':
          description: Caller lacks remediation:approve permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Remediation request not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Not in the pending_approval state, or reviewer is the requester
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/remediation/requests/{rid}:reject:
    post:
      operationId: rejectRemediation
      summary: Reject a pending remediation request
      description: |
        pending_approval -> rejected. The reviewer must differ from the
        requester (409). RBAC: remediation:approve. Spec api-remediation.
      x-required-permission: remediation:approve
      x-audit-events: [remediation.approved]
      parameters:
        - name: rid
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        content:
          application/json:
            schema: {$ref: '#/components/schemas/RemediationReview'}
      responses:
        '200':
          description: The rejected remediation request
          content:
            application/json:
              schema: {$ref: '#/components/schemas/RemediationRequest'}
        '403':
          description: Caller lacks remediation:approve permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Remediation request not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Not in the pending_approval state, or reviewer is the requester
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/remediation/requests/{rid}:dry-run:
    post:
      operationId: dryRunRemediation
      summary: Dry-run a remediation (preview)
      description: |
        Would connect to the host and report what an apply changes, without
        applying. Free core (remediation:execute). Not yet implemented; returns
        501. Spec api-remediation.
      x-required-permission: remediation:execute
      parameters:
        - name: rid
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '403':
          description: Caller lacks remediation:execute permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '501':
          description: Dry-run not yet implemented
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/remediation/requests/{rid}:execute:
    post:
      operationId: executeRemediation
      summary: Execute an approved single-rule remediation (free core)
      description: |
        Applies the fix on the host (Kensa Capture/Apply/Validate/Commit),
        queued to the remediation worker. Free core: requires
        remediation:execute (single-rule manual remediation is not
        license-gated). The request must be in the 'approved' state; poll
        GET /requests/{rid} for the executed|failed outcome. Spec api-remediation.
      x-required-permission: remediation:execute
      x-audit-events: [remediation.executed]
      parameters:
        - name: rid
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '202':
          description: Execution queued; poll GET /requests/{rid} for executed|failed
        '403':
          description: Caller lacks remediation:execute permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Remediation request not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Request is not in the approved state
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/remediation/requests/{rid}:rollback:
    post:
      operationId: rollbackRemediation
      summary: Roll back an executed remediation (free core)
      description: |
        Restores the captured pre-state, queued to the remediation worker. Free
        core: requires remediation:rollback. The request must be in the
        'executed' state. Spec api-remediation.
      x-required-permission: remediation:rollback
      x-audit-events: [remediation.rolled_back]
      parameters:
        - name: rid
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '202':
          description: Rollback queued
        '403':
          description: Caller lacks remediation:rollback permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Remediation request not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Request is not in the executed state
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/groups:
    get:
      operationId: getGroups
      summary: Fleet group summary + every group with its rollup
      description: |
        Returns the Groups-page KPI summary and the full list of groups
        (sites first, then OS categories), each with its computed member
        rollup. RBAC: host:read. Spec api-groups.
      responses:
        '200':
          description: Summary plus groups with rollups
          content:
            application/json:
              schema: {$ref: '#/components/schemas/GroupListResponse'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    post:
      operationId: postGroup
      summary: Create a group
      description: |
        Create a site (manual membership) or an OS category (manual
        workload group or auto group keyed on os_family). RBAC:
        host:write. Spec api-groups.
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/GroupCreate'}
      responses:
        '201':
          description: The created group
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Group'}
        '400':
          description: Invalid group definition
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks host:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: An auto group already exists for that OS family
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/groups/{id}:
    patch:
      operationId: patchGroup
      summary: Update a group's display fields
      description: |
        Patch name, subtype, and color. Kind and membership are
        immutable. RBAC: host:write. Spec api-groups.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/GroupUpdate'}
      responses:
        '200':
          description: The updated group
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Group'}
        '400':
          description: Invalid update
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks host:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Group not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    delete:
      operationId: deleteGroup
      summary: Delete a group
      description: |
        Removes the group (members cascade). RBAC: host:write. Spec
        api-groups.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '204':
          description: Deleted
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks host:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Group not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/groups/{id}:maintenance:
    post:
      operationId: postGroupMaintenance
      summary: Toggle a group's maintenance flag
      description: |
        Sets the maintenance flag on or off. RBAC: host:write. Spec
        api-groups.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/GroupMaintenanceRequest'}
      responses:
        '200':
          description: The updated group
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Group'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks host:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Group not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/groups/{id}/members:
    post:
      operationId: postGroupMember
      summary: Add a host to a manual group
      description: |
        Assigns a host to a manual group (auto groups derive their
        members and reject this with 400). RBAC: host:write. Spec
        api-groups.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/GroupMemberRequest'}
      responses:
        '204':
          description: Member added
        '400':
          description: Cannot add a member to an auto group
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks host:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Group not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/groups/{id}/members/{host_id}:
    delete:
      operationId: deleteGroupMember
      summary: Remove a host from a manual group
      description: |
        Removes a host from a manual group. RBAC: host:write. Spec
        api-groups.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: host_id
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '204':
          description: Member removed
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks host:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/reports:
    get:
      operationId: getReports
      summary: List generated reports (newest first)
      description: |
        Returns the Reports library: every generated report, newest
        first. RBAC: host:read. Spec api-reports.
      responses:
        '200':
          description: The reports library
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ReportListResponse'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/reports:generate:
    post:
      operationId: postReportGenerate
      summary: Generate a Fleet Compliance Executive Summary
      description: |
        Computes a point-in-time posture snapshot from current data
        (host_rule_state pass/fail counts + critical, host count, top
        failing rules) and stores it as an immutable report. The MVP
        generates only the executive summary for all hosts. RBAC:
        host:write. Spec api-reports.
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: The generated report
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Report'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks host:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/reports/{id}:
    get:
      operationId: getReportByID
      summary: Fetch one report (with its stored JSON posture)
      description: |
        Returns a single report by id, including the stored JSON
        content. RBAC: host:read. Spec api-reports.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '200':
          description: The report
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Report'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Report not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/scans:
    get:
      operationId: getScans
      summary: List a host's compliance scans (newest first)
      description: |
        Returns the scan_runs history for one host, newest first, backing
        the scan-history drill-down at /scans (expand a host to see its
        scans). host_id is required. Cursor pagination by queued_at.
        RBAC: scan:read. Spec api-scans.
      x-required-permission: scan:read
      parameters:
        - name: host_id
          in: query
          required: true
          schema: {type: string, format: uuid}
        - name: limit
          in: query
          required: false
          schema: {type: integer, minimum: 1, maximum: 100, default: 20}
        - name: cursor
          in: query
          required: false
          description: queued_at of the last row already seen (RFC3339); omit to start at the newest
          schema: {type: string, format: date-time}
      responses:
        '200':
          description: The host's scan history page
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ScanList'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks scan:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Host not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/scans/{id}:
    get:
      operationId: getScanByID
      summary: One scan's metadata + per-rule results (no inline evidence)
      description: |
        Returns a scan's scan_runs metadata plus every rule's durable
        verdict for that scan (status, severity, framework refs,
        has_evidence). The raw check output is NOT inlined here; fetch it
        per rule via the evidence endpoint. RBAC: scan:read. Spec
        api-scans.
      x-required-permission: scan:read
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '200':
          description: The scan detail
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ScanDetail'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks scan:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Scan not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/scans/{id}/rules/{ruleId}/evidence:
    get:
      operationId: getScanRuleEvidence
      summary: One rule's full evidence for a scan (the drill-down payload)
      description: |
        Returns one rule's durable evidence for a scan: the verdict
        detail, the structured per-command checks (command, captured
        output, exit code, expected/actual), and framework refs. This is
        the proof behind the verdict, exposed only under /api/v1/scans and
        gated by scan:read (the host-detail Compliance tab stays
        evidence-free). Spec api-scans.
      x-required-permission: scan:read
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: ruleId
          in: path
          required: true
          schema: {type: string, minLength: 1, maxLength: 256}
      responses:
        '200':
          description: The rule's evidence
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ScanRuleEvidence'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks scan:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Scan or rule not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/scans/{id}/rules/{ruleId}/oscal:
    get:
      operationId: getScanRuleOSCAL
      summary: One rule's outcome as an OSCAL 1.0.6 Assessment Results document
      description: |
        Renders one rule's stored outcome as a standalone OSCAL 1.0.6
        Assessment Results document (one finding + observation),
        reconstructed from the durable scan store via Kensa's exporter.
        RBAC: scan:read. Spec api-scans.
      x-required-permission: scan:read
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: ruleId
          in: path
          required: true
          schema: {type: string, minLength: 1, maxLength: 256}
      responses:
        '200':
          description: OSCAL 1.0.6 Assessment Results JSON
          content:
            application/json:
              schema: {$ref: '#/components/schemas/OscalDocument'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks scan:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Scan or rule not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/scans/{id}/oscal:
    get:
      operationId: getScanOSCAL
      summary: A whole scan as an OSCAL 1.0.6 Assessment Results document
      description: |
        Renders an entire scan as a single OSCAL 1.0.6 Assessment Results
        document (one finding + observation per rule), reconstructed from
        the durable scan store via Kensa's exporter — the audit-window
        artifact for that scan. RBAC: scan:read. Spec api-scans.
      x-required-permission: scan:read
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '200':
          description: OSCAL 1.0.6 Assessment Results JSON
          content:
            application/json:
              schema: {$ref: '#/components/schemas/OscalDocument'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks scan:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Scan not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/rules:
    get:
      operationId: getRules
      summary: List the Kensa rule library (the full rule catalog)
      description: |
        Returns every Kensa rule with its normalized framework references
        and a remediation summary, for the rule-library browser on /scans.
        Reference data (the corpus is static), filtered client-side. RBAC:
        scan:read. Spec api-rules.
      x-required-permission: scan:read
      responses:
        '200':
          description: The rule library
          content:
            application/json:
              schema: {$ref: '#/components/schemas/RuleList'}
        '401':
          description: Caller is not authenticated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks scan:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/system/connectivity/status:
    get:
      operationId: getSystemConnectivityStatus
      summary: Read the connectivity-monitor in-process metrics + maintenance flag
      responses:
        '200':
          description: Metrics snapshot
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ConnectivityStatus'}
        '403':
          description: Caller lacks system:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{id}/connectivity:check:
    post:
      operationId: postHostConnectivityCheck
      summary: Synchronous on-demand reachability probe for a single host
      description: |
        Calls the same in-process probe machinery the periodic loop uses
        (credential-free TCP-banner on port 22), persists to
        host_liveness, and returns the fresh result. Idempotency-Key
        required. Spec api-host-connectivity-check.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: Idempotency-Key
          in: header
          required: true
          schema: {type: string, minLength: 1, maxLength: 128}
      responses:
        '200':
          description: Probe result
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ConnectivityCheckResult'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Host not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: A probe for this host is already in flight
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{id}/scans:
    post:
      operationId: postHostScan
      summary: Enqueue an on-demand compliance scan for a single host
      description: |
        Creates a scan run (the scan_runs logbook row) and enqueues the
        HMAC-signed scan job the worker executes via Kensa. Returns 202
        with the scan id — the scan itself is asynchronous; completion
        lands in host_rule_state/transactions and is announced on the
        event bus. 409 when a run for this host is already queued or
        running. Idempotency-Key required. Requires host:write.
        Spec api-host-scan.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: Idempotency-Key
          in: header
          required: true
          schema: {type: string, minLength: 1, maxLength: 128}
      responses:
        '202':
          description: Scan run created and job enqueued
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ScanRunQueued'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403':
          description: Caller lacks host:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Host not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: A scan for this host is already queued or running
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{id}/compliance:
    get:
      operationId: getHostCompliance
      summary: Per-host compliance lens (one scan, many framework views)
      description: |
        Projects the host's full host_rule_state corpus through an
        optional framework lens. scan_context carries the latest
        completed scan_runs row for the host (nulls when never
        scanned). summary counts every status plus a score_pct
        (passing/total as a percentage, one decimal, 0 when total is
        0). categories groups the same rows by kensa catalog category
        (uncategorized when unknown), sorted failing DESC then
        category ASC. rules lists EVERY row (pass/fail/skipped/error),
        severity-ordered then rule_id ASC, with control_ids projected
        for the requested framework (empty otherwise). The stored
        per-rule check output is never exposed. The per-host corpus is
        bounded (~539 rules), so this is one unpaginated query.
        Requires host:read. Spec api-host-compliance v1.1.0.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: framework
          in: query
          description: Filter to rows whose framework_refs contains this key and project its control ids; summary and categories are recomputed under the filter.
          schema: {type: string}
      responses:
        '200':
          description: Compliance lens (scan context + summary + categories + rules)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HostComplianceLensResponse'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Host not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{id}/compliance/schedule:
    get:
      operationId: getHostComplianceSchedule
      summary: One host's adaptive-scan schedule (Auto-scan tile)
      description: |
        The host's row from the adaptive scheduler: compliance state,
        next scheduled scan, current interval, and the pause flags
        (per-host maintenance + the scheduler-wide enabled/maintenance
        config). A host without a schedule row returns state unknown
        with a null next_scan_at - never an error.
        Spec api-system-scan-config.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '200':
          description: Schedule projection for the host
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HostComplianceSchedule'}
        '404':
          description: Unknown or deleted host
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{id}/compliance/trend:
    get:
      operationId: getHostComplianceTrend
      summary: Daily compliance posture trend for one host
      description: |
        Per-day posture snapshots over the trailing window (default 30
        days, clamped 1..90): score_pct, passing, failing, total. Days
        without a snapshot are absent from the array; history
        accumulates from the daily rollup going forward. Spec
        api-compliance-trend.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: days
          in: query
          required: false
          schema: {type: integer, default: 30}
          description: Trailing window in days; clamped into [1, 90]
      responses:
        '200':
          description: Daily points, oldest first
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HostComplianceTrend'}
        '404':
          description: Unknown or deleted host
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/fleet/compliance/trend:
    get:
      operationId: getFleetComplianceTrend
      summary: Daily fleet compliance trend
      description: |
        Per-day fleet aggregates over the trailing window (default 30
        days, clamped 1..90): average score across snapshotted hosts,
        host count, total failing rules, and hosts carrying critical
        findings. Powers the hosts-page average-compliance delta.
        Spec api-compliance-trend.
      parameters:
        - name: days
          in: query
          required: false
          schema: {type: integer, default: 30}
          description: Trailing window in days; clamped into [1, 90]
      responses:
        '200':
          description: Daily fleet points, oldest first
          content:
            application/json:
              schema: {$ref: '#/components/schemas/FleetComplianceTrend'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{id}/compliance/frameworks:
    get:
      operationId: getHostComplianceFrameworks
      summary: List the frameworks the host's rule state maps to
      description: |
        Distinct framework_refs keys across the host's host_rule_state
        rows with the number of rules mapped to each, ordered by
        framework id. Empty when the host has never been scanned.
        Backs the lens picker on the host compliance view. Requires
        host:read. Spec api-host-compliance v1.1.0.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '200':
          description: Frameworks with per-framework mapped-rule counts
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HostComplianceFrameworksResponse'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Host not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{id}/compliance/failed-rules:
    get:
      operationId: getHostFailedRules
      summary: List a host's currently-failing compliance rules
      description: |
        Returns host_rule_state rows with current_status=fail for the
        host, ordered by severity (critical > high > medium > low >
        unset) then last_checked_at DESC. Titles and categories come
        from the in-memory kensa rule catalog; when the catalog is
        unavailable, title falls back to the rule id. The optional
        framework filter restricts rows to those whose framework_refs
        contains the key and projects that framework's control ids
        into control_ids. total_failing is the post-filter, pre-limit
        count. Requires host:read. Spec api-host-compliance.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: limit
          in: query
          description: Max rules returned. Clamped to [1, 100]; default 10.
          schema: {type: integer, default: 10}
        - name: framework
          in: query
          description: Filter to rows whose framework_refs contains this key and project its control ids.
          schema: {type: string}
      responses:
        '200':
          description: Failing rules, severity-ordered
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HostFailedRulesResponse'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Host not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/fleet/scan-queue:
    get:
      operationId: getFleetScanQueue
      summary: Scan-queue depth split by lifecycle state
      description: |
        Counts of scan_runs rows in the queued and running states.
        Terminal (completed/failed) runs are excluded. Requires
        host:read. Spec api-host-compliance.
      responses:
        '200':
          description: Queued and running scan counts
          content:
            application/json:
              schema: {$ref: '#/components/schemas/FleetScanQueue'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/intelligence/events:
    get:
      operationId: getIntelligenceEvents
      summary: List OS Intelligence change events
      description: |
        Returns the change events the OS Intelligence collector
        recorded — newly opened ports, package updates, service
        failures, etc. Cursor pagination on detected_at DESC. Filter
        by host_id, event_code, severity, since/until. Spec
        api-os-intelligence.
      parameters:
        - name: host_id
          in: query
          schema: {type: string, format: uuid}
        - name: event_code
          in: query
          schema: {type: string, minLength: 1, maxLength: 64}
        - name: severity
          in: query
          schema: {type: string, enum: [info, low, medium, high, critical]}
        - name: since
          in: query
          schema: {type: string, format: date-time}
        - name: until
          in: query
          schema: {type: string, format: date-time}
        - name: cursor
          in: query
          schema: {type: string}
        - name: limit
          in: query
          schema: {type: integer, minimum: 1, maximum: 200, default: 50}
      responses:
        '200':
          description: Events page
          content:
            application/json:
              schema: {$ref: '#/components/schemas/IntelligenceEventsPage'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/intelligence/state/{host_id}:
    get:
      operationId: getIntelligenceState
      summary: Last full Intelligence snapshot for one host
      description: |
        Returns the most recent host_intelligence_state row for the
        given host. 404 hosts.not_found if the host is unknown OR if
        no Intelligence cycle has populated the row yet (operators
        cannot probe host existence via this endpoint). Spec
        api-os-intelligence.
      parameters:
        - name: host_id
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '200':
          description: Last snapshot
          content:
            application/json:
              schema: {$ref: '#/components/schemas/IntelligenceState'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Host unknown OR no snapshot yet
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/alerts:
    get:
      operationId: getAlerts
      summary: List persisted alerts (paginated, filterable)
      description: |
        Returns alerts in the alerts table — written by the
        system-alert-router persistence amendment (v1.1.0). Cursor
        pagination on occurred_at DESC. RBAC: alert:read. Spec
        api-alerts.
      parameters:
        - name: state
          in: query
          schema: {type: string, enum: [active, acknowledged, silenced, resolved, dismissed]}
        - name: host_id
          in: query
          schema: {type: string, format: uuid}
        - name: severity
          in: query
          schema: {type: string, enum: [info, low, medium, high, critical]}
        - name: since
          in: query
          schema: {type: string, format: date-time}
        - name: until
          in: query
          schema: {type: string, format: date-time}
        - name: cursor
          in: query
          schema: {type: string}
        - name: limit
          in: query
          schema: {type: integer, minimum: 1, maximum: 200, default: 50}
      responses:
        '200':
          description: Alerts page
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AlertsPage'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403':
          description: Caller lacks alert:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/alerts/{id}:
    get:
      operationId: getAlertByID
      summary: Single alert by id
      description: |
        Returns the alert row (including terminal states — resolved /
        dismissed are still queryable). RBAC: alert:read. Spec api-alerts.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '200':
          description: Alert
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Alert'}
        '403':
          description: Caller lacks alert:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Alert not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/alerts/{id}:acknowledge:
    post:
      operationId: postAlertAcknowledge
      summary: Acknowledge an active alert
      description: 'active -> acknowledged. RBAC: alert:write. Spec api-alerts.'
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        content:
          application/json:
            schema: {$ref: '#/components/schemas/AlertLifecycleRequest'}
      responses:
        '200':
          description: Updated alert
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Alert'}
        '403':
          description: Caller lacks alert:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Alert not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Invalid transition for current state
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/alerts/{id}:silence:
    post:
      operationId: postAlertSilence
      summary: Silence an alert until a timestamp (or indefinitely)
      description: |
        active|acknowledged -> silenced. Optional body.until specifies
        when the silence elapses; missing means indefinite. Past until
        returns 400. RBAC: alert:write. Spec api-alerts.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        content:
          application/json:
            schema: {$ref: '#/components/schemas/AlertLifecycleRequest'}
      responses:
        '200':
          description: Updated alert
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Alert'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403':
          description: Caller lacks alert:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Alert not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Invalid transition for current state
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/alerts/{id}:resolve:
    post:
      operationId: postAlertResolve
      summary: Resolve an alert
      description: 'active|acknowledged|silenced -> resolved. RBAC: alert:write. Spec api-alerts.'
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        content:
          application/json:
            schema: {$ref: '#/components/schemas/AlertLifecycleRequest'}
      responses:
        '200':
          description: Updated alert
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Alert'}
        '403':
          description: Caller lacks alert:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Alert not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Invalid transition for current state
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/alerts/{id}:dismiss:
    post:
      operationId: postAlertDismiss
      summary: Dismiss an alert (terminal)
      description: 'Any non-dismissed state -> dismissed. RBAC: alert:write. Spec api-alerts.'
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        content:
          application/json:
            schema: {$ref: '#/components/schemas/AlertLifecycleRequest'}
      responses:
        '200':
          description: Updated alert
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Alert'}
        '403':
          description: Caller lacks alert:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Alert not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Invalid transition for current state
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/activity:
    get:
      operationId: getActivity
      summary: Unified Activity feed (UNION over alerts + transactions + intelligence + audit + monitoring)
      description: |
        Returns the per-source RBAC-filtered union of recent events.
        Caller's permissions decide which sources contribute; hidden_count
        reports how many rows the caller's RBAC suppressed so the UI
        can render "N visible / M hidden". Spec api-activity.
      parameters:
        - name: source
          in: query
          schema: {type: string, enum: [alert, transaction, intelligence, audit, monitoring]}
        - name: severity
          in: query
          schema: {type: string, enum: [info, low, medium, high, critical]}
        - name: host_id
          in: query
          schema: {type: string, format: uuid}
        - name: since
          in: query
          schema: {type: string, format: date-time}
        - name: until
          in: query
          schema: {type: string, format: date-time}
        - name: cursor
          in: query
          schema: {type: string}
        - name: limit
          in: query
          schema: {type: integer, minimum: 1, maximum: 200, default: 50}
      responses:
        '200':
          description: Activity page
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ActivityPage'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403':
          description: Anonymous caller
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{id}/system-info:
    get:
      operationId: getHostSystemInfo
      summary: Read the latest Discovery facts for one host
      description: |
        Returns the most recent host_system_info row for the given
        host. Populated by system-host-discovery (synchronous via
        POST /hosts/{id}/discovery:run or async by the scheduler).
        404 hosts.not_found if (a) the host is unknown, (b) the
        host is soft-deleted, or (c) the host exists but Discovery
        has not run yet — operators cannot probe host existence
        via this endpoint. Spec api-host-system-info.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '200':
          description: Latest HostSystemInfo for the host
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HostSystemInfo'}
        '403':
          description: Caller lacks host:read permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Host unknown OR no Discovery row yet
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{id}/discovery:run:
    post:
      operationId: postHostDiscoveryRun
      summary: Synchronous on-demand OS fingerprint discovery for a single host
      description: |
        Opens one SSH session against the host using its resolved
        credential, runs the closed-set probe batch (os-release, uname,
        meminfo, df, hostname, getenforce, aa-status, firewall), parses
        the outputs, upserts host_system_info + denormalized hosts.os_*
        columns in a single transaction, publishes
        eventbus.HostDiscovered, and emits the host.discovery.completed
        audit event. Spec system-host-discovery.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: Idempotency-Key
          in: header
          required: true
          schema: {type: string, minLength: 1, maxLength: 128}
      responses:
        '200':
          description: Discovery result — the captured SystemFacts
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HostSystemInfo'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403':
          description: Caller lacks host:write permission
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '404':
          description: Host not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '502':
          description: Host unreachable — SSH dial or credential resolve failed
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '503':
          description: Discovery service not wired on the server
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  # Spec: api-notifications — operator-managed alert-delivery channels.
  /api/v1/notifications/channels:
    get:
      operationId: getNotificationChannels
      summary: List notification channels (secrets redacted)
      x-required-permission: notification:read
      responses:
        '200':
          description: Channel list
          content:
            application/json:
              schema: {$ref: '#/components/schemas/NotificationChannelList'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '503': {$ref: '#/components/responses/ServiceUnavailable'}
    post:
      operationId: postNotificationChannel
      summary: Create a notification channel
      x-required-permission: notification:write
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/NotificationChannelCreate'}
      responses:
        '201':
          description: Channel created (secret redacted)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/NotificationChannel'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '503': {$ref: '#/components/responses/ServiceUnavailable'}
  /api/v1/notifications/channels/{id}:
    get:
      operationId: getNotificationChannel
      summary: Fetch a notification channel (secret redacted)
      x-required-permission: notification:read
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200':
          description: Channel
          content:
            application/json:
              schema: {$ref: '#/components/schemas/NotificationChannel'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '404': {$ref: '#/components/responses/NotFound'}
        '503': {$ref: '#/components/responses/ServiceUnavailable'}
    patch:
      operationId: patchNotificationChannel
      summary: Update a notification channel
      x-required-permission: notification:write
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/NotificationChannelUpdate'}
      responses:
        '200':
          description: Updated channel (secret redacted)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/NotificationChannel'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '404': {$ref: '#/components/responses/NotFound'}
        '503': {$ref: '#/components/responses/ServiceUnavailable'}
    delete:
      operationId: deleteNotificationChannel
      summary: Delete a notification channel
      x-required-permission: notification:delete
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '204':
          description: Deleted
        '403': {$ref: '#/components/responses/Forbidden'}
        '503': {$ref: '#/components/responses/ServiceUnavailable'}
  /api/v1/notifications/channels/{id}:test:
    post:
      operationId: testNotificationChannel
      summary: Send a synthetic test alert through the channel
      x-required-permission: notification:test
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '204':
          description: Test alert delivered
        '400': {$ref: '#/components/responses/BadRequest'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '404': {$ref: '#/components/responses/NotFound'}
        '503': {$ref: '#/components/responses/ServiceUnavailable'}

  # Spec: api-tokens — API service-account tokens for automation.
  /api/v1/tokens:
    get:
      operationId: getAPITokens
      summary: List API tokens (metadata only; secrets never returned)
      x-required-permission: token:read
      responses:
        '200':
          description: Token list
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ApiTokenList'}
        '403': {$ref: '#/components/responses/Forbidden'}
    post:
      operationId: postAPIToken
      summary: Create an API token (the secret is returned once, here only)
      x-required-permission: token:write
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ApiTokenCreateRequest'}
      responses:
        '201':
          description: Token created; the raw secret is present in this response only
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ApiTokenCreated'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403': {$ref: '#/components/responses/Forbidden'}
  /api/v1/tokens/{id}:
    delete:
      operationId: deleteAPIToken
      summary: Revoke an API token
      x-required-permission: token:delete
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '204':
          description: Revoked (idempotent)
        '403': {$ref: '#/components/responses/Forbidden'}

  # Spec: api-auth-policy — workspace authentication policy.
  /api/v1/auth-policy:
    get:
      operationId: getAuthPolicy
      summary: View the workspace authentication policy
      x-required-permission: system:auth_policy_read
      responses:
        '200':
          description: Current policy
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AuthPolicy'}
        '403': {$ref: '#/components/responses/Forbidden'}
    put:
      operationId: putAuthPolicy
      summary: Replace the workspace authentication policy
      x-required-permission: system:auth_policy_write
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/AuthPolicyUpdateRequest'}
      responses:
        '200':
          description: Policy updated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AuthPolicy'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403': {$ref: '#/components/responses/Forbidden'}

  # Spec: api-sso — SSO (OIDC) provider configuration + sign-in flow.
  /api/v1/sso/providers:
    get:
      operationId: getSSOProviders
      summary: List SSO providers (metadata only; client secret never returned)
      x-required-permission: admin:sso_provider
      responses:
        '200':
          description: Provider list
          content:
            application/json:
              schema: {$ref: '#/components/schemas/SSOProviderList'}
        '403': {$ref: '#/components/responses/Forbidden'}
    post:
      operationId: postSSOProvider
      summary: Create an SSO provider
      x-required-permission: admin:sso_provider
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/SSOProviderCreateRequest'}
      responses:
        '201':
          description: Provider created
          content:
            application/json:
              schema: {$ref: '#/components/schemas/SSOProvider'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403': {$ref: '#/components/responses/Forbidden'}
  /api/v1/sso/providers/enabled:
    get:
      operationId: getSSOProvidersEnabled
      summary: List enabled SSO providers for the sign-in picker (anonymous)
      responses:
        '200':
          description: Enabled providers (id + name only)
          content:
            application/json:
              schema: {$ref: '#/components/schemas/SSOEnabledList'}
  /api/v1/sso/providers/{id}:
    get:
      operationId: getSSOProvider
      summary: View one SSO provider (metadata only)
      x-required-permission: admin:sso_provider
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '200':
          description: Provider
          content:
            application/json:
              schema: {$ref: '#/components/schemas/SSOProvider'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '404': {$ref: '#/components/responses/NotFound'}
    put:
      operationId: putSSOProvider
      summary: Update an SSO provider (omit client_secret to keep the existing one)
      x-required-permission: admin:sso_provider
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/SSOProviderUpdateRequest'}
      responses:
        '200':
          description: Provider updated
          content:
            application/json:
              schema: {$ref: '#/components/schemas/SSOProvider'}
        '400': {$ref: '#/components/responses/BadRequest'}
        '403': {$ref: '#/components/responses/Forbidden'}
        '404': {$ref: '#/components/responses/NotFound'}
    delete:
      operationId: deleteSSOProvider
      summary: Delete an SSO provider (cascades its identities + states)
      x-required-permission: admin:sso_provider
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
      responses:
        '204':
          description: Deleted
        '403': {$ref: '#/components/responses/Forbidden'}
        '404': {$ref: '#/components/responses/NotFound'}

  # Anonymous sign-in flow. Both endpoints 302-redirect (to the IdP, then
  # back to the app); they carry no JSON success body.
  /api/v1/auth/sso/{id}/login:
    get:
      operationId: getAuthSSOLogin
      summary: Begin SSO sign-in — redirects to the IdP authorization endpoint
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
        - {name: return_to, in: query, required: false, schema: {type: string}}
      responses:
        '302':
          description: Redirect to the identity provider
        '404': {$ref: '#/components/responses/NotFound'}
  /api/v1/auth/sso/{id}/callback:
    get:
      operationId: getAuthSSOCallback
      summary: SSO redirect-back — exchanges the code, issues a session, redirects into the app
      parameters:
        - {name: id, in: path, required: true, schema: {type: string, format: uuid}}
        - {name: code, in: query, required: false, schema: {type: string}}
        - {name: state, in: query, required: false, schema: {type: string}}
        - {name: error, in: query, required: false, schema: {type: string}}
      responses:
        '302':
          description: Redirect into the app (success) or to /login with an error

components:
  responses:
    BadRequest:
      description: Validation, pagination, or idempotency error
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    MethodNotAllowed:
      description: Wrong HTTP method
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    Forbidden:
      description: Caller lacks the required permission
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    ServiceUnavailable:
      description: Backing service not wired on the server
      content:
        application/json:
          schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  schemas:

    AuthLoginRequest:
      type: object
      required: [username, password]
      properties:
        username: {type: string, minLength: 1, maxLength: 256}
        password: {type: string, minLength: 1, maxLength: 256}
        otp:      {type: string, minLength: 6, maxLength: 6}

    AuthLoginResponse:
      type: object
      required: [access_token, refresh_token, user]
      properties:
        access_token:  {type: string}
        refresh_token: {type: string}
        user:          {$ref: '#/components/schemas/AuthMeResponse'}
        mfa_enrollment_required:
          type: boolean
          description: >-
            True when workspace policy requires MFA but the user has not
            enrolled. The session is still issued (soft enforcement); the
            client must force MFA enrollment before anything else.

    AuthRefreshRequest:
      type: object
      required: [refresh_token]
      properties:
        refresh_token: {type: string}

    AuthMeResponse:
      type: object
      required: [id, username, email, role]
      properties:
        id:       {type: string, format: uuid}
        username: {type: string}
        email:    {type: string}
        role:     {type: string}

    # Per-user UI preferences (system-user-preferences). Every field is
    # optional: GET returns only the keys the user has set, and PATCH treats
    # the body as a partial (present keys merge, omitted keys are retained).
    # additionalProperties:false governs the valid key set — adding a knob is
    # a deliberate contract change here, not arbitrary client-written JSON.
    UserPreferences:
      type: object
      additionalProperties: false
      properties:
        # The /hosts page default view when the URL has no ?view= override.
        hosts_view_default: {type: string, enum: [table, cards]}
        density:            {type: string, enum: [comfortable, compact]}
        accent_color:       {type: string, enum: [info, ok, brand2]}
        landing_page:       {type: string, enum: [hosts, dashboard, reports]}
        date_format:        {type: string, enum: [us12, iso24, long24]}
        reduce_motion:      {type: boolean}

    AuthMFAEnrollResponse:
      type: object
      required: [provisioning_uri]
      properties:
        provisioning_uri: {type: string}

    AuthMFAVerifyRequest:
      type: object
      required: [otp]
      properties:
        otp: {type: string, minLength: 6, maxLength: 6}

    AuthPasswordChangeRequest:
      type: object
      required: [current_password, new_password]
      properties:
        current_password: {type: string, minLength: 1}
        new_password:     {type: string, minLength: 1}

    UserResponse:
      type: object
      required: [id, username, email]
      properties:
        id:                       {type: string, format: uuid}
        username:                 {type: string}
        email:                    {type: string}
        roles:
          type: array
          items: {type: string}
          description: >-
            Role IDs assigned to the user. Populated by the list endpoint
            (GET /users); other responses may omit it.
        last_password_change_at:  {type: string, format: date-time}
        created_at:               {type: string, format: date-time}
        updated_at:               {type: string, format: date-time}
        disabled_at:
          type: string
          format: date-time
          nullable: true
          description: Non-null when the account is disabled (cannot authenticate)

    UserPasswordResetRequest:
      type: object
      required: [new_password]
      properties:
        new_password: {type: string, minLength: 1, maxLength: 256}

    UsersListResponse:
      type: object
      required: [users]
      properties:
        users:
          type: array
          items: {$ref: '#/components/schemas/UserResponse'}

    NotificationChannel:
      type: object
      required: [id, type, name, enabled, target_hint, tag_filter, created_at, updated_at]
      description: >-
        A delivery channel. SECRETS are NEVER returned — the SMTP password,
        and the slack/webhook URL + token, are write-only. For email channels
        the NON-secret config is returned so the edit form can pre-fill:
        smtp_host (also target_hint), smtp_port, from, to, username.
      properties:
        id:          {type: string, format: uuid}
        type:        {type: string, enum: [slack, webhook, email]}
        name:        {type: string}
        enabled:     {type: boolean}
        target_hint: {type: string, description: Non-secret host (URL host or SMTP host)}
        tag_filter:
          type: object
          additionalProperties: {type: string}
          description: Alert tags this channel matches; empty = every alert
        smtp_port: {type: integer, nullable: true, description: SMTP port (email channels)}
        from:      {type: string, nullable: true, description: Sender address (email channels)}
        to:
          type: array
          nullable: true
          items: {type: string}
          description: Recipient addresses (email channels)
        username:  {type: string, nullable: true, description: SMTP username (email; the password is never returned)}
        created_at:  {type: string, format: date-time}
        updated_at:  {type: string, format: date-time}
    NotificationChannelList:
      type: object
      required: [channels]
      properties:
        channels:
          type: array
          items: {$ref: '#/components/schemas/NotificationChannel'}
    NotificationChannelCreate:
      type: object
      required: [type, name]
      description: >-
        For slack/webhook supply url (https, public host). For email supply
        smtp_host/smtp_port/from/to (and username/password if the relay
        authenticates). All secrets are stored encrypted and never returned.
      properties:
        type:    {type: string, enum: [slack, webhook, email]}
        name:    {type: string, minLength: 1, maxLength: 256}
        enabled: {type: boolean, default: true}
        url:
          type: string
          description: Target URL (https, public host) for slack/webhook. Stored encrypted.
        token:
          type: string
          description: Optional bearer token for webhook auth. Stored encrypted.
        smtp_host: {type: string, description: SMTP relay host (email). Stored encrypted.}
        smtp_port: {type: integer, description: SMTP relay port (email), e.g. 587.}
        username:  {type: string, description: SMTP auth username (email). Stored encrypted.}
        password:  {type: string, description: SMTP auth password (email). Stored encrypted.}
        from:      {type: string, description: Envelope From address (email).}
        to:
          type: array
          items: {type: string}
          description: Recipient addresses (email).
        tag_filter:
          type: object
          additionalProperties: {type: string}
    NotificationChannelUpdate:
      type: object
      required: [name, enabled]
      description: >-
        Updates name/enabled/tag_filter. Supplying the secret config
        (url for slack/webhook, or smtp_host for email) replaces it;
        omitting it leaves the stored secret unchanged.
      properties:
        name:      {type: string, minLength: 1, maxLength: 256}
        enabled:   {type: boolean}
        url:       {type: string}
        token:     {type: string}
        smtp_host: {type: string}
        smtp_port: {type: integer}
        username:  {type: string}
        password:  {type: string}
        from:      {type: string}
        to:
          type: array
          items: {type: string}
        tag_filter:
          type: object
          additionalProperties: {type: string}

    ApiToken:
      type: object
      required: [id, name, prefix, role_id, created_at]
      description: API token metadata. The secret is NEVER included.
      properties:
        id:           {type: string, format: uuid}
        name:         {type: string}
        prefix:       {type: string, description: Non-secret display prefix (e.g. owk_a1b2c3d4)}
        role_id:      {type: string, description: The role whose permissions the token carries}
        created_at:   {type: string, format: date-time}
        expires_at:   {type: string, format: date-time, nullable: true}
        last_used_at: {type: string, format: date-time, nullable: true}
        revoked_at:   {type: string, format: date-time, nullable: true}
    ApiTokenList:
      type: object
      required: [tokens]
      properties:
        tokens:
          type: array
          items: {$ref: '#/components/schemas/ApiToken'}
    ApiTokenCreateRequest:
      type: object
      required: [name, role_id]
      properties:
        name:       {type: string, minLength: 1, maxLength: 256}
        role_id:    {type: string, description: Role the token acts as (must be a known role)}
        expires_at: {type: string, format: date-time, nullable: true}
    ApiTokenCreated:
      type: object
      required: [token, api_token]
      description: >-
        The raw token is shown ONCE, in this create response only. Store
        it now; it cannot be retrieved again.
      properties:
        token:     {type: string, description: The raw secret. Shown once.}
        api_token: {$ref: '#/components/schemas/ApiToken'}

    AuthPolicy:
      type: object
      required: [require_mfa, session_idle_timeout_seconds, session_absolute_timeout_seconds, updated_at]
      description: Workspace-wide authentication policy.
      properties:
        require_mfa:
          type: boolean
          description: When true, every user must have MFA enrolled (soft-enforced at login).
        session_idle_timeout_seconds:
          type: integer
          description: Inactivity window. A session expires this many seconds after its last use.
        session_absolute_timeout_seconds:
          type: integer
          description: Absolute lifetime cap regardless of activity, in seconds.
        updated_at: {type: string, format: date-time}
        updated_by: {type: string, format: uuid, nullable: true}

    AuthPolicyUpdateRequest:
      type: object
      required: [require_mfa, session_idle_timeout_seconds, session_absolute_timeout_seconds]
      description: >-
        Replaces the whole policy. Bounds (enforced server-side): idle
        300..86400 s, absolute 3600..2592000 s, absolute >= idle.
      properties:
        require_mfa: {type: boolean}
        session_idle_timeout_seconds:     {type: integer, minimum: 300, maximum: 86400}
        session_absolute_timeout_seconds: {type: integer, minimum: 3600, maximum: 2592000}

    SSOProvider:
      type: object
      required: [id, name, type, issuer, client_id, scopes, default_role, enabled, created_at]
      description: SSO provider metadata. The client secret is NEVER included.
      properties:
        id:           {type: string, format: uuid}
        name:         {type: string}
        type:         {type: string, description: Protocol (oidc)}
        issuer:       {type: string, description: OIDC issuer URL}
        client_id:    {type: string}
        scopes:       {type: string, description: Space-delimited OAuth scopes}
        default_role: {type: string, description: Role granted to users provisioned via this provider}
        enabled:      {type: boolean}
        created_at:   {type: string, format: date-time}
        updated_at:   {type: string, format: date-time}
    SSOProviderList:
      type: object
      required: [providers]
      properties:
        providers:
          type: array
          items: {$ref: '#/components/schemas/SSOProvider'}
    SSOProviderCreateRequest:
      type: object
      required: [name, issuer, client_id, client_secret]
      properties:
        name:          {type: string, minLength: 1, maxLength: 256}
        issuer:        {type: string, description: OIDC issuer URL (https)}
        client_id:     {type: string, minLength: 1}
        client_secret: {type: string, minLength: 1, description: Stored encrypted; never returned}
        scopes:        {type: string, description: 'Space-delimited; openid is always added'}
        default_role:  {type: string, description: 'Role for provisioned users (default viewer)'}
        enabled:       {type: boolean}
    SSOProviderUpdateRequest:
      type: object
      required: [name, issuer, client_id]
      description: Omit client_secret (or send empty) to keep the stored secret.
      properties:
        name:          {type: string, minLength: 1, maxLength: 256}
        issuer:        {type: string}
        client_id:     {type: string, minLength: 1}
        client_secret: {type: string, description: Optional; empty keeps the existing secret}
        scopes:        {type: string}
        default_role:  {type: string}
        enabled:       {type: boolean}
    SSOEnabledProvider:
      type: object
      required: [id, name]
      description: The minimal, non-secret shape rendered on the anonymous login page.
      properties:
        id:   {type: string, format: uuid}
        name: {type: string}
    SSOEnabledList:
      type: object
      required: [providers]
      properties:
        providers:
          type: array
          items: {$ref: '#/components/schemas/SSOEnabledProvider'}

    UserCreateRequest:
      type: object
      required: [username, email, password]
      properties:
        username: {type: string, minLength: 1, maxLength: 256}
        email:    {type: string, minLength: 3, maxLength: 256}
        password: {type: string, minLength: 8, maxLength: 256}

    UserRoleAssignRequest:
      type: object
      required: [role_id]
      properties:
        role_id: {type: string, minLength: 1}

    CustomRoleCreateRequest:
      type: object
      required: [id, description, permissions]
      properties:
        id:          {type: string, pattern: '^[a-z][a-z0-9_]{1,63}$'}
        description: {type: string, minLength: 1, maxLength: 256}
        permissions:
          type: array
          minItems: 1
          items: {type: string}

    CustomRoleResponse:
      type: object
      required: [id, description, is_built_in, permissions]
      properties:
        id:           {type: string}
        description:  {type: string}
        is_built_in:  {type: boolean}
        permissions:
          type: array
          items: {type: string}

    CredentialResponse:
      type: object
      required: [id, scope, name, username, auth_method, is_default, is_active]
      properties:
        id:                    {type: string, format: uuid}
        scope:                 {type: string, enum: [system, host]}
        scope_id:              {type: string, format: uuid, nullable: true}
        name:                  {type: string}
        description:           {type: string}
        username:              {type: string}
        auth_method:           {type: string, enum: [ssh_key, password, both]}
        ssh_key_fingerprint:   {type: string}
        ssh_key_type:          {type: string}
        ssh_key_bits:          {type: integer}
        ssh_key_comment:       {type: string}
        is_default:            {type: boolean}
        is_active:             {type: boolean}
        created_by:            {type: string, format: uuid}
        created_at:            {type: string, format: date-time}
        updated_at:            {type: string, format: date-time}

    CredentialListResponse:
      type: object
      required: [credentials]
      properties:
        credentials:
          type: array
          items: {$ref: '#/components/schemas/CredentialResponse'}

    HostResponse:
      type: object
      required: [id, hostname, ip_address, port, environment]
      properties:
        id:           {type: string, format: uuid}
        hostname:     {type: string}
        ip_address:   {type: string}
        port:         {type: integer}
        display_name: {type: string}
        description:  {type: string}
        environment:  {type: string}
        tags:
          type: array
          items: {type: string}
        group_id:     {type: string, format: uuid, nullable: true}
        username:     {type: string}
        created_by:   {type: string, format: uuid}
        created_at:   {type: string, format: date-time}
        updated_at:   {type: string, format: date-time}
        # v1.3.0 — per-host probe pause + priority. Sourced from
        # hosts.maintenance_mode + hosts.check_priority.
        maintenance_mode: {type: boolean}
        check_priority:   {type: integer, minimum: 1, maximum: 10}
        # v1.4.0 — denormalized OS fields populated by system-host-discovery.
        # NULL pre-Discovery; populated post-Discovery from the captured
        # SystemFacts. Spec api-hosts C-10.
        os_family:           {type: string, nullable: true, description: 'Distro ID from /etc/os-release (e.g. rhel, ubuntu, rocky, centos, almalinux, debian, opensuse-leap, sles); rollup family (rhel | debian | suse | alpine | arch | gentoo | other) ONLY when ID was empty; null pre-Discovery. Spec system-host-discovery v1.3.0 AC-22.'}
        os_version:          {type: string, nullable: true}
        architecture:        {type: string, nullable: true, description: 'e.g. x86_64, aarch64'}
        platform_identifier: {type: string, nullable: true, description: 'e.g. platform:el9'}
        os_discovered_at:    {type: string, format: date-time, nullable: true}

    # Per-host enrichment (spec api-hosts v1.1.0 C-05).
    # Populated on GET /hosts/{id} when host_liveness has a row for the host.
    HostLiveness:
      type: object
      required: [reachability_status]
      properties:
        reachability_status:
          type: string
          enum: [reachable, unreachable, unknown]
        # 5-band classification (v1.3.0). Derived from which layer of
        # the multi-layer probe failed. UI rolls reachability_status +
        # monitoring_state into a single badge.
        monitoring_state:
          type: string
          enum: [online, degraded, critical, down, maintenance, unknown]
        last_probe_at:        {type: string, format: date-time, nullable: true}
        last_response_ms:     {type: integer, nullable: true}
        consecutive_failures: {type: integer}
        # Per-layer counters (v1.3.0). Surface for the operator to see
        # WHICH axis is failing without parsing last_error_type.
        ping_consecutive_failures:      {type: integer}
        ping_consecutive_successes:     {type: integer}
        ssh_consecutive_failures:       {type: integer}
        ssh_consecutive_successes:      {type: integer}
        privilege_consecutive_failures: {type: integer}
        privilege_consecutive_successes: {type: integer}
        last_state_change_at: {type: string, format: date-time, nullable: true}
        last_error_type:      {type: string, nullable: true}

    HostMaintenanceRequest:
      type: object
      required: [enabled]
      properties:
        enabled: {type: boolean, description: "true = pause probes; false = resume"}

    HostMonitoringHistoryEntry:
      type: object
      required: [id, host_id, check_time, monitoring_state]
      properties:
        id:                {type: integer, format: int64}
        host_id:           {type: string, format: uuid}
        check_time:        {type: string, format: date-time}
        monitoring_state:  {type: string, enum: [online, degraded, critical, down, maintenance, unknown]}
        previous_state:    {type: string, enum: [online, degraded, critical, down, maintenance, unknown], nullable: true}
        response_time_ms:  {type: integer, nullable: true}
        ping_ok:           {type: boolean, nullable: true}
        ssh_ok:            {type: boolean, nullable: true}
        privilege_ok:      {type: boolean, nullable: true}
        failed_layer:      {type: string, enum: [ping, ssh, privilege], nullable: true}
        error_message:     {type: string, nullable: true}
        error_type:        {type: string, nullable: true}

    HostMonitoringHistoryResponse:
      type: object
      required: [host_id, entries]
      properties:
        host_id: {type: string, format: uuid}
        entries:
          type: array
          items: {$ref: '#/components/schemas/HostMonitoringHistoryEntry'}

    # Per-host compliance roll-up (spec api-hosts v1.1.0 C-06).
    # Always populated on GET /hosts/{id} — zero counts when no rule_state.
    HostComplianceSummary:
      type: object
      required: [passing, failing, skipped, error, total]
      properties:
        passing: {type: integer, format: int64}
        failing: {type: integer, format: int64}
        skipped: {type: integer, format: int64}
        error:   {type: integer, format: int64}
        total:   {type: integer, format: int64}

    # Per-host failing-rule listing (spec api-host-compliance).
    # Severity-ordered; titles resolved from the kensa rule catalog.
    # The host_rule_state stored check output is never exposed here.
    HostFailedRule:
      type: object
      required: [rule_id, title, category, severity, control_ids, last_checked_at, check_count]
      properties:
        rule_id:  {type: string}
        title:
          type: string
          description: Catalog title; falls back to rule_id when the catalog lacks the rule.
        category:
          type: string
          description: Catalog category; empty when unknown.
        severity:
          type: string
          description: Stored severity; empty when the scan recorded none.
        control_ids:
          type: array
          items: {type: string}
          description: Control ids for the requested framework; empty unless ?framework= is given.
        last_checked_at: {type: string, format: date-time}
        check_count:     {type: integer}

    HostFailedRulesResponse:
      type: object
      required: [total_failing, rules]
      properties:
        total_failing:
          type: integer
          format: int64
          description: Count of ALL failing rows for the host (post-framework-filter, pre-limit).
        rules:
          type: array
          items: {$ref: '#/components/schemas/HostFailedRule'}

    # Per-host compliance lens (spec api-host-compliance v1.1.0).
    # The stored per-rule check output is never exposed here.
    HostScanContext:
      type: object
      required: [last_scan_at, scan_id, policy_version]
      properties:
        last_scan_at:
          type: string
          format: date-time
          nullable: true
          description: finished_at of the latest completed scan run; null when never scanned.
        scan_id:
          type: string
          format: uuid
          nullable: true
          description: id of the latest completed scan run; null when never scanned.
        policy_version:
          type: string
          description: Policy version of the latest completed run; empty when never scanned.
        duration_seconds:
          type: integer
          nullable: true
          description: Wall-clock duration of the latest completed run (finished_at - started_at); null when never scanned or timestamps absent.

    HostComplianceLensSummary:
      type: object
      required: [passing, failing, skipped, error, total, score_pct]
      properties:
        passing: {type: integer, format: int64}
        failing: {type: integer, format: int64}
        skipped: {type: integer, format: int64}
        error:   {type: integer, format: int64}
        total:   {type: integer, format: int64}
        score_pct:
          type: number
          format: double
          description: passing/total as a percentage rounded to one decimal; 0 when total is 0.

    HostComplianceCategory:
      type: object
      required: [category, passing, failing, total]
      properties:
        category:
          type: string
          description: Kensa catalog category; uncategorized when the catalog lacks the rule.
        passing: {type: integer, format: int64}
        failing: {type: integer, format: int64}
        total:   {type: integer, format: int64}

    HostComplianceRule:
      type: object
      required: [rule_id, title, description, category, severity, status, control_ids, last_checked_at]
      properties:
        rule_id: {type: string}
        title:
          type: string
          description: Catalog title; falls back to rule_id when the catalog lacks the rule.
        description:
          type: string
          description: First sentence of the catalog description; empty when the catalog lacks the rule. Catalog text only, never stored check output.
        category:
          type: string
          description: Catalog category; uncategorized when unknown.
        severity:
          type: string
          description: Stored severity; empty when the scan recorded none.
        status:
          type: string
          description: current_status of the rule on this host (pass, fail, skipped, error).
        control_ids:
          type: array
          items: {type: string}
          description: Control ids for the requested framework; empty unless ?framework= is given.
        last_checked_at: {type: string, format: date-time}

    HostComplianceLensResponse:
      type: object
      required: [scan_context, summary, categories, rules]
      properties:
        scan_context: {$ref: '#/components/schemas/HostScanContext'}
        summary: {$ref: '#/components/schemas/HostComplianceLensSummary'}
        categories:
          type: array
          items: {$ref: '#/components/schemas/HostComplianceCategory'}
        rules:
          type: array
          items: {$ref: '#/components/schemas/HostComplianceRule'}

    HostComplianceFramework:
      type: object
      required: [framework_id, rule_count, passing, failing, score_pct]
      properties:
        framework_id: {type: string}
        rule_count:
          type: integer
          format: int64
          description: Number of host_rule_state rows mapped to this framework.
        passing:
          type: integer
          description: Rows mapped to this framework with current_status pass.
        failing:
          type: integer
          description: Rows mapped to this framework with current_status fail.
        score_pct:
          type: number
          format: float
          description: passing/rule_count as a percentage rounded to one decimal; 0 when rule_count is 0. Powers the per-lens score on the View-as chips.

    HostComplianceFrameworksResponse:
      type: object
      required: [frameworks, overall]
      properties:
        overall:
          $ref: '#/components/schemas/HostComplianceFramework'
          description: The all-rules aggregate (framework_id "all"). Powers the All-rules chip score.
        frameworks:
          type: array
          items: {$ref: '#/components/schemas/HostComplianceFramework'}

    # List-view compliance roll-up (spec api-hosts v1.5.0 C-12). Same
    # counts as HostComplianceSummary plus critical_failing; nullable
    # on the list item (null = host has no rule_state rows).
    HostListComplianceSummary:
      type: object
      required: [passing, failing, skipped, error, total, critical_failing]
      properties:
        passing: {type: integer, format: int64}
        failing: {type: integer, format: int64}
        skipped: {type: integer, format: int64}
        error:   {type: integer, format: int64}
        total:   {type: integer, format: int64}
        critical_failing:
          type: integer
          format: int64
          description: Rows with current_status=fail and critical severity (case-insensitive).

    # Scan-queue depth KPI (spec api-host-compliance).
    FleetScanQueue:
      type: object
      required: [queued, running]
      properties:
        queued:  {type: integer, format: int64}
        running: {type: integer, format: int64}

    # Detail-view response: HostResponse plus enrichments. Used by
    # GET /hosts/{id} only; the list endpoint keeps HostResponse to
    # avoid per-host join overhead on bulk reads.
    HostDetailResponse:
      type: object
      required: [host, compliance_summary]
      properties:
        host: {$ref: '#/components/schemas/HostResponse'}
        liveness:
          allOf: [{$ref: '#/components/schemas/HostLiveness'}]
          nullable: true
          description: Null when no liveness probe has ever run against this host.
        compliance_summary: {$ref: '#/components/schemas/HostComplianceSummary'}

    # List-view item: HostResponse plus optional liveness sub-object.
    # Liveness comes from a single LEFT JOIN — bounded overhead even on
    # large fleets. compliance_summary stays on the detail endpoint
    # only (per-host aggregation is too expensive to do in a list).
    HostListItem:
      type: object
      required: [id, hostname, ip_address, port, environment]
      properties:
        id:           {type: string, format: uuid}
        hostname:     {type: string}
        ip_address:   {type: string}
        port:         {type: integer}
        display_name: {type: string}
        description:  {type: string}
        environment:  {type: string}
        tags:
          type: array
          items: {type: string}
        group_id:     {type: string, format: uuid, nullable: true}
        username:     {type: string}
        created_by:   {type: string, format: uuid}
        created_at:   {type: string, format: date-time}
        updated_at:   {type: string, format: date-time}
        maintenance_mode: {type: boolean}
        check_priority:   {type: integer, minimum: 1, maximum: 10}
        # v1.3.0 — MAX(host_rule_state.last_checked_at) per host. NULL
        # when no compliance check has ever run against the host.
        # Surface for the operator dashboard's "last scan X ago" cell.
        last_scan_at: {type: string, format: date-time, nullable: true}
        # v1.6.0 — id of the newest COMPLETED scan_run for this host. Drives
        # the host card's "view report" affordance, which links to
        # /scans/{latest_scan_id} (the scan:read-gated detail page). NULL
        # when the host has no completed scan yet (icon hidden). Spec
        # api-hosts C-13.
        latest_scan_id: {type: string, format: uuid, nullable: true}
        liveness:
          allOf: [{$ref: '#/components/schemas/HostLiveness'}]
          nullable: true
          description: Null when no liveness probe has ever run against this host.
        # v1.5.0 — per-host compliance roll-up for the list view, loaded
        # with one grouped query over host_rule_state for the whole page
        # (no N+1). Spec api-hosts C-12.
        compliance_summary:
          allOf: [{$ref: '#/components/schemas/HostListComplianceSummary'}]
          nullable: true
          description: Null when the host has no host_rule_state rows (never scanned).
        # v1.4.0 — denormalized OS fields. Same semantics as HostResponse.
        # Spec api-hosts C-10.
        os_family:           {type: string, nullable: true}
        os_version:          {type: string, nullable: true}
        architecture:        {type: string, nullable: true}
        platform_identifier: {type: string, nullable: true}
        os_discovered_at:    {type: string, format: date-time, nullable: true}

    HostListResponse:
      type: object
      required: [hosts]
      properties:
        hosts:
          type: array
          items: {$ref: '#/components/schemas/HostListItem'}

    HostCreateRequest:
      type: object
      required: [hostname, ip_address]
      properties:
        hostname:     {type: string, minLength: 1, maxLength: 256}
        ip_address:   {type: string, minLength: 1, maxLength: 64}
        port:         {type: integer, minimum: 1, maximum: 65535}
        display_name: {type: string, maxLength: 256}
        description:  {type: string, maxLength: 1024}
        environment:  {type: string, maxLength: 64}
        tags:
          type: array
          items: {type: string, maxLength: 64}
        group_id:     {type: string, format: uuid, nullable: true}
        username:     {type: string, maxLength: 256}

    HostUpdateRequest:
      type: object
      properties:
        ip_address:   {type: string, minLength: 1, maxLength: 64}
        port:         {type: integer, minimum: 1, maximum: 65535}
        display_name: {type: string, maxLength: 256}
        description:  {type: string, maxLength: 1024}
        environment:  {type: string, minLength: 1, maxLength: 64}
        tags:
          type: array
          items: {type: string, maxLength: 64}
        group_id:     {type: string, format: uuid, nullable: true}
        username:     {type: string, maxLength: 256}

    CredentialCreateRequest:
      type: object
      required: [scope, name, username, auth_method]
      properties:
        scope:                  {type: string, enum: [system, host]}
        scope_id:               {type: string, format: uuid, nullable: true}
        name:                   {type: string, minLength: 1, maxLength: 256}
        description:            {type: string, maxLength: 1024}
        username:               {type: string, minLength: 1, maxLength: 256}
        auth_method:            {type: string, enum: [ssh_key, password, both]}
        password:               {type: string}
        private_key:            {type: string}
        private_key_passphrase: {type: string}
        is_default:             {type: boolean}

    # Partial update shape. Every field is optional; only the fields
    # present are changed. Omitting a secret keeps the stored ciphertext,
    # so metadata can be edited without re-entering the key or password.
    # scope and scope_id are intentionally absent — a credential's scope
    # is immutable.
    CredentialUpdateRequest:
      type: object
      properties:
        name:                   {type: string, minLength: 1, maxLength: 256}
        description:            {type: string, maxLength: 1024}
        username:               {type: string, minLength: 1, maxLength: 256}
        auth_method:            {type: string, enum: [ssh_key, password, both]}
        password:               {type: string, description: "Re-encrypts and replaces the stored password when non-empty; omit to keep the current secret"}
        private_key:            {type: string, description: "Re-encrypts and replaces the stored key when non-empty; omit to keep the current secret"}
        private_key_passphrase: {type: string, description: "Re-encrypts and replaces the stored passphrase when non-empty; omit to keep the current secret"}
        is_default:             {type: boolean, description: "Setting true on a system credential atomically demotes the previous system default"}

    # Clone target shape. The source credential's secret material is
    # inherited verbatim (no plaintext crosses the wire); only the new
    # scope, scope_id, name, and is_default are operator-controlled.
    CredentialCloneRequest:
      type: object
      required: [scope]
      properties:
        scope:      {type: string, enum: [system, host]}
        scope_id:   {type: string, format: uuid, nullable: true, description: "Required when scope=host"}
        name:       {type: string, minLength: 1, maxLength: 256, description: "Defaults to '<source name> (clone)' when omitted"}
        is_default: {type: boolean, description: "Mark this clone as the system default (only valid when scope=system)"}

    HealthResponse:
      type: object
      required: [status, db_connected, version]
      properties:
        status: {type: string, enum: [healthy, degraded]}
        db_connected: {type: boolean}
        version: {type: string}

    VersionResponse:
      type: object
      required: [openwatch, kensa, go, commit, build_time]
      properties:
        openwatch: {type: string, description: 'OpenWatch semver (ldflags-injected)'}
        kensa: {type: string, description: 'Embedded Kensa engine module version (build info)'}
        go: {type: string, description: 'Go toolchain version the binary was built with'}
        commit: {type: string, description: 'Abbreviated git commit'}
        build_time: {type: string, description: 'ISO-8601 build timestamp'}

    EchoRequest:
      type: object
      required: [message]
      properties:
        message: {type: string, minLength: 1, maxLength: 1024}

    EchoResponse:
      type: object
      required: [echoed, correlation_id]
      properties:
        echoed: {type: string}
        correlation_id: {type: string}
        audit_event_id: {type: string, format: uuid}

    LicenseStateResponse:
      type: object
      required: [tier, status, features]
      properties:
        tier: {type: string, enum: [free, openwatch_plus, enterprise]}
        status: {type: string, enum: [active, grace, expired, no_license, invalid]}
        features: {type: array, items: {type: string}}
        customer_id: {type: string}
        expires_at: {type: string, format: date-time, nullable: true}
        in_grace_period: {type: boolean}
        using_prev_key: {type: boolean}

    LicenseVerifyRequest:
      type: object
      required: [license_jwt]
      properties:
        license_jwt: {type: string}

    LicenseVerifyResponse:
      type: object
      required: [is_valid, verify_result]
      properties:
        is_valid: {type: boolean}
        verify_result: {type: string}
        tier: {type: string, nullable: true}
        features: {type: array, items: {type: string}, nullable: true}
        expires_at: {type: string, format: date-time, nullable: true}
        warnings: {type: array, items: {type: string}, nullable: true}

    AuditEvent:
      type: object
      required: [id, correlation_id, action, actor_type, occurred_at]
      properties:
        id: {type: string, format: uuid}
        correlation_id: {type: string}
        action: {type: string}
        # Server-rendered human-readable sentence for the event
        # ("<actor> <predicate>", e.g. "alice@example.com created a host"),
        # built from action + actor_label + actor_type. Lets every audit
        # surface show a sentence instead of the raw dotted action code.
        message: {type: string}
        severity: {type: string}
        actor_type: {type: string}
        actor_id: {type: string, nullable: true}
        actor_label: {type: string, nullable: true}
        resource_type: {type: string, nullable: true}
        resource_id: {type: string, nullable: true}
        occurred_at: {type: string, format: date-time}
        recorded_at: {type: string, format: date-time}
        detail: {type: object, additionalProperties: true}
        redactions: {type: array, items: {type: string}}

    AuditEventsPage:
      type: object
      required: [items, next_cursor]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/AuditEvent'}
        next_cursor:
          type: string
          nullable: true
          description: Opaque cursor; pass as ?cursor= to fetch the next page

    # Fleet observability schemas (spec: api-fleet-observability)
    FleetScore:
      type: object
      required: [passing_fraction, total_evaluations]
      properties:
        passing_fraction:
          type: number
          format: double
          description: Passing rules / (passing + failing) across all hosts. 0..1.
        total_evaluations:
          type: integer
          format: int64
          description: Count of host_rule_state rows where current_status is pass or fail.

    FleetLiveness:
      type: object
      required: [reachable, unreachable, unknown, never_probed]
      properties:
        reachable:    {type: integer, format: int64}
        unreachable:  {type: integer, format: int64}
        unknown:      {type: integer, format: int64}
        never_probed: {type: integer, format: int64}

    ConnectivityBreakdown:
      type: object
      required: [online, degraded, critical, down, never_probed]
      properties:
        online:       {type: integer, format: int64, description: reachable + consecutive_failures=0}
        degraded:     {type: integer, format: int64, description: reachable + consecutive_failures>=1}
        critical:     {type: integer, format: int64, description: unreachable + consecutive_failures<3}
        down:         {type: integer, format: int64, description: consecutive_failures>=3}
        never_probed: {type: integer, format: int64, description: no host_liveness row exists}

    ConnectivityConfig:
      type: object
      required: [online_sec, degraded_sec, critical_sec, down_sec, maintenance_sec, timeout_sec, unreachable_threshold, rate_limit, maintenance_global]
      properties:
        online_sec:
          type: integer
          minimum: 60
          maximum: 86400
          description: Probe interval for reachable hosts with consecutive_failures=0 (60..86400). Default 900 (15m)
        degraded_sec:
          type: integer
          minimum: 60
          maximum: 86400
          description: Probe interval for reachable hosts with consecutive_failures>=1 (60..86400). Default 300 (5m)
        critical_sec:
          type: integer
          minimum: 60
          maximum: 86400
          description: Probe interval for unreachable hosts below the threshold (60..86400). Default 120 (2m)
        down_sec:
          type: integer
          minimum: 60
          maximum: 86400
          description: Probe interval for hosts at or above the threshold (60..86400). Default 1800 (30m)
        maintenance_sec:
          type: integer
          minimum: 60
          maximum: 86400
          description: Persisted band interval for hosts in maintenance (60..86400). Default 3600 (60m). Not yet auto-applied; tracked for the per-host maintenance slice
        timeout_sec:
          type: integer
          minimum: 1
          maximum: 30
          description: Per-probe TCP-banner timeout in seconds (1..30)
        unreachable_threshold:
          type: integer
          minimum: 1
          maximum: 10
          description: Consecutive failures before reachable→unreachable (1..10)
        rate_limit:
          type: integer
          minimum: 1
          maximum: 200
          description: Max concurrent SSH connections during fleet sweeps (1..200)
        maintenance_global:
          type: boolean
          description: When true, probe loop ticks but probes no hosts

    ConnectivityConfigResponse:
      type: object
      required: [config, defaults]
      properties:
        config:   {$ref: '#/components/schemas/ConnectivityConfig'}
        defaults: {$ref: '#/components/schemas/ConnectivityConfig'}

    IntelligenceConfig:
      type: object
      required: [interval_sec, rate_limit, maintenance_global]
      properties:
        interval_sec:
          type: integer
          minimum: 300
          maximum: 86400
          description: Per-host cadence the scheduler advances next_intelligence_at by after a successful RunCycle (300..86400). Default 3600 (1h)
        rate_limit:
          type: integer
          minimum: 1
          maximum: 200
          description: Max concurrent RunCycles per scheduler instance (1..200). Default 10
        maintenance_global:
          type: boolean
          description: When true, the scheduler loop ticks but RunCycles no hosts

    IntelligenceConfigResponse:
      type: object
      required: [config, defaults]
      properties:
        config:   {$ref: '#/components/schemas/IntelligenceConfig'}
        defaults: {$ref: '#/components/schemas/IntelligenceConfig'}

    DiscoveryConfig:
      type: object
      required: [interval_sec, rate_limit, detect_on_first_contact, maintenance_global]
      properties:
        interval_sec:
          type: integer
          minimum: 3600
          maximum: 604800
          description: Per-host cadence — a host's discovery becomes due once now() - hosts.os_discovered_at exceeds this many seconds. 3600..604800. Default 86400 (24h)
        rate_limit:
          type: integer
          minimum: 1
          maximum: 500
          description: Max host.discovery jobs enqueued per scheduler tick (1..500). Default 25. Bounds thundering-herd on a fleet that hits NULL os_discovered_at simultaneously
        detect_on_first_contact:
          type: boolean
          description: When true, POST /api/v1/hosts auto-enqueues a host.discovery job for the new host before returning 201. When false, new hosts stay at hosts.os_discovered_at NULL until the scheduler picks them up or an operator clicks Re-run discovery
        maintenance_global:
          type: boolean
          description: When true, the scheduler loop ticks but enqueues no jobs and the host-create gate behaves as if detect_on_first_contact is false

    DiscoveryConfigResponse:
      type: object
      required: [config, defaults]
      properties:
        config:   {$ref: '#/components/schemas/DiscoveryConfig'}
        defaults: {$ref: '#/components/schemas/DiscoveryConfig'}

    DiscoverySweepResponse:
      type: object
      required: [enqueued]
      properties:
        enqueued:
          type: integer
          minimum: 0
          description: Count of host.discovery jobs persisted by this sweep. Zero is a valid steady state (every host already discovered, or fleet empty)

    ScanConfig:
      type: object
      required: [enabled, unknown_mins, critical_mins, non_compliant_mins,
                 partial_mins, mostly_compliant_mins, compliant_mins,
                 rate_limit, maintenance_global]
      properties:
        enabled:
          type: boolean
          description: Master switch for the adaptive scheduler. When false the loop ticks but dispatches nothing. On-demand scans are unaffected
        unknown_mins:
          type: integer
          description: Re-scan interval (minutes) for never-classified hosts. Clamped into [5, 2880]
        critical_mins:
          type: integer
          description: Re-scan interval (minutes) for hosts in the critical band (score under 20 or any critical finding). Clamped into [5, 2880]
        non_compliant_mins:
          type: integer
          description: Re-scan interval (minutes) for the non_compliant band (score 20 to 49). Clamped into [5, 2880]
        partial_mins:
          type: integer
          description: Re-scan interval (minutes) for the partial band (score 50 to 69). Clamped into [5, 2880]
        mostly_compliant_mins:
          type: integer
          description: Re-scan interval (minutes) for the mostly_compliant band (score 70 to 89). Clamped into [5, 2880]
        compliant_mins:
          type: integer
          description: Re-scan interval (minutes) for the compliant band (score 90 and above). Clamped into [5, 2880]
        rate_limit:
          type: integer
          description: Max hosts dispatched per 60s scheduler tick. Clamped into [1, 100]
        maintenance_global:
          type: boolean
          description: When true the scheduler loop ticks but dispatches nothing (fleet-wide pause)

    ScanConfigResponse:
      type: object
      required: [config, defaults]
      properties:
        config:   {$ref: '#/components/schemas/ScanConfig'}
        defaults: {$ref: '#/components/schemas/ScanConfig'}

    ScanSchedulePreview:
      type: object
      required: [due_now, queued_jobs, running_jobs, buckets]
      properties:
        next_scan_at:
          type: string
          format: date-time
          nullable: true
          description: Soonest next_scheduled_scan across non-maintenance hosts; null when no schedule rows exist
        due_now:
          type: integer
          description: Hosts whose next_scheduled_scan has already passed (dispatch backlog)
        queued_jobs:
          type: integer
          description: scan_runs rows currently queued
        running_jobs:
          type: integer
          description: scan_runs rows currently running
        buckets:
          type: array
          description: 24 entries, one per hour from now; due count of hosts whose next_scheduled_scan falls inside that hour
          items:
            type: object
            required: [hour_offset, due_count]
            properties:
              hour_offset:
                type: integer
                description: Hours from now (0 = the coming hour)
              due_count:
                type: integer

    ScanVariablesResponse:
      type: object
      required: [variables]
      properties:
        variables:
          type: array
          description: Corpus-used variables sorted by name
          items:
            type: object
            required: [name, default, value, overridden, affects_rules, rule_ids, configure_me]
            properties:
              name:
                type: string
              default:
                type: string
                description: kensa built-in default in effect without an override
              value:
                type: string
                description: Effective value (override when set, else the default)
              overridden:
                type: boolean
              affects_rules:
                type: integer
                description: Count of corpus rules referencing the variable
              rule_ids:
                type: array
                items: {type: string}
                description: The referencing rule ids, sorted
              configure_me:
                type: boolean
                description: Organization-specific placeholder default the operator should always review

    ScanVariableOverrides:
      type: object
      required: [overrides]
      properties:
        overrides:
          type: object
          additionalProperties: {type: string}
          description: Variable name to override value. PUT replaces the full map

    Exception:
      type: object
      required: [id, host_id, rule_id, reason, status, requested_by, requested_at]
      properties:
        id:           {type: string, format: uuid}
        host_id:      {type: string, format: uuid}
        host_name:
          type: string
          description: Hostname, populated on list responses (empty on single-row lifecycle results)
        rule_id:      {type: string}
        reason:       {type: string}
        status:
          type: string
          enum: [requested, approved, rejected, revoked, expired]
        requested_by: {type: string, format: uuid}
        reviewed_by:  {type: string, format: uuid, nullable: true}
        review_note:  {type: string}
        expires_at:   {type: string, format: date-time, nullable: true}
        requested_at: {type: string, format: date-time}
        reviewed_at:  {type: string, format: date-time, nullable: true}

    ExceptionList:
      type: object
      required: [exceptions]
      properties:
        exceptions:
          type: array
          items: {$ref: '#/components/schemas/Exception'}

    ExceptionRequest:
      type: object
      required: [rule_id, reason]
      properties:
        rule_id:    {type: string}
        reason:     {type: string}
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: Optional expiry; null means active until revoked

    ExceptionReview:
      type: object
      properties:
        note: {type: string, description: Optional reviewer note}

    ProjectedLift:
      type: object
      description: >
        Estimated per-framework compliance-score delta (percentage points) if
        the rule flips to pass. Best-effort; a field is null when that
        framework's data is unavailable for the host.
      properties:
        cis:  {type: number, format: double, nullable: true}
        stig: {type: number, format: double, nullable: true}
        nist: {type: number, format: double, nullable: true}

    RemediationRequest:
      type: object
      required: [id, host_id, rule_id, status, requested_by, requested_at]
      properties:
        id:           {type: string, format: uuid}
        host_id:      {type: string, format: uuid}
        host_name:
          type: string
          description: Hostname, populated on list responses (empty on single-row lifecycle results)
        rule_id:      {type: string}
        status:
          type: string
          enum: [pending_approval, approved, rejected, dry_run_complete, executing, executed, rolled_back, failed]
        requested_by: {type: string, format: uuid}
        reviewed_by:  {type: string, format: uuid, nullable: true}
        review_note:  {type: string}
        scan_run_id:  {type: string, format: uuid, nullable: true}
        mechanism:
          type: string
          description: Kensa remediation handler id (empty when unknown at request time)
        reboot_required: {type: boolean}
        transactional:   {type: boolean}
        projected_lift:  {$ref: '#/components/schemas/ProjectedLift'}
        requested_at: {type: string, format: date-time}
        reviewed_at:  {type: string, format: date-time, nullable: true}

    RemediationRequestList:
      type: object
      required: [requests]
      properties:
        requests:
          type: array
          items: {$ref: '#/components/schemas/RemediationRequest'}

    RemediationRequestCreate:
      type: object
      required: [host_id, rule_id]
      properties:
        host_id: {type: string, format: uuid}
        rule_id: {type: string}
        scan_run_id:
          type: string
          format: uuid
          nullable: true
          description: Optional provenance - the scan run whose finding this remediates

    RemediationReview:
      type: object
      properties:
        note: {type: string, description: Optional reviewer note}

    RemediationStep:
      type: object
      required: [id, rule_id, dry_run]
      properties:
        id:        {type: string, format: uuid}
        rule_id:   {type: string}
        mechanism: {type: string}
        phase_result:
          type: string
          nullable: true
          enum: [committed, rolled_back, skipped]
        dry_run:    {type: boolean}
        applied_at: {type: string, format: date-time, nullable: true}

    RemediationStepList:
      type: object
      required: [steps]
      properties:
        steps:
          type: array
          items: {$ref: '#/components/schemas/RemediationStep'}

    Group:
      type: object
      required: [id, name, kind, subtype, color, membership, maintenance,
                 created_at, updated_at]
      properties:
        id:          {type: string, format: uuid}
        name:        {type: string}
        kind:
          type: string
          enum: [site, os_category]
        subtype:     {type: string, description: Free-form sub-classifier (may be empty)}
        color:       {type: string, description: Design-token color key (e.g. info)}
        membership:
          type: string
          enum: [manual, auto]
        match_family:
          type: string
          description: OS family an auto group matches on (empty for manual groups)
        maintenance: {type: boolean}
        created_at:  {type: string, format: date-time}
        updated_at:  {type: string, format: date-time}

    GroupMember:
      type: object
      required: [host_id, hostname, status]
      properties:
        host_id:  {type: string, format: uuid}
        hostname: {type: string}
        status:
          type: string
          description: Host monitoring band (online, down, unknown, ...)

    GroupRollup:
      type: object
      required: [hosts, online, down, critical_hosts, members]
      properties:
        hosts:          {type: integer}
        online:         {type: integer}
        down:           {type: integer}
        critical_hosts: {type: integer}
        avg_compliance_pct:
          type: integer
          nullable: true
          description: Mean compliance across scanned members; null when none scanned
        members:
          type: array
          items: {$ref: '#/components/schemas/GroupMember'}

    GroupWithRollup:
      allOf:
        - $ref: '#/components/schemas/Group'
        - type: object
          required: [rollup]
          properties:
            rollup: {$ref: '#/components/schemas/GroupRollup'}

    GroupSummary:
      type: object
      required: [groups, sites, os_categories, hosts_maintenance, ungrouped]
      properties:
        groups:           {type: integer}
        sites:            {type: integer}
        os_categories:    {type: integer}
        hosts_maintenance: {type: integer}
        avg_compliance_pct:
          type: integer
          nullable: true
          description: Fleet mean compliance; null when nothing scanned
        ungrouped:        {type: integer}

    GroupListResponse:
      type: object
      required: [summary, groups]
      properties:
        summary: {$ref: '#/components/schemas/GroupSummary'}
        groups:
          type: array
          items: {$ref: '#/components/schemas/GroupWithRollup'}

    Report:
      type: object
      required: [id, title, kind, scope_label, data_as_of, generated_by, format, content, created_at]
      properties:
        id: {type: string, format: uuid}
        title: {type: string}
        kind:
          type: string
          enum: [executive]
        scope_label: {type: string}
        data_as_of: {type: string, format: date-time}
        generated_by: {type: string}
        format: {type: string}
        content:
          type: object
          additionalProperties: true
          description: |
            The rendered JSON posture document. For an executive summary:
            compliance_pct, host_count, passing_rules, failing_rules,
            critical_issues, top_failing_rules.
        created_at: {type: string, format: date-time}

    ReportListResponse:
      type: object
      required: [reports]
      properties:
        reports:
          type: array
          items: {$ref: '#/components/schemas/Report'}

    ScanSummary:
      type: object
      description: One scan_runs row — a scan's metadata and outcome counts.
      required: [scan_id, host_id, status, trigger_source, queued_at, policy_version, rules_pass, rules_fail, rules_skipped, rules_error]
      properties:
        scan_id:        {type: string, format: uuid}
        host_id:        {type: string, format: uuid}
        # Human-friendly host label resolved from the hosts table for the
        # scan-detail header (so it shows a hostname/IP, not a raw UUID).
        # Populated on the detail endpoint (GET /scans/{id}); the list
        # endpoint leaves them absent since the caller already has host
        # context. hostname is the registered hostname (may be empty);
        # ip_address is always present for a real host. Spec api-scans.
        hostname:       {type: string}
        ip_address:     {type: string}
        status:         {type: string, description: 'queued | running | completed | failed'}
        trigger_source: {type: string, description: 'on_demand | scheduled'}
        queued_at:      {type: string, format: date-time}
        started_at:     {type: string, format: date-time, nullable: true}
        finished_at:    {type: string, format: date-time, nullable: true}
        policy_version: {type: string}
        rules_pass:     {type: integer}
        rules_fail:     {type: integer}
        rules_skipped:  {type: integer}
        rules_error:    {type: integer}

    ScanList:
      type: object
      required: [scans]
      properties:
        scans:
          type: array
          items: {$ref: '#/components/schemas/ScanSummary'}
        next_cursor:
          type: string
          format: date-time
          description: Pass as ?cursor= to fetch the next page; absent when exhausted

    RuleRemediation:
      type: object
      description: >-
        Host-independent remediation summary from the kensa read model
        (facts only; risk level is operator policy, owned by OpenWatch).
      required: [available, mechanisms, restarts_services, reboot_behavior]
      properties:
        available:   {type: boolean, description: true when an automated (non-manual) remediation exists}
        mechanisms:
          type: array
          items: {type: string}
          description: distinct remediation mechanisms across implementations (e.g. config_set, service_enabled)
        restarts_services:
          type: array
          items: {type: string}
          description: services the remediation reloads or restarts
        reboot_behavior:
          type: string
          description: 'kensa reboot signal: "boot-param" (staged boot change, pending reboot) or "none" (not a complete requires-reboot answer)'

    RuleListItem:
      type: object
      description: One normalized Kensa rule for the library browser.
      required: [id, title, description, severity, category, tags, framework_refs, transactional, remediation]
      properties:
        id:          {type: string}
        title:       {type: string}
        description: {type: string}
        transactional: {type: boolean, description: the rule's apply path is a capturable atomic transaction (the "atomic" signal)}
        severity:    {type: string, description: 'critical | high | medium | low'}
        category:    {type: string}
        tags:
          type: array
          items: {type: string}
        framework_refs:
          type: object
          additionalProperties:
            type: array
            items: {type: string}
          description: framework_id -> control ids (same shape as scan results)
        remediation: {$ref: '#/components/schemas/RuleRemediation'}

    RuleList:
      type: object
      required: [rules, total]
      properties:
        rules:
          type: array
          items: {$ref: '#/components/schemas/RuleListItem'}
        total: {type: integer, description: total rules in the library}

    ScanRuleResult:
      type: object
      description: One rule's durable verdict for a scan. No inline check output.
      required: [rule_id, title, category, status, severity, framework_refs, has_evidence]
      properties:
        rule_id:  {type: string}
        title:    {type: string, description: human rule title from the catalog (falls back to rule_id)}
        category: {type: string, description: catalog category (falls back to "uncategorized")}
        status:   {type: string, description: 'pass | fail | skipped | error'}
        severity: {type: string, description: 'critical | high | medium | low | "" when unset'}
        description:
          type: string
          description: one-line catalog description of what the rule checks; empty when uncatalogued
        framework_refs:
          type: object
          additionalProperties:
            type: array
            items: {type: string}
          description: framework_id -> control ids
        skip_reason: {type: string}
        has_evidence:
          type: boolean
          description: true when this rule has stored check output to drill into

    ScanDetail:
      type: object
      required: [scan, results]
      properties:
        scan: {$ref: '#/components/schemas/ScanSummary'}
        results:
          type: array
          items: {$ref: '#/components/schemas/ScanRuleResult'}

    ScanCheckEvidence:
      type: object
      description: One command's reproducible evidence (mirrors kensa CheckEvidence).
      required: [method, exit_code]
      properties:
        method:    {type: string}
        command:   {type: string}
        stdout:    {type: string}
        stderr:    {type: string}
        exit_code: {type: integer}
        expected:  {type: string}
        actual:    {type: string}
        truncated: {type: boolean}

    ScanRuleEvidence:
      type: object
      description: One rule's full drill-down payload — the stored evidence unwrapped plus metadata.
      required: [rule_id, status, severity, detail, checks, framework_refs]
      properties:
        rule_id:  {type: string}
        status:   {type: string, description: 'pass | fail | skipped | error'}
        severity: {type: string}
        detail:   {type: string, description: human-readable verdict context}
        error:    {type: string, description: present only when status is error}
        checks:
          type: array
          items: {$ref: '#/components/schemas/ScanCheckEvidence'}
        framework_refs:
          type: object
          additionalProperties:
            type: array
            items: {type: string}
        skip_reason: {type: string}

    OscalDocument:
      type: object
      description: >-
        An OSCAL 1.0.6 Assessment Results document (JSON), as produced by
        Kensa's exporter. Opaque to OpenWatch — passed through verbatim.
      additionalProperties: true

    GroupCreate:
      type: object
      required: [name, kind, membership]
      properties:
        name: {type: string}
        kind:
          type: string
          enum: [site, os_category]
        subtype: {type: string}
        color:   {type: string}
        membership:
          type: string
          enum: [manual, auto]
        match_family:
          type: string
          description: Required for auto membership; must be empty for manual

    GroupUpdate:
      type: object
      required: [name]
      properties:
        name:    {type: string}
        subtype: {type: string}
        color:   {type: string}

    GroupMaintenanceRequest:
      type: object
      required: [on]
      properties:
        on: {type: boolean}

    GroupMemberRequest:
      type: object
      required: [host_id]
      properties:
        host_id: {type: string, format: uuid}

    HostComplianceSchedule:
      type: object
      required: [scheduler_enabled, scheduler_paused, compliance_state,
                 interval_minutes, host_maintenance]
      properties:
        scheduler_enabled:
          type: boolean
          description: The scan config enabled flag
        scheduler_paused:
          type: boolean
          description: True when the scheduler dispatches nothing fleet-wide (disabled or global maintenance)
        compliance_state:
          type: string
          enum: [critical, non_compliant, partial, mostly_compliant, compliant, unknown]
        next_scan_at:
          type: string
          format: date-time
          nullable: true
          description: Null when the host has no schedule row yet
        interval_minutes:
          type: integer
          description: Current per-state interval; 0 when unseeded
        host_maintenance:
          type: boolean
          description: Per-host maintenance flag on the schedule row

    HostComplianceTrend:
      type: object
      required: [days]
      properties:
        days:
          type: array
          description: One entry per day with a snapshot, oldest first
          items:
            type: object
            required: [date, score_pct, passing, failing, total]
            properties:
              date:
                type: string
                format: date
              score_pct:
                type: number
              passing:
                type: integer
              failing:
                type: integer
              total:
                type: integer

    FleetComplianceTrend:
      type: object
      required: [days]
      properties:
        days:
          type: array
          description: One entry per day with snapshots, oldest first
          items:
            type: object
            required: [date, avg_score_pct, hosts, failing, critical_hosts]
            properties:
              date:
                type: string
                format: date
              avg_score_pct:
                type: number
              hosts:
                type: integer
              failing:
                type: integer
              critical_hosts:
                type: integer

    FleetComplianceStates:
      type: object
      required: [states]
      properties:
        states:
          type: array
          description: One entry per ComplianceState in ladder order; zero-count states included
          items:
            type: object
            required: [state, host_count]
            properties:
              state:
                type: string
                enum: [critical, non_compliant, partial, mostly_compliant, compliant, unknown]
              host_count:
                type: integer

    ConnectivityStatus:
      type: object
      required: [probe_count, probe_success_count, probe_failure_count, state_transition_count, maintenance_active]
      properties:
        last_probe_at:
          type: string
          format: date-time
          nullable: true
          description: Most recent probe-start time; null until the first tick
        probe_count:           {type: integer, format: int64}
        probe_success_count:   {type: integer, format: int64}
        probe_failure_count:   {type: integer, format: int64}
        state_transition_count: {type: integer, format: int64}
        maintenance_active:
          type: boolean
          description: Mirrors connectivity_config.maintenance_global

    ConnectivityCheckResult:
      type: object
      required: [reachable, response_time_ms, probed_at, new_reachability_status]
      properties:
        reachable:        {type: boolean}
        response_time_ms: {type: integer, description: 0 on failure}
        error_type:
          type: string
          nullable: true
          description: tcp_timeout, connection_refused, banner_mismatch, or tcp_error; null on success
        probed_at:        {type: string, format: date-time}
        new_reachability_status:
          type: string
          enum: [reachable, unreachable, unknown]
          description: Post-hysteresis status (same value the periodic loop would write)

    ScanRunQueued:
      type: object
      required: [scan_id, status, queued_at]
      properties:
        scan_id:   {type: string, format: uuid, description: scan_runs.id == queue job id == transactions.scan_id}
        status:    {type: string, enum: [queued]}
        queued_at: {type: string, format: date-time}

    IntelligenceEvent:
      type: object
      required: [id, host_id, event_code, severity, occurred_at, detected_at]
      properties:
        id:             {type: string, format: uuid}
        host_id:        {type: string, format: uuid}
        event_code:     {type: string, description: 'Closed taxonomy: e.g. system.package.updated'}
        severity:       {type: string, enum: [info, low, medium, high, critical]}
        detail:
          type: object
          additionalProperties: true
        occurred_at:    {type: string, format: date-time}
        detected_at:    {type: string, format: date-time}
        correlation_id: {type: string}

    IntelligenceEventsPage:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/IntelligenceEvent'}
        next_cursor:
          type: string
          nullable: true

    IntelligenceState:
      type: object
      required: [host_id, snapshot, collected_at]
      properties:
        host_id:      {type: string, format: uuid}
        snapshot:
          type: object
          additionalProperties: true
          description: Free-form host_intelligence_state.snapshot — mirrors collector.Snapshot
        collected_at: {type: string, format: date-time}

    Alert:
      type: object
      required: [id, dedup_key, alert_type, severity, title, state, occurred_at]
      properties:
        id:           {type: string, format: uuid}
        dedup_key:    {type: string}
        alert_type:   {type: string}
        severity:     {type: string, enum: [info, low, medium, high, critical]}
        host_id:      {type: string, format: uuid, nullable: true}
        rule_id:      {type: string}
        title:        {type: string}
        body:         {type: string}
        tags:
          type: object
          additionalProperties: {type: string}
        state:        {type: string, enum: [active, acknowledged, silenced, resolved, dismissed]}
        occurred_at:  {type: string, format: date-time}
        acknowledged_by: {type: string, format: uuid, nullable: true}
        acknowledged_at: {type: string, format: date-time, nullable: true}
        silenced_by:     {type: string, format: uuid, nullable: true}
        silenced_until:  {type: string, format: date-time, nullable: true}
        resolved_by:     {type: string, format: uuid, nullable: true}
        resolved_at:     {type: string, format: date-time, nullable: true}
        dismissed_by:    {type: string, format: uuid, nullable: true}
        dismissed_at:    {type: string, format: date-time, nullable: true}
        created_at:      {type: string, format: date-time}
        updated_at:      {type: string, format: date-time}

    AlertsPage:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/Alert'}
        next_cursor:
          type: string
          nullable: true

    Activity:
      type: object
      required: [id, source, severity, title, occurred_at]
      properties:
        id:          {type: string, format: uuid}
        source:      {type: string, enum: [alert, transaction, intelligence, audit, monitoring]}
        severity:    {type: string, enum: [info, low, medium, high, critical]}
        host_id:     {type: string, format: uuid, nullable: true}
        title:       {type: string}
        summary:     {type: string}
        occurred_at: {type: string, format: date-time}

    ActivityPage:
      type: object
      required: [items, hidden_count]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/Activity'}
        hidden_count: {type: integer, minimum: 0}
        next_cursor:
          type: string
          nullable: true

    AlertLifecycleRequest:
      type: object
      description: 'Optional body for POST lifecycle endpoints. silence accepts an optional until; all accept a reason for the audit detail.'
      properties:
        reason: {type: string, maxLength: 256}
        until:  {type: string, format: date-time, nullable: true}

    HostSystemInfo:
      type: object
      required: [host_id, collected_at]
      description: |
        Result of a Discovery run. Mirrors the host_system_info table
        column-for-column. Spec system-host-discovery.
      properties:
        host_id:             {type: string, format: uuid}
        # /etc/os-release
        os_name:             {type: string, nullable: true}
        os_version:          {type: string, nullable: true}
        os_version_full:     {type: string, nullable: true}
        os_id:               {type: string, nullable: true}
        os_id_like:          {type: string, nullable: true}
        os_pretty_name:      {type: string, nullable: true}
        platform_identifier: {type: string, nullable: true}
        os_family:           {type: string, nullable: true, description: 'Distro ID from /etc/os-release (rhel, ubuntu, rocky, ...); rollup family (rhel/debian/suse/alpine/arch/gentoo/other) only when ID was empty. Spec system-host-discovery v1.3.0 AC-22.'}
        # uname -srvm
        kernel_name:    {type: string, nullable: true}
        kernel_release: {type: string, nullable: true}
        kernel_version: {type: string, nullable: true}
        architecture:   {type: string, nullable: true}
        # /proc/meminfo
        mem_total_mb:     {type: integer, nullable: true}
        mem_available_mb: {type: integer, nullable: true}
        swap_total_mb:    {type: integer, nullable: true}
        # df -BG /
        disk_total_gb: {type: integer, nullable: true}
        disk_used_gb:  {type: integer, nullable: true}
        disk_free_gb:  {type: integer, nullable: true}
        # hostname
        hostname: {type: string, nullable: true}
        fqdn:     {type: string, nullable: true}
        # security posture
        selinux_status:   {type: string, nullable: true, description: 'Enforcing | Permissive | Disabled | empty if not present'}
        apparmor_enabled: {type: boolean, nullable: true}
        # firewall (may be empty if sudo unavailable — partial success per spec C-03)
        firewall_service: {type: string, nullable: true, description: 'firewalld | ufw | nftables | iptables | empty'}
        firewall_status:  {type: string, nullable: true}
        collected_at:     {type: string, format: date-time}

    FleetRuleFailure:
      type: object
      required: [rule_id, failing_host_count]
      properties:
        rule_id: {type: string}
        failing_host_count: {type: integer, format: int64}

    FleetTopFailingRules:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/FleetRuleFailure'}

    FleetHostFailure:
      type: object
      required: [host_id, failing_rule_count]
      properties:
        host_id: {type: string, format: uuid}
        failing_rule_count: {type: integer, format: int64}

    FleetTopFailingHosts:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/FleetHostFailure'}

    FleetTransaction:
      type: object
      required: [id, host_id, rule_id, status, change_kind, occurred_at]
      properties:
        id:          {type: string, format: uuid}
        host_id:     {type: string, format: uuid}
        rule_id:     {type: string}
        status:      {type: string, enum: [pass, fail, skipped, error]}
        severity:    {type: string}
        change_kind: {type: string, enum: [first_seen, state_changed, severity_changed]}
        occurred_at: {type: string, format: date-time}

    FleetRecentChanges:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/FleetTransaction'}

    ErrorEnvelope:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, fault, retryable, human_message]
          properties:
            code: {type: string}
            fault: {type: string, enum: [client, server, policy, external]}
            retryable: {type: boolean}
            human_message: {type: string}
            detail: {type: object, additionalProperties: true}
            correlation_id: {type: string}

    AuthMePermissionsResponse:
      type: object
      required: [identity, permissions]
      properties:
        identity:
          type: object
          required: [id, role, is_anonymous]
          properties:
            id: {type: string}
            role: {type: string}
            is_anonymous: {type: boolean}
        permissions:
          type: array
          items: {type: string}

    PermissionEntry:
      type: object
      required: [id, category, description, dangerous]
      properties:
        id: {type: string}
        category: {type: string}
        description: {type: string}
        dangerous: {type: boolean}
        license_gated: {type: string}

    CategoryEntry:
      type: object
      required: [id, description]
      properties:
        id: {type: string}
        description: {type: string}

    RoleEntry:
      type: object
      required: [id, description, permissions, is_built_in]
      properties:
        id: {type: string}
        description: {type: string}
        is_built_in: {type: boolean}
        permissions:
          type: array
          items: {type: string}

    PermissionsRegistryResponse:
      type: object
      required: [categories, permissions, roles]
      properties:
        categories:
          type: array
          items: {$ref: '#/components/schemas/CategoryEntry'}
        permissions:
          type: array
          items: {$ref: '#/components/schemas/PermissionEntry'}
        roles:
          type: array
          items: {$ref: '#/components/schemas/RoleEntry'}

    AdminRolesResponse:
      type: object
      required: [roles]
      properties:
        roles:
          type: array
          items: {$ref: '#/components/schemas/RoleEntry'}

    EvaluateAlertRequest:
      type: object
      required: [score]
      properties:
        score: {type: integer, minimum: 0, maximum: 100}

    PolicyDecisionResponse:
      type: object
      required: [outcome, policy_type, policy_version, reason]
      properties:
        outcome:        {type: string}
        policy_type:    {type: string}
        policy_version: {type: string}
        reason:         {type: string}
        human_message:  {type: string}
        detail:         {type: object, additionalProperties: true}

    EnqueueTestJobResponse:
      type: object
      required: [job_id, correlation_id]
      properties:
        job_id:         {type: string, format: uuid}
        correlation_id: {type: string}

    PoliciesReloadResponse:
      type: object
      required: [outcomes]
      properties:
        outcomes:
          type: object
          additionalProperties: {type: string}