feat: DGR-017 - Lock the GLM-5.2 Max target and alpha contract

tests/test_glm_alpha_target.py

@@ -0,0 +1,851 @@
+"""DGR-017 — the locked GLM-5.2 Max target, resource plan, and alpha contract.
+
+These tests are deterministic, offline, GPU-free, and download-free. They assert
+against the *pinned* manifest, so they fail if a later agent swaps the artifact,
+loosens the memory accounting, or moves a threshold after seeing a result.
+
+The planner tests are written as a reproduction of the roadmap's published tables.
+That is the point: if the arithmetic here ever stops reproducing them, either the
+roadmap or the planner is lying, and the test says which numbers changed.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+
+import pytest
+
+from meshnet_node.glm_alpha import (
+    AGGREGATE_HARD_FIT_FLOOR_GIB,
+    ALPHA_CONTRACT_ID,
+    ALPHA_QUANTIZATION,
+    ALPHA_SHARD_COUNT,
+    MIN_LINK_RATE_GBPS,
+    RECOMMENDED_LINK_RATE_GBPS,
+    RESERVE_FLOOR_GIB,
+    AlphaContractError,
+    GlmTargetError,
+    NodeMemory,
+    ResourcePlanError,
+    compute_contract_digest,
+    kv_bytes,
+    load_alpha_contract,
+    load_architecture_snapshot,
+    load_locked_target,
+    load_target_manifest,
+    parse_alpha_contract,
+    parse_architecture_snapshot,
+    parse_target_manifest,
+    plan_route,
+    plan_seams,
+    plan_topology,
+    require_contract_target,
+    require_pinned_target,
+    seal_contract,
+)
+from meshnet_node.glm_alpha.manifest import GIB
+
+# The revisions observed and pinned by DGR-017 on 2026-07-13.
+SOURCE_REVISION = "b4734de4facf877f85769a911abafc5283eab3d9"
+GGUF_REVISION = "abc55e72527792c6e77069c99b4cb7de16fa9f23"
+TOTAL_BYTES = 216_715_360_960
+
+
+@pytest.fixture(scope="module")
+def manifest():
+    return load_target_manifest()
+
+
+@pytest.fixture(scope="module")
+def snapshot():
+    return load_architecture_snapshot()
+
+
+@pytest.fixture(scope="module")
+def contract():
+    return load_alpha_contract()
+
+
+@pytest.fixture
+def manifest_doc(manifest):
+    return copy.deepcopy(dict(manifest.raw))
+
+
+@pytest.fixture
+def snapshot_doc(snapshot):
+    return copy.deepcopy(dict(snapshot.raw))
+
+
+@pytest.fixture
+def contract_doc(contract):
+    return copy.deepcopy(dict(contract.raw))
+
+
+# --------------------------------------------------------------------------
+# Identity: the exact artifact, pinned
+# --------------------------------------------------------------------------
+
+
+def test_manifest_pins_both_repositories_by_exact_revision(manifest):
+    assert manifest.source_repo_id == "zai-org/GLM-5.2"
+    assert manifest.source_revision == SOURCE_REVISION
+    assert manifest.gguf_repo_id == "unsloth/GLM-5.2-GGUF"
+    assert manifest.gguf_revision == GGUF_REVISION
+    assert manifest.quantization == ALPHA_QUANTIZATION == "UD-IQ1_S"
+    assert manifest.source_license == "mit"
+    assert manifest.gguf_license == "mit"
+
+
+def test_manifest_resolves_all_six_shards_with_sizes_hashes_and_urls(manifest):
+    assert len(manifest.shards) == ALPHA_SHARD_COUNT == 6
+    assert [shard.index for shard in manifest.shards] == [1, 2, 3, 4, 5, 6]
+
+    for shard in manifest.shards:
+        assert shard.size_bytes > 0
+        assert len(shard.sha256) == 64
+        assert shard.url.startswith(f"https://huggingface.co/{manifest.gguf_repo_id}/resolve/")
+        assert GGUF_REVISION in shard.url, "a shard URL must resolve at the pinned revision"
+
+    digests = {shard.sha256 for shard in manifest.shards}
+    assert len(digests) == 6, "six distinct shards must have six distinct content digests"
+
+
+def test_manifest_aggregate_bytes_are_exact_and_self_consistent(manifest):
+    assert manifest.total_bytes == TOTAL_BYTES
+    assert sum(shard.size_bytes for shard in manifest.shards) == TOTAL_BYTES
+    assert round(manifest.total_gib, 3) == 201.832
+    assert round(manifest.total_gb, 3) == 216.715
+
+
+def test_manifest_records_the_iq1_m_diagnostic_fallback_without_promoting_it(manifest):
+    fallback = manifest.raw["diagnostic_fallback"]
+    assert fallback["quantization"] == "UD-IQ1_M"
+    assert fallback["total_bytes"] == 228_492_966_624
+    assert fallback["total_bytes"] > manifest.total_bytes
+    assert "does not satisfy" in fallback["policy"]
+
+
+def test_manifest_forbids_home_storage(manifest):
+    assert manifest.raw["storage"]["mounted_storage_only"] is True
+    assert "/home" in manifest.raw["storage"]["forbidden_path_prefixes"]
+
+
+# --------------------------------------------------------------------------
+# Identity: what the manifest must reject
+# --------------------------------------------------------------------------
+
+
+def test_a_changed_source_revision_is_rejected(manifest, snapshot, manifest_doc):
+    manifest_doc["source_model"]["revision"] = "0" * 40
+    swapped = parse_target_manifest(manifest_doc)
+
+    with pytest.raises(GlmTargetError, match="does not match the locked alpha revision"):
+        require_pinned_target(
+            swapped,
+            snapshot,
+            expected_source_revision=SOURCE_REVISION,
+            expected_gguf_revision=GGUF_REVISION,
+        )
+
+
+def test_a_changed_gguf_revision_is_rejected(manifest, snapshot, manifest_doc):
+    manifest_doc["gguf_artifact"]["revision"] = "1" * 40
+    swapped = parse_target_manifest(manifest_doc)
+
+    with pytest.raises(GlmTargetError, match="does not match the locked alpha revision"):
+        require_pinned_target(
+            swapped,
+            snapshot,
+            expected_source_revision=SOURCE_REVISION,
+            expected_gguf_revision=GGUF_REVISION,
+        )
+
+
+def test_the_pinned_target_passes_its_own_revision_check(manifest, snapshot):
+    require_pinned_target(
+        manifest,
+        snapshot,
+        expected_source_revision=SOURCE_REVISION,
+        expected_gguf_revision=GGUF_REVISION,
+    )
+
+
+def test_config_metadata_from_a_different_revision_than_the_weights_is_rejected(
+    manifest, snapshot_doc
+):
+    snapshot_doc["source_revision"] = "2" * 40
+    drifted = parse_architecture_snapshot(snapshot_doc)
+
+    with pytest.raises(GlmTargetError, match="must come from one revision"):
+        require_pinned_target(
+            manifest,
+            drifted,
+            expected_source_revision=SOURCE_REVISION,
+            expected_gguf_revision=GGUF_REVISION,
+        )
+
+
+def test_a_branch_name_is_not_an_acceptable_revision_pin(manifest_doc):
+    manifest_doc["gguf_artifact"]["revision"] = "main"
+
+    with pytest.raises(GlmTargetError, match="not an immutable pin"):
+        parse_target_manifest(manifest_doc)
+
+
+def test_a_missing_shard_is_rejected(manifest_doc):
+    manifest_doc["gguf_artifact"]["shards"].pop()
+
+    with pytest.raises(GlmTargetError, match="exactly 6 shards"):
+        parse_target_manifest(manifest_doc)
+
+
+def test_a_shard_replaced_by_a_duplicate_of_another_is_rejected(manifest_doc):
+    shards = manifest_doc["gguf_artifact"]["shards"]
+    # Keep the count at six and the byte total consistent, but drop shard 6's
+    # identity — the shape a lazy "just re-download it" repair takes.
+    shards[5]["index"] = 5
+
+    with pytest.raises(GlmTargetError, match="duplicate shard index"):
+        parse_target_manifest(manifest_doc)
+
+
+def test_two_shards_claiming_the_same_content_digest_are_rejected(manifest_doc):
+    shards = manifest_doc["gguf_artifact"]["shards"]
+    shards[5]["sha256"] = shards[4]["sha256"]
+
+    with pytest.raises(GlmTargetError, match="same content digest"):
+        parse_target_manifest(manifest_doc)
+
+
+def test_an_inconsistent_aggregate_byte_total_is_rejected(manifest_doc):
+    manifest_doc["gguf_artifact"]["total_bytes"] = TOTAL_BYTES - 1
+
+    with pytest.raises(GlmTargetError, match="not self-consistent"):
+        parse_target_manifest(manifest_doc)
+
+
+def test_a_shard_size_edited_to_make_the_model_look_smaller_is_rejected(manifest_doc):
+    # The aggregate is now internally inconsistent, which is exactly the tell.
+    manifest_doc["gguf_artifact"]["shards"][2]["size_bytes"] = 1_000_000
+
+    with pytest.raises(GlmTargetError, match="not self-consistent"):
+        parse_target_manifest(manifest_doc)
+
+
+def test_swapping_in_a_different_quantization_is_rejected(manifest_doc):
+    manifest_doc["alpha_quantization"] = "UD-IQ1_M"
+
+    with pytest.raises(GlmTargetError, match="requires a human contract change"):
+        parse_target_manifest(manifest_doc)
+
+
+def test_a_truncated_sha256_is_rejected(manifest_doc):
+    manifest_doc["gguf_artifact"]["shards"][0]["sha256"] = "abc123"
+
+    with pytest.raises(GlmTargetError, match="64-character hex SHA-256"):
+        parse_target_manifest(manifest_doc)
+
+
+# --------------------------------------------------------------------------
+# Architecture snapshot
+# --------------------------------------------------------------------------
+
+
+def test_snapshot_captures_the_architecture_critical_metadata(snapshot):
+    assert snapshot["model_type"] == "glm_moe_dsa"
+    assert snapshot["num_hidden_layers"] == 78
+    assert snapshot["num_nextn_predict_layers"] == 1
+    assert snapshot["total_artifact_layers"] == 79
+    assert snapshot["dense_layers"] == 3
+    assert snapshot["sparse_moe_layers"] == 75
+    assert snapshot["hidden_size"] == 6144
+    assert snapshot["n_routed_experts"] == 256
+    assert snapshot["num_experts_per_tok"] == 8
+    assert snapshot["n_shared_experts"] == 1
+    assert snapshot["index_topk"] == 2048
+    assert snapshot["index_head_dim"] == 128
+    assert snapshot["max_position_embeddings"] == 1_048_576
+    assert snapshot["vocab_size"] == 154_880
+
+
+def test_snapshot_records_indexshare_roles_for_every_layer(snapshot):
+    assert snapshot["indexer_full_layers"] == 21
+    assert snapshot["indexer_shared_layers"] == 57
+    assert snapshot["indexer_full_layers"] + snapshot["indexer_shared_layers"] == 78
+
+
+def test_mla_cache_width_is_derived_not_asserted(snapshot):
+    assert snapshot["kv_lora_rank"] == 512
+    assert snapshot["qk_rope_head_dim"] == 64
+    assert snapshot["mla_cached_values_per_token_per_layer"] == 576
+
+
+def test_snapshot_hashes_the_config_and_chat_template_bytes(snapshot):
+    assert len(snapshot.file_sha256("config.json")) == 64
+    assert len(snapshot.file_sha256("chat_template.jinja")) == 64
+    assert len(snapshot.file_sha256("tokenizer_config.json")) == 64
+    assert len(snapshot["indexer_types_sha256"]) == 64
+    assert len(snapshot.digest) == 64
+
+
+def test_reasoning_effort_max_is_locked_as_an_observable_rendered_marker(snapshot):
+    reasoning = snapshot.reasoning_effort
+    assert reasoning["alpha_mode"] == "max"
+    assert reasoning["rendered_marker"] == "<|system|>Reasoning Effort: Max"
+    # The template's only non-max level is 'high'; everything else renders Max. So
+    # "the request carried reasoning_effort=max" proves nothing on its own.
+    assert reasoning["default_is_max"] is True
+
+
+def test_folding_the_nextn_layer_into_the_backbone_is_rejected(snapshot_doc):
+    snapshot_doc["architecture"]["total_artifact_layers"] = 78
+
+    with pytest.raises(GlmTargetError, match="NextN layer must be counted"):
+        parse_architecture_snapshot(snapshot_doc)
+
+
+def test_indexshare_roles_that_do_not_cover_every_layer_are_rejected(snapshot_doc):
+    snapshot_doc["architecture"]["indexer_full_layers"] = 20
+
+    with pytest.raises(GlmTargetError, match="exactly one IndexShare role"):
+        parse_architecture_snapshot(snapshot_doc)
+
+
+def test_a_route_with_no_full_indexer_producer_is_rejected(snapshot_doc):
+    snapshot_doc["architecture"]["indexer_full_layers"] = 0
+    snapshot_doc["architecture"]["indexer_shared_layers"] = 78
+
+    with pytest.raises(GlmTargetError, match="no index for its Shared consumers"):
+        parse_architecture_snapshot(snapshot_doc)
+
+
+def test_a_contradictory_mla_width_is_rejected(snapshot_doc):
+    snapshot_doc["architecture"]["mla_cached_values_per_token_per_layer"] = 512
+
+    with pytest.raises(GlmTargetError, match="kv_lora_rank"):
+        parse_architecture_snapshot(snapshot_doc)
+
+
+def test_a_snapshot_missing_an_architecture_critical_field_is_rejected(snapshot_doc):
+    del snapshot_doc["architecture"]["n_routed_experts"]
+
+    with pytest.raises(GlmTargetError, match="architecture-critical field"):
+        parse_architecture_snapshot(snapshot_doc)
+
+
+def test_a_snapshot_that_drops_reasoning_effort_max_is_rejected(snapshot_doc):
+    snapshot_doc["reasoning_effort"]["alpha_mode"] = "high"
+
+    with pytest.raises(GlmTargetError, match="does not lock reasoning_effort=max"):
+        parse_architecture_snapshot(snapshot_doc)
+
+
+# --------------------------------------------------------------------------
+# KV planning
+# --------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    ("context", "mla_only", "optimized", "conservative", "conservative_f16"),
+    [
+        (16_384, 0.73, 0.77, 0.89, 1.68),
+        (131_072, 5.83, 6.18, 7.12, 13.41),
+        (1_048_576, 46.62, 49.41, 56.98, 107.25),
+    ],
+)
+def test_kv_planner_reproduces_the_published_roadmap_table(
+    snapshot, context, mla_only, optimized, conservative, conservative_f16
+):
+    def gib(**kwargs):
+        return kv_bytes(snapshot, context_tokens=context, concurrency=1, **kwargs) / GIB
+
+    assert round(gib(include_indexer=False), 2) == mla_only
+    assert round(gib(indexer_layout="optimized"), 2) == optimized
+    assert round(gib(indexer_layout="conservative"), 2) == conservative
+    assert round(gib(indexer_layout="conservative", dtype="F16"), 2) == conservative_f16
+
+
+def test_alpha_budgets_the_conservative_indexer_layout(snapshot):
+    """Alpha must budget the implementation it may actually get, not the ideal one."""
+    optimized = kv_bytes(snapshot, indexer_layout="optimized")
+    conservative = kv_bytes(snapshot, indexer_layout="conservative")
+
+    assert conservative > optimized
+    assert kv_bytes(snapshot) == conservative, "the default must be the conservative layout"
+
+
+def test_kv_scales_with_concurrency(snapshot):
+    assert kv_bytes(snapshot, concurrency=2) == 2 * kv_bytes(snapshot, concurrency=1)
+
+
+def test_an_unlocked_kv_dtype_is_rejected(snapshot):
+    with pytest.raises(ResourcePlanError, match="alpha locks Q8_0"):
+        kv_bytes(snapshot, dtype="Q4_0")
+
+
+@pytest.mark.parametrize("bad", [0, -1, True, 1.5])
+def test_kv_rejects_non_positive_or_non_integer_dimensions(snapshot, bad):
+    with pytest.raises(ResourcePlanError, match="positive integers"):
+        kv_bytes(snapshot, context_tokens=bad)
+
+
+# --------------------------------------------------------------------------
+# Memory accounting: unified memory is one pool
+# --------------------------------------------------------------------------
+
+
+def test_unified_memory_is_counted_once():
+    node = NodeMemory.from_host("strix-halo", system_ram_gib=128.0, unified=True)
+
+    assert node.physical_usable_gib == 128.0, "integrated-GPU memory is not extra memory"
+
+
+def test_adding_integrated_gpu_memory_to_system_ram_is_rejected():
+    with pytest.raises(ResourcePlanError, match="double-counts one pool"):
+        NodeMemory.from_host(
+            "strix-halo",
+            system_ram_gib=128.0,
+            gpu_memory_gib=96.0,
+            unified=True,
+        )
+
+
+def test_a_discrete_gpu_does_add_its_own_memory():
+    node = NodeMemory.from_host(
+        "workstation", system_ram_gib=64.0, gpu_memory_gib=24.0, unified=False
+    )
+
+    assert node.physical_usable_gib == 88.0
+
+
+def test_the_same_machine_counted_twice_in_a_route_is_rejected(manifest, snapshot):
+    twin = [
+        NodeMemory.from_host("box-a", system_ram_gib=128.0, unified=True),
+        NodeMemory.from_host("box-a", system_ram_gib=128.0, unified=True),
+    ]
+
+    with pytest.raises(ResourcePlanError, match="counted twice"):
+        plan_route(manifest, snapshot, twin)
+
+
+@pytest.mark.parametrize("bad", [float("nan"), float("inf"), -1.0, True])
+def test_node_memory_rejects_non_finite_or_invalid_capacity(bad):
+    with pytest.raises(ResourcePlanError, match="finite positive"):
+        NodeMemory(name="bad-host", physical_usable_gib=bad, unified=True)
+
+
+# --------------------------------------------------------------------------
+# Reserve and topology
+# --------------------------------------------------------------------------
+
+
+def test_the_reserve_floor_binds_on_small_nodes():
+    small = NodeMemory(name="32", physical_usable_gib=32.0, unified=True)
+
+    assert small.reserve_gib == RESERVE_FLOOR_GIB == 8.0  # 20% of 32 is only 6.4
+    assert small.placement_budget_gib == 24.0
+
+
+def test_the_reserve_fraction_binds_on_large_nodes():
+    large = NodeMemory(name="128", physical_usable_gib=128.0, unified=True)
+
+    assert large.reserve_gib == 25.6  # 20% of 128 clears the 8 GiB floor
+    assert large.placement_budget_gib == 102.4
+
+
+@pytest.mark.parametrize(
+    ("tier", "reserve", "budget", "arithmetic_minimum", "recommended"),
+    [
+        (32.0, 8.0, 24.0, 9, 10),
+        (48.0, 9.6, 38.4, 6, 6),
+        (64.0, 12.8, 51.2, 4, 5),
+        (96.0, 19.2, 76.8, 3, 3),
+        (128.0, 25.6, 102.4, 2, 3),
+    ],
+)
+def test_topology_planner_reproduces_the_published_tier_table(
+    manifest, snapshot, tier, reserve, budget, arithmetic_minimum, recommended
+):
+    plan = plan_topology(manifest, snapshot, physical_usable_gib=tier)
+
+    assert round(plan.reserve_gib, 2) == reserve
+    assert round(plan.placement_budget_gib, 2) == budget
+    assert plan.arithmetic_minimum_nodes == arithmetic_minimum
+    assert plan.recommended_nodes == recommended
+    assert round(plan.weight_gib, 3) == 201.832
+    assert round(plan.kv_gib, 2) == 0.89  # 16K, concurrency 1, Q8_0, conservative DSA
+
+
+def test_the_recommended_topologies_are_five_by_64_or_three_by_96_or_128(manifest, snapshot):
+    assert plan_topology(manifest, snapshot, physical_usable_gib=64.0).recommended_nodes == 5
+    assert plan_topology(manifest, snapshot, physical_usable_gib=96.0).recommended_nodes == 3
+    assert plan_topology(manifest, snapshot, physical_usable_gib=128.0).recommended_nodes == 3
+
+
+def test_two_by_128_is_an_arithmetic_minimum_not_a_recommendation(manifest, snapshot):
+    plan = plan_topology(manifest, snapshot, physical_usable_gib=128.0)
+
+    assert plan.arithmetic_minimum_nodes == 2
+    assert plan.recommended_nodes == 3
+    assert not plan.is_arithmetic_minimum_topology, (
+        "2x128 GiB leaves no room for endpoint/tensor imbalance; it is a fit probe that "
+        "requires measured placement evidence, not the alpha recommendation"
+    )
+
+
+@pytest.mark.parametrize("bad", [0.9, float("nan"), float("inf"), True])
+def test_an_invalid_placement_imbalance_is_rejected(manifest, snapshot, bad):
+    with pytest.raises(ResourcePlanError, match="less than an equal share"):
+        plan_topology(manifest, snapshot, physical_usable_gib=64.0, imbalance_factor=bad)
+
+
+# --------------------------------------------------------------------------
+# Route fit
+# --------------------------------------------------------------------------
+
+
+def test_the_recommended_five_by_64_route_fits(manifest, snapshot):
+    nodes = [
+        NodeMemory.from_host(f"node-{i}", system_ram_gib=64.0, unified=True) for i in range(5)
+    ]
+
+    fit = plan_route(manifest, snapshot, nodes)
+
+    assert fit.fits
+    assert fit.meets_hard_fit_floor
+    assert fit.no_single_node_can_admit_target
+    assert fit.reasons == ()
+
+
+def test_224_gib_aggregate_is_a_hard_fit_floor_not_an_operational_envelope(manifest, snapshot):
+    """Exactly 224 GiB of aggregate memory clears the floor and still does not fit.
+
+    This is the whole reason the roadmap calls 224 GiB an *experimental hard-fit
+    floor*. It is the number you get by ignoring the per-node reserve — and once
+    the reserve is applied, the weights alone no longer have anywhere to go.
+    """
+    nodes = [
+        NodeMemory.from_host(f"node-{i}", system_ram_gib=112.0, unified=True) for i in range(2)
+    ]
+
+    fit = plan_route(manifest, snapshot, nodes)
+
+    assert fit.aggregate_usable_gib == AGGREGATE_HARD_FIT_FLOOR_GIB == 224.0
+    assert fit.meets_hard_fit_floor
+    assert not fit.fits, "224 GiB aggregate does not fit the target once reserves are honoured"
+    assert any("below the" in reason for reason in fit.reasons)
+
+
+def test_a_route_too_small_for_the_target_does_not_fit(manifest, snapshot):
+    nodes = [
+        NodeMemory.from_host(f"node-{i}", system_ram_gib=64.0, unified=True) for i in range(3)
+    ]
+
+    fit = plan_route(manifest, snapshot, nodes)
+
+    assert not fit.fits
+    assert not fit.meets_hard_fit_floor
+
+
+def test_a_route_where_one_node_could_hold_everything_is_not_distributed_alpha(
+    manifest, snapshot
+):
+    nodes = [
+        NodeMemory.from_host(f"node-{i}", system_ram_gib=512.0, unified=True) for i in range(2)
+    ]
+
+    fit = plan_route(manifest, snapshot, nodes)
+
+    assert fit.fits
+    assert not fit.no_single_node_can_admit_target
+    assert any("single-host run" in reason for reason in fit.reasons)
+
+
+def test_a_single_node_is_not_a_route(manifest, snapshot):
+    with pytest.raises(ResourcePlanError, match="at least two physical nodes"):
+        plan_route(
+            manifest,
+            snapshot,
+            [NodeMemory.from_host("solo", system_ram_gib=512.0, unified=True)],
+        )
+
+
+# --------------------------------------------------------------------------
+# Seams and network
+# --------------------------------------------------------------------------
+
+
+def test_seam_bytes_match_the_published_activation_arithmetic(snapshot):
+    plan = plan_seams(snapshot, node_count=4, context_tokens=16_384)
+
+    assert plan.seam_count == 3, "four nodes imply three serial seams"
+    assert plan.bytes_per_token_per_seam == 12_288  # 6144 x bf16
+    assert plan.prefill_bytes_per_seam == 192 * 1024**2  # 192 MiB
+    assert plan.decode_bytes_per_seam_per_token == 12 * 1024  # 12 KiB
+    assert plan.dsa_sideband_bytes_per_query == 8 * 1024  # 2048 int32 = 8 KiB
+
+
+def test_2_5_gbe_is_the_alpha_minimum_and_10_gbe_is_recommended(snapshot):
+    gigabit = plan_seams(snapshot, node_count=3, link_rate_gbps=1.0)
+    minimum = plan_seams(snapshot, node_count=3, link_rate_gbps=MIN_LINK_RATE_GBPS)
+    recommended = plan_seams(snapshot, node_count=3, link_rate_gbps=RECOMMENDED_LINK_RATE_GBPS)
+
+    assert not gigabit.meets_alpha_minimum, "1 GbE is fit-only evidence, not an alpha route"
+    assert minimum.meets_alpha_minimum
+    assert not minimum.is_recommended_link
+    assert recommended.meets_alpha_minimum
+    assert recommended.is_recommended_link
+
+
+def test_serial_seam_latency_is_modelled_separately_from_bandwidth(snapshot):
+    """Decode moves 12 KiB a token. What it pays is hops, not bytes."""
+    fast_link = plan_seams(snapshot, node_count=5, link_rate_gbps=10.0, per_hop_latency_ms=2.0)
+    slow_link = plan_seams(snapshot, node_count=5, link_rate_gbps=2.5, per_hop_latency_ms=2.0)
+
+    # Quadrupling the link rate barely touches decode: the payload is tiny.
+    assert fast_link.decode_bandwidth_share_ms_per_token < 0.05
+    assert slow_link.decode_bandwidth_share_ms_per_token < 0.2
+
+    # Latency is unchanged by link rate and scales with the number of serial seams.
+    assert fast_link.decode_latency_ms_per_token == slow_link.decode_latency_ms_per_token == 8.0
+
+    # A 10 GbE claim cannot buy back a hop.
+    assert fast_link.decode_latency_ms_per_token > fast_link.decode_bandwidth_share_ms_per_token
+
+
+def test_adding_a_node_adds_a_serial_seam_to_every_decoded_token(snapshot):
+    three = plan_seams(snapshot, node_count=3, per_hop_latency_ms=1.0)
+    five = plan_seams(snapshot, node_count=5, per_hop_latency_ms=1.0)
+
+    assert three.decode_latency_ms_per_token == 2.0
+    assert five.decode_latency_ms_per_token == 4.0
+
+
+@pytest.mark.parametrize("bad", [float("nan"), float("inf"), 0.0, True])
+def test_seam_planner_rejects_invalid_link_telemetry(snapshot, bad):
+    with pytest.raises(ResourcePlanError, match="finite and positive"):
+        plan_seams(snapshot, node_count=3, link_rate_gbps=bad)
+
+
+# --------------------------------------------------------------------------
+# The immutable alpha contract
+# --------------------------------------------------------------------------
+
+
+def test_the_packaged_contract_is_sealed_and_verifies(contract):
+    assert contract.contract_id == ALPHA_CONTRACT_ID
+    assert contract.contract_version == 1
+    assert contract.locked_by == "DGR-017"
+    assert contract.raw["locked_before_target_execution"] is True
+    assert contract.digest == compute_contract_digest(contract.raw)
+
+
+def test_the_contract_locks_the_same_target_as_the_manifest(contract, manifest, snapshot):
+    assert contract.target["source_revision"] == manifest.source_revision
+    assert contract.target["gguf_revision"] == manifest.gguf_revision
+    assert contract.target["quantization"] == manifest.quantization
+    assert contract.target["total_bytes"] == manifest.total_bytes
+    assert contract.target["target_manifest_sha256"] == manifest.digest
+    assert contract.target["architecture_snapshot_sha256"] == snapshot.digest
+    assert contract.target["reasoning_effort"] == "max"
+
+
+def test_the_packaged_target_documents_are_cross_bound_to_the_contract():
+    contract, manifest, snapshot = load_locked_target()
+    assert contract.target["target_manifest_sha256"] == manifest.digest
+    assert contract.target["architecture_snapshot_sha256"] == snapshot.digest
+
+
+def test_coordinated_shard_hash_substitution_is_rejected_by_contract(
+    contract, manifest_doc, snapshot
+):
+    manifest_doc["gguf_artifact"]["shards"][0]["sha256"] = "0" * 64
+    substituted = parse_target_manifest(manifest_doc)
+
+    with pytest.raises(AlphaContractError, match="target_manifest_sha256"):
+        require_contract_target(contract, substituted, snapshot)
+
+
+def test_internally_consistent_architecture_substitution_is_rejected_by_contract(
+    contract, manifest, snapshot_doc
+):
+    snapshot_doc["architecture"]["hidden_size"] = 8192
+    substituted = parse_architecture_snapshot(snapshot_doc)
+
+    with pytest.raises(AlphaContractError, match="architecture_snapshot_sha256"):
+        require_contract_target(contract, manifest, substituted)
+
+
+def test_contract_id_cannot_be_changed_even_when_resealed(contract_doc):
+    contract_doc["contract_id"] = "glm-5.2-max-alpha/v2"
+    contract_doc = seal_contract(contract_doc)
+
+    with pytest.raises(AlphaContractError, match="contract_id"):
+        parse_alpha_contract(contract_doc)
+
+
+def test_max_reasoning_mode_cannot_be_changed_even_when_resealed(contract_doc):
+    contract_doc["target"]["reasoning_effort"] = "high"
+    contract_doc = seal_contract(contract_doc)
+
+    with pytest.raises(AlphaContractError, match="reasoning_effort='max'"):
+        parse_alpha_contract(contract_doc)
+
+
+@pytest.mark.parametrize("field", ["schema_version", "contract_version"])
+def test_boolean_contract_versions_are_rejected_even_when_resealed(contract_doc, field):
+    contract_doc[field] = True
+    contract_doc = seal_contract(contract_doc)
+
+    with pytest.raises(AlphaContractError, match="version"):
+        parse_alpha_contract(contract_doc)
+
+
+def test_wheel_metadata_includes_nested_glm_alpha_json_resources():
+    pyproject = Path(__file__).parents[1] / "packages/node/pyproject.toml"
+    text = pyproject.read_text(encoding="utf-8")
+    assert '"meshnet_node.glm_alpha" = ["data/*.json"]' in text
+
+
+def test_the_contract_locks_every_roadmap_acceptance_section(contract):
+    for section in (
+        "identity_and_fit",
+        "semantic_correctness",
+        "target_run",
+        "performance",
+        "reliability",
+        "storage",
+    ):
+        assert contract.section(section)
+
+
+def test_the_contract_locks_the_roadmap_thresholds(contract):
+    assert contract.threshold("identity_and_fit", "min_node_reserve_fraction") == 0.20
+    assert contract.threshold("identity_and_fit", "min_node_reserve_gib") == 8.0
+    assert contract.threshold("identity_and_fit", "aggregate_hard_fit_floor_gib") == 224.0
+    assert (
+        contract.threshold("identity_and_fit", "aggregate_floor_class")
+        == "experimental_hard_fit_floor"
+    )
+    assert contract.threshold("identity_and_fit", "forbid_double_counted_unified_memory") is True
+
+    assert contract.threshold("semantic_correctness", "min_greedy_token_agreement") == 0.90
+    assert contract.threshold("semantic_correctness", "min_mean_state_cosine_similarity") == 0.999
+    assert contract.threshold("semantic_correctness", "dense_attention_fallback_satisfies_alpha") is False
+
+    assert contract.threshold("target_run", "context_tokens") == 16_384
+    assert contract.threshold("target_run", "kv_dtype") == "Q8_0"
+    assert contract.threshold("target_run", "min_link_rate_gbps") == MIN_LINK_RATE_GBPS
+    assert contract.threshold("target_run", "recommended_link_rate_gbps") == RECOMMENDED_LINK_RATE_GBPS
+    assert contract.threshold("target_run", "min_output_tokens") == 512
+
+    assert contract.threshold("performance", "min_median_decode_tokens_per_second") == 0.5
+    assert contract.threshold("performance", "max_ttft_seconds_at_4096_prompt") == 600
+    assert contract.threshold("performance", "quality_pass_with_speed_fail_verdict") == "stop"
+
+    assert contract.threshold("reliability", "synthetic_workers_satisfy_alpha") is False
+    assert contract.threshold("storage", "forbidden_path_prefixes") == ["/home"]
+
+
+def test_the_contract_offers_only_alpha_or_stop(contract):
+    assert sorted(contract.verdicts) == ["alpha", "stop"]
+
+
+def test_lowering_the_speed_floor_after_seeing_a_result_is_rejected(contract_doc):
+    """The exact move the contract exists to prevent."""
+    contract_doc["performance"]["min_median_decode_tokens_per_second"] = 0.05
+
+    with pytest.raises(AlphaContractError, match="modified since it was locked"):
+        parse_alpha_contract(contract_doc)
+
+
+def test_relabelling_a_speed_failure_as_a_pass_is_rejected(contract_doc):
+    contract_doc["performance"]["quality_pass_with_speed_fail_verdict"] = "alpha"
+
+    with pytest.raises(AlphaContractError, match="modified since it was locked"):
+        parse_alpha_contract(contract_doc)
+
+
+def test_admitting_the_dense_attention_fallback_after_the_fact_is_rejected(contract_doc):
+    contract_doc["semantic_correctness"]["dense_attention_fallback_satisfies_alpha"] = True
+
+    with pytest.raises(AlphaContractError, match="modified since it was locked"):
+        parse_alpha_contract(contract_doc)
+
+
+def test_relaxing_the_per_node_reserve_after_the_fact_is_rejected(contract_doc):
+    contract_doc["identity_and_fit"]["min_node_reserve_gib"] = 1.0
+
+    with pytest.raises(AlphaContractError, match="modified since it was locked"):
+        parse_alpha_contract(contract_doc)
+
+
+def test_re_pointing_the_contract_at_a_different_artifact_is_rejected(contract_doc):
+    contract_doc["target"]["gguf_revision"] = "9" * 40
+
+    with pytest.raises(AlphaContractError, match="modified since it was locked"):
+        parse_alpha_contract(contract_doc)
+
+
+def test_an_unsealed_contract_is_rejected(contract_doc):
+    del contract_doc["contract_sha256"]
+
+    with pytest.raises(AlphaContractError, match="cannot prove it predates"):
+        parse_alpha_contract(contract_doc)
+
+
+def test_a_contract_not_locked_before_execution_is_rejected(contract_doc):
+    contract_doc["locked_before_target_execution"] = False
+    contract_doc = seal_contract(contract_doc)
+
+    with pytest.raises(AlphaContractError, match="not a contract"):
+        parse_alpha_contract(contract_doc)
+
+
+def test_a_third_verdict_is_rejected(contract_doc):
+    contract_doc["verdicts"] = ["alpha", "stop", "partial"]
+    contract_doc = seal_contract(contract_doc)
+
+    with pytest.raises(AlphaContractError, match="third outcome"):
+        parse_alpha_contract(contract_doc)
+
+
+def test_a_dropped_acceptance_section_is_rejected(contract_doc):
+    del contract_doc["reliability"]
+    contract_doc = seal_contract(contract_doc)
+
+    with pytest.raises(AlphaContractError, match="missing locked acceptance section"):
+        parse_alpha_contract(contract_doc)
+
+
+def test_resealing_a_mutated_contract_changes_its_digest(contract, contract_doc):
+    """Tamper-evidence, not tamper-proofing: a rewrite is legal but never silent."""
+    contract_doc["performance"]["min_median_decode_tokens_per_second"] = 0.05
+    resealed = seal_contract(contract_doc)
+
+    # It parses — nothing in-repo can stop a determined rewrite of file plus digest.
+    reparsed = parse_alpha_contract(resealed)
+
+    # But the digest moved, so the change is a visible diff on a file whose entire
+    # purpose is to not change, and the contract_id still claims to be v1.
+    assert reparsed.digest != contract.digest
+
+
+def test_an_unknown_threshold_cannot_be_invented_at_read_time(contract):
+    with pytest.raises(AlphaContractError, match="is not locked"):
+        contract.threshold("performance", "min_decode_tokens_per_second_v2")
+
+
+# --------------------------------------------------------------------------
+# The tests themselves stay offline
+# --------------------------------------------------------------------------
+
+
+def test_the_packaged_data_files_are_valid_json_and_load_offline(manifest, snapshot, contract):
+    """No network, no model, no GPU: the whole target contract is reviewable offline."""
+    assert json.dumps(manifest.to_dict())
+    assert json.dumps(snapshot.to_dict())
+    assert json.dumps(contract.to_dict())
+    assert len(manifest.digest) == 64