feat(client)!: live-verified spec drift batch + verification harness

Reusable harness (``scripts/spec_drift_verify.py`` + per-issue probe
scripts) for running tagged POSTs against a live Katana tenant and
cleaning up afterwards. Every test artifact gets an ``SDT-<date>``
prefix and is recorded in ``/tmp/spec-drift-ledger.jsonl``; a single
``cleanup`` subcommand walks the ledger in reverse and deletes
everything (idempotent — already-deleted rows are skipped).

Spec-drift findings encoded in ``docs/katana-openapi.yaml``:

**#737 — CustomFieldDefinition**
- ``id``: ``integer`` → ``string, format: uuid`` (per README example,
  inferred — couldn't live-verify because our API key lacks create
  permission on this endpoint, but README is authoritative and the
  shape is universal across Katana custom-field surfaces).
- ``field_type``: ``string maxLength: 50`` → new
  ``CustomFieldType`` enum (``shortText`` / ``number`` /
  ``singleSelect`` / ``date`` / ``boolean`` / ``url``). Verified
  via live-API 422 introspection.
- ``entity_type``: ``string maxLength: 50`` → new
  ``CustomFieldEntityType`` enum with **19 values** (vs README's
  documented 1). Verified via live-API 422 introspection — the
  enum spans SalesOrder, SalesOrderRow, ManufacturingOrder*,
  PurchaseOrder*, StockAdjustment*, Production*, Customer,
  ProductVariant, MaterialVariant, ServiceVariant.
- ``CustomFieldDefinition`` no longer extends ``UpdatableEntity``
  because the singleton's ``id`` is a UUID string, not the integer
  ``BaseEntity`` defines for the rest of the API surface.
  ``created_at`` / ``updated_at`` are inlined.

**#736 — variant_bin_locations + CreateServiceVariant.sku**
- ``POST /variant_bin_locations`` request body wrapped in array
  (``minItems: 1, maxItems: 500``). The endpoint description
  already said "accepts up to 500 variant storage bin objects"
  but the schema was a single object. Verified via live API:
  single-object body returns ``422 must be array``.
- ``CreateServiceVariantRequest.sku`` is no longer required. The
  field is nullable. Verified by creating a service variant via
  the live API with ``sku`` omitted — server accepted it and
  returned ``sku: null``.

**#738 — StockTransferRowRequest.quantity**
- Changed from ``number`` to ``string``. Verified via live-API
  422 introspection — sending a JSON number returns
  ``must be string``. Wire format is a fixed-precision decimal
  string (e.g. ``"1.0000000000"``). MCP boundary in
  ``stock_transfers._build_row_requests`` stringifies the pydantic
  ``float`` input at the call site.

**#739 — SalesOrderFulfillment**
- No spec change needed. Verified ``sales_order_fulfillment_rows``
  IS required on create — local spec is correct, README is stale.

Findings deferred to follow-ups:

- **#734** ``custom_fields`` shape — live API rejects array-shaped
  custom_fields with ``must be object`` at both SO and SO-row
  create paths; dict-shape is accepted. Local READ schemas use
  structured-array shape, which contradicts this. Read-side
  verification requires a populated example (tenant has zero
  ``custom_field_definitions`` and our key can't create them).
  Sweeping all the READ schemas is broader than this PR.
- **#736** ``CustomFieldDefinition`` ``options`` shape, ``id`` type
  via live API, ``UpdateCustomerRequest.default_billing_id``,
  ``Operator`` fields — all blocked by either authorization
  (custom_field_definitions endpoint) or absence of populated
  fixtures on this tenant.

BREAKING CHANGE: ``CustomFieldDefinition.id`` becomes a UUID string
(was integer); ``field_type`` / ``entity_type`` become enums;
``CreateServiceVariantRequest.sku`` is no longer required (callers
omitting it will continue to work, but ``required`` removal is a
schema-level breaking change); ``StockTransferRowRequest.quantity``
becomes a string. The MCP ``stock_transfers`` boundary already
stringifies the input float so MCP callers don't have to.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: dougborg

docs/katana-openapi.yaml

@@ -289,9 +289,13 @@ def _build_row_requests(
     """Convert pydantic row inputs to attrs request rows."""
     out: list[StockTransferRowRequest] = []
     for row in rows:
+        # ``StockTransferRowRequest.quantity`` is a wire-format string
+        # (fixed-precision decimal) per the spec; the MCP input is a
+        # pydantic ``float`` so stringify at the boundary. Katana
+        # normalizes the precision server-side (e.g. ``"1.0000000000"``).
         api_row = StockTransferRowRequest(
             variant_id=row.variant_id,
-            quantity=row.quantity,
+            quantity=str(row.quantity),
         )
         if row.batch_transactions:
             api_row.additional_properties = {

katana_mcp_server/src/katana_mcp/tools/foundation/stock_transfers.py

@@ -94,9 +94,10 @@ def sync_detailed(
 
     Args:
         body (CreateCustomFieldDefinitionRequest): Request payload for creating a new custom field
-            definition. Example: {'label': 'Quality Grade', 'field_type': 'select', 'entity_type':
-            'product', 'source': 'user', 'description': 'Customer-facing quality classification',
-            'options': {'values': ['A', 'B', 'C']}}.
+            definition. Example: {'label': 'Channel', 'field_type': 'singleSelect', 'entity_type':
+            'SalesOrder', 'source': 'your-integration', 'description': 'Customer-facing sales channel
+            classification', 'options': {'choices': [{'label': 'Online'}, {'label': 'Retail'},
+            {'label': 'Wholesale'}]}}.
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -129,9 +130,10 @@ def sync(
 
     Args:
         body (CreateCustomFieldDefinitionRequest): Request payload for creating a new custom field
-            definition. Example: {'label': 'Quality Grade', 'field_type': 'select', 'entity_type':
-            'product', 'source': 'user', 'description': 'Customer-facing quality classification',
-            'options': {'values': ['A', 'B', 'C']}}.
+            definition. Example: {'label': 'Channel', 'field_type': 'singleSelect', 'entity_type':
+            'SalesOrder', 'source': 'your-integration', 'description': 'Customer-facing sales channel
+            classification', 'options': {'choices': [{'label': 'Online'}, {'label': 'Retail'},
+            {'label': 'Wholesale'}]}}.
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -159,9 +161,10 @@ async def asyncio_detailed(
 
     Args:
         body (CreateCustomFieldDefinitionRequest): Request payload for creating a new custom field
-            definition. Example: {'label': 'Quality Grade', 'field_type': 'select', 'entity_type':
-            'product', 'source': 'user', 'description': 'Customer-facing quality classification',
-            'options': {'values': ['A', 'B', 'C']}}.
+            definition. Example: {'label': 'Channel', 'field_type': 'singleSelect', 'entity_type':
+            'SalesOrder', 'source': 'your-integration', 'description': 'Customer-facing sales channel
+            classification', 'options': {'choices': [{'label': 'Online'}, {'label': 'Retail'},
+            {'label': 'Wholesale'}]}}.
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -192,9 +195,10 @@ async def asyncio(
 
     Args:
         body (CreateCustomFieldDefinitionRequest): Request payload for creating a new custom field
-            definition. Example: {'label': 'Quality Grade', 'field_type': 'select', 'entity_type':
-            'product', 'source': 'user', 'description': 'Customer-facing quality classification',
-            'options': {'values': ['A', 'B', 'C']}}.
+            definition. Example: {'label': 'Channel', 'field_type': 'singleSelect', 'entity_type':
+            'SalesOrder', 'source': 'your-integration', 'description': 'Customer-facing sales channel
+            classification', 'options': {'choices': [{'label': 'Online'}, {'label': 'Retail'},
+            {'label': 'Wholesale'}]}}.
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.

katana_public_api_client/api/custom_fields/create_custom_field_definition.py

@@ -1,6 +1,7 @@
 from http import HTTPStatus
 from typing import Any, cast
 from urllib.parse import quote
+from uuid import UUID
 
 import httpx
 
@@ -11,7 +12,7 @@
 
 
 def _get_kwargs(
-    id: int,
+    id: UUID,
 ) -> dict[str, Any]:
 
     _kwargs: dict[str, Any] = {
@@ -69,7 +70,7 @@ def _build_response(
 
 
 def sync_detailed(
-    id: int,
+    id: UUID,
     *,
     client: AuthenticatedClient | Client,
 ) -> Response[Any | ErrorResponse]:
@@ -78,7 +79,7 @@ def sync_detailed(
      Deletes an existing custom field definition.
 
     Args:
-        id (int):
+        id (UUID):
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -101,7 +102,7 @@ def sync_detailed(
 
 
 def sync(
-    id: int,
+    id: UUID,
     *,
     client: AuthenticatedClient | Client,
 ) -> Any | ErrorResponse | None:
@@ -110,7 +111,7 @@ def sync(
      Deletes an existing custom field definition.
 
     Args:
-        id (int):
+        id (UUID):
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -128,7 +129,7 @@ def sync(
 
 
 async def asyncio_detailed(
-    id: int,
+    id: UUID,
     *,
     client: AuthenticatedClient | Client,
 ) -> Response[Any | ErrorResponse]:
@@ -137,7 +138,7 @@ async def asyncio_detailed(
      Deletes an existing custom field definition.
 
     Args:
-        id (int):
+        id (UUID):
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -158,7 +159,7 @@ async def asyncio_detailed(
 
 
 async def asyncio(
-    id: int,
+    id: UUID,
     *,
     client: AuthenticatedClient | Client,
 ) -> Any | ErrorResponse | None:
@@ -167,7 +168,7 @@ async def asyncio(
      Deletes an existing custom field definition.
 
     Args:
-        id (int):
+        id (UUID):
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.

katana_public_api_client/api/custom_fields/delete_custom_field_definition.py

@@ -1,6 +1,7 @@
 from http import HTTPStatus
 from typing import Any
 from urllib.parse import quote
+from uuid import UUID
 
 import httpx
 
@@ -12,7 +13,7 @@
 
 
 def _get_kwargs(
-    id: int,
+    id: UUID,
 ) -> dict[str, Any]:
 
     _kwargs: dict[str, Any] = {
@@ -71,7 +72,7 @@ def _build_response(
 
 
 def sync_detailed(
-    id: int,
+    id: UUID,
     *,
     client: AuthenticatedClient | Client,
 ) -> Response[CustomFieldDefinition | ErrorResponse]:
@@ -80,7 +81,7 @@ def sync_detailed(
      Retrieves a single custom field definition by ID.
 
     Args:
-        id (int):
+        id (UUID):
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -103,7 +104,7 @@ def sync_detailed(
 
 
 def sync(
-    id: int,
+    id: UUID,
     *,
     client: AuthenticatedClient | Client,
 ) -> CustomFieldDefinition | ErrorResponse | None:
@@ -112,7 +113,7 @@ def sync(
      Retrieves a single custom field definition by ID.
 
     Args:
-        id (int):
+        id (UUID):
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -130,7 +131,7 @@ def sync(
 
 
 async def asyncio_detailed(
-    id: int,
+    id: UUID,
     *,
     client: AuthenticatedClient | Client,
 ) -> Response[CustomFieldDefinition | ErrorResponse]:
@@ -139,7 +140,7 @@ async def asyncio_detailed(
      Retrieves a single custom field definition by ID.
 
     Args:
-        id (int):
+        id (UUID):
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.
@@ -160,7 +161,7 @@ async def asyncio_detailed(
 
 
 async def asyncio(
-    id: int,
+    id: UUID,
     *,
     client: AuthenticatedClient | Client,
 ) -> CustomFieldDefinition | ErrorResponse | None:
@@ -169,7 +170,7 @@ async def asyncio(
      Retrieves a single custom field definition by ID.
 
     Args:
-        id (int):
+        id (UUID):
 
     Raises:
         errors.UnexpectedStatus: If the server returns an undocumented status code and Client.raise_on_unexpected_status is True.

katana_public_api_client/api/custom_fields/get_custom_field_definition.py

@@ -1,6 +1,7 @@
 from http import HTTPStatus
 from typing import Any
 from urllib.parse import quote
+from uuid import UUID
 
 import httpx
 
@@ -16,7 +17,7 @@
 
 
 def _get_kwargs(
-    id: int,
+    id: UUID,
     *,
     body: UpdateCustomFieldDefinitionRequest,
 ) -> dict[str, Any]:
@@ -93,7 +94,7 @@ def _build_response(
 
 
 def sync_detailed(
-    id: int,
+    id: UUID,
     *,
     client: AuthenticatedClient | Client,
     body: UpdateCustomFieldDefinitionRequest,
@@ -103,7 +104,7 @@ def sync_detailed(
      Updates an existing custom field definition.
 
     Args:
-        id (int):
+        id (UUID):
         body (UpdateCustomFieldDefinitionRequest): Request payload for updating an existing custom
             field definition. Example: {'label': 'Quality Grade (revised)', 'description': 'Updated
             customer-facing quality classification'}.
@@ -130,7 +131,7 @@ def sync_detailed(
 
 
 def sync(
-    id: int,
+    id: UUID,
     *,
     client: AuthenticatedClient | Client,
     body: UpdateCustomFieldDefinitionRequest,
@@ -140,7 +141,7 @@ def sync(
      Updates an existing custom field definition.
 
     Args:
-        id (int):
+        id (UUID):
         body (UpdateCustomFieldDefinitionRequest): Request payload for updating an existing custom
             field definition. Example: {'label': 'Quality Grade (revised)', 'description': 'Updated
             customer-facing quality classification'}.
@@ -162,7 +163,7 @@ def sync(
 
 
 async def asyncio_detailed(
-    id: int,
+    id: UUID,
     *,
     client: AuthenticatedClient | Client,
     body: UpdateCustomFieldDefinitionRequest,
@@ -172,7 +173,7 @@ async def asyncio_detailed(
      Updates an existing custom field definition.
 
     Args:
-        id (int):
+        id (UUID):
         body (UpdateCustomFieldDefinitionRequest): Request payload for updating an existing custom
             field definition. Example: {'label': 'Quality Grade (revised)', 'description': 'Updated
             customer-facing quality classification'}.
@@ -197,7 +198,7 @@ async def asyncio_detailed(
 
 
 async def asyncio(
-    id: int,
+    id: UUID,
     *,
     client: AuthenticatedClient | Client,
     body: UpdateCustomFieldDefinitionRequest,
@@ -207,7 +208,7 @@ async def asyncio(
      Updates an existing custom field definition.
 
     Args:
-        id (int):
+        id (UUID):
         body (UpdateCustomFieldDefinitionRequest): Request payload for updating an existing custom
             field definition. Example: {'label': 'Quality Grade (revised)', 'description': 'Updated
             customer-facing quality classification'}.