Skip to content

Run frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦

C
15.3 KB
Raw Blame
import json
import os
import tempfile
import unittest
from pathlib import Path

from tools.qpack_install_policy import (
    JOURNAL,
    MANIFEST,
    MAX_FILE_SIZE,
    QpackFile,
    QpackInstallError,
    begin_install,
    commit_file,
    parse_manifest,
    publish_manifest,
    resume_decision,
    validate_delivery,
)


class QpackInstallPolicyTest(unittest.TestCase):
    def setUp(self):
        self.temporary = tempfile.TemporaryDirectory()
        self.addCleanup(self.temporary.cleanup)
        self.root = Path(self.temporary.name) / "model.qpack"
        self.raw = self.manifest({
            "model.safetensors": 7,
            "packed_experts/layout.json": 5,
        })
        self.plan = parse_manifest(self.raw, "hf:owner/model@0123456789abcdef")
        self.sessions = []
        self.addCleanup(self.close_sessions)

    def close_sessions(self):
        for session in reversed(self.sessions):
            session.close()

    def begin(self, plan=None):
        session = begin_install(self.root, plan or self.plan)
        self.sessions.append(session)
        return session

    @staticmethod
    def manifest(files, **extra):
        value = {
            "magic": "QPACK",
            "version": 1,
            "modelName": "tiny-qwen",
            "sourceCheckpoint": "owner/model@0123456789abcdef",
            "quantBits": 4,
            "quantGroupSize": 64,
            "files": files,
        }
        value.update(extra)
        return json.dumps(value, sort_keys=True, separators=(",", ":")).encode()

    def file(self, name):
        return next(file for file in self.plan.files if file.name == name)

    def write_partial(self, session, file, data):
        decision = resume_decision(session, file)
        decision.partial_path.write_bytes(data)
        return decision.partial_path

    def commit_all(self, session):
        for file in self.plan.files:
            self.write_partial(session, self.file(file.name),
                               bytes([file.size]) * file.size)
            commit_file(session, file)

    def test_manifest_is_sorted_and_bound_to_exact_bytes_and_source(self):
        reordered = self.raw + b"\n"
        other = parse_manifest(reordered, self.plan.source_id)
        self.assertEqual([file.name for file in other.files],
                         ["model.safetensors", "packed_experts/layout.json"])
        self.assertNotEqual(other.manifest_sha256, self.plan.manifest_sha256)
        self.assertNotEqual(parse_manifest(self.raw, "local:fixture"), self.plan)

    def test_manifest_rejects_duplicate_keys(self):
        raw = (b'{"magic":"QPACK","version":1,"files":'
               b'{"packed_experts/layout.json":5,'
               b'"packed_experts/layout.json":6}}')
        with self.assertRaisesRegex(QpackInstallError, "duplicate JSON key"):
            parse_manifest(raw, "local:fixture")

    def test_manifest_rejects_nonfinite_numbers_and_escaped_nuls(self):
        raw = self.raw.replace(b'"quantBits":4', b'"quantBits":NaN')
        with self.assertRaisesRegex(QpackInstallError, "non-finite"):
            parse_manifest(raw, "local:fixture")
        value = json.loads(self.raw)
        value["modelName"] = "tiny\x00qwen"
        with self.assertRaisesRegex(QpackInstallError, "embedded NUL"):
            parse_manifest(json.dumps(value).encode(), "local:fixture")

    def test_manifest_rejects_unsafe_and_reserved_paths(self):
        invalid = [
            "../escape", "/absolute", "a//b", "a/./b", "a/../b",
            "a\\b", "manifest.json", ".qpack-install.json",
            ".qpack-install.lock", ".manifest.json.part", "nul\x00name",
            "C:/escape", "C:escape", "packed_experts/CON",
            "packed_experts/aux.txt", "packed_experts/trailing. ",
            "packed_experts/file:stream", "packed_experts/a?.bin",
            "packed_experts/caf\u00e9.bin",
        ]
        for name in invalid:
            files = {"packed_experts/layout.json": 5, name: 1}
            with self.subTest(name=name), self.assertRaises(QpackInstallError):
                parse_manifest(self.manifest(files), "local:fixture")

    def test_manifest_rejects_invalid_sizes_and_layout_is_not_required(self):
        for size in (True, False, 0, -1, 1.5, MAX_FILE_SIZE + 1):
            with self.subTest(size=size), self.assertRaises(QpackInstallError):
                parse_manifest(self.manifest({
                    "packed_experts/layout.json": size,
                }), "local:fixture")
        # The production Qwen3-Next-80B manifest declares no layout.json;
        # Swiftlet's reader never consults the files table for it.
        plan = parse_manifest(
            self.manifest({"model.safetensors": 7}), "local:fixture")
        self.assertEqual(plan.files, (QpackFile("model.safetensors", 7),))
        with self.assertRaisesRegex(QpackInstallError, "source_id"):
            parse_manifest(self.raw, "")

    def test_real_swiftlet_manifests_are_accepted_with_or_without_layout(self):
        fixtures = Path(__file__).parent / "fixtures"
        # Qwen3-Next-80B, as published on Swiftlet's mirror: 49 entries,
        # model.safetensors plus 48 layer blobs, no layout.json, no aux files.
        plan = parse_manifest(
            (fixtures / "swiftlet_qwen3_next_80b_manifest.json").read_bytes(),
            "mirror:fixture")
        names = [file.name for file in plan.files]
        self.assertEqual(len(names), 49)
        self.assertNotIn("packed_experts/layout.json", names)
        self.assertEqual(
            names,
            ["model.safetensors"]
            + [f"packed_experts/layer_{index:02d}.bin" for index in range(48)])
        self.assertTrue(all(file.size > 0 for file in plan.files))
        # Qwen3.6-35B, same writer, declares layout.json and the tokenizer.
        plan = parse_manifest(
            (fixtures / "swiftlet_qwen36_35b_manifest.json").read_bytes(),
            "mirror:fixture")
        self.assertEqual(len(plan.files), 47)
        self.assertIn(QpackFile("packed_experts/layout.json", 2048), plan.files)

    def test_declared_layout_with_wrong_size_cannot_commit_or_publish(self):
        session = self.begin()
        layout = self.file("packed_experts/layout.json")
        self.write_partial(session, layout, b"x" * (layout.size + 1))
        with self.assertRaisesRegex(QpackInstallError, "not complete"):
            commit_file(session, layout)
        self.write_partial(session, layout, b"x" * (layout.size - 1))
        with self.assertRaisesRegex(QpackInstallError, "not complete"):
            commit_file(session, layout)
        self.write_partial(session, self.file("model.safetensors"), b"w" * 7)
        commit_file(session, self.file("model.safetensors"))
        with self.assertRaisesRegex(QpackInstallError, "before all files"):
            publish_manifest(session, self.raw)
        self.assertFalse((self.root / MANIFEST).exists())

    def test_manifest_matches_swiftlet_required_fields_and_file_limit(self):
        for field in ("modelName", "sourceCheckpoint"):
            value = json.loads(self.raw)
            value.pop(field)
            with self.subTest(field=field), self.assertRaisesRegex(
                    QpackInstallError, "supported QPACK"):
                parse_manifest(json.dumps(value).encode(), "local:fixture")
        for field in ("quantBits", "quantGroupSize"):
            value = json.loads(self.raw)
            value[field] = True
            with self.subTest(field=field), self.assertRaisesRegex(
                    QpackInstallError, field):
                parse_manifest(json.dumps(value).encode(), "local:fixture")
        too_many = {"packed_experts/layout.json": 5}
        too_many.update({f"packed_experts/file-{index}.bin": 1
                         for index in range(8192)})
        with self.assertRaisesRegex(QpackInstallError, "files table"):
            parse_manifest(self.manifest(too_many), "local:fixture")

    def test_manifest_rejects_plan_wide_path_collisions(self):
        collisions = [
            {"packed_experts/layout.json": 5, "foo": 1, "foo.part": 1},
            {"packed_experts/layout.json": 5, "foo": 1, "foo/bar": 1},
            {"packed_experts/layout.json": 5, "Foo": 1, "foo": 1},
        ]
        for files in collisions:
            with self.subTest(files=files), self.assertRaisesRegex(
                    QpackInstallError, "namespace collision"):
                parse_manifest(self.manifest(files), "local:fixture")

    def test_begin_binds_partials_and_rejects_unbound_or_mismatched_work(self):
        self.root.mkdir()
        (self.root / "model.safetensors.part").write_bytes(b"old")
        with self.assertRaisesRegex(QpackInstallError, "unbound"):
            begin_install(self.root, self.plan)
        (self.root / "model.safetensors.part").unlink()

        session = self.begin()
        with self.assertRaisesRegex(QpackInstallError, "locked"):
            begin_install(self.root, self.plan)
        session.close()
        other_raw = self.manifest({
            "model.safetensors": 8,
            "packed_experts/layout.json": 5,
        })
        other = parse_manifest(other_raw, self.plan.source_id)
        with self.assertRaisesRegex(QpackInstallError, "another source or manifest"):
            begin_install(self.root, other)

    def test_malformed_journal_and_closed_session_fail_closed(self):
        session = self.begin()
        session.close()
        (self.root / JOURNAL).write_text('{"schema":"wrong"}', encoding="utf-8")
        with self.assertRaisesRegex(QpackInstallError, "journal is invalid"):
            begin_install(self.root, self.plan)
        with self.assertRaisesRegex(QpackInstallError, "closed or invalid"):
            resume_decision(session, self.plan.files[0])

    def test_resume_decisions_cover_missing_partial_and_committed_files(self):
        session = self.begin()
        file = self.file("model.safetensors")
        decision = resume_decision(session, file)
        self.assertEqual((decision.action, decision.offset), ("restart", 0))

        decision.partial_path.write_bytes(b"abc")
        decision = resume_decision(session, file)
        self.assertEqual((decision.action, decision.offset), ("resume", 3))

        decision.partial_path.write_bytes(b"too-large")
        decision = resume_decision(session, file)
        self.assertEqual((decision.action, decision.offset), ("restart", 0))

        decision.partial_path.write_bytes(b"1234567")
        commit_file(session, file)
        decision = resume_decision(session, file)
        self.assertEqual((decision.action, decision.offset), ("complete", 7))

    def test_relative_root_remains_stable_after_working_directory_change(self):
        original = Path.cwd()
        self.addCleanup(os.chdir, original)
        os.chdir(self.temporary.name)
        session = begin_install(Path("relative") / "model.qpack", self.plan)
        self.sessions.append(session)
        os.chdir(original)
        decision = resume_decision(session, self.plan.files[0])
        self.assertTrue(decision.partial_path.is_absolute())
        self.assertEqual(decision.offset, 0)

    def test_delivery_requires_exact_offsets_bounds_and_final_length(self):
        file = QpackFile("model.safetensors", 10)
        self.assertEqual(validate_delivery(file, 3, 3, 4), 7)
        self.assertEqual(validate_delivery(file, 3, 3, 7, complete=True), 10)
        invalid = [
            (-1, 0, 1, False),
            (3, 0, 7, True),
            (3, 3, 8, False),
            (3, 3, 6, True),
        ]
        for requested, delivered, size, complete in invalid:
            with self.subTest(values=(requested, delivered, size, complete)), \
                    self.assertRaises(QpackInstallError):
                validate_delivery(file, requested, delivered, size,
                                  complete=complete)

    def test_incomplete_commit_never_publishes_a_final_path(self):
        session = self.begin()
        file = self.file("model.safetensors")
        partial = self.write_partial(session, file, b"short")
        with self.assertRaisesRegex(QpackInstallError, "not complete"):
            commit_file(session, file)
        self.assertTrue(partial.exists())
        self.assertFalse(self.root.joinpath(file.name).exists())

    def test_manifest_is_published_last_and_completion_is_idempotent(self):
        session = self.begin()
        first = self.plan.files[0]
        self.write_partial(session, first, bytes([first.size]) * first.size)
        commit_file(session, first)
        with self.assertRaisesRegex(QpackInstallError, "all files"):
            publish_manifest(session, self.raw)
        self.assertFalse((self.root / MANIFEST).exists())

        remaining = self.plan.files[1]
        self.write_partial(session, remaining,
                           bytes([remaining.size]) * remaining.size)
        commit_file(session, remaining)
        publish_manifest(session, self.raw)
        self.assertEqual((self.root / MANIFEST).read_bytes(), self.raw)
        self.assertFalse((self.root / JOURNAL).exists())

        session.close()
        complete_session = self.begin()
        self.assertTrue(complete_session.complete)
        self.assertFalse((self.root / JOURNAL).exists())

    def test_crash_boundaries_remain_recoverable(self):
        session = self.begin()
        first = self.plan.files[0]
        self.write_partial(session, first, bytes([first.size]) * first.size)
        self.assertEqual(resume_decision(session, first).offset, first.size)
        session.close()
        session = self.begin()
        commit_file(session, first)
        self.assertEqual(resume_decision(session, first).action, "complete")

        for file in self.plan.files[1:]:
            self.write_partial(session, file, bytes([file.size]) * file.size)
            commit_file(session, file)
        stale_manifest_temp = self.root / ".manifest.json.part"
        stale_manifest_temp.write_bytes(b"interrupted")
        publish_manifest(session, self.raw)
        self.assertEqual((self.root / MANIFEST).read_bytes(), self.raw)
        self.assertFalse(stale_manifest_temp.exists())

    def test_existing_manifest_cleans_a_stale_matching_journal(self):
        session = self.begin()
        self.commit_all(session)
        (self.root / MANIFEST).write_bytes(self.raw)
        self.assertTrue((self.root / JOURNAL).exists())
        session.close()
        complete_session = self.begin()
        self.assertTrue(complete_session.complete)
        self.assertFalse((self.root / JOURNAL).exists())

    @unittest.skipUnless(hasattr(os, "symlink"), "symlinks unsupported")
    def test_manifest_symlink_cannot_mark_install_complete(self):
        session = self.begin()
        self.commit_all(session)
        external = Path(self.temporary.name) / "external-manifest.json"
        external.write_bytes(self.raw)
        os.symlink(external, self.root / MANIFEST)
        with self.assertRaisesRegex(QpackInstallError, "symlink"):
            publish_manifest(session, self.raw)
        self.assertTrue((self.root / JOURNAL).exists())

    @unittest.skipUnless(hasattr(os, "symlink"), "symlinks unsupported")
    def test_symlinked_artifact_parent_is_rejected(self):
        outside = Path(self.temporary.name) / "outside"
        outside.mkdir()
        self.root.mkdir()
        os.symlink(outside, self.root / "packed_experts", target_is_directory=True)
        with self.assertRaisesRegex(QpackInstallError, "symlink"):
            begin_install(self.root, self.plan)


if __name__ == "__main__":
    unittest.main()