fix(client-contract): read a no_data part's gap kind from its own reason

python/client-contract/CHANGELOG.md

@@ -11,11 +11,12 @@ All notable changes to the `dfo-spec-kit-client-contract` Python package will be
 - `strict-fields.json` and its schema: 29 members that stay required and non-nullable, each one a client reads, and the answer kinds, part statuses and operation statuses the clients branch on.
 - `actions.json` and its schema: the caller's next step for each of the 102 active refusal codes on `problem_details` or `no_data_reason`, with the gap kind of each no_data reason.
 - The status fallback for a refusal whose code has no row: 400 and 422 to `InvalidRequestError`, 401 to `AuthenticationError`, 403 to `PermissionDeniedError`, 404 and 410 to `NotFoundError`, 408 to `DfoTimeoutError`, 429 to `RateLimitError`, and any other 4xx or 5xx to `InvalidRequestError` or `ServerError`.
-- `scenario.schema.json`, the scenario record, and 121 scenarios: 32 recorded against the deployed dfo-apis dev app at `99e62038c`, and 89 synthetic, each derived from a recorded one by a one-line edit, with 19 binary bodies totalling 1,124,808 bytes and records and bodies together 13,186,279 bytes. `search-place-ambiguous-twice` pins two entity_ambiguous groups of one text, each option and slot token naming its group by `entity_choice`. The scenarios cover the several-part choice entries and the assumptions each identity entry echoes, a picked reading whose assumption Search states in its answer, the place choice through a no_data part's options, the choice refusals, a part without variable_text, an unknown status without a restatement, a shared label, a one-part option whose data_query holds two parts, the separate and operations echo, an unsupported part's placeholder, the timed_out, unsupported and unknown gaps, an unknown answer kind, the `SearchWarning` rule, the stacked dataset's `part` column, the frame layout, a strict fetch's `DataWarning`, a spec fetch that rebinds one of two entity roles and keeps the other, one that drops a role bound to null, a spec whose destination is a named group fetched with a window or with its origin rebound, whose sentence lookup posts the groups of the roles the build left bound, a twice cut-off build, a cut-off build retried after its Retry-After, a build refused 504 then 503 and one refused 503 then 504, a refused build, a build refused 501 `capability_unavailable`, a digest mismatch, a signed URL refused on both rounds, a relative files-route Location, an artifact url on a foreign origin, on the storage host and absolute on the API's origin, a manifest definition without identity or schema_version, a Search spec without identity or resolved, nested specs no rule reads, an empty parts list, a Search body that is not an object, a codeless 503 problem document that is not retryable, a 401, an identity resubmit answering another spec, a part whose status is not a string, a Search spec whose definition names another spec_id, a Search response with no JSON body, an option with no data_query, empty entities and facets, a Sunset header issued once, `x-dfo-warning` messages and a Deprecation and Sunset pair, an unreadable versions page, a mint and a spec fetch whose build answers 202 and is polled to done, a resumed operation, a rate-limited poll, 503 polls retried within the budget an answered poll restores, a 202 that reads running, polls whose `retry_after_ms` changes from one to the next, a 404 poll that raises, a failed operation posted again, a failed operation with no error, and a ref whose stored file expired, read through the file selector, rebuilt at the same version, at a newer one, or refused with the newest version read from the versions route: the first version it lists with no `base_content_version`, the newest plain build, so a derived version listed before it is skipped.
+- `scenario.schema.json`, the scenario record, and 122 scenarios: 32 recorded against the deployed dfo-apis dev app at `99e62038c`, and 90 synthetic, each derived from a recorded one by a one-line edit, with 19 binary bodies totalling 1,124,808 bytes and records and bodies together 13,324,483 bytes. `search-place-ambiguous-twice` pins two entity_ambiguous groups of one text, each option and slot token naming its group by `entity_choice`. The scenarios cover the several-part choice entries and the assumptions each identity entry echoes, a picked reading whose assumption Search states in its answer, the place choice through a no_data part's options, the choice refusals, a part without variable_text, an unknown status without a restatement, a shared label, a one-part option whose data_query holds two parts, the separate and operations echo, an unsupported part's placeholder, the timed_out, unsupported and unknown gaps, an unknown answer kind, the `SearchWarning` rule, the stacked dataset's `part` column, the frame layout, a strict fetch's `DataWarning`, a spec fetch that rebinds one of two entity roles and keeps the other, one that drops a role bound to null, a spec whose destination is a named group fetched with a window or with its origin rebound, whose sentence lookup posts the groups of the roles the build left bound, a twice cut-off build, a cut-off build retried after its Retry-After, a build refused 504 then 503 and one refused 503 then 504, a refused build, a build refused 501 `capability_unavailable`, a digest mismatch, a signed URL refused on both rounds, a relative files-route Location, an artifact url on a foreign origin, on the storage host and absolute on the API's origin, a manifest definition without identity or schema_version, a Search spec without identity or resolved, nested specs no rule reads, an empty parts list, a Search body that is not an object, a codeless 503 problem document that is not retryable, a 401, an identity resubmit answering another spec, a part whose status is not a string, a Search spec whose definition names another spec_id, a Search response with no JSON body, an option with no data_query, empty entities and facets, a Sunset header issued once, `x-dfo-warning` messages and a Deprecation and Sunset pair, an unreadable versions page, a mint and a spec fetch whose build answers 202 and is polled to done, a resumed operation, a rate-limited poll, 503 polls retried within the budget an answered poll restores, a 202 that reads running, polls whose `retry_after_ms` changes from one to the next, a 404 poll that raises, a failed operation posted again, a failed operation with no error, and a ref whose stored file expired, read through the file selector, rebuilt at the same version, at a newer one, or refused with the newest version read from the versions route: the first version it lists with no `base_content_version`, the newest plain build, so a derived version listed before it is skipped.
 - `client-codes.json` and its schema: the 23 codes a client sets on the errors it raises itself, each with its error class, retryable flag and condition, disjoint from `actions.json` and `registries/codes.json`, and the `client_codes()` and `client_codes_schema()` accessors. Every scenario error the client raises itself carries its code, and `refusal_without_code` names a refusal whose body carries no code.
 - `proxy-codes.json` and its schema, the website proxy's `rate_limited` and `transient_unavailable` codes with their statuses, which the proxy sends in problem documents of the shape every refusal has, both retryable, with `Retry-After` on the 429, so a client reads one refusal shape, and `warning-codes.json` and its schema, the 6 codes a client sets on the warnings it issues itself, with the `proxy_codes()` and `warning_codes()` accessors.
 - `ref_digest_changed` in `warning-codes.json`, a `DfoWarning` for a ref member whose `content_version` serves a file with another digest than the ref's, because the server rendered the same data again. The client returns the data, with no error under strict.
 - `timed_out` in `actions.json` and `registries/codes.json`, the no_data reason Search gives a part it left unresolved at the request's time limit, with action `ask_data_question` and gap kind `timed_out`, which `actions.schema.json` now admits. The client-side `timeout` code, a transport timeout, is unchanged.
+- A no_data part's gap kind comes from its own reason, whatever the answer's `diagnostics.timed_out` says. `answer-timed-out` gives its part the reason `timed_out`, and `answer-timed-out-keeps-reasons` pins a part that keeps `variable_not_resolved` as a `not_understood` gap in a timed-out answer.
 - Error outcomes give the error's `trace_id`, the body's, else the `x-dfo-trace-id` header's, else null. Scenario outcomes give `retry_waits`, the waits before each retry, and `warnings`, the warning codes a step's responses issued. Scenario steps take no `timeout`.
 - `dataset-ref.schema.json`, the frozen `DatasetRef` format, with accepted and rejected examples.
 - `without_party_totals` in the ref's artifact rendering, `true` for the version rendered with party totals left out and absent for a plain rendering, with `ref-without-party-totals` and `ref-without-party-totals-false-rejected` as its examples.

python/client-contract/README.md

@@ -73,7 +73,7 @@ uv run ty check src/dfo_client_contract
 
 ## Strict fields
 
-`strict-fields.json` lists the members a client cannot act without. Each pointer names one property of one component schema, `/components/schemas/<Schema>/properties/<member>`. A `required` entry stays in its schema's `required` list and admits no null, so a client raises `ContractError` when one is missing or null. Every entry is a member some client rule acts on, and a client checks a body only along them: from the body's root it goes down through strict members alone, so a member no client reads goes unchecked, however deep. A `Spec` where no rule reads it, in `resolved.equivalent_readings`, `no_data.flagged_match` or `no_data.alternate_match`, may lack `resolved` or its definition's `identity` and raises nothing, which `answer-nested-specs-unchecked` pins at all three. A strict member that holds a JSON type its schema does not admit raises `ContractError` `contract_violation` at its pointer, as a missing one does, which `answer-candidate-specs-not-a-list` pins with `candidates.specs` as an object. An integer is a JSON number with no fractional part that is not a boolean, as JSON Schema's `integer` reads it, since a JavaScript client cannot tell `1.0` from `1`: a strict member such as a manifest definition's `schema_version`, and a ref's `definition.schema_version`, admit `1.0` and refuse `1.5` and `true`. Each item of a strict list, `parts`, `candidates.specs` or `artifacts`, must be an object, and an item of another type raises `contract_violation` at its index pointer, such as `/parts/0/candidates/specs/0`. A member a client reads that no strict pointer names, and that holds a JSON type other than the list, object or string its rule reads, reads as absent, and so does every member of a holder that is not an object; an item of another type in such a list reads as absent too. So `no_data.options` as an object or null offers no option, `mentions` as a string mentions nothing, and a `diagnostics` that is not an object holds no `timed_out` and no warnings. `answer-operations-not-a-list` pins a definite part's `operations` as an object. An item of an `assumptions` or `reading_assumptions` list reads only when it is an object whose `kind`, `binding_ref` and `text` are strings, and an item of an `operations` list only when it is an object whose `verb` and `phrase` are strings; any other item reads as absent. A read item holds its schema's members alone: an assumption's `refs` as its string items when it is a list, and an operation's `over` when it is a string or null and its `target_year` when it is null or a number other than a boolean with no fractional part, read as that integer, so `2020.0` reads and echoes as `2020` and `2020.5` reads as absent. An optional member of another type reads as absent, and a client reads no member the schema does not name. An `enums` entry keeps every listed value, the values a client branches on: the answer kinds, the part statuses and the operation statuses. A client still accepts a value no entry lists.
+`strict-fields.json` lists the members a client cannot act without. Each pointer names one property of one component schema, `/components/schemas/<Schema>/properties/<member>`. A `required` entry stays in its schema's `required` list and admits no null, so a client raises `ContractError` when one is missing or null. Every entry is a member some client rule acts on, and a client checks a body only along them: from the body's root it goes down through strict members alone, so a member no client reads goes unchecked, however deep. A `Spec` where no rule reads it, in `resolved.equivalent_readings`, `no_data.flagged_match` or `no_data.alternate_match`, may lack `resolved` or its definition's `identity` and raises nothing, which `answer-nested-specs-unchecked` pins at all three. A strict member that holds a JSON type its schema does not admit raises `ContractError` `contract_violation` at its pointer, as a missing one does, which `answer-candidate-specs-not-a-list` pins with `candidates.specs` as an object. An integer is a JSON number with no fractional part that is not a boolean, as JSON Schema's `integer` reads it, since a JavaScript client cannot tell `1.0` from `1`: a strict member such as a manifest definition's `schema_version`, and a ref's `definition.schema_version`, admit `1.0` and refuse `1.5` and `true`. Each item of a strict list, `parts`, `candidates.specs` or `artifacts`, must be an object, and an item of another type raises `contract_violation` at its index pointer, such as `/parts/0/candidates/specs/0`. A member a client reads that no strict pointer names, and that holds a JSON type other than the list, object or string its rule reads, reads as absent, and so does every member of a holder that is not an object; an item of another type in such a list reads as absent too. So `no_data.options` as an object or null offers no option, `mentions` as a string mentions nothing, and a `diagnostics` that is not an object holds no warnings. `answer-operations-not-a-list` pins a definite part's `operations` as an object. An item of an `assumptions` or `reading_assumptions` list reads only when it is an object whose `kind`, `binding_ref` and `text` are strings, and an item of an `operations` list only when it is an object whose `verb` and `phrase` are strings; any other item reads as absent. A read item holds its schema's members alone: an assumption's `refs` as its string items when it is a list, and an operation's `over` when it is a string or null and its `target_year` when it is null or a number other than a boolean with no fractional part, read as that integer, so `2020.0` reads and echoes as `2020` and `2020.5` reads as absent. An optional member of another type reads as absent, and a client reads no member the schema does not name. An `enums` entry keeps every listed value, the values a client branches on: the answer kinds, the part statuses and the operation statuses. A client still accepts a value no entry lists.
 
 The answer's `kind` and each part's `status` are the discriminators of their unions in the served document. A search response with no `kind` raises `ContractError`, as a part with no `status` does, although the served document gives `kind` a default and leaves it out of `required`. A part `status` a client does not know raises nothing and makes the part an `unknown` gap. An answer `kind` a client does not know raises `ContractError`, because the client cannot read the answer. A Search response body that is not an object, a `resolution` answer whose `parts` is empty, at pointer `/parts`, since the served schema gives it at least one item, a part whose `status` is not a string, at pointer `/parts/<i>/status`, and a definite or candidate spec whose `definition.spec_id` differs from its `spec_id` raise `ContractError` `contract_violation`, in a Search response as in a ref; `search-body-not-an-object`, `answer-empty-parts`, `answer-part-status-not-a-string` and `answer-definition-spec-id-mismatch` pin the four.
 
@@ -114,7 +114,7 @@ A client maps a refusal whose code has no row, or that carries no code, on its H
 
 A 408 is a timeout the caller retries, and a 410 names a resource that is gone, so the caller stops as it does on a 404. A client reads a refusal's body as a problem document when its content type is `application/problem+json` or `application/json`; a body of any other type reads as no body, so the refusal carries no code. A no_data reason with no row becomes a `no_data` gap.
 
-An answer's gaps follow from its parts. A candidates part is a `choice` gap, its options the candidates. A no_data part is a gap of its reason's `gap_kind`, its options the no_data `options`, and of kind `timed_out` instead when the answer's `diagnostics.timed_out` is true. An unsupported part is an `unsupported` gap. A part whose status a client does not know is an `unknown` gap.
+An answer's gaps follow from its parts. A candidates part is a `choice` gap, its options the candidates. A no_data part is a gap of its reason's `gap_kind`, its options the no_data `options`, whatever `diagnostics.timed_out` says. Search marks a part it left unresolved at its time limit with the reason `timed_out`. An unsupported part is an `unsupported` gap. A part whose status a client does not know is an `unknown` gap.
 
 ## Client codes