@epilot/pricing-client 3.58.2 → 3.59.1

package/dist/openapi.json

@@ -2534,6 +2534,7 @@
                     "type": "power",
                     "billing_period": "monthly",
                     "postal_code": "04109",
+                    "city": "Leipzig",
                     "consumption": 3500,
                     "association_id": "123456789"
                   }
@@ -2574,6 +2575,13 @@
                             "amount_decimal": "50.00"
                           }
                         }
+                      },
+                      "inputs": {
+                        "type": "power",
+                        "consumptionHT": 3500,
+                        "zipCode": "04109",
+                        "city": "Leipzig",
+                        "billingPeriod": "monthly"
                       }
                     }
                   }
@@ -3414,7 +3422,7 @@
     },
     "/v1/conditional-pricing/{slug}/condition-sets": {
       "get": {
-        "description": "Returns the condition sets built in for one conditional entity type: the situations a\nconditional Product, Price or Coupon is commonly varied by, ready to be copied into that\nschema's `conditions` array and extended or modified from there.\n\nWhich sets exist depends on the schema — an offer window is a Product's dimension, a delivery\narea is a Price's and a Coupon's — so only the sets built in for `slug` are returned.\n\nStatic, read-only reference data. The catalog is the same for every organization and is not\napplied to any schema by this endpoint — adding conditions to a schema stays an Entity API\nwrite.\n",
+        "description": "Returns the condition sets built in for one conditional entity type, ready to copy into that schema's `conditions` array. Read-only, and the same for every organization.",
         "operationId": "$getConditionSets",
         "summary": "$getConditionSets",
         "tags": [
@@ -3458,7 +3466,7 @@
     },
     "/v1/conditional-pricing:resolve": {
       "post": {
-        "description": "Resolves which of a conditional entity's variants apply, and returns each one composed: the\nbase entity overlaid with the values of the version in effect at `as_of`.\n\nResolution is two selections in a fixed order — the variant, then the version by `as_of`. It\nis always scoped to one logical entity, so it stays a cheap, predictable lookup rather than\nan open search.\n\n**The variant is selected one of two ways, and the body says which.** A `context` describes a\nsituation and is matched against the conditions each variant pins. A `variant_id` names one\nvariant and skips matching entirely. Exactly one of the two: a body carrying both, or\nneither, is a `400`.\n\nMatching follows two rules worth knowing before assembling a context. A condition a variant\ndoes **not** pin matches any value, which is what lets a condition be added to a schema\nwithout breaking the variants that already exist. A condition **missing from `context`**,\nhowever, does not satisfy one a variant pinned: an incomplete integration resolves to\nnothing rather than silently matching another segment's variants.\n\nWhen nothing matches, the entity's `default` variant is returned if it has one. There is no\nimplicit fallback to the unmodified base entity: an empty `results` means nothing applies to\nthis situation, and the base entity's values are not an answer to it. A pin does not reach\nthat fallback at all: it asks for one variant by name, and answers with it or with a 404.\n\n`options.hydrate` returns the entities a relation attribute references in place of the\nreferences, on either branch.\n\nAvailability is a separate mechanism and is never consulted here.\n",
+        "description": "Returns the variants of one conditional entity that apply, each composed: the base entity\noverlaid with the version in effect at `as_of`.\n\nSelect the variant either by `context`, matched against the conditions each variant pins, or\nby `variant_id`. Exactly one of the two. A condition a variant leaves unpinned matches any\nvalue; a condition absent from `context` matches only variants that leave it unpinned.\n\nWhen no variant matches, the entity's `default` variant is returned, or `results` is empty.\n`options.hydrate` replaces relation references with the entities they reference.\n",
         "operationId": "$resolveConditionalEntity",
         "summary": "$resolveConditionalEntity",
         "tags": [
@@ -3473,7 +3481,7 @@
               },
               "examples": {
                 "Pin a variant at a recorded instant": {
-                  "summary": "What an order shows — the numbers the customer agreed to",
+                  "summary": "The numbers an order recorded",
                   "value": {
                     "schema": "price",
                     "entity_id": "price-sp26d1yo",
@@ -3482,7 +3490,7 @@
                   }
                 },
                 "Pin a variant as it stands now": {
-                  "summary": "What a contract shows — what is billable today",
+                  "summary": "What a contract is billed at today",
                   "value": {
                     "schema": "price",
                     "entity_id": "price-sp26d1yo",
@@ -3508,7 +3516,7 @@
         },
         "responses": {
           "200": {
-            "description": "The variants that apply, each composed with the version in effect. Empty when nothing\napplies and the entity has no `default` variant. With `resolve_one`, exactly one result;\nwith a pin, exactly one or a 404.\n",
+            "description": "The variants that apply, each composed with the version in effect. Empty when none\napplies and the entity has no `default` variant.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -3516,7 +3524,7 @@
                 },
                 "examples": {
                   "A hydrated composite price": {
-                    "summary": "`price_components` holds the component entities the variant's override names, fetched after composition",
+                    "summary": "The component entities the variant's override names, fetched after composition",
                     "value": {
                       "results": [
                         {
@@ -3535,13 +3543,21 @@
                               "_id": "price-base-fee-46045",
                               "_schema": "price",
                               "unit_amount": 1290,
-                              "unit_amount_currency": "EUR"
+                              "unit_amount_currency": "EUR",
+                              "$relation": {
+                                "entity_id": "price-base-fee-46045",
+                                "attribute": "price_components"
+                              }
                             },
                             {
                               "_id": "price-kwh-46045",
                               "_schema": "price",
                               "unit_amount": 32,
-                              "unit_amount_currency": "EUR"
+                              "unit_amount_currency": "EUR",
+                              "$relation": {
+                                "entity_id": "price-kwh-46045",
+                                "attribute": "price_components"
+                              }
                             }
                           ]
                         }
@@ -3549,7 +3565,7 @@
                     }
                   },
                   "A variant carrying overrides that did not apply": {
-                    "summary": "`unit_amount_currency` reads as the entity's own value rather than the variant's, and `_inert_overrides` says why each stored override was passed over",
+                    "summary": "`unit_amount_currency` reads as the entity's own value, and `_inert_overrides` says why each stored override was passed over",
                     "value": {
                       "results": [
                         {
@@ -3582,7 +3598,7 @@
             }
           },
           "400": {
-            "description": "The context is not usable against this schema: it names an undefined condition\n(`CONDITION_UNDEFINED`), applies an operator the condition's type does not support\n(`OPERATOR_UNSUPPORTED`), carries a value malformed for its type (`CONTEXT_FORMAT_INVALID`),\nor selects more variants than one response may carry (`TOO_MANY_MATCHES`).\n\nOr the body did not pick a branch: it carries both `context` and `variant_id`, or\nneither, or sends `resolve_one` beside a pin. Those are request-validation failures, so\nthey carry a message and neither `code` nor `details` — testing `code` for absence is how\na client tells one from the four coded failures above.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n",
+            "description": "`CONDITION_UNDEFINED`, `OPERATOR_UNSUPPORTED`, `CONTEXT_FORMAT_INVALID`,\n`DEFAULT_MARKER_RESERVED`, `TOO_MANY_MATCHES`, `VALID_FROM_INVALID`,\n`ENTITY_TYPE_MISMATCH`. A body carrying both `context` and `variant_id`, or neither,\nfails validation and carries no `code`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -3592,7 +3608,7 @@
             }
           },
           "404": {
-            "description": "No such schema (`SCHEMA_NOT_FOUND`) or entity (`ENTITY_NOT_FOUND`).\n\nOn the pinned branch: the entity has no such variant, or the variant belongs to another\nentity (`VARIANT_NOT_FOUND`), or it has no version in effect at `as_of` because its first\none is later (`NO_ACTIVE_VERSION`, carrying the instant in `details.as_of`). Context\nmatching drops such a variant from the results instead — a set may lose a member where a\npin naming one cannot answer with silence. It is not `VERSION_NOT_FOUND`: a pin names no\n`valid_from`, and the variant's versions all exist — none is in effect yet.\n\nOn the context branch, with `resolve_one`: nothing applied to the context and the entity\nhas no `default` variant (`NO_MATCHES`). That says the addressing was right and nothing\nserves this situation; without `resolve_one` it is a `200` carrying an empty `results`.\n",
+            "description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`, and on the pinned branch `VARIANT_NOT_FOUND` or\n`NO_ACTIVE_VERSION`. With `resolve_one`, `NO_MATCHES`; without it, no match is a `200`\ncarrying an empty `results`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -3602,7 +3618,7 @@
             }
           },
           "409": {
-            "description": "Several variants apply while a single result was requested (`AMBIGUOUS_RESOLUTION`); the\ncandidates are in `details`.\n",
+            "description": "`AMBIGUOUS_RESOLUTION`, `CONDITION_UNREADABLE`, `VARIANT_PIN_UNDECLARED`,\n`ENTITY_NOT_CONDITIONAL`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -3610,23 +3626,13 @@
                 }
               }
             }
-          },
-          "501": {
-            "description": "A field published ahead of its behaviour was used: `variant_id`, or `options.hydrate` set\nto `true`. Declining it is how a deployed stage says the field exists and does not work\nyet, rather than quietly returning the `default` variant or unhydrated references.\n\nAnswered ahead of every other check, so a body that also names a schema that does not\nexist gets this rather than a `404`.\n\nRead `message`. The body is the shared `Error` shape rather than\n`ConditionalPricingError` — there is no code for \"not built yet\" — as it is on every 501\nthis API answers, so one branch covers all of them.\n",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Error"
-                }
-              }
-            }
           }
         }
       }
     },
     "/v1/conditional-pricing/{slug}/entities/{entity_id}/variants": {
       "post": {
-        "description": "Creates one variant of a conditional entity, together with the first version carrying its\nvalues: a variant always has at least one version.\n\nThe body pins the situation the variant applies to. Pins are exact values only — predicates\nare a read-side concept and are rejected here — and are stored canonicalized for their\ncondition's type, so two spellings of one instant, or one town written two ways, are one\nvariant rather than two that no context can tell apart.\n\nThree write rules are worth knowing before the first call:\n\n- A variant must pin at least one condition or be marked `default`. A variant pinning nothing\n  would be a universal wildcard matching every resolve, which is a far more dangerous thing\n  than a fallback and far easier to create by accident.\n- `default` is a property of the variant, set by the `default` flag, and is never a value in\n  `conditions` — not even `false`. A `default` variant cannot pin anything else, and an entity\n  can have only one; a second is refused as `TUPLE_CONFLICT`. Any entity may have one;\n  nothing is declared in the schema to allow it.\n- Condition values are immutable afterwards. A variant's identity is the situation it applies\n  to, and orders and contracts pin it. **A condition added to a schema that already has\n  variants is effectively one-way**: every existing variant is a wildcard on the new\n  dimension, but the first variant that pins it is ambiguous against all of them, and\n  retro-pinning the others is blocked by this same rule.\n\nAttribute values are applied only for attributes currently carrying `overridable_attribute`.\nMetadata and non-overridable fields present in the body are not applied rather than rejected,\nand every one but the metadata is named in the response's `warnings`, so a client working from\na slightly stale schema snapshot still succeeds and still learns which fields did not land.\nMetadata is never named, since a client echoing back a payload it read carries it in every\nbody.\n\n`variant_id` is always server-generated and returned, and is not accepted in the body — the\nrequest schema admits no such property. It is the durable key orders and contracts pin.\n",
+        "description": "Creates one variant together with its first version.\n\n`conditions` pins the situation the variant applies to, as exact values. A variant must pin\nat least one condition or be marked `default`, of which an entity may have one, and its\ncondition values are fixed once created.\n\nValues are stored only for attributes carrying `overridable_attribute`; the rest are\nreported in `warnings` rather than rejected. `variant_id` is server-generated.\n",
         "operationId": "$createConditionalVariant",
         "summary": "$createConditionalVariant",
         "tags": [
@@ -3674,7 +3680,7 @@
                 },
                 "examples": {
                   "A body naming attributes this variant may not override": {
-                    "summary": "The write succeeded and `values` holds what was stored, so the two attributes the warning names are absent from it",
+                    "summary": "The write succeeded, and the attributes the warning names are absent from `values`",
                     "value": {
                       "variant_id": "var-46045",
                       "entity_id": "price-sp26d1yo",
@@ -3715,7 +3721,7 @@
             }
           },
           "400": {
-            "description": "The variant cannot be created as described: it pins nothing and is not the default\n(`VARIANT_UNPINNED`), pins a condition the schema does not declare\n(`CONDITION_UNDEFINED`), pins a `select` value the condition's vocabulary does not admit\n(`CONDITION_VALUE_INVALID`), carries a value malformed for its condition's type\n(`PIN_FORMAT_INVALID`), or the entity already holds every variant it may hold\n(`VARIANT_LIMIT_REACHED`).\n\nSeveral refusals on this response carry no code, and testing `code` for absence is how\nthey are told from the five above: pinning the fallback marker directly under either of\nits names (`default` or `_default`), marking a variant `default` while it also pins a\nreal condition, pinning a condition whose declared type this deploy cannot read, and a\n`valid_from` this store cannot sort by. Each is an integration mistake rather than one\nbad row in a source file.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n",
+            "description": "`VARIANT_UNPINNED`, `CONDITION_UNDEFINED`, `CONDITION_VALUE_INVALID`,\n`PIN_FORMAT_INVALID`, `DEFAULT_MARKER_RESERVED`, `DEFAULT_VARIANT_PINS_CONDITIONS`,\n`VALID_FROM_INVALID`, `VALUE_UNSTORABLE`, `IDENTIFIER_INVALID`, `ENTITY_TYPE_MISMATCH`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -3724,8 +3730,18 @@
               }
             }
           },
+          "403": {
+            "description": "The token names no organization this API can act for",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "404": {
-            "description": "No such schema (`SCHEMA_NOT_FOUND`), or no such entity under it (`ENTITY_NOT_FOUND`).\n",
+            "description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -3735,7 +3751,7 @@
             }
           },
           "409": {
-            "description": "Another variant of this entity already pins this exact combination of condition values\n(`TUPLE_CONFLICT`, naming it in `details.conflicting_variant_id`) — which is also how a\nsecond `default` variant is refused — or the entity's items are being written\nconcurrently (`WRITE_CONFLICT`, retryable).\n",
+            "description": "`TUPLE_CONFLICT` (also how a second `default` variant is refused), `WRITE_CONFLICT`,\n`CONDITION_UNREADABLE`, `CONDITION_UNCONFIGURED`, `VARIANT_LIMIT_REACHED`,\n`ENTITY_NOT_CONDITIONAL`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -3749,7 +3765,7 @@
     },
     "/v1/conditional-pricing/{slug}/entities/{entity_id}/variants:list": {
       "post": {
-        "description": "Lists a conditional entity's variants and the conditions each one pins — the browse, filter\nand search read behind the Entity UI's variant screens.\n\nA `POST` because the condition filter is a structured object and needs a body; nothing is\nwritten. Every property in that body is optional, so `{}` is the whole of \"the first ten\nvariants, in `variant_id` order\" — but the body itself is required, so send `{}` rather than\nnothing at all.\n\nThree ways to narrow, and they combine. `conditions` filters on the pins themselves and takes\nthe same seven predicates a resolve context does; `search` is free text over pinned values;\n`sort` orders by one pin. **A variant matches the filter only where it pins the condition** —\nthe one place a filter and a resolve context differ: asking for the variants pinning postal\ncode 46045 does not return every variant that pins no postal code at all.\n\nRows report what is *stored*, not what resolves: no version data, no `_revision` and no\n`_inert_overrides`.\n\nPaging is by offset for the first pages and by an opaque `cursor` beyond them. `size` defaults\nto 10 and is clamped at 1000; a `from` past the offset window is refused rather than clamped,\nand the refusal names the cursor to continue with.\n\n**Published ahead of the behaviour.** No handler serves this yet, so a deployed stage answers\n`501`. The examples below are what a consumer builds against in the meantime.\n",
+        "description": "Lists a conditional entity's variants and the conditions each one pins. A `POST` because the\ncondition filter is a structured object; nothing is written. The body is required, so send\n`{}` for the first page.\n\n`conditions` filters on the pins, taking the same predicates a resolve context does, and\nmatches a variant only where it pins that condition. `search` is free text over pinned\nvalues; `sort` orders by one pin.\n\nOffset paging up to the search index's window, then the `cursor` from `next`.\n",
         "operationId": "$listConditionalVariants",
         "summary": "$listConditionalVariants",
         "tags": [
@@ -3790,7 +3806,7 @@
                   "value": {}
                 },
                 "Find the entity's fallback variant": {
-                  "summary": "The variant served when nothing else applies — at most one per entity",
+                  "summary": "The variant served when nothing else applies",
                   "value": {
                     "conditions": {
                       "default": true
@@ -3798,7 +3814,7 @@
                   }
                 },
                 "Filter, search and sort together": {
-                  "summary": "The variants pinning a consumption band in either segment, ordered by postal code",
+                  "summary": "Variants pinning a consumption band in either segment, ordered by postal code",
                   "value": {
                     "conditions": {
                       "segment": {
@@ -3869,7 +3885,7 @@
             }
           },
           "400": {
-            "description": "The listing cannot be served as described.\n\nThe filter is checked against the schema exactly as a resolve context is, by the same\ncode, so it reports the same three codes: a condition the schema does not declare\n(`CONDITION_UNDEFINED`), a predicate the condition's type does not support\n(`OPERATOR_UNSUPPORTED`), or a value malformed for its type (`CONTEXT_FORMAT_INVALID`).\n\nTwo paging refusals carry codes of their own, and the fix for each is a different request:\na `from` plus `size` reaching past the offset window (`OFFSET_WINDOW_EXCEEDED`, naming all\nthree numbers in `details`; page on with the last response's `next` instead), and a\n`cursor` that is malformed or was issued for a different listing (`CURSOR_INVALID`; start\nthe listing again without one).\n\nA `sort` naming something other than a `conditions.<name>` of a sortable type carries a\nmessage and neither `code` nor `details`, as does a body this schema rejects outright.\nTesting `code` for absence is how those are told from the five above.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n",
+            "description": "`CONDITION_UNDEFINED`, `OPERATOR_UNSUPPORTED`, `CONTEXT_FORMAT_INVALID`, `SORT_INVALID`,\n`OFFSET_WINDOW_EXCEEDED`, `CURSOR_INVALID`, `ENTITY_TYPE_MISMATCH`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -3878,8 +3894,18 @@
               }
             }
           },
+          "403": {
+            "description": "The token names no organization this API can act for",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "404": {
-            "description": "No such schema (`SCHEMA_NOT_FOUND`), or no such entity under it (`ENTITY_NOT_FOUND`).\n\nAn entity that exists and has no variants is a `200` carrying an empty `results` and\n`hits: 0` — having none is an answer, not a missing resource.\n",
+            "description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`. An entity with no variants is a `200` carrying\nan empty `results` and `hits: 0`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -3888,12 +3914,12 @@
               }
             }
           },
-          "501": {
-            "description": "Published ahead of the behaviour. This operation is declared and not yet dispatched, so\nevery request to it is answered here until the listing behaviour lands — which is how a\ndeployed stage says \"this exists and does not work yet\" rather than answering with an\nempty page a client would read as an empty entity.\n\nRead `message`. The body is the shared `Error` shape, as it is on every 501 this API\nanswers, so one \"not built yet\" branch covers all of them.\n",
+          "409": {
+            "description": "`CONDITION_UNREADABLE`, raised only where the filter or `sort` names that condition, and\n`ENTITY_NOT_CONDITIONAL`.\n",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Error"
+                  "$ref": "#/components/schemas/ConditionalPricingError"
                 }
               }
             }
@@ -3903,7 +3929,7 @@
     },
     "/v1/conditional-pricing/{slug}/entities/{entity_id}/variants:tree": {
       "post": {
-        "description": "The variants list, each row carrying the version in effect at `as_of` — the Entity UI's main\nediting screen in one call rather than one call per row.\n\nEverything the variants list accepts, filtering, search, sort and paging alike, means the same\nhere. Three differences, all from the version lookup each row costs: the body takes an\n`as_of`, `size` is clamped at 100 rather than 1000, and a variant with no version to show is\nomitted from `results` (see `VariantTree`).\n\nEvery row carries a `version`, and a `status` saying which one it got. A variant always has at\nleast one version, so at any instant either a version is in effect (`active`) or every\nversion of that variant is still ahead of it (`scheduled`) — in which case `version` is that\nupcoming first one, which is what makes a staged variant visible on the screen rather than\nblank.\n\nThe version on a row carries no `_revision`. An editing screen re-reads the one version it is\nabout to write through that version's own `GET`, which is strongly consistent, and writes with\nthe revision it returns.\n\nThe base entity is not part of this response. The screen's standard-price row is an ordinary\nentity read, and a variant's full timeline is the versions list.\n\n**Published ahead of the behaviour.** No handler serves this yet, so a deployed stage answers\n`501`.\n",
+        "description": "The variants list, each row carrying the version in effect at `as_of` and a `status` saying\nwhether that version is `active` or still `scheduled`.\n\nTakes everything the variants list takes, plus `as_of`. `size` is clamped at 100, and a\nvariant mid-delete is omitted from `results`.\n",
         "operationId": "$getConditionalVariantTree",
         "summary": "$getConditionalVariantTree",
         "tags": [
@@ -3947,7 +3973,7 @@
                   }
                 },
                 "The screen at a future date": {
-                  "summary": "What the table will look like once next year's versions take effect",
+                  "summary": "The table once next year's versions take effect",
                   "value": {
                     "as_of": "2027-03-15T00:00:00Z",
                     "conditions": {
@@ -4040,7 +4066,7 @@
             }
           },
           "400": {
-            "description": "The listing cannot be served as described — the variants list's `400` word for word, plus\nan `as_of` that is not a timestamp this API can read.\n\nThe filter is checked against the schema exactly as a resolve context is, by the same\ncode, so it reports the same three codes: a condition the schema does not declare\n(`CONDITION_UNDEFINED`), a predicate the condition's type does not support\n(`OPERATOR_UNSUPPORTED`), or a value malformed for its type (`CONTEXT_FORMAT_INVALID`).\n\nTwo paging refusals carry codes of their own, and the fix for each is a different request:\na `from` plus `size` reaching past the offset window (`OFFSET_WINDOW_EXCEEDED`, naming all\nthree numbers in `details`; page on with the last response's `next` instead), and a\n`cursor` that is malformed or was issued for a different listing (`CURSOR_INVALID`; start\nthe listing again without one).\n\nA `sort` naming something other than a `conditions.<name>` of a sortable type carries a\nmessage and neither `code` nor `details`, as does a body this schema rejects outright.\nTesting `code` for absence is how those are told from the five above.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n",
+            "description": "`CONDITION_UNDEFINED`, `OPERATOR_UNSUPPORTED`, `CONTEXT_FORMAT_INVALID`, `SORT_INVALID`,\n`OFFSET_WINDOW_EXCEEDED`, `CURSOR_INVALID`, `VALID_FROM_INVALID`,\n`ENTITY_TYPE_MISMATCH`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -4049,8 +4075,18 @@
               }
             }
           },
+          "403": {
+            "description": "The token names no organization this API can act for",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "404": {
-            "description": "No such schema (`SCHEMA_NOT_FOUND`), or no such entity under it (`ENTITY_NOT_FOUND`).\n\nAn entity that exists and has no variants is a `200` carrying an empty `results` and\n`hits: 0` — having none is an answer, not a missing resource.\n",
+            "description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`. An entity with no variants is a `200` carrying\nan empty `results` and `hits: 0`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -4059,12 +4095,12 @@
               }
             }
           },
-          "501": {
-            "description": "Published ahead of the behaviour. This operation is declared and not yet dispatched, so\nevery request to it is answered here until the listing behaviour lands — which is how a\ndeployed stage says \"this exists and does not work yet\" rather than answering with an\nempty page a client would read as an empty entity.\n\nRead `message`. The body is the shared `Error` shape, as it is on every 501 this API\nanswers, so one \"not built yet\" branch covers all of them.\n",
+          "409": {
+            "description": "`CONDITION_UNREADABLE`, raised only where the filter or `sort` names that condition, and\n`ENTITY_NOT_CONDITIONAL`.\n",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Error"
+                  "$ref": "#/components/schemas/ConditionalPricingError"
                 }
               }
             }
@@ -4074,7 +4110,7 @@
     },
     "/v1/conditional-pricing/{slug}/entities/{entity_id}/variants/{variant_id}": {
       "get": {
-        "description": "Returns the version of this variant that is currently in effect — the one with the latest\n`valid_from` at or before now.\n\nThe \"open this variant\" read: no date arithmetic is asked of the caller, and what comes back\ncarries the `_revision` a write to that version has to be sent with, so an editing screen can\nload and save without working out which version it is looking at.\n\nWhat is returned is the version's own attribute overrides, not the base entity overlaid with\nthem. Composing the two is what `:resolve` answers.\n\nA variant staged ahead of its launch has versions but none of them in effect, and is reported\nas having none rather than as not existing — the two are fixed differently.\n",
+        "description": "Returns the version of this variant in effect now — the latest `valid_from` at or before now\n— with the `_revision` a write to it must carry.\n\nThese are the version's own overrides; `:resolve` composes them onto the entity.\n",
         "operationId": "$getActiveConditionalVariantVersion",
         "summary": "$getActiveConditionalVariantVersion",
         "tags": [
@@ -4124,7 +4160,7 @@
             }
           },
           "400": {
-            "description": "Invalid request, e.g. the slug names no conditional entity type.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n",
+            "description": "`IDENTIFIER_INVALID`, `ENTITY_TYPE_MISMATCH`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4133,8 +4169,28 @@
               }
             }
           },
+          "403": {
+            "description": "The token names no organization this API can act for",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "404": {
-            "description": "No entity with that id (`ENTITY_NOT_FOUND`), no such variant under it\n(`VARIANT_NOT_FOUND`), or it has no version in effect at the instant addressed\n(`NO_ACTIVE_VERSION`). A variant whose versions are all still\nscheduled has none in effect, which is reported as such rather than as a missing\nvariant. Selecting the\nversion in effect and reading it are two reads, so a delete landing between them is\nanswered `VERSION_NOT_FOUND`.\n",
+            "description": "`ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`, `NO_ACTIVE_VERSION`, `VERSION_NOT_FOUND`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConditionalPricingError"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "`ENTITY_NOT_CONDITIONAL`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4146,7 +4202,7 @@
         }
       },
       "put": {
-        "description": "Replaces the values of the version currently in effect, wholesale.\n\nThe body is the complete set of attribute overrides: an attribute the variant may override and\nthat is absent from it stops being overridden. Attributes the variant may **not** override are\nnot applied where the body carries them, and their stored value is kept rather than dropped.\n\nEditing the version in effect is the ordinary way a live price is corrected, and warns about\nnothing: what changes is what that version *says*, not which version is in effect.\n\nNeither `valid_from` nor `conditions` can be changed here. Both are accepted when they match\nwhat is stored, so a client building its body from the version it loaded need not strip them\nout first, and both are refused when they name something else.\n",
+        "description": "Replaces the values of the version in effect. The body is the complete set of overrides: an\noverridable attribute absent from it stops being overridden, and one the variant may not\noverride keeps its stored value.\n\n`valid_from` and `conditions` are accepted only unchanged.\n",
         "operationId": "$replaceActiveConditionalVariantVersion",
         "summary": "$replaceActiveConditionalVariantVersion",
         "tags": [
@@ -4206,7 +4262,7 @@
             }
           },
           "400": {
-            "description": "The write cannot be applied as described: it would move the version it addresses to another\n`valid_from`, or change the conditions its variant is pinned to — both identity rather than\ncontent, and both fixed at creation. Also when `_revision` is missing or is not a revision\nmarker.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n",
+            "description": "`VALID_FROM_IMMUTABLE`, `VALID_FROM_INVALID`, `VALUE_UNSTORABLE`, `IDENTIFIER_INVALID`,\n`ENTITY_TYPE_MISMATCH`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -4215,8 +4271,18 @@
               }
             }
           },
+          "403": {
+            "description": "The token names no organization this API can act for",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "404": {
-            "description": "No such schema (`SCHEMA_NOT_FOUND`), no entity with that id (`ENTITY_NOT_FOUND`), no such\nvariant under it (`VARIANT_NOT_FOUND`), or the variant has no version in effect at the\ninstant addressed (`NO_ACTIVE_VERSION`). A\nvariant whose versions are all still scheduled has none in effect, which is reported as\nsuch rather than as a missing variant. Selecting the\nversion in effect and reading it are two reads, so a delete landing between them is\nanswered `VERSION_NOT_FOUND`.\n",
+            "description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`, `NO_ACTIVE_VERSION`,\n`VERSION_NOT_FOUND`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -4226,7 +4292,7 @@
             }
           },
           "409": {
-            "description": "The version has been written since `_revision` was read (`WRITE_CONFLICT`, retryable after\nre-reading the version).\n",
+            "description": "`WRITE_CONFLICT`, `VARIANT_CONDITIONS_IMMUTABLE`, `ENTITY_NOT_CONDITIONAL`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4238,7 +4304,7 @@
         }
       },
       "patch": {
-        "description": "Changes only the fields it names on the version currently in effect.\n\nEverything the body does not mention is left as stored — the \"just nudge this number\" write. A\n`null` is a value like any other rather than a deletion; a client that wants an attribute to\nstop being overridden sends the complete snapshot without it through `PUT`.\n\nAttempting to change a pinned condition value is refused, as on every version write: a\nvariant's conditions are fixed at creation.\n",
+        "description": "Changes only the fields it names on the version in effect. `null` sets a value rather than\nremoving an override; use the replace operation to remove one.\n",
         "operationId": "$patchActiveConditionalVariantVersion",
         "summary": "$patchActiveConditionalVariantVersion",
         "tags": [
@@ -4298,7 +4364,7 @@
             }
           },
           "400": {
-            "description": "The write cannot be applied as described: it would move the version it addresses to another\n`valid_from`, or change the conditions its variant is pinned to — both identity rather than\ncontent, and both fixed at creation. Also when `_revision` is missing or is not a revision\nmarker.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n",
+            "description": "`VALID_FROM_IMMUTABLE`, `VALID_FROM_INVALID`, `VALUE_UNSTORABLE`, `IDENTIFIER_INVALID`,\n`ENTITY_TYPE_MISMATCH`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -4307,8 +4373,18 @@
               }
             }
           },
+          "403": {
+            "description": "The token names no organization this API can act for",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "404": {
-            "description": "No such schema (`SCHEMA_NOT_FOUND`), no entity with that id (`ENTITY_NOT_FOUND`), no such\nvariant under it (`VARIANT_NOT_FOUND`), or the variant has no version in effect at the\ninstant addressed (`NO_ACTIVE_VERSION`). A\nvariant whose versions are all still scheduled has none in effect, which is reported as\nsuch rather than as a missing variant. Selecting the\nversion in effect and reading it are two reads, so a delete landing between them is\nanswered `VERSION_NOT_FOUND`.\n",
+            "description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`, `NO_ACTIVE_VERSION`,\n`VERSION_NOT_FOUND`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -4318,7 +4394,7 @@
             }
           },
           "409": {
-            "description": "The version has been written since `_revision` was read (`WRITE_CONFLICT`, retryable after\nre-reading the version).\n",
+            "description": "`WRITE_CONFLICT`, `VARIANT_CONDITIONS_IMMUTABLE`, `ENTITY_NOT_CONDITIONAL`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4330,7 +4406,7 @@
         }
       },
       "delete": {
-        "description": "Removes one variant of a conditional entity: the condition tuple it holds, its registration\nin the search index, and every version it accumulated.\n\nTwo phases. The first frees the tuple and deregisters the variant, and is what makes the\ncombination of condition values immediately reusable — the second removes the version rows in\nbatches afterwards. A response arrives only once both have finished for this request, but the\ntuple is reusable from the moment the first completes, whether or not the second did: a\nvariant with more versions than one transaction can carry is the ordinary case, not an edge\none. An interrupted delete is safe to send again; it picks up where it stopped.\n\nNothing is archived. A variant an order or contract pins stops resolving, and hydration drops\nthe reference leniently rather than failing the read.\n\nThis removes the **variant**, not one of its versions. To remove a single version, name it on\n`…/variants/{variant_id}/versions/{valid_from}` — including the one currently in effect, which\nhas no shorthand delete: a delete names the version it removes.\n",
+        "description": "Removes one variant: its condition tuple, its index entry and all its versions. The tuple\nbecomes reusable, and an interrupted delete is safe to send again.\n\nOrders and contracts pinning the variant stop resolving. To remove a single version, address\nit under `versions/{valid_from}`.\n",
         "operationId": "$deleteConditionalVariant",
         "summary": "$deleteConditionalVariant",
         "tags": [
@@ -4380,7 +4456,7 @@
             }
           },
           "400": {
-            "description": "Invalid request, e.g. the slug names no conditional entity type.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n",
+            "description": "`IDENTIFIER_INVALID`, `ENTITY_TYPE_MISMATCH`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4389,8 +4465,18 @@
               }
             }
           },
+          "403": {
+            "description": "The token names no organization this API can act for",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "404": {
-            "description": "No entity with that id (`ENTITY_NOT_FOUND`), or it has no such variant\n(`VARIANT_NOT_FOUND`).\n",
+            "description": "`ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4400,7 +4486,7 @@
             }
           },
           "409": {
-            "description": "The variant's items are being written concurrently (`WRITE_CONFLICT`, retryable).",
+            "description": "`WRITE_CONFLICT`, `ENTITY_NOT_CONDITIONAL`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4414,7 +4500,7 @@
     },
     "/v1/conditional-pricing/{slug}/entities/{entity_id}/variants/{variant_id}/versions": {
       "get": {
-        "description": "Lists one variant's versions — its whole timeline, oldest first, which is what expanding a row\nof the tree loads.\n\nIts paging differs from the two variant reads: cursor paging only, no `from` and no `size`,\nand **no `hits`**.\n\nTwo paging facts a client gets wrong if it assumes otherwise. **A page may be shorter than\n`limit`, or empty, and still carry a `next`**, so a client pages until `next` is absent rather\nthan until a page looks short. And **a cursor belongs to one variant and one `order`**:\nreplaying one against another variant, or against the opposite order, is a `400` rather than a\nplausible-looking wrong page.\n\nVersions carry no `_revision` here. An editing screen re-reads the one version it is about to\nwrite through that version's own `GET`, which is strongly consistent, and writes with the\nrevision it returns.\n\n**Published ahead of the behaviour.** No handler serves this yet, so a deployed stage answers\n`501`.\n",
+        "description": "Lists one variant's versions. Cursor paging only: a page may be short or empty and still\ncarry a `next`, so page until `next` is absent. A cursor is bound to one variant and one\n`order`.\n",
         "operationId": "$listConditionalVariantVersions",
         "summary": "$listConditionalVariantVersions",
         "tags": [
@@ -4454,7 +4540,7 @@
           {
             "in": "query",
             "name": "limit",
-            "description": "Versions per page. Defaults to 100, which is also the maximum; a larger value is clamped\nsilently. A variant's timeline is usually short enough to fit one page.\n",
+            "description": "Versions per page. Defaults to 100, which is also the maximum; a larger value is clamped.",
             "schema": {
               "type": "integer",
               "minimum": 1,
@@ -4466,7 +4552,7 @@
           {
             "in": "query",
             "name": "order",
-            "description": "Which end of the timeline to read from: `asc` oldest first, `desc` newest first. Defaults\nto `asc`.\n\nBaked into every cursor this read issues: a cursor resumes one direction, and replaying it\nagainst the other is a `400`.\n",
+            "description": "Which end of the timeline to read from. Baked into every cursor this read issues.",
             "schema": {
               "type": "string",
               "enum": [
@@ -4481,7 +4567,7 @@
           {
             "in": "query",
             "name": "cursor",
-            "description": "Continue from a previous response's `next`. Opaque: it encodes the position and the order\nit was issued for, and nothing a client should read or construct.\n",
+            "description": "Continue from a previous response's `next`. Opaque.",
             "schema": {
               "type": "string"
             },
@@ -4499,7 +4585,7 @@
                 },
                 "examples": {
                   "A short page that is not the last one": {
-                    "summary": "One version and a `next` — a page shorter than `limit` says nothing about whether the timeline has ended",
+                    "summary": "One version and a `next` — a short page does not mean the timeline has ended",
                     "value": {
                       "results": [
                         {
@@ -4523,7 +4609,7 @@
                     }
                   },
                   "The last page": {
-                    "summary": "No `next`, which is the only reliable end of the timeline",
+                    "summary": "No `next`, which is the end of the timeline",
                     "value": {
                       "results": [
                         {
@@ -4550,7 +4636,7 @@
             }
           },
           "400": {
-            "description": "A `cursor` that is malformed, belongs to another variant, or was issued for the opposite\norder is `CURSOR_INVALID`, with `details.reason` saying which. The fix is the same for all\nthree: read the timeline again without a cursor.\n\nA `limit` below 1 and an `order` that is neither `asc` nor `desc` carry a message and\nneither `code` nor `details`; testing `code` for absence is how they are told from the one\nabove.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n",
+            "description": "`CURSOR_INVALID`, `ENTITY_TYPE_MISMATCH`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4559,8 +4645,18 @@
               }
             }
           },
+          "403": {
+            "description": "The token names no organization this API can act for",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "404": {
-            "description": "No such schema (`SCHEMA_NOT_FOUND`), no such entity under it (`ENTITY_NOT_FOUND`), or the\nentity has no such variant (`VARIANT_NOT_FOUND`) — which is also the answer for a variant\nbelonging to a *different* entity: a variant id alone addresses nothing.\n\nThe entity is established before the timeline is read, so a caller who mistyped the entity\nid is never sent to fix the variant id, and one who sent the wrong slug hears about the\nslug.\n",
+            "description": "`ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4569,12 +4665,12 @@
               }
             }
           },
-          "501": {
-            "description": "Published ahead of the behaviour. This operation is declared and not yet dispatched, so\nevery request to it is answered here until the listing behaviour lands — which is how a\ndeployed stage says \"this exists and does not work yet\" rather than answering with an\nempty page a client would read as an empty entity.\n\nRead `message`. The body is the shared `Error` shape, as it is on every 501 this API\nanswers, so one \"not built yet\" branch covers all of them.\n",
+          "409": {
+            "description": "`ENTITY_NOT_CONDITIONAL`.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Error"
+                  "$ref": "#/components/schemas/ConditionalPricingError"
                 }
               }
             }
@@ -4582,7 +4678,7 @@
         }
       },
       "post": {
-        "description": "Appends a version to a variant: a new set of values taking effect at its own instant.\n\nThis is how a price changes. No version carries an end date and nothing is superseded\nexplicitly — the version in effect at an instant is simply the one with the latest `valid_from`\nat or before it, so appending a later version is the whole of \"this is the new price from then\non\". A version dated in the future is staged and excluded from resolution until its date.\n\n**A version is never refused for being late.** A `valid_from` in the past is written like any\nother and answered with warnings in `warnings` naming what it moved — what resolves now, what a\npast-dated read returns, or both. Correcting a price that took effect last week is ordinary\nwork.\n\nWhat is refused is appending at a `valid_from` the variant already has: that write means either\n\"replace it\" or \"and also this\", and only the caller knows which. The two operations both\nexist, on the dated version path.\n\nThe variant's `conditions` are its identity and are fixed at creation; they may be sent back\nunchanged but never changed.\n",
+        "description": "Appends a version taking effect at its own instant. The version in effect at any instant is\nthe one with the latest `valid_from` at or before it; a future one is staged until its date.\n\nA past `valid_from` is accepted and reported in `warnings`. One the variant already has is\nrefused — replace or patch that version instead.\n",
         "operationId": "$appendConditionalVariantVersion",
         "summary": "$appendConditionalVariantVersion",
         "tags": [
@@ -4642,7 +4738,7 @@
             }
           },
           "400": {
-            "description": "The version cannot be appended as described: the body would change the variant's conditions,\nor `valid_from` is not a timestamp this store can sort by.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n",
+            "description": "`VALID_FROM_INVALID`, `VALUE_UNSTORABLE`, `IDENTIFIER_INVALID`, `ENTITY_TYPE_MISMATCH`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4651,8 +4747,18 @@
               }
             }
           },
+          "403": {
+            "description": "The token names no organization this API can act for",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "404": {
-            "description": "No such schema (`SCHEMA_NOT_FOUND`), no entity with that id (`ENTITY_NOT_FOUND`), or no\nsuch variant under it (`VARIANT_NOT_FOUND`).\n",
+            "description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4662,7 +4768,7 @@
             }
           },
           "409": {
-            "description": "The variant already has a version at that `valid_from` (`VERSION_CONFLICT`) — append means\nappend, never an implicit overwrite. Replace or patch that version instead.\n",
+            "description": "`VERSION_CONFLICT`, `VARIANT_CONDITIONS_IMMUTABLE`, `ENTITY_NOT_CONDITIONAL`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4676,7 +4782,7 @@
     },
     "/v1/conditional-pricing/{slug}/entities/{entity_id}/variants/{variant_id}/versions/{valid_from}": {
       "get": {
-        "description": "Returns one specific version of a variant, by the instant it takes effect — what a form editing\nthat version loads.\n\nExact, never nearest: an instant the variant has no version at is a not-found rather than the\nversion that would be in effect at it. That question is the shorthand read's, or `:resolve`'s.\n",
+        "description": "Returns one version by the instant it takes effect. Exact, never nearest.",
         "operationId": "$getConditionalVariantVersion",
         "summary": "$getConditionalVariantVersion",
         "tags": [
@@ -4716,7 +4822,7 @@
           {
             "in": "path",
             "name": "valid_from",
-            "description": "The version to address, by the instant it takes effect.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision. Written any accepted way: it is\ncanonicalized before it is matched, so the spelling a read returned and the spelling a\nhuman typed address the same version.\n",
+            "description": "The version to address, by the instant it takes effect. An RFC 3339 date\n(`2026-01-01`, read as midnight UTC) or date-time, to at most millisecond precision,\ncanonicalized before it is matched.\n",
             "schema": {
               "type": "string"
             },
@@ -4736,7 +4842,7 @@
             }
           },
           "400": {
-            "description": "Invalid request, e.g. a `valid_from` that is not a timestamp this store can sort by.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n",
+            "description": "`VALID_FROM_INVALID`, `IDENTIFIER_INVALID`, `ENTITY_TYPE_MISMATCH`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4745,8 +4851,28 @@
               }
             }
           },
+          "403": {
+            "description": "The token names no organization this API can act for",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "404": {
-            "description": "No entity with that id (`ENTITY_NOT_FOUND`), no such variant under this schema\n(`VARIANT_NOT_FOUND`), or no version at that instant (`VERSION_NOT_FOUND`).\n",
+            "description": "`ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`, `VERSION_NOT_FOUND`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConditionalPricingError"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "`ENTITY_NOT_CONDITIONAL`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4758,7 +4884,7 @@
         }
       },
       "put": {
-        "description": "Replaces one version's values wholesale, addressed by its `valid_from`.\n\nEditable whatever its date, scheduled or past. Writing a superseded version is answered with a\nwarning naming what a past-dated read now returns; it is not refused.\n\nAttributes the variant may not override are not applied where the body carries them, and their\nstored value is preserved rather than dropped.\n",
+        "description": "Replaces one version's values, whatever its date. Attributes the variant may not override\nkeep their stored value. Writing a superseded version is reported in `warnings`.\n",
         "operationId": "$replaceConditionalVariantVersion",
         "summary": "$replaceConditionalVariantVersion",
         "tags": [
@@ -4798,7 +4924,7 @@
           {
             "in": "path",
             "name": "valid_from",
-            "description": "The version to address, by the instant it takes effect.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision. Written any accepted way: it is\ncanonicalized before it is matched, so the spelling a read returned and the spelling a\nhuman typed address the same version.\n",
+            "description": "The version to address, by the instant it takes effect. An RFC 3339 date\n(`2026-01-01`, read as midnight UTC) or date-time, to at most millisecond precision,\ncanonicalized before it is matched.\n",
             "schema": {
               "type": "string"
             },
@@ -4828,7 +4954,7 @@
             }
           },
           "400": {
-            "description": "The write cannot be applied as described: it would move the version it addresses to another\n`valid_from`, or change the conditions its variant is pinned to — both identity rather than\ncontent, and both fixed at creation. Also when `_revision` is missing or is not a revision\nmarker.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n",
+            "description": "`VALID_FROM_IMMUTABLE`, `VALID_FROM_INVALID`, `VALUE_UNSTORABLE`, `IDENTIFIER_INVALID`,\n`ENTITY_TYPE_MISMATCH`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -4837,8 +4963,18 @@
               }
             }
           },
+          "403": {
+            "description": "The token names no organization this API can act for",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "404": {
-            "description": "No such schema (`SCHEMA_NOT_FOUND`), no entity with that id (`ENTITY_NOT_FOUND`), no such\nvariant under it (`VARIANT_NOT_FOUND`), or no version at that instant\n(`VERSION_NOT_FOUND`).\n",
+            "description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`, `VERSION_NOT_FOUND`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -4848,7 +4984,7 @@
             }
           },
           "409": {
-            "description": "The version has been written since `_revision` was read (`WRITE_CONFLICT`, retryable after\nre-reading the version).\n",
+            "description": "`WRITE_CONFLICT`, `VARIANT_CONDITIONS_IMMUTABLE`, `ENTITY_NOT_CONDITIONAL`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4860,7 +4996,7 @@
         }
       },
       "patch": {
-        "description": "Changes only the fields it names on one version, addressed by its `valid_from`.\n\nEverything the body does not mention is left as stored. A partial update that tries to change a\npinned condition value is refused: condition values are immutable after a variant is created.\n",
+        "description": "Changes only the fields it names on one version.",
         "operationId": "$patchConditionalVariantVersion",
         "summary": "$patchConditionalVariantVersion",
         "tags": [
@@ -4900,7 +5036,7 @@
           {
             "in": "path",
             "name": "valid_from",
-            "description": "The version to address, by the instant it takes effect.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision. Written any accepted way: it is\ncanonicalized before it is matched, so the spelling a read returned and the spelling a\nhuman typed address the same version.\n",
+            "description": "The version to address, by the instant it takes effect. An RFC 3339 date\n(`2026-01-01`, read as midnight UTC) or date-time, to at most millisecond precision,\ncanonicalized before it is matched.\n",
             "schema": {
               "type": "string"
             },
@@ -4930,7 +5066,7 @@
             }
           },
           "400": {
-            "description": "The write cannot be applied as described: it would move the version it addresses to another\n`valid_from`, or change the conditions its variant is pinned to — both identity rather than\ncontent, and both fixed at creation. Also when `_revision` is missing or is not a revision\nmarker.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n",
+            "description": "`VALID_FROM_IMMUTABLE`, `VALID_FROM_INVALID`, `VALUE_UNSTORABLE`, `IDENTIFIER_INVALID`,\n`ENTITY_TYPE_MISMATCH`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -4939,8 +5075,18 @@
               }
             }
           },
+          "403": {
+            "description": "The token names no organization this API can act for",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "404": {
-            "description": "No such schema (`SCHEMA_NOT_FOUND`), no entity with that id (`ENTITY_NOT_FOUND`), no such\nvariant under it (`VARIANT_NOT_FOUND`), or no version at that instant\n(`VERSION_NOT_FOUND`).\n",
+            "description": "`SCHEMA_NOT_FOUND`, `ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`, `VERSION_NOT_FOUND`.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -4950,7 +5096,7 @@
             }
           },
           "409": {
-            "description": "The version has been written since `_revision` was read (`WRITE_CONFLICT`, retryable after\nre-reading the version).\n",
+            "description": "`WRITE_CONFLICT`, `VARIANT_CONDITIONS_IMMUTABLE`, `ENTITY_NOT_CONDITIONAL`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4962,7 +5108,7 @@
         }
       },
       "delete": {
-        "description": "Removes one version of a variant.\n\nWithdrawing a scheduled adjustment is what this is for, and deleting a future version warns\nabout nothing — nothing that has resolved, or could have resolved, changes. Deleting a version\nthat has taken effect is allowed too and answered with a warning: it changes what a past-dated\nread returns, and if it was the version in effect it changes what resolves now.\n\n**A variant's last remaining version cannot be deleted.** Such a variant would still hold its\ncondition tuple and still be selectable, and then resolve to nothing — which is a variant delete\nwearing a version delete's clothes. Delete the variant instead; that frees the tuple too.\n\nThe variant itself is untouched: it keeps its conditions, its tuple and its place in the index.\n",
+        "description": "Removes one version. What the removal moves is reported in `warnings`. A variant's last\nremaining version cannot be removed — delete the variant instead.\n",
         "operationId": "$deleteConditionalVariantVersion",
         "summary": "$deleteConditionalVariantVersion",
         "tags": [
@@ -5002,7 +5148,7 @@
           {
             "in": "path",
             "name": "valid_from",
-            "description": "The version to address, by the instant it takes effect.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision. Written any accepted way: it is\ncanonicalized before it is matched, so the spelling a read returned and the spelling a\nhuman typed address the same version.\n",
+            "description": "The version to address, by the instant it takes effect. An RFC 3339 date\n(`2026-01-01`, read as midnight UTC) or date-time, to at most millisecond precision,\ncanonicalized before it is matched.\n",
             "schema": {
               "type": "string"
             },
@@ -5012,7 +5158,7 @@
           {
             "in": "query",
             "name": "_revision",
-            "description": "The revision marker read from the version being deleted. The delete is refused if the\nversion has been written since.\n\nThe same marker the write bodies carry as `_revision`.\n",
+            "description": "The revision read from the version being deleted. The delete is refused if the version\nhas been written since.\n",
             "schema": {
               "type": "integer",
               "minimum": 1
@@ -5033,7 +5179,7 @@
             }
           },
           "400": {
-            "description": "The version cannot be removed because it is the variant's only one\n(`LAST_VERSION_UNDELETABLE`) — such a variant would keep its condition tuple, stay\nselectable and resolve to nothing, so delete the variant instead, which frees the tuple\ntoo.\n\nThe refusals around it carry no code, and testing `code` for absence is how they are told\nfrom it: a missing or unreadable `_revision`, a `valid_from` this store cannot sort by,\nand an id this store cannot key by.\n\nAlso refused here: an entity id belonging to another type than the slug names\n(`ENTITY_TYPE_MISMATCH`), and an entity that was never created as a conditional one\n(`ENTITY_NOT_CONDITIONAL`).\n",
+            "description": "`VALID_FROM_INVALID`, `IDENTIFIER_INVALID`, `ENTITY_TYPE_MISMATCH`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -5042,8 +5188,18 @@
               }
             }
           },
+          "403": {
+            "description": "The token names no organization this API can act for",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "404": {
-            "description": "No entity with that id (`ENTITY_NOT_FOUND`), no such variant under this schema\n(`VARIANT_NOT_FOUND`), or no version at that instant (`VERSION_NOT_FOUND`).\n",
+            "description": "`ENTITY_NOT_FOUND`, `VARIANT_NOT_FOUND`, `VERSION_NOT_FOUND`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -5053,7 +5209,7 @@
             }
           },
           "409": {
-            "description": "The version has been written since `_revision` was read (`WRITE_CONFLICT`, retryable after\nre-reading the version).\n",
+            "description": "`LAST_VERSION_UNDELETABLE`, `WRITE_CONFLICT`, `ENTITY_NOT_CONDITIONAL`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -5067,7 +5223,7 @@
     },
     "/v1/conditional-pricing/{slug}/variants:batchUpsert": {
       "post": {
-        "description": "Writes up to 100 variants or versions in one call — the endpoint a bulk importer drives a\nrefresh cycle through, so hundreds of thousands of keys are a stream of calls rather than a\ncall per key.\n\n**One schema in the path, one entity per item.** A single call may name several entities, so\nit can refresh a whole tariff hierarchy — a composite price and its components together —\nand the entity id rides each item instead of the path.\n\n**An item addresses a condition tuple, never a `variant_id`.** An upsert creates a variant\nthat has no id yet. The id it created, or found, is on the result entry.\n\nEach item's outcome is derived from what is stored, with no mode for the caller to declare,\nin this order: an unknown tuple is `variant_created`, a known tuple with no version at the\nitem's `valid_from` is `version_created`, and an existing version at that exact instant is\n`updated` — or `skipped`, which is reserved for a write whose values are identical to what is\nstored, so re-running an unchanged import still reads as a no-op. `version_created` is\ndistinct from `variant_created` so an importer's counts can tell \"new postal codes appeared\"\nfrom \"existing variants got their scheduled adjustment\".\n\nAn item without `valid_from` is a current-state, last-write-wins write, and has no `skipped`\ndetection. A `valid_from` in the past changes nothing about the outcome — it is written like\nany other and answered with the timeline warnings on that item. An importer stamping one\n`valid_from` across a batch therefore sees backdate warnings on every item; omitting the\nfield is how it avoids them.\n\n**Items addressing the same variant apply in array order; items addressing different\nvariants are processed in parallel.** Here \"the same variant\" is the same `(entity_id,\ncondition tuple)`, so two items sharing a tuple and a `valid_from` apply in order and the\nlast one wins. There is no cross-item rollback.\n\n**This write is unguarded.** No `_revision` is accepted on an item or returned on an entry;\nan editing screen that needs a guard re-reads the one version it is about to write through\nits own `GET`.\n\nThree refusals a client would otherwise expect do not occur here. `VERSION_CONFLICT` never\ndoes: an existing `valid_from` is a replacement rather than a collision. A tuple-uniqueness\nguard lost to a concurrent writer is not reported as `TUPLE_CONFLICT` either — the item is\nre-read against current state and re-derived through the same outcome order above, which is\ncontent-aware. `WRITE_CONFLICT` marks the case that is genuinely worth retrying: transient\ncontention on one entity's rows.\n\n**Published ahead of the behaviour.** No handler serves this yet, so a deployed stage answers\n`501`. The examples below are what an importer builds against in the meantime.\n",
+        "description": "Writes up to 100 variants or versions in one call. Each item names its own entity, so one\ncall can span a tariff hierarchy, and addresses a variant by condition tuple rather than by\nid — the id it created or found is on the result entry.\n\nEach item's outcome is derived from what is stored: an unknown tuple is `variant_created`, a\nknown tuple with no version at the item's `valid_from` is `version_created`, an existing\nversion there is `updated`, and a write matching what is stored is `skipped`. An item\nwithout `valid_from` is a last-write-wins write with no `skipped` detection.\n\nItems addressing the same `(entity_id, conditions)` apply in array order; the rest run in\nparallel. No cross-item rollback, and no `_revision` guard.\n",
         "operationId": "$batchUpsertConditionalVariants",
         "summary": "$batchUpsertConditionalVariants",
         "tags": [
@@ -5164,7 +5320,7 @@
         },
         "responses": {
           "200": {
-            "description": "What every item did, in request order, and a count per outcome.\n\n`200` whatever the per-item outcomes: a batch that processed 100 items and failed 99 did\nits job, and `counts` says what happened.\n",
+            "description": "What every item did, in request order, and a count per outcome. Always `200`, whatever\nthe per-item outcomes.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -5172,7 +5328,7 @@
                 },
                 "examples": {
                   "Every outcome once": {
-                    "summary": "The five items above, in order — the created variant's id is the one an order pins, and item five failed on its own without touching the rest",
+                    "summary": "The five items above, in order",
                     "value": {
                       "correlation_id": "tariff-refresh-2027-01",
                       "counts": {
@@ -5258,7 +5414,7 @@
             }
           },
           "400": {
-            "description": "The envelope cannot be processed at all: more than 100 items, an empty `items`, a slug\nthat names no conditional entity type, or a body this schema rejects outright.\n\nAll of those are request-validation failures, so they carry a message and neither `code`\nnor `details`. Every failure of an individual item is on that item's result entry\ninstead, `ENTITY_NOT_FOUND` included — the entity id is on the item and not in the path,\nso one wrong id in a source file cannot fail the other 99 rows. `ENTITY_TYPE_MISMATCH`\nand `ENTITY_NOT_CONDITIONAL` are per item for the same reason: each item names its own\nentity, and each entity is checked against the slug and for `is_conditional` on its own.\n",
+            "description": "The envelope cannot be processed: more than 100 items, an empty `items`, a slug that\nnames no conditional entity type, or a body this schema rejects. No `code` is carried —\nan individual item's failure is on its own result entry.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -5267,22 +5423,22 @@
               }
             }
           },
-          "404": {
-            "description": "No such schema (`SCHEMA_NOT_FOUND`) — the one lookup the whole call depends on, since it\nis what the items are validated against.\n",
+          "403": {
+            "description": "The token names no organization this API can act for",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ConditionalPricingError"
+                  "$ref": "#/components/schemas/Error"
                 }
               }
             }
           },
-          "501": {
-            "description": "Published ahead of the behaviour. This operation is declared and not yet dispatched, so\nevery request to it is answered here until the batch write behaviour lands — which is how\na deployed stage says \"this exists and does not work yet\" rather than answering with\ncounts a client would read as a completed import.\n\nRead `message`. The body is the shared `Error` shape, as it is on every 501 this API\nanswers, so one \"not built yet\" branch covers all of them.\n",
+          "404": {
+            "description": "`SCHEMA_NOT_FOUND`.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Error"
+                  "$ref": "#/components/schemas/ConditionalPricingError"
                 }
               }
             }
@@ -5292,7 +5448,7 @@
     },
     "/v1/conditional-pricing/{slug}/variants:batchDelete": {
       "post": {
-        "description": "Removes up to 100 variants or versions in one call — the symmetric bulk withdrawal, so\nretiring a generation of variants, or a scheduled adjustment across many of them, is as\ncheap as creating it was.\n\nThe noun is `variants` on both batch endpoints, although an item carrying `valid_from`\nremoves one **version** rather than the variant: an item without it removes the whole variant\n— its condition tuple, its registration in the index, and every version it accumulated — and\nan item with it removes exactly that version, under the single-item rules. A future version\nand a superseded one are both deletable and both answered with the warnings that say what\nmoved; a variant's last remaining version is refused\n(`LAST_VERSION_UNDELETABLE`), because such a variant would still hold its tuple and still\nresolve to nothing. Delete the variant instead.\n\n**An item addresses its variant one of two ways, and never both**: by `variant_id`, or by the\ncondition tuple it pins. Use ids once the schema has drifted: a tuple naming a condition the\nschema no longer declares cannot be canonicalized, so it addresses nothing. An item naming\nboth fails validation and is an envelope `400`, not a per-item error: the request validator\nrejects the body before any item runs.\n\n**`entity_id` is required beside a `variant_id`, and is not redundant.** A variant id alone\naddresses nothing in this API.\n\n**Items addressing the same variant apply in array order; items addressing different variants\nare processed in parallel.** Because an item addresses its variant two ways, \"the same\nvariant\" is decided after addressing, in three steps: every condition tuple is resolved to a\nvariant id, items are grouped by that id, and each group is applied in array order. So one\ncall may hold an item naming `var-46045` and an item naming the tuple that variant pins, and\nthe guarantee holds across both. There is no cross-item rollback.\n\n**An item that addresses nothing is `skipped` — but only when the variant or the version is\nwhat is missing.** A missing *entity* is a per-item `ENTITY_NOT_FOUND`.\n\nAn interrupted call is safe to send again. A whole-variant delete frees the tuple in its\nfirst phase and removes the version rows afterwards, so a re-run picks up where it stopped\nand reports `skipped` for what has already gone. Nothing is archived: a variant an order or\ncontract pins stops resolving, and a pinned `:resolve` naming it answers `VARIANT_NOT_FOUND`.\n\n**Published ahead of the behaviour.** No handler serves this yet, so a deployed stage answers\n`501`.\n",
+        "description": "Removes up to 100 variants or versions in one call. An item carrying `valid_from` removes\nthat version; one without it removes the whole variant.\n\nEach item addresses its variant by `variant_id` beside its `entity_id`, or by the condition\ntuple it pins, never both. Use ids once a condition has left the schema, since its tuple can\nno longer be canonicalized.\n\nItems addressing the same variant apply in array order, resolved to ids first; the rest run\nin parallel. An item addressing a missing variant or version is `skipped`, and the call is\nsafe to send again.\n",
         "operationId": "$batchDeleteConditionalVariants",
         "summary": "$batchDeleteConditionalVariants",
         "tags": [
@@ -5350,7 +5506,7 @@
         },
         "responses": {
           "200": {
-            "description": "What every item did, in request order, and a count per outcome.\n\n`200` whatever the per-item outcomes: the call did its job, and `counts` says what\nhappened.\n",
+            "description": "What every item did, in request order, and a count per outcome. Always `200`, whatever\nthe per-item outcomes.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -5358,7 +5514,7 @@
                 },
                 "examples": {
                   "Every outcome once": {
-                    "summary": "The three items above, in order — the second addressed a tuple no variant pins, so it names no variant to have skipped",
+                    "summary": "The three items above, in order — the second addressed a tuple no variant pins",
                     "value": {
                       "correlation_id": "postal-code-cleanup-2026-09",
                       "counts": {
@@ -5411,7 +5567,7 @@
             }
           },
           "400": {
-            "description": "The envelope cannot be processed at all: more than 100 items, an empty `items`, a slug\nthat names no conditional entity type, an item naming both a `variant_id` and a condition\ntuple, or a body this schema rejects outright.\n\nAll of those are request-validation failures, so they carry a message and neither `code`\nnor `details`. Every failure of an individual item is on that item's result entry\ninstead, `ENTITY_NOT_FOUND` included, along with the per-entity `ENTITY_TYPE_MISMATCH`\nand `ENTITY_NOT_CONDITIONAL` — each item names its own entity, so each is checked on its\nown.\n",
+            "description": "The envelope cannot be processed: more than 100 items, an empty `items`, a slug that\nnames no conditional entity type, an item naming both a `variant_id` and a condition\ntuple, or a body this schema rejects. No `code` is carried — an individual item's\nfailure is on its own result entry.\n",
             "content": {
               "application/json": {
                 "schema": {
@@ -5420,22 +5576,22 @@
               }
             }
           },
-          "404": {
-            "description": "No such schema (`SCHEMA_NOT_FOUND`) — the one lookup the whole call depends on.\n",
+          "403": {
+            "description": "The token names no organization this API can act for",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ConditionalPricingError"
+                  "$ref": "#/components/schemas/Error"
                 }
               }
             }
           },
-          "501": {
-            "description": "Published ahead of the behaviour. This operation is declared and not yet dispatched, so\nevery request to it is answered here until the batch delete behaviour lands — which is\nhow a deployed stage says \"this exists and does not work yet\" rather than answering with\ncounts a client would read as a completed cleanup.\n\nRead `message`. The body is the shared `Error` shape, as it is on every 501 this API\nanswers, so one \"not built yet\" branch covers all of them.\n",
+          "404": {
+            "description": "`SCHEMA_NOT_FOUND`.",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/Error"
+                  "$ref": "#/components/schemas/ConditionalPricingError"
                 }
               }
             }
@@ -5468,7 +5624,7 @@
       },
       "ConditionalEntitySlug": {
         "type": "string",
-        "description": "Schema slug of an entity type that can be conditional — the `{slug}` of every\nconditional-pricing route.\n",
+        "description": "Schema slug of an entity type that can be conditional — the `{slug}` of every conditional-pricing route.",
         "enum": [
           "product",
           "price",
@@ -5477,7 +5633,7 @@
       },
       "ConditionType": {
         "type": "string",
-        "description": "The kind of value a condition holds, which decides how a variant's pinned value is matched\nagainst a resolve context.\n\n- `string`: an arbitrary string, matched exactly and case-sensitively\n- `number`: a numeric value\n- `date`: a single date\n- `daterange`: a window with a from and an until timestamp; both ends may be left open\n- `boolean`: a true/false value\n- `select`: one of the values declared in `options`, which is always a closed vocabulary\n- `location`: a geographic value, shaped by `format`\n\nThere is no condition type for the fallback variant. Being the entity's fallback is a\nproperty of the variant, set by the `default` flag on a variant write, and needs nothing\ndeclared in the schema.\n",
+        "description": "The kind of value a condition holds, which decides how a pinned value is matched against a\nresolve context.\n\n- `string`: an arbitrary string, matched exactly and case-sensitively\n- `number`: a numeric value\n- `date`: a single date\n- `daterange`: a window with a from and an until timestamp; either end may be left open\n- `boolean`: a true/false value\n- `select`: one of the values declared in `options`, which is always a closed vocabulary\n- `location`: a geographic value, shaped by `format`\n",
         "enum": [
           "string",
           "number",
@@ -5490,7 +5646,7 @@
       },
       "ConditionDefinition": {
         "type": "object",
-        "description": "One condition dimension, in the shape a schema's `conditions` array holds it — copy it in\nverbatim.\n",
+        "description": "One condition dimension, in the shape a schema's `conditions` array holds it — copy it in verbatim.",
         "required": [
           "id",
           "name",
@@ -5501,12 +5657,12 @@
           "id": {
             "type": "string",
             "format": "uuid",
-            "description": "Stable identity of the condition, round-tripped unchanged for the lifetime of the\ncondition: it is what tells a rename apart from a remove plus an add. The Entity API\nmints none of its own, so whoever creates a condition supplies one — a catalog condition\narrives with the identity the catalog gives it, the same in every org, and is copied into\nthe schema along with the rest of the object.\n",
+            "description": "Stable identity of the condition, supplied on creation and round-tripped unchanged. A\ncatalog condition keeps the id the catalog gives it.\n",
             "example": "d5839b94-ba20-4225-a78e-76951d352bd6"
           },
           "name": {
             "type": "string",
-            "description": "How variants and resolve contexts refer to this condition. Independent of attribute\nnames: a value needed as an attribute too is duplicated onto the variant.\n\n`default`, and any name beginning with `_`, are reserved for the server: a condition\ndeclared under one is ignored, since nothing could pin it and no context could address it.\n",
+            "description": "How variants and resolve contexts refer to this condition, independent of attribute\nnames. `default` and names beginning with `_` are reserved and are ignored here.\n",
             "example": "postal_code"
           },
           "label": {
@@ -5519,7 +5675,7 @@
           },
           "options": {
             "type": "array",
-            "description": "The declared vocabulary of a `select` condition. Absent for every other type.\n\nThe same shape a `select` condition's `options` has on the Entity API, item for item: an\nentry is either the value itself or an object carrying that value and an optional display\n`title`. A `title` is never pinned by a variant and never matched — two entries differing\nonly in their title are one vocabulary entry.\n\nThe vocabulary is always closed: a condition carries no flag widening it, so a pinned\nvalue outside a declared vocabulary is rejected with `CONDITION_VALUE_INVALID`. A\nvocabulary that declares nothing is closed too — while `options` is absent or empty, or\nholds nothing this deploy can read, the condition admits no pin at all and the same code\nis returned with an empty `options`. It is *not* enforced on resolve — a vocabulary says\nwhat may be stored, not what may be asked for, so a context value outside it is a query\nthat simply matches nothing.\n",
+            "description": "The vocabulary of a `select` condition, absent for every other type. Each entry is the\nvalue itself or an object carrying that value and a display `title`, which is never\nmatched.\n\nAlways closed: a pinned value outside it is `CONDITION_VALUE_INVALID`, and while\n`options` is absent or empty the condition admits no pin at all. Not enforced on\nresolve, where a context value outside the vocabulary matches nothing.\n",
             "items": {
               "anyOf": [
                 {
@@ -5600,7 +5756,7 @@
         "properties": {
           "results": {
             "type": "array",
-            "description": "The condition sets built in for the requested entity type, in the order they are offered.\n",
+            "description": "The condition sets built in for the requested entity type, in the order they are offered.",
             "items": {
               "$ref": "#/components/schemas/ConditionSet"
             }
@@ -5609,7 +5765,7 @@
       },
       "ConditionalPricingErrorCode": {
         "type": "string",
-        "description": "Machine-readable failure mode of a conditional-pricing operation, allowing clients\nto branch on the kind of failure instead of parsing the error message.\n\n- `SCHEMA_NOT_FOUND` (404): no conditional entity type by that slug\n- `ENTITY_NOT_FOUND` (404): the schema holds no entity with that id\n- `ENTITY_TYPE_MISMATCH` (400): that id belongs to an entity of another type than the slug named\n- `ENTITY_NOT_CONDITIONAL` (400): the entity is of the right type but was not created as a conditional one\n- `VARIANT_NOT_FOUND` (404): the entity has no such variant\n- `VERSION_NOT_FOUND` (404): the variant has no version at that `valid_from`\n- `NO_MATCHES` (404): nothing applied to the context and the entity has no `default` variant\n- `NO_ACTIVE_VERSION` (404): the variant has no version in effect at the instant asked about\n- `AMBIGUOUS_RESOLUTION` (409): several variants match the given context while a single result was requested\n- `TUPLE_CONFLICT` (409): the condition tuple is already claimed by another variant\n- `VERSION_CONFLICT` (409): a version already exists at the given `valid_from` on that variant\n- `CONDITION_UNDEFINED` (400): a resolve context, a listing filter or a variant's pins name a condition the entity's schema does not define\n- `OPERATOR_UNSUPPORTED` (400): the requested operator is not applicable to the condition's type\n- `CONTEXT_FORMAT_INVALID` (400): a resolve context or listing filter value is malformed for its condition type\n- `CONDITION_VALUE_INVALID` (400): a variant write pins a `select` value the condition's `options` do not admit, including every pin on a condition whose `options` are absent, empty or unreadable\n- `TOO_MANY_MATCHES` (400): a multi-match resolve exceeded its result cap\n- `WRITE_CONFLICT` (409): transient write contention, retryable unlike `TUPLE_CONFLICT`\n- `OFFSET_WINDOW_EXCEEDED` (400): a listing's `from` plus `size` reaches past the offset window the search index allows\n- `CURSOR_INVALID` (400): a paging cursor cannot be read, or does not belong to the read it was sent with\n- `VARIANT_LIMIT_REACHED` (400): the entity already holds every variant it may hold\n- `PIN_FORMAT_INVALID` (400): a variant pins a value malformed for its condition's type\n- `VARIANT_UNPINNED` (400): a variant write pins no condition and is not marked `default`, or a batch delete item addresses no variant\n- `LAST_VERSION_UNDELETABLE` (400): the delete would leave the variant with no version at all\n\nIn a batch, the last four are the refusals an importer branches on: `VARIANT_LIMIT_REACHED`\nmeans stop the import, `PIN_FORMAT_INVALID` means one bad row, `LAST_VERSION_UNDELETABLE`\nmeans delete the variant instead.\n\nNot every refusal has a code. These carry a message and neither `code` nor `details`, and\neach operation's `400` names its own: a write pinning the reserved marker (`default` or\n`_default`), a variant marked `default` that also pins a real condition, a pin on a condition\nwhose declared type this deploy cannot read, an id this store cannot key by, a `valid_from`\nthis store cannot sort by, and a version write or delete with no `_revision`. Testing `code`\nfor absence is how a client tells them from the coded failures.\n\nFour of the 404s say that something the request addressed does not exist, and are fixed by\ncorrecting an id or accepting the thing is gone. The other two say the opposite: everything\naddressed exists and there is still nothing to serve — no variant applies to this situation,\nor none of a variant's versions is in effect yet. Those are ordinary business outcomes, told\napart from a wrong id by their code.\n\n`ENTITY_TYPE_MISMATCH` and `ENTITY_NOT_CONDITIONAL` are `400`s, not 404s: the entity the\nrequest addressed **was** found, and the fix is the slug beside it. A slug that names no\nconditional entity type at all is a `400` too.\n\nEach code is emitted with the HTTP status shown above, and only with that status, and each\none is pinned by a member of `ConditionalPricingError` — which is where the structured data\nthat code carries is declared.\n",
+        "description": "Machine-readable failure mode of a conditional-pricing operation, so a client can branch on\nthe kind of failure instead of parsing the message. A `400` is about the request; a `409` is\nabout what is already stored. Refusals raised by request validation carry no `code` at all.\n\n- `SCHEMA_NOT_FOUND` (404): no conditional entity type by that slug\n- `ENTITY_NOT_FOUND` (404): the schema holds no entity with that id\n- `ENTITY_TYPE_MISMATCH` (400): that id belongs to an entity of another type than the slug named\n- `ENTITY_NOT_CONDITIONAL` (409): the entity is of the right type but was not created as a conditional one\n- `VARIANT_NOT_FOUND` (404): the entity has no such variant\n- `VERSION_NOT_FOUND` (404): the variant has no version at that `valid_from`\n- `NO_MATCHES` (404): nothing applied to the context and the entity has no `default` variant\n- `NO_ACTIVE_VERSION` (404): the variant has no version in effect at the instant asked about\n- `AMBIGUOUS_RESOLUTION` (409): several variants match the given context while a single result was requested\n- `TUPLE_CONFLICT` (409): the condition tuple is already claimed by another variant\n- `VERSION_CONFLICT` (409): a version already exists at the given `valid_from` on that variant\n- `CONDITION_UNDEFINED` (400): the request names a condition the entity's schema does not define\n- `VARIANT_PIN_UNDECLARED` (409): a variant a resolve would compose pins a condition the entity's schema no longer declares\n- `OPERATOR_UNSUPPORTED` (400): the requested predicate, or a sort, is not applicable to the condition's type\n- `CONTEXT_FORMAT_INVALID` (400): a resolve context or listing filter value is malformed for its condition type\n- `CONDITION_VALUE_INVALID` (400): a variant write pins a `select` value absent from the condition's declared `options`\n- `CONDITION_UNCONFIGURED` (409): a variant write pins a `select` condition whose `options` are absent or empty\n- `TOO_MANY_MATCHES` (400): a multi-match resolve exceeded its result cap\n- `WRITE_CONFLICT` (409): transient write contention, retryable unlike `TUPLE_CONFLICT`\n- `OFFSET_WINDOW_EXCEEDED` (400): a listing's `from` plus `size` reaches past the offset window the search index allows\n- `CURSOR_INVALID` (400): a paging cursor cannot be read, or does not belong to the read it was sent with\n- `VARIANT_LIMIT_REACHED` (409): the entity already holds every variant it may hold\n- `PIN_FORMAT_INVALID` (400): a variant pins a value malformed for its condition's type\n- `VARIANT_UNPINNED` (400): a variant write pins no condition and is not marked `default`, or a batch delete item addresses no variant\n- `LAST_VERSION_UNDELETABLE` (409): the delete would leave the variant with no version at all\n- `CONDITION_UNREADABLE` (409): the entity's schema declares a condition in a way this deploy cannot read\n- `SORT_INVALID` (400): a listing's `sort` is not `conditions.<name>:asc` or `conditions.<name>:desc`\n- `DEFAULT_MARKER_RESERVED` (400): a variant write's pins, or a resolve context, address the fallback marker — `default` or `_default`\n- `DEFAULT_VARIANT_PINS_CONDITIONS` (400): a variant marked `default` also pins real conditions\n- `VALID_FROM_IMMUTABLE` (400): a version write asks for a different `valid_from` than the version its own address names\n- `VARIANT_CONDITIONS_IMMUTABLE` (409): a version write carries a condition tuple other than the one its variant was created with\n- `IDENTIFIER_INVALID` (400): an id in the request cannot be used as a storage key — empty, carrying an unsupported character, or longer than 128 characters\n- `VALID_FROM_INVALID` (400): a `valid_from` is not one of the timestamp forms a version timeline can be sorted by\n- `VALUE_UNSTORABLE` (400): a write carries a value the store cannot hold, such as a non-finite number or one outside the table's numeric range\n",
         "enum": [
           "SCHEMA_NOT_FOUND",
           "ENTITY_NOT_FOUND",
@@ -5623,9 +5779,11 @@
           "TUPLE_CONFLICT",
           "VERSION_CONFLICT",
           "CONDITION_UNDEFINED",
+          "VARIANT_PIN_UNDECLARED",
           "OPERATOR_UNSUPPORTED",
           "CONTEXT_FORMAT_INVALID",
           "CONDITION_VALUE_INVALID",
+          "CONDITION_UNCONFIGURED",
           "TOO_MANY_MATCHES",
           "WRITE_CONFLICT",
           "OFFSET_WINDOW_EXCEEDED",
@@ -5633,11 +5791,20 @@
           "VARIANT_LIMIT_REACHED",
           "PIN_FORMAT_INVALID",
           "VARIANT_UNPINNED",
-          "LAST_VERSION_UNDELETABLE"
+          "LAST_VERSION_UNDELETABLE",
+          "CONDITION_UNREADABLE",
+          "SORT_INVALID",
+          "DEFAULT_MARKER_RESERVED",
+          "DEFAULT_VARIANT_PINS_CONDITIONS",
+          "VALID_FROM_IMMUTABLE",
+          "VARIANT_CONDITIONS_IMMUTABLE",
+          "IDENTIFIER_INVALID",
+          "VALID_FROM_INVALID",
+          "VALUE_UNSTORABLE"
         ]
       },
       "ResolveConditionalEntityRequest": {
-        "description": "A resolve names one conditional entity, then says which of its variants it means — one of two\nways, and never both. `context` describes a situation and asks which variants apply to it;\n`variant_id` names one variant and skips matching entirely.\n\nA body carrying both, or neither, is a validation `400`. Asking for the default variant\nwithout knowing its id is `context: {}`, which matches nothing and therefore falls back to it.\n\nEverything below the variant selection is the same on both branches, `as_of` included.\n",
+        "description": "A resolve names one conditional entity and selects its variants either by `context` or by\n`variant_id`, never both. `context: {}` matches nothing and so returns the `default`\nvariant, which is how to ask for it without knowing its id.\n",
         "oneOf": [
           {
             "$ref": "#/components/schemas/ResolveByContextRequest"
@@ -5670,7 +5837,7 @@
           },
           "as_of": {
             "type": "string",
-            "description": "The instant the version is selected at — the version with the latest `valid_from` at or\nbefore it. Defaults to now. A variant whose first version is later than this is\nscheduled rather than applicable, and is excluded from resolution entirely.\n\nThat exclusion belongs to context matching only: a set of results may quietly drop a\nmember, where a pin naming one variant cannot answer with silence and is told\n`NO_ACTIVE_VERSION` instead.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision.\n",
+            "description": "The instant the version is selected at — the version with the latest `valid_from` at or\nbefore it. Defaults to now. A variant whose first version is later is excluded from\nmatching; a pin naming one is answered `NO_ACTIVE_VERSION` instead.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time, to at most\nmillisecond precision.\n",
             "example": "2027-03-15T00:00:00Z"
           },
           "options": {
@@ -5681,7 +5848,7 @@
       "ResolveByPinRequest": {
         "type": "object",
         "additionalProperties": false,
-        "description": "Resolve by naming a variant: compose this one, whatever a context would have matched. What an\norder needs to show the numbers a customer agreed to, and what a contract needs to show what\nis billable now — the two differ only in whether `as_of` is supplied.\n",
+        "description": "Resolve by naming a variant: compose this one, whatever a context would have matched.",
         "required": [
           "schema",
           "entity_id",
@@ -5698,12 +5865,12 @@
           },
           "variant_id": {
             "type": "string",
-            "description": "The variant to compose. Condition matching is skipped entirely: no `context` is read, the\n`default` fallback does not apply, and `results` carries exactly one entry — a pin asks\nfor one variant by name.\n\nA `variant_id` this entity has no variant under is `VARIANT_NOT_FOUND`, and so is one\nnaming a variant of a different entity: a variant id alone addresses nothing.\n`SCHEMA_NOT_FOUND` and `ENTITY_NOT_FOUND` are still answered ahead of both.\n\n**Published ahead of the behaviour.** Until the pinned path is built, a body carrying\nthis field is answered `501`, ahead of every check above — the field exists so consumers\ncan build against it, and declining it is how a deployed stage says so rather than\nquietly returning the `default` variant.\n",
+            "description": "The variant to compose. Condition matching is skipped, the `default` fallback does not\napply, and `results` carries exactly one entry. A variant of another entity is\n`VARIANT_NOT_FOUND`.\n",
             "example": "var-46045"
           },
           "as_of": {
             "type": "string",
-            "description": "The instant the version is selected at — the version with the latest `valid_from` at or\nbefore it. Defaults to now. The same selector, by the same rule, as on a context resolve:\nhow the variant was chosen is orthogonal to which of its versions applies, so a caller\nreplaying a recorded resolution instant supplies it here.\n\nA pinned variant whose first version is later than this is `NO_ACTIVE_VERSION`, carrying\nthe instant in `details.as_of`, rather than being dropped the way context matching drops\na scheduled variant.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision.\n",
+            "description": "The instant the version is selected at — the version with the latest `valid_from` at or\nbefore it. Defaults to now. A pinned variant whose first version is later is\n`NO_ACTIVE_VERSION`, carrying the instant in `details.as_of`.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time, to at most\nmillisecond precision.\n",
             "example": "2027-03-15T00:00:00Z"
           },
           "options": {
@@ -5714,7 +5881,7 @@
       "ResolveContext": {
         "type": "object",
         "additionalProperties": true,
-        "description": "The situation to resolve for: a flat map keyed by condition name, as the entity's schema\ndeclares them. A condition left out of the map is not a wildcard — it matches only variants\nthat leave that condition unpinned.\n\nEach value is either an exact value, typed by its condition, or a single-operator predicate\nobject:\n\n- `{ \"lt\": v }`, `{ \"lte\": v }`, `{ \"gt\": v }`, `{ \"gte\": v }` — order against a `number` or\n  `date` condition.\n- `{ \"in\": [...] }` — membership, against a `string`, `select` or `number` condition.\n- `{ \"between\": \"2026-03-01\" }` — the explicit spelling of `daterange` containment; a plain\n  date supplied for a `daterange` condition means the same thing.\n- `{ \"exists\": true }` — pinned to any value. `{ \"exists\": false }` says what leaving the key\n  out says.\n\nAn `in` list carries at most 50,000 values; a longer one is `CONTEXT_FORMAT_INVALID`. To match\na condition whatever its value, send `{ \"exists\": true }` rather than enumerating its\nvocabulary.\n\nExact values are typed by their condition: a `string` or `select` matches exactly and\ncase-sensitively, with no trimming; a `location` of format `zipcode` is the postal code\nitself, and one of format `zipcode_town` an object carrying both, whose town is compared\ncase- and whitespace-insensitively while its postal code is not.\n\n`default`, and any name beginning with `_`, are reserved for the server and cannot be\nsupplied here.\n\nAn empty map is valid and means what it says: it supplies no value, so it matches no variant\nthat pins a condition, and the entity's `default` variant is what comes back. It is the only way to\nask for the default variant without knowing its id.\n",
+        "description": "The situation to resolve for: a flat map keyed by condition name. A condition left out\nmatches only variants that leave it unpinned; an empty map therefore returns the `default`\nvariant.\n\nEach value is an exact value, typed by its condition, or a single-operator predicate:\n\n- `{ \"lt\": v }`, `{ \"lte\": v }`, `{ \"gt\": v }`, `{ \"gte\": v }` — order, against a `number`\n  or `date` condition\n- `{ \"in\": [...] }` — membership, against a `string`, `select` or `number` condition\n- `{ \"between\": \"2026-03-01\" }` — `daterange` containment, which a plain date also means\n- `{ \"exists\": true }` — pinned to any value; `{ \"exists\": false }` — left unpinned\n\nAn `in` list carries at most 50,000 values. A `string` or `select` matches exactly and\ncase-sensitively. A `location` of format\n`zipcode` is the postal code itself; one of format `zipcode_town` is an object carrying\nboth, whose town is compared case- and whitespace-insensitively.\n\n`default` and names beginning with `_` are reserved and cannot be supplied.\n",
         "example": {
           "postal_code": "46045",
           "consumption": {
@@ -5730,24 +5897,24 @@
           "resolve_one": {
             "type": "boolean",
             "default": false,
-            "description": "Ask for an unambiguous answer. Several applicable variants become `AMBIGUOUS_RESOLUTION`\nrather than a set, and nothing applicable becomes `NO_MATCHES` rather than an empty one.\nThe response shape does not change: `results` simply carries exactly one entry.\n"
+            "description": "Ask for an unambiguous answer: several applicable variants become\n`AMBIGUOUS_RESOLUTION`, and none becomes `NO_MATCHES`.\n"
           },
           "hydrate": {
             "type": "boolean",
             "default": false,
-            "description": "Return the entities a relation attribute references in place of the references\nthemselves, one level deep, exactly as an entity read with hydration does.\n\nA fetch, not a second resolution: a referenced entity comes back as it is read, and one\nthat is itself conditional carries its own flag — acting on that is the consumer's\nchoice, and this API does not resolve it on their behalf.\n\nApplied after composition, so a relation attribute whose value this variant's version\nreplaced is hydrated too. That is what makes a composite price work: the override\nreferences different component *entities*, which exist only in the composed payload.\n\nA reference that cannot be fetched comes back exactly as entity hydration returns it —\nno drop, no failure, and no field reporting it. A resolved payload behaves as an entity\nof the same shape would, and the discriminators are the only difference.\n\nCosts one fetch per referenced entity per result, and carries no cap of its own: the\nper-attribute limits are entity hydration's, and the 100-result cap on the resolve itself\nis unchanged.\n\n**Published ahead of the behaviour.** Until hydration is built, `true` is answered `501`\nrather than served as unhydrated references; `false`, which asks for what this path\nalready does, resolves normally.\n"
+            "description": "Return the entities a relation attribute references in place of the references, one\nlevel deep, as an entity read with hydration does. Applied after composition, so a\nrelation this variant's version replaced is hydrated too.\n\nA referenced entity that is itself conditional is returned unresolved, carrying its own\nflag. Costs one fetch per distinct referenced entity, with no per-attribute limit.\n"
           }
         }
       },
       "PinnedResolveOptions": {
         "type": "object",
         "additionalProperties": false,
-        "description": "The options a pinned resolve accepts — `hydrate` and nothing else. `resolve_one` has nothing\nto change on this branch, where the answer is exactly one result or a 404, so a body sending\nit is a validation `400`. `hydrate` means what `ResolveOptions.hydrate` means.\n",
+        "description": "The options a pinned resolve accepts — `hydrate` and nothing else. `resolve_one` has nothing\nto change where the answer is one result or a 404, so a body sending it is a `400`.\n",
         "properties": {
           "hydrate": {
             "type": "boolean",
             "default": false,
-            "description": "Return the entities a relation attribute references in place of the references\nthemselves, one level deep, exactly as an entity read with hydration does.\n\nA fetch, not a second resolution: a referenced entity comes back as it is read, and one\nthat is itself conditional carries its own flag — acting on that is the consumer's\nchoice, and this API does not resolve it on their behalf.\n\nApplied after composition, so a relation attribute whose value this variant's version\nreplaced is hydrated too. That is what makes a composite price work: the override\nreferences different component *entities*, which exist only in the composed payload.\n\nA reference that cannot be fetched comes back exactly as entity hydration returns it —\nno drop, no failure, and no field reporting it. A resolved payload behaves as an entity\nof the same shape would, and the discriminators are the only difference.\n\nCosts one fetch per referenced entity per result, and carries no cap of its own: the\nper-attribute limits are entity hydration's, and the 100-result cap on the resolve itself\nis unchanged.\n\n**Published ahead of the behaviour.** Until hydration is built, `true` is answered `501`\nrather than served as unhydrated references; `false`, which asks for what this path\nalready does, resolves normally.\n"
+            "description": "Return the entities a relation attribute references in place of the references, one\nlevel deep, as an entity read with hydration does. Applied after composition, so a\nrelation this variant's version replaced is hydrated too.\n\nA referenced entity that is itself conditional is returned unresolved, carrying its own\nflag. Costs one fetch per distinct referenced entity, with no per-attribute limit.\n"
           }
         }
       },
@@ -5759,7 +5926,7 @@
         "properties": {
           "results": {
             "type": "array",
-            "description": "One composed payload per applicable variant, capped at 100 — a context selecting more\nthan that is answered with `TOO_MANY_MATCHES` instead. No dominance or specificity\nordering is applied between them.\n",
+            "description": "One composed payload per applicable variant, capped at 100 — a context selecting more is\n`TOO_MANY_MATCHES`. Unordered.\n",
             "items": {
               "$ref": "#/components/schemas/ResolvedVariant"
             }
@@ -5769,7 +5936,7 @@
       "ResolvedVariant": {
         "type": "object",
         "additionalProperties": true,
-        "description": "The entity as this variant leaves it — every attribute of a plain entity read, with the\napplicable version's overrides applied — plus the discriminators saying where the numbers\ncame from.\n\nWith `options.hydrate`, a relation attribute holds the entities it references rather than the\nreferences themselves. That changes what an attribute holds, not the payload's shape, so\nnothing is declared here for it.\n",
+        "description": "The entity as this variant leaves it — every attribute of a plain entity read with the\napplicable version's overrides applied — plus the discriminators below.\n",
         "required": [
           "_id",
           "_variant_id",
@@ -5780,12 +5947,12 @@
         "properties": {
           "_id": {
             "type": "string",
-            "description": "The logical entity's id — the same one a plain entity read returns. Resolution never\nmints a new identity; a variant is a set of values for *this* entity, not another one.\n",
+            "description": "The logical entity's id, the same one a plain entity read returns.",
             "example": "price-sp26d1yo"
           },
           "_variant_id": {
             "type": "string",
-            "description": "The variant these values came from. Durable: this is what an order or a contract pins to\nread the same numbers back later.\n",
+            "description": "The variant these values came from — what an order or contract pins.",
             "example": "var-46045"
           },
           "_version_valid_from": {
@@ -5799,11 +5966,11 @@
                 "$ref": "#/components/schemas/VariantConditions"
               }
             ],
-            "description": "The conditions this variant pins, plus the boolean `default` discriminator.\n"
+            "description": "The conditions this variant pins, plus the boolean `default` discriminator."
           },
           "_inert_overrides": {
             "type": "array",
-            "description": "The variant's stored overrides this payload did not apply, and why. Always present, and\nempty in the ordinary case — a client reads its length rather than branching on its\nabsence, the same way it reads a write's `warnings`.\n\nComputed per read from the schema as it stands, never stored, so granting or withdrawing\n`overridable_attribute` changes what resolves — and this list — without any data being\nrewritten. A version read reports what is stored and carries no such list; this is the\nonly surface that honours the schema.\n",
+            "description": "The variant's stored overrides this payload did not apply, and why. Always present, and\nempty in the ordinary case. Computed per read against the schema as it stands, so\ngranting or withdrawing `overridable_attribute` changes it without any data being\nrewritten.\n",
             "items": {
               "$ref": "#/components/schemas/InertOverride"
             }
@@ -5823,11 +5990,11 @@
           "default": {
             "type": "boolean",
             "default": false,
-            "description": "Mark this variant as the entity's fallback: the one served when no other variant applies.\n\nA property of the variant, never an entry in `conditions`. A default variant cannot pin\nanything else, and an entity can have at most one; a second is refused as\n`TUPLE_CONFLICT`.\n\nAvailable to every conditional entity: nothing has to be declared in the schema first.\n"
+            "description": "Mark this variant as the entity's fallback, served when no other variant applies. It can\npin nothing else, and an entity may have one; a second is `TUPLE_CONFLICT`. Available to\nevery conditional entity without anything being declared in the schema.\n"
           },
           "valid_from": {
             "type": "string",
-            "description": "When the first version takes effect. Defaults to now.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision.\n",
+            "description": "When the first version takes effect. Defaults to now. An RFC 3339 date (`2026-01-01`,\nread as midnight UTC) or date-time, to at most millisecond precision.\n",
             "example": "2027-01-01T00:00:00Z"
           },
           "values": {
@@ -5841,7 +6008,7 @@
         "required": [
           "default"
         ],
-        "description": "A variant's pinned conditions as a reader sees them: the pins the schema declares, plus a\nboolean `default` saying whether this is the entity's fallback.\n\n`default` is always present and always a boolean, so a client can branch on \"did I get the\nfallback?\" without knowing how one is stored. The reserved condition a fallback is actually\npinned under never appears here.\n",
+        "description": "A variant's pinned conditions as a reader sees them: the pins the schema declares, plus a\nboolean `default` saying whether this is the entity's fallback.\n",
         "properties": {
           "default": {
             "type": "boolean"
@@ -5855,7 +6022,7 @@
       "PinnedConditions": {
         "type": "object",
         "additionalProperties": true,
-        "description": "The situation this variant applies to: a flat map keyed by condition name, as the entity's\nschema declares them. A condition left out is a wildcard — the variant applies whatever the\ncontext says for it, which is what makes adding a condition to a schema non-breaking for the\nvariants that already exist.\n\nExact values only. A predicate is a read-side thing — a resolve context or a listing's\ncondition filter — and is never stored: what a variant applies to is one situation, not a\nrange of them.\n\nValues are typed by their condition and stored canonicalized for that type: a `date` becomes\nmillisecond-precision UTC, a `daterange` an object carrying `from` and `until` where an empty\nstring is an open end, a `location` of format `zipcode` the postal code itself and one of\nformat `zipcode_town` an object carrying both. A `select` value must be a string, and must\nbe one the condition's `options` declare, which is always a closed vocabulary.\n\n`default`, and any name beginning with `_`, are reserved for the server and cannot be pinned\nhere. Whether a variant is the entity's fallback is set through the request's `default` flag.\n",
+        "description": "The situation this variant applies to: a flat map keyed by condition name. A condition left\nout is a wildcard, which is what makes adding a condition to a schema non-breaking for\nexisting variants.\n\nExact values only; predicates belong to reads. Values are stored canonicalized for their\ntype: a `date` becomes millisecond-precision UTC, a `daterange` an object carrying `from`\nand `until` where an empty string is an open end, a `location` of format `zipcode` the\npostal code itself and one of format `zipcode_town` an object carrying both.\n\n`default` and names beginning with `_` are reserved; use the request's `default` flag.\n",
         "example": {
           "postal_code": "46045"
         }
@@ -5863,7 +6030,7 @@
       "VariantValues": {
         "type": "object",
         "additionalProperties": true,
-        "description": "The attribute values this version overrides on the base entity, keyed by attribute name.\n\nOnly attributes currently declaring `overridable_attribute` are applied. Metadata fields\n(anything underscore-prefixed), readonly attributes, hidden attributes, computed attributes,\nattributes of a type no variant may override and non-overridable attributes present here are\nnot applied rather than rejected, and every one but the metadata is named in the write's\n`warnings`, so a client working from a slightly stale schema snapshot still succeeds instead\nof failing on fields it could not have known to drop, and still learns which of them did not\nland. Metadata is never named, since a client echoing back a payload it read carries it in\nevery body. An attribute's `render_condition` says when to show it and has no\nbearing on whether a variant may override it.\n\nNot applied means *not updated*, never *removed*: a value already stored for an attribute that\nis not currently overridable is preserved, so removing and restoring the flag deactivates and\nthen reactivates the same override. An append seeds the attributes the variant may not\noverride from the version in effect at its own `valid_from`, so its stored values are not a\npure function of the body that wrote it; a variant's first version, and an append dated before\nthe variant's earliest version, inherit nothing.\n\nA composite price's `price_components` is an ordinary overridable relation attribute. A\ncomposite variant's override references different component *entities*, never a variant or a\nversion of one, and holds whatever a relation attribute ordinarily holds — this API defines no\nreference shape of its own.\n",
+        "description": "The values this version overrides on the base entity, keyed by entity field name.\n\nA field is overridable if its attribute declares `overridable_attribute` — which readonly,\nhidden, computed and metadata fields, and types no variant may override, cannot be given —\nor if a capability declaring `overridable_attribute` names it in `managed_fields`, which\nexcludes only readonly and metadata fields.\n\nFields that are not overridable are reported in the write's `warnings` rather than rejected,\nand keep whatever value they already had. An append seeds them from the version in effect at\nits own `valid_from`.\n\nA composite price's `price_components` is an ordinary overridable relation attribute,\nreferencing component entities rather than variants or versions.\n",
         "example": {
           "unit_amount": 2499,
           "unit_amount_decimal": "24.99"
@@ -5886,7 +6053,7 @@
         "properties": {
           "variant_id": {
             "type": "string",
-            "description": "Server-generated, always, and never accepted from a client. This is the durable key orders\nand contracts pin.\n",
+            "description": "Server-generated. The durable key orders and contracts pin.",
             "example": "var-46045"
           },
           "entity_id": {
@@ -5902,7 +6069,7 @@
                 "$ref": "#/components/schemas/VariantConditions"
               }
             ],
-            "description": "The situation this variant applies to, plus the boolean `default` discriminator — the\nsame shape `_conditions` has on a resolved payload.\n"
+            "description": "The situation this variant applies to, plus the boolean `default` discriminator."
           },
           "valid_from": {
             "type": "string",
@@ -5924,12 +6091,12 @@
           },
           "_revision": {
             "type": "number",
-            "description": "The revision a later write to this version must carry to be accepted.\n",
+            "description": "The revision a later write to this version must carry.",
             "readOnly": true
           },
           "warnings": {
             "type": "array",
-            "description": "Things worth knowing that did not stop the write. Empty in the ordinary case — a client\nreads its length rather than branching on its absence.\n",
+            "description": "Things worth knowing that did not stop the write. Always present, and empty in the ordinary case.",
             "items": {
               "$ref": "#/components/schemas/WriteWarning"
             }
@@ -5937,12 +6104,12 @@
         }
       },
       "WriteWarning": {
-        "description": "Something worth knowing that did not stop a write.\n\nOne vocabulary for every write, so a client branches on what happened rather than on which\nendpoint it called. `code` and `message` are the only two fields every code shares; everything\nelse lives in a `details` object typed per code, so narrowing on `code` yields a payload the\nclient can read rather than an untyped bag. A write raises each code at most once, and in the\nordinary case raises none of them.\n",
+        "description": "Something worth knowing that did not stop a write. One vocabulary for every write; `details`\nis typed per `code`, and a write raises each code at most once.\n",
         "oneOf": [
           {
             "type": "object",
             "additionalProperties": false,
-            "description": "This entity is nearing the number of variants it may hold. Surfaced rather than rejected,\nso an importer finds out with a whole run's notice instead of discovering the limit\nhalfway through a refresh.\n",
+            "description": "This entity is nearing the number of variants it may hold.",
             "required": [
               "code",
               "message",
@@ -5972,7 +6139,7 @@
                   },
                   "cap": {
                     "type": "number",
-                    "description": "Variants this entity may hold. Configurable per deploy, the same value for every\norganization on it.\n"
+                    "description": "Variants this entity may hold. Configurable per deploy."
                   }
                 }
               }
@@ -5981,7 +6148,7 @@
           {
             "type": "object",
             "additionalProperties": false,
-            "description": "What resolves **now** changed, other than by a newer version taking effect: the version in\neffect was written behind, or removed.\n",
+            "description": "What resolves now changed, other than by a newer version taking effect: the version in\neffect was written behind, or removed.\n",
             "required": [
               "code",
               "message",
@@ -6005,7 +6172,7 @@
           {
             "type": "object",
             "additionalProperties": false,
-            "description": "What a past-dated (`as_of`) read returns changed: the write landed on, or created, a\nversion dated in the past. The version in effect is one of those whenever its own date has\npassed, which is the ordinary case — it covers every instant from that date until now. A\nversion dated now or later covers no past instant and is not reported here.\n",
+            "description": "What a past-dated (`as_of`) read returns changed: the write landed on, or created, a\nversion dated in the past.\n",
             "required": [
               "code",
               "message",
@@ -6029,7 +6196,7 @@
           {
             "type": "object",
             "additionalProperties": false,
-            "description": "Attributes named in the request body that the write did not store, whatever the reason.\nThe write itself succeeded: an attribute a variant may not override is left alone rather\nthan making the whole call fail, so a client working from a slightly stale schema snapshot\nstill succeeds instead of failing on fields it could not have known to drop.\n\nOne entry per attribute, each with its own reason, so a client that only cares about typos\nfilters the entries by `reason` rather than branching on a second code.\n",
+            "description": "Attributes named in the request body that the write did not store, one entry each with\nits own reason. The write itself succeeded.\n",
             "required": [
               "code",
               "message",
@@ -6068,7 +6235,7 @@
       "VersionMoved": {
         "type": "object",
         "additionalProperties": false,
-        "description": "Which version a write moved, and which one was in effect while it did.\n",
+        "description": "Which version a write moved, and which one was in effect while it did.",
         "required": [
           "valid_from"
         ],
@@ -6080,7 +6247,7 @@
           },
           "active_valid_from": {
             "type": "string",
-            "description": "The version in effect when the write landed, before it did. Absent when the variant had\nnone — every version of it still scheduled.\n\nMay lag the variant's timeline by milliseconds, so a version written moments earlier may\nnot be named here. Advisory, like the warning carrying it: nothing branches on it except a\nhuman reading the message.\n",
+            "description": "The version in effect when the write landed, before it did. Absent when the variant had\nnone. Advisory, and may lag the timeline by milliseconds.\n",
             "example": "2026-01-01T00:00:00.000Z"
           }
         }
@@ -6088,7 +6255,7 @@
       "InertOverride": {
         "type": "object",
         "additionalProperties": false,
-        "description": "One override that did not apply, and why.\n\nThe same entry on both sides of the feature: a write reports the attributes in its body it did\nnot store, and a resolved payload reports the stored overrides composition did not apply. Those\nare the same fact observed at two moments, so a client learns one shape and reads it in both\nplaces.\n",
+        "description": "One override that did not apply, and why — reported by a write for the attributes in its\nbody, and by a resolved payload for the stored overrides composition passed over.\n",
         "required": [
           "attribute",
           "reason"
@@ -6106,7 +6273,7 @@
       },
       "InertOverrideReason": {
         "type": "string",
-        "description": "Why one override did not apply.\n\n- `ATTRIBUTE_NOT_OVERRIDABLE`: the entity's schema declares the attribute but has not granted\n  it `overridable_attribute`. Granting the flag is an ordinary schema edit, which makes this\n  the reason most often worth acting on.\n- `ATTRIBUTE_READONLY`: the attribute is declared readonly, and a readonly attribute cannot\n  be granted the flag.\n- `ATTRIBUTE_HIDDEN`: the attribute is declared hidden, and a hidden attribute cannot be\n  granted the flag.\n- `ATTRIBUTE_COMPUTED`: the attribute's value is derived (`type: computed` or\n  `computed: true`) rather than stored, so an override would be recomputed away.\n- `ATTRIBUTE_UNDECLARED`: the entity's schema declares no attribute of that name. On a write\n  that is usually a typo; on a resolved payload it is a stored override whose attribute has\n  since left the schema — a stored value outlives the flag being withdrawn, so it can outlive\n  its own attribute too. This API keeps no record of what a schema once declared, so it states\n  only the observable fact and does not distinguish the two.\n- `TYPE_NOT_OVERRIDABLE`: the attribute's type is not one a variant may override, whatever\n  the schema says about that particular attribute.\n- `CAPABILITY_NOT_OVERRIDABLE`: the attribute is contributed by a capability rather than\n  declared on the entity's schema. Published for completeness and not emitted in this version,\n  in which no capability attribute can be overridden at all.\n",
+        "description": "Why one override did not apply.\n\n- `ATTRIBUTE_NOT_OVERRIDABLE`: the schema declares the attribute without\n  `overridable_attribute`, which is an ordinary schema edit away\n- `ATTRIBUTE_READONLY`: the attribute is readonly, and cannot be granted the flag\n- `ATTRIBUTE_HIDDEN`: the attribute is hidden, and cannot be granted the flag\n- `ATTRIBUTE_COMPUTED`: the attribute's value is derived rather than stored\n- `ATTRIBUTE_UNDECLARED`: the schema declares no attribute of that name\n- `TYPE_NOT_OVERRIDABLE`: the attribute's type is not one a variant may override\n- `CAPABILITY_NOT_OVERRIDABLE`: the field is managed by a capability that does not declare\n  `overridable_attribute`\n",
         "enum": [
           "ATTRIBUTE_NOT_OVERRIDABLE",
           "ATTRIBUTE_READONLY",
@@ -6140,7 +6307,7 @@
           },
           "tuple_released": {
             "type": "boolean",
-            "description": "Whether this call is the one that freed the variant's combination of condition values.\n`false` where an earlier, interrupted attempt had already freed it — the delete still\nsucceeded, and the combination was already reusable.\n"
+            "description": "Whether this call freed the variant's combination of condition values. `false` where an\nearlier, interrupted attempt had already freed it.\n"
           },
           "versions_deleted": {
             "type": "number",
@@ -6150,7 +6317,7 @@
       },
       "VariantVersion": {
         "type": "object",
-        "description": "One version of one variant: the attribute overrides it carries, the instant it takes effect,\nand the variant it belongs to.\n\nThese are the version's **own** overrides, not the base entity overlaid with them — this is\nwhat an editing screen loads and saves, and what it edits is the overrides. Composing them onto\nthe entity is what `:resolve` answers.\n",
+        "description": "One version of one variant: the overrides it carries, the instant it takes effect, and the\nvariant it belongs to. These are the version's own overrides; `:resolve` composes them onto\nthe entity.\n",
         "required": [
           "variant_id",
           "entity_id",
@@ -6180,11 +6347,11 @@
                 "$ref": "#/components/schemas/VariantConditions"
               }
             ],
-            "description": "The situation the variant applies to, plus the boolean `default` discriminator. A property\nof the variant rather than of this version: every version of a variant carries the same\none, and no version write can change it.\n"
+            "description": "The situation the variant applies to, plus the boolean `default` discriminator. A\nproperty of the variant: every version carries the same one.\n"
           },
           "valid_from": {
             "type": "string",
-            "description": "When this version takes effect, canonicalized to millisecond-precision UTC. A version's\nidentity within its variant — it never moves.\n",
+            "description": "When this version takes effect, canonicalized to millisecond-precision UTC. Its identity\nwithin the variant.\n",
             "example": "2027-01-01T00:00:00.000Z"
           },
           "values": {
@@ -6202,14 +6369,14 @@
           },
           "_revision": {
             "type": "integer",
-            "description": "The revision a write to this version must carry to be accepted. Always current: every read\nthat returns one is strongly consistent, so it is never a marker a write would be refused\nfor having read too early.\n",
+            "description": "The revision a write to this version must carry. Read from a strongly consistent read.",
             "readOnly": true,
             "example": 3
           }
         }
       },
       "WrittenVariantVersion": {
-        "description": "A version as a write left it, together with anything the write moved.\n",
+        "description": "A version as a write left it, together with anything the write moved.",
         "allOf": [
           {
             "$ref": "#/components/schemas/VariantVersion"
@@ -6222,7 +6389,7 @@
             "properties": {
               "warnings": {
                 "type": "array",
-                "description": "What this write moved, and anything in the body it did not store. Empty in the\nordinary case — a client reads its length rather than branching on its absence.\n",
+                "description": "What this write moved, and anything in the body it did not store. Always present,\nand empty in the ordinary case.\n",
                 "items": {
                   "$ref": "#/components/schemas/WriteWarning"
                 }
@@ -6259,7 +6426,7 @@
           },
           "warnings": {
             "type": "array",
-            "description": "What the delete moved, if anything. Empty when a scheduled version was withdrawn — a\nclient reads its length rather than branching on its absence.\n",
+            "description": "What the delete moved. Always present, and empty when a scheduled version was withdrawn.",
             "items": {
               "$ref": "#/components/schemas/WriteWarning"
             }
@@ -6275,7 +6442,7 @@
         "properties": {
           "valid_from": {
             "type": "string",
-            "description": "When this version takes effect. Defaults to now.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision.\n\nA date in the past is accepted and answered with warnings, never refused. A date the\nvariant already has a version at is refused as `VERSION_CONFLICT`.\n\n**Omit this to mean \"now\"** — that is the only spelling of now that is reliably silent. A\ntimestamp taken from the caller's own clock is already some milliseconds old when the\nserver judges it, which makes it a backdate, however small, and it is answered with the\nwarnings a backdate earns.\n",
+            "description": "When this version takes effect. Omit it to mean now; a timestamp read from the caller's\nown clock is already a backdate by the time the server judges it, and earns a warning.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time, to at most\nmillisecond precision. A date in the past is accepted; one the variant already has a\nversion at is `VERSION_CONFLICT`.\n",
             "example": "2027-01-01T00:00:00Z"
           },
           "values": {
@@ -6284,7 +6451,7 @@
                 "$ref": "#/components/schemas/VariantValues"
               }
             ],
-            "description": "The attribute overrides this version carries. An append seeds the attributes the variant\nmay not override from the version in effect at this version's own `valid_from` and then\napplies these values over them, so the stored values are not a pure function of this\nbody. An append dated before the variant's earliest version inherits nothing.\n"
+            "description": "The overrides this version carries. Attributes the variant may not override are seeded\nfrom the version in effect at this version's own `valid_from`.\n"
           },
           "conditions": {
             "allOf": [
@@ -6292,7 +6459,7 @@
                 "$ref": "#/components/schemas/PinnedConditions"
               }
             ],
-            "description": "Optional, and never applied: a variant's conditions are fixed when it is created. Accepted\nonly so that a client building its body from the version it loaded is not forced to strip\nthem out, and refused when they describe a different situation from the stored one.\n"
+            "description": "Accepted only unchanged, so a client can send back the body it loaded. A variant's\nconditions are fixed when it is created.\n"
           }
         }
       },
@@ -6310,17 +6477,17 @@
                 "$ref": "#/components/schemas/VariantValues"
               }
             ],
-            "description": "The complete set of attribute overrides this version carries. An overridable attribute\nabsent from here stops being overridden.\n\nAttributes the variant may not override are not applied where this carries them, and\ntheir **stored value is kept rather than dropped**.\n"
+            "description": "The complete set of overrides this version carries. An overridable attribute absent from\nhere stops being overridden; one the variant may not override keeps its stored value.\n"
           },
           "_revision": {
             "type": "integer",
             "minimum": 1,
-            "description": "The revision marker read from the version being written. The write is refused with\n`WRITE_CONFLICT` if the version has been written since.\n",
+            "description": "The revision read from the version being written. Refused with `WRITE_CONFLICT` if the\nversion has been written since.\n",
             "example": 3
           },
           "valid_from": {
             "type": "string",
-            "description": "Optional, and never applied. Accepted when it names the version being addressed — so a\nclient building its body from what it loaded need not strip it out — and refused when it\nnames another: a version's `valid_from` is its identity, and moving it is an append and a\ndelete rather than an edit.\n"
+            "description": "Accepted only when it names the version being addressed. Moving a version is an append\nand a delete.\n"
           },
           "conditions": {
             "allOf": [
@@ -6328,7 +6495,7 @@
                 "$ref": "#/components/schemas/PinnedConditions"
               }
             ],
-            "description": "Optional, and never applied: a variant's conditions are fixed when it is created. Refused\nwhen they describe a different situation from the stored one.\n"
+            "description": "Accepted only unchanged. A variant's conditions are fixed when it is created."
           }
         }
       },
@@ -6346,17 +6513,17 @@
                 "$ref": "#/components/schemas/VariantValues"
               }
             ],
-            "description": "Only the attribute overrides to change. Everything not mentioned is left as stored.\n\n`null` is a value like any other here rather than a deletion; to stop overriding an\nattribute, send the complete snapshot without it through the replace operation.\n"
+            "description": "Only the overrides to change; everything not mentioned is left as stored. `null` sets a\nvalue rather than removing an override — use the replace operation to remove one.\n"
           },
           "_revision": {
             "type": "integer",
             "minimum": 1,
-            "description": "The revision marker read from the version being written. The write is refused with\n`WRITE_CONFLICT` if the version has been written since.\n",
+            "description": "The revision read from the version being written. Refused with `WRITE_CONFLICT` if the\nversion has been written since.\n",
             "example": 3
           },
           "valid_from": {
             "type": "string",
-            "description": "Optional, never applied, and refused when it names a version other than the one addressed."
+            "description": "Accepted only when it names the version being addressed."
           },
           "conditions": {
             "allOf": [
@@ -6364,43 +6531,43 @@
                 "$ref": "#/components/schemas/PinnedConditions"
               }
             ],
-            "description": "Optional, and never applied. A partial update that tries to change a pinned condition value\nis refused.\n"
+            "description": "Accepted only unchanged. A variant's conditions are fixed when it is created."
           }
         }
       },
       "ListVariantsRequest": {
         "type": "object",
         "additionalProperties": false,
-        "description": "How to narrow and page a variant listing. Every property is optional, so `{}` is a valid body\nand asks for the first ten variants of the entity in `variant_id` order — the body itself is\nrequired, and an omitted one is a request-validation `400` rather than an unnarrowed page.\n\n`conditions` and `search` narrow independently and a variant has to satisfy both.\n",
+        "description": "How to narrow and page a variant listing. Every property is optional, so `{}` asks for the\nfirst ten variants in `variant_id` order, but the body itself is required. `conditions` and\n`search` narrow independently and a variant must satisfy both.\n",
         "properties": {
           "conditions": {
             "$ref": "#/components/schemas/VariantConditionFilter"
           },
           "search": {
             "type": "string",
-            "description": "Free text matched against the variant's pinned values — how someone finds one postal code\namong 800,000.\n\nMatches `string`, `select` and `number` pins only. A `location` pin is stored as an array\nof its format's parts and a `daterange` pin as an object carrying `from` and `until`, so\nneither is text a user could have typed.\n",
+            "description": "Free text matched against the scalar pins — `string`, `select`, `number` and `date`.\n`location` and `daterange` pins are stored structured and are not matched.\n",
             "example": "460"
           },
           "sort": {
             "type": "string",
-            "description": "`conditions.<name>:asc` or `conditions.<name>:desc`, for a `string`, `select`, `number` or\n`date` pin. Anything else — another field, or a pin of another type — is a `400`.\n\n**`variant_id:asc` is appended by the server**, always, so the order is total: many\nvariants can pin one postal code, and without a tiebreaker a cursor would repeat or skip\nrows between pages. Asking for no sort is `variant_id:asc` alone.\n",
+            "description": "`conditions.<name>:asc` or `conditions.<name>:desc`, for a `string`, `select`, `number`\nor `date` pin. `variant_id:asc` is always appended, so the order is total.\n",
             "example": "conditions.postal_code:asc"
           },
           "from": {
             "type": "integer",
             "minimum": 0,
             "default": 0,
-            "description": "The offset to read from. Not read when a `cursor` is sent, which carries its own position.\n\nBounded by the search index's offset window, together with `size`: the window bounds the\nlast row a page may contain, so the final servable offset is the window minus the page\nsize. A page reaching past it is `OFFSET_WINDOW_EXCEEDED`, naming all three numbers,\nrather than a page clamped back inside it as entity listing does. The window is the\ndeploy's: read its size from the error, not from here.\n"
+            "description": "The offset to read from, ignored when a `cursor` is sent. Bounded together with `size`\nby the search index's offset window; a page reaching past it is\n`OFFSET_WINDOW_EXCEEDED`, which reports the window.\n"
           },
           "size": {
             "type": "integer",
             "minimum": 1,
             "default": 10,
-            "description": "Rows per page. Clamped silently at 1000, as entity listing's is.\n"
+            "description": "Rows per page. Clamped silently at 1000."
           },
           "cursor": {
             "type": "string",
-            "description": "Continue from a previous response's `next`, which is where a caller goes when the offset\nwindow runs out. Opaque: it encodes the position and the listing it was issued for, and\nnothing a client should read or construct.\n\n`conditions`, `search` and `sort` must be the ones the cursor was issued with — a cursor\nresumes one listing, and cannot mean anything against a different one. A cursor that is\nmalformed, or does not match the listing it is sent with, is a `400`.\n",
+            "description": "Continue from a previous response's `next`, which is where a caller goes when the offset\nwindow runs out. Opaque, and valid only with the `conditions`, `search` and `sort` it\nwas issued with.\n",
             "example": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0"
           }
         }
@@ -6408,41 +6575,41 @@
       "VariantTreeRequest": {
         "type": "object",
         "additionalProperties": false,
-        "description": "The variants list's request plus `as_of`, the instant each row's version is selected at.\n`size` is clamped at 100 here; every other shared property means what it means on the list.\n",
+        "description": "The variants list's request plus `as_of`, the instant each row's version is selected at.\n`size` is clamped at 100 here; every other property means what it means on the list.\n",
         "properties": {
           "conditions": {
             "$ref": "#/components/schemas/VariantConditionFilter"
           },
           "search": {
             "type": "string",
-            "description": "Free text matched against the variant's pinned values — how someone finds one postal code\namong 800,000.\n\nMatches `string`, `select` and `number` pins only. A `location` pin is stored as an array\nof its format's parts and a `daterange` pin as an object carrying `from` and `until`, so\nneither is text a user could have typed.\n",
+            "description": "Free text matched against the scalar pins — `string`, `select`, `number` and `date`.\n`location` and `daterange` pins are stored structured and are not matched.\n",
             "example": "460"
           },
           "sort": {
             "type": "string",
-            "description": "`conditions.<name>:asc` or `conditions.<name>:desc`, for a `string`, `select`, `number` or\n`date` pin. Anything else — another field, or a pin of another type — is a `400`.\n\n**`variant_id:asc` is appended by the server**, always, so the order is total: many\nvariants can pin one postal code, and without a tiebreaker a cursor would repeat or skip\nrows between pages. Asking for no sort is `variant_id:asc` alone.\n",
+            "description": "`conditions.<name>:asc` or `conditions.<name>:desc`, for a `string`, `select`, `number`\nor `date` pin. `variant_id:asc` is always appended, so the order is total.\n",
             "example": "conditions.postal_code:asc"
           },
           "from": {
             "type": "integer",
             "minimum": 0,
             "default": 0,
-            "description": "The offset to read from. Not read when a `cursor` is sent, which carries its own position.\n\nBounded by the search index's offset window, together with `size`: the window bounds the\nlast row a page may contain, so the final servable offset is the window minus the page\nsize. A page reaching past it is `OFFSET_WINDOW_EXCEEDED`, naming all three numbers,\nrather than a page clamped back inside it as entity listing does. The window is the\ndeploy's: read its size from the error, not from here.\n"
+            "description": "The offset to read from, ignored when a `cursor` is sent. Bounded together with `size`\nby the search index's offset window; a page reaching past it is\n`OFFSET_WINDOW_EXCEEDED`, which reports the window.\n"
           },
           "size": {
             "type": "integer",
             "minimum": 1,
             "default": 10,
-            "description": "Rows per page. Clamped silently at 100, a tenth of the variants list's cap: every row here\ncosts its own version lookup.\n"
+            "description": "Rows per page. Clamped silently at 100, since every row costs its own version lookup."
           },
           "cursor": {
             "type": "string",
-            "description": "Continue from a previous response's `next`, which is where a caller goes when the offset\nwindow runs out. Opaque: it encodes the position and the listing it was issued for, and\nnothing a client should read or construct.\n\n`conditions`, `search` and `sort` must be the ones the cursor was issued with — a cursor\nresumes one listing, and cannot mean anything against a different one. A cursor that is\nmalformed, or does not match the listing it is sent with, is a `400`.\n",
+            "description": "Continue from a previous response's `next`, which is where a caller goes when the offset\nwindow runs out. Opaque, and valid only with the `conditions`, `search` and `sort` it\nwas issued with.\n",
             "example": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0"
           },
           "as_of": {
             "type": "string",
-            "description": "The instant each row's version is selected at — the version with the latest `valid_from`\nat or before it. Defaults to now. The same selector, by the same rule, as `:resolve`'s.\n\nA variant whose first version is later than this is not dropped the way context matching\ndrops it: it is a row with `status: scheduled` carrying that upcoming first version, which\nis what makes a staged price visible on the editing screen.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision.\n",
+            "description": "The instant each row's version is selected at. Defaults to now. A variant whose first\nversion is later is a row with `status: scheduled` carrying that upcoming version.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time, to at most\nmillisecond precision.\n",
             "example": "2027-03-15T00:00:00Z"
           }
         }
@@ -6450,7 +6617,7 @@
       "VariantConditionFilter": {
         "type": "object",
         "additionalProperties": true,
-        "description": "Which pins a variant must carry to be listed: a flat map keyed by condition name, as the\nentity's schema declares them. A condition left out of the map is not filtered on at all.\n\nEach value is either an exact value, typed by its condition, or a single-operator predicate\nobject — the same seven a resolve context accepts, because in both cases a predicate is\napplied to the variant's *pinned* value, so nothing about matching moves:\n\n- `{ \"lt\": v }`, `{ \"lte\": v }`, `{ \"gt\": v }`, `{ \"gte\": v }` — order against a `number` or\n  `date` condition.\n- `{ \"in\": [...] }` — membership, against a `string`, `select` or `number` condition.\n- `{ \"between\": \"2026-03-01\" }` — the explicit spelling of `daterange` containment; a plain\n  date supplied for a `daterange` condition means the same thing.\n- `{ \"exists\": true }` — pinned to any value. `{ \"exists\": false }` — the condition left\n  unpinned.\n\nAn `in` list carries at most 50,000 values; a longer one is `CONTEXT_FORMAT_INVALID`. To\nfilter on a condition whatever its pinned value, send `{ \"exists\": true }` rather than\nenumerating its vocabulary.\n\n**A variant matches only where it pins the condition** — the one place a filter and a resolve\ncontext differ. On `:resolve` a condition a variant does not pin matches any value; here,\nasking for postal code 46045 does not return the variants that pin no postal code at all.\n`{ \"exists\": false }` is how those are asked for.\n\nValues are typed and canonicalized exactly as a resolve context's are, by the same code, so\none instant written two ways filters the same way either way. A condition the schema does not\ndeclare is `CONDITION_UNDEFINED`, a predicate its type does not support is\n`OPERATOR_UNSUPPORTED`, and a value malformed for its type is `CONTEXT_FORMAT_INVALID`.\n\n**`default` is accepted here**, as the exact boolean every row reports it as: `true` selects\nthe entity's fallback variant, `false` every variant that is not it.\n\nIt takes no predicate. `default` is not a condition and has no type, so ordering and\nmembership have nothing to apply to. It is also the one key the pinned-only rule above does\nnot describe literally: a variant that is not the fallback does not pin the marker to `false`,\nit does not pin it at all, so `false` selects the variants that leave it unpinned.\n\nNames beginning with `_` stay reserved for the server and cannot be filtered on — `_default`,\nthe marker a fallback is actually stored under, included. `default` is the spelling every read\nreports and the only one this accepts.\n",
+        "description": "Which pins a variant must carry to be listed: a flat map keyed by condition name, taking the\nsame exact values and predicates a resolve context does. A condition left out is not\nfiltered on. An `in` list carries at most 50,000 values.\n\nA variant matches only where it pins the condition — unlike `:resolve`, where an unpinned\ncondition matches any value. `{ \"exists\": false }` selects the variants that leave it\nunpinned.\n\n`default` is accepted as an exact boolean and takes no predicate: `true` selects the\nentity's fallback variant, `false` every variant that is not it. Names beginning with `_`\nare reserved.\n",
         "example": {
           "postal_code": "46045",
           "consumption": {
@@ -6467,7 +6634,7 @@
         "properties": {
           "hits": {
             "type": "integer",
-            "description": "How many variants match, exactly, at any depth — not how many this page carries. Exact,\nas entity listing's is.\n",
+            "description": "How many variants match in total, exactly — not how many this page carries.",
             "example": 8128
           },
           "results": {
@@ -6478,14 +6645,14 @@
           },
           "next": {
             "type": "string",
-            "description": "The cursor that continues this listing, absent on the last page. Send it back as `cursor`,\nwith the same filter, search and sort.\n",
+            "description": "The cursor that continues this listing, absent on the last page. Send it back as\n`cursor`, with the same filter, search and sort.\n",
             "example": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0"
           }
         }
       },
       "VariantListRow": {
         "type": "object",
-        "description": "One variant as a listing reports it: which variant it is and what it pins.\n\nNo `_revision` — a write re-reads its version through that version's own `GET` — and no\n`_inert_overrides`, since a listing reports what is stored and only `:resolve` honours the\nschema.\n",
+        "description": "One variant as a listing reports it: which variant it is and what it pins.",
         "required": [
           "variant_id",
           "entity_id",
@@ -6510,7 +6677,7 @@
                 "$ref": "#/components/schemas/VariantConditions"
               }
             ],
-            "description": "The situation this variant applies to, plus the boolean `default` discriminator — the same\nshape a variant write returns.\n\nMay lag: a variant just created can be missing from a page, and one just deleted can still\nbe on it. The pins shown for a variant are never stale, since a variant's conditions are\nimmutable after creation.\n"
+            "description": "The situation this variant applies to, plus the boolean `default` discriminator.\nMembership of a page may lag a write by moments; the pins themselves never do.\n"
           }
         }
       },
@@ -6523,26 +6690,26 @@
         "properties": {
           "hits": {
             "type": "integer",
-            "description": "How many variants match, exactly, at any depth — not how many this page carries. Exact,\nas entity listing's is.\n",
+            "description": "How many variants match in total, exactly — not how many this page carries.",
             "example": 8128
           },
           "results": {
             "type": "array",
-            "description": "One row per matching variant, in the requested order.\n\nA variant the index still holds but whose versions are already gone — a variant\nmid-delete — is **omitted** rather than returned without a `version`. So `results` can be\nshorter than `hits` implies, for the width of that lag and no longer. Paging still ends\nwhere `next` does.\n",
+            "description": "One row per matching variant, in the requested order. A variant mid-delete is omitted,\nso `results` can be shorter than `hits` implies.\n",
             "items": {
               "$ref": "#/components/schemas/VariantTreeRow"
             }
           },
           "next": {
             "type": "string",
-            "description": "The cursor that continues this listing, absent on the last page. Send it back as `cursor`,\nwith the same filter, search and sort.\n\n`as_of` is free to change between pages. It selects which version each row shows and has\nno bearing on which variants match or on the order they come back in, so a screen whose\ndate picker moves mid-listing keeps paging rather than starting over.\n",
+            "description": "The cursor that continues this listing, absent on the last page. Send it back as\n`cursor`, with the same filter, search and sort; `as_of` may change between pages.\n",
             "example": "eyJmcm9tIjoyNSwibGlzdGluZyI6IjNmOWMxZTJhIn0"
           }
         }
       },
       "VariantTreeRow": {
         "type": "object",
-        "description": "A listing row plus the one version the tree view shows for it, and the status saying which\nversion that is.\n",
+        "description": "A listing row plus the one version the tree shows for it, and the status saying which.",
         "required": [
           "variant_id",
           "entity_id",
@@ -6569,7 +6736,7 @@
                 "$ref": "#/components/schemas/VariantConditions"
               }
             ],
-            "description": "The situation this variant applies to, plus the boolean `default` discriminator — the same\nshape a variant write returns.\n\nMay lag: a variant just created can be missing from a page, and one just deleted can still\nbe on it. The pins shown for a variant are never stale, since a variant's conditions are\nimmutable after creation.\n"
+            "description": "The situation this variant applies to, plus the boolean `default` discriminator.\nMembership of a page may lag a write by moments; the pins themselves never do.\n"
           },
           "status": {
             "$ref": "#/components/schemas/VariantTreeRowStatus"
@@ -6580,13 +6747,13 @@
                 "$ref": "#/components/schemas/VariantVersionSnapshot"
               }
             ],
-            "description": "The version this row shows: the one in effect at `as_of`, or — where every version of the\nvariant is still ahead of it — that upcoming first one. `status` says which of the two it\nis.\n\nAlways present. A variant always has at least one version, and the one case where a row\ncould have none — a variant whose delete has removed its versions but not yet its index\ndocument — is omitted from `results` instead, so a consumer never reads this field\ndefensively.\n"
+            "description": "The version in effect at `as_of`, or the variant's upcoming first one where every\nversion is still ahead of it. `status` says which. Always present.\n"
           }
         }
       },
       "VariantTreeRowStatus": {
         "type": "string",
-        "description": "Whether a tree row's version is the one in effect at `as_of`, or one still ahead of it.\n\nExactly two values, and every row has one: a variant always has at least one version, so\neither a version is in effect at `as_of` or every version of that variant is still to come.\n\n- `active`: `version` is the version with the latest `valid_from` at or before `as_of` —\n  the same version `active_valid_from` and `NO_ACTIVE_VERSION` speak of.\n- `scheduled`: the variant's first version is later than `as_of`, and `version` is that\n  upcoming first version.\n",
+        "description": "Whether a tree row's version is the one in effect at `as_of`, or one still ahead of it.\n\n- `active`: the version with the latest `valid_from` at or before `as_of`\n- `scheduled`: the variant's first version, which is later than `as_of`\n",
         "enum": [
           "active",
           "scheduled"
@@ -6594,7 +6761,7 @@
       },
       "VariantVersionSnapshot": {
         "type": "object",
-        "description": "One version of one variant as a listing reports it: `VariantVersion` without `_revision`.\n\nThe revision is missing on purpose. An editing screen re-reads the one version it is about to\nwrite through that version's own `GET`, which is strongly consistent, and writes with the\nrevision it gets back.\n\nEverything else is `VariantVersion` field for field, including the variant's `conditions`,\nwhich every version of a variant repeats.\n",
+        "description": "One version of one variant as a listing reports it: `VariantVersion` without `_revision`.\nRead the version through its own `GET` to get the revision a write must carry.\n",
         "required": [
           "variant_id",
           "entity_id",
@@ -6623,11 +6790,11 @@
                 "$ref": "#/components/schemas/VariantConditions"
               }
             ],
-            "description": "The situation the variant applies to, plus the boolean `default` discriminator. A property\nof the variant rather than of this version: every version of a variant carries the same\none, and no version write can change it.\n"
+            "description": "The situation the variant applies to, plus the boolean `default` discriminator. A\nproperty of the variant: every version carries the same one.\n"
           },
           "valid_from": {
             "type": "string",
-            "description": "When this version takes effect, canonicalized to millisecond-precision UTC. A version's\nidentity within its variant — it never moves.\n",
+            "description": "When this version takes effect, canonicalized to millisecond-precision UTC. Its identity\nwithin the variant.\n",
             "example": "2027-01-01T00:00:00.000Z"
           },
           "values": {
@@ -6653,14 +6820,14 @@
         "properties": {
           "results": {
             "type": "array",
-            "description": "A page of the variant's timeline, in the requested `order`.\n",
+            "description": "A page of the variant's timeline, in the requested `order`.",
             "items": {
               "$ref": "#/components/schemas/VariantVersionSnapshot"
             }
           },
           "next": {
             "type": "string",
-            "description": "The cursor that continues this timeline, absent only on the last page.\n\nThe only end-of-data signal: a page shorter than `limit`, or an empty one, can still carry\na cursor, so a client pages until this field is absent rather than until a page looks\nshort. Send it back as `cursor`, against the same variant and the same `order`.\n",
+            "description": "The cursor that continues this timeline, absent only on the last page — the only\nend-of-data signal, since a short or empty page can still carry one. Send it back as\n`cursor`, against the same variant and `order`.\n",
             "example": "eyJzayI6IlYjcHJpY2Utc3AyNmQxeW8jdmFyLTQ2MDQ1IzIwMjYtMDEtMDFUMDA6MDA6MDAuMDAwWiIsIm9yZGVyIjoiYXNjIn0"
           }
         }
@@ -6668,21 +6835,21 @@
       "BatchUpsertVariantsRequest": {
         "type": "object",
         "additionalProperties": false,
-        "description": "A batch of variant writes under one schema, each item naming the entity it writes to.\n",
+        "description": "A batch of variant writes under one schema, each item naming the entity it writes to.",
         "required": [
           "items"
         ],
         "properties": {
           "correlation_id": {
             "type": "string",
-            "description": "An opaque string the caller uses to tie this response to the file and cycle that produced\nit. Echoed back verbatim, only when it was sent, and never interpreted.\n",
+            "description": "An opaque string echoed back verbatim when it was sent, and never interpreted.",
             "example": "tariff-refresh-2027-01"
           },
           "items": {
             "type": "array",
             "minItems": 1,
             "maxItems": 100,
-            "description": "The writes to apply, in the order they should apply where two of them address the same\nvariant. At most 100 per call — a limit on one request, distinct from the per-entity\nvariant cap, which limits stored state.\n",
+            "description": "The writes to apply, in the order they should apply where two of them address the same\nvariant. At most 100 per call, which is distinct from the per-entity variant cap.\n",
             "items": {
               "$ref": "#/components/schemas/BatchUpsertItem"
             }
@@ -6692,7 +6859,7 @@
       "BatchUpsertItem": {
         "type": "object",
         "additionalProperties": false,
-        "description": "One variant write: the entity it belongs to, the situation it applies to, and the values it\ncarries — the single-item create's body plus `entity_id`. The two differ on `conditions`: on\na create an existing tuple is `TUPLE_CONFLICT`, and here it is a version appended to the\nvariant already holding it.\n\nThere is no `variant_id`. An upsert creates variants that have no id yet.\n",
+        "description": "One variant write: the single-item create's body plus `entity_id`, and no `variant_id`. An\nexisting condition tuple appends a version to the variant holding it rather than conflicting.\n",
         "required": [
           "entity_id",
           "values"
@@ -6700,7 +6867,7 @@
         "properties": {
           "entity_id": {
             "type": "string",
-            "description": "The conditional entity this item writes to. On the item rather than in the path, so one\ncall can refresh a whole tariff hierarchy — a composite price and its components\ntogether.\n",
+            "description": "The conditional entity this item writes to.",
             "example": "price-sp26d1yo"
           },
           "conditions": {
@@ -6709,11 +6876,11 @@
           "default": {
             "type": "boolean",
             "default": false,
-            "description": "Mark this variant as the entity's fallback, exactly as a create does: a property of the\nvariant, never an entry in `conditions`. An item that pins nothing and is not the default\nis `VARIANT_UNPINNED` — the empty postal-code column in a source file.\n"
+            "description": "Mark this variant as the entity's fallback, as a create does. An item that pins nothing\nand is not the default is `VARIANT_UNPINNED`.\n"
           },
           "valid_from": {
             "type": "string",
-            "description": "When the version this item writes takes effect. Omitted, it is a current-state,\nlast-write-wins write with no `skipped` detection.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time\n(`2026-01-01T00:00:00Z`), to at most millisecond precision.\n\nA past instant is written like any other and answered with the timeline warnings on this\nitem, so an importer stamping one `valid_from` across a batch sees them on every item.\n",
+            "description": "When the version this item writes takes effect. Omitted, it is a last-write-wins write\nwith no `skipped` detection; a past instant is accepted and reported in this item's\n`warnings`.\n\nAn RFC 3339 date (`2026-01-01`, read as midnight UTC) or date-time, to at most\nmillisecond precision.\n",
             "example": "2027-01-01T00:00:00Z"
           },
           "values": {
@@ -6724,21 +6891,21 @@
       "BatchDeleteVariantsRequest": {
         "type": "object",
         "additionalProperties": false,
-        "description": "A batch of variant and version deletes under one schema, each item naming the entity it\nremoves from.\n",
+        "description": "A batch of variant and version deletes under one schema, each item naming the entity it removes from.",
         "required": [
           "items"
         ],
         "properties": {
           "correlation_id": {
             "type": "string",
-            "description": "An opaque string the caller uses to tie this response to the file and cycle that produced\nit. Echoed back verbatim, only when it was sent, and never interpreted.\n",
+            "description": "An opaque string echoed back verbatim when it was sent, and never interpreted.",
             "example": "postal-code-cleanup-2026-09"
           },
           "items": {
             "type": "array",
             "minItems": 1,
             "maxItems": 100,
-            "description": "The deletes to apply, in the order they should apply where two of them address the same\nvariant — which is decided after every condition tuple has been resolved to a variant id,\nso the order holds across the two addressing forms. At most 100 per call.\n",
+            "description": "The deletes to apply, in the order they should apply where two of them address the same\nvariant — decided after every condition tuple has been resolved to a variant id. At most\n100 per call.\n",
             "items": {
               "$ref": "#/components/schemas/BatchDeleteItem"
             }
@@ -6746,7 +6913,7 @@
         }
       },
       "BatchDeleteItem": {
-        "description": "One delete: the variant, addressed by id or by the condition tuple it pins, and optionally\nthe one version of it to remove.\n\nExactly one of the two forms. An item carrying both a `variant_id` and `conditions` matches\nneither branch and is an envelope `400`, since the request validator rejects the body before\nany item runs.\n",
+        "description": "One delete: the variant, addressed by id or by the condition tuple it pins, and optionally\nthe one version of it to remove. An item carrying both matches neither branch and is an\nenvelope `400`.\n",
         "oneOf": [
           {
             "$ref": "#/components/schemas/BatchDeleteByVariantId"
@@ -6759,7 +6926,7 @@
       "BatchDeleteByVariantId": {
         "type": "object",
         "additionalProperties": false,
-        "description": "A delete addressing its variant by id — the form a cleanup pass uses after the schema has\ndrifted, since a tuple naming a condition the schema no longer declares addresses nothing.\n",
+        "description": "A delete addressing its variant by id.",
         "required": [
           "entity_id",
           "variant_id"
@@ -6767,7 +6934,7 @@
         "properties": {
           "entity_id": {
             "type": "string",
-            "description": "The conditional entity the variant belongs to. **Required beside `variant_id`, and not\nredundant**: a variant id alone addresses nothing in this API.\n",
+            "description": "The conditional entity the variant belongs to. Required: a variant id alone addresses nothing.",
             "example": "price-sp26d1yo"
           },
           "variant_id": {
@@ -6777,7 +6944,7 @@
           },
           "valid_from": {
             "type": "string",
-            "description": "The one version to remove, by the instant it takes effect. Omitted, the whole variant\ngoes — its tuple, its index registration and every version it accumulated.\n\nAn RFC 3339 date or date-time, to at most millisecond precision, canonicalized before it\nis matched.\n",
+            "description": "The one version to remove, by the instant it takes effect. Omitted, the whole variant\ngoes. An RFC 3339 date or date-time, canonicalized before it is matched.\n",
             "example": "2027-01-01T00:00:00Z"
           }
         }
@@ -6785,14 +6952,14 @@
       "BatchDeleteByConditions": {
         "type": "object",
         "additionalProperties": false,
-        "description": "A delete addressing its variant by the situation it applies to — the form an importer uses\nwhen it knows the source rows rather than the ids they produced.\n\n`conditions` is optional because the entity's fallback variant pins nothing: an item\naddressing it sends `default: true` and no `conditions`, exactly as a create marks one.\n\n**An item that addresses no variant is a per-item `VARIANT_UNPINNED`, not an envelope\n`400` and not a `skipped`.** Three shapes reach it: no `conditions` and no `default`,\n`conditions: {}`, and `default: false` alone — an empty postal-code column in a source row,\nserialized one way or another.\n\nTwo more shapes validate here and are refused per item rather than described by the schema:\nan item marking `default` while also pinning `conditions` — a fallback variant applies only\nwhen nothing else does, so it cannot also pin — and an item carrying `valid_from` with no\nvariant addressed at all. Both carry a message and no code, as the create path refuses the\nfirst today.\n",
+        "description": "A delete addressing its variant by the situation it applies to.\n\n`conditions` is optional because the fallback variant pins nothing: address it with\n`default: true` and no `conditions`. An item that ends up addressing no variant at all is a\nper-item `VARIANT_UNPINNED`, and one marking `default` beside `conditions` is refused per\nitem with no code.\n",
         "required": [
           "entity_id"
         ],
         "properties": {
           "entity_id": {
             "type": "string",
-            "description": "The conditional entity the variant belongs to. Required, as it is beside a `variant_id`.\n",
+            "description": "The conditional entity the variant belongs to.",
             "example": "price-sp26d1yo"
           },
           "conditions": {
@@ -6801,18 +6968,18 @@
           "default": {
             "type": "boolean",
             "default": false,
-            "description": "Address the entity's fallback variant, the one it serves when nothing else applies. A\nproperty of the variant, as it is on a write, never an entry in `conditions`.\n"
+            "description": "Address the entity's fallback variant, the one served when nothing else applies."
           },
           "valid_from": {
             "type": "string",
-            "description": "The one version to remove, by the instant it takes effect. Omitted, the whole variant\ngoes.\n\nAn RFC 3339 date or date-time, to at most millisecond precision, canonicalized before it\nis matched.\n",
+            "description": "The one version to remove, by the instant it takes effect. Omitted, the whole variant\ngoes. An RFC 3339 date or date-time, canonicalized before it is matched.\n",
             "example": "2027-01-01T00:00:00Z"
           }
         }
       },
       "BatchUpsertResult": {
         "type": "object",
-        "description": "What a batch upsert did: one entry per item, in request order, and a count per outcome.\n",
+        "description": "What a batch upsert did: one entry per item, in request order, and a count per outcome.",
         "required": [
           "counts",
           "results"
@@ -6828,7 +6995,7 @@
           },
           "results": {
             "type": "array",
-            "description": "One entry per item, **in request order** — position is what maps an outcome back to its\nsource row, and no entry carries an index of its own.\n",
+            "description": "One entry per item, in request order, which is what maps an outcome back to its source row.",
             "items": {
               "$ref": "#/components/schemas/BatchUpsertResultEntry"
             }
@@ -6837,7 +7004,7 @@
       },
       "BatchDeleteResult": {
         "type": "object",
-        "description": "What a batch delete did: one entry per item, in request order, and a count per outcome.\n",
+        "description": "What a batch delete did: one entry per item, in request order, and a count per outcome.",
         "required": [
           "counts",
           "results"
@@ -6853,7 +7020,7 @@
           },
           "results": {
             "type": "array",
-            "description": "One entry per item, **in request order** — position is what maps an outcome back to its\nsource row.\n",
+            "description": "One entry per item, in request order, which is what maps an outcome back to its source row.",
             "items": {
               "$ref": "#/components/schemas/BatchDeleteResultEntry"
             }
@@ -6862,7 +7029,7 @@
       },
       "BatchUpsertOutcome": {
         "type": "string",
-        "description": "What one upsert item did, derived from what was stored rather than from a mode the caller\ndeclared.\n\n- `variant_created`: the condition tuple was unknown, so a variant and its first version were\n  created. The entry's `variant_id` is the id an order or contract pins.\n- `version_created`: the tuple was known and had no version at the item's `valid_from`, so\n  one was appended. The ordinary monthly-refresh case, and a separate value from\n  `variant_created` so an importer's counts can tell \"new postal codes appeared\" from\n  \"existing variants got their scheduled adjustment\".\n- `updated`: a version existed at that exact instant and was written in place.\n- `skipped`: reserved for a write whose values are identical to what is stored, so re-running\n  an unchanged import reads as a no-op. An item without `valid_from` has no `skipped`\n  detection at all.\n- `error`: this item alone failed, and the entry's `error` says why.\n",
+        "description": "What one upsert item did, derived from what was stored.\n\n- `variant_created`: the condition tuple was unknown, so a variant and its first version\n  were created\n- `version_created`: the tuple was known and had no version at the item's `valid_from`\n- `updated`: a version existed at that exact instant and was written in place\n- `skipped`: the values are identical to what is stored; not detected for an item without\n  `valid_from`\n- `error`: this item alone failed, and the entry's `error` says why\n",
         "enum": [
           "variant_created",
           "version_created",
@@ -6873,7 +7040,7 @@
       },
       "BatchDeleteOutcome": {
         "type": "string",
-        "description": "What one delete item did.\n\n- `deleted`: the variant, or the one version the item named, is gone.\n- `skipped`: the item addressed nothing — **the variant or the version**, never the entity. An\n  entity that cannot answer the item is an `error` carrying `ENTITY_NOT_FOUND`,\n  `ENTITY_TYPE_MISMATCH` or `ENTITY_NOT_CONDITIONAL`.\n- `error`: this item alone failed, and the entry's `error` says why.\n",
+        "description": "What one delete item did.\n\n- `deleted`: the variant, or the one version the item named, is gone\n- `skipped`: the item addressed no such variant or version; a missing entity is an `error`\n- `error`: this item alone failed, and the entry's `error` says why\n",
         "enum": [
           "deleted",
           "skipped",
@@ -6883,7 +7050,7 @@
       "BatchUpsertCounts": {
         "type": "object",
         "additionalProperties": false,
-        "description": "How many items reached each outcome. Keyed by exactly the values of `BatchUpsertOutcome`, all\nof them present, so a logger reads a count without `?? 0`.\n\n**They sum to the length of `results`.** There is no `total`.\n",
+        "description": "How many items reached each outcome. Keyed by exactly the values of `BatchUpsertOutcome`,\nall present, and summing to the length of `results`.\n",
         "required": [
           "variant_created",
           "version_created",
@@ -6917,7 +7084,7 @@
       "BatchDeleteCounts": {
         "type": "object",
         "additionalProperties": false,
-        "description": "How many items reached each outcome. Keyed by exactly the values of `BatchDeleteOutcome`, all\nof them present, and summing to the length of `results`. No `total`.\n",
+        "description": "How many items reached each outcome. Keyed by exactly the values of `BatchDeleteOutcome`,\nall present, and summing to the length of `results`.\n",
         "required": [
           "deleted",
           "skipped",
@@ -6941,7 +7108,7 @@
       "BatchUpsertResultEntry": {
         "type": "object",
         "additionalProperties": false,
-        "description": "What one upsert item did, and anything worth knowing about it.\n\n**It carries nothing else.** Position in `results` is the contract, so no entry carries an\nindex; nothing the caller sent is echoed back beyond `entity_id`; and there is no `_revision`\n— an editing screen re-reads the version it is about to write through its own `GET`.\n",
+        "description": "What one upsert item did. Position in `results` maps it back to its source row.",
         "required": [
           "outcome",
           "entity_id",
@@ -6953,22 +7120,22 @@
           },
           "entity_id": {
             "type": "string",
-            "description": "The entity this item wrote to, echoed from the item — present whatever happened.",
+            "description": "The entity this item wrote to, echoed from the item.",
             "example": "price-sp26d1yo"
           },
           "variant_id": {
             "type": "string",
-            "description": "The variant this item created or wrote to. Present on every outcome but `error`: for a\n`variant_created` item it is the id an importer needs to pin, and for the rest it is the\nvariant the item's condition tuple resolved to.\n",
+            "description": "The variant this item created or wrote to. Present on every outcome but `error`.",
             "example": "var-46045"
           },
           "valid_from": {
             "type": "string",
-            "description": "The version this item wrote, canonicalized to millisecond-precision UTC. Present on every\noutcome but `error`, including for an item that sent none — the server stamps the instant\na current-state write takes effect, and this is where the caller reads it back.\n",
+            "description": "The version this item wrote, canonicalized to millisecond-precision UTC. Present on\nevery outcome but `error`, including for an item that sent none.\n",
             "example": "2027-01-01T00:00:00.000Z"
           },
           "warnings": {
             "type": "array",
-            "description": "Things worth knowing that did not stop this item's write. **Always present, and possibly\nempty** — on a `skipped` and an `error` entry too — so a client reads its length rather\nthan branching on its absence, as every other write in this document already asks.\n`skipped` describes what storage did; a warning describes what the request asked for, and\nthe two are not the same fact.\n\nEvery warning fires per item, with no batch-level suppression:\n`VARIANT_COUNT_APPROACHING_CAP` included, even where an entity past its threshold\nproduces it on all 100 entries. A logger dedupes by code.\n",
+            "description": "Things worth knowing that did not stop this item's write. Always present and possibly\nempty, on every outcome. Fires per item, with no batch-level deduplication.\n",
             "items": {
               "$ref": "#/components/schemas/WriteWarning"
             }
@@ -6979,14 +7146,14 @@
                 "$ref": "#/components/schemas/ConditionalPricingError"
               }
             ],
-            "description": "Why this item failed, present only with `outcome: error`. The same typed shape a\nsingle-item write is refused with, so a per-item failure and a single-item failure are\nread by one client type.\n\nAn item carries the codes variant create raises — `VARIANT_UNPINNED`,\n`CONDITION_UNDEFINED`, `CONDITION_VALUE_INVALID`, `PIN_FORMAT_INVALID`,\n`VARIANT_LIMIT_REACHED`, `WRITE_CONFLICT` for transient contention, and the three the\naddressed entity answers with: `ENTITY_NOT_FOUND`, `ENTITY_TYPE_MISMATCH` and\n`ENTITY_NOT_CONDITIONAL` — less two. Those three are per item because each item names its\nown entity, while `SCHEMA_NOT_FOUND` is the envelope's, since the slug is in the path. `TUPLE_CONFLICT` never appears on an item, and neither does `VERSION_CONFLICT`: a\nguard failure on a brand-new tuple is re-read and re-derived, and an existing\n`valid_from` is a replacement.\n"
+            "description": "Why this item failed, present only with `outcome: error`: the codes a variant create\nraises, plus `ENTITY_NOT_FOUND`, `ENTITY_TYPE_MISMATCH` and `ENTITY_NOT_CONDITIONAL`,\nwhich are per item because each item names its own entity. Never `TUPLE_CONFLICT` or\n`VERSION_CONFLICT`.\n"
           }
         }
       },
       "BatchDeleteResultEntry": {
         "type": "object",
         "additionalProperties": false,
-        "description": "What one delete item did, and anything worth knowing about it.\n\nThe same six properties as a batch upsert entry, and it carries nothing else.\n",
+        "description": "What one delete item did. Position in `results` maps it back to its source row.",
         "required": [
           "outcome",
           "entity_id",
@@ -6998,22 +7165,22 @@
           },
           "entity_id": {
             "type": "string",
-            "description": "The entity this item removed from, echoed from the item — present whatever happened.",
+            "description": "The entity this item removed from, echoed from the item.",
             "example": "price-sp26d1yo"
           },
           "variant_id": {
             "type": "string",
-            "description": "The variant this item removed, or whose version it removed. Present wherever it is known:\nalways for an item that named one, and for an item addressing a condition tuple only once\nthat tuple resolved. **A `skipped` entry for a tuple no variant pins therefore names no\nvariant.**\n",
+            "description": "The variant this item removed, or whose version it removed. Present wherever it is\nknown, so a `skipped` entry for a tuple no variant pins names none.\n",
             "example": "var-46045"
           },
           "valid_from": {
             "type": "string",
-            "description": "The version this item removed, canonicalized to millisecond-precision UTC. Absent where\nthe item removed the whole variant, which is what distinguishes the two deletes this one\nendpoint performs.\n",
+            "description": "The version this item removed, canonicalized to millisecond-precision UTC. Absent where\nthe item removed the whole variant.\n",
             "example": "2027-01-01T00:00:00.000Z"
           },
           "warnings": {
             "type": "array",
-            "description": "Things worth knowing that did not stop this item's delete — chiefly which reads the\nremoval moved: `ACTIVE_VERSION_CHANGED` where what resolves now changed, and\n`SUPERSEDED_VERSION_WRITTEN` where a past-dated read did. Always present and possibly\nempty, on every outcome, as batch upsert's is.\n",
+            "description": "Things worth knowing that did not stop this item's delete, chiefly which reads the\nremoval moved. Always present and possibly empty, on every outcome.\n",
             "items": {
               "$ref": "#/components/schemas/WriteWarning"
             }
@@ -7024,7 +7191,7 @@
                 "$ref": "#/components/schemas/ConditionalPricingError"
               }
             ],
-            "description": "Why this item failed, present only with `outcome: error`. The same typed shape a\nsingle-item delete is refused with.\n\n`LAST_VERSION_UNDELETABLE` is the refusal specific to this endpoint's dated form;\n`VARIANT_UNPINNED` is an item that addresses no variant — no `variant_id`, no\n`default`, and no or empty `conditions`; `ENTITY_NOT_FOUND`, `ENTITY_TYPE_MISMATCH` and\n`ENTITY_NOT_CONDITIONAL` are per item, since each item names its own entity;\n`WRITE_CONFLICT` is transient contention.\nA missing variant or version is not here at all — that is `skipped`.\n"
+            "description": "Why this item failed, present only with `outcome: error`:\n`LAST_VERSION_UNDELETABLE`, `VARIANT_UNPINNED`, the codes a condition tuple that cannot\nbe canonicalized raises, `IDENTIFIER_INVALID`, `VALID_FROM_INVALID`, `WRITE_CONFLICT`,\nand the per-item `ENTITY_NOT_FOUND`, `ENTITY_TYPE_MISMATCH` and\n`ENTITY_NOT_CONDITIONAL`. A missing variant or version is `skipped` instead.\n"
           }
         }
       },
@@ -7048,7 +7215,7 @@
         }
       },
       "ReportedError": {
-        "description": "The `error` field of an error response: the message, or — where the request itself failed\nvalidation before any handler ran — the validation errors themselves, which those 400s put\nhere in place of a string.\n\nA conditional-pricing operation answers a body its schema rejects with the list, and\neverything else it refuses with the message.\n",
+        "description": "The `error` field of an error response: the message, or — where the request failed\nvalidation before any handler ran — the validation errors themselves.\n",
         "oneOf": [
           {
             "type": "string",
@@ -7066,7 +7233,7 @@
         ]
       },
       "ConditionalPricingError": {
-        "description": "An error from a conditional-pricing operation, carrying a machine-readable `code` from the\nconditional-pricing vocabulary plus the structured data that code explains, so a client can\nbranch on the kind of failure rather than parse the message.\nReferenced only by the operations that emit these codes; every other operation\nkeeps the plain `Error` shape.\n\n`details` is typed per code. Narrow on `code` and the object under it declares exactly the\nfields that code sends — never a field it does not send, and nothing beyond the declaration —\nso the conflicting variant id, or the value and vocabulary behind a rejected pin, is read\ndirectly.\n\nNot every failure these operations raise is in the vocabulary. A request body that is simply\nmalformed earns a message and nothing to branch on, and is answered with neither `code` nor\n`details` — the last member of the union, so testing `code` for absence is how a client tells\none of those from the twenty-three coded failures.\n",
+        "description": "An error from a conditional-pricing operation, carrying a `code` plus the structured data\nthat code explains. `details` is typed per code: narrow on `code` and the object under it\ndeclares exactly the fields that code sends.\n\nA request these schemas reject is answered by the request validator with a message and\ncarries neither `code` nor `details` — the last member of the union.\n",
         "allOf": [
           {
             "$ref": "#/components/schemas/Error"
@@ -7080,7 +7247,7 @@
                     "$ref": "#/components/schemas/ReportedError"
                   }
                 ],
-                "description": "What went wrong, in the field responses have always used and every caller to date\nreads. Carries the same string as `message` — which the shared `Error` schema\nrequires — except on a request-validation failure, which puts the list of validation\nerrors here instead.\n"
+                "description": "What went wrong. The same string as `message`, except on a request-validation\nfailure, which puts the list of validation errors here instead.\n"
               }
             }
           },
@@ -7088,7 +7255,7 @@
             "oneOf": [
               {
                 "type": "object",
-                "description": "No conditional entity type by that slug — the organization has no schema under it, or\nthe schema it has is not a conditional-pricing one.\n\nAddressed to the caller's own path parameter, and the same answer for every operation:\nnothing below a schema can be looked up until the schema itself is known.\n",
+                "description": "No conditional entity type by that slug.",
                 "required": [
                   "code",
                   "details"
@@ -7118,7 +7285,7 @@
               },
               {
                 "type": "object",
-                "description": "The schema exists and holds no entity with that id.\n\nA wrong entity id is answered here, never as a variant that was never there. An id\nthat *does* exist, under another type, is not this code — the entity was found, and\n`ENTITY_TYPE_MISMATCH` is what says so.\n",
+                "description": "The schema holds no entity with that id.",
                 "required": [
                   "code",
                   "details"
@@ -7154,7 +7321,7 @@
               },
               {
                 "type": "object",
-                "description": "That entity id belongs to an entity of a different type than the `{slug}` segment\nnamed.\n\nA `400`, not a `404`: the entity **was** found. The fix is to correct the slug and\nsend the request again; the entity id and the variant id were right. `actual_schema`\nnames the type the id belongs to, and where that is a conditional entity type it is\nthe slug to send.\n",
+                "description": "That entity id belongs to an entity of a different type than the `{slug}` segment\nnamed. Correct the slug and send the request again.\n",
                 "required": [
                   "code",
                   "details"
@@ -7187,7 +7354,7 @@
                       },
                       "actual_schema": {
                         "type": "string",
-                        "description": "The entity type that id belongs to. Where it is a conditional entity type, it\nis the slug to send instead.\n",
+                        "description": "The entity type that id belongs to. Where it is a conditional entity type,\nit is the slug to send instead.\n",
                         "example": "product"
                       }
                     }
@@ -7196,7 +7363,7 @@
               },
               {
                 "type": "object",
-                "description": "The entity is of the type the slug named, and is not a conditional one.\n\nA Product, Price or Coupon carries variants only if it was created with\n`is_conditional` set, and that flag is fixed at creation. So this is not a refusal\nanother request can get past: the entity has no conditional capability to address,\nand one that needs it has to be created as such.\n\nA `400`, as `ENTITY_TYPE_MISMATCH` is: the entity was found. Reading and writing the\nentity itself are unaffected; it is these endpoints that do not apply to it.\n",
+                "description": "The entity is of the type the slug named and was not created with `is_conditional`,\nwhich is fixed at creation. Reading and writing the entity itself are unaffected.\n",
                 "required": [
                   "code",
                   "details"
@@ -7232,7 +7399,7 @@
               },
               {
                 "type": "object",
-                "description": "This entity has no such variant — nothing to read, write or delete, and nothing that\nwas ever there to have deleted.\n\nRaised only once the entity itself has been established, so it never stands in for a\nwrong entity id or a wrong slug.\n",
+                "description": "This entity has no such variant.",
                 "required": [
                   "code",
                   "details"
@@ -7268,7 +7435,7 @@
               },
               {
                 "type": "object",
-                "description": "No version at that `valid_from` — never written, or deleted since.\n\nA version is addressed by the exact instant it takes effect from, not by the instant\na read happens to fall in, so this is not \"no version applies then\"; that case is\n`NO_ACTIVE_VERSION`.\n\nResolving a dated address tells an absent version from an absent variant, so a\nvariant that does not exist at all answers `VARIANT_NOT_FOUND` — the same answer the\npaths that name no date give.\n",
+                "description": "No version at that `valid_from` — never written, or deleted since. A version is\naddressed by the exact instant it takes effect from; for the version in effect at an\ninstant, see `NO_ACTIVE_VERSION`.\n",
                 "required": [
                   "code",
                   "details"
@@ -7304,7 +7471,7 @@
               },
               {
                 "type": "object",
-                "description": "Nothing applied to the given context, and the entity has no `default` variant to fall\nback to.\n\nEverything the request addressed exists: this is an answer about the organization's\nown data, not a defect to fix — \"we do not serve this situation\".\n\nOnly reachable with `resolve_one`. Without it the same situation is a `200` carrying\nan empty `results`, since a set of applicable variants can legitimately be empty; it\nis asking for exactly one answer that turns having none into a failure.\n",
+                "description": "Nothing applied to the given context and the entity has no `default` variant. Only\nreachable with `resolve_one`; without it the same situation is a `200` carrying an\nempty `results`.\n",
                 "required": [
                   "code",
                   "details"
@@ -7340,7 +7507,7 @@
               },
               {
                 "type": "object",
-                "description": "The variant has no version in effect at the instant asked about — raised by the\nshorthand reads and writes that address \"the version in effect\" without naming a\ndate, and by a pinned `:resolve` whose variant has no version in effect at `as_of`.\n\nRelative to `as_of`, and not a claim that every version is scheduled: a variant that\nis live today has none in effect at an instant before its first `valid_from` either.\nThe ordinary case is a variant staged ahead of its launch, which is a variant waiting\nrather than a variant broken — address one of its versions by `valid_from` to read or\nedit it before it takes effect.\n",
+                "description": "The variant has no version in effect at the instant asked about — typically a\nvariant staged ahead of its launch. Address one of its versions by `valid_from` to\nread or edit it before it takes effect.\n",
                 "required": [
                   "code",
                   "details"
@@ -7376,7 +7543,7 @@
               },
               {
                 "type": "object",
-                "description": "Several variants apply to the given context while a single result was requested.\n\nThe candidates are named, and none of them is served over the others: which is right\nis a question about the organization's own data.\n",
+                "description": "Several variants apply to the given context while a single result was requested.",
                 "required": [
                   "code",
                   "details"
@@ -7398,7 +7565,7 @@
                       "candidates": {
                         "type": "array",
                         "minItems": 2,
-                        "description": "Every variant that applied, each with the conditions it pins — which is what\nmakes the overlap actionable: two variants both apply because their pins do\nnot distinguish the context they were both asked about.\n\nBounded by the same cap `TOO_MANY_MATCHES` reports, which is checked first,\nso this list is never longer than one response may carry.\n",
+                        "description": "Every variant that applied, each with the conditions it pins.",
                         "items": {
                           "type": "object",
                           "additionalProperties": false,
@@ -7424,7 +7591,7 @@
               },
               {
                 "type": "object",
-                "description": "The condition tuple this write claims is already held.\n\nPersistent, unlike `WRITE_CONFLICT`: the same request fails the same way until the\nholder changes, so a bulk importer can tell \"send this again\" from \"this combination\nis taken and always will be\".\n",
+                "description": "The condition tuple this write claims is already held. Persistent, unlike\n`WRITE_CONFLICT`: the same request fails the same way until the holder changes.\n",
                 "required": [
                   "code",
                   "details"
@@ -7450,7 +7617,7 @@
                       },
                       "conflicting_variant_id": {
                         "type": "string",
-                        "description": "The variant already holding the tuple, where the write read it back.\n",
+                        "description": "The variant already holding the tuple, where the write read it back.",
                         "example": "var-50667"
                       }
                     }
@@ -7479,15 +7646,417 @@
                       "valid_from"
                     ],
                     "properties": {
-                      "variant_id": {
-                        "type": "string",
-                        "description": "The variant the write addressed.",
-                        "example": "var-46045"
+                      "variant_id": {
+                        "type": "string",
+                        "description": "The variant the write addressed.",
+                        "example": "var-46045"
+                      },
+                      "valid_from": {
+                        "type": "string",
+                        "description": "The instant already claimed by a version of that variant.",
+                        "example": "2027-01-01T00:00:00.000Z"
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "description": "The request names a condition the entity's schema does not define. A *stored* pin on\na condition the schema no longer declares is `VARIANT_PIN_UNDECLARED`.\n",
+                "required": [
+                  "code",
+                  "details"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "CONDITION_UNDEFINED"
+                    ]
+                  },
+                  "details": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "condition_name"
+                    ],
+                    "properties": {
+                      "condition_name": {
+                        "type": "string",
+                        "description": "The condition the request named and the schema does not define.",
+                        "example": "postal_code"
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "description": "A variant a resolve would compose pins a condition the entity's schema no longer\ndeclares, which would make it match every context. Declare the condition again, or\nremove the variants pinning it — found with `variants:list` or the tree, and removed\nby id.\n",
+                "required": [
+                  "code",
+                  "details"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "VARIANT_PIN_UNDECLARED"
+                    ]
+                  },
+                  "details": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "condition_name",
+                      "variant_id"
+                    ],
+                    "properties": {
+                      "condition_name": {
+                        "type": "string",
+                        "description": "The condition the variant pins and the schema no longer declares.",
+                        "example": "postal_code"
+                      },
+                      "variant_id": {
+                        "type": "string",
+                        "description": "One variant carrying such a pin.",
+                        "example": "var-46045"
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "description": "The requested operator is not applicable to the condition's type.",
+                "required": [
+                  "code",
+                  "details"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "OPERATOR_UNSUPPORTED"
+                    ]
+                  },
+                  "details": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "condition_name",
+                      "condition_type",
+                      "operator"
+                    ],
+                    "properties": {
+                      "condition_name": {
+                        "type": "string",
+                        "example": "postal_code"
+                      },
+                      "condition_type": {
+                        "type": "string",
+                        "description": "The type the schema declares that condition with.",
+                        "example": "location"
+                      },
+                      "operator": {
+                        "type": "string",
+                        "description": "The predicate the context or filter asked for, or `sort` where a listing\nasked to order by a condition whose type has no order.\n",
+                        "example": "between"
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "description": "A resolve context or listing filter value that is malformed for its condition's type.",
+                "required": [
+                  "code",
+                  "details"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "CONTEXT_FORMAT_INVALID"
+                    ]
+                  },
+                  "details": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "condition_name",
+                      "expected"
+                    ],
+                    "properties": {
+                      "condition_name": {
+                        "type": "string",
+                        "example": "postal_code"
+                      },
+                      "expected": {
+                        "type": "string",
+                        "description": "What a value for that condition has to be, in prose.",
+                        "example": "a postal code"
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "description": "A variant write pins a `select` value absent from its condition's vocabulary. A\ncondition declaring no vocabulary at all is `CONDITION_UNCONFIGURED`, and one whose\n`options` hold nothing readable is `CONDITION_UNREADABLE`.\n",
+                "required": [
+                  "code",
+                  "details"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "CONDITION_VALUE_INVALID"
+                    ]
+                  },
+                  "details": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "condition_name",
+                      "value",
+                      "options"
+                    ],
+                    "properties": {
+                      "condition_name": {
+                        "type": "string",
+                        "example": "segment"
+                      },
+                      "value": {
+                        "description": "The value the write pinned, as it arrived.",
+                        "example": "industrial"
+                      },
+                      "options": {
+                        "type": "array",
+                        "minItems": 1,
+                        "description": "The vocabulary as enforced, after any entries this deploy cannot read have\nbeen dropped.\n",
+                        "items": {
+                          "type": "string"
+                        },
+                        "example": [
+                          "private",
+                          "commercial"
+                        ]
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "description": "A variant write pins a `select` condition whose `options` are absent or empty. A\n`select` vocabulary is always closed, so one declaring nothing admits nothing; fill\nthe `options` in.\n",
+                "required": [
+                  "code",
+                  "details"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "CONDITION_UNCONFIGURED"
+                    ]
+                  },
+                  "details": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "condition_name"
+                    ],
+                    "properties": {
+                      "condition_name": {
+                        "type": "string",
+                        "description": "The condition whose vocabulary is not configured yet.",
+                        "example": "segment"
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "description": "A multi-match resolve found more variants than one response may carry. Narrow the\ncontext; the matches are not reported.\n",
+                "required": [
+                  "code",
+                  "details"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "TOO_MANY_MATCHES"
+                    ]
+                  },
+                  "details": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "limit"
+                    ],
+                    "properties": {
+                      "limit": {
+                        "type": "number",
+                        "description": "The most variants one resolve may compose.",
+                        "example": 100
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "description": "Transient write contention. Retryable, unlike `TUPLE_CONFLICT`. The revisions are\npresent where the contention was detected on a specific version.\n",
+                "required": [
+                  "code",
+                  "details"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "WRITE_CONFLICT"
+                    ]
+                  },
+                  "details": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "variant_id"
+                    ],
+                    "properties": {
+                      "variant_id": {
+                        "type": "string",
+                        "description": "The variant the write addressed.",
+                        "example": "var-46045"
+                      },
+                      "valid_from": {
+                        "type": "string",
+                        "description": "The version the write addressed, where one was addressed.",
+                        "example": "2027-01-01T00:00:00.000Z"
+                      },
+                      "expected_revision": {
+                        "type": "number",
+                        "description": "The revision the write required the stored version to still be at.",
+                        "example": 3
+                      },
+                      "current_revision": {
+                        "type": "number",
+                        "description": "The revision the version is actually at, where the failed write read it back.",
+                        "example": 4
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "description": "A listing's `from` plus `size` reaches past the offset window the search index\nallows — the window bounds the last row a page may contain. The page is not clamped;\npage on with the last response's `next` instead.\n",
+                "required": [
+                  "code",
+                  "details"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "OFFSET_WINDOW_EXCEEDED"
+                    ]
+                  },
+                  "details": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "from",
+                      "size",
+                      "window"
+                    ],
+                    "properties": {
+                      "from": {
+                        "type": "integer",
+                        "description": "The offset the request asked for.",
+                        "example": 24990
+                      },
+                      "size": {
+                        "type": "integer",
+                        "description": "The page size the request asked for, after clamping.",
+                        "example": 25
+                      },
+                      "window": {
+                        "type": "integer",
+                        "description": "The last row this deploy's index will serve from an offset.",
+                        "example": 25000
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "description": "A paging cursor could not be used for the read it arrived on. Start the read again\nwithout one; `details.reason` says which check failed.\n",
+                "required": [
+                  "code",
+                  "details"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "CURSOR_INVALID"
+                    ]
+                  },
+                  "details": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "reason"
+                    ],
+                    "properties": {
+                      "reason": {
+                        "type": "string",
+                        "description": "Which check the cursor failed, in prose.",
+                        "example": "The cursor was issued for a different sort order"
+                      }
+                    }
+                  }
+                }
+              },
+              {
+                "type": "object",
+                "description": "The entity already holds every variant it may hold. In a batch, every remaining item\nfor that entity will be refused the same way.\n",
+                "required": [
+                  "code",
+                  "details"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "enum": [
+                      "VARIANT_LIMIT_REACHED"
+                    ]
+                  },
+                  "details": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "variant_count",
+                      "cap"
+                    ],
+                    "properties": {
+                      "variant_count": {
+                        "type": "number",
+                        "description": "Variants this entity already holds.",
+                        "example": 5000
                       },
-                      "valid_from": {
-                        "type": "string",
-                        "description": "The instant already claimed by a version of that variant.",
-                        "example": "2027-01-01T00:00:00.000Z"
+                      "cap": {
+                        "type": "number",
+                        "description": "Variants this entity may hold. Configurable per deploy.",
+                        "example": 5000
                       }
                     }
                   }
@@ -7495,7 +8064,7 @@
               },
               {
                 "type": "object",
-                "description": "A condition the entity's schema does not define, named by a resolve context, by a\nlisting's condition filter, or by a variant's pins.\n",
+                "description": "A variant pins a value malformed for its condition's type. `condition_type` is what\na client branches on; `expected` says what the value had to be, which the type alone\ndoes not — a `location` is `location` whichever `format` it declares.\n",
                 "required": [
                   "code",
                   "details"
@@ -7504,20 +8073,36 @@
                   "code": {
                     "type": "string",
                     "enum": [
-                      "CONDITION_UNDEFINED"
+                      "PIN_FORMAT_INVALID"
                     ]
                   },
                   "details": {
                     "type": "object",
                     "additionalProperties": false,
                     "required": [
-                      "condition_name"
+                      "condition_name",
+                      "condition_type",
+                      "expected",
+                      "value"
                     ],
                     "properties": {
                       "condition_name": {
                         "type": "string",
-                        "description": "The condition named by the request and absent from the schema.",
-                        "example": "postal_code"
+                        "example": "valid_period"
+                      },
+                      "condition_type": {
+                        "type": "string",
+                        "description": "The type the schema declares that condition with.",
+                        "example": "daterange"
+                      },
+                      "expected": {
+                        "type": "string",
+                        "description": "What a pin for that condition has to be, in prose.",
+                        "example": "an object carrying a from and an until date, either may be open"
+                      },
+                      "value": {
+                        "description": "The value the write pinned, as it arrived.",
+                        "example": "2027-01-01/2027-12-31"
                       }
                     }
                   }
@@ -7525,7 +8110,7 @@
               },
               {
                 "type": "object",
-                "description": "The requested operator is not applicable to the condition's type.",
+                "description": "The write pins no condition and is not marked `default`, so it would match every\nresolve. On a delete, the item addresses no variant at all.\n",
                 "required": [
                   "code",
                   "details"
@@ -7534,31 +8119,20 @@
                   "code": {
                     "type": "string",
                     "enum": [
-                      "OPERATOR_UNSUPPORTED"
+                      "VARIANT_UNPINNED"
                     ]
                   },
                   "details": {
                     "type": "object",
                     "additionalProperties": false,
                     "required": [
-                      "condition_name",
-                      "condition_type",
-                      "operator"
+                      "entity_id"
                     ],
                     "properties": {
-                      "condition_name": {
-                        "type": "string",
-                        "example": "postal_code"
-                      },
-                      "condition_type": {
-                        "type": "string",
-                        "description": "The type the schema declares that condition with, which is what decides the\noperators it accepts.\n",
-                        "example": "location"
-                      },
-                      "operator": {
+                      "entity_id": {
                         "type": "string",
-                        "description": "The operator the context or filter asked for.",
-                        "example": "between"
+                        "description": "The conditional entity the item addressed.",
+                        "example": "price-sp26d1yo"
                       }
                     }
                   }
@@ -7566,7 +8140,7 @@
               },
               {
                 "type": "object",
-                "description": "A resolve context or listing filter value that is malformed for its condition's type.\n\n`details` says what the type requires, never what arrived: a resolve context value is\nnot quoted back.\n",
+                "description": "The delete would leave the variant with no version at all, which would keep its\ncondition tuple claimed while resolving to nothing. Delete the variant instead.\n",
                 "required": [
                   "code",
                   "details"
@@ -7575,25 +8149,26 @@
                   "code": {
                     "type": "string",
                     "enum": [
-                      "CONTEXT_FORMAT_INVALID"
+                      "LAST_VERSION_UNDELETABLE"
                     ]
                   },
                   "details": {
                     "type": "object",
                     "additionalProperties": false,
                     "required": [
-                      "condition_name",
-                      "expected"
+                      "variant_id",
+                      "valid_from"
                     ],
                     "properties": {
-                      "condition_name": {
+                      "variant_id": {
                         "type": "string",
-                        "example": "postal_code"
+                        "description": "The variant whose last version the delete addressed.",
+                        "example": "var-46045"
                       },
-                      "expected": {
+                      "valid_from": {
                         "type": "string",
-                        "description": "What a value for that condition has to be, in prose.",
-                        "example": "a postal code"
+                        "description": "The version the delete addressed, by the instant it takes effect from.",
+                        "example": "2027-01-01T00:00:00.000Z"
                       }
                     }
                   }
@@ -7601,7 +8176,7 @@
               },
               {
                 "type": "object",
-                "description": "A variant write pins a `select` value the condition's `options` do not admit — either\na value a declared vocabulary does not contain, or any value at all where the\ncondition declares no vocabulary for it to be in.\n\nOne of the two codes that report the submitted value back — `PIN_FORMAT_INVALID` is\nthe other. A resolve context value is never quoted back.\n",
+                "description": "A condition the entity's schema declares in a way this deploy cannot read: a\n`location` whose `format` is unrecognized or absent, or a `select` whose `options`\nhold nothing readable. Repair the definition on the schema.\n\nReads that do not interpret the condition — an unfiltered variants list, the tree, a\nvariant by id, a version timeline — keep working.\n",
                 "required": [
                   "code",
                   "details"
@@ -7610,7 +8185,7 @@
                   "code": {
                     "type": "string",
                     "enum": [
-                      "CONDITION_VALUE_INVALID"
+                      "CONDITION_UNREADABLE"
                     ]
                   },
                   "details": {
@@ -7618,28 +8193,22 @@
                     "additionalProperties": false,
                     "required": [
                       "condition_name",
-                      "value",
-                      "options"
+                      "unreadable"
                     ],
                     "properties": {
                       "condition_name": {
                         "type": "string",
-                        "example": "segment"
+                        "description": "The condition whose definition this deploy cannot read.",
+                        "example": "delivery_area"
                       },
-                      "value": {
-                        "description": "The value the write pinned, as it arrived. Declared without a type: the\nvocabulary holds strings, so anything else is out of it by definition and is\nreported as sent.\n",
-                        "example": "industrial"
-                      },
-                      "options": {
-                        "type": "array",
-                        "description": "The vocabulary *as enforced* — after the entries this deploy cannot read have\nbeen dropped, so a tenant whose `options` holds a title-only entry is told\nwhat the API actually checked against rather than what they believe they\nwrote. Empty when the condition declares no vocabulary at all, which is\nitself the reason the pin was refused; the message says which of the two\n(unconfigured, or unreadable) applies.\n",
-                        "items": {
-                          "type": "string"
-                        },
-                        "example": [
-                          "private",
-                          "commercial"
-                        ]
+                      "unreadable": {
+                        "type": "string",
+                        "description": "Which field of the definition cannot be read, named as the schema spells it.",
+                        "enum": [
+                          "format",
+                          "options"
+                        ],
+                        "example": "format"
                       }
                     }
                   }
@@ -7647,7 +8216,7 @@
               },
               {
                 "type": "object",
-                "description": "A multi-match resolve found more variants than one response may carry. Narrowing the\ncontext is the only fix; the matches are not reported.\n",
+                "description": "A listing's `sort` is not a field and direction this API can read. A well-formed\n`sort` naming a condition is refused under that condition's own code instead.\n",
                 "required": [
                   "code",
                   "details"
@@ -7656,20 +8225,20 @@
                   "code": {
                     "type": "string",
                     "enum": [
-                      "TOO_MANY_MATCHES"
+                      "SORT_INVALID"
                     ]
                   },
                   "details": {
                     "type": "object",
                     "additionalProperties": false,
                     "required": [
-                      "limit"
+                      "expected"
                     ],
                     "properties": {
-                      "limit": {
-                        "type": "number",
-                        "description": "The most variants one resolve may compose.",
-                        "example": 100
+                      "expected": {
+                        "type": "string",
+                        "description": "What a `sort` has to be, in prose.",
+                        "example": "conditions.<name>:asc or conditions.<name>:desc, naming a string, select, number or date condition"
                       }
                     }
                   }
@@ -7677,7 +8246,7 @@
               },
               {
                 "type": "object",
-                "description": "Transient write contention — concurrent writers, or throughput pressure on the\nentity's own rows. Retryable, unlike `TUPLE_CONFLICT`.\n\nThe revisions are present where the contention was detected on a specific version: a\nwrite carrying `_revision` lost to another that landed first, and a client that read\nthe version again would see `current_revision`. A variant-level refusal carries the\nvariant alone.\n",
+                "description": "The fallback marker — `default` or `_default` — used as though it were a condition.\nMark the variant `default` instead, or leave the marker out of the context.\n",
                 "required": [
                   "code",
                   "details"
@@ -7686,35 +8255,20 @@
                   "code": {
                     "type": "string",
                     "enum": [
-                      "WRITE_CONFLICT"
+                      "DEFAULT_MARKER_RESERVED"
                     ]
                   },
                   "details": {
                     "type": "object",
                     "additionalProperties": false,
                     "required": [
-                      "variant_id"
+                      "condition_name"
                     ],
                     "properties": {
-                      "variant_id": {
-                        "type": "string",
-                        "description": "The variant the write addressed.",
-                        "example": "var-46045"
-                      },
-                      "valid_from": {
+                      "condition_name": {
                         "type": "string",
-                        "description": "The version the write addressed, where one was addressed.",
-                        "example": "2027-01-01T00:00:00.000Z"
-                      },
-                      "expected_revision": {
-                        "type": "number",
-                        "description": "The revision the write required the stored version to still be at.",
-                        "example": 3
-                      },
-                      "current_revision": {
-                        "type": "number",
-                        "description": "The revision the version is actually at, where the failed write read it back.\nAbsent when it could not be.\n",
-                        "example": 4
+                        "description": "The marker, spelled as the request spelled it.",
+                        "example": "default"
                       }
                     }
                   }
@@ -7722,7 +8276,7 @@
               },
               {
                 "type": "object",
-                "description": "A listing asked for a page reaching past the window the search index allows.\n\n**`from` plus `size`**, not `from` alone: the window bounds the last row a page may\ncontain, so the final servable offset is `window` minus the page size. All three\nnumbers are in `details`, because a refusal quoting only an offset below the window\nreads like a mistake.\n\nNot a page clamped back inside the window, as entity listing does. The fix is a\ndifferent request: page on with the last response's `next`.\n\nThe window belongs to the deploy's search index, so it is reported and never\npublished.\n\nRaised by the paginated variant reads, which answer `501` until their behaviour\nlands.\n",
+                "description": "A variant marked `default` that also pins real conditions. Drop `default` to keep\nthe pins, or drop the pins to keep the fallback.\n",
                 "required": [
                   "code",
                   "details"
@@ -7731,32 +8285,25 @@
                   "code": {
                     "type": "string",
                     "enum": [
-                      "OFFSET_WINDOW_EXCEEDED"
+                      "DEFAULT_VARIANT_PINS_CONDITIONS"
                     ]
                   },
                   "details": {
                     "type": "object",
                     "additionalProperties": false,
                     "required": [
-                      "from",
-                      "size",
-                      "window"
+                      "condition_names"
                     ],
                     "properties": {
-                      "from": {
-                        "type": "integer",
-                        "description": "The offset the request asked for.",
-                        "example": 24990
-                      },
-                      "size": {
-                        "type": "integer",
-                        "description": "The page size the request asked for, after clamping. Present because the two\ntogether are what exceeded the window — an offset inside it can still be\nrefused for the page it would have to read.\n",
-                        "example": 25
-                      },
-                      "window": {
-                        "type": "integer",
-                        "description": "The last row this deploy's index will serve from an offset. Read it to size a\npage control, never to decide when to switch to the cursor — a caller can page\non with `next` from any page.\n",
-                        "example": 25000
+                      "condition_names": {
+                        "type": "array",
+                        "description": "The conditions the write pinned beside the marker.",
+                        "items": {
+                          "type": "string"
+                        },
+                        "example": [
+                          "postal_code"
+                        ]
                       }
                     }
                   }
@@ -7764,7 +8311,7 @@
               },
               {
                 "type": "object",
-                "description": "A paging cursor could not be used for the read it arrived on.\n\nOne code for every way that happens, because the caller's fix is the same for all of\nthem: start the read again without a cursor. `details.reason` says which check failed,\nfor a human reading a log rather than for a client to branch on — a cursor this API\nminted and a caller stored can go stale, be truncated in transit, be replayed against\na different filter or sort, or be replayed against another variant or the opposite\norder on a versions read.\n\nRaised by the paginated variant and version reads, which answer `501` until their\nbehaviour lands.\n",
+                "description": "A version write asking for a different `valid_from` than the version its own address\nnames. Moving a version is an append and a delete; a body repeating the `valid_from`\nit was read with is accepted.\n",
                 "required": [
                   "code",
                   "details"
@@ -7773,20 +8320,26 @@
                   "code": {
                     "type": "string",
                     "enum": [
-                      "CURSOR_INVALID"
+                      "VALID_FROM_IMMUTABLE"
                     ]
                   },
                   "details": {
                     "type": "object",
                     "additionalProperties": false,
                     "required": [
-                      "reason"
+                      "addressed",
+                      "requested"
                     ],
                     "properties": {
-                      "reason": {
+                      "addressed": {
                         "type": "string",
-                        "description": "Which check the cursor failed, in prose.",
-                        "example": "The cursor was issued for a different sort order"
+                        "description": "The version the request addressed, by the instant it takes effect from.",
+                        "example": "2027-01-01T00:00:00.000Z"
+                      },
+                      "requested": {
+                        "type": "string",
+                        "description": "The instant the body asked for instead, canonicalized.",
+                        "example": "2027-04-01T00:00:00.000Z"
                       }
                     }
                   }
@@ -7794,7 +8347,7 @@
               },
               {
                 "type": "object",
-                "description": "The entity already holds every variant it may hold.\n\nA hard refusal, unlike the `VARIANT_COUNT_APPROACHING_CAP` warning that precedes it,\ncarrying the warning's two keys. In a batch it means stop the import rather than fix\na row: every remaining item for that entity will be refused the same way.\n\nEmitted by `$createConditionalVariant`. The batch writes that will also raise it\nanswer `501` until their handlers land.\n",
+                "description": "A version write carrying a condition tuple other than the one its variant was\ncreated with. Create a second variant for the other situation.\n",
                 "required": [
                   "code",
                   "details"
@@ -7803,26 +8356,20 @@
                   "code": {
                     "type": "string",
                     "enum": [
-                      "VARIANT_LIMIT_REACHED"
+                      "VARIANT_CONDITIONS_IMMUTABLE"
                     ]
                   },
                   "details": {
                     "type": "object",
                     "additionalProperties": false,
                     "required": [
-                      "variant_count",
-                      "cap"
+                      "variant_id"
                     ],
                     "properties": {
-                      "variant_count": {
-                        "type": "number",
-                        "description": "Variants this entity already holds.",
-                        "example": 5000
-                      },
-                      "cap": {
-                        "type": "number",
-                        "description": "Variants this entity may hold. Configurable per deploy, the same value for\nevery organization on it.\n",
-                        "example": 5000
+                      "variant_id": {
+                        "type": "string",
+                        "description": "The variant whose conditions the write would have changed.",
+                        "example": "var-46045"
                       }
                     }
                   }
@@ -7830,7 +8377,7 @@
               },
               {
                 "type": "object",
-                "description": "A variant pins a value that is malformed for its condition's type.\n\nThe write-side mirror of `CONTEXT_FORMAT_INVALID`: a context value is *matched*, a\nvariant's value is *pinned*. Unlike that one it reports the value back, as\n`CONDITION_VALUE_INVALID` does.\n\nDistinct from a condition whose *declared type* this deploy cannot read at all: that\nis a schema problem rather than a bad row, every item naming the condition fails\nidentically, and it stays uncoded.\n\nIt carries `expected` as well as `condition_type`, and the two are not the same fact:\na `location` condition is `condition_type: location` whichever format it declares,\nand the two formats want different values — a postal code, or an object carrying a\npostal code and a town. The type is what a client branches on; `expected` is what\nsays what the value had to be.\n\nEmitted by `$createConditionalVariant`. The batch writes that will also raise it\nanswer `501` until their handlers land.\n",
+                "description": "An id in the request that cannot be used as a storage key: empty, longer than 128\ncharacters, or carrying a character outside letters, digits, `_`, `.`, `:` and `-`.\nEvery id the platform issues qualifies.\n",
                 "required": [
                   "code",
                   "details"
@@ -7839,36 +8386,30 @@
                   "code": {
                     "type": "string",
                     "enum": [
-                      "PIN_FORMAT_INVALID"
+                      "IDENTIFIER_INVALID"
                     ]
                   },
                   "details": {
                     "type": "object",
                     "additionalProperties": false,
                     "required": [
-                      "condition_name",
-                      "condition_type",
-                      "expected",
-                      "value"
+                      "field",
+                      "reason"
                     ],
                     "properties": {
-                      "condition_name": {
-                        "type": "string",
-                        "example": "valid_period"
-                      },
-                      "condition_type": {
+                      "field": {
                         "type": "string",
-                        "description": "The type the schema declares that condition with, which is what decides the\nvalues it accepts.\n",
-                        "example": "daterange"
+                        "description": "Which id could not be keyed by, named as the request names it.",
+                        "enum": [
+                          "entity_id",
+                          "variant_id"
+                        ],
+                        "example": "entity_id"
                       },
-                      "expected": {
+                      "reason": {
                         "type": "string",
-                        "description": "What a pin for that condition has to be, in prose — the same field\n`CONTEXT_FORMAT_INVALID` carries, worded for the write side. It says what\n`condition_type` cannot: a `location` of format `zipcode` wants a postal code\nand one of format `zipcode_town` wants an object carrying both, and the type\nis `location` either way.\n",
-                        "example": "an object carrying a from and an until date, either may be open"
-                      },
-                      "value": {
-                        "description": "The value the write pinned, as it arrived. Declared without a type, since\nwhat makes it invalid is that it is not of the condition's type.\n",
-                        "example": "2027-01-01/2027-12-31"
+                        "description": "Which of the three checks the id failed, in prose.",
+                        "example": "it carries a character this scheme does not admit"
                       }
                     }
                   }
@@ -7876,7 +8417,7 @@
               },
               {
                 "type": "object",
-                "description": "The write pins no condition and is not marked `default`.\n\nSuch a variant would be a universal wildcard matching every resolve, which is a far\nmore dangerous thing than a fallback and far easier to create by accident — an empty\npostal-code column in a source file produces exactly this.\n\nRaised on a delete too, where an item addresses no variant at all — no `variant_id`,\nno `default`, and either no `conditions` or an empty one: the item names no target.\nIt is an `error`, not a `skipped`.\n\nEmitted by `$createConditionalVariant`. Batch upsert and batch delete, which raise\nit too, answer `501` until their handlers land.\n",
+                "description": "A `valid_from` that is not one of the timestamp forms a version timeline can be\nsorted by. Wider ISO 8601 forms — a bare year, an ordinal date, `T24:00:00Z` — are\nrefused rather than interpreted.\n",
                 "required": [
                   "code",
                   "details"
@@ -7885,20 +8426,20 @@
                   "code": {
                     "type": "string",
                     "enum": [
-                      "VARIANT_UNPINNED"
+                      "VALID_FROM_INVALID"
                     ]
                   },
                   "details": {
                     "type": "object",
                     "additionalProperties": false,
                     "required": [
-                      "entity_id"
+                      "expected"
                     ],
                     "properties": {
-                      "entity_id": {
+                      "expected": {
                         "type": "string",
-                        "description": "The conditional entity the item addressed.",
-                        "example": "price-sp26d1yo"
+                        "description": "What a `valid_from` has to be, in prose.",
+                        "example": "an RFC 3339 date, optionally with a time to at most millisecond precision and an optional UTC offset"
                       }
                     }
                   }
@@ -7906,7 +8447,7 @@
               },
               {
                 "type": "object",
-                "description": "The delete would leave the variant with no version at all.\n\nSuch a variant would still hold its condition tuple and still be selectable, and\nwould then resolve to nothing — a variant delete wearing a version delete's clothes.\nDelete the variant instead; that frees the tuple too.\n\nEmitted by `$deleteConditionalVariantVersion`. Batch delete, which raises it too,\nanswers `501` until its handler lands.\n",
+                "description": "A value the store cannot hold: a non-finite number, one outside the table's numeric\nrange, or a key with no value. Send a value needing more precision than a JSON\nnumber carries as a decimal string, as `unit_amount_decimal` does.\n",
                 "required": [
                   "code",
                   "details"
@@ -7915,26 +8456,26 @@
                   "code": {
                     "type": "string",
                     "enum": [
-                      "LAST_VERSION_UNDELETABLE"
+                      "VALUE_UNSTORABLE"
                     ]
                   },
                   "details": {
                     "type": "object",
                     "additionalProperties": false,
                     "required": [
-                      "variant_id",
-                      "valid_from"
+                      "path",
+                      "reason"
                     ],
                     "properties": {
-                      "variant_id": {
+                      "path": {
                         "type": "string",
-                        "description": "The variant whose last version the delete addressed.",
-                        "example": "var-46045"
+                        "description": "Where the value sits, as a dotted path of the request's own keys, with array\nentries by index.\n",
+                        "example": "values.tiers.0.unit_amount"
                       },
-                      "valid_from": {
+                      "reason": {
                         "type": "string",
-                        "description": "The version the delete addressed, by the instant it takes effect from.",
-                        "example": "2027-01-01T00:00:00.000Z"
+                        "description": "What about the value cannot be stored, in prose.",
+                        "example": "the non-finite number Infinity"
                       }
                     }
                   }
@@ -7942,7 +8483,7 @@
               },
               {
                 "type": "object",
-                "description": "A failure the vocabulary has no entry for: a malformed request body, a value that is\nnot readable as its condition's type, a rule refusing a write for a reason a client\ncannot branch on. The message says what to fix, and no code is sent.\n\nCarries what every response carries and nothing else — reading `code` on this member\nis how a client tells it from the coded members above.\n",
+                "description": "A refusal the request validator raises, answered before any handler runs. The\nmessage says what to fix, and no code is sent — which is how a client tells this\nmember from the coded ones.\n",
                 "additionalProperties": false,
                 "required": [
                   "message"
@@ -10373,6 +10914,10 @@
             "description": "The optional reference date for the price computation (ISO 8601 format)",
             "type": "string",
             "format": "date"
+          },
+          "city": {
+            "description": "The city the postal code belongs to. Not used for price computation,\nonly echoed back in `inputs` for display purposes.\n",
+            "type": "string"
           }
         },
         "required": [
@@ -10612,6 +11157,14 @@
           "breakdown": {
             "$ref": "#/components/schemas/ComputedPriceBreakdown"
           },
+          "inputs": {
+            "description": "A snapshot of the parameters this price was computed from, for display purposes\n(e.g. showing \"computed for 3,500 kWh/year\"). Included in the `_meta` signature.\n",
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/ComputePriceInputs"
+              }
+            ]
+          },
           "_meta": {
             "$ref": "#/components/schemas/SignatureMeta"
           }
@@ -10624,6 +11177,49 @@
           "breakdown"
         ]
       },
+      "ComputePriceInputs": {
+        "type": "object",
+        "description": "Echo of the request parameters used to compute the price, in the caller-facing shape.",
+        "properties": {
+          "type": {
+            "$ref": "#/components/schemas/ProductCategory"
+          },
+          "consumptionHT": {
+            "type": "number"
+          },
+          "consumptionNT": {
+            "type": "number"
+          },
+          "consumptionType": {
+            "$ref": "#/components/schemas/ConsumptionTypeGetAg"
+          },
+          "zipCode": {
+            "type": "string"
+          },
+          "city": {
+            "type": "string"
+          },
+          "providerId": {
+            "type": "string"
+          },
+          "billingPeriod": {
+            "type": "string",
+            "enum": [
+              "weekly",
+              "monthly",
+              "every_quarter",
+              "every_6_months",
+              "yearly",
+              "one_time"
+            ]
+          },
+          "referenceDate": {
+            "type": "string",
+            "format": "date"
+          }
+        },
+        "additionalProperties": true
+      },
       "SpotMarketBiddingZone": {
         "description": "The bidding zone for a spot market price.",
         "type": "string",
@@ -14057,6 +14653,23 @@
             "items": {
               "$ref": "#/components/schemas/ProductRecommendation"
             }
+          },
+          "source": {
+            "type": "object",
+            "description": "Context about what the recommendations were searched against.",
+            "properties": {
+              "item": {
+                "description": "The first line item of the contract used as source for the recommendation.\nCarries the amounts the customer currently pays; only present when searching by contract_id.\n",
+                "anyOf": [
+                  {
+                    "$ref": "#/components/schemas/PriceItem"
+                  },
+                  {
+                    "$ref": "#/components/schemas/CompositePriceItem"
+                  }
+                ]
+              }
+            }
           }
         },
         "required": [