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        repository: repository.clone(),
461        default_ref: "main".into(),
462        resolved_ref: "main".into(),
463        package: PortablePackageReference {
464            format: PORTABLE_FORMAT.into(),
465            package_digest: Sha256Digest(exported_package_digest.clone()),
466            producing_core_version: derived.summary.package.producing_core_version.clone(),
467            object_digest: project_object.digest.clone(),
468        },
469        summary: Some(summary_reference(&derived, &summary_object)),
470        ontology,
471        lineage: None,
472        objects,
473    })?;
474    let summary = derived.summary;
475    let summary_digest = derived.summary_digest;
476    let manifest_bytes = manifest.to_canonical_json().map_err(err)?;
477    let manifest_digest = manifest.canonical_digest().map_err(err)?.0;
478    let refs = RefSet {
479        format: DISCOVERY_FORMAT.into(),
480        version: ProtocolVersion::CURRENT,
481        repository,
482        default_ref: "main".into(),
483        refs: vec![RepositoryRef {
484            name: "main".into(),
485            target: manifest.immutable_version.clone(),
486            validator: Sha256Digest(manifest_digest.clone()),
487        }],
488        extensions: BTreeMap::new(),
489    };
490    refs.validate_manifest(&manifest).map_err(err)?;
491    manifest.bind_summary(&summary).map_err(err)?;
492    let refs_bytes = refs.to_canonical_json().map_err(err)?;
493    let metadata = FixtureMetadata {
494        format: "graphforge-hub-fixture/1",
495        generator: GeneratorIdentity {
496            contract: GENERATOR_CONTRACT,
497            crate_name: "graphforge-cli",
498            source_digest: generator_source_digest(),
499        },
500        source: SourceIdentity {
501            tree_digest: tree_digest(source)?,
502            package_digest: source_report.package_digest,
503        },
504        object_path: OBJECT_PATH,
505        object_digest,
506        object_length: project_object.length,
507        package_digest: exported_package_digest,
508        summary_path: SUMMARY_PATH,
509        summary_digest: summary_digest.0,
510        summary_object_digest: summary_object.digest.0,
511        summary_object_length: summary_object.length,
512        module_objects: module_records,
513        manifest_digest,
514        location_base,
515    };
516    write(destination.join("manifest.json"), &manifest_bytes)?;
517    write(destination.join("refs.json"), &refs_bytes)?;
518    let mut metadata_bytes = serde_json::to_vec(&metadata).map_err(err)?;
519    metadata_bytes.push(b'\n');
520    write(destination.join("fixture.json"), &metadata_bytes)
521}
522
523/// Regenerate at `location_base` in a private directory and compare every artifact byte.
524pub fn check(source: &Path, expected: &Path, location_base: &str) -> Result<(), String> {
525    validate_location_base(location_base)?;
526    validate(source, expected, location_base)?;
527    let scratch = tempfile::tempdir().map_err(err)?;
528    generate(source, scratch.path(), location_base)?;
529    let regenerated = artifact_files(scratch.path())?;
530    if regenerated != artifact_files(expected)? {
531        return Err("generated Hub fixture artifact set drifted".into());
532    }
533    for relative in regenerated {
534        let actual = fs::read(scratch.path().join(&relative)).map_err(err)?;
535        let expected_bytes = fs::read(expected.join(&relative)).map_err(err)?;
536        if actual != expected_bytes {
537            return Err(format!("generated Hub fixture artifact drift: {relative}"));
538        }
539    }
540    Ok(())
541}
542
543/// Sorted relative paths of every regular file under `root`.
544fn artifact_files(root: &Path) -> Result<Vec<String>, String> {
545    let mut files = Vec::new();
546    let mut pending = vec![root.to_path_buf()];
547    while let Some(directory) = pending.pop() {
548        for entry in fs::read_dir(&directory).map_err(err)? {
549            let path = entry.map_err(err)?.path();
550            if fs::symlink_metadata(&path).map_err(err)?.is_dir() {
551                pending.push(path);
552            } else {
553                files.push(canonical_relative_path(
554                    path.strip_prefix(root).map_err(err)?,
555                )?);
556            }
557        }
558    }
559    files.sort();
560    Ok(files)
561}
562
563/// Validate all generator, source, portable, discovery, summary, and metadata bindings.
564fn validate(source: &Path, artifacts: &Path, location_base: &str) -> Result<(), String> {
565    let metadata: serde_json::Value =
566        serde_json::from_slice(&fs::read(artifacts.join("fixture.json")).map_err(err)?)
567            .map_err(err)?;
568    let manifest_bytes = fs::read(artifacts.join("manifest.json")).map_err(err)?;
569    let refs_bytes = fs::read(artifacts.join("refs.json")).map_err(err)?;
570    let manifest =
571        DiscoveryManifest::from_json(&manifest_bytes, DiscoveryLimits::default()).map_err(err)?;
572    let refs = RefSet::from_json(&refs_bytes, DiscoveryLimits::default()).map_err(err)?;
573    refs.validate_manifest(&manifest).map_err(err)?;
574    let module_paths = manifest
575        .ontology
576        .iter()
577        .flat_map(|inventory| &inventory.modules)
578        .map(|module| module_object_path(&module.content_digest.0))
579        .collect::<Result<Vec<_>, _>>()?;
580    validate_expected_tree(artifacts, &module_paths)?;
581    let expected_repository = repository_identity();
582    if manifest.repository != expected_repository
583        || manifest.default_ref != "main"
584        || manifest.resolved_ref != "main"
585        || refs.repository != expected_repository
586        || refs.default_ref != "main"
587        || manifest.immutable_version != manifest.package.package_digest
588    {
589        return Err("fixture repository, ref, or immutable version binding is invalid".into());
590    }
591    let manifest_digest = manifest.canonical_digest().map_err(err)?.0;
592    let reference = refs
593        .refs
594        .iter()
595        .find(|reference| reference.name == "main")
596        .ok_or("fixture main ref is absent")?;
597    if reference.validator.0 != manifest_digest {
598        return Err("fixture validator does not bind canonical manifest bytes".into());
599    }
600    if metadata["location_base"] != location_base {
601        return Err("fixture location base does not match the requested base".into());
602    }
603    for object in &manifest.objects {
604        if object.locations != [location(location_base, &object.digest.0)?] {
605            return Err(
606                "fixture object location is not digest addressed at the requested base".into(),
607            );
608        }
609    }
610    let selected = manifest.package_object().map_err(err)?;
611    let object_path = metadata["object_path"]
612        .as_str()
613        .ok_or("fixture object path is absent")?;
614    if object_path != OBJECT_PATH {
615        return Err("fixture object path is invalid".into());
616    }
617    let object = artifacts.join(object_path);
618    let bytes = fs::read(&object).map_err(err)?;
619    let report = verify_full(&object)?;
620    if digest_bytes(&bytes) != selected.digest.0
621        || bytes.len() as u64 != selected.length
622        || report.package_digest != manifest.package.package_digest.0
623        || metadata["format"] != "graphforge-hub-fixture/1"
624        || metadata["object_digest"] != selected.digest.0
625        || metadata["object_length"] != selected.length
626        || metadata["package_digest"] != manifest.package.package_digest.0
627        || metadata["manifest_digest"] != manifest_digest
628        || metadata["generator"]["contract"] != GENERATOR_CONTRACT
629        || metadata["generator"]["crate_name"] != "graphforge-cli"
630        || metadata["generator"]["source_digest"] != generator_source_digest()
631        || metadata["source"]["tree_digest"] != tree_digest(source)?
632        || metadata["source"]["package_digest"] != verify_full(source)?.package_digest
633    {
634        return Err(
635            "fixture portable, discovery, metadata, provenance, or source binding is invalid"
636                .into(),
637        );
638    }
639    validate_summary(artifacts, &manifest, &metadata)?;
640    validate_modules(
641        artifacts,
642        &manifest,
643        &manifest_bytes,
644        &refs_bytes,
645        &metadata,
646    )
647}
648
649/// The summary object must hash to the manifest descriptor, parse through the
650/// public contract, and bind to the manifest it is advertised by.
651fn validate_summary(
652    artifacts: &Path,
653    manifest: &DiscoveryManifest,
654    metadata: &serde_json::Value,
655) -> Result<(), String> {
656    let reference = manifest
657        .summary
658        .as_ref()
659        .ok_or("fixture manifest does not advertise a summary")?;
660    let selected = manifest.summary_object().map_err(err)?;
661    let bytes = fs::read(artifacts.join(SUMMARY_PATH)).map_err(err)?;
662    if digest_bytes(&bytes) != reference.object_digest.0 || bytes.len() as u64 != selected.length {
663        return Err("fixture summary object bytes do not match the manifest descriptor".into());
664    }
665    let summary = ProjectSummary::from_json(&bytes, DiscoveryLimits::default()).map_err(err)?;
666    manifest.bind_summary(&summary).map_err(err)?;
667    if summary.to_canonical_json().map_err(err)? != bytes {
668        return Err("fixture summary object is not canonical".into());
669    }
670    if metadata["summary_path"] != SUMMARY_PATH
671        || metadata["summary_digest"] != reference.summary_digest.0
672        || metadata["summary_object_digest"] != reference.object_digest.0
673        || metadata["summary_object_length"] != selected.length
674    {
675        return Err("fixture summary metadata binding is invalid".into());
676    }
677    Ok(())
678}
679
680/// Every advertised module package must verify and resolve to exactly the
681/// advertised identity, and `fixture.json` must record it.
682fn validate_modules(
683    artifacts: &Path,
684    manifest: &DiscoveryManifest,
685    manifest_bytes: &[u8],
686    refs_bytes: &[u8],
687    metadata: &serde_json::Value,
688) -> Result<(), String> {
689    let mut records = Vec::new();
690    for module in manifest
691        .ontology
692        .iter()
693        .flat_map(|inventory| &inventory.modules)
694    {
695        let package = module
696            .package
697            .as_ref()
698            .ok_or("fixture ontology module has no package")?;
699        let identity = ExactIdentity {
700            id: module.id.clone(),
701            version: module.version.clone(),
702            content_digest: module.content_digest.clone(),
703        };
704        let (_, selected) = manifest.ontology_module_object(&identity).map_err(err)?;
705        let path = module_object_path(&module.content_digest.0)?;
706        let file = artifacts.join(&path);
707        let bytes = fs::read(&file).map_err(err)?;
708        if digest_bytes(&bytes) != selected.digest.0 || bytes.len() as u64 != selected.length {
709            return Err("fixture module object bytes do not match the manifest descriptor".into());
710        }
711        let resolved = resolve_discovered_ontology_module(&DiscoveryOntologyModuleRequest {
712            manifest_json: manifest_bytes,
713            refs_json: refs_bytes,
714            expected_repository: &repository_identity(),
715            module: &identity,
716            package: &file,
717            discovery_limits: DiscoveryLimits::default(),
718            portable_limits: PortableLimits::default(),
719            cancelled: None,
720        })
721        .map_err(err)?;
722        if resolved.module.ontology_id != module.id
723            || resolved.module.authored_version != module.version
724            || format!("sha256:{}", resolved.module.canonical_digest) != module.content_digest.0
725            || resolved.package_digest != package.package_digest.0
726        {
727            return Err("fixture module package does not resolve to the advertised module".into());
728        }
729        records.push(ModuleObjectRecord {
730            ontology_id: module.id.clone(),
731            version: module.version.clone(),
732            content_digest: module.content_digest.0.clone(),
733            package_digest: package.package_digest.0.clone(),
734            object_digest: selected.digest.0.clone(),
735            object_length: selected.length,
736            object_path: path,
737        });
738    }
739    if metadata["module_objects"] != serde_json::to_value(&records).map_err(err)? {
740        return Err("fixture module object records do not match the manifest".into());
741    }
742    Ok(())
743}
744
745fn validate_expected_tree(root: &Path, module_paths: &[String]) -> Result<(), String> {
746    let mut actual = Vec::new();
747    let mut pending = vec![root.to_path_buf()];
748    while let Some(directory) = pending.pop() {
749        for entry in fs::read_dir(&directory).map_err(err)? {
750            let entry = entry.map_err(err)?;
751            let path = entry.path();
752            let relative = canonical_relative_path(path.strip_prefix(root).map_err(err)?)?;
753            let metadata = fs::symlink_metadata(&path).map_err(err)?;
754            if metadata.file_type().is_symlink() {
755                return Err(format!(
756                    "fixture artifact tree contains a symlink: {relative}"
757                ));
758            }
759            if metadata.is_dir() {
760                actual.push(format!("{relative}/"));
761                pending.push(path);
762            } else if metadata.is_file() {
763                actual.push(relative);
764            } else {
765                return Err("fixture artifact tree contains a non-file entry".into());
766            }
767        }
768    }
769    actual.sort();
770    let mut expected: Vec<String> = FIXED_FILES
771        .iter()
772        .map(|path| (*path).to_owned())
773        .chain(module_paths.iter().cloned())
774        .chain(["objects/".to_owned()])
775        .collect();
776    expected.sort();
777    if actual != expected {
778        return Err("fixture artifact tree does not match the exact generated contract".into());
779    }
780    Ok(())
781}
782
783fn write(path: PathBuf, bytes: &[u8]) -> Result<(), String> {
784    if let Some(parent) = path.parent() {
785        fs::create_dir_all(parent).map_err(err)?;
786    }
787    fs::write(path, bytes).map_err(err)
788}
789
790fn generator_source_digest() -> String {
791    let mut hasher = Sha256::new();
792    hasher.update(b"graphforge-hub-fixture-generator-source/1\0");
793    hasher.update(include_bytes!("hub_fixture_artifacts.rs"));
794    hasher.update(b"\0");
795    hasher.update(include_bytes!("hub_publish/publication.rs"));
796    format!("sha256:{}", hex(&hasher.finalize()))
797}
798
799fn hex(bytes: &[u8]) -> String {
800    bytes.iter().fold(
801        String::with_capacity(bytes.len() * 2),
802        |mut output, byte| {
803            write!(output, "{byte:02x}").expect("writing to String cannot fail");
804            output
805        },
806    )
807}
808
809fn canonical_relative_path(path: &Path) -> Result<String, String> {
810    path.components()
811        .map(|component| match component {
812            std::path::Component::Normal(value) => value
813                .to_str()
814                .map(str::to_owned)
815                .ok_or_else(|| "fixture path component is not UTF-8".to_owned()),
816            _ => Err("fixture path is not a normalized relative path".to_owned()),
817        })
818        .collect::<Result<Vec<_>, _>>()
819        .map(|components| components.join("/"))
820}
821
822fn tree_digest(root: &Path) -> Result<String, String> {
823    fn walk(root: &Path, current: &Path, files: &mut Vec<PathBuf>) -> Result<(), String> {
824        for entry in fs::read_dir(current).map_err(|error| error.to_string())? {
825            let path = entry.map_err(|error| error.to_string())?.path();
826            let metadata = fs::symlink_metadata(&path).map_err(|error| error.to_string())?;
827            if metadata.file_type().is_symlink() {
828                return Err("fixture source may not contain symlinks".into());
829            }
830            if metadata.is_dir() {
831                walk(root, &path, files)?;
832            } else if metadata.is_file() {
833                files.push(
834                    path.strip_prefix(root)
835                        .map_err(|error| error.to_string())?
836                        .to_path_buf(),
837                );
838            } else {
839                return Err("fixture source contains a non-file entry".into());
840            }
841        }
842        Ok(())
843    }
844    let mut files = Vec::new();
845    walk(root, root, &mut files)?;
846    files.sort();
847    let mut hasher = Sha256::new();
848    hasher.update(b"graphforge-hub-fixture-source/1\0");
849    for relative in files {
850        let canonical = canonical_relative_path(&relative)?;
851        let name = canonical.as_bytes();
852        let bytes = fs::read(root.join(&relative)).map_err(|error| error.to_string())?;
853        hasher.update((name.len() as u64).to_be_bytes());
854        hasher.update(name);
855        hasher.update((bytes.len() as u64).to_be_bytes());
856        hasher.update(&bytes);
857    }
858    Ok(format!("sha256:{}", hex(&hasher.finalize())))
859}
860
861#[cfg(test)]
862mod tests {
863    use super::*;
864    use graphforge_api::{PortableMode, PortableVerifyRequest, verify_portable};
865
866    fn root() -> PathBuf {
867        PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../..")
868    }
869
870    fn private_source() -> tempfile::TempDir {
871        fn copy_tree(source: &Path, destination: &Path) {
872            fs::create_dir_all(destination).unwrap();
873            for entry in fs::read_dir(source).unwrap() {
874                let entry = entry.unwrap();
875                let destination = destination.join(entry.file_name());
876                if entry.file_type().unwrap().is_dir() {
877                    copy_tree(&entry.path(), &destination);
878                } else {
879                    fs::copy(entry.path(), destination).unwrap();
880                }
881            }
882        }
883        let private = tempfile::tempdir().unwrap();
884        copy_tree(
885            &root().join("tests/fixtures/hub/openalex-source"),
886            private.path(),
887        );
888        private
889    }
890
891    #[test]
892    fn relative_paths_use_platform_independent_slash_encoding() {
893        let nested = PathBuf::from("objects").join("sha256").join("fixture.gfpb");
894        assert_eq!(
895            canonical_relative_path(&nested).unwrap(),
896            "objects/sha256/fixture.gfpb"
897        );
898        assert!(canonical_relative_path(Path::new("../outside")).is_err());
899    }
900
901    fn copy_artifacts(source: &Path) -> tempfile::TempDir {
902        let private = tempfile::tempdir().unwrap();
903        copy_tree_for_test(source, private.path());
904        private
905    }
906
907    fn copy_tree_for_test(source: &Path, destination: &Path) {
908        fs::create_dir_all(destination).unwrap();
909        for entry in fs::read_dir(source).unwrap() {
910            let entry = entry.unwrap();
911            let destination = destination.join(entry.file_name());
912            if entry.file_type().unwrap().is_dir() {
913                copy_tree_for_test(&entry.path(), &destination);
914            } else {
915                fs::copy(entry.path(), destination).unwrap();
916            }
917        }
918    }
919
920    #[test]
921    fn checked_in_hub_fixture_is_exact_rust_output() {
922        let source = private_source();
923        let artifacts = copy_artifacts(&root().join("tests/fixtures/hub/generated/v1"));
924        check(source.path(), artifacts.path(), DEFAULT_LOCATION_BASE).unwrap();
925    }
926
927    #[test]
928    fn check_rejects_tampered_artifact() {
929        let source = private_source();
930        let output = tempfile::tempdir().unwrap();
931        generate(source.path(), output.path(), DEFAULT_LOCATION_BASE).unwrap();
932        fs::write(output.path().join("refs.json"), b"{}\n").unwrap();
933        let error = check(source.path(), output.path(), DEFAULT_LOCATION_BASE).unwrap_err();
934        assert!(!error.is_empty());
935    }
936
937    #[test]
938    fn generated_artifacts_are_cross_contract_coherent() {
939        let generated = root().join("tests/fixtures/hub/generated/v1");
940        let manifest_bytes = fs::read(generated.join("manifest.json")).unwrap();
941        let refs_bytes = fs::read(generated.join("refs.json")).unwrap();
942        let manifest = DiscoveryManifest::from_json(
943            &manifest_bytes,
944            graphforge_discovery::DiscoveryLimits::default(),
945        )
946        .unwrap();
947        let refs = RefSet::from_json(
948            &refs_bytes,
949            graphforge_discovery::DiscoveryLimits::default(),
950        )
951        .unwrap();
952        refs.validate_manifest(&manifest).unwrap();
953        let object = fs::read(generated.join(OBJECT_PATH)).unwrap();
954        let selected = manifest.package_object().unwrap();
955        assert_eq!(selected.digest.0, digest_bytes(&object));
956        assert_eq!(selected.length, object.len() as u64);
957        assert_eq!(
958            refs.refs[0].validator.0,
959            manifest.canonical_digest().unwrap().0
960        );
961        let private_object = tempfile::NamedTempFile::new().unwrap();
962        fs::write(private_object.path(), &object).unwrap();
963        let verified = verify_portable(
964            &PortableVerifyRequest {
965                input: private_object.path().to_path_buf(),
966                mode: PortableMode::Full,
967                limits: PortableLimits::default(),
968            },
969            None,
970        )
971        .unwrap();
972        assert_eq!(verified.package_digest, manifest.package.package_digest.0);
973        let metadata: serde_json::Value =
974            serde_json::from_slice(&fs::read(generated.join("fixture.json")).unwrap()).unwrap();
975        assert_eq!(metadata["object_digest"], selected.digest.0);
976        assert_eq!(metadata["object_length"], selected.length);
977        assert_eq!(
978            metadata["package_digest"],
979            manifest.package.package_digest.0
980        );
981        assert_eq!(metadata["manifest_digest"], refs.refs[0].validator.0);
982    }
983
984    #[test]
985    fn repeated_generation_is_byte_identical() {
986        let source = private_source();
987        let first = tempfile::tempdir().unwrap();
988        let second = tempfile::tempdir().unwrap();
989        generate(source.path(), first.path(), DEFAULT_LOCATION_BASE).unwrap();
990        generate(source.path(), second.path(), DEFAULT_LOCATION_BASE).unwrap();
991        let files = artifact_files(first.path()).unwrap();
992        assert_eq!(files, artifact_files(second.path()).unwrap());
993        for relative in files {
994            assert_eq!(
995                fs::read(first.path().join(&relative)).unwrap(),
996                fs::read(second.path().join(&relative)).unwrap(),
997                "{relative}"
998            );
999        }
1000    }
1001
1002    #[test]
1003    fn adversarial_binding_matrix_fails_semantic_validation_and_drift() {
1004        let source = private_source();
1005        let pristine = root().join("tests/fixtures/hub/generated/v1");
1006        let cases: &[(&str, &str, fn(&mut serde_json::Value))] = &[
1007            ("version", "manifest.json", |value| {
1008                value["version"]["major"] = serde_json::json!(999)
1009            }),
1010            ("object-digest", "manifest.json", |value| {
1011                value["package"]["object_digest"] =
1012                    serde_json::json!(format!("sha256:{}", "0".repeat(64)))
1013            }),
1014            ("object-length", "manifest.json", |value| {
1015                value["objects"][0]["length"] = serde_json::json!(1)
1016            }),
1017            ("object-location", "manifest.json", |value| {
1018                value["objects"][0]["locations"][0] =
1019                    serde_json::json!("https://example.com/object")
1020            }),
1021            ("repository", "manifest.json", |value| {
1022                value["repository"]["owner"] = serde_json::json!("other")
1023            }),
1024            ("default-ref", "manifest.json", |value| {
1025                value["default_ref"] = serde_json::json!("other")
1026            }),
1027            ("immutable-version", "manifest.json", |value| {
1028                value["immutable_version"] = serde_json::json!(format!("sha256:{}", "1".repeat(64)))
1029            }),
1030            ("package-digest", "manifest.json", |value| {
1031                value["package"]["package_digest"] =
1032                    serde_json::json!(format!("sha256:{}", "5".repeat(64)))
1033            }),
1034            ("refs-target", "refs.json", |value| {
1035                value["refs"][0]["target"] = serde_json::json!(format!("sha256:{}", "2".repeat(64)))
1036            }),
1037            ("refs-validator", "refs.json", |value| {
1038                value["refs"][0]["validator"] =
1039                    serde_json::json!(format!("sha256:{}", "3".repeat(64)))
1040            }),
1041            ("provenance", "fixture.json", |value| {
1042                value["generator"]["source_digest"] =
1043                    serde_json::json!(format!("sha256:{}", "4".repeat(64)))
1044            }),
1045            ("object-path", "fixture.json", |value| {
1046                value["object_path"] = serde_json::json!("../../outside.gfpb")
1047            }),
1048        ];
1049        for (name, relative, mutate) in cases {
1050            let candidate = copy_artifacts(&pristine);
1051            let path = candidate.path().join(relative);
1052            let mut value: serde_json::Value =
1053                serde_json::from_slice(&fs::read(&path).unwrap()).unwrap();
1054            mutate(&mut value);
1055            fs::write(&path, serde_json::to_vec(&value).unwrap()).unwrap();
1056            assert!(
1057                validate(source.path(), candidate.path(), DEFAULT_LOCATION_BASE).is_err(),
1058                "semantic case {name}"
1059            );
1060            assert!(
1061                check(source.path(), candidate.path(), DEFAULT_LOCATION_BASE).is_err(),
1062                "drift case {name}"
1063            );
1064        }
1065        let package = copy_artifacts(&pristine);
1066        let path = package.path().join(OBJECT_PATH);
1067        let mut bytes = fs::read(&path).unwrap();
1068        bytes[1024] ^= 1;
1069        fs::write(path, bytes).unwrap();
1070        assert!(validate(source.path(), package.path(), DEFAULT_LOCATION_BASE).is_err());
1071        assert!(check(source.path(), package.path(), DEFAULT_LOCATION_BASE).is_err());
1072        let altered_source = private_source();
1073        fs::write(altered_source.path().join("bag-info.txt"), b"changed").unwrap();
1074        assert!(validate(altered_source.path(), &pristine, DEFAULT_LOCATION_BASE).is_err());
1075    }
1076
1077    #[test]
1078    fn exact_artifact_tree_rejects_extra_files_and_directories() {
1079        let source = private_source();
1080        let pristine = root().join("tests/fixtures/hub/generated/v1");
1081        for relative in ["extra.json", "objects/extra.gfpb", "extra/nested.json"] {
1082            let candidate = copy_artifacts(&pristine);
1083            let path = candidate.path().join(relative);
1084            fs::create_dir_all(path.parent().unwrap()).unwrap();
1085            fs::write(path, b"extra").unwrap();
1086            assert!(
1087                validate(source.path(), candidate.path(), DEFAULT_LOCATION_BASE).is_err(),
1088                "{relative}"
1089            );
1090            assert!(
1091                check(source.path(), candidate.path(), DEFAULT_LOCATION_BASE).is_err(),
1092                "{relative}"
1093            );
1094        }
1095    }
1096
1097    /// Rewrite a JSON artifact in place.
1098    fn mutate_json(path: &Path, mutate: impl FnOnce(&mut serde_json::Value)) {
1099        let mut value: serde_json::Value =
1100            serde_json::from_slice(&fs::read(path).unwrap()).unwrap();
1101        mutate(&mut value);
1102        fs::write(path, serde_json::to_vec(&value).unwrap()).unwrap();
1103    }
1104
1105    /// Re-bind the ref validator and fixture metadata to the current manifest so a
1106    /// test reaches the check it targets instead of the manifest-digest binding.
1107    fn reseal_manifest_digest(artifacts: &Path) {
1108        let manifest = DiscoveryManifest::from_json(
1109            &fs::read(artifacts.join("manifest.json")).unwrap(),
1110            DiscoveryLimits::default(),
1111        )
1112        .unwrap();
1113        let digest = manifest.canonical_digest().unwrap().0;
1114        mutate_json(&artifacts.join("refs.json"), |value| {
1115            value["refs"][0]["validator"] = serde_json::json!(digest);
1116        });
1117        mutate_json(&artifacts.join("fixture.json"), |value| {
1118            value["manifest_digest"] = serde_json::json!(digest);
1119        });
1120    }
1121
1122    fn other_digest() -> serde_json::Value {
1123        serde_json::json!(format!("sha256:{}", "7".repeat(64)))
1124    }
1125
1126    /// Apply `mutate` to a pristine copy and require `validate` to reject it with
1127    /// a message containing `expected`, and `check` to reject it too.
1128    fn assert_rejected(name: &str, expected: &str, mutate: impl FnOnce(&Path)) {
1129        let source = private_source();
1130        let candidate = copy_artifacts(&root().join("tests/fixtures/hub/generated/v1"));
1131        mutate(candidate.path());
1132        let error = validate(source.path(), candidate.path(), DEFAULT_LOCATION_BASE).unwrap_err();
1133        assert!(error.contains(expected), "{name}: {error}");
1134        assert!(
1135            check(source.path(), candidate.path(), DEFAULT_LOCATION_BASE).is_err(),
1136            "{name}"
1137        );
1138    }
1139
1140    fn mutate_manifest(dir: &Path, mutate: impl FnOnce(&mut serde_json::Value)) {
1141        mutate_json(&dir.join("manifest.json"), mutate);
1142    }
1143
1144    #[test]
1145    fn manifest_summary_and_ontology_descriptors_are_each_enforced() {
1146        assert_rejected("summary-digest", "disagrees with manifest", |dir| {
1147            mutate_manifest(dir, |value| {
1148                value["summary"]["summary_digest"] = other_digest();
1149            });
1150            reseal_manifest_digest(dir);
1151        });
1152        assert_rejected("summary-removed", "does not advertise a summary", |dir| {
1153            mutate_manifest(dir, |value| {
1154                value.as_object_mut().unwrap().remove("summary");
1155            });
1156            reseal_manifest_digest(dir);
1157        });
1158        assert_rejected(
1159            "ontology-composition-digest",
1160            "disagrees with manifest",
1161            |dir| {
1162                mutate_manifest(dir, |value| {
1163                    value["ontology"]["composition_digest"] = other_digest();
1164                });
1165                reseal_manifest_digest(dir);
1166            },
1167        );
1168        assert_rejected("ontology-removed", "exact generated contract", |dir| {
1169            mutate_manifest(dir, |value| {
1170                value.as_object_mut().unwrap().remove("ontology");
1171            });
1172            reseal_manifest_digest(dir);
1173        });
1174        assert_rejected(
1175            "module-package-digest",
1176            "reference mismatch: PackageDigest",
1177            |dir| {
1178                mutate_manifest(dir, |value| {
1179                    value["ontology"]["modules"][0]["package"]["package_digest"] = other_digest();
1180                });
1181                reseal_manifest_digest(dir);
1182            },
1183        );
1184        // The manifest itself no longer parses, so no reseal is possible.
1185        assert_rejected(
1186            "module-package-is-project-package",
1187            "module package object is incompatible",
1188            |dir| {
1189                mutate_manifest(dir, |value| {
1190                    let project = value["package"]["object_digest"].clone();
1191                    value["ontology"]["modules"][0]["package"]["object_digest"] = project;
1192                });
1193            },
1194        );
1195    }
1196
1197    #[test]
1198    fn summary_and_module_objects_and_records_are_each_enforced() {
1199        let pristine = root().join("tests/fixtures/hub/generated/v1");
1200        let module_object = fs::read_dir(pristine.join("objects"))
1201            .unwrap()
1202            .map(|entry| entry.unwrap().file_name().into_string().unwrap())
1203            .find(|name| name.starts_with("ontology-module-"))
1204            .unwrap();
1205        assert_rejected("summary-object-bytes", "summary object bytes", |dir| {
1206            let path = dir.join(SUMMARY_PATH);
1207            let mut bytes = fs::read(&path).unwrap();
1208            bytes[10] ^= 1;
1209            fs::write(path, bytes).unwrap();
1210        });
1211        assert_rejected("module-object-bytes", "module object bytes", |dir| {
1212            let path = dir.join("objects").join(&module_object);
1213            let mut bytes = fs::read(&path).unwrap();
1214            bytes[1024] ^= 1;
1215            fs::write(path, bytes).unwrap();
1216        });
1217        assert_rejected("fixture-summary-digest", "summary metadata", |dir| {
1218            mutate_json(&dir.join("fixture.json"), |value| {
1219                value["summary_digest"] = other_digest();
1220            });
1221        });
1222        assert_rejected("fixture-module-record", "module object records", |dir| {
1223            mutate_json(&dir.join("fixture.json"), |value| {
1224                value["module_objects"][0]["package_digest"] = other_digest();
1225            });
1226        });
1227    }
1228
1229    #[test]
1230    fn summary_and_descriptors_do_not_depend_on_the_object_location_base() {
1231        let source = private_source();
1232        let first = tempfile::tempdir().unwrap();
1233        let second = tempfile::tempdir().unwrap();
1234        generate(source.path(), first.path(), DEFAULT_LOCATION_BASE).unwrap();
1235        let mirror = "https://mirror.example.org/content/";
1236        generate(source.path(), second.path(), mirror).unwrap();
1237
1238        assert_eq!(
1239            fs::read(first.path().join(SUMMARY_PATH)).unwrap(),
1240            fs::read(second.path().join(SUMMARY_PATH)).unwrap()
1241        );
1242        let manifest = |dir: &Path| -> serde_json::Value {
1243            serde_json::from_slice(&fs::read(dir.join("manifest.json")).unwrap()).unwrap()
1244        };
1245        let (first_manifest, second_manifest) = (manifest(first.path()), manifest(second.path()));
1246        for field in [
1247            "summary",
1248            "ontology",
1249            "package",
1250            "immutable_version",
1251            "repository",
1252        ] {
1253            assert_eq!(first_manifest[field], second_manifest[field], "{field}");
1254            assert!(!first_manifest[field].is_null(), "{field}");
1255        }
1256        // Only transport differs: same objects, same digests, different locations.
1257        let objects =
1258            |manifest: &serde_json::Value| -> Vec<(serde_json::Value, serde_json::Value)> {
1259                manifest["objects"]
1260                    .as_array()
1261                    .unwrap()
1262                    .iter()
1263                    .map(|object| (object["digest"].clone(), object["locations"].clone()))
1264                    .collect()
1265            };
1266        let (default_objects, mirror_objects) =
1267            (objects(&first_manifest), objects(&second_manifest));
1268        assert_eq!(default_objects.len(), 3);
1269        for ((first_digest, first_locations), (second_digest, second_locations)) in
1270            default_objects.iter().zip(&mirror_objects)
1271        {
1272            assert_eq!(first_digest, second_digest);
1273            assert_ne!(first_locations, second_locations);
1274            assert!(
1275                first_locations[0]
1276                    .as_str()
1277                    .unwrap()
1278                    .starts_with(DEFAULT_LOCATION_BASE)
1279            );
1280            assert_eq!(
1281                second_locations[0].as_str().unwrap(),
1282                format!(
1283                    "{mirror}{}",
1284                    first_digest
1285                        .as_str()
1286                        .unwrap()
1287                        .strip_prefix("sha256:")
1288                        .unwrap()
1289                )
1290            );
1291        }
1292        // Every non-manifest artifact is byte-identical across bases.
1293        for relative in artifact_files(first.path()).unwrap() {
1294            if relative == "manifest.json" || relative == "refs.json" || relative == "fixture.json"
1295            {
1296                continue;
1297            }
1298            assert_eq!(
1299                fs::read(first.path().join(&relative)).unwrap(),
1300                fs::read(second.path().join(&relative)).unwrap(),
1301                "{relative}"
1302            );
1303        }
1304        let metadata = |dir: &Path| -> serde_json::Value {
1305            serde_json::from_slice(&fs::read(dir.join("fixture.json")).unwrap()).unwrap()
1306        };
1307        let (first_metadata, second_metadata) = (metadata(first.path()), metadata(second.path()));
1308        for field in [
1309            "summary_digest",
1310            "summary_object_digest",
1311            "module_objects",
1312            "package_digest",
1313        ] {
1314            assert_eq!(first_metadata[field], second_metadata[field], "{field}");
1315        }
1316        // The mirror manifest is self-consistent but is not the checked-in
1317        // location contract.
1318        assert!(validate(source.path(), second.path(), DEFAULT_LOCATION_BASE).is_err());
1319    }
1320
1321    #[test]
1322    fn location_bases_follow_public_https_transport_rules_before_writing() {
1323        for base in [
1324            DEFAULT_LOCATION_BASE,
1325            "https://preview-data.example.org/objects/sha256/",
1326            "https://8.8.8.8/objects/",
1327            "https://[2606:4700:4700::1111]/objects/",
1328        ] {
1329            validate_location_base(base).unwrap();
1330        }
1331        let output = tempfile::tempdir().unwrap();
1332        for base in [
1333            "http://preview.example.org/objects/",
1334            "https://user:secret@preview.example.org/objects/",
1335            "https://preview.example.org/objects/?token=x/",
1336            "https://preview.example.org/objects/#fragment/",
1337            "https://preview.example.org/objects",
1338            "https://localhost/objects/",
1339            "https://service.localhost/objects/",
1340            "https://service.local/objects/",
1341            "https://localhost./objects/",
1342            "https://127.0.0.1/objects/",
1343            "https://10.0.0.1/objects/",
1344            "https://192.168.1.1/objects/",
1345            "https://169.254.1.1/objects/",
1346            "https://[::1]/objects/",
1347            "https://[fc00::1]/objects/",
1348            "https://[::ffff:127.0.0.1]/objects/",
1349            "https://preview.example.org/a/../objects/",
1350        ] {
1351            assert!(validate_location_base(base).is_err(), "{base}");
1352            // A missing source demonstrates validation precedes import and writes.
1353            let error = generate(Path::new("absent-source"), output.path(), base).unwrap_err();
1354            assert!(!error.is_empty(), "{base}");
1355            assert_eq!(fs::read_dir(output.path()).unwrap().count(), 0, "{base}");
1356        }
1357    }
1358
1359    #[test]
1360    fn preview_generation_is_deterministic_and_only_transport_bindings_change() {
1361        let source = private_source();
1362        let first = tempfile::tempdir().unwrap();
1363        let second = tempfile::tempdir().unwrap();
1364        let base = "https://preview-data.example.org/objects/sha256/";
1365        generate(source.path(), first.path(), base).unwrap();
1366        generate(source.path(), second.path(), base).unwrap();
1367        assert_eq!(tree_bytes(first.path()), tree_bytes(second.path()));
1368        check(source.path(), first.path(), base).unwrap();
1369        assert!(check(source.path(), first.path(), DEFAULT_LOCATION_BASE).is_err());
1370
1371        let default = root().join("tests/fixtures/hub/generated/v1");
1372        let preview_bytes = tree_bytes(first.path());
1373        let default_bytes = tree_bytes(&default);
1374        assert_eq!(
1375            preview_bytes.keys().collect::<Vec<_>>(),
1376            default_bytes.keys().collect::<Vec<_>>()
1377        );
1378        for (relative, bytes) in &preview_bytes {
1379            if !["manifest.json", "refs.json", "fixture.json"].contains(&relative.as_str()) {
1380                assert_eq!(bytes, &default_bytes[relative], "{relative}");
1381            }
1382        }
1383        let json = |dir: &Path, name: &str| -> serde_json::Value {
1384            serde_json::from_slice(&fs::read(dir.join(name)).unwrap()).unwrap()
1385        };
1386        let mut preview = json(first.path(), "manifest.json");
1387        let canonical = json(&default, "manifest.json");
1388        for (object, default_object) in preview["objects"]
1389            .as_array_mut()
1390            .unwrap()
1391            .iter_mut()
1392            .zip(canonical["objects"].as_array().unwrap())
1393        {
1394            assert_eq!(
1395                object["locations"],
1396                serde_json::json!([location(base, object["digest"].as_str().unwrap()).unwrap()])
1397            );
1398            object["locations"] = default_object["locations"].clone();
1399        }
1400        assert_eq!(preview, canonical);
1401        for name in ["refs.json", "fixture.json"] {
1402            let mut preview = json(first.path(), name);
1403            let canonical = json(&default, name);
1404            if name == "refs.json" {
1405                assert_ne!(
1406                    preview["refs"][0]["validator"],
1407                    canonical["refs"][0]["validator"]
1408                );
1409                preview["refs"][0]["validator"] = canonical["refs"][0]["validator"].clone();
1410            } else {
1411                assert_eq!(preview["location_base"], base);
1412                preview["location_base"] = canonical["location_base"].clone();
1413                preview["manifest_digest"] = canonical["manifest_digest"].clone();
1414            }
1415            assert_eq!(preview, canonical, "{name}");
1416        }
1417        // Even a re-sealed manifest must bind every object's location to the base.
1418        for index in 0..canonical["objects"].as_array().unwrap().len() {
1419            let candidate = copy_artifacts(first.path());
1420            mutate_manifest(candidate.path(), |value| {
1421                value["objects"][index]["locations"][0] =
1422                    serde_json::json!("https://other.example.org/tampered");
1423            });
1424            reseal_manifest_digest(candidate.path());
1425            let error = check(source.path(), candidate.path(), base).unwrap_err();
1426            assert!(
1427                error.contains("not digest addressed"),
1428                "object {index}: {error}"
1429            );
1430        }
1431        mutate_json(&first.path().join("fixture.json"), |value| {
1432            value["location_base"] = serde_json::json!(DEFAULT_LOCATION_BASE);
1433        });
1434        assert!(
1435            check(source.path(), first.path(), base)
1436                .unwrap_err()
1437                .contains("does not match")
1438        );
1439    }
1440
1441    fn tree_bytes(root: &Path) -> BTreeMap<String, Vec<u8>> {
1442        artifact_files(root)
1443            .unwrap()
1444            .into_iter()
1445            .map(|relative| {
1446                let bytes = fs::read(root.join(&relative)).unwrap();
1447                (relative, bytes)
1448            })
1449            .collect()
1450    }
1451
1452    #[test]
1453    fn rebuilt_source_is_deterministic_and_matches_the_checked_in_tree() {
1454        let workspace = tempfile::tempdir().unwrap();
1455        let first = workspace.path().join("first");
1456        let second = workspace.path().join("second");
1457        rebuild_source(&first).unwrap();
1458        rebuild_source(&second).unwrap();
1459        // Rebuilding over an existing tree replaces it with identical bytes.
1460        rebuild_source(&first).unwrap();
1461        let rebuilt = tree_bytes(&first);
1462        let independent = tree_bytes(&second);
1463        if rebuilt != independent {
1464            let changed: std::collections::BTreeSet<_> = rebuilt
1465                .keys()
1466                .chain(independent.keys())
1467                .filter(|path| rebuilt.get(*path) != independent.get(*path))
1468                .cloned()
1469                .collect();
1470            let retained = workspace.keep();
1471            panic!(
1472                "independent rebuild trees differ: {changed:?}; retained at {}",
1473                retained.display()
1474            );
1475        }
1476        assert!(
1477            rebuilt == tree_bytes(&root().join("tests/fixtures/hub/openalex-source")),
1478            "checked-in source is not the Rust rebuild; run the generator with --rebuild-source"
1479        );
1480        assert_eq!(
1481            fs::read_dir(workspace.path()).unwrap().count(),
1482            2,
1483            "rebuild left staging directories behind"
1484        );
1485        verify_full(&first).unwrap();
1486    }
1487}