# SPDX-License-Identifier: Apache-2.0 # Copyright 2026 Scienting # # Source Code: https://git.scient.ing/papers/paperspec # See the LICENSE.md file for full license terms. """Packages: writing, reading and validating a scienting-doc/1 folder or zipped package.""" import bz2 import json import shutil import zipfile from pathlib import Path import pytest from hypothesis import HealthCheck, given, settings, strategies as st from conftest import FIXTURES, read_jsonl from helpers_cli import ( CHECKS_ONLY, HALE, INVALID, TINY, TINY_ZIP, edit_package, key_for, package_dirs, read_package, rules_of, store, ) from paperspec import crypto, package from paperspec.text import sha256_hex from paperspec.tree import Refusal PROFILE = settings( derandomize=True, max_examples=200, database=None, suppress_health_check=[HealthCheck.too_slow], ) TINY_KEY = TINY.name @pytest.fixture(scope="module") def schemas(): return store() @pytest.fixture(scope="module") def scratch(tmp_path_factory): return tmp_path_factory.mktemp("scratch") def invalid_cases(): return sorted(INVALID.iterdir(), key=lambda p: p.name) def validate_case(case, schemas): archive = case / ("package" + package.ZIP_EXTENSION) if archive.exists(): return package.validate_zip(archive, schemas) return package.validate(case / "package", schemas) def edit_manifest(root, change): path = root / "MANIFEST.json" manifest = json.loads(path.read_text(encoding="utf-8")) path.write_text(package.line(change(manifest)), encoding="utf-8") return root def copy_package(source, dest): shutil.copytree(source, dest) return dest class TestSafePath: @pytest.mark.parametrize( "path", [ "document.json", "assets/a.png", "datasets/ds-1/data.csv", "a b/c", "é/ü.json", ], ) def test_accepts_relative_normalized_paths(self, path): assert package.safe_path(path) @pytest.mark.parametrize( "path", [ "", "/etc/passwd", "../outside", "assets/../../outside", "a//b", "a/./b", "a/b/", "./a", "a\\b", "a\x00b", ".", "..", None, 7, b"bytes", ], ) def test_refuses_what_leaves_or_is_not_normal(self, path): assert not package.safe_path(path) @PROFILE @given(st.text()) def test_accepted_paths_stay_inside_and_are_normal(self, path): if package.safe_path(path): assert all(part not in ("", ".", "..") for part in path.split("/")) assert not path.startswith("/") assert "\\" not in path class TestSerialization: def test_line_is_canonical_json_and_a_newline(self): assert package.line({"b": 1, "a": [True, None]}) == '{"a":[true,null],"b":1}\n' def test_jsonl_joins_lines_as_utf8(self): assert package.jsonl([{"k": "é"}, {"k": 2}]) == '{"k":"é"}\n{"k":2}\n'.encode() def test_jsonl_of_nothing_is_empty(self): assert package.jsonl([]) == b"" def test_witness_id_derives_from_the_hash(self): sha = sha256_hex(b"a witness") wid = package.witness_id(sha) assert len(wid) == 7 assert wid[0].isalpha() assert wid == package.witness_id(sha) assert wid != package.witness_id(sha256_hex(b"another witness")) @pytest.mark.parametrize("source", package_dirs(), ids=lambda p: p.name) def test_fixture_witness_ids_derive_from_their_hashes(self, source): witnesses = json.loads((source / "witnesses.json").read_text())["witnesses"] for w in witnesses: assert package.witness_id(w["sha256"]) == w["id"] def test_sha256_pattern_wants_lowercase_hex(self): assert package.SHA256_RE.fullmatch("0" * 64) assert not package.SHA256_RE.fullmatch("A" * 64) assert not package.SHA256_RE.fullmatch("0" * 63) class TestWrite: @pytest.mark.parametrize("source", package_dirs(), ids=lambda p: p.name) def test_rewriting_a_fixture_reproduces_it_byte_for_byte(self, source, tmp_path): files, absent = read_package(source) digest = package.write(tmp_path / "out", files, absent) manifest = (source / "MANIFEST.json").read_bytes() assert (tmp_path / "out" / "MANIFEST.json").read_bytes() == manifest assert digest == sha256_hex(manifest) for path, data in files.items(): assert (tmp_path / "out" / path).read_bytes() == data def test_lists_absent_assets_without_writing_them(self, tmp_path): files, absent = read_package(HALE) package.write(tmp_path / "out", files, absent) manifest = json.loads((tmp_path / "out" / "MANIFEST.json").read_text()) listed = [e for e in manifest["files"] if e.get("present") is False] assert listed == absent assert not (tmp_path / "out" / listed[0]["path"]).exists() def test_skips_a_file_given_as_none(self, tmp_path): files, absent = read_package(TINY) files["references.jsonl"] = None package.write(tmp_path / "out", files, absent) manifest = json.loads((tmp_path / "out" / "MANIFEST.json").read_text()) assert "references.jsonl" not in [e["path"] for e in manifest["files"]] assert not (tmp_path / "out" / "references.jsonl").exists() @pytest.mark.parametrize( "bad", ["../outside", "/etc/outside", "assets/../../outside", "MANIFEST.json"] ) def test_refuses_an_unsafe_file_path(self, bad, tmp_path): files, absent = read_package(TINY) files[bad] = b"x" with pytest.raises(Refusal, match="unsafe path") as raised: package.write(tmp_path / "out", files, absent) assert raised.value.rule == "package.path.unsafe" assert not (tmp_path / "outside").exists() def test_refuses_an_unsafe_absent_path(self, tmp_path): files, _ = read_package(TINY) absent = [{"path": "../x.png", "sha256": "0" * 64, "size": 1, "present": False}] with pytest.raises(Refusal, match="unsafe path") as raised: package.write(tmp_path / "out", files, absent) assert raised.value.rule == "package.path.unsafe" class TestCanonicalReaders: def test_read_jsonl_parses_canonical_lines(self, tmp_path): path = tmp_path / "a.jsonl" path.write_bytes(b'{"a":1}\n[2,"\xc3\xa9"]\n') assert package.read_jsonl(path) == [{"a": 1}, [2, "é"]] def test_read_jsonl_of_an_empty_file_has_no_records(self, tmp_path): path = tmp_path / "a.jsonl" path.write_bytes(b"") assert package.read_jsonl(path) == [] def test_read_jsonl_wants_a_final_newline(self, tmp_path): path = tmp_path / "a.jsonl" path.write_bytes(b'{"a":1}') with pytest.raises(Refusal, match="every line ends with a newline") as raised: package.read_jsonl(path) assert raised.value.rule == "package.file.newline" @pytest.mark.parametrize( ("data", "ending"), [ (b'{"a": 1}\n', "not canonical JSON"), (b'{"b":1,"a":2}\n', "not canonical JSON"), (b'{"a":1}\r\n', "not canonical JSON"), (b'{"a":123456789012345678901}\n', "not canonical JSON"), (b'{"a":1.0}\n', "not canonical JSON"), (b'\xef\xbb\xbf{"a":1}\n', "(JSONDecodeError)"), (b'{"a":NaN}\n', "(ValueError)"), (b'{"a":Infinity}\n', "(ValueError)"), (b'{"a":"\xff"}\n', "(UnicodeDecodeError)"), (b'{"a":"\\ud800"}\n', "(ValueError)"), (b"[" * 100000 + b"]" * 100000 + b"\n", "(RecursionError)"), (b'{"a":' + b"9" * 5000 + b"}\n", "(ValueError)"), (b"\n", "(JSONDecodeError)"), ], ) def test_read_jsonl_refuses_what_is_not_canonical(self, tmp_path, data, ending): path = tmp_path / "a.jsonl" path.write_bytes(data) with pytest.raises(Refusal, match="not canonical JSON") as raised: package.read_jsonl(path) assert raised.value.rule == "package.file.canonical" assert str(raised.value).endswith(ending) def test_read_jsonl_names_the_line(self, tmp_path): path = tmp_path / "a.jsonl" path.write_bytes(b'{"a":1}\n{"a": 2}\n') with pytest.raises(Refusal, match=r"a\.jsonl:2"): package.read_jsonl(path) def test_integers_up_to_2_pow_53_stay_exact(self, tmp_path): path = tmp_path / "a.jsonl" path.write_bytes(b'{"a":9007199254740992}\n') assert package.read_jsonl(path) == [{"a": 2**53}] def test_read_json_parses_one_value(self, tmp_path): path = tmp_path / "a.json" path.write_bytes(b'{"a":[1,2]}\n') assert package.read_json(path) == {"a": [1, 2]} @pytest.mark.parametrize("data", [b'{"a":1}', b'{"a":1}\n\n', b""]) def test_read_json_wants_exactly_one_final_newline(self, tmp_path, data): path = tmp_path / "a.json" path.write_bytes(data) with pytest.raises(Refusal) as raised: package.read_json(path) assert raised.value.rule == "package.file.canonical" @PROFILE @given( st.lists( st.recursive( st.none() | st.booleans() | st.integers(-(2**53), 2**53) | st.floats(allow_nan=False, allow_infinity=False) | st.text(), lambda inner: ( st.lists(inner, max_size=3) | st.dictionaries(st.text(), inner, max_size=3) ), max_leaves=8, ), max_size=4, ) ) def test_jsonl_written_reads_back_equal(self, scratch, records): path = scratch / "round.jsonl" path.write_bytes(package.jsonl(records)) assert package.read_jsonl(path) == records class TestReport: def test_an_empty_report_is_true(self): assert package.Report() def test_a_report_with_an_error_is_false(self): rep = package.Report() rep.add("doc.counts", "document.json", "counts do not recompute") assert not rep assert rep.errors == [ { "rule": "doc.counts", "where": "document.json", "message": "counts do not recompute", } ] class TestValidateFixtures: @pytest.mark.parametrize("source", package_dirs(), ids=lambda p: p.name) def test_every_valid_package_validates(self, source, schemas): rep = package.validate(source, schemas, key_for(source)) assert rep.errors == [] def test_a_checks_only_package_validates_without_its_key(self, schemas): assert package.validate(CHECKS_ONLY, schemas).errors == [] def test_the_wrong_key_does_not_match_the_key_id(self, schemas): rep = package.validate(CHECKS_ONLY, schemas, b"\x01" * 32) assert "doc.hash.key" in rules_of(rep) def test_the_zipped_fixture_validates(self, schemas): assert package.validate_zip(TINY_ZIP, schemas).errors == [] @pytest.mark.parametrize("case", invalid_cases(), ids=lambda p: p.name) def test_every_broken_package_is_refused_with_its_rule(self, case, schemas): expected = json.loads((case / "expect.json").read_text())["rule"] assert expected in rules_of(validate_case(case, schemas)) def test_each_broken_package_is_a_folder_or_an_archive(self): for case in invalid_cases(): folder = (case / "package").is_dir() archive = (case / ("package" + package.ZIP_EXTENSION)).is_file() assert folder != archive class TestValidateManifest: def test_a_folder_without_a_manifest_is_refused(self, tmp_path, schemas): root = copy_package(TINY, tmp_path / "pkg") (root / "MANIFEST.json").unlink() rep = package.validate(root, schemas) assert rules_of(rep) == {"package.manifest.missing"} def test_a_manifest_that_breaks_its_schema_is_reported(self, tmp_path, schemas): root = edit_manifest( copy_package(TINY, tmp_path / "pkg"), lambda m: dict(m, format="other/1") ) rep = package.validate(root, schemas) assert rules_of(rep) == {"package.manifest.schema"} assert rep.errors[0]["where"] == "MANIFEST.json" def test_a_manifest_that_is_not_canonical_is_refused(self, tmp_path, schemas): root = copy_package(TINY, tmp_path / "pkg") manifest = json.loads((root / "MANIFEST.json").read_text()) (root / "MANIFEST.json").write_text(json.dumps(manifest, indent=1) + "\n") assert rules_of(package.validate(root, schemas)) == {"package.file.canonical"} def test_a_manifest_key_that_differs_from_the_document_is_reported( self, tmp_path, schemas ): root = edit_manifest( copy_package(TINY, tmp_path / "pkg"), lambda m: dict(m, key="tiny2026tiny-zzzz"), ) assert "package.manifest.key" in rules_of(package.validate(root, schemas)) def test_unsorted_entries_are_reported(self, tmp_path, schemas): root = edit_manifest( copy_package(TINY, tmp_path / "pkg"), lambda m: dict(m, files=m["files"][::-1]), ) assert rules_of(package.validate(root, schemas)) == {"package.manifest.order"} def test_duplicate_entries_are_reported(self, tmp_path, schemas): root = edit_manifest( copy_package(TINY, tmp_path / "pkg"), lambda m: dict(m, files=m["files"] + m["files"][-1:]), ) assert "package.manifest.order" in rules_of(package.validate(root, schemas)) def test_paths_that_collide_under_case_folding_are_reported( self, tmp_path, schemas ): def add(manifest): extra = [ { "path": "assets/A.png", "present": False, "sha256": "0" * 64, "size": 1, }, { "path": "assets/a.png", "present": False, "sha256": "1" * 64, "size": 1, }, ] files = manifest["files"] + extra return dict(manifest, files=sorted(files, key=lambda f: f["path"].encode())) root = edit_manifest(copy_package(TINY, tmp_path / "pkg"), add) rep = package.validate(root, schemas) assert rules_of(rep) == {"package.manifest.order"} assert "collides with assets/A.png" in rep.errors[0]["message"] def test_only_assets_may_be_listed_as_absent(self, tmp_path, schemas): def hide(manifest): files = [ dict(f, present=False) if f["path"] == "references.jsonl" else f for f in manifest["files"] ] return dict(manifest, files=files) root = edit_manifest(copy_package(TINY, tmp_path / "pkg"), hide) messages = [e["message"] for e in package.validate(root, schemas).errors] assert "only assets may be listed without their bytes" in messages assert "a file listed as absent is present" in messages def test_an_absent_asset_that_is_present_is_reported(self, tmp_path, schemas): root = copy_package(HALE, tmp_path / "pkg") present = next((root / "assets").iterdir()).name (root / "assets" / present).write_bytes(b"x") edit_manifest( root, lambda m: dict( m, files=[ dict(f, present=False) if f["path"] == "assets/" + present else f for f in m["files"] ], ), ) rep = package.validate(root, schemas) assert rules_of(rep) == {"package.manifest.absent"} assert rep.errors[0]["message"] == "a file listed as absent is present" def test_a_listed_file_that_is_missing_is_reported(self, tmp_path, schemas): root = copy_package(TINY, tmp_path / "pkg") (root / "references.jsonl").unlink() rep = package.validate(root, schemas) assert rules_of(rep) == {"package.manifest.missing-file"} assert rep.errors[0]["where"] == "references.jsonl" def test_the_manifest_cannot_list_itself(self, tmp_path, schemas): entry = {"path": "MANIFEST.json", "sha256": "0" * 64, "size": 1} root = edit_manifest( copy_package(TINY, tmp_path / "pkg"), lambda m: dict( m, files=sorted(m["files"] + [entry], key=lambda f: f["path"]) ), ) assert "package.path.unsafe" in rules_of(package.validate(root, schemas)) def test_a_wrong_size_is_reported_as_a_hash_mismatch(self, tmp_path, schemas): def lie(manifest): files = [dict(f, size=f["size"] + 1) for f in manifest["files"]] return dict(manifest, files=files) root = edit_manifest(copy_package(TINY, tmp_path / "pkg"), lie) assert rules_of(package.validate(root, schemas)) == {"package.manifest.hash"} def test_a_symbolic_link_is_refused(self, tmp_path, schemas): root = copy_package(TINY, tmp_path / "pkg") (tmp_path / "target").write_bytes(b"x") Path(root / "link").symlink_to(tmp_path / "target") rep = package.validate(root, schemas) assert rules_of(rep) == {"package.path.unsafe"} assert "link: symbolic links are refused" in rep.errors[0]["message"] def test_a_package_past_the_size_limit_is_refused(self, schemas): rep = package.validate(HALE, schemas, limit=100) assert rules_of(rep) == {"package.size"} assert "exceed the limit" in rep.errors[0]["message"] def test_the_budget_counts_every_file_together(self, schemas): total = sum( f["size"] for f in json.loads((TINY / "MANIFEST.json").read_text())["files"] ) assert package.validate(TINY, schemas, limit=total).errors == [] assert rules_of(package.validate(TINY, schemas, limit=total - 1)) == { "package.size" } def set_at(records, position, **fields): records[position] = dict(records[position], **fields) return records def qa_indexes(records): return [i for i, r in enumerate(records) if "qa" in r] def edit_qa(**changes): def edit(records): i = qa_indexes(records)[0] return set_at(records, i, qa=dict(records[i]["qa"], **changes)) return edit def swap_seeds(records): first, second = qa_indexes(records) a, b = records[first]["qa"]["seed"], records[second]["qa"]["seed"] set_at(records, first, qa=dict(records[first]["qa"], seed=b)) return set_at(records, second, qa=dict(records[second]["qa"], seed=a)) def edit_first_qa_receipt(**fields): def edit(records): return set_at(records, qa_indexes(records)[0], **fields) return edit def edit_roster_key(key_id, **fields): def edit(roster): roster["keys"] = [ dict(k, **fields) if k["id"] == key_id else k for k in roster["keys"] ] return roster return edit def edit_document(**fields): def edit(document): return dict(document, **fields) return edit def reverse(records): return records[::-1] def node_id(kind): nodes = read_jsonl(HALE / "nodes.jsonl") return next(n["id"] for n in nodes if n["kind"] == kind) def tweak_node(kind, **fields): def edit(nodes): i = next(i for i, n in enumerate(nodes) if n["kind"] == kind) return set_at(nodes, i, **fields) return edit def withhold_first(kind): def edit(nodes): i = next(i for i, n in enumerate(nodes) if n["kind"] == kind) bare = {k: v for k, v in nodes[i].items() if k != "content"} nodes[i] = dict(bare, withheld=True) return nodes return edit def set_notation(notation): def edit(nodes): i = next(i for i, n in enumerate(nodes) if n["kind"] == "equation") content = dict(nodes[i]["content"], notation=notation) return set_at(nodes, i, content=content) return edit def add_resolve(corrections): last = {k: v for k, v in corrections[-1].items() if k not in ("label", "from")} corrections.append( dict( last, op="resolve", index=len(corrections) + 1, target=node_id("reference"), resolution={"type": "none"}, ) ) return corrections MUTATIONS = { "work-key-suffix-wrong": ( HALE, { "document.json": lambda d: dict( d, work=dict(d["work"], same_as=["doi:10.5555/other"]) ) }, "doc.key.suffix", ), "meta-hash-stale": ( HALE, {"document.json": lambda d: dict(d, meta=dict(d["meta"], volume="15"))}, "doc.hash.meta", ), "fidelity-report-stale": ( HALE, { "document.json": lambda d: dict( d, fidelity=dict( d["fidelity"], counts={"F0": 2, "F1": 3, "F2": 13, "F3": 27} ), ) }, "doc.fidelity.report", ), "hash-algorithm-outside-the-schema": ( HALE, { "document.json": edit_document( hashing={"algorithm": "sha-512", "scheme": "plain"} ) }, "package.schema", ), "withheld-node-keeps-its-content": ( HALE, {"nodes.jsonl": tweak_node("sentence", withheld=True)}, "doc.policy.withheld", ), "full-package-withholds": ( HALE, {"nodes.jsonl": withhold_first("sentence")}, "doc.policy.withheld", ), "derived-line-names-no-formula": ( HALE, {"derived/math.jsonl": lambda ms: set_at(ms, 0, node="zzzzzzz")}, "doc.derived.node", ), "derived-line-claims-it-is-incomplete": ( HALE, {"derived/math.jsonl": lambda ms: set_at(ms, 0, complete=False)}, "doc.derived.math", ), "derived-line-lacks-a-symbol": ( HALE, {"derived/math.jsonl": lambda ms: set_at(ms, 0, symbols=ms[0]["symbols"][1:])}, "doc.derived.math", ), "derived-line-reads-a-formula-that-is-not-tex": ( HALE, {"nodes.jsonl": set_notation("typst")}, "doc.derived.math", ), "root-differs-in-a-package-checked-without-a-key": ( CHECKS_ONLY, {"document.json": edit_document(root="0" * 64)}, "doc.hash.root", ), "roster-public-key-is-not-base64": ( HALE, {"roster.json": edit_roster_key("ana", public="!!")}, "doc.roster.did", ), "id-both-live-and-retired": ( HALE, {"ids.jsonl": lambda ids: [*ids, dict(ids[2], id=node_id("sentence"), rev=13)]}, "doc.id.retired-live", ), "id-successor-unknown": ( HALE, {"ids.jsonl": lambda ids: set_at(ids, 0, successor="aaaaaaa")}, "doc.id.successor", ), "alias-names-a-retired-node": ( HALE, {"ids.jsonl": lambda ids: set_at(ids, 0, successor=ids[2]["id"])}, "doc.id.alias", ), "id-table-out-of-order": (HALE, {"ids.jsonl": reverse}, "doc.order.ids"), "correction-index-gap": ( HALE, {"corrections.jsonl": lambda cs: set_at(cs, 3, index=9)}, "doc.correction.index", ), "correction-id-does-not-derive": ( HALE, {"corrections.jsonl": lambda cs: set_at(cs, 0, reason="Another reason.")}, "doc.correction.id", ), "retired-node-missing-from-ids": ( HALE, {"ids.jsonl": lambda ids: [i for i in ids if i["id"] != "ayea71r"]}, "doc.id.retired-missing", ), "last-correction-misses-the-hash": ( HALE, {"corrections.jsonl": lambda cs: set_at(cs, 0, after="0" * 64)}, "doc.correction.after", ), "resolve-differs-from-the-reference-record": ( HALE, {"corrections.jsonl": add_resolve}, "doc.correction.resolution", ), "witness-id-does-not-derive": ( HALE, { "witnesses.json": lambda w: { "witnesses": [dict(w["witnesses"][0], id="aaaaaaa")] } }, "doc.witness.id", ), "page-names-an-unknown-witness": ( HALE, {"pages.jsonl": lambda ps: set_at(ps, 0, witness="aaaaaaa")}, "doc.page.witness", ), "pages-out-of-order": (HALE, {"pages.jsonl": reverse}, "doc.order.pages"), "location-names-an-unknown-node": ( HALE, {"locations.jsonl": lambda ls: set_at(ls, 0, node="aaaaaaa")}, "doc.location.node", ), "locations-out-of-order": ( HALE, {"locations.jsonl": reverse}, "doc.order.locations", ), "reference-record-names-a-sentence": ( HALE, {"references.jsonl": lambda rs: set_at(rs, 0, node=node_id("sentence"))}, "doc.reference.node", ), "references-out-of-order": ( HALE, {"references.jsonl": reverse}, "doc.order.references", ), "roster-did-does-not-match-the-key": ( HALE, { "roster.json": edit_roster_key( "ana", did="did:key:z6MkhemKN7rMQcgt6wT2eWPyx3vFRS1RUoRziLMnLq2vZ9yi" ) }, "doc.roster.did", ), "receipts-out-of-order": (HALE, {"receipts.jsonl": reverse}, "doc.order.receipts"), "receipt-id-does-not-derive": ( HALE, {"receipts.jsonl": lambda rs: set_at(rs, 0, scope="targeted:other")}, "doc.receipt.id", ), "receipt-names-another-document": ( HALE, {"receipts.jsonl": lambda rs: set_at(rs, 0, doc="other2026document-abcd")}, "doc.receipt.doc", ), "receipt-signature-key-is-not-the-signer": ( HALE, {"receipts.jsonl": lambda rs: set_at(rs, 0, by="cara")}, "doc.receipt.signature", ), "spot-check-names-no-receipt": ( HALE, {"receipts.jsonl": edit_qa(of="zzzzzzzzzzzzz")}, "doc.qa.of", ), "spot-check-scope-names-another-receipt": ( HALE, {"receipts.jsonl": edit_first_qa_receipt(scope="qa:zzzzzzzzzzzzz")}, "doc.qa.of", ), "spot-check-before-the-receipt": ( HALE, {"receipts.jsonl": edit_first_qa_receipt(at="2026-10-01T00:00:00Z")}, "doc.qa.of", ), "spot-check-nodes-are-not-the-sample": ( HALE, {"receipts.jsonl": edit_qa(sample=["aaaaaaa"])}, "doc.qa.sample", ), "spot-check-error-outside-the-sample": ( HALE, { "receipts.jsonl": edit_qa( errors=[{"kind": "word", "node": "aaaaaaa", "note": "x"}] ) }, "doc.qa.sample", ), "spot-check-seed-is-not-base64": ( HALE, {"receipts.jsonl": edit_qa(seed="AAAAA")}, "doc.qa.seed", ), "spot-check-seed-is-not-a-proof": ( HALE, {"receipts.jsonl": edit_qa(seed="AAAA")}, "doc.qa.seed", ), "spot-check-seed-is-another-receipts": ( HALE, {"receipts.jsonl": swap_seeds}, "doc.qa.seed", ), "spot-check-key-is-not-a-spot-check-key": ( HALE, {"receipts.jsonl": edit_qa(key="ana")}, "doc.qa.key", ), "spot-check-key-registered-late": ( HALE, { "roster.json": edit_roster_key( "ben-spot", registered_at="2026-10-12T00:00:00Z" ) }, "doc.qa.key", ), "spot-check-sample-does-not-follow-the-seed": ( HALE, {"receipts.jsonl": edit_qa(rate="0.5")}, "doc.qa.sample", ), } class TestValidateEdited: @pytest.mark.parametrize( ("source", "edits", "rule"), MUTATIONS.values(), ids=MUTATIONS.keys() ) def test_an_edited_package_breaks_the_rule( self, source, edits, rule, tmp_path, schemas ): root = edit_package(tmp_path, source, edits) rep = package.validate(root, schemas, key_for(source)) assert rule in rules_of(rep) def test_receipts_are_not_judged_without_a_roster(self, tmp_path, schemas): root = edit_package(tmp_path, HALE, {"roster.json": None}) assert package.validate(root, schemas).errors == [] def test_a_roster_key_without_a_did_is_not_checked_against_one( self, tmp_path, schemas ): def drop_did(roster): keys = [ {k: v for k, v in key.items() if k != "did"} if key["id"] == "ana" else key for key in roster["keys"] ] return dict(roster, keys=keys) root = edit_package(tmp_path, HALE, {"roster.json": drop_did}) assert package.validate(root, schemas).errors == [] def test_a_file_without_a_final_newline_is_refused(self, tmp_path, schemas): data = (TINY / "references.jsonl").read_bytes().rstrip(b"\n") root = edit_package(tmp_path, TINY, {"references.jsonl": data}) assert rules_of(package.validate(root, schemas)) == {"package.file.newline"} def test_an_empty_optional_derived_file_is_reported(self, tmp_path, schemas): root = edit_package(tmp_path, HALE, {"derived/math.jsonl": b""}) rep = package.validate(root, schemas) assert rules_of(rep) == {"package.file.empty"} assert rep.errors[0]["where"] == "derived/math.jsonl" def test_a_derived_record_is_checked_against_its_schema(self, tmp_path, schemas): root = edit_package( tmp_path, HALE, {"derived/math.jsonl": lambda ms: set_at(ms, 0, form="scienting-math/2")}, ) rep = package.validate(root, schemas) assert rules_of(rep) == {"package.schema"} assert rep.errors[0]["where"].startswith("derived/math.jsonl:1") def test_a_checks_only_package_carries_no_corrections(self, tmp_path, schemas): corrections = (HALE / "corrections.jsonl").read_bytes() root = edit_package(tmp_path, CHECKS_ONLY, {"corrections.jsonl": corrections}) rep = package.validate(root, schemas, key_for(CHECKS_ONLY)) assert any( e["rule"] == "doc.policy.withheld" and e["where"] == "corrections.jsonl" for e in rep.errors ) def test_a_checks_only_package_carries_no_derived_files(self, tmp_path, schemas): math = (HALE / "derived" / "math.jsonl").read_bytes().split(b"\n")[0] + b"\n" root = edit_package(tmp_path, CHECKS_ONLY, {"derived/math.jsonl": math}) rep = package.validate(root, schemas, key_for(CHECKS_ONLY)) assert any( e["rule"] == "doc.policy.withheld" and e["where"] == "derived/math.jsonl" for e in rep.errors ) def test_a_checks_only_policy_wants_every_leaf_withheld_under_keyed_hashes( self, tmp_path, schemas ): root = edit_package( tmp_path, HALE, {"document.json": edit_document(policy="checks-only")} ) rep = package.validate(root, schemas) by_rule = {(e["rule"], e["where"]) for e in rep.errors} assert ("doc.policy.withheld", "nodes.jsonl") in by_rule assert ("doc.policy.keyed", "document.json") in by_rule assert ("doc.policy.withheld", "derived/math.jsonl") in by_rule def test_suspects_sort_by_id_and_name_their_witness(self, tmp_path, schemas): suspect = json.loads((FIXTURES / "records" / "suspect.json").read_text()) later = dict(suspect, id="zzzzzzzzzzzzz", witness="aaaaaaa") earlier = dict(suspect, id="aaaaaaaaaaaaa") data = package.jsonl([later, earlier]) root = edit_package(tmp_path, HALE, {"suspects.jsonl": data}) rep = package.validate(root, schemas) assert rules_of(rep) == {"doc.order.suspects", "doc.suspect.witness"} def test_a_suspect_is_valid_when_its_witness_is_the_packages( self, tmp_path, schemas ): suspect = json.loads((FIXTURES / "records" / "suspect.json").read_text()) root = edit_package( tmp_path, HALE, {"suspects.jsonl": package.jsonl([suspect])} ) assert package.validate(root, schemas).errors == [] @pytest.fixture(scope="module") def doc(): return package.read_state(HALE).doc() @pytest.fixture(scope="module") def lines(): return read_jsonl(HALE / "derived" / "math.jsonl") class TestDerivedFormulas: def test_an_equation_is_named_by_a_null_run(self, doc, lines): equation = next(m for m in lines if m["run"] is None) formula = package.derived_formula(doc, equation["node"], None) assert formula == doc.nodes[equation["node"]]["content"] assert formula["notation"] == "tex" def test_a_math_run_is_named_by_its_index(self, doc, lines): run = next(m for m in lines if m["run"] is not None) formula = package.derived_formula(doc, run["node"], run["run"]) assert formula["kind"] == "math" assert formula == doc.nodes[run["node"]]["content"][run["run"]] def test_unknown_nodes_name_nothing(self, doc): assert package.derived_formula(doc, "zzzzzzz", None) is None def test_a_run_past_the_end_names_nothing(self, doc, lines): run = next(m for m in lines if m["run"] is not None) assert package.derived_formula(doc, run["node"], 99) is None def test_a_run_that_is_not_math_names_nothing(self, doc, lines): run = next(m for m in lines if m["run"] is not None) content = doc.nodes[run["node"]]["content"] text = next(i for i, r in enumerate(content) if r["kind"] != "math") assert package.derived_formula(doc, run["node"], text) is None def test_a_null_run_on_a_sentence_names_nothing(self, doc, lines): run = next(m for m in lines if m["run"] is not None) assert package.derived_formula(doc, run["node"], None) is None def test_a_run_of_an_equation_names_nothing(self, doc, lines): equation = next(m for m in lines if m["run"] is None) assert package.derived_formula(doc, equation["node"], 0) is None def test_withheld_text_names_nothing(self, lines): withheld = package.read_state(CHECKS_ONLY).doc() run = next(m for m in lines if m["run"] is not None) assert package.derived_formula(withheld, run["node"], run["run"]) is None @pytest.mark.parametrize( ("tree", "keys", "opaque"), [ (["sym", "x"], ["x"], False), (["opaque"], [], True), (["rel", ["sym", "a"], "=", ["sym", "b"]], ["a", "b"], False), ([["sym", "a"], ["sym", "b"]], ["a", "b"], False), (["add", ["sym", "x"], ["pow", ["opaque"], ["num", "2"]]], ["x"], True), (["sym"], [], False), (["sym", 7], [], False), ([], [], False), ("text", [], False), (["num", "1"], [], False), (["sym", "y", ["sym", "z"]], ["y", "z"], False), ], ) def test_tree_facts_lists_sym_keys_in_document_order(self, tree, keys, opaque): assert package.tree_facts(tree) == (keys, opaque) def test_tree_facts_walks_a_deep_tree_without_recursion(self): tree = ["sym", "leaf"] for _ in range(20000): tree = ["neg", tree] assert package.tree_facts(tree) == (["leaf"], False) def test_derived_lines_of_the_fixture_agree_with_their_trees(self, lines): for line in lines: keys, opaque = package.tree_facts(line["tree"]) assert sorted(set(keys)) == sorted(line["symbols"]) assert line["complete"] != opaque class TestState: def test_reads_the_state_a_correction_starts_from(self): state = package.read_state(HALE) assert state.key == HALE.name assert state.rev == 12 assert [c["index"] for c in state.corrections] == list(range(1, 13)) assert len(state.nodes) == 75 assert {r["node"] for r in state.references} == { r["node"] for r in read_jsonl(HALE / "references.jsonl") } assert state.ids == read_jsonl(HALE / "ids.jsonl") def test_nodes_come_without_their_values(self): for node in package.read_state(HALE).nodes: assert not { "text_hash", "match_hash", "align_key", "own_hash", "node_hash", } & set(node) def test_recomputed_values_are_the_stored_ones(self): state = package.read_state(HALE) stored = {n["id"]: n for n in read_jsonl(HALE / "nodes.jsonl")} for nid, values in state.index().values.items(): assert all(stored[nid][k] == v for k, v in values.items()) def test_optional_files_that_are_absent_read_as_empty(self): state = package.read_state(TINY) assert state.corrections == [] assert state.ids == [] def test_history_items_follow_the_corrections(self): corrections = read_jsonl(HALE / "corrections.jsonl") items = package.history_items(corrections) assert items[0] == ["correction", 1, corrections[0]["id"]] assert len(items) == len(corrections) document = json.loads((HALE / "document.json").read_text()) assert crypto.history_root(items) == document["history"] def test_the_root_hash_is_the_root_nodes_node_hash(self): nodes = read_jsonl(HALE / "nodes.jsonl") (root,) = (n for n in nodes if n["parent"] is None) document = json.loads((HALE / "document.json").read_text()) assert root["node_hash"] == document["root"] def make_zip(path, entries, *, compression=zipfile.ZIP_STORED): """Write (name, data, mode) entries as a producer does: dated 1980-01-01, no extra field.""" with zipfile.ZipFile(path, "w") as zf: for name, data, mode in entries: zi = zipfile.ZipInfo(name, date_time=(1980, 1, 1, 0, 0, 0)) zi.compress_type = compression zi.create_system = 3 zi.external_attr = mode << 16 zf.writestr(zi, data) return path def patch_flags(archive, *, set_bits=0, clear_bits=0): """Rewrite the general-purpose flags in the central directory of an archive.""" data = bytearray(archive.read_bytes()) start = data.find(b"PK\x01\x02") while start != -1: flags = int.from_bytes(data[start + 8 : start + 10], "little") flags = (flags | set_bits) & ~clear_bits data[start + 8 : start + 10] = flags.to_bytes(2, "little") start = data.find(b"PK\x01\x02", start + 4) archive.write_bytes(bytes(data)) def tiny_entries(): entries = [] for path in sorted(p for p in TINY.rglob("*") if p.is_file()): rel = path.relative_to(TINY).as_posix() entries.append((TINY_KEY + "/" + rel, path.read_bytes(), 0o644)) return entries def relocated(entries, folder): return [(folder + "/" + n.partition("/")[2], d, m) for n, d, m in entries] class TestZip: def test_is_zip_wants_an_existing_file_with_a_zip_name(self, tmp_path): assert package.is_zip(str(TINY_ZIP)) assert not package.is_zip(str(TINY)) assert not package.is_zip(str(tmp_path / "missing.zip")) (tmp_path / "upper.ZIP").write_bytes(b"") assert package.is_zip(str(tmp_path / "upper.ZIP")) (tmp_path / "plain.txt").write_bytes(b"") assert not package.is_zip(str(tmp_path / "plain.txt")) def test_unpacks_to_the_folder_it_was_made_from(self, tmp_path): root = package.read_zip(TINY_ZIP, tmp_path) assert Path(root) == tmp_path / TINY_KEY made = sorted(p.relative_to(root) for p in Path(root).rglob("*") if p.is_file()) want = sorted(p.relative_to(TINY) for p in TINY.rglob("*") if p.is_file()) assert made == want for rel in want: assert (Path(root) / rel).read_bytes() == (TINY / rel).read_bytes() def test_write_zip_reproduces_the_fixture_archive(self, tmp_path): digest = package.write_zip(TINY, tmp_path / "again.zip") assert (tmp_path / "again.zip").read_bytes() == TINY_ZIP.read_bytes() assert digest == sha256_hex(TINY_ZIP.read_bytes()) def test_write_zip_orders_entries_by_utf8_bytes_under_the_key(self, tmp_path): package.write_zip(HALE, tmp_path / "hale.zip") with zipfile.ZipFile(tmp_path / "hale.zip") as zf: names = [i.filename for i in zf.infolist()] assert names == sorted(names, key=lambda n: n.encode()) assert {n.partition("/")[0] for n in names} == {HALE.name} assert all( i.date_time == (1980, 1, 1, 0, 0, 0) and not i.extra for i in zf.infolist() ) def test_write_zip_refuses_an_unsafe_name(self, tmp_path): root = copy_package(TINY, tmp_path / "pkg") (root / "back\\slash").write_bytes(b"x") with pytest.raises(Refusal, match="unsafe path") as raised: package.write_zip(root, tmp_path / "out.zip") assert raised.value.rule == "package.path.unsafe" def test_write_zip_refuses_a_symbolic_link(self, tmp_path): root = copy_package(TINY, tmp_path / "pkg") Path(root / "link").symlink_to(root / "document.json") with pytest.raises(Refusal, match="symbolic links") as raised: package.write_zip(root, tmp_path / "out.zip") assert raised.value.rule == "package.path.unsafe" def test_directory_entries_are_allowed(self, tmp_path, schemas): entries = [*tiny_entries(), (TINY_KEY + "/assets/", b"", 0o755)] archive = make_zip(tmp_path / "dirs.zip", entries) assert package.validate_zip(archive, schemas).errors == [] def test_deflated_entries_are_allowed(self, tmp_path, schemas): archive = make_zip( tmp_path / "deflated.zip", tiny_entries(), compression=zipfile.ZIP_DEFLATED ) assert package.validate_zip(archive, schemas).errors == [] @pytest.mark.parametrize( ("name", "entries", "message"), [ ( "two-folders", lambda: [*tiny_entries(), ("other2026example-abcd/x.txt", b"x", 0o644)], "more than one top-level folder", ), ( "stray-file", lambda: [*tiny_entries(), ("other2026/x.txt", b"x", 0o644)], "named by the key", ), ( "folder-not-a-key", lambda: relocated(tiny_entries(), "Tiny Example"), "named by the key", ), ( "no-folder", lambda: [(n.partition("/")[2], d, m) for n, d, m in tiny_entries()], "named by the key", ), ( "dot-dot", lambda: [*tiny_entries(), (TINY_KEY + "/assets/../../x", b"x", 0o644)], "unsafe path", ), ( "unsafe-directory", lambda: [*tiny_entries(), (TINY_KEY + "/a/../b/", b"", 0o755)], "unsafe path", ), ( "symlink", lambda: [ *tiny_entries(), (TINY_KEY + "/assets/link", b"document.json", 0o120777), ], "symbolic links are refused", ), ("empty", list, "no entries"), ], ) def test_a_crafted_archive_is_refused(self, tmp_path, name, entries, message): archive = make_zip(tmp_path / (name + ".zip"), entries()) with pytest.raises(Refusal, match=message) as raised: package.read_zip(archive, tmp_path / "out") assert raised.value.rule == "package.zip.entry" assert not (tmp_path / "out").exists() def test_a_duplicate_entry_is_refused(self, tmp_path): with pytest.warns(UserWarning, match="Duplicate name"): archive = make_zip( tmp_path / "duplicate.zip", [*tiny_entries(), tiny_entries()[0]] ) with pytest.raises(Refusal, match="duplicate entry") as raised: package.read_zip(archive, tmp_path / "out") assert raised.value.rule == "package.zip.entry" def test_an_encrypted_entry_is_refused(self, tmp_path): archive = make_zip(tmp_path / "encrypted.zip", tiny_entries()) patch_flags(archive, set_bits=0x1) with pytest.raises(Refusal, match="encrypted entries are refused") as raised: package.read_zip(archive, tmp_path / "out") assert raised.value.rule == "package.zip.entry" def test_an_entry_that_is_neither_stored_nor_deflated_is_refused(self, tmp_path): archive = tmp_path / "bzip.zip" with zipfile.ZipFile(archive, "w", zipfile.ZIP_BZIP2) as zf: zf.writestr(TINY_KEY + "/document.json", bz2.compress(b"x")) with pytest.raises(Refusal, match="stored or deflated") as raised: package.read_zip(archive, tmp_path / "out") assert raised.value.rule == "package.zip.entry" def test_a_name_that_is_not_marked_utf8_is_refused(self, tmp_path): archive = make_zip( tmp_path / "latin.zip", [(TINY_KEY + "/é.json", b"x", 0o644)] ) patch_flags(archive, clear_bits=0x800) with pytest.raises(Refusal, match="not marked as UTF-8") as raised: package.read_zip(archive, tmp_path / "out") assert raised.value.rule == "package.zip.entry" def test_an_archive_past_the_size_limit_is_refused(self, tmp_path): with pytest.raises(Refusal, match="expands past the limit") as raised: package.read_zip(TINY_ZIP, tmp_path / "out", limit=100) assert raised.value.rule == "package.zip.size" def test_the_limit_counts_every_entry_together(self, tmp_path): with zipfile.ZipFile(TINY_ZIP) as zf: total = sum(i.file_size for i in zf.infolist()) package.read_zip(TINY_ZIP, tmp_path / "exact", limit=total) with pytest.raises(Refusal) as raised: package.read_zip(TINY_ZIP, tmp_path / "short", limit=total - 1) assert raised.value.rule == "package.zip.size" def test_bytes_that_are_not_an_archive_are_refused(self, tmp_path): archive = tmp_path / "not-a.zip" archive.write_bytes(b"PK\x03\x04 this is not an archive") with pytest.raises(Refusal, match="not a zip archive") as raised: package.read_zip(archive, tmp_path / "out") assert raised.value.rule == "package.zip.entry" def test_an_entry_that_needs_a_later_zip_version_is_refused(self, tmp_path): archive = tmp_path / "version.zip" with zipfile.ZipFile(archive, "w") as zf: for name, data, _ in tiny_entries(): zi = zipfile.ZipInfo(name, date_time=(1980, 1, 1, 0, 0, 0)) zi.extract_version = 98 zf.writestr(zi, data) with pytest.raises(Refusal, match="not a zip archive") as raised: package.read_zip(archive, tmp_path / "out") assert raised.value.rule == "package.zip.entry" def test_deflated_bytes_that_do_not_inflate_are_refused(self, tmp_path): archive = make_zip( tmp_path / "bad.zip", tiny_entries(), compression=zipfile.ZIP_DEFLATED ) with zipfile.ZipFile(archive) as zf: info = next(i for i in zf.infolist() if i.compress_size > 8) start = info.header_offset + 30 + len(info.filename.encode()) + len(info.extra) data = bytearray(archive.read_bytes()) data[start : start + 8] = b"\xff" * 8 archive.write_bytes(bytes(data)) with pytest.raises(Refusal) as raised: package.read_zip(archive, tmp_path / "out") assert raised.value.rule == "package.zip.entry" assert info.filename in str(raised.value) def test_validate_zip_reports_a_folder_not_named_by_the_key( self, tmp_path, schemas ): archive = make_zip( tmp_path / "other.zip", relocated(tiny_entries(), "other2026example-abcd") ) rep = package.validate_zip(archive, schemas) assert any( e["rule"] == "package.zip.entry" and e["message"] == "the top-level folder is not named by the key" for e in rep.errors ) def test_validate_zip_of_an_archive_without_a_manifest(self, tmp_path, schemas): entries = [e for e in tiny_entries() if not e[0].endswith("/MANIFEST.json")] rep = package.validate_zip(make_zip(tmp_path / "bare.zip", entries), schemas) assert rules_of(rep) == {"package.manifest.missing"} def test_validate_zip_reports_a_manifest_that_cannot_be_read( self, tmp_path, schemas ): entries = [ (n, b"not json\n" if n.endswith("/MANIFEST.json") else d, m) for n, d, m in tiny_entries() ] rep = package.validate_zip(make_zip(tmp_path / "bad.zip", entries), schemas) assert {"package.file.canonical", "package.zip.entry"} <= rules_of(rep) def test_validate_zip_reports_a_refused_archive_as_an_error( self, tmp_path, schemas ): rep = package.validate_zip(TINY_ZIP, schemas, limit=100) assert rules_of(rep) == {"package.zip.size"} assert rep.errors[0]["where"] == ""