Skip to content

feat: add the regression corpus for broad coverage - #6

Closed
tobocop2 wants to merge 1 commit into
xberg-io:mainfrom
tobocop2:feat/ballast-corpus
Closed

feat: add the regression corpus for broad coverage#6
tobocop2 wants to merge 1 commit into
xberg-io:mainfrom
tobocop2:feat/ballast-corpus

Conversation

@tobocop2

@tobocop2 tobocop2 commented Aug 14, 2026

Copy link
Copy Markdown
Member

A broad corpus of ordinary documents, used to answer one question: does a change alter output anywhere it should not. Mathematics is incidental here. Breadth and volume are the point, which is what makes it a regression net rather than a set of chosen fixtures.

3,275 documents from five sources: PubMed Central open access, arXiv, Project Gutenberg, govdocs1 and Wikipedia.

Licensing, read rather than assumed

Every licence came from the document's own metadata or the publisher's stated terms:

  • PMC, from each file's JATS ali:license_ref
  • arXiv, per paper from its OAI record
  • Gutenberg, govdocs1 and Wikipedia, from published policy, which is uniform for each

The result splits into the two lanes LICENSES.md already defines:

lane count terms
vendor 1,816 CC-BY-4.0, CC0, US public domain
reference 1,459 CC-BY-SA, CC-BY-NC*, arXiv nonexclusive-distrib

arXiv shows the split plainly. A paper released under CC-BY is vendored. A paper under the arXiv perpetual non-exclusive licence grants distribution rights to arXiv rather than to us, so the corpus records it and does not host it.

Nothing is excluded. Both lanes are in REGRESSION_PROVENANCE.md, which lists all 3,275 with source, licence and how the licence was determined.

The bytes stay out of git

The vendored set is about 1 GB. The corpus already keeps binaries in the bucket, and this follows that rule for bulk content of any format, so clones stay small.

The five regression directories join scripts/corpus-patterns.txt and .gitignore, which scripts/test_publish_corpus.py checks for divergence. The entries are path-scoped, so an ordinary .xml or .html fixture elsewhere in the tree is unaffected.

Getting the bytes in

python3 scripts/fetch_regression.py
python3 scripts/publish_corpus.py --bucket xberg-test-documents

scripts/regression-objects.json carries a source, sha256 and size for each of the 1,816. A download whose digest does not match is written to <path>.mismatch and reported, so a source that changed upstream cannot quietly become the fixture.

govdocs1 publishes 486 MB shards rather than individual files, so those 400 entries name the shard and the member inside it. A shard is downloaded once and every member taken from it before it is discarded.

Verified

Both fetch paths were run against the real sources: three PMC articles through the direct path, and four govdocs1 members extracted from a shard, all digests matching. scripts/test_publish_corpus.py passes, 31 tests.

@tobocop2
tobocop2 requested a review from Goldziher as a code owner August 14, 2026 02:30
The corpus answers one question: does a change alter output anywhere it
should not. Mathematics is incidental. Breadth and volume are the point,
which makes it a regression net rather than a set of chosen fixtures.

Sources are PubMed Central open access, arXiv, Project Gutenberg,
govdocs1 and Wikipedia. Every licence was read from the document's own
metadata or the publisher's stated terms: PMC from each file's JATS
ali:license_ref, arXiv per paper from its OAI record, and the remaining
three from published policy.

1,816 documents are permissively licensed and are vendored. 1,459 carry
ShareAlike, NonCommercial, or terms granting redistribution to the
publisher alone, so the corpus records their source and licence without
hosting them. arXiv shows the split plainly: a CC-BY paper is vendored,
while one under the arXiv perpetual non-exclusive licence grants
distribution to arXiv rather than to us.

The bytes stay out of git, as the corpus already does for binaries. The
regression directories join scripts/corpus-patterns.txt and .gitignore,
so publish_corpus.py carries them to the bucket. Path-scoped entries
leave ordinary .xml and .html fixtures elsewhere untouched.

scripts/fetch_regression.py obtains the vendored bytes from their sources
and verifies each against the sha256 the corpus was built from. govdocs1
publishes shards rather than files, so those entries name the shard and
the member, and a shard is downloaded once for every member taken.
@tobocop2
tobocop2 force-pushed the feat/ballast-corpus branch from bb15732 to a372a66 Compare August 14, 2026 02:44
@tobocop2 tobocop2 changed the title feat: add the ballast corpus for regression coverage feat: add the regression corpus for broad coverage Aug 14, 2026
@tobocop2

Copy link
Copy Markdown
Member Author

Superseded by #7, which carries the same commit on a branch named for the corpus rather than the term it used to use.

@tobocop2 tobocop2 closed this Aug 14, 2026
@tobocop2
tobocop2 deleted the feat/ballast-corpus branch August 14, 2026 02:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant