Skip to main content

graphforge_cli/
hub_fixture_artifacts.rs

1//! Rust-owned deterministic artifact generation for the public Hub fixture.
2
3use crate::hub_publish::publication::{
4    ManifestInputs, PACKAGE_MEDIA_TYPE, build_manifest, derive_summary, digest_bytes,
5    export_module_packages, object_descriptor, summary_reference, verify_full,
6};
7use graphforge_api::{
8    ActivationMode, ActivationProfileChangeRequest, DiscoveryOntologyModuleRequest, GraphForge,
9    ModuleAdoptionRequest, OntologyAuthorityExpectation, OntologyDoc, OperationId,
10    PortableExportRequest, PortableImportRequest, PortableLimits, PortableOutput,
11    PortableSelection, PortableSelectionProfile, ResearchCorpusSize, UpdateResearchMetadataRequest,
12    WorkspaceResearchMetadata, WriteContext, repack_verified_expanded_portable,
13    resolve_discovered_ontology_module,
14};
15use graphforge_discovery::{
16    DISCOVERY_FORMAT, DiscoveryLimits, DiscoveryManifest, ExactIdentity, ObjectDescriptor,
17    PORTABLE_FORMAT, PORTABLE_MEDIA_TYPE, PROJECT_SUMMARY_MEDIA_TYPE, PortablePackageReference,
18    ProjectSummary, ProtocolVersion, RefSet, RepositoryIdentity, RepositoryRef, Sha256Digest,
19};
20use serde::Serialize;
21use sha2::{Digest as _, Sha256};
22use std::collections::BTreeMap;
23use std::fmt::Write as _;
24use std::fs;
25use std::path::{Path, PathBuf};
26use uuid::Uuid;
27
28/// Stable generator contract. Git commit evidence belongs to the invoking checkout,
29/// rather than caller-controlled artifact metadata.
30pub const GENERATOR_CONTRACT: &str = "graphforge-hub-fixture-generator/1";
31/// Object location base used by the checked-in fixture. Locations are transport,
32/// never identity, so a different base changes the manifest locations and their bindings.
33pub const DEFAULT_LOCATION_BASE: &str = "https://data.graphforge.sh/objects/sha256/";
34const OBJECT_PATH: &str = "objects/opendata-openalex.gfpb";
35const SUMMARY_PATH: &str = "objects/opendata-openalex.summary.json";
36const MODULE_OBJECT_PREFIX: &str = "objects/ontology-module-";
37const MODULE_OBJECT_SUFFIX: &str = ".gfpb";
38const FIXED_FILES: [&str; 5] = [
39    "fixture.json",
40    "manifest.json",
41    "refs.json",
42    OBJECT_PATH,
43    SUMMARY_PATH,
44];
45
46/// GraphForge-owned permanent module ID in the `ont_` form (#2215). The fixture is a
47/// maintainer-curated mirror, so the ID is never minted in the data source's domain.
48const MODULE_ID: &str = "https://graphforge.sh/ont_drqf2xw8w33cxaxj";
49const MODULE_VERSION: &str = "2026.01";
50const SOURCE_METADATA_OPERATION: u128 = 0x91f2_1a60_d89e_54e1_a000_0000_0000_0001;
51const SOURCE_ADOPTION_OPERATION: u128 = 0x91f2_1a60_d89e_54e1_a000_0000_0000_0002;
52const SOURCE_PROFILE_OPERATION: u128 = 0x91f2_1a60_d89e_54e1_a000_0000_0000_0003;
53
54#[derive(Debug, Serialize)]
55struct GeneratorIdentity<'a> {
56    contract: &'a str,
57    crate_name: &'a str,
58    source_digest: String,
59}
60
61#[derive(Debug, Serialize)]
62struct SourceIdentity {
63    tree_digest: String,
64    package_digest: String,
65}
66
67/// One per-module package object advertised by the manifest.
68#[derive(Debug, PartialEq, Serialize)]
69struct ModuleObjectRecord {
70    ontology_id: String,
71    version: String,
72    content_digest: String,
73    package_digest: String,
74    object_digest: String,
75    object_length: u64,
76    object_path: String,
77}
78
79#[derive(Debug, Serialize)]
80struct FixtureMetadata<'a> {
81    format: &'a str,
82    generator: GeneratorIdentity<'a>,
83    source: SourceIdentity,
84    object_path: &'a str,
85    object_digest: String,
86    object_length: u64,
87    package_digest: String,
88    summary_path: &'a str,
89    summary_digest: String,
90    summary_object_digest: String,
91    summary_object_length: u64,
92    module_objects: Vec<ModuleObjectRecord>,
93    manifest_digest: String,
94    location_base: &'a str,
95}
96
97fn err(error: impl std::fmt::Display) -> String {
98    error.to_string()
99}
100
101fn module_document() -> Result<OntologyDoc, String> {
102    serde_json::from_value(serde_json::json!({
103        "ontology_id": MODULE_ID,
104        "version": MODULE_VERSION,
105        "entity_types": [
106            {"name": "Work", "abstract": false, "parent": null},
107            {"name": "Author", "abstract": false, "parent": null},
108            {"name": "Institution", "abstract": false, "parent": null}
109        ],
110        "relation_types": [{"name": "AUTHORED", "src": "Author", "dst": "Work"}],
111        "properties": [],
112        "constraints": [],
113        "migrations": []
114    }))
115    .map_err(err)
116}
117
118/// Synthetic public research metadata. These are fixture values, not product
119/// behavior; `update_research_metadata` canonicalizes them.
120fn fixture_research_metadata() -> WorkspaceResearchMetadata {
121    let mut metadata = WorkspaceResearchMetadata::empty();
122    metadata.title = Some("OpenAlex".into());
123    metadata.authors = vec!["OurResearch".into()];
124    metadata.languages = vec!["en".into()];
125    metadata.subjects = vec!["scholarly-communication".into()];
126    metadata.source_types = vec!["bibliographic-database".into()];
127    metadata.ontologies = vec![MODULE_ID.into()];
128    metadata.license = Some("CC0-1.0".into());
129    metadata.corpus_size = Some(ResearchCorpusSize {
130        node_count: Some(1_000),
131        relationship_count: Some(2_500),
132        source_count: Some(1),
133        artifact_count: Some(0),
134    });
135    metadata.created_at = Some("2026-01-01T00:00:00.000000Z".into());
136    metadata.updated_at = Some("2026-01-01T00:00:00.000000Z".into());
137    metadata
138}
139
140/// Rebuild the synthetic expanded source package through the public facade and
141/// replace `destination` with it.
142///
143/// The Project is durable, every write identity is fixed, and the export is the
144/// complete expanded package, so repeated rebuilds are byte-identical. The new
145/// tree is built and fully verified beside `destination` and swapped in only
146/// when complete; a failed swap restores the previous tree.
147pub fn rebuild_source(destination: &Path) -> Result<(), String> {
148    let limits = PortableLimits::default();
149    let parent = destination
150        .parent()
151        .ok_or("fixture source destination has no parent directory")?;
152    fs::create_dir_all(parent).map_err(err)?;
153    let scratch = tempfile::tempdir().map_err(err)?;
154    let project = scratch.path().join("project");
155    fs::create_dir(&project).map_err(err)?;
156    let mut graph = GraphForge::new(project.to_str()).map_err(err)?;
157    graph
158        .update_research_metadata(UpdateResearchMetadataRequest {
159            context: write_context(SOURCE_METADATA_OPERATION),
160            metadata: fixture_research_metadata(),
161        })
162        .map_err(err)?;
163    let candidate = graph
164        .create_ontology_module(module_document()?, Vec::new(), None)
165        .map_err(err)?;
166    graph
167        .adopt_ontology_module(
168            &ModuleAdoptionRequest {
169                authority: authority(&graph, SOURCE_ADOPTION_OPERATION)?,
170                candidate,
171            },
172            None,
173        )
174        .map_err(err)?;
175    let (_, activation) = graph.ontology_activation_profile().map_err(err)?;
176    graph
177        .change_ontology_activation_profile(
178            &ActivationProfileChangeRequest {
179                authority: authority(&graph, SOURCE_PROFILE_OPERATION)?,
180                profile_default: ActivationMode::Advisory,
181                activation,
182            },
183            None,
184        )
185        .map_err(err)?;
186    // Stage beside the destination so the final swap is a same-volume rename.
187    let staging = tempfile::Builder::new()
188        .prefix(".hub-source-rebuild-")
189        .tempdir_in(parent)
190        .map_err(err)?;
191    let staged = staging.path().join("source");
192    graph
193        .export_portable(
194            &PortableExportRequest {
195                selection: PortableSelection::Current,
196                output_path: staged.clone(),
197                representation: PortableOutput::Expanded,
198                profile: PortableSelectionProfile::Complete,
199                subset: None,
200                limits,
201            },
202            None,
203            |_| {},
204        )
205        .map_err(err)?;
206    verify_full(&staged)?;
207    let previous = staging.path().join("previous");
208    let had_previous = match fs::rename(destination, &previous) {
209        Ok(()) => true,
210        Err(error) if error.kind() == std::io::ErrorKind::NotFound => false,
211        Err(error) => return Err(err(error)),
212    };
213    if let Err(error) = fs::rename(&staged, destination) {
214        if had_previous {
215            fs::rename(&previous, destination).map_err(|restore| {
216                format!("{error}; restoring the previous source also failed: {restore}")
217            })?;
218        }
219        return Err(err(error));
220    }
221    Ok(())
222}
223
224fn write_context(operation: u128) -> WriteContext {
225    WriteContext {
226        operation_uuid: OperationId(Uuid::from_u128(operation)),
227        actor_uuid: None,
228    }
229}
230
231fn authority(graph: &GraphForge, operation: u128) -> Result<OntologyAuthorityExpectation, String> {
232    let state = graph.ontology_authority_state().map_err(err)?;
233    Ok(OntologyAuthorityExpectation {
234        context: write_context(operation),
235        expected_project_generation_uuid: state.project_generation_uuid,
236        expected_composition_fingerprint: state.composition_fingerprint,
237    })
238}
239
240/// Validate a digest-addressed HTTPS base using the Hub transport's location rules.
241/// No network lookup is needed to generate deterministic artifacts; clone still
242/// validates resolved addresses when fetching them.
243pub fn validate_location_base(location_base: &str) -> Result<(), String> {
244    let parsed = url::Url::parse(location_base).map_err(err)?;
245    crate::hub_http::validate_url(&parsed).map_err(err)?;
246    let public_host = match parsed.host() {
247        Some(url::Host::Ipv4(ip)) => crate::hub_http::public_ip(ip.into()),
248        Some(url::Host::Ipv6(ip)) => crate::hub_http::public_ip(ip.into()),
249        Some(url::Host::Domain(host)) => {
250            let host = host.trim_end_matches('.');
251            let suffix = host.rsplit('.').next().unwrap_or_default();
252            host.contains('.') && !matches!(suffix, "localhost" | "local")
253        }
254        None => false,
255    };
256    if !public_host {
257        return Err("fixture location base host is not public".into());
258    }
259    if !location_base.ends_with('/') || parsed.as_str() != location_base {
260        return Err("fixture location base must be a canonical HTTPS URL ending in /".into());
261    }
262    Ok(())
263}
264
265fn location(location_base: &str, digest: &str) -> Result<String, String> {
266    let hex = digest
267        .strip_prefix("sha256:")
268        .ok_or("object digest prefix is invalid")?;
269    Ok(format!("{location_base}{hex}"))
270}
271
272fn descriptor(
273    bytes: &[u8],
274    media_type: &str,
275    location_base: &str,
276) -> Result<ObjectDescriptor, String> {
277    let digest = digest_bytes(bytes);
278    Ok(ObjectDescriptor {
279        locations: vec![location(location_base, &digest)?],
280        digest: Sha256Digest(digest),
281        length: u64::try_from(bytes.len()).map_err(|_| "object length overflow")?,
282        media_type: media_type.into(),
283    })
284}
285
286fn module_object_path(content_digest: &str) -> Result<String, String> {
287    let hex = content_digest
288        .strip_prefix("sha256:")
289        .filter(|hex| hex.len() == 64 && hex.bytes().all(|byte| byte.is_ascii_hexdigit()))
290        .ok_or("module content digest is invalid")?;
291    Ok(format!("{MODULE_OBJECT_PREFIX}{hex}{MODULE_OBJECT_SUFFIX}"))
292}
293
294fn repository_identity() -> RepositoryIdentity {
295    RepositoryIdentity {
296        owner: "opendata".into(),
297        repository: "openalex".into(),
298    }
299}
300
301/// Generate canonical object, discovery, and provenance artifacts from the checked-in source.
302///
303/// `location_base` prefixes every digest-addressed object location. It is
304/// transport only: the summary bytes and the manifest's `summary` and `ontology`
305/// descriptors do not depend on it.
306#[expect(
307    clippy::too_many_lines,
308    reason = "one transaction binds portable and discovery artifacts"
309)]
310pub fn generate(source: &Path, destination: &Path, location_base: &str) -> Result<(), String> {
311    validate_location_base(location_base)?;
312    let limits = PortableLimits::default();
313    let source_report = verify_full(source)?;
314    let scratch = tempfile::tempdir().map_err(err)?;
315    let imported = scratch.path().join("imported");
316    let operation_id = OperationId(Uuid::from_u128(0x91f2_1a60_d89e_54e1_9000_0000_0000_0001));
317    GraphForge::import_portable(
318        &imported,
319        &PortableImportRequest {
320            input: source.to_path_buf(),
321            operation_id,
322            limits,
323        },
324        None,
325    )
326    .map_err(err)?;
327    let imported_project = GraphForge::new(imported.to_str()).map_err(err)?;
328    fs::create_dir_all(destination.join("objects")).map_err(err)?;
329    let object_path = destination.join(OBJECT_PATH);
330    let exported = repack_verified_expanded_portable(
331        &graphforge_api::PortableRepackRequest {
332            source: source.to_path_buf(),
333            destination: object_path.clone(),
334            limits,
335        },
336        &std::sync::atomic::AtomicBool::new(false),
337    )
338    .map_err(err)?;
339    let verified = verify_full(&object_path)?;
340    let imported_bundle = scratch.path().join("imported-bundle");
341    let bundle_import = GraphForge::import_portable(
342        &imported_bundle,
343        &PortableImportRequest {
344            input: object_path.clone(),
345            operation_id: OperationId(Uuid::from_u128(0x91f2_1a60_d89e_54e1_9000_0000_0000_0002)),
346            limits,
347        },
348        None,
349    )
350    .map_err(err)?;
351    let reopened_bundle = GraphForge::new(imported_bundle.to_str()).map_err(err)?;
352    if reopened_bundle
353        .committed_generation_identity()
354        .map_err(err)?
355        .generation_uuid
356        != bundle_import.generation_uuid
357    {
358        return Err("generated bundle did not reopen at its imported generation".into());
359    }
360    let exported_package_digest = format!("sha256:{}", hex(&exported.package_digest));
361    let exported_transport_digest = format!("sha256:{}", hex(&exported.transport_digest));
362    if exported_package_digest != verified.package_digest
363        || exported_transport_digest != verified.transport_digest.clone().unwrap_or_default()
364    {
365        return Err("portable export and verification receipts disagree".into());
366    }
367    let bytes = fs::read(&object_path).map_err(err)?;
368    let object_digest = digest_bytes(&bytes);
369    if object_digest != exported_transport_digest {
370        return Err("transport digest does not bind emitted object bytes".into());
371    }
372    let repository = repository_identity();
373    let immutable_version = Sha256Digest(exported_package_digest.clone());
374
375    // The summary is derived from the verified bundle, never entered by hand. The
376    // fixture publishes no research lineage, so it lists no people.
377    let derived = derive_summary(&repository, &immutable_version, &object_path, None)?;
378    write(destination.join(SUMMARY_PATH), &derived.bytes)?;
379
380    // One component-selective package per advertised module, exported from the
381    // Project reopened from the same checked-in source.
382    let (ontology, modules) =
383        export_module_packages(&imported_project, &derived.summary, |digest| {
384            Ok(destination.join(module_object_path(digest)?))
385        })?;
386    let mut module_objects = Vec::new();
387    let mut module_records = Vec::new();
388    for module in &modules {
389        let module_object = object_descriptor(
390            module.bundle.object_digest.clone(),
391            module.bundle.length,
392            PACKAGE_MEDIA_TYPE,
393            location(location_base, &module.bundle.object_digest)?,
394        );
395        module_records.push(ModuleObjectRecord {
396            ontology_id: module.descriptor.id.clone(),
397            version: module.descriptor.version.clone(),
398            content_digest: module.descriptor.content_digest.0.clone(),
399            package_digest: module.bundle.package_digest.clone(),
400            object_digest: module_object.digest.0.clone(),
401            object_length: module_object.length,
402            object_path: module_object_path(&module.descriptor.content_digest.0)?,
403        });
404        module_objects.push(module_object);
405    }
406
407    let project_object = descriptor(&bytes, PORTABLE_MEDIA_TYPE, location_base)?;
408    let summary_object = descriptor(&derived.bytes, PROJECT_SUMMARY_MEDIA_TYPE, location_base)?;
409    let mut objects = vec![project_object.clone(), summary_object.clone()];
410    objects.extend(module_objects);
411    let manifest = build_manifest(ManifestInputs {
412        repository: repository.clone(),
413        default_ref: "main".into(),
414        resolved_ref: "main".into(),
415        package: PortablePackageReference {
416            format: PORTABLE_FORMAT.into(),
417            package_digest: Sha256Digest(exported_package_digest.clone()),
418            producing_core_version: derived.summary.package.producing_core_version.clone(),
419            object_digest: project_object.digest.clone(),
420        },
421        summary: Some(summary_reference(&derived, &summary_object)),
422        ontology,
423        lineage: None,
424        objects,
425    })?;
426    let summary = derived.summary;
427    let summary_digest = derived.summary_digest;
428    let manifest_bytes = manifest.to_canonical_json().map_err(err)?;
429    let manifest_digest = manifest.canonical_digest().map_err(err)?.0;
430    let refs = RefSet {
431        format: DISCOVERY_FORMAT.into(),
432        version: ProtocolVersion::CURRENT,
433        repository,
434        default_ref: "main".into(),
435        refs: vec![RepositoryRef {
436            name: "main".into(),
437            target: manifest.immutable_version.clone(),
438            validator: Sha256Digest(manifest_digest.clone()),
439        }],
440        extensions: BTreeMap::new(),
441    };
442    refs.validate_manifest(&manifest).map_err(err)?;
443    manifest.bind_summary(&summary).map_err(err)?;
444    let refs_bytes = refs.to_canonical_json().map_err(err)?;
445    let metadata = FixtureMetadata {
446        format: "graphforge-hub-fixture/1",
447        generator: GeneratorIdentity {
448            contract: GENERATOR_CONTRACT,
449            crate_name: "graphforge-cli",
450            source_digest: generator_source_digest(),
451        },
452        source: SourceIdentity {
453            tree_digest: tree_digest(source)?,
454            package_digest: source_report.package_digest,
455        },
456        object_path: OBJECT_PATH,
457        object_digest,
458        object_length: project_object.length,
459        package_digest: exported_package_digest,
460        summary_path: SUMMARY_PATH,
461        summary_digest: summary_digest.0,
462        summary_object_digest: summary_object.digest.0,
463        summary_object_length: summary_object.length,
464        module_objects: module_records,
465        manifest_digest,
466        location_base,
467    };
468    write(destination.join("manifest.json"), &manifest_bytes)?;
469    write(destination.join("refs.json"), &refs_bytes)?;
470    let mut metadata_bytes = serde_json::to_vec(&metadata).map_err(err)?;
471    metadata_bytes.push(b'\n');
472    write(destination.join("fixture.json"), &metadata_bytes)
473}
474
475/// Regenerate at `location_base` in a private directory and compare every artifact byte.
476pub fn check(source: &Path, expected: &Path, location_base: &str) -> Result<(), String> {
477    validate_location_base(location_base)?;
478    validate(source, expected, location_base)?;
479    let scratch = tempfile::tempdir().map_err(err)?;
480    generate(source, scratch.path(), location_base)?;
481    let regenerated = artifact_files(scratch.path())?;
482    if regenerated != artifact_files(expected)? {
483        return Err("generated Hub fixture artifact set drifted".into());
484    }
485    for relative in regenerated {
486        let actual = fs::read(scratch.path().join(&relative)).map_err(err)?;
487        let expected_bytes = fs::read(expected.join(&relative)).map_err(err)?;
488        if actual != expected_bytes {
489            return Err(format!("generated Hub fixture artifact drift: {relative}"));
490        }
491    }
492    Ok(())
493}
494
495/// Sorted relative paths of every regular file under `root`.
496fn artifact_files(root: &Path) -> Result<Vec<String>, String> {
497    let mut files = Vec::new();
498    let mut pending = vec![root.to_path_buf()];
499    while let Some(directory) = pending.pop() {
500        for entry in fs::read_dir(&directory).map_err(err)? {
501            let path = entry.map_err(err)?.path();
502            if fs::symlink_metadata(&path).map_err(err)?.is_dir() {
503                pending.push(path);
504            } else {
505                files.push(canonical_relative_path(
506                    path.strip_prefix(root).map_err(err)?,
507                )?);
508            }
509        }
510    }
511    files.sort();
512    Ok(files)
513}
514
515/// Validate all generator, source, portable, discovery, summary, and metadata bindings.
516fn validate(source: &Path, artifacts: &Path, location_base: &str) -> Result<(), String> {
517    let metadata: serde_json::Value =
518        serde_json::from_slice(&fs::read(artifacts.join("fixture.json")).map_err(err)?)
519            .map_err(err)?;
520    let manifest_bytes = fs::read(artifacts.join("manifest.json")).map_err(err)?;
521    let refs_bytes = fs::read(artifacts.join("refs.json")).map_err(err)?;
522    let manifest =
523        DiscoveryManifest::from_json(&manifest_bytes, DiscoveryLimits::default()).map_err(err)?;
524    let refs = RefSet::from_json(&refs_bytes, DiscoveryLimits::default()).map_err(err)?;
525    refs.validate_manifest(&manifest).map_err(err)?;
526    let module_paths = manifest
527        .ontology
528        .iter()
529        .flat_map(|inventory| &inventory.modules)
530        .map(|module| module_object_path(&module.content_digest.0))
531        .collect::<Result<Vec<_>, _>>()?;
532    validate_expected_tree(artifacts, &module_paths)?;
533    let expected_repository = repository_identity();
534    if manifest.repository != expected_repository
535        || manifest.default_ref != "main"
536        || manifest.resolved_ref != "main"
537        || refs.repository != expected_repository
538        || refs.default_ref != "main"
539        || manifest.immutable_version != manifest.package.package_digest
540    {
541        return Err("fixture repository, ref, or immutable version binding is invalid".into());
542    }
543    let manifest_digest = manifest.canonical_digest().map_err(err)?.0;
544    let reference = refs
545        .refs
546        .iter()
547        .find(|reference| reference.name == "main")
548        .ok_or("fixture main ref is absent")?;
549    if reference.validator.0 != manifest_digest {
550        return Err("fixture validator does not bind canonical manifest bytes".into());
551    }
552    if metadata["location_base"] != location_base {
553        return Err("fixture location base does not match the requested base".into());
554    }
555    for object in &manifest.objects {
556        if object.locations != [location(location_base, &object.digest.0)?] {
557            return Err(
558                "fixture object location is not digest addressed at the requested base".into(),
559            );
560        }
561    }
562    let selected = manifest.package_object().map_err(err)?;
563    let object_path = metadata["object_path"]
564        .as_str()
565        .ok_or("fixture object path is absent")?;
566    if object_path != OBJECT_PATH {
567        return Err("fixture object path is invalid".into());
568    }
569    let object = artifacts.join(object_path);
570    let bytes = fs::read(&object).map_err(err)?;
571    let report = verify_full(&object)?;
572    if digest_bytes(&bytes) != selected.digest.0
573        || bytes.len() as u64 != selected.length
574        || report.package_digest != manifest.package.package_digest.0
575        || metadata["format"] != "graphforge-hub-fixture/1"
576        || metadata["object_digest"] != selected.digest.0
577        || metadata["object_length"] != selected.length
578        || metadata["package_digest"] != manifest.package.package_digest.0
579        || metadata["manifest_digest"] != manifest_digest
580        || metadata["generator"]["contract"] != GENERATOR_CONTRACT
581        || metadata["generator"]["crate_name"] != "graphforge-cli"
582        || metadata["generator"]["source_digest"] != generator_source_digest()
583        || metadata["source"]["tree_digest"] != tree_digest(source)?
584        || metadata["source"]["package_digest"] != verify_full(source)?.package_digest
585    {
586        return Err(
587            "fixture portable, discovery, metadata, provenance, or source binding is invalid"
588                .into(),
589        );
590    }
591    validate_summary(artifacts, &manifest, &metadata)?;
592    validate_modules(
593        artifacts,
594        &manifest,
595        &manifest_bytes,
596        &refs_bytes,
597        &metadata,
598    )
599}
600
601/// The summary object must hash to the manifest descriptor, parse through the
602/// public contract, and bind to the manifest it is advertised by.
603fn validate_summary(
604    artifacts: &Path,
605    manifest: &DiscoveryManifest,
606    metadata: &serde_json::Value,
607) -> Result<(), String> {
608    let reference = manifest
609        .summary
610        .as_ref()
611        .ok_or("fixture manifest does not advertise a summary")?;
612    let selected = manifest.summary_object().map_err(err)?;
613    let bytes = fs::read(artifacts.join(SUMMARY_PATH)).map_err(err)?;
614    if digest_bytes(&bytes) != reference.object_digest.0 || bytes.len() as u64 != selected.length {
615        return Err("fixture summary object bytes do not match the manifest descriptor".into());
616    }
617    let summary = ProjectSummary::from_json(&bytes, DiscoveryLimits::default()).map_err(err)?;
618    manifest.bind_summary(&summary).map_err(err)?;
619    if summary.to_canonical_json().map_err(err)? != bytes {
620        return Err("fixture summary object is not canonical".into());
621    }
622    if metadata["summary_path"] != SUMMARY_PATH
623        || metadata["summary_digest"] != reference.summary_digest.0
624        || metadata["summary_object_digest"] != reference.object_digest.0
625        || metadata["summary_object_length"] != selected.length
626    {
627        return Err("fixture summary metadata binding is invalid".into());
628    }
629    Ok(())
630}
631
632/// Every advertised module package must verify and resolve to exactly the
633/// advertised identity, and `fixture.json` must record it.
634fn validate_modules(
635    artifacts: &Path,
636    manifest: &DiscoveryManifest,
637    manifest_bytes: &[u8],
638    refs_bytes: &[u8],
639    metadata: &serde_json::Value,
640) -> Result<(), String> {
641    let mut records = Vec::new();
642    for module in manifest
643        .ontology
644        .iter()
645        .flat_map(|inventory| &inventory.modules)
646    {
647        let package = module
648            .package
649            .as_ref()
650            .ok_or("fixture ontology module has no package")?;
651        let identity = ExactIdentity {
652            id: module.id.clone(),
653            version: module.version.clone(),
654            content_digest: module.content_digest.clone(),
655        };
656        let (_, selected) = manifest.ontology_module_object(&identity).map_err(err)?;
657        let path = module_object_path(&module.content_digest.0)?;
658        let file = artifacts.join(&path);
659        let bytes = fs::read(&file).map_err(err)?;
660        if digest_bytes(&bytes) != selected.digest.0 || bytes.len() as u64 != selected.length {
661            return Err("fixture module object bytes do not match the manifest descriptor".into());
662        }
663        let resolved = resolve_discovered_ontology_module(&DiscoveryOntologyModuleRequest {
664            manifest_json: manifest_bytes,
665            refs_json: refs_bytes,
666            expected_repository: &repository_identity(),
667            module: &identity,
668            package: &file,
669            discovery_limits: DiscoveryLimits::default(),
670            portable_limits: PortableLimits::default(),
671            cancelled: None,
672        })
673        .map_err(err)?;
674        if resolved.module.ontology_id != module.id
675            || resolved.module.authored_version != module.version
676            || format!("sha256:{}", resolved.module.canonical_digest) != module.content_digest.0
677            || resolved.package_digest != package.package_digest.0
678        {
679            return Err("fixture module package does not resolve to the advertised module".into());
680        }
681        records.push(ModuleObjectRecord {
682            ontology_id: module.id.clone(),
683            version: module.version.clone(),
684            content_digest: module.content_digest.0.clone(),
685            package_digest: package.package_digest.0.clone(),
686            object_digest: selected.digest.0.clone(),
687            object_length: selected.length,
688            object_path: path,
689        });
690    }
691    if metadata["module_objects"] != serde_json::to_value(&records).map_err(err)? {
692        return Err("fixture module object records do not match the manifest".into());
693    }
694    Ok(())
695}
696
697fn validate_expected_tree(root: &Path, module_paths: &[String]) -> Result<(), String> {
698    let mut actual = Vec::new();
699    let mut pending = vec![root.to_path_buf()];
700    while let Some(directory) = pending.pop() {
701        for entry in fs::read_dir(&directory).map_err(err)? {
702            let entry = entry.map_err(err)?;
703            let path = entry.path();
704            let relative = canonical_relative_path(path.strip_prefix(root).map_err(err)?)?;
705            let metadata = fs::symlink_metadata(&path).map_err(err)?;
706            if metadata.file_type().is_symlink() {
707                return Err(format!(
708                    "fixture artifact tree contains a symlink: {relative}"
709                ));
710            }
711            if metadata.is_dir() {
712                actual.push(format!("{relative}/"));
713                pending.push(path);
714            } else if metadata.is_file() {
715                actual.push(relative);
716            } else {
717                return Err("fixture artifact tree contains a non-file entry".into());
718            }
719        }
720    }
721    actual.sort();
722    let mut expected: Vec<String> = FIXED_FILES
723        .iter()
724        .map(|path| (*path).to_owned())
725        .chain(module_paths.iter().cloned())
726        .chain(["objects/".to_owned()])
727        .collect();
728    expected.sort();
729    if actual != expected {
730        return Err("fixture artifact tree does not match the exact generated contract".into());
731    }
732    Ok(())
733}
734
735fn write(path: PathBuf, bytes: &[u8]) -> Result<(), String> {
736    if let Some(parent) = path.parent() {
737        fs::create_dir_all(parent).map_err(err)?;
738    }
739    fs::write(path, bytes).map_err(err)
740}
741
742fn generator_source_digest() -> String {
743    let mut hasher = Sha256::new();
744    hasher.update(b"graphforge-hub-fixture-generator-source/1\0");
745    hasher.update(include_bytes!("hub_fixture_artifacts.rs"));
746    hasher.update(b"\0");
747    hasher.update(include_bytes!("hub_publish/publication.rs"));
748    format!("sha256:{}", hex(&hasher.finalize()))
749}
750
751fn hex(bytes: &[u8]) -> String {
752    bytes.iter().fold(
753        String::with_capacity(bytes.len() * 2),
754        |mut output, byte| {
755            write!(output, "{byte:02x}").expect("writing to String cannot fail");
756            output
757        },
758    )
759}
760
761fn canonical_relative_path(path: &Path) -> Result<String, String> {
762    path.components()
763        .map(|component| match component {
764            std::path::Component::Normal(value) => value
765                .to_str()
766                .map(str::to_owned)
767                .ok_or_else(|| "fixture path component is not UTF-8".to_owned()),
768            _ => Err("fixture path is not a normalized relative path".to_owned()),
769        })
770        .collect::<Result<Vec<_>, _>>()
771        .map(|components| components.join("/"))
772}
773
774fn tree_digest(root: &Path) -> Result<String, String> {
775    fn walk(root: &Path, current: &Path, files: &mut Vec<PathBuf>) -> Result<(), String> {
776        for entry in fs::read_dir(current).map_err(|error| error.to_string())? {
777            let path = entry.map_err(|error| error.to_string())?.path();
778            let metadata = fs::symlink_metadata(&path).map_err(|error| error.to_string())?;
779            if metadata.file_type().is_symlink() {
780                return Err("fixture source may not contain symlinks".into());
781            }
782            if metadata.is_dir() {
783                walk(root, &path, files)?;
784            } else if metadata.is_file() {
785                files.push(
786                    path.strip_prefix(root)
787                        .map_err(|error| error.to_string())?
788                        .to_path_buf(),
789                );
790            } else {
791                return Err("fixture source contains a non-file entry".into());
792            }
793        }
794        Ok(())
795    }
796    let mut files = Vec::new();
797    walk(root, root, &mut files)?;
798    files.sort();
799    let mut hasher = Sha256::new();
800    hasher.update(b"graphforge-hub-fixture-source/1\0");
801    for relative in files {
802        let canonical = canonical_relative_path(&relative)?;
803        let name = canonical.as_bytes();
804        let bytes = fs::read(root.join(&relative)).map_err(|error| error.to_string())?;
805        hasher.update((name.len() as u64).to_be_bytes());
806        hasher.update(name);
807        hasher.update((bytes.len() as u64).to_be_bytes());
808        hasher.update(&bytes);
809    }
810    Ok(format!("sha256:{}", hex(&hasher.finalize())))
811}
812
813#[cfg(test)]
814mod tests {
815    use super::*;
816    use graphforge_api::{PortableMode, PortableVerifyRequest, verify_portable};
817
818    fn root() -> PathBuf {
819        PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..")
820    }
821
822    fn private_source() -> tempfile::TempDir {
823        fn copy_tree(source: &Path, destination: &Path) {
824            fs::create_dir_all(destination).unwrap();
825            for entry in fs::read_dir(source).unwrap() {
826                let entry = entry.unwrap();
827                let destination = destination.join(entry.file_name());
828                if entry.file_type().unwrap().is_dir() {
829                    copy_tree(&entry.path(), &destination);
830                } else {
831                    fs::copy(entry.path(), destination).unwrap();
832                }
833            }
834        }
835        let private = tempfile::tempdir().unwrap();
836        copy_tree(
837            &root().join("tests/fixtures/hub/openalex-source"),
838            private.path(),
839        );
840        private
841    }
842
843    #[test]
844    fn relative_paths_use_platform_independent_slash_encoding() {
845        let nested = PathBuf::from("objects").join("sha256").join("fixture.gfpb");
846        assert_eq!(
847            canonical_relative_path(&nested).unwrap(),
848            "objects/sha256/fixture.gfpb"
849        );
850        assert!(canonical_relative_path(Path::new("../outside")).is_err());
851    }
852
853    fn copy_artifacts(source: &Path) -> tempfile::TempDir {
854        let private = tempfile::tempdir().unwrap();
855        copy_tree_for_test(source, private.path());
856        private
857    }
858
859    fn copy_tree_for_test(source: &Path, destination: &Path) {
860        fs::create_dir_all(destination).unwrap();
861        for entry in fs::read_dir(source).unwrap() {
862            let entry = entry.unwrap();
863            let destination = destination.join(entry.file_name());
864            if entry.file_type().unwrap().is_dir() {
865                copy_tree_for_test(&entry.path(), &destination);
866            } else {
867                fs::copy(entry.path(), destination).unwrap();
868            }
869        }
870    }
871
872    #[test]
873    fn checked_in_hub_fixture_is_exact_rust_output() {
874        let source = private_source();
875        let artifacts = copy_artifacts(&root().join("tests/fixtures/hub/generated/v1"));
876        check(source.path(), artifacts.path(), DEFAULT_LOCATION_BASE).unwrap();
877    }
878
879    #[test]
880    fn check_rejects_tampered_artifact() {
881        let source = private_source();
882        let output = tempfile::tempdir().unwrap();
883        generate(source.path(), output.path(), DEFAULT_LOCATION_BASE).unwrap();
884        fs::write(output.path().join("refs.json"), b"{}\n").unwrap();
885        let error = check(source.path(), output.path(), DEFAULT_LOCATION_BASE).unwrap_err();
886        assert!(!error.is_empty());
887    }
888
889    #[test]
890    fn generated_artifacts_are_cross_contract_coherent() {
891        let generated = root().join("tests/fixtures/hub/generated/v1");
892        let manifest_bytes = fs::read(generated.join("manifest.json")).unwrap();
893        let refs_bytes = fs::read(generated.join("refs.json")).unwrap();
894        let manifest = DiscoveryManifest::from_json(
895            &manifest_bytes,
896            graphforge_discovery::DiscoveryLimits::default(),
897        )
898        .unwrap();
899        let refs = RefSet::from_json(
900            &refs_bytes,
901            graphforge_discovery::DiscoveryLimits::default(),
902        )
903        .unwrap();
904        refs.validate_manifest(&manifest).unwrap();
905        let object = fs::read(generated.join(OBJECT_PATH)).unwrap();
906        let selected = manifest.package_object().unwrap();
907        assert_eq!(selected.digest.0, digest_bytes(&object));
908        assert_eq!(selected.length, object.len() as u64);
909        assert_eq!(
910            refs.refs[0].validator.0,
911            manifest.canonical_digest().unwrap().0
912        );
913        let private_object = tempfile::NamedTempFile::new().unwrap();
914        fs::write(private_object.path(), &object).unwrap();
915        let verified = verify_portable(
916            &PortableVerifyRequest {
917                input: private_object.path().to_path_buf(),
918                mode: PortableMode::Full,
919                limits: PortableLimits::default(),
920            },
921            None,
922        )
923        .unwrap();
924        assert_eq!(verified.package_digest, manifest.package.package_digest.0);
925        let metadata: serde_json::Value =
926            serde_json::from_slice(&fs::read(generated.join("fixture.json")).unwrap()).unwrap();
927        assert_eq!(metadata["object_digest"], selected.digest.0);
928        assert_eq!(metadata["object_length"], selected.length);
929        assert_eq!(
930            metadata["package_digest"],
931            manifest.package.package_digest.0
932        );
933        assert_eq!(metadata["manifest_digest"], refs.refs[0].validator.0);
934    }
935
936    #[test]
937    fn repeated_generation_is_byte_identical() {
938        let source = private_source();
939        let first = tempfile::tempdir().unwrap();
940        let second = tempfile::tempdir().unwrap();
941        generate(source.path(), first.path(), DEFAULT_LOCATION_BASE).unwrap();
942        generate(source.path(), second.path(), DEFAULT_LOCATION_BASE).unwrap();
943        let files = artifact_files(first.path()).unwrap();
944        assert_eq!(files, artifact_files(second.path()).unwrap());
945        for relative in files {
946            assert_eq!(
947                fs::read(first.path().join(&relative)).unwrap(),
948                fs::read(second.path().join(&relative)).unwrap(),
949                "{relative}"
950            );
951        }
952    }
953
954    #[test]
955    fn adversarial_binding_matrix_fails_semantic_validation_and_drift() {
956        let source = private_source();
957        let pristine = root().join("tests/fixtures/hub/generated/v1");
958        let cases: &[(&str, &str, fn(&mut serde_json::Value))] = &[
959            ("version", "manifest.json", |value| {
960                value["version"]["major"] = serde_json::json!(999)
961            }),
962            ("object-digest", "manifest.json", |value| {
963                value["package"]["object_digest"] =
964                    serde_json::json!(format!("sha256:{}", "0".repeat(64)))
965            }),
966            ("object-length", "manifest.json", |value| {
967                value["objects"][0]["length"] = serde_json::json!(1)
968            }),
969            ("object-location", "manifest.json", |value| {
970                value["objects"][0]["locations"][0] =
971                    serde_json::json!("https://example.com/object")
972            }),
973            ("repository", "manifest.json", |value| {
974                value["repository"]["owner"] = serde_json::json!("other")
975            }),
976            ("default-ref", "manifest.json", |value| {
977                value["default_ref"] = serde_json::json!("other")
978            }),
979            ("immutable-version", "manifest.json", |value| {
980                value["immutable_version"] = serde_json::json!(format!("sha256:{}", "1".repeat(64)))
981            }),
982            ("package-digest", "manifest.json", |value| {
983                value["package"]["package_digest"] =
984                    serde_json::json!(format!("sha256:{}", "5".repeat(64)))
985            }),
986            ("refs-target", "refs.json", |value| {
987                value["refs"][0]["target"] = serde_json::json!(format!("sha256:{}", "2".repeat(64)))
988            }),
989            ("refs-validator", "refs.json", |value| {
990                value["refs"][0]["validator"] =
991                    serde_json::json!(format!("sha256:{}", "3".repeat(64)))
992            }),
993            ("provenance", "fixture.json", |value| {
994                value["generator"]["source_digest"] =
995                    serde_json::json!(format!("sha256:{}", "4".repeat(64)))
996            }),
997            ("object-path", "fixture.json", |value| {
998                value["object_path"] = serde_json::json!("../../outside.gfpb")
999            }),
1000        ];
1001        for (name, relative, mutate) in cases {
1002            let candidate = copy_artifacts(&pristine);
1003            let path = candidate.path().join(relative);
1004            let mut value: serde_json::Value =
1005                serde_json::from_slice(&fs::read(&path).unwrap()).unwrap();
1006            mutate(&mut value);
1007            fs::write(&path, serde_json::to_vec(&value).unwrap()).unwrap();
1008            assert!(
1009                validate(source.path(), candidate.path(), DEFAULT_LOCATION_BASE).is_err(),
1010                "semantic case {name}"
1011            );
1012            assert!(
1013                check(source.path(), candidate.path(), DEFAULT_LOCATION_BASE).is_err(),
1014                "drift case {name}"
1015            );
1016        }
1017        let package = copy_artifacts(&pristine);
1018        let path = package.path().join(OBJECT_PATH);
1019        let mut bytes = fs::read(&path).unwrap();
1020        bytes[1024] ^= 1;
1021        fs::write(path, bytes).unwrap();
1022        assert!(validate(source.path(), package.path(), DEFAULT_LOCATION_BASE).is_err());
1023        assert!(check(source.path(), package.path(), DEFAULT_LOCATION_BASE).is_err());
1024        let altered_source = private_source();
1025        fs::write(altered_source.path().join("bag-info.txt"), b"changed").unwrap();
1026        assert!(validate(altered_source.path(), &pristine, DEFAULT_LOCATION_BASE).is_err());
1027    }
1028
1029    #[test]
1030    fn exact_artifact_tree_rejects_extra_files_and_directories() {
1031        let source = private_source();
1032        let pristine = root().join("tests/fixtures/hub/generated/v1");
1033        for relative in ["extra.json", "objects/extra.gfpb", "extra/nested.json"] {
1034            let candidate = copy_artifacts(&pristine);
1035            let path = candidate.path().join(relative);
1036            fs::create_dir_all(path.parent().unwrap()).unwrap();
1037            fs::write(path, b"extra").unwrap();
1038            assert!(
1039                validate(source.path(), candidate.path(), DEFAULT_LOCATION_BASE).is_err(),
1040                "{relative}"
1041            );
1042            assert!(
1043                check(source.path(), candidate.path(), DEFAULT_LOCATION_BASE).is_err(),
1044                "{relative}"
1045            );
1046        }
1047    }
1048
1049    /// Rewrite a JSON artifact in place.
1050    fn mutate_json(path: &Path, mutate: impl FnOnce(&mut serde_json::Value)) {
1051        let mut value: serde_json::Value =
1052            serde_json::from_slice(&fs::read(path).unwrap()).unwrap();
1053        mutate(&mut value);
1054        fs::write(path, serde_json::to_vec(&value).unwrap()).unwrap();
1055    }
1056
1057    /// Re-bind the ref validator and fixture metadata to the current manifest so a
1058    /// test reaches the check it targets instead of the manifest-digest binding.
1059    fn reseal_manifest_digest(artifacts: &Path) {
1060        let manifest = DiscoveryManifest::from_json(
1061            &fs::read(artifacts.join("manifest.json")).unwrap(),
1062            DiscoveryLimits::default(),
1063        )
1064        .unwrap();
1065        let digest = manifest.canonical_digest().unwrap().0;
1066        mutate_json(&artifacts.join("refs.json"), |value| {
1067            value["refs"][0]["validator"] = serde_json::json!(digest);
1068        });
1069        mutate_json(&artifacts.join("fixture.json"), |value| {
1070            value["manifest_digest"] = serde_json::json!(digest);
1071        });
1072    }
1073
1074    fn other_digest() -> serde_json::Value {
1075        serde_json::json!(format!("sha256:{}", "7".repeat(64)))
1076    }
1077
1078    /// Apply `mutate` to a pristine copy and require `validate` to reject it with
1079    /// a message containing `expected`, and `check` to reject it too.
1080    fn assert_rejected(name: &str, expected: &str, mutate: impl FnOnce(&Path)) {
1081        let source = private_source();
1082        let candidate = copy_artifacts(&root().join("tests/fixtures/hub/generated/v1"));
1083        mutate(candidate.path());
1084        let error = validate(source.path(), candidate.path(), DEFAULT_LOCATION_BASE).unwrap_err();
1085        assert!(error.contains(expected), "{name}: {error}");
1086        assert!(
1087            check(source.path(), candidate.path(), DEFAULT_LOCATION_BASE).is_err(),
1088            "{name}"
1089        );
1090    }
1091
1092    fn mutate_manifest(dir: &Path, mutate: impl FnOnce(&mut serde_json::Value)) {
1093        mutate_json(&dir.join("manifest.json"), mutate);
1094    }
1095
1096    #[test]
1097    fn manifest_summary_and_ontology_descriptors_are_each_enforced() {
1098        assert_rejected("summary-digest", "disagrees with manifest", |dir| {
1099            mutate_manifest(dir, |value| {
1100                value["summary"]["summary_digest"] = other_digest();
1101            });
1102            reseal_manifest_digest(dir);
1103        });
1104        assert_rejected("summary-removed", "does not advertise a summary", |dir| {
1105            mutate_manifest(dir, |value| {
1106                value.as_object_mut().unwrap().remove("summary");
1107            });
1108            reseal_manifest_digest(dir);
1109        });
1110        assert_rejected(
1111            "ontology-composition-digest",
1112            "disagrees with manifest",
1113            |dir| {
1114                mutate_manifest(dir, |value| {
1115                    value["ontology"]["composition_digest"] = other_digest();
1116                });
1117                reseal_manifest_digest(dir);
1118            },
1119        );
1120        assert_rejected("ontology-removed", "exact generated contract", |dir| {
1121            mutate_manifest(dir, |value| {
1122                value.as_object_mut().unwrap().remove("ontology");
1123            });
1124            reseal_manifest_digest(dir);
1125        });
1126        assert_rejected(
1127            "module-package-digest",
1128            "reference mismatch: PackageDigest",
1129            |dir| {
1130                mutate_manifest(dir, |value| {
1131                    value["ontology"]["modules"][0]["package"]["package_digest"] = other_digest();
1132                });
1133                reseal_manifest_digest(dir);
1134            },
1135        );
1136        // The manifest itself no longer parses, so no reseal is possible.
1137        assert_rejected(
1138            "module-package-is-project-package",
1139            "module package object is incompatible",
1140            |dir| {
1141                mutate_manifest(dir, |value| {
1142                    let project = value["package"]["object_digest"].clone();
1143                    value["ontology"]["modules"][0]["package"]["object_digest"] = project;
1144                });
1145            },
1146        );
1147    }
1148
1149    #[test]
1150    fn summary_and_module_objects_and_records_are_each_enforced() {
1151        let pristine = root().join("tests/fixtures/hub/generated/v1");
1152        let module_object = fs::read_dir(pristine.join("objects"))
1153            .unwrap()
1154            .map(|entry| entry.unwrap().file_name().into_string().unwrap())
1155            .find(|name| name.starts_with("ontology-module-"))
1156            .unwrap();
1157        assert_rejected("summary-object-bytes", "summary object bytes", |dir| {
1158            let path = dir.join(SUMMARY_PATH);
1159            let mut bytes = fs::read(&path).unwrap();
1160            bytes[10] ^= 1;
1161            fs::write(path, bytes).unwrap();
1162        });
1163        assert_rejected("module-object-bytes", "module object bytes", |dir| {
1164            let path = dir.join("objects").join(&module_object);
1165            let mut bytes = fs::read(&path).unwrap();
1166            bytes[1024] ^= 1;
1167            fs::write(path, bytes).unwrap();
1168        });
1169        assert_rejected("fixture-summary-digest", "summary metadata", |dir| {
1170            mutate_json(&dir.join("fixture.json"), |value| {
1171                value["summary_digest"] = other_digest();
1172            });
1173        });
1174        assert_rejected("fixture-module-record", "module object records", |dir| {
1175            mutate_json(&dir.join("fixture.json"), |value| {
1176                value["module_objects"][0]["package_digest"] = other_digest();
1177            });
1178        });
1179    }
1180
1181    #[test]
1182    fn summary_and_descriptors_do_not_depend_on_the_object_location_base() {
1183        let source = private_source();
1184        let first = tempfile::tempdir().unwrap();
1185        let second = tempfile::tempdir().unwrap();
1186        generate(source.path(), first.path(), DEFAULT_LOCATION_BASE).unwrap();
1187        let mirror = "https://mirror.example.org/content/";
1188        generate(source.path(), second.path(), mirror).unwrap();
1189
1190        assert_eq!(
1191            fs::read(first.path().join(SUMMARY_PATH)).unwrap(),
1192            fs::read(second.path().join(SUMMARY_PATH)).unwrap()
1193        );
1194        let manifest = |dir: &Path| -> serde_json::Value {
1195            serde_json::from_slice(&fs::read(dir.join("manifest.json")).unwrap()).unwrap()
1196        };
1197        let (first_manifest, second_manifest) = (manifest(first.path()), manifest(second.path()));
1198        for field in [
1199            "summary",
1200            "ontology",
1201            "package",
1202            "immutable_version",
1203            "repository",
1204        ] {
1205            assert_eq!(first_manifest[field], second_manifest[field], "{field}");
1206            assert!(!first_manifest[field].is_null(), "{field}");
1207        }
1208        // Only transport differs: same objects, same digests, different locations.
1209        let objects =
1210            |manifest: &serde_json::Value| -> Vec<(serde_json::Value, serde_json::Value)> {
1211                manifest["objects"]
1212                    .as_array()
1213                    .unwrap()
1214                    .iter()
1215                    .map(|object| (object["digest"].clone(), object["locations"].clone()))
1216                    .collect()
1217            };
1218        let (default_objects, mirror_objects) =
1219            (objects(&first_manifest), objects(&second_manifest));
1220        assert_eq!(default_objects.len(), 3);
1221        for ((first_digest, first_locations), (second_digest, second_locations)) in
1222            default_objects.iter().zip(&mirror_objects)
1223        {
1224            assert_eq!(first_digest, second_digest);
1225            assert_ne!(first_locations, second_locations);
1226            assert!(
1227                first_locations[0]
1228                    .as_str()
1229                    .unwrap()
1230                    .starts_with(DEFAULT_LOCATION_BASE)
1231            );
1232            assert_eq!(
1233                second_locations[0].as_str().unwrap(),
1234                format!(
1235                    "{mirror}{}",
1236                    first_digest
1237                        .as_str()
1238                        .unwrap()
1239                        .strip_prefix("sha256:")
1240                        .unwrap()
1241                )
1242            );
1243        }
1244        // Every non-manifest artifact is byte-identical across bases.
1245        for relative in artifact_files(first.path()).unwrap() {
1246            if relative == "manifest.json" || relative == "refs.json" || relative == "fixture.json"
1247            {
1248                continue;
1249            }
1250            assert_eq!(
1251                fs::read(first.path().join(&relative)).unwrap(),
1252                fs::read(second.path().join(&relative)).unwrap(),
1253                "{relative}"
1254            );
1255        }
1256        let metadata = |dir: &Path| -> serde_json::Value {
1257            serde_json::from_slice(&fs::read(dir.join("fixture.json")).unwrap()).unwrap()
1258        };
1259        let (first_metadata, second_metadata) = (metadata(first.path()), metadata(second.path()));
1260        for field in [
1261            "summary_digest",
1262            "summary_object_digest",
1263            "module_objects",
1264            "package_digest",
1265        ] {
1266            assert_eq!(first_metadata[field], second_metadata[field], "{field}");
1267        }
1268        // The mirror manifest is self-consistent but is not the checked-in
1269        // location contract.
1270        assert!(validate(source.path(), second.path(), DEFAULT_LOCATION_BASE).is_err());
1271    }
1272
1273    #[test]
1274    fn location_bases_follow_public_https_transport_rules_before_writing() {
1275        for base in [
1276            DEFAULT_LOCATION_BASE,
1277            "https://preview-data.example.org/objects/sha256/",
1278            "https://8.8.8.8/objects/",
1279            "https://[2606:4700:4700::1111]/objects/",
1280        ] {
1281            validate_location_base(base).unwrap();
1282        }
1283        let output = tempfile::tempdir().unwrap();
1284        for base in [
1285            "http://preview.example.org/objects/",
1286            "https://user:secret@preview.example.org/objects/",
1287            "https://preview.example.org/objects/?token=x/",
1288            "https://preview.example.org/objects/#fragment/",
1289            "https://preview.example.org/objects",
1290            "https://localhost/objects/",
1291            "https://service.localhost/objects/",
1292            "https://service.local/objects/",
1293            "https://localhost./objects/",
1294            "https://127.0.0.1/objects/",
1295            "https://10.0.0.1/objects/",
1296            "https://192.168.1.1/objects/",
1297            "https://169.254.1.1/objects/",
1298            "https://[::1]/objects/",
1299            "https://[fc00::1]/objects/",
1300            "https://[::ffff:127.0.0.1]/objects/",
1301            "https://preview.example.org/a/../objects/",
1302        ] {
1303            assert!(validate_location_base(base).is_err(), "{base}");
1304            // A missing source demonstrates validation precedes import and writes.
1305            let error = generate(Path::new("absent-source"), output.path(), base).unwrap_err();
1306            assert!(!error.is_empty(), "{base}");
1307            assert_eq!(fs::read_dir(output.path()).unwrap().count(), 0, "{base}");
1308        }
1309    }
1310
1311    #[test]
1312    fn preview_generation_is_deterministic_and_only_transport_bindings_change() {
1313        let source = private_source();
1314        let first = tempfile::tempdir().unwrap();
1315        let second = tempfile::tempdir().unwrap();
1316        let base = "https://preview-data.example.org/objects/sha256/";
1317        generate(source.path(), first.path(), base).unwrap();
1318        generate(source.path(), second.path(), base).unwrap();
1319        assert_eq!(tree_bytes(first.path()), tree_bytes(second.path()));
1320        check(source.path(), first.path(), base).unwrap();
1321        assert!(check(source.path(), first.path(), DEFAULT_LOCATION_BASE).is_err());
1322
1323        let default = root().join("tests/fixtures/hub/generated/v1");
1324        let preview_bytes = tree_bytes(first.path());
1325        let default_bytes = tree_bytes(&default);
1326        assert_eq!(
1327            preview_bytes.keys().collect::<Vec<_>>(),
1328            default_bytes.keys().collect::<Vec<_>>()
1329        );
1330        for (relative, bytes) in &preview_bytes {
1331            if !["manifest.json", "refs.json", "fixture.json"].contains(&relative.as_str()) {
1332                assert_eq!(bytes, &default_bytes[relative], "{relative}");
1333            }
1334        }
1335        let json = |dir: &Path, name: &str| -> serde_json::Value {
1336            serde_json::from_slice(&fs::read(dir.join(name)).unwrap()).unwrap()
1337        };
1338        let mut preview = json(first.path(), "manifest.json");
1339        let canonical = json(&default, "manifest.json");
1340        for (object, default_object) in preview["objects"]
1341            .as_array_mut()
1342            .unwrap()
1343            .iter_mut()
1344            .zip(canonical["objects"].as_array().unwrap())
1345        {
1346            assert_eq!(
1347                object["locations"],
1348                serde_json::json!([location(base, object["digest"].as_str().unwrap()).unwrap()])
1349            );
1350            object["locations"] = default_object["locations"].clone();
1351        }
1352        assert_eq!(preview, canonical);
1353        for name in ["refs.json", "fixture.json"] {
1354            let mut preview = json(first.path(), name);
1355            let canonical = json(&default, name);
1356            if name == "refs.json" {
1357                assert_ne!(
1358                    preview["refs"][0]["validator"],
1359                    canonical["refs"][0]["validator"]
1360                );
1361                preview["refs"][0]["validator"] = canonical["refs"][0]["validator"].clone();
1362            } else {
1363                assert_eq!(preview["location_base"], base);
1364                preview["location_base"] = canonical["location_base"].clone();
1365                preview["manifest_digest"] = canonical["manifest_digest"].clone();
1366            }
1367            assert_eq!(preview, canonical, "{name}");
1368        }
1369        // Even a re-sealed manifest must bind every object's location to the base.
1370        for index in 0..canonical["objects"].as_array().unwrap().len() {
1371            let candidate = copy_artifacts(first.path());
1372            mutate_manifest(candidate.path(), |value| {
1373                value["objects"][index]["locations"][0] =
1374                    serde_json::json!("https://other.example.org/tampered");
1375            });
1376            reseal_manifest_digest(candidate.path());
1377            let error = check(source.path(), candidate.path(), base).unwrap_err();
1378            assert!(
1379                error.contains("not digest addressed"),
1380                "object {index}: {error}"
1381            );
1382        }
1383        mutate_json(&first.path().join("fixture.json"), |value| {
1384            value["location_base"] = serde_json::json!(DEFAULT_LOCATION_BASE);
1385        });
1386        assert!(
1387            check(source.path(), first.path(), base)
1388                .unwrap_err()
1389                .contains("does not match")
1390        );
1391    }
1392
1393    fn tree_bytes(root: &Path) -> BTreeMap<String, Vec<u8>> {
1394        artifact_files(root)
1395            .unwrap()
1396            .into_iter()
1397            .map(|relative| {
1398                let bytes = fs::read(root.join(&relative)).unwrap();
1399                (relative, bytes)
1400            })
1401            .collect()
1402    }
1403
1404    #[test]
1405    fn rebuilt_source_is_deterministic_and_matches_the_checked_in_tree() {
1406        let workspace = tempfile::tempdir().unwrap();
1407        let first = workspace.path().join("first");
1408        let second = workspace.path().join("second");
1409        rebuild_source(&first).unwrap();
1410        rebuild_source(&second).unwrap();
1411        // Rebuilding over an existing tree replaces it with identical bytes.
1412        rebuild_source(&first).unwrap();
1413        let rebuilt = tree_bytes(&first);
1414        assert_eq!(rebuilt, tree_bytes(&second));
1415        assert_eq!(
1416            rebuilt,
1417            tree_bytes(&root().join("tests/fixtures/hub/openalex-source")),
1418            "checked-in source is not the Rust rebuild; run the generator with --rebuild-source"
1419        );
1420        assert_eq!(
1421            fs::read_dir(workspace.path()).unwrap().count(),
1422            2,
1423            "rebuild left staging directories behind"
1424        );
1425        verify_full(&first).unwrap();
1426    }
1427}