OpenAPI drift: 12 gaps between live spec and library

[github-actions]

The live ClickHouse Cloud OpenAPI spec has drifted from the Rust API library.
The comparison was produced by the shared syn-based analyzer.

• Live spec: https://api.clickhouse.cloud/v1
• Client: crates/clickhouse-cloud-api/src/client.rs
• Models: crates/clickhouse-cloud-api/src/models.rs
• Analyzer: crates/clickhouse-openapi-analyzer

Summary

Change	Count
Missing client methods	1
Extra client methods	0
Missing model types	2
Missing schema definitions	0
Missing struct fields	4
Extra struct fields	0
Missing enum values	1
Extra enum values	0
Enum VALUES const mismatches	0
Field optionality mismatches	0
Beta status changes	1
Deprecated-field changes	0
Stale snapshot changes	3
Stale exemptions	0
New unsupported enum constraints	0
Acknowledged unsupported enum constraints	13

Missing Client Methods

active_balances_get

GET /v1/organizations/{organizationId}/activeBalances

Get organization active prepaid balances

Operation spec JSON

{
  "summary": "Get organization active prepaid balances",
  "description": "**This endpoint is in beta.** API contract is stable, and no breaking changes are expected in the future. <br /><br /> Returns the active prepaid credit balances for the organization, each with its own balance ID and remaining credits, along with the total remaining credits across all active balances. A balance is active when it has started, has not expired, and has credits remaining. Balances are ordered by expiration date, soonest first, and the returned page is capped at `limit` (default and maximum 100). When `totalCount` exceeds the number of returned balances, page with `limit`/`offset` to retrieve them all. `totalRemainingPrepaidCredits` always covers every active balance, not just the returned page.",
  "operationId": "activeBalancesGet",
  "parameters": [
    {
      "in": "path",
      "name": "organizationId",
      "description": "ID of the requested organization.",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    },
    {
      "in": "query",
      "name": "limit",
      "description": "Maximum number of results to return.",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "default": 100
      }
    },
    {
      "in": "query",
      "name": "offset",
      "description": "Number of results to skip before returning.",
      "schema": {
        "type": "integer",
        "minimum": 0,
        "default": 0
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Successful response",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "number",
                "description": "HTTP status code.",
                "example": 200
              },
              "requestId": {
                "type": "string",
                "description": "Unique id assigned to every request. UUIDv4",
                "format": "uuid"
              },
              "result": {
                "$ref": "#/components/schemas/ActiveBalances"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "The request cannot be processed due to a client error. Please verify your request parameters and try again.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "number",
                "description": "HTTP status code.",
                "example": 400
              },
              "error": {
                "type": "string",
                "description": "Detailed error description."
              },
              "requestId": {
                "type": "string",
                "description": "Unique id assigned to every request. UUIDv4",
                "format": "uuid"
              }
            }
          }
        }
      }
    },
    "500": {
      "description": "An internal server error has occurred. If this issue persists, please contact ClickHouse Cloud support for assistance.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "status": {
                "type": "integer",
                "description": "HTTP status code.",
                "example": 500
              },
              "error": {
                "type": "string",
                "description": "Detailed error description."
              },
              "requestId": {
                "type": "string",
                "description": "Unique id assigned to every request. UUIDv4",
                "format": "uuid"
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    "Billing"
  ],
  "x-badges": [
    {
      "name": "Beta",
      "position": "after"
    }
  ]
}

Missing Struct Fields

• /components/schemas/ClickPipeSettings/properties/kafka_read_committed — ClickPipeSettings.kafka_read_committed is missing from models.rs
• /components/schemas/ClickPipeSettingsPutRequest/properties/kafka_read_committed — ClickPipeSettingsPutRequest.kafka_read_committed is missing from models.rs
• /components/schemas/ClickPipeSettings/properties/kafka_read_committed — ClickPipeSettingsResponse.kafka_read_committed is missing from models.rs
• /components/schemas/Udf/properties/memoryLimitMib — Udf.memoryLimitMib is missing from models.rs

Missing Enum Values

• /components/schemas/OrganizationQuota/properties/quotaCode — OrganizationQuotaQuotacode has no variant for wire value "api-keys-per-organization"

Newly Beta Operations

• /paths/~1v1~1organizations~1{organizationId}~1activeBalances/get — active_balances_get is Beta in the spec but absent from BETA_OPERATIONS

New Operations Missing From Snapshot

• /paths/~1v1~1organizations~1{organizationId}~1activeBalances/get — operation active_balances_get is present in the target spec but absent from the snapshot

New Schemas Missing From Snapshot

• /components/schemas/ActiveBalance — schema ActiveBalance is present in the target spec but absent from the snapshot
• /components/schemas/ActiveBalances — schema ActiveBalances is present in the target spec but absent from the snapshot

Missing Model Types

ActiveBalance (spec: ActiveBalance)

Schema JSON

{
  "properties": {
    "id": {
      "description": "Unique ID of the prepaid balance.",
      "type": "string",
      "format": "uuid"
    },
    "remainingPrepaidCredits": {
      "description": "Remaining credits available on this balance, in ClickHouse Credits (CHCs).",
      "type": "number"
    },
    "totalAmount": {
      "description": "Total credits granted on this balance, in ClickHouse Credits (CHCs).",
      "type": "number"
    },
    "amountSpent": {
      "description": "Credits spent from this balance, in ClickHouse Credits (CHCs).",
      "type": "number"
    },
    "startDate": {
      "description": "Date the balance became active. ISO-8601, based on the UTC timezone.",
      "type": "string",
      "format": "date-time"
    },
    "expirationDate": {
      "description": "Date the balance expires. ISO-8601, based on the UTC timezone.",
      "type": "string",
      "format": "date-time"
    }
  }
}

ActiveBalances (spec: ActiveBalances)

Schema JSON

{
  "properties": {
    "totalRemainingPrepaidCredits": {
      "description": "Total remaining credits across all active prepaid balances, in ClickHouse Credits (CHCs).",
      "type": "number"
    },
    "prepaidBalances": {
      "type": "array",
      "description": "List of active prepaid balances for the organization.",
      "items": {
        "$ref": "#/components/schemas/ActiveBalance"
      }
    }
  }
}

Acknowledged Unsupported Enum Constraints

These locations are inventoried but cannot yet be compared to a typed Rust value enum.
They do not count as drift; new or stale locations do.

• /components/schemas/ApiKey/properties/roles/items (models.rs::ApiKey::roles) — Rust type String is not an enum
• /components/schemas/ApiKeyPatchRequest/properties/roles/items (models.rs::ApiKeyPatchRequest::roles) — Rust type String is not an enum
• /components/schemas/ApiKeyPostRequest/properties/roles/items (models.rs::ApiKeyPostRequest::roles) — Rust type String is not an enum
• /components/schemas/ByocInfrastructurePostRequest/properties/availabilityZoneSuffixes/items (models.rs::ByocInfrastructurePostRequest::availability_zone_suffixes) — Rust type String is not an enum
• /components/schemas/InstanceServiceQueryApiEndpointsPostRequest/properties/roles/items (models.rs::InstanceServiceQueryApiEndpointsPostRequest::roles) — Rust type String is not an enum
• /components/schemas/ServiceQueryAPIEndpoint/properties/roles/items (models.rs::ServiceQueryAPIEndpoint::roles) — Rust type String is not an enum
• /components/schemas/UpgradeWindow/properties/duration (models.rs::UpgradeWindow::duration) — numeric enum constraints cannot be represented by Rust unit variants
• /components/schemas/UpgradeWindow/properties/startHourUtc (models.rs::UpgradeWindow::start_hour_utc) — numeric enum constraints cannot be represented by Rust unit variants
• /components/schemas/UpgradeWindowPutRequest/properties/startHourUtc (models.rs::UpgradeWindowPutRequest::start_hour_utc) — numeric enum constraints cannot be represented by Rust unit variants
• /paths/~1v1~1organizations~1{organizationId}~1postgres~1{postgresId}~1slowQueryPatterns/get/parameters/8/schema (client.rs::Client::slow_query_patterns_get_list::sort_by) — Rust type str is not an enum
• /paths/~1v1~1organizations~1{organizationId}~1postgres~1{postgresId}~1slowQueryPatterns/get/parameters/9/schema (client.rs::Client::slow_query_patterns_get_list::sort_order) — Rust type str is not an enum
• /paths/~1v1~1organizations~1{organizationId}~1udfs~1{functionName}~1attachments~1{serviceId}/put/responses/424/content/application~1json/schema/properties/code — enum location cannot be mapped to a concrete Rust item
• /paths/~1v1~1organizations~1{organizationId}~1udfs~1{functionName}~1attachments~1{serviceId}/put/responses/424/content/application~1json/schema/properties/serviceState — enum location cannot be mapped to a concrete Rust item

Implementation Guide

1. Replace crates/clickhouse-cloud-api/clickhouse_cloud_openapi.json with this same live document; do not hand-edit it.
2. Follow each finding's spec_pointer and rust_item to update client.rs, models.rs, or meta.rs.
3. Regenerate beta/deprecation metadata when applicable and add focused model/client tests.
4. Edit crates/clickhouse-openapi-analyzer/src/config.rs only for a deliberate, documented divergence. New unsupported acknowledgements require a tracking issue.
5. Run the analyzer and Cloud API tests, Clippy, Python renderer tests, and this dry run again; see AGENTS.md for the exact commands.