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