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 catalog —
vendor/clbdr/data/editions.json, a bibliographic register
of martyrology editions that exist in the world. Currently 8.
- Attachment —
Store.__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.
Problem
/healthzreports only the editions whose texts are attached, so atranscription backlog is invisible to monitoring and only surfaces as a 404
when someone requests one.
Two different things determine what a caller can read:
vendor/clbdr/data/editions.json, a bibliographic registerof martyrology editions that exist in the world. Currently 8.
Store.__init__(src/martyrology_api/store.py:129) treatsan edition as attached only when its directory holds at least one
MM.jsonmonth file. Currently 5.
healthzreturnseditions=sorted(app.state.store.available())(
src/martyrology_api/app.py), which is the attachment set alone. Live now:martyrologium_romanum_1584,_1914(the Latin editio typica recognita, notthe attached
_1914_en_unofficial) and_2001have never had text in eitherrepo — verified with
git log --allover bothmartyrology-apiand the privatemartyrology-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_urlpointer). Nothing is broken. The gap is only that you cannot seeit 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
editionsexactly as it is — the deploy smoke check reads it, and changingits shape would be a breaking change to
scripts/deploy/deploy.sh. Add the twocounts 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 costsnothing 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 unchangedonce text lands.
Found while investigating why those three editions 404 after the v0.2.0 deploy.