ivans_dbcs

Mark the month's stuck in-flight build failed so it can be resubmitted.

Code
Body: ``{year, month}``. Response: ``{abandoned, reference_id, year,
month}``. Does not stop a running worker.

Poll the month's build. Idempotent: polling never consumes the result.

Code
Body: ``{year, month}``. Response: ``{success, async_status, async_result,
build_status, stalled_since, reference_id, year, month}``. Render
``build_status``, not ``async_status``: a build that failed its stability
check still finishes as a Celery success.

Return the credential-free DBCS configuration read model.

Code
Response: ``{checked, upload_enabled, upload_method,
selected_agency_count}``. Built from named fields only, so no transport or
connection detail can reach the wire through it.

List the DBCS XML already on file for the month, newest first.

Code
Body: ``{year, month}``. Response: ``{year, month, artifacts}``. Matches on
the file's metadata first; a file with no metadata is matched by legacy
filename only, and flagged ``verified: false``.

Return the stored selection, resolved, INCLUDING ids no longer eligible.

Code
Response: ``{agencies, unknown_contact_ids}`` -- the same shape the batch
resolver answers with, because both endpoints answer the same two
questions.

The save replaces the whole set, so a caller wanting to add or drop one
agency has to submit the complete list. A stored id that has since become
ineligible appears on no search page, yet it is still stored and is still
refused on the next save; this endpoint is the only way to see it.

NOT paginated and NOT capped, unlike every other endpoint here. That is
deliberate but it is a real cost, so it is stated rather than buried: this
endpoint answers with the whole stored selection, and nothing bounds how
large that is. ``MAX_SELECTION_IDS`` bounds a REQUEST, not the stored set:
``vendors/nxtech/dbcs/cli.py::select_agencies`` writes the key with no cap
of its own and is deliberately left in place by this story, so a tenant can
already hold more ids than this API would accept in a save. (Postfix 250
only seeds the key empty; the CLI is the uncapped writer.) Capping or
paging the answer would hide exactly the
stored ids an operator opened it to find, which is the whole reason the
endpoint exists. What the size does NOT do is reach the database as one
statement: ``repository/ivans_dbcs.py::IvansDbcsRepository`` chunks the
lookup at ``ID_QUERY_CHUNK_SIZE`` and unions the batches. A client must be
prepared for a list longer than it could have submitted itself.

Submit a new build that supersedes an earlier DBCS XML for the month.

Code
Body: ``{year, month, supersedes_file_id, acknowledged_unverified_month}``.
Same admission and response as ``submit_build``. The superseded file must
exist, be DBCS XML, and cover the requested month; only the NEW file's
metadata records the link.

Resolve a batch of contact ids to rows plus their eligibility verdicts.

Code
Body: ``{contact_ids}``. Response: ``{agencies, unknown_contact_ids}``.

No eligibility filter is applied: this answers for ANY contact and each row
carries the axes it fails, which is what makes it useful for auditing a
selection rather than a filtered view of the search.

Replace the whole stored selection with the submitted ids.

Code
Body: ``{contact_ids, confirmation_text}``. Response:
``{selected_agency_count, previous_agency_count}``.

An empty ``contact_ids`` is a legitimate request that clears the selection,
guarded by the typed confirmation the request schema enforces. Validation
is all-or-nothing and runs before the write, so a refused request stores
nothing; the refusal names every offending id, both as a sentence under
``contact_ids`` and as structured entries under ``rejected_agencies`` or
``duplicate_agency_numbers`` that a UI can act on.

Return one page of the eligible agency roster, flagged for the picker.

Code
Body: ``{search_text, page, page_size}``. Response:
``{page, page_size, total_count, total_pages, agencies}``.

A page past the last one is an empty list with the real total, never an
error -- a paging control branches on exactly that.

Admit and enqueue a DBCS build for one completed calendar month.

Code
Body: ``{year, month, acknowledged_unverified_month}``. Response:
``{success, accepted, async_status, async_result, reference_id,
build_token, snapshot_file_id, submitted_at, supersedes_file_id, year,
month}``.

A refused admission answers ``success: false`` with
``messages.refusal_code`` naming the gate. ``accepted: false`` means a
build for the month is already in flight and nothing new was queued.