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
  version: 0.2.1
  description: |
    The OpenWatch REST API: authentication, hosts, scans, compliance posture,
    remediation, reports, notifications, and administration. All responses carry
    a correlation ID and a structured error envelope; mutating calls are
    idempotency-keyed and audited.

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

# The anonymous allowlist. Spec system-rbac C-10 and AC-26.
#
# Every POST, PUT, PATCH and DELETE below has to resolve to a gate. Either its
# handler proves who is asking, with an RBAC check on a typed permission or a
# check that the caller is not anonymous, or its operationId appears here. An
# operation on neither is a defect, and AC-26 fails the build for it. The point
# is that the next author has a question to answer rather than a list to keep.
#
# This list is the small side on purpose. It holds routes that cannot require a
# credential, because they are how a caller gets one. Nothing joins it without
# a reason written next to it, and a reason has to say why the route cannot be
# gated, not why gating it would be inconvenient.
#
# A route that rejects an anonymous caller does NOT belong here, even when its
# path starts with /auth. POST /auth/mfa:enroll, POST /auth/mfa:verify and POST
# /auth/password:change all run against an already-authenticated identity and
# answer 401 without one, so they resolve to a gate on their own. Adding them
# would be worse than redundant: an entry here exempts an operation from AC-26
# permanently, so if someone later deleted the check, the test would stay green
# while the route went open.
#
# Each operationId MUST still exist in paths below. A renamed or deleted route
# fails AC-26 rather than leaving a dead entry that quietly widens the rule.
x-anonymous-mutations:
  - operationId: postAuthLogin
    reason: >
      No identity exists yet. This route is what creates one, so it cannot
      require a caller to already have it.
  - operationId: postAuthLogout
    reason: >
      Logout is idempotent and answers 204 for an anonymous caller on purpose.
      It reads the identity, but only to decide whether there is a session to
      revoke, and it never rejects. A caller whose session already expired must
      still be able to clear the cookies.
  - operationId: postAuthRefresh
    reason: >
      The refresh token in the request body IS the credential being presented.
      Requiring a bound identity first would make the route unusable, since a
      client refreshes precisely when its access credential has expired.
  - operationId: postAuthRefreshCookie
    reason: >
      Same as postAuthRefresh, with the refresh token arriving in a cookie
      rather than the body.

x-anonymous-reads:
  - operationId: getCapabilities
    reason: >
      A client needs to know which capabilities this deployment has before it has an identity, so it can present a locked control instead of discovering the gate from a 402. The response carries capability ids, tiers and availability, and no license, customer or deployment detail.
  - operationId: getLicense
    reason: >
      Pre-auth by design (api-license C-06, C-09): an anonymous caller receives only tier, status and features, an allowlisted public field set; every other field is written only for a caller holding system:read, decided inside the handler.
  - operationId: getAuthPermissionsRegistry
    reason: >
      The static permission registry: permission ids, descriptions, categories and the built-in role bundles, all of which USER_ROLES.md publishes in this public repository. It reads no table and returns no user, assignment, custom role or deployment setting (system-rbac AC-30). Retained anonymous by founder decision, 2026-09-21.
  - operationId: getAuthMePermissions
    reason: >
      Introspection of the calling identity. An anonymous caller gets is_anonymous true and an empty permission list, which tells them only what they already are; the SPA uses it to decide whether to show the login page.
  - operationId: getSSOProvidersEnabled
    reason: >
      The login page must list the identity providers before anyone is signed in (api-sso). The response carries provider id and name only.
  - operationId: getAuthSSOLogin
    reason: >
      The SSO redirect that starts a sign-in; there is no identity yet (api-sso).
  - operationId: getAuthSSOCallback
    reason: >
      The SSO redirect-back that exchanges the code and creates the session; there is no identity yet (api-sso).
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'}
        '503':
          description: >-
            server.error. retryable true: sign-in did not complete and nothing was
            issued, including when the per-user lock was not acquired in time.
            retryable false: the outcome is unknown; sign in again rather than
            assuming either result.
          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
        '403':
          description: >-
            authz.csrf_invalid. A credential cookie selects what to revoke and the
            double-submit token is missing or does not match. Nothing was revoked and
            no cookie was changed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '500':
          description: >-
            auth.logout_incomplete, retryable. The revocation failed and rolled back,
            so nothing was revoked. Both cookies are cleared; the session may stay
            valid until it expires.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: >-
            server.error, not retryable, and both cookies are cleared. Two outcomes,
            told apart by the message. The account lock was not acquired in time:
            this attempt revoked nothing. The commit outcome is unknown: revocation
            could not be confirmed. Neither invites an automatic retry, because
            with the cookies cleared a repeated request may name no family, or a
            different one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'

  /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'}
        '503':
          description: >-
            server.error. retryable true: nothing was rotated, including when the
            per-user lock was not acquired in time. retryable false: the rotation
            outcome is unknown; sign in again rather than presenting the same token.
          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'}
        '503':
          description: >-
            server.error. retryable true: nothing was rotated and no cookie was
            set, including when the per-user lock was not acquired in time.
            retryable false: the rotation outcome is unknown.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'

  /api/v1/auth/me:
    get:
      operationId: getAuthMe
      x-requires-identity: true
      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'}
    patch:
      operationId: patchAuthMe
      x-requires-identity: true
      summary: Update the calling user's own profile
      description: >-
        Self-service profile edit for the authenticated user. The body is a
        partial: present fields are updated, omitted fields are unchanged.
        Changing email (the sign-in identity) is allowed but must be unique
        among active users (409 on conflict). Username, role, and password
        are NOT editable here (password uses /auth/password:change).
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/AuthMeUpdateRequest'}
      responses:
        '200':
          description: Updated identity
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AuthMeResponse'}
        '400':
          description: Malformed body or invalid field
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '401':
          description: No valid session or bearer
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '409':
          description: Email already in use by another active user
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/users/me/preferences:
    get:
      operationId: getUsersMePreferences
      x-requires-identity: true
      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
      x-requires-identity: true
      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
      x-requires-identity: true
      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
      x-requires-identity: true
      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
      x-requires-identity: true
      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
      # A successful call writes the caller's message into an audit event and
      # into a stored idempotency record. The message is capped at 1024
      # characters, so each write is bounded, but the call count is not.
      # Attacker-supplied text in the audit log is evidence integrity, not a
      # demo nit.
      x-required-permission: system:read
      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'
        '401':
          description: Caller is anonymous
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks system:read
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '409':
          description: Idempotency-Key reused with different body
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/capabilities:
    get:
      operationId: getCapabilities
      summary: What this deployment is entitled to use
      description: |
        The paywall, made visible. Returns every registered capability with
        whether THIS deployment can use it, so the interface can lock or
        upsell a control instead of letting a Community user click it and
        collect a 402.

        Deliberately unauthenticated, like GET /license: a pre-login screen
        needs to know what the deployment offers. It exposes no customer
        identity and no license key material, only capability ids, their tier,
        and whether each is available here.

        There are no quotas. Tiering is by capability alone: OpenWatch does not
        cap hosts, scans, or users.
      responses:
        '200':
          description: Capability set for this deployment
          content:
            application/json:
              schema: {$ref: '#/components/schemas/CapabilitiesResponse'}

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

  /api/v1/admin/license:verify:
    post:
      operationId: postAdminLicenseVerify
      x-required-permission: system:read
      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
      # RBAC resolves before entitlement, so a caller who lacks system:read
      # gets 401 or 403 and never learns whether this deployment is licensed
      # for premium_diagnostics. Spec api-license C-05, AC-17.
      x-required-permission: system:read
      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'}
        '401':
          description: Caller is anonymous
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '402':
          description: License does not include premium_diagnostics feature
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks system:read
          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
      # The response is this deployment's alert threshold policy, read back one
      # score at a time. A caller who walks the score from 0 to 100 learns
      # where each verdict flips, and the body names the loaded policy version.
      # That is policy content, so policy:read rather than the system:read its
      # sibling diagnostics routes use. Spec system-rbac AC-25.
      x-required-permission: policy:read
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/EvaluateAlertRequest'}
      responses:
        '200':
          description: Policy decision
          content:
            application/json:
              schema: {$ref: '#/components/schemas/PolicyDecisionResponse'}
        '401':
          description: Caller is anonymous
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks policy:read
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/diagnostics:enqueue-test-job:
    post:
      operationId: postDiagnosticsEnqueueTestJob
      x-required-permission: system:config_write
      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'}
        '503':
          description: >-
            server.error. retryable true: a lock wait exceeded its limit and the
            transaction rolled back, so the user was not deleted. retryable false:
            the commit outcome is unknown.
          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'}
        '503':
          description: >-
            server.error. retryable true: a lock wait exceeded its limit and the
            transaction rolled back, so the change was not applied. retryable
            false: the commit outcome is unknown, and the change may or may not
            have been applied.
          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'}
        '503':
          description: >-
            server.error. retryable true: a lock wait exceeded its limit and the
            transaction rolled back, so the change was not applied. retryable
            false: the commit outcome is unknown, and the change may or may not
            have been applied.
          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'}
        '503':
          description: >-
            server.error. retryable true: a lock wait exceeded its limit and the
            transaction rolled back, so the change was not applied. retryable
            false: the commit outcome is unknown, and the change may or may not
            have been applied.
          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}}
        - {name: framework, in: query, required: false, schema: {type: string}, description: 'Lens each host card''s compliance_summary through a framework family (e.g. "stig") or a specific corpus key; omit for All rules.'}
      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
      x-required-permission: audit:read
      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:export gated (the list
        endpoint stays audit:read; auditor, security_admin and admin hold
        audit:export). 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:export
      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: correlation_id
          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:
        '400':
          description: A query parameter the export does not declare (request.unknown_parameter), or one that fails to parse.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '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
      x-required-permission: system:read
      summary: Fleet-wide compliance score (equal-host mean)
      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/AggregateScore'}
        '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
      x-required-permission: system:read
      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
      x-required-permission: system:read
      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
      x-required-permission: system:read
      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
      x-required-permission: system:read
      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
      x-required-permission: system:read
      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
      x-required-permission: system:read
      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
      x-required-permission: system:config_write
      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
      x-required-permission: system:read
      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
      x-required-permission: system:config_write
      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
      x-required-permission: system:read
      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
      x-required-permission: system:config_write
      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
      x-required-permission: system:config_write
      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/compliance/frameworks:
    get:
      operationId: getComplianceFrameworks
      summary: List the framework families present in the scanned corpus
      x-required-permission: host:read
      description: >
        Framework families derived at runtime from
        host_rule_state.framework_refs (STIG, CIS, NIST 800-53, …), each with
        a display label and the concrete corpus keys it spans. Feeds the
        default-lens picker. Empty until at least one host is scanned. By
        default the list is narrowed to the enabled-frameworks allowlist (if
        set); pass all=true to return every corpus family (for the allowlist
        editor).
      parameters:
        - name: all
          in: query
          required: false
          description: When true, return every corpus family, ignoring the enabled-frameworks allowlist.
          schema: {type: boolean, default: false}
      responses:
        '200':
          description: Families
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ComplianceFrameworksResponse'}
        '401':
          description: No valid session or bearer
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/system/compliance/config:
    get:
      operationId: getSystemComplianceConfig
      summary: Read the org-wide compliance-display config (default lens)
      x-required-permission: system:read
      responses:
        '200':
          description: Current compliance config
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ComplianceConfig'}
        '403':
          description: Caller lacks system:read
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    put:
      operationId: putSystemComplianceConfig
      summary: Set the default compliance lens (framework family, or empty for All rules)
      x-required-permission: system:config_write
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ComplianceConfig'}
      responses:
        '200':
          description: Updated compliance config
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ComplianceConfig'}
        '400':
          description: Invalid default_framework
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '403':
          description: Caller lacks system:config_write
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/system/scan/config:
    get:
      operationId: getSystemScanConfig
      x-required-permission: system:read
      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
      x-required-permission: system:config_write
      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
      x-required-permission: system:read
      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
      x-required-permission: host:read
      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
      x-required-permission: system:read
      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
      x-required-permission: system:config_write
      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}:target:
    post:
      operationId: postHostTarget
      summary: Set or clear a host's compliance target framework
      description: |
        Sets (or clears, when target_framework is empty) the host's own
        compliance target family - the per-host override that wins over any
        site-group target in the effective-target resolution. A host may always
        carry its own target (no site-only constraint). RBAC: host:write.
        Spec api-hosts, system-compliance-lens.
      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/HostTargetRequest'}
      responses:
        '200':
          description: The updated host
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HostResponse'}
        '400':
          description: An invalid target family value
          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: Host not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/hosts/{id}/exceptions:
    get:
      operationId: getHostExceptions
      x-required-permission: exception:read
      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
      x-required-permission: exception:request
      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
      x-required-permission: exception:read
      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
      x-required-permission: exception:approve
      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
      x-required-permission: exception:approve
      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
      x-required-permission: exception:revoke
      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 Enterprise 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, staged, reverted, not_applied, partially_applied]
        - 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 Enterprise 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}/plan:
    get:
      operationId: getRemediationPlan
      summary: Preview what a remediation would do, without changing the host
      description: |
        Asks Kensa to plan the request's rule against its host: the apply steps
        that would run, the validators that would check them, and how each
        would be reversed. Read-only. Kensa captures pre-state during planning
        but does not apply anything.

        This reaches the host over SSH, so it is a live call and fails the way
        a scan does when the host is unreachable. It is not cached: a plan
        describes the host as it is now, and a stale preview is worse than none.

        Free core, like the single-rule fix it previews. 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 plan
          content:
            application/json:
              schema: {$ref: '#/components/schemas/RemediationPlan'}
        '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'}
        '502':
          description: |
            The host could not be planned against (unreachable, auth, or sudo).
            The body names which.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
        '503':
          description: Planning is unavailable because the Kensa rule corpus is not loaded
          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
      x-required-permission: host:read
      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
      x-required-permission: host:write
      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
      x-required-permission: host:write
      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
      x-required-permission: host:write
      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
      x-required-permission: host:write
      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}:target:
    post:
      operationId: postGroupTarget
      x-required-permission: host:write
      summary: Set or clear a site group's compliance target framework
      description: |
        Sets (or clears, when target_framework is empty) the compliance
        target family a member host is held to. Only a site group may carry a
        target; an os_category group is rejected 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/GroupTargetRequest'}
      responses:
        '200':
          description: The updated group
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Group'}
        '400':
          description: Target on a non-site group, or an invalid family value
          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:
    post:
      operationId: postGroupMember
      x-required-permission: host:write
      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
      x-required-permission: host:write
      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
      x-required-permission: host:read
      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
      x-required-permission: host:write
      # Gated on the REQUEST, not the route: only report kind `attestation`
      # requires the entitlement. The rest of this route is free, so a
      # route-level x-required-feature would be a false claim.
      x-conditional-feature: compliance_attestation
      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 optional
        body scopes the summary to a group's member hosts and/or a
        framework lens; an empty body covers all hosts and all
        frameworks. RBAC: host:write. Spec api-reports.
      requestBody:
        required: false
        content:
          application/json:
            schema: {$ref: '#/components/schemas/GenerateReportRequest'}
      responses:
        '201':
          description: The generated report
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Report'}
        '400':
          description: Malformed body or an unknown group_id scope
          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'}

  /api/v1/reports/frameworks:
    get:
      operationId: getReportFrameworks
      x-required-permission: host:read
      summary: List the framework lenses available across the fleet
      description: |
        Returns the distinct framework_refs keys present anywhere in the
        fleet (across host_rule_state), each with the count of distinct
        rules mapped to it, most-populated first. Backs the report scope
        picker's framework lens. RBAC: host:read. Spec api-reports.
      responses:
        '200':
          description: The fleet framework catalog
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ReportFrameworksResponse'}
        '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/schedules:
    get:
      operationId: getReportSchedules
      x-required-permission: host:read
      summary: List the report delivery schedules
      description: |
        Returns every scheduled report (daily/weekly/monthly cadence that
        generates a report and emails its PDF through a notification
        channel), newest first. RBAC: host:read. Spec system-report-schedule.
      responses:
        '200':
          description: The schedules
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ReportScheduleList'}
        '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: createReportSchedule
      x-required-permission: host:write
      # Gated on the REQUEST, not the route: only report kind `attestation`
      # requires the entitlement. The rest of this route is free, so a
      # route-level x-required-feature would be a false claim.
      x-conditional-feature: compliance_attestation
      summary: Create a report delivery schedule
      description: |
        Schedules a report to generate on a daily/weekly/monthly cadence and
        email its PDF through an email notification channel. RBAC:
        host:write. Spec system-report-schedule.
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CreateReportScheduleRequest'}
      responses:
        '201':
          description: The created schedule
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ReportSchedule'}
        '400':
          description: Invalid request
          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'}

  /api/v1/reports/schedules/{id}:
    patch:
      operationId: updateReportSchedule
      x-required-permission: host:write
      summary: Enable or disable a report schedule
      description: |
        Toggles a schedule's enabled flag. Re-enabling recomputes the next
        run from now. RBAC: host:write. Spec system-report-schedule.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/UpdateReportScheduleRequest'}
      responses:
        '200':
          description: The updated schedule
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ReportSchedule'}
        '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: Schedule not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}
    delete:
      operationId: deleteReportSchedule
      x-required-permission: host:write
      summary: Delete a report schedule
      description: |
        Removes a schedule (does not delete reports it already generated).
        RBAC: host:write. Spec system-report-schedule.
      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: Schedule not found
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/reports/signing-key:
    get:
      operationId: getReportSigningKey
      x-required-permission: host:read
      summary: The public key for verifying report signatures
      description: |
        Returns the Ed25519 public key (with its key id) used to sign
        report snapshots, so a caller can verify a report's signature over
        its content_sha256 offline. RBAC: host:read. Spec api-reports.
      responses:
        '200':
          description: The report signing public key
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ReportSigningKey'}
        '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'}
        '503':
          description: No signer configured
          content:
            application/json:
              schema: {$ref: '#/components/schemas/ErrorEnvelope'}

  /api/v1/reports/{id}:
    get:
      operationId: getReportByID
      x-required-permission: host:read
      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/reports/{id}/export:
    get:
      operationId: getReportExport
      x-required-permission: host:read
      # Gated on the REQUEST, not the route: only report kind `attestation`
      # requires the entitlement. The rest of this route is free, so a
      # route-level x-required-feature would be a false claim.
      x-conditional-feature: compliance_attestation
      summary: Download a rendered face of a report (PDF, JSON, CSV, or OSCAL SAR)
      description: |
        Streams a rendered face of the report as a downloadable
        attachment. format=pdf (default) renders the bounded one-page PDF,
        dispatched by kind: the executive summary (a fixed posture block,
        the coverage caveat, and the top-failing list) or the framework
        attestation cover (a methodology note, the aggregate coverage +
        framework rollup, a sampled top-failing list, and a content-hash
        pointer to the bulk faces) - never the full per-host/per-rule
        evidence. format=json returns the canonical frozen posture content
        (any kind). For an attestation report, format=csv returns the
        per-(host, rule) evidence extract and format=oscal_sar returns a
        single OSCAL 1.0.6 assessment-results document (one observation +
        finding per (host, rule), evidence referenced by sha256 in
        back-matter, not inlined). A face that does not apply to the
        report's kind is a 400. Each face is rendered on first request and
        cached in report_faces, so a repeat download re-streams the stored
        bytes. RBAC: host:read. Spec api-reports.
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
        - name: format
          in: query
          required: false
          description: The face to render. Defaults to pdf.
          schema: {type: string, enum: [pdf, json, csv, oscal_sar], default: pdf}
      responses:
        '200':
          description: The rendered face, as a downloadable attachment
          content:
            application/pdf:
              schema: {type: string, format: binary}
            text/csv:
              schema: {type: string}
            application/json:
              schema: {type: object, additionalProperties: true}
        '400':
          description: Unknown format
          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: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
      x-required-permission: system:read
      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
      x-required-permission: host:connectivity_check
      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
      x-required-permission: host:write
      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
      x-required-permission: host:read
      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 over passing plus failing, one decimal, NULL when no
        rule produced a verdict), a coverage_status with its
        percentage, and the envelope that says how the score was
        produced. 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
      x-required-permission: host:read
      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
      x-required-permission: host:read
      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. A day
        is absent from the array when it has no snapshot AND when its
        snapshot holds no score, which happens when no rule produced a
        verdict that day. score_pct cannot express that absence, so the
        day is omitted rather than reported as 0.0; 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
      x-required-permission: host:read
      summary: Daily fleet compliance trend
      description: |
        Per-day fleet aggregates over the trailing window (default 30
        days, clamped 1..90): average score, host count, total failing
        rules, and hosts carrying critical findings. Powers the
        hosts-page average-compliance delta.

        score_pct is the mean of the hosts that produced a SCORE
        that day, counting each host once. hosts counts every host with
        a snapshot that day, so the two differ whenever a host could not
        be assessed; such a host is omitted from the average rather than
        averaged in as zero. A day on which no host produced a score
        still appears, carrying score_pct: null with its host counts and
        formula_status, so a client can say WHY there is no number
        instead of showing a gap. That day used to be dropped from the
        array, because score_pct could not express absence; it is
        nullable now, so it can.
        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
      x-required-permission: host:read
      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
      x-required-permission: host:read
      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
      x-required-permission: host:read
      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
      x-required-permission: host:read
      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
      x-required-permission: host:read
      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
      x-required-permission: alert:read
      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
      x-required-permission: alert:read
      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
      x-required-permission: alert:write
      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
      x-required-permission: alert:write
      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
      x-required-permission: alert:write
      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
      x-required-permission: alert:write
      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
      x-requires-identity: true
      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
      x-required-permission: host:read
      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
      x-required-permission: host:write
      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: system-notifications — the in-app notification feed (the bell).
  /api/v1/notifications/feed:
    get:
      operationId: getNotificationFeed
      x-requires-identity: true
      summary: List the calling user's in-app notifications (the bell)
      description: >
        Self-scoped: any authenticated identity reads its own notifications; no
        special permission. Returns recent notifications newest-first plus the
        unread count for the badge. Spec system-notifications.
      parameters:
        - name: unread
          in: query
          required: false
          schema: {type: boolean}
          description: When true, return only unread notifications.
        - name: limit
          in: query
          required: false
          schema: {type: integer, minimum: 1, maximum: 200}
          description: Max items to return (default 50).
      responses:
        '200':
          description: The caller's notification feed
          content:
            application/json:
              schema: {$ref: '#/components/schemas/NotificationFeed'}
        '503': {$ref: '#/components/responses/ServiceUnavailable'}
  /api/v1/notifications/feed:read-all:
    post:
      operationId: postNotificationFeedReadAll
      x-requires-identity: true
      summary: Mark all the calling user's notifications read
      responses:
        '200':
          description: Number of notifications marked read
          content:
            application/json:
              schema: {$ref: '#/components/schemas/NotificationReadResult'}
        '503': {$ref: '#/components/responses/ServiceUnavailable'}
  /api/v1/notifications/feed/{id}:read:
    post:
      operationId: postNotificationFeedRead
      x-requires-identity: true
      summary: Mark one notification read (must belong to the caller)
      parameters:
        - name: id
          in: path
          required: true
          schema: {type: string, format: uuid}
      responses:
        '204': {description: Marked read}
        '404': {$ref: '#/components/responses/NotFound'}
        '503': {$ref: '#/components/responses/ServiceUnavailable'}

  # 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}
        full_name:    {type: string, description: Editable profile field (may be empty)}
        display_name: {type: string, description: Editable profile field (may be empty)}
        job_title:    {type: string, description: Editable profile field (may be empty)}
        timezone:     {type: string, description: IANA timezone, editable (may be empty)}
        phone:        {type: string, description: Editable profile field (may be empty)}

    AuthMeUpdateRequest:
      type: object
      description: >-
        Partial self-profile update. Every field is optional; a present field
        replaces the stored value (empty string clears it). Omitted fields are
        left unchanged.
      properties:
        email:        {type: string, description: Sign-in identity; must be unique among active users}
        full_name:    {type: string, maxLength: 256}
        display_name: {type: string, maxLength: 256}
        job_title:    {type: string, maxLength: 256}
        timezone:     {type: string, maxLength: 64}
        phone:        {type: string, maxLength: 64}

    # 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)}
        smtp_encryption: {type: string, nullable: true, description: SMTP transport security (email channels) - none|starttls|tls}
        smtp_insecure_skip_verify: {type: boolean, nullable: true, description: Skip TLS cert verification for an internal relay with a self-signed/private-CA cert (email channels; STARTTLS/TLS only)}
        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'}
    NotificationFeedItem:
      type: object
      required: [id, kind, severity, title, occurred_at, read]
      description: One in-app notification (the bell). Self-scoped to the caller.
      properties:
        id:          {type: string, format: uuid}
        kind:        {type: string, description: 'Change/alert kind, e.g. host_unreachable or drift_major'}
        severity:    {type: string, enum: [critical, high, medium, low, info]}
        title:       {type: string}
        body:        {type: string}
        host_id:     {type: string, format: uuid, nullable: true, description: 'Present for host-scoped changes'}
        link:        {type: string, description: 'Deep-link target for the notification'}
        occurred_at: {type: string, format: date-time}
        read:        {type: boolean, description: 'True when the caller has read it'}
    NotificationFeed:
      type: object
      required: [items, unread_count]
      properties:
        items:
          type: array
          items: {$ref: '#/components/schemas/NotificationFeedItem'}
        unread_count: {type: integer, description: 'Count of the unread notifications (badge value)'}
    NotificationReadResult:
      type: object
      required: [marked_read]
      properties:
        marked_read: {type: integer, description: Number of notifications marked read}
    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.}
        smtp_encryption:
          type: string
          enum: [none, starttls, tls]
          description: >-
            Transport security for the SMTP connection (email). 'starttls'
            (default) connects plaintext then requires a STARTTLS upgrade;
            'tls' uses implicit TLS from connect (SMTPS, e.g. port 465);
            'none' is plaintext for a trusted local relay. Omitted defaults
            to starttls.
        smtp_insecure_skip_verify:
          type: boolean
          description: >-
            Skip TLS certificate verification for the SMTP handshake (email).
            For an internal relay with a self-signed or private-CA cert only;
            a MITM-exposing downgrade, inert under 'none'. Defaults false.
        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}
        smtp_encryption: {type: string, enum: [none, starttls, tls]}
        smtp_insecure_skip_verify: {type: boolean}
        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}
        # Phase 3 (compliance-targets) — the host's OWN target framework
        # (nil = inherit the site-group target, else the org default). The
        # per-host override; wins over any group target. Spec api-hosts.
        target_framework:    {type: string, description: "Host's own compliance target framework family (absent when unset/inheriting)."}

    # 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, score_pct,
                 coverage_status, coverage_pct, envelope]
      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
          nullable: true
          description: >-
            Passing over passing plus failing, to one decimal. NULL when no rule
            produced a verdict. This is the PRIMARY single-host score, and it is
            computed server side: the host detail page used to derive
            passing/total in the browser, so a host whose rules all skipped
            displayed 0% instead of no score.
        coverage_status:
          type: string
          enum: [available, unavailable_unclassified_skips, unavailable_no_outcomes]
          description: Whether coverage can be stated for this host, and if not, why.
        coverage_pct:
          type: number
          format: double
          nullable: true
          description: Non-null if and only if coverage_status is available.
        envelope:
          $ref: '#/components/schemas/ScoreEnvelope'
          description: How this host's score was produced.

    # 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.
        scan_state:
          type: string
          enum: [queued, running]
          nullable: true
          description: >
            In-flight scan state for this host, independent of the latest
            COMPLETED run above. 'queued' = enqueued, awaiting a worker;
            'running' = actively executing; null = no scan in flight. Drives
            the host-detail hero "Running"/"Queued" badge. Spec
            api-host-compliance AC-17.

    HostComplianceLensSummary:
      type: object
      required: [passing, failing, skipped, error, total, score_pct,
                 coverage_status, coverage_pct, envelope]
      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
          nullable: true
          description: >-
            Passing over passing plus failing, to one decimal. NULL when no rule
            produced a verdict, which is a different fact from every evaluated
            rule failing (that is 0).
        coverage_status:
          type: string
          enum: [available, unavailable_unclassified_skips, unavailable_no_outcomes]
          description: >-
            Whether the share of in-scope rules that produced a verdict can be
            stated, and when it cannot, why.
        coverage_pct:
          type: number
          format: double
          nullable: true
          description: Non-null if and only if coverage_status is available.
        envelope:
          $ref: '#/components/schemas/ScoreEnvelope'
          description: >-
            How this host's score was produced. aggregation_method is none: one
            host aggregates nothing.

    HostComplianceCategory:
      type: object
      required: [category, passing, failing, total, score_pct]
      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}
        score_pct:
          type: number
          format: double
          nullable: true
          description: >-
            Passing over passing plus failing within this category, to one
            decimal, computed server side. NULL when the category produced no
            verdict. Sent rather than derived so the browser holds no compliance
            arithmetic (system-compliance-scoring C-14).

    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, envelope]
      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
          nullable: true
          description: >-
            Passing over passing plus failing, to one decimal. NULL when this
            framework's rules produced no verdict. Not over rule_count, which
            counts rules that were skipped or errored. Powers the per-lens score
            on the View-as chips.
        envelope:
          $ref: '#/components/schemas/ScoreEnvelope'
          description: How this chip's score was produced. Its lens is framework_id.

    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, score_pct,
                 coverage_status, coverage_pct, envelope]
      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).
        score_pct:
          type: number
          format: double
          nullable: true
          description: >-
            Passing over passing plus failing, to one decimal, computed server
            side. NULL when the host produced no verdict. Added so the hosts list
            stops deriving a compliance percentage in the browser, which produced
            a second formula the rest of the product could not agree with
            (system-compliance-scoring C-14).
        coverage_status:
          type: string
          enum: [available, unavailable_unclassified_skips, unavailable_no_outcomes]
          description: Whether coverage can be stated for this host, and if not, why.
        coverage_pct:
          type: number
          format: double
          nullable: true
          description: Non-null if and only if coverage_status is available.
        envelope:
          $ref: '#/components/schemas/ScoreEnvelope'
          description: How this host's score was produced.

    # 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'}
        # v1.7.0 — MAX(host_rule_state.last_checked_at); null when the host
        # has never been checked. Drives the detail hero "LAST SCAN" tile.
        # Spec api-hosts C-14.
        last_scan_at: {type: string, format: date-time, nullable: true}
        # v1.7.0 — in-flight scan state (queued|running); null when idle.
        # Independent of last_scan_at. Drives the detail hero "Running"/
        # "Queued" badge, updated live via scan.started/scan.completed SSE.
        # Spec api-hosts C-14.
        scan_state:
          type: string
          enum: [queued, running]
          nullable: true

    # 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}
        # v1.7.0 — in-flight scan state for this host, independent of
        # last_scan_at/latest_scan_id (which track the latest COMPLETED
        # run). 'queued' = enqueued awaiting a worker; 'running' = actively
        # executing; null = idle. Loaded with one grouped query over the
        # scan_runs_active partial index for the whole page (no N+1). Drives
        # the hosts-list card/row + scans-coverage "Running"/"Queued"
        # indicator. Spec api-hosts C-14.
        scan_state:
          type: string
          enum: [queued, running]
          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 rows in its current corpus. That is not
            the same as never scanned: a completed scan that produced no outcome
            writes no rule state either, and the two are indistinguishable from
            this field alone.
        # 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, description: 'Required when scope=host (the host id); must be absent when scope=system.'}
        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}

    CapabilitiesResponse:
      type: object
      required: [tier, status, capabilities]
      properties:
        tier: {type: string, enum: [free, enterprise]}
        status: {type: string, enum: [active, grace, expired, no_license, invalid]}
        capabilities:
          type: array
          items: {$ref: '#/components/schemas/Capability'}

    Capability:
      type: object
      required: [id, tier, available, description]
      properties:
        id:          {type: string, description: 'Registry id, e.g. remediation_execution'}
        tier:        {type: string, enum: [free, enterprise]}
        available:   {type: boolean, description: 'Whether THIS deployment may use it now'}
        description: {type: string}

    LicenseStateResponse:
      type: object
      required: [tier, status, features]
      properties:
        tier: {type: string, enum: [free, 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}
        # True when the host clock ran behind the stored watermark at load
        # time. A rollback warns, it does not deny, so an operator needs to
        # be able to read the warning. Requires system:read, like the three
        # properties above it.
        clock_rollback_detected: {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)
    # ScoreEnvelope says how a score was produced and what it measured
    # against. Every score-bearing response carries it, INCLUDING responses
    # whose score is null: a number with no record of its formula, lens and
    # corpus cannot be compared with a later one, and neither can its absence.
    # Spec system-compliance-scoring C-15.
    ScoreEnvelope:
      type: object
      required:
        - lens
        - formula_version
        - aggregation_method
        - engine_version
        - engines
        - engine_identity_status
        - hosts_without_engine_identity
        - corpus_identity_status
        - corpora
        - hosts_without_corpus_identity
        - corpus_version
        - corpus_digest
      properties:
        lens:
          type: string
          description: >-
            The single framework family every host was scored against, OS-resolved
            per host. "all_rules" when no lens narrows the set. An aggregate never
            blends per-host lenses.
        formula_version:
          type: integer
          nullable: true
          description: >-
            2 for the current formula (passing over passing plus failing). Null on
            an aggregate whose contributors disagree, or that predates the formula.
        aggregation_method:
          type: string
          enum: [none, equal_host_mean]
          description: >-
            none for a single host; equal_host_mean for an aggregate, where each
            host counts once whatever its rule count.
        engine_version:
          type: string
          nullable: true
          description: >-
            Convenience field, non-null ONLY when engine_identity_status is
            identified: one engine version, and every scored host accounted for
            by it. Null under partially_identified even though exactly one
            version appears in engines, because that version does not speak for
            the hosts that recorded none. The durable record is engines. It is
            COPIED from the scan runs, never taken from the process answering the
            request: in a rolling or split deployment the API, the rollup and the
            workers run different builds, so a process describing itself names an
            engine that never touched the host.
        engine_identity_status:
          type: string
          enum: [unavailable, identified, mixed, partially_identified]
          description: >-
            Whether the engine behind the score can be named. partially_identified
            means some scored hosts named an engine and some did not, which is
            what a fleet part way through an upgrade looks like and what a bare
            version list reported as agreement.
        engines:
          type: array
          description: >-
            One entry per engine version that produced contributing outcomes,
            with how many scored hosts it covers, sorted by version. Empty when
            none was recorded. The counts plus hosts_without_engine_identity
            always equal hosts_scored.
          items:
            type: object
            required: [engine_version, contributors_scored]
            properties:
              engine_version: {type: string}
              contributors_scored: {type: integer}
        hosts_without_engine_identity:
          type: integer
          description: Scored hosts whose scan run recorded no engine version.
        corpus_identity_status:
          type: string
          enum: [unavailable, identified, mixed, partially_identified, not_applicable]
          description: >-
            Whether the rule corpus behind the score can be named. unavailable
            until the scan engine can report it; never inferred from the corpus
            installed now.
        corpora:
          type: array
          description: One entry per distinct corpus that contributed. Empty when unavailable.
          items:
            type: object
            required: [corpus_version, corpus_digest, contributors_scored]
            properties:
              corpus_version:
                type: string
                nullable: true
                description: Null for a curated corpus, which has a digest and no version.
              corpus_digest:
                type: string
              contributors_scored:
                type: integer
        hosts_without_corpus_identity:
          type: integer
          description: Scored hosts whose corpus could not be named.
        corpus_version:
          type: string
          nullable: true
          description: >-
            Convenience field, non-null ONLY when corpus_identity_status is
            identified. One entry in corpora is not sufficient:
            partially_identified also has one, alongside contributors whose
            corpus could not be named, and reporting that one as THE corpus
            would name an identity for hosts that have none. The durable record
            is corpora.
        corpus_digest:
          type: string
          nullable: true
          description: >-
            Convenience field, non-null ONLY when corpus_identity_status is
            identified. See corpus_version.

    # AggregateScore is the whole answer for any fleet or group average: the
    # number, the outcomes behind it, whether coverage can be stated, the
    # population it was taken over, and the envelope that says how it was
    # produced. Every score-bearing aggregate uses this schema rather than
    # assembling its own subset, because a surface that assembles its own is a
    # surface that can omit the half that makes the number interpretable.
    # Spec system-compliance-scoring C-07, C-15.
    AggregateScore:
      type: object
      required:
        - score_pct
        - passing
        - failing
        - skipped
        - error
        - coverage_status
        - coverage_pct
        - hosts_scored
        - hosts_without_score
        - hosts_total
        - envelope
      properties:
        score_pct:
          type: number
          format: double
          nullable: true
          description: >-
            Equal-host mean of the per-host scores, to one decimal, so each host
            counts once whatever its rule count. NULL when no host produced a
            verdict, which is a different fact from every host failing every
            rule (that scores 0). It replaces a pooled ratio that weighted hosts
            by rule count and could not express absence.
        hosts_scored:
          type: integer
          description: Hosts that produced a score. The population the mean is over.
        hosts_without_score:
          type: integer
          description: >-
            Active hosts that produced no score: never scanned, scanned with no
            verdict, or carrying no rule that matches the lens.
        hosts_total:
          type: integer
          description: Active hosts. Always hosts_scored + hosts_without_score.
        passing:
          type: integer
          format: int64
          description: Rule outcomes that passed, summed across the population.
        failing:
          type: integer
          format: int64
          description: Rule outcomes that failed, summed across the population.
        skipped:
          type: integer
          format: int64
          description: >-
            Outcomes that produced no verdict, summed across the population.
            They enter neither side of score_pct.
        error:
          type: integer
          format: int64
          description: Outcomes that errored, summed across the population.
        coverage_status:
          type: string
          enum: [available, unavailable_unclassified_skips, unavailable_no_outcomes]
          description: >-
            Whether the share of in-scope rules that produced a verdict can be
            stated, and when it cannot, why. unavailable_unclassified_skips
            means at least one skip carries no machine-readable reason, so an
            inapplicable rule cannot be told from an unevaluated one; the number
            is withheld rather than guessed.
        coverage_pct:
          type: number
          format: double
          nullable: true
          description: >-
            Share of in-scope rules that produced a verdict, to one decimal.
            Non-null if and only if coverage_status is available.
        envelope:
          $ref: '#/components/schemas/ScoreEnvelope'

    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)

    ComplianceConfig:
      type: object
      required: [default_framework]
      description: >-
        Org-wide compliance-display config. default_framework is the default
        lens the score surfaces (dashboard/hosts avg compliance, host detail)
        project to: a framework family id (e.g. "stig", "cis") or empty for
        All rules (the full Kensa corpus). Resolved per-host to the OS key at
        query time. enabled_frameworks is the allowlist of families offered as
        lenses; empty means all corpus families are available. A non-empty
        default_framework must be in a non-empty enabled_frameworks.
      properties:
        default_framework: {type: string, description: Framework family id, or empty for All rules}
        enabled_frameworks:
          type: array
          items: {type: string}
          description: >-
            Allowlist of framework family ids offered as lenses. Empty (or
            omitted) means every family found in the corpus is available.

    ComplianceFramework:
      type: object
      required: [id, label, keys]
      properties:
        id:    {type: string, description: Family id (e.g. "stig")}
        label: {type: string, description: Display label (e.g. "STIG")}
        keys:
          type: array
          items: {type: string}
          description: Concrete corpus keys in this family (e.g. stig_rhel9, stig_rhel10)

    ComplianceFrameworksResponse:
      type: object
      required: [frameworks]
      properties:
        frameworks:
          type: array
          items: {$ref: '#/components/schemas/ComplianceFramework'}

    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, staged, reverted, not_applied, partially_applied]
        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:
      description: |
        One rule's Kensa transaction. Note that a "step" here is a RULE, not a
        phase: the Capture/Apply/Validate/Commit phases are in `phases`, one
        level below.
      type: object
      required: [id, rule_id, dry_run]
      properties:
        id:        {type: string, format: uuid}
        rule_id:   {type: string}
        mechanism: {type: string}
        phase_result:
          description: |
            Terminal outcome of the rule's transaction. Widened past
            committed/rolled_back/skipped by the v0.7.0 outcome vocabulary.
          type: string
          nullable: true
          enum: [committed, rolled_back, skipped, staged, partially_applied, not_applied]
        dry_run:    {type: boolean}
        applied_at: {type: string, format: date-time, nullable: true}
        phases:
          description: |
            The per-phase journal Kensa returned, in execution order. `detail`
            is the engine's own account of what each phase did, and is the
            answer to why a remediation failed.
          type: array
          items: {$ref: '#/components/schemas/RemediationPhase'}
        pre_state:
          description: |
            The state captured before any change, one entry per phase, in phase
            order.
          type: array
          items: {$ref: '#/components/schemas/RemediationPreState'}

    RemediationPlan:
      description: |
        What remediating one rule on one host would do. Produced by Kensa
        without mutating the host.
      type: object
      required: [rule_id, steps, checks, undo, transactional, control_channel_sensitive, reversible_steps]
      properties:
        plan_id: {type: string, format: uuid}
        rule_id: {type: string}
        steps:
          description: The apply steps that would run, in order.
          type: array
          items: {$ref: '#/components/schemas/RemediationPlanStep'}
        checks:
          description: The validators that would run after apply.
          type: array
          items:
            type: object
            required: [name]
            properties:
              name:    {type: string}
              summary: {type: string}
        undo:
          description: |
            How each applied step would be reversed. Rollback runs this in
            reverse order.
          type: array
          items: {$ref: '#/components/schemas/RemediationPlanStep'}
        reversible_steps:
          description: |
            How many steps Kensa actually captured pre-state for, counted from
            the capture rather than from the rule's own claim about itself.
          type: integer
        transactional:
          description: False when the steps are not all-or-nothing.
          type: boolean
        control_channel_sensitive:
          description: |
            True when a step touches SSH, networking, PAM or firewall state.
            Kensa arms a deadman timer before applying such a transaction, so
            a fix that could lock you out reverts itself if you lose contact.
          type: boolean
        warnings:
          description: Kensa's own operator-facing notices about this plan.
          type: array
          items: {type: string}
        before:
          description: |
            What Kensa found on the host while planning, one entry per step.
            Computed live and never stored, because a plan describes the host
            as it is now.
          type: array
          items:
            type: object
            required: [index, mechanism]
            properties:
              index:     {type: integer}
              mechanism: {type: string}
              summary:   {type: string}
        estimated_seconds: {type: number}
        captured_at:       {type: string, format: date-time}

    RemediationPlanStep:
      type: object
      required: [index, mechanism]
      properties:
        index:     {type: integer}
        mechanism: {type: string}
        summary:
          description: Kensa's human-readable description of the action.
          type: string
        capturable:
          description: False when this step cannot be reversed.
          type: boolean

    RemediationPreState:
      description: |
        One phase's captured pre-change state.

        `data` is mechanism-specific and is passed through from Kensa without
        interpretation. OpenWatch has no schema for it and deliberately does
        not decode it: each capturable handler defines its own layout, so
        reading it here would couple this contract to Kensa handler internals.
        Clients should treat it as opaque evidence unless they know the
        mechanism.
      type: object
      required: [index, mechanism, capturable]
      properties:
        index:     {type: integer}
        mechanism: {type: string}
        capturable:
          description: False for phases whose mechanism cannot capture pre-state; `data` is then empty.
          type: boolean
        summary:
          description: |
            Kensa's one-line rendering of what was captured, from the handler
            that captured it.

            Display text, not evidence. It carries no stability guarantee and
            may change between Kensa releases, which is why the transaction
            records the Kensa version that produced it. `data` remains the
            authoritative capture. Elided by construction so no file body
            appears, and a credential named inside a config line is redacted,
            but it is not a secret scanner: treat it as operator-visible text.
          type: string
        data:
          type: object
          additionalProperties: true

    RemediationPhase:
      description: One Capture/Apply/Validate/Commit phase of a rule's transaction.
      type: object
      required: [index, mechanism, success, capturable, staged, stranded]
      properties:
        index:     {type: integer}
        mechanism: {type: string}
        detail:
          description: Human-readable account of what this phase did, or why it did not.
          type: string
        success:   {type: boolean}
        capturable:
          description: |
            False when this phase's mechanism cannot record pre-state, which is
            what makes a rule non-rollbackable.
          type: boolean
        staged:
          description: |
            True when the change was written to the persist layer but the
            running host has not converged, so a re-scan still reports the rule
            failing until reboot.
          type: boolean
        stranded:
          description: |
            True for a non-capturable phase that succeeded before a later
            failure. Rollback does NOT reverse it.
          type: boolean

    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}
        target_framework:
          type: string
          description: >-
            Compliance target framework family a member host is held to (empty
            for none). Only a site group may carry one.
        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, score, members]
      properties:
        hosts:          {type: integer}
        online:         {type: integer}
        down:           {type: integer}
        critical_hosts: {type: integer}
        score:
          $ref: '#/components/schemas/AggregateScore'
          description: >-
            The group's compliance average with its population and envelope. It
            replaces a bare nullable integer, which rounded the canonical one
            decimal a second time and could not say which lens produced it.
        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, score]
      properties:
        groups:           {type: integer}
        sites:            {type: integer}
        os_categories:    {type: integer}
        hosts_maintenance: {type: integer}
        score:
          $ref: '#/components/schemas/AggregateScore'
          description: >-
            The Groups-page fleet KPI. It IS the GET /fleet/score answer, sent
            through the same mapper, so the two numbers cannot disagree.
        ungrouped:        {type: integer}

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

    ReportScope:
      type: object
      description: |
        The structured slice of the fleet a report summarizes: an optional
        group and/or framework lens. An empty object is the all-hosts,
        all-frameworks scope. Echoed so a caller can see and reproduce
        exactly what a report covers.
      properties:
        group_id:
          type: string
          format: uuid
          description: When set, the report is scoped to this group's member hosts.
        group_name:
          type: string
          description: The group's display name, frozen at generation time.
        framework:
          type: string
          description: When set, the framework lens (framework_refs key) the report is scoped to.

    GenerateReportRequest:
      type: object
      description: |
        Optional kind + scope for the report. An empty body (or empty
        object) generates the all-hosts, all-frameworks executive summary.
      properties:
        kind:
          type: string
          enum: [executive, attestation, exception, remediation]
          description: |
            The report kind; defaults to executive. attestation produces
            the Framework Attestation (CSV/OSCAL bulk faces over the latest
            completed scan per in-scope host); exception produces the
            Exception Register; remediation produces the Remediation
            Activity log over a look-back period.
        group_id:
          type: string
          format: uuid
          description: Scope the report to this group's member hosts.
        framework:
          type: string
          description: Scope the report to this framework lens (framework_refs key).
        period_days:
          type: integer
          minimum: 1
          maximum: 365
          description: |
            Look-back window in days for time-windowed kinds (remediation):
            the report covers requests filed in the last period_days.
            Defaults to 30; ignored by point-in-time kinds.

    Report:
      type: object
      required: [id, title, kind, scope_label, scope, data_as_of, generated_by, format, content, content_sha256, created_at]
      properties:
        id: {type: string, format: uuid}
        title: {type: string}
        kind:
          type: string
          enum: [executive, attestation, exception, remediation]
        scope_label: {type: string}
        scope: {$ref: '#/components/schemas/ReportScope'}
        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:
            score_pct, host_count, passing_rules, failing_rules,
            critical_issues, top_failing_rules, coverage (hosts_total,
            hosts_fresh, hosts_stale, hosts_unreachable), and provenance.

            score_pct is the equal-host mean of the in-scope hosts' scores,
            to one decimal, null when no host produced a verdict. Null is not
            zero: zero means every evaluated rule failed.

            provenance carries artifact_class and the frozen envelope. Its
            ABSENCE identifies an artifact signed before 2026-09-03, which
            instead carries compliance_pct: a pooled whole percent computed
            over every rule outcome in scope. The two are not comparable and
            a client must label a legacy artifact as such rather than
            plotting it beside a current one. Nothing backfills provenance,
            and a legacy artifact's bytes, content address and signature are
            never rewritten. A current artifact never carries
            compliance_pct.
        content_sha256:
          type: string
          description: |
            The snapshot's content address: hex SHA-256 of the canonical
            content (the json export face reproduces these exact bytes).
        signature:
          type: string
          description: |
            Base64 Ed25519 signature over the content address, or absent
            for an unsigned snapshot. Verify with the key from
            GET /api/v1/reports/signing-key.
        signing_key_id:
          type: string
          description: |
            Short correlation identifier of the key that produced the
            signature: the first 8 bytes of SHA-256 over the public key.
            It matches a report to a served key. It is NOT an authenticity
            anchor; 64 bits is within reach of a collision search. Anchor
            trust on the complete public key or its full SHA-256.
        created_at: {type: string, format: date-time}

    ReportSigningKey:
      type: object
      required: [key_id, algorithm, public_key, ephemeral]
      description: |
        The public key used to sign report snapshots, for offline
        verification of a report's signature over its content_sha256.
      properties:
        key_id:
          type: string
          description: |
            Short correlation identifier: the first 8 bytes of SHA-256 over
            public_key, hex encoded, prefixed `ed25519-`. Use it to match a
            report's signing_key_id to this key. It is NOT an authenticity
            anchor; compare the complete public_key, or its full SHA-256,
            against a copy obtained independently of this server.
        algorithm: {type: string, enum: [ed25519]}
        public_key:
          type: string
          description: |
            Base64-encoded Ed25519 public key, 32 bytes when decoded. This,
            or its lowercase hex SHA-256, is the value to compare against an
            independently trusted copy.
        ephemeral:
          type: boolean
          description: |
            True when the server runs a per-boot development key (no durable
            key configured); such signatures do not verify across restarts.

    ReportFramework:
      type: object
      required: [framework, rule_count]
      description: A framework lens present in the fleet, with its rule count.
      properties:
        framework:
          type: string
          description: The framework_refs key (e.g. cis_rhel9_v2.0.0).
        rule_count:
          type: integer
          description: Distinct rules mapped to this framework across the fleet.

    ReportFrameworksResponse:
      type: object
      required: [frameworks]
      properties:
        frameworks:
          type: array
          items: {$ref: '#/components/schemas/ReportFramework'}

    ReportSchedule:
      type: object
      required: [id, name, kind, frequency, hour, channel_id, enabled, next_run_at, created_at]
      properties:
        id: {type: string, format: uuid}
        name: {type: string}
        kind:
          type: string
          enum: [executive, attestation, exception, remediation]
        group_id: {type: string, format: uuid, description: Optional group scope.}
        framework: {type: string, description: Optional framework lens.}
        period_days: {type: integer, description: Period window for the remediation kind.}
        frequency:
          type: string
          enum: [daily, weekly, monthly]
        hour: {type: integer, description: Hour of day (UTC) to run (0-23).}
        weekday: {type: integer, description: 0=Sunday..6=Saturday, for weekly.}
        day_of_month: {type: integer, description: 1-28, for monthly.}
        channel_id: {type: string, format: uuid, description: The email channel used for delivery.}
        enabled: {type: boolean}
        next_run_at: {type: string, format: date-time}
        last_run_at: {type: string, format: date-time}
        last_status: {type: string}
        created_at: {type: string, format: date-time}

    ReportScheduleList:
      type: object
      required: [schedules]
      properties:
        schedules:
          type: array
          items: {$ref: '#/components/schemas/ReportSchedule'}

    CreateReportScheduleRequest:
      type: object
      required: [name, kind, frequency, channel_id]
      properties:
        name: {type: string}
        kind:
          type: string
          enum: [executive, attestation, exception, remediation]
        group_id: {type: string, format: uuid}
        framework: {type: string}
        period_days: {type: integer, minimum: 1, maximum: 365}
        frequency:
          type: string
          enum: [daily, weekly, monthly]
        hour: {type: integer, minimum: 0, maximum: 23, description: Defaults to 6.}
        weekday: {type: integer, minimum: 0, maximum: 6, description: Required for weekly.}
        day_of_month: {type: integer, minimum: 1, maximum: 28, description: Required for monthly.}
        channel_id: {type: string, format: uuid, description: An email notification channel.}

    UpdateReportScheduleRequest:
      type: object
      required: [enabled]
      properties:
        enabled: {type: boolean}

    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}

    GroupTargetRequest:
      type: object
      required: [target_framework]
      properties:
        target_framework:
          type: string
          description: Compliance target family id, or empty to clear the target.

    HostTargetRequest:
      type: object
      required: [target_framework]
      properties:
        target_framework:
          type: string
          description: Compliance target family id, or empty to clear the host's own target.

    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, formula_status, formula_version, passing, failing, total, envelope]
            properties:
              date:
                type: string
                format: date
              score_pct:
                type: number
                nullable: true
                description: >-
                  Passing over passing plus failing, to one decimal. NULL when
                  that day's rules produced no verdict. The day still appears,
                  with its counts, so the absence is explained rather than shown
                  as a gap.
              formula_status:
                type: string
                enum: [identified, legacy_unknown, mixed]
                description: >-
                  identified when the day's snapshot used the current formula;
                  legacy_unknown when it predates it, in which case the score is
                  preserved as stored and is NOT comparable with an identified
                  one. mixed cannot occur on a host point: a snapshot is one host
                  on one date under one lens and holds a single formula.
              formula_version:
                type: integer
                nullable: true
                description: 2 when formula_status is identified, otherwise null.
              envelope:
                $ref: '#/components/schemas/ScoreEnvelope'
                description: >-
                  Provenance recorded ON THE SNAPSHOT, not read from the process
                  serving the request. A legacy point carries a null formula
                  version and an empty engines list, because nothing recorded
                  them; that absence is the honest historical shape rather than
                  a substituted current value.
              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
              - score_pct
              - formula_status
              - formula_version
              - envelope
              - hosts
              - hosts_scored
              - hosts_without_score
              - failing
              - critical_hosts
            properties:
              date:
                type: string
                format: date
              score_pct:
                type: number
                nullable: true
                description: >-
                  Equal-host mean over the hosts that produced a score that day,
                  to one decimal. Not a pooled ratio, so a host with many rules
                  does not outweigh one with few. NULL when no host produced a
                  score, and NULL when formula_status is mixed.
              formula_status:
                type: string
                enum: [identified, legacy_unknown, mixed]
                description: >-
                  mixed means the day's snapshots were produced by MORE THAN ONE
                  formula. Those measure different things, so the day reports no
                  score rather than their average. legacy_unknown means every
                  snapshot predates the current formula; its score is preserved
                  and is not comparable with an identified one.
              formula_version:
                type: integer
                nullable: true
                description: 2 when formula_status is identified, otherwise null.
              envelope:
                $ref: '#/components/schemas/ScoreEnvelope'
                description: >-
                  Provenance recorded on the day's snapshots. engines can carry
                  several versions, which is normal while a fleet is part way
                  through an upgrade.
              hosts_scored:
                type: integer
                description: Hosts that produced a score that day.
              hosts_without_score:
                type: integer
                description: Hosts with a snapshot that day but no score.
              hosts:
                type: integer
                description: >-
                  Every host with a snapshot that day, including hosts that
                  produced no score and are therefore not in score_pct.
              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}
        # Per-category collection freshness (system-os-intelligence v1.3.0 C-09).
        # nullable: rows written before migration 0052 have no freshness map.
        category_freshness:
          nullable: true
          allOf: [{$ref: '#/components/schemas/CategoryFreshness'}]

    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}

    FreshnessEntry:
      type: object
      required: [status, observed_at, attempt_at]
      description: |
        Per-category collection freshness. status=ok when the category was
        observed on the most recent run; status=stale when the run did not
        observe it and the last-known-good value was carried forward
        (observed_at then points at the last successful observation). On a
        stale entry, reason records WHY it was not re-observed: denied (a
        fixable sudo/permission refusal), failed (transport or command
        failure), or timeout. Spec system-host-discovery / system-os-intelligence.
      properties:
        status:      {type: string, enum: [ok, stale]}
        observed_at: {type: string, format: date-time}
        attempt_at:  {type: string, format: date-time}
        reason:      {type: string, enum: [denied, failed, timeout], description: 'Present only on stale entries: why the category was not re-observed this run'}
    CategoryFreshness:
      type: object
      additionalProperties: {$ref: '#/components/schemas/FreshnessEntry'}
      description: |
        Map of fact category -> freshness. Absent categories were never
        observed. Discovery keys: os_release, uname, memory, disk, hostname,
        fqdn, selinux, apparmor, firewall. Intelligence keys: users, groups,
        ports, interfaces, routes, firewall, packages, services, kernel,
        uptime, mounts, config.

    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}
        # Per-category collection freshness (system-host-discovery v1.6.0 C-13).
        # nullable: rows written before migration 0052 have no freshness map.
        category_freshness:
          nullable: true
          allOf: [{$ref: '#/components/schemas/CategoryFreshness'}]

    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}

    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}