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

@@ -7624,15 +7624,21 @@ components:
               - field_name: Skill Level
                 field_value: Expert
     CreateServiceVariantRequest:
-      description: Request payload for creating a service variant with pricing and custom fields
+      description: |
+        Request payload for creating a service variant with pricing and
+        custom fields. ``sku`` is optional — verified against live API:
+        omitting it returns a created variant with ``sku: null``.
       type: object
       additionalProperties: false
-      required:
-        - sku
       properties:
         sku:
-          type: string
-          description: A unique service code
+          type:
+            - string
+            - "null"
+          description: |
+            Optional unique service code. May be ``null`` when the
+            variant doesn't need a SKU (e.g., a generic labour
+            service).
         sales_price:
           type:
             - number
@@ -10650,75 +10656,139 @@ components:
                   - COD
             created_at: "2024-01-10T11:00:00Z"
             updated_at: "2024-01-14T09:15:00Z"
+    CustomFieldType:
+      type: string
+      enum:
+        - shortText
+        - number
+        - singleSelect
+        - date
+        - boolean
+        - url
+      description: |
+        Field input type for a ``CustomFieldDefinition``. Immutable after
+        creation — the value determines how Katana renders and validates
+        the field's stored values. Confirmed via live-API enum
+        introspection on ``POST /custom_field_definitions``.
+
+    CustomFieldEntityType:
+      type: string
+      enum:
+        - SalesOrder
+        - SalesOrderRow
+        - SalesRecipeRow
+        - SalesOrderFulfillmentRow
+        - ManufacturingOrder
+        - ManufacturingOrderRecipeRow
+        - PurchaseOrder
+        - PurchaseOrderRow
+        - PurchaseOrderRecipeRow
+        - OutsourcedPurchaseOrderRow
+        - StockAdjustment
+        - StockAdjustmentRow
+        - StockTransferRow
+        - Production
+        - ProductionIngredient
+        - Customer
+        - ProductVariant
+        - MaterialVariant
+        - ServiceVariant
+      description: |
+        Resource type a ``CustomFieldDefinition`` applies to. Immutable
+        after creation. Note: many resources accept custom fields even
+        though their request DTOs don't explicitly document the
+        ``custom_fields`` property — the field is universally available
+        on the entities listed here. Verified against live-API enum
+        introspection.
+
     CustomFieldDefinition:
       description: |
         A configured custom field definition that callers can attach to a
         resource (sales order, service, product, etc.) via the resource's
         ``custom_fields`` property. Definitions are scoped to a specific
         ``entity_type`` and shape what values consumers can store.
-      allOf:
-        - type: object
-          properties:
-            id:
-              type: integer
-              description: Unique identifier for the custom field definition
-            label:
-              type: string
-              maxLength: 255
-              description: Display label shown in the Katana UI
-            field_type:
-              type: string
-              maxLength: 50
-              description: |
-                Field input type (e.g. ``text``, ``number``, ``date``,
-                ``select``). Drives how Katana renders and validates the
-                field's values.
-            entity_type:
-              type: string
-              maxLength: 50
-              description: |
-                Resource type the definition applies to (matches the
-                resource's ``custom_fields`` API field — e.g.
-                ``sales_order``, ``service``, ``product``).
-            source:
-              type: string
-              maxLength: 255
-              description: Origin / namespace of the definition (e.g. ``katana``, ``user``).
-            description:
-              type:
-                - string
-                - "null"
-              description: Optional long-form description of the field's purpose
-            options:
-              type:
-                - object
-                - "null"
-              additionalProperties: true
-              description: |
-                Free-form configuration object — shape varies per
-                ``field_type`` (e.g., select fields carry the option list
-                here).
-          required:
-            - id
-            - label
-            - field_type
-            - entity_type
-            - source
-        - $ref: "#/components/schemas/UpdatableEntity"
+
+        Does **not** extend ``UpdatableEntity`` because the singleton's
+        ``id`` is a UUID string (not the integer that ``BaseEntity``
+        defines for the rest of the API surface) — ``created_at`` /
+        ``updated_at`` are inlined here instead.
+      type: object
+      additionalProperties: false
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: |
+            Server-assigned identifier for the custom field
+            definition. Returned as a UUID string (e.g.
+            ``"0c8f1d6e-3c2a-4f5b-9d77-12ab34cd56ef"``).
+        label:
+          type: string
+          maxLength: 255
+          description: Display label shown in the Katana UI
+        field_type:
+          allOf:
+            - $ref: "#/components/schemas/CustomFieldType"
+          description: |
+            Field input type. Immutable after creation — see
+            :class:`CustomFieldType` for the allowed values and the
+            value Katana stores for each.
+        entity_type:
+          allOf:
+            - $ref: "#/components/schemas/CustomFieldEntityType"
+          description: |
+            Resource type the definition applies to. Immutable after
+            creation — see :class:`CustomFieldEntityType` for the
+            full list.
+        source:
+          type: string
+          maxLength: 255
+          description: Origin / namespace of the definition (e.g. ``katana``, ``user``).
+        description:
+          type:
+            - string
+            - "null"
+          description: Optional long-form description of the field's purpose
+        options:
+          type:
+            - object
+            - "null"
+          additionalProperties: true
+          description: |
+            Free-form configuration object — shape varies per
+            ``field_type`` (e.g., select fields carry the option list
+            here).
+        created_at:
+          type: string
+          format: date-time
+          description: Timestamp when the definition was created
+        updated_at:
+          type: string
+          format: date-time
+          description: Timestamp when the definition was last updated
+      required:
+        - id
+        - label
+        - field_type
+        - entity_type
+        - source
       example:
-        id: 42
-        label: Quality Grade
-        field_type: select
-        entity_type: product
-        source: user
+        id: "0c8f1d6e-3c2a-4f5b-9d77-12ab34cd56ef"
+        label: Channel
+        field_type: singleSelect
+        entity_type: SalesOrder
+        source: your-integration
         description: Customer-facing quality classification
         options:
-          values:
-            - A
-            - B
-            - C
-        created_at: "2024-01-08T10:00:00Z"
-        updated_at: "2024-01-12T15:30:00Z"
+          choices:
+            - id: 1
+              label: Online
+            - id: 2
+              label: Retail
+            - id: 3
+              label: Wholesale
+        created_at: "2026-05-14T10:00:00Z"
+        updated_at: "2026-05-14T10:00:00Z"
     CreateCustomFieldDefinitionRequest:
       description: Request payload for creating a new custom field definition.
       type: object
@@ -10734,17 +10804,25 @@ components:
           maxLength: 255
           description: Display label shown in the Katana UI
         field_type:
-          type: string
-          maxLength: 50
-          description: Field input type (text, number, date, select, etc.)
+          allOf:
+            - $ref: "#/components/schemas/CustomFieldType"
+          description: |
+            Field input type. Immutable after creation. The live API
+            enforces this enum at validation time (verified via 422
+            introspection).
         entity_type:
-          type: string
-          maxLength: 50
-          description: Resource type the definition applies to
+          allOf:
+            - $ref: "#/components/schemas/CustomFieldEntityType"
+          description: |
+            Resource type the definition applies to. Immutable after
+            creation. The live API enforces this enum at validation
+            time (verified via 422 introspection — 19 allowed values).
         source:
           type: string
           maxLength: 255
-          description: Origin / namespace of the definition
+          description: |
+            Caller-provided integration identifier — used to namespace
+            and audit field definitions.
         description:
           type:
             - string
@@ -10755,18 +10833,24 @@ components:
             - object
             - "null"
           additionalProperties: true
-          description: Free-form configuration object — shape varies per ``field_type``
+          description: |
+            Only meaningful when ``field_type`` is ``singleSelect``. Omit
+            (or send ``null``) for other types. On create, send choices
+            as ``{choices: [{label: ...}]}``; the server assigns each one
+            an integer ``id`` and returns the resolved array in the
+            response (use that ``id`` when setting a value on a sales
+            order).
       example:
-        label: Quality Grade
-        field_type: select
-        entity_type: product
-        source: user
-        description: Customer-facing quality classification
+        label: Channel
+        field_type: singleSelect
+        entity_type: SalesOrder
+        source: your-integration
+        description: Customer-facing sales channel classification
         options:
-          values:
-            - A
-            - B
-            - C
+          choices:
+            - label: Online
+            - label: Retail
+            - label: Wholesale
     UpdateCustomFieldDefinitionRequest:
       description: Request payload for updating an existing custom field definition.
       type: object
@@ -10801,19 +10885,22 @@ components:
             $ref: "#/components/schemas/CustomFieldDefinition"
       example:
         data:
-          - id: 42
-            label: Quality Grade
-            field_type: select
-            entity_type: product
-            source: user
-            description: Customer-facing quality classification
+          - id: "0c8f1d6e-3c2a-4f5b-9d77-12ab34cd56ef"
+            label: Channel
+            field_type: singleSelect
+            entity_type: SalesOrder
+            source: your-integration
+            description: Customer-facing sales channel classification
             options:
-              values:
-                - A
-                - B
-                - C
-            created_at: "2024-01-08T10:00:00Z"
-            updated_at: "2024-01-12T15:30:00Z"
+              choices:
+                - id: 1
+                  label: Online
+                - id: 2
+                  label: Retail
+                - id: 3
+                  label: Wholesale
+            created_at: "2026-05-14T10:00:00Z"
+            updated_at: "2026-05-14T10:00:00Z"
     Stocktake:
       description: Physical inventory count process for reconciling actual stock levels with system records
       allOf:
@@ -12739,8 +12826,12 @@ components:
           type: integer
           description: Product variant ID
         quantity:
-          type: number
-          description: Quantity to transfer
+          type: string
+          description: |
+            Quantity to transfer. Sent as a fixed-precision decimal
+            string on the wire (e.g. ``"1.0000000000"``). Verified via
+            422 introspection — sending a JSON number returns
+            ``must be string``.
     CreateStockTransferRequest:
       description: Request payload for creating a new stock transfer
       type: object
@@ -17245,14 +17336,23 @@ paths:
         This endpoint can also be used for changing existing links of the variants to different storage bins.
 
         The endpoint accepts up to 500 variant storage bin objects.
+
+        **Request body shape:** the endpoint requires an array of link
+        objects, even when linking a single variant. Sending a single
+        object (without the array wrapper) returns
+        ``422 must be array``. Verified via live-API shape probe.
       operationId: linkVariantDefaultStorageBins
       requestBody:
         description: Linked variant default storage bin details
         required: true
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/VariantDefaultStorageBinLink"
+              type: array
+              minItems: 1
+              maxItems: 500
+              items:
+                $ref: "#/components/schemas/VariantDefaultStorageBinLink"
       responses:
         "200":
           description: Linked variant default storage bin order

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

@@ -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 (#738 verification);
+        # the MCP input is a pydantic ``float`` for ergonomics, so
+        # stringify at the boundary here.
         api_row = StockTransferRowRequest(
             variant_id=row.variant_id,
-            quantity=row.quantity,
+            quantity=str(row.quantity),
         )
         if row.batch_transactions:
             api_row.additional_properties = {