Skip to content

healthz reports attached editions only, hiding the transcription backlog #27

Description

@JohnRDOrazio

Problem

/healthz reports only the editions whose texts are attached, so a
transcription backlog is invisible to monitoring and only surfaces as a 404
when someone requests one.

Two different things determine what a caller can read:

  • The catalogvendor/clbdr/data/editions.json, a bibliographic register
    of martyrology editions that exist in the world. Currently 8.
  • AttachmentStore.__init__ (src/martyrology_api/store.py:129) treats
    an edition as attached only when its directory holds at least one MM.json
    month file. Currently 5.

healthz returns editions=sorted(app.state.store.available())
(src/martyrology_api/app.py), which is the attachment set alone. Live now:

attached (healthz):  1749, 1914_en_unofficial, 2004, 2004_en_unofficial, 2004_it_IT
catalogued:          the above + 1584, 1914, 2001

martyrologium_romanum_1584, _1914 (the Latin editio typica recognita, not
the attached _1914_en_unofficial) and _2001 have never had text in either
repo — verified with git log --all over both martyrology-api and the private
martyrology-texts, which returns zero commits touching those paths.

Requesting one returns a correct and well-formed 404 edition-unavailable
("registered but its texts are not attached in this deployment", with an
editions_url pointer). Nothing is broken. The gap is only that you cannot see
it without diffing healthz against the catalog by hand.

Why it matters

The count silently changed meaning once already. Deploy tooling and humans both
read "editions: 5" as a health signal, but it answers "how many are attached",
not "how many should be". If a data submodule were pinned to a stale commit and
dropped an edition, healthz would report 4 and look just as healthy as 5 —
there is nothing to compare against.

Proposal

Report both, so the delta is legible:

{
  "status": "ok",
  "version": "0.2.0",
  "data": { "crmedr": "...", "clbdr": "...", "texts": "..." },
  "editions": ["martyrologium_romanum_1749", "..."],
  "editions_catalogued": 8,
  "editions_attached": 5
}

Keep editions exactly as it is — the deploy smoke check reads it, and changing
its shape would be a breaking change to scripts/deploy/deploy.sh. Add the two
counts alongside, and add the fields to HealthOut
(src/martyrology_api/models.py:127).

The catalogued count is available as len(registry.editions)
(src/martyrology_api/registry.py:65), already loaded at startup, so this costs
nothing at request time.

Worth deciding as part of the change: whether an attached-but-uncatalogued
edition — the reverse direction, which would indicate a genuine data fault
rather than a backlog — should also be surfaced, and whether a shrinking
attached count deserves anything stronger than a number.

Not a defect

3 of 8 catalogued editions await transcription. That is a content backlog, not
an engineering fault, and the governance model already accommodates it: all
three sit under governance_body:editio_typica, so permissions work unchanged
once text lands.

Found while investigating why those three editions 404 after the v0.2.0 deploy.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions