[jm-rivera]

A Datasets client can pace its polls, fetch any stored version's file by format, list a dataset's versions without a principal, and read how long the server holds each version's frame. Every pending or running operation response carries operation.retry_after_ms and a Retry-After header, a quarter of the time since Operation.submitted_at, held between 1,500 and 8,000 ms. A done poll carries neither.

GET /api/datasets/{id}/{content_version}/file?format=&bundle=&layout= answers 302 to one file of that version (src/datasets_api/doors/files.py). It signs a stored copy first, renews an aged copy whose bytes survive, renders from the stored frame only when no copy survives, and refuses artifact_expired only when the frame's bytes are gone too. The rendering uses the version's recorded minting options with the requested format, bundle and layout applied. GET /api/datasets/{id}/versions serves under datasets.snapshot and pages with limit (1 to 500, default 100), a cursor bound to the path id, next_cursor and complete. An id no dataset has refuses 404 spec_not_found, where the old route answered an empty list. A single served id reads its page through a keyset over version_record_recency (0037_version_record_recency.sql, on subject_id, recorded_at DESC, content_version DESC), so a page reads its own rows however long the history; several served ids keep the grouped query, and both compare the cursor as a row. On 20,000 versions of one subject in Postgres 17, a page at offset 10,000 took 0.73 ms where the grouped query took about 260 ms. The migration's CREATE INDEX takes a SHARE lock and fails after its 5 s lock timeout.

Every Manifest the mint, definition GET, snapshot and done-poll routes return carries retention, either {"pinned": true} or {"pinned": false, "held_until": ...} at the frame's stored_at plus 30 days. A pin promotes the frame retention reads, aged or servable, so the next Manifest reports pinned. LiveArtifactStore.copy reads a 404 as an expired artifact only when the source object is gone. A missing destination bucket is a retryable 503.

The OpenAPI document names every operation {surface}_{route.name}, declares one tag per surface, documents the 202 with Location and Retry-After, and marks no field required that the wire can omit. SlotOption and ObservationPoint list their fields, where a wrap serializer's dict[str, Any] annotation had made them open objects, and test_every_object_schema_names_its_properties guards every component. The Scope schema says that on a spec_id input each supplied member replaces the stored spec's value whole, so entities naming one role unbinds the others. Docstrings describe the website proxy as a per-IP fixed window kept in Postgres, failing open, with Authorization passed upstream unread.

The spec-kit pin moves to 0f1a106 (DevelopmentFinanceObservatory/spec-kit#10), which maps the codes the selector and versions routes serve. The pin moves again to the release commit once that release is cut. The list_versions change in DevelopmentFinanceObservatory/ai#30 merges once this deploys to dev. Until then, the harness backfill preflight refuses, an unknown id raises in mint recovery, and recovery sees only the newest 100 versions. Conformance clauses C182 to C186 state the new contract.

Testing: just check at ec65f9c against spec-kit 0f1a106 passed 37,908 tests, with 132 skipped and 5 xfailed. Its one failure, test_a_surface_built_while_serving_a_release_binds_it_and_the_session_s_after in tests/graph_release/test_views.py, fails the same way on dev and is fixed by #65. With the index, tests/datasets_api, tests/dataset_store and the migration immutability test passed (3,115 passed, 82 skipped).