docs: test_tags_in_items_match_tag_list fails on live data — docket tag drift from P36/P37 tag operations #623

New Issue

kert · 2026-08-14T04:31:56Z

kert commented

2026-08-14 04:31:56 +00:00

Surfaced during #618's full-suite gate proof: tests/docs/test_docs_build.py::TestExportLibrary::test_tags_in_items_match_tag_list fails against the live bib store (a docket tag present on items is missing from the exported tag list). Pre-existing on clean main (verified via stash), local-only (CI containers don't carry data/bib.sqlite). Almost certainly drift from this week's controller tag operations (added cms-rule:CMS-1832-F to NHRGIHGD, added/removed year: tags on 2KVJ2HKX/5ITGVDJV, new sup:2027_PFS_NPRM tag) without regenerating whatever tag-list export the docs test validates. Fix: regenerate the export (find the generator the test names) or make the test's fixture hermetic; decide which is the intended contract. Cost #618 a full 25-min suite run — worth fixing promptly.

Surfaced during #618's full-suite gate proof: `tests/docs/test_docs_build.py::TestExportLibrary::test_tags_in_items_match_tag_list` fails against the live bib store (a docket tag present on items is missing from the exported tag list). Pre-existing on clean main (verified via stash), local-only (CI containers don't carry `data/bib.sqlite`). Almost certainly drift from this week's controller tag operations (added `cms-rule:CMS-1832-F` to NHRGIHGD, added/removed `year:` tags on 2KVJ2HKX/5ITGVDJV, new `sup:2027_PFS_NPRM` tag) without regenerating whatever tag-list export the docs test validates. Fix: regenerate the export (find the generator the test names) or make the test's fixture hermetic; decide which is the intended contract. Cost #618 a full 25-min suite run — worth fixing promptly.

kert added the quality docs labels 2026-08-14 04:31:56 +00:00

kert referenced this issue

2026-08-14 15:10:50 +00:00

tests: close leaked sqlite connections — ResourceWarning flood in CI test job #618

kert referenced this issue from a commit

2026-08-14 19:10:57 +00:00

fix(docs): self-consistent, hermetic library export (closes #623)

kert closed this issue

2026-08-14 19:10:57 +00:00

kert commented

2026-08-14 19:11:39 +00:00

Root cause confirmed and fixed in f346007 — it was not stale-export drift but a mid-export race: the exporter hydrated all ~184k items (minutes) and only then queried list_tags(). During #618's suite run, controller tag ops (P37 year: tag removals on 2KVJ2HKX/5ITGVDJV) landed in that window — the removed tag stayed on already-serialized items but dropped out of the later tag query (zero-count tags vanish from the JOIN), poisoning the on-disk library.json so test_tags_in_items_match_tag_list failed on every subsequent run.

Fix (two-part, contract decided):

docs/scripts/export_library.py:67 derives the tag list from the serialized items themselves (L99) — self-consistent by construction, immune to concurrent DB mutation — and swaps the output in atomically.
The pytest contract is now hermetic: tests/docs/test_docs_build.py:29 exports a fixture store via new STACK_BIB_DB/STACK_LIBRARY_JSON overrides; test_tags_match_item_tags pins tag/item consistency exactly. Live-store validation belongs to the docs build itself — the suite no longer reads the constantly-mutating data/bib.sqlite, so this class of 25-minute-suite-killing flake can't recur.

Verification: 9/9 docs tests green in ~3s (hermetic, runs in CI too now — previously skipped there for lack of bib.sqlite); pre-commit hook gate green; live library.json regenerated clean (orphans: []).

Root cause confirmed and fixed in [f346007](https://git.fhirworx.io/homelab/stack/commit/f346007) — it was **not** stale-export drift but a mid-export race: the exporter hydrated all ~184k items (minutes) and only then queried `list_tags()`. During #618's suite run, controller tag ops (P37 `year:` tag removals on 2KVJ2HKX/5ITGVDJV) landed in that window — the removed tag stayed on already-serialized items but dropped out of the later tag query (zero-count tags vanish from the JOIN), poisoning the on-disk `library.json` so `test_tags_in_items_match_tag_list` failed on every subsequent run. **Fix (two-part, contract decided):** 1. [docs/scripts/export_library.py:67](https://git.fhirworx.io/homelab/stack/src/branch/main/docs/scripts/export_library.py#L67) derives the tag list from the serialized items themselves ([L99](https://git.fhirworx.io/homelab/stack/src/branch/main/docs/scripts/export_library.py#L99)) — self-consistent by construction, immune to concurrent DB mutation — and swaps the output in atomically. 2. The pytest contract is now **hermetic**: [tests/docs/test_docs_build.py:29](https://git.fhirworx.io/homelab/stack/src/branch/main/tests/docs/test_docs_build.py#L29) exports a fixture store via new `STACK_BIB_DB`/`STACK_LIBRARY_JSON` overrides; [test_tags_match_item_tags](https://git.fhirworx.io/homelab/stack/src/branch/main/tests/docs/test_docs_build.py#L94) pins tag/item consistency exactly. Live-store validation belongs to the docs build itself — the suite no longer reads the constantly-mutating `data/bib.sqlite`, so this class of 25-minute-suite-killing flake can't recur. **Verification:** 9/9 docs tests green in ~3s (hermetic, runs in CI too now — previously skipped there for lack of `bib.sqlite`); pre-commit hook gate green; live `library.json` regenerated clean (orphans: `[]`).

kert referenced this issue

2026-08-17 14:57:48 +00:00

bib: Store.upsert clobbers curated tags/collections on URL-dedupe update (wipe-and-replace _sync_tags) #624

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: homelab/stack#623