Skip to main content

eggpack_core/
finalization.rs

1//! Qualification-gated local finalization and manifest aggregation.
2
3use crate::{
4    build_manifest, err, file_digest, BuildAttempt, CandidateArtifact, CoreError,
5    LogicalOutputSelector, QualificationEvidence, QualificationStatus, ReleasePlan, SupportTier,
6};
7use eggpack_contract::{expected_release_files, DistributionContract, ExpandedAssets};
8use flate2::{Compression, GzBuilder};
9use std::{
10    collections::{BTreeMap, BTreeSet},
11    fs::{self, File, OpenOptions},
12    io::Write,
13    path::{Path, PathBuf},
14};
15
16/// Explicit archive encoding accepted by the local finalizer.
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub enum ArchiveEncoding {
19    /// POSIX tar stream compressed with gzip; the contract asset name must end in `.tar.gz`.
20    TarGzip,
21}
22
23/// One target's exact build and qualification evidence to finalize.
24#[derive(Debug, Clone)]
25pub struct FinalizationTargetInput {
26    /// Contract canonical triple or unambiguous alias.
27    pub target: String,
28    /// Build result that produced the candidate bytes.
29    pub attempt: BuildAttempt,
30    /// M003 qualification evidence for this exact build attempt.
31    pub qualification: QualificationEvidence,
32}
33
34/// Identity and target evidence aggregated into one local release.
35#[derive(Debug, Clone)]
36pub struct FinalizationRequest {
37    /// Opaque product id.
38    pub product_id: String,
39    /// Opaque release id/version used by contract expansion.
40    pub release_id: String,
41    /// Opaque source revision.
42    pub source_revision: String,
43    /// Exact selected target build/evidence pairs.
44    pub targets: Vec<FinalizationTargetInput>,
45    /// Bounded references to external producer evidence.
46    pub evidence_references: Vec<String>,
47    /// Required explicit encoding when any selected target is an archive.
48    pub archive_encoding: Option<ArchiveEncoding>,
49}
50
51/// Completed local output root and manifest, returned only after complete validation.
52#[derive(Debug, Clone)]
53pub struct FinalizedRelease {
54    /// Invocation-owned directory containing contract-named artifacts and sidecars.
55    pub root: PathBuf,
56    /// Manifest v1 describing the final bytes and archive members.
57    pub manifest: eggpack_manifest::ReleaseManifest,
58}
59
60/// Finalize candidate bytes under an initially absent, caller-selected private directory.
61///
62/// Required targets must have passing qualification. Non-gating/experimental targets may
63/// remain deferred, but still need complete candidate byte evidence. All outputs are written
64/// under `output_root`; on any error this invocation removes only the root it created. The
65/// parent directory must be caller-secured/private on Windows (its ACL is inherited); Unix
66/// output roots are restricted to mode 0700.
67pub fn finalize_release(
68    contract: &DistributionContract,
69    plan: &ReleasePlan,
70    request: &FinalizationRequest,
71    output_root: &Path,
72) -> Result<FinalizedRelease, CoreError> {
73    if contract.product.id != request.product_id
74        || plan.schema_version != 1
75        || plan.release_id != request.release_id
76        || plan.source_revision != request.source_revision
77        || plan.targets.is_empty()
78        || plan.targets.len() > 256
79        || request.targets.is_empty()
80        || request.targets.len() > 256
81        || !output_root.is_absolute()
82    {
83        return Err(err(
84            "finalization identity, target count, or root is invalid",
85        ));
86    }
87    if output_root.components().any(|component| {
88        matches!(
89            component,
90            std::path::Component::CurDir | std::path::Component::ParentDir
91        )
92    }) {
93        return Err(err("finalization root path contains traversal components"));
94    }
95    let mut canonical_targets = BTreeSet::new();
96    for target in &plan.targets {
97        let expanded = contract
98            .expand(&target.target, &plan.release_id)
99            .map_err(|_| err("ReleasePlan target is not supported by contract"))?;
100        let form_matches = matches!(
101            (target.artifact_form, expanded.assets),
102            (crate::PlannedAssetForm::Direct, ExpandedAssets::Direct(_))
103                | (crate::PlannedAssetForm::Bundle, ExpandedAssets::Bundle(_))
104                | (crate::PlannedAssetForm::Archive, ExpandedAssets::Archive(_))
105        );
106        if target.policy.target != target.target
107            || !canonical_targets.insert(target.target.as_str())
108            || !form_matches
109        {
110            return Err(err("ReleasePlan target inventory or layout is invalid"));
111        }
112    }
113    let parent = output_root
114        .parent()
115        .ok_or_else(|| err("finalization root has no parent"))?;
116    let parent_metadata =
117        fs::symlink_metadata(parent).map_err(|_| err("finalization root parent is unavailable"))?;
118    if !parent_metadata.is_dir() || parent_metadata.file_type().is_symlink() {
119        return Err(err("finalization root parent is not a real directory"));
120    }
121    let filename = output_root
122        .file_name()
123        .filter(|name| !name.is_empty())
124        .ok_or_else(|| err("finalization root name is invalid"))?;
125    let canonical_parent =
126        fs::canonicalize(parent).map_err(|_| err("finalization root parent cannot be resolved"))?;
127    let root = canonical_parent.join(filename);
128    if fs::symlink_metadata(&root).is_ok() {
129        return Err(err("finalization root must be absent"));
130    }
131    fs::create_dir(&root).map_err(|_| err("finalization root could not be created"))?;
132    let result = (|| {
133        #[cfg(unix)]
134        {
135            use std::os::unix::fs::PermissionsExt;
136            fs::set_permissions(&root, fs::Permissions::from_mode(0o700))
137                .map_err(|_| err("finalization root permissions could not be restricted"))?;
138        }
139        finalize_into(contract, plan, request, &root)
140    })();
141    if result.is_err() {
142        let _ = fs::remove_dir_all(&root);
143    }
144    result
145}
146
147fn finalize_into(
148    contract: &DistributionContract,
149    plan: &ReleasePlan,
150    request: &FinalizationRequest,
151    root: &Path,
152) -> Result<FinalizedRelease, CoreError> {
153    let has_archive = request.targets.iter().any(|input| {
154        contract
155            .expand(&input.target, &request.release_id)
156            .is_ok_and(|expanded| matches!(expanded.assets, ExpandedAssets::Archive(_)))
157    });
158    if has_archive != request.archive_encoding.is_some()
159        || (has_archive && request.archive_encoding != Some(ArchiveEncoding::TarGzip))
160    {
161        return Err(err(
162            "archive encoding must be explicit and match selected layouts",
163        ));
164    }
165
166    let expected_targets: BTreeSet<_> = plan.targets.iter().map(|t| t.target.as_str()).collect();
167    let mut actual_targets = BTreeSet::new();
168    let mut manifest_targets = Vec::new();
169    let staging_members = root.join(".eggpack-members");
170    let mut staging_created = false;
171    for input in &request.targets {
172        let canonical_target = contract
173            .resolve(&input.target)
174            .map_err(|_| err("finalization target is not supported by contract"))?
175            .triple
176            .clone();
177        let planned = plan
178            .targets
179            .iter()
180            .find(|target| target.target == canonical_target)
181            .ok_or_else(|| err("finalization target is not in ReleasePlan"))?;
182        if input.attempt.target != planned.target
183            || input.attempt.release_id != request.release_id
184            || input.attempt.source_revision != request.source_revision
185            || input.attempt.strategy != planned.policy.strategy
186            || input.attempt.process.outcome != crate::CommandOutcome::Success
187            || !actual_targets.insert(planned.target.as_str())
188        {
189            return Err(err("build attempt identity or target inventory is invalid"));
190        }
191        input
192            .qualification
193            .validate_for(plan, planned, &input.attempt)
194            .map_err(|_| err("qualification evidence does not match build attempt"))?;
195        match input.qualification.status {
196            QualificationStatus::Passed => {}
197            QualificationStatus::Deferred if planned.policy.support != SupportTier::Required => {}
198            _ => return Err(err("target qualification does not permit finalization")),
199        }
200        let candidate_map = validated_candidates(&input.attempt, &input.qualification)?;
201        let expanded = contract
202            .expand(&input.target, &request.release_id)
203            .map_err(|_| err("target expansion failed"))?;
204        validate_layout_selectors(&candidate_map, &expanded.assets)?;
205        let expected_files = expected_release_files(contract, &input.target, &request.release_id)
206            .map_err(|_| err("expected contract inventory unavailable"))?;
207        let mut release_files = BTreeMap::new();
208        let mut archive_members = BTreeMap::new();
209        match expanded.assets {
210            ExpandedAssets::Direct(direct) => {
211                let candidate = get_candidate(&candidate_map, &LogicalOutputSelector::Direct)?;
212                copy_verified(candidate, &input.qualification, &direct.asset_file, root)?;
213                let path = root.join(&direct.asset_file);
214                write_checksum(&path, &direct.sidecar_file, root)?;
215                release_files.insert(direct.asset_file, path);
216                release_files.insert(direct.sidecar_file.clone(), root.join(direct.sidecar_file));
217            }
218            ExpandedAssets::Bundle(bundle) => {
219                for (index, entry) in bundle.entries.iter().enumerate() {
220                    let selector = LogicalOutputSelector::BundleEntry { index };
221                    let candidate = get_candidate(&candidate_map, &selector)?;
222                    copy_verified(candidate, &input.qualification, &entry.asset_file, root)?;
223                    let path = root.join(&entry.asset_file);
224                    write_checksum(&path, &entry.sidecar_file, root)?;
225                    release_files.insert(entry.asset_file.clone(), path);
226                    release_files
227                        .insert(entry.sidecar_file.clone(), root.join(&entry.sidecar_file));
228                }
229            }
230            ExpandedAssets::Archive(archive) => {
231                if !archive.archive_file.ends_with(".tar.gz") {
232                    return Err(err(
233                        "TarGzip encoding requires a `.tar.gz` contract filename",
234                    ));
235                }
236                if !staging_created {
237                    fs::create_dir(&staging_members)
238                        .map_err(|_| err("archive member staging root could not be created"))?;
239                    staging_created = true;
240                }
241                let mut staged_candidates = Vec::with_capacity(archive.members.len());
242                for (index, member) in archive.members.iter().enumerate() {
243                    let selector = LogicalOutputSelector::ArchiveMember {
244                        source: member.source.clone(),
245                    };
246                    let candidate = get_candidate(&candidate_map, &selector)?;
247                    let staged_name = format!("member-{index}");
248                    copy_verified(
249                        candidate,
250                        &input.qualification,
251                        &staged_name,
252                        &staging_members,
253                    )?;
254                    let staged = CandidateArtifact {
255                        path: staging_members.join(staged_name),
256                        ..candidate.clone()
257                    };
258                    archive_members.insert(member.source.clone(), staged.path.clone());
259                    staged_candidates.push(staged);
260                }
261                let members: Vec<_> = archive
262                    .members
263                    .iter()
264                    .zip(staged_candidates.iter())
265                    .map(|(member, candidate)| (member.source.as_str(), candidate))
266                    .collect();
267                create_tar_gzip(&root.join(&archive.archive_file), &members)?;
268                let archive_path = root.join(&archive.archive_file);
269                write_checksum(&archive_path, &archive.sidecar_file, root)?;
270                release_files.insert(archive.archive_file, archive_path);
271                release_files.insert(
272                    archive.sidecar_file.clone(),
273                    root.join(archive.sidecar_file),
274                );
275            }
276        }
277        let actual_files: BTreeSet<_> = release_files.keys().cloned().collect();
278        let expected_names: BTreeSet<_> = expected_files
279            .into_iter()
280            .map(|item| item.file_name)
281            .collect();
282        if actual_files != expected_names {
283            return Err(err(
284                "finalized files do not exactly match contract inventory",
285            ));
286        }
287        manifest_targets.push(crate::FinalizedTargetInput {
288            target: planned.target.clone(),
289            release_files,
290            archive_members,
291        });
292    }
293    if expected_targets != actual_targets {
294        return Err(err("finalization targets do not exactly cover ReleasePlan"));
295    }
296    manifest_targets.sort_by(|left, right| left.target.cmp(&right.target));
297    let manifest_input = crate::FinalizedReleaseInput {
298        product_id: request.product_id.clone(),
299        release_id: request.release_id.clone(),
300        source_revision: request.source_revision.clone(),
301        targets: manifest_targets,
302        evidence_references: request.evidence_references.clone(),
303    };
304    let manifest = build_manifest(contract, &manifest_input)?;
305    if staging_created {
306        fs::remove_dir_all(&staging_members)
307            .map_err(|_| err("archive member staging cleanup failed"))?;
308    }
309    Ok(FinalizedRelease {
310        root: root.to_path_buf(),
311        manifest,
312    })
313}
314
315/// Digest candidate bytes with the candidate-file diagnostic subject.
316fn digest_candidate_bytes(path: &Path) -> Result<(u64, String), CoreError> {
317    file_digest(path).map_err(|error| err(format!("candidate file {}", error.reason())))
318}
319
320/// Digest finalized bytes with the finalized-file diagnostic subject.
321fn digest_finalized_bytes(path: &Path) -> Result<(u64, String), CoreError> {
322    file_digest(path).map_err(|error| err(format!("finalized file {}", error.reason())))
323}
324
325fn validated_candidates<'a>(
326    attempt: &'a BuildAttempt,
327    qualification: &crate::QualificationEvidence,
328) -> Result<BTreeMap<LogicalOutputSelector, &'a CandidateArtifact>, CoreError> {
329    if qualification.candidates.len() != attempt.candidates.len() {
330        return Err(err("qualification candidate evidence is incomplete"));
331    }
332    let qualified: BTreeMap<_, _> = qualification
333        .candidates
334        .iter()
335        .map(|item| (item.selector.clone(), item))
336        .collect();
337    let mut candidates = BTreeMap::new();
338    for candidate in &attempt.candidates {
339        let evidence = qualified
340            .get(&candidate.selector)
341            .ok_or_else(|| err("candidate has no qualification byte evidence"))?;
342        let (size, digest) = digest_candidate_bytes(&candidate.path)?;
343        if evidence.package != candidate.package
344            || evidence.binary != candidate.binary
345            || evidence.size != candidate.size
346            || size != evidence.size
347            || digest != evidence.sha256
348            || candidates
349                .insert(candidate.selector.clone(), candidate)
350                .is_some()
351        {
352            return Err(err(
353                "candidate bytes or identity differ from qualification evidence",
354            ));
355        }
356    }
357    Ok(candidates)
358}
359
360fn get_candidate<'a>(
361    candidates: &'a BTreeMap<LogicalOutputSelector, &'a CandidateArtifact>,
362    selector: &LogicalOutputSelector,
363) -> Result<&'a CandidateArtifact, CoreError> {
364    candidates
365        .get(selector)
366        .copied()
367        .ok_or_else(|| err("required logical candidate is missing"))
368}
369
370fn validate_layout_selectors(
371    candidates: &BTreeMap<LogicalOutputSelector, &CandidateArtifact>,
372    form: &ExpandedAssets,
373) -> Result<(), CoreError> {
374    let expected: BTreeSet<_> = match form {
375        ExpandedAssets::Direct(_) => [LogicalOutputSelector::Direct].into_iter().collect(),
376        ExpandedAssets::Bundle(bundle) => (0..bundle.entries.len())
377            .map(|index| LogicalOutputSelector::BundleEntry { index })
378            .collect(),
379        ExpandedAssets::Archive(archive) => archive
380            .members
381            .iter()
382            .map(|member| LogicalOutputSelector::ArchiveMember {
383                source: member.source.clone(),
384            })
385            .collect(),
386    };
387    if candidates.keys().cloned().collect::<BTreeSet<_>>() != expected {
388        return Err(err(
389            "candidate selectors do not exactly match contract layout",
390        ));
391    }
392    Ok(())
393}
394
395fn copy_verified(
396    candidate: &CandidateArtifact,
397    qualification: &QualificationEvidence,
398    filename: &str,
399    root: &Path,
400) -> Result<(), CoreError> {
401    let evidence = qualification
402        .candidates
403        .iter()
404        .find(|item| item.selector == candidate.selector)
405        .ok_or_else(|| err("candidate qualification digest is missing"))?;
406    let destination = root.join(filename);
407    let mut source = File::open(&candidate.path)
408        .map_err(|_| err("qualified candidate could not be reopened"))?;
409    let mut target = OpenOptions::new()
410        .write(true)
411        .create_new(true)
412        .open(&destination)
413        .map_err(|_| err("contract output path already exists"))?;
414    std::io::copy(&mut source, &mut target).map_err(|_| err("candidate copy failed"))?;
415    target
416        .flush()
417        .map_err(|_| err("finalized file flush failed"))?;
418    drop(target);
419    let (size, digest) = digest_finalized_bytes(&destination)?;
420    if size != evidence.size || digest != evidence.sha256 {
421        return Err(err("candidate changed while being finalized"));
422    }
423    Ok(())
424}
425
426fn create_tar_gzip(path: &Path, members: &[(&str, &CandidateArtifact)]) -> Result<(), CoreError> {
427    let file = OpenOptions::new()
428        .write(true)
429        .create_new(true)
430        .open(path)
431        .map_err(|_| err("archive output path already exists"))?;
432    let encoder = GzBuilder::new()
433        .mtime(0)
434        .write(file, Compression::default());
435    let mut archive = tar::Builder::new(encoder);
436    archive.mode(tar::HeaderMode::Deterministic);
437    for (member_name, candidate) in members {
438        let (size, _) = digest_candidate_bytes(&candidate.path)?;
439        let mut source = File::open(&candidate.path)
440            .map_err(|_| err("archive member candidate could not be opened"))?;
441        let mut header = tar::Header::new_gnu();
442        header.set_entry_type(tar::EntryType::Regular);
443        header
444            .set_path(member_name)
445            .map_err(|_| err("archive member path rejected"))?;
446        header.set_size(size);
447        // A uniform `0o755` for every member is deliberate and is pinned by
448        // the determinism contract (architecture/determinism.md and the
449        // finalization deep dive): it is part of the archive's stable bytes.
450        // It is also only a default — every supported install path applies an
451        // explicit per-entry mode afterwards (`InstallMode`, rendered by the
452        // bootstrap installers and honoured by Eggup), so a data member is
453        // never left executable by extraction alone.
454        header.set_mode(0o755);
455        header.set_uid(0);
456        header.set_gid(0);
457        header.set_mtime(0);
458        header.set_cksum();
459        archive
460            .append(&header, &mut source)
461            .map_err(|_| err("archive member assembly failed"))?;
462    }
463    let encoder = archive
464        .into_inner()
465        .map_err(|_| err("archive stream finalization failed"))?;
466    encoder
467        .finish()
468        .map_err(|_| err("gzip stream finalization failed"))?;
469    Ok(())
470}
471
472fn write_checksum(artifact: &Path, filename: &str, root: &Path) -> Result<(), CoreError> {
473    let (_, digest) = digest_finalized_bytes(artifact)?;
474    let sidecar = root.join(filename);
475    let mut file = OpenOptions::new()
476        .write(true)
477        .create_new(true)
478        .open(sidecar)
479        .map_err(|_| err("checksum sidecar path already exists"))?;
480    writeln!(
481        file,
482        "{digest}  {}",
483        artifact.file_name().unwrap_or_default().to_string_lossy()
484    )
485    .map_err(|_| err("checksum sidecar write failed"))?;
486    file.flush()
487        .map_err(|_| err("checksum sidecar flush failed"))?;
488    Ok(())
489}
490
491#[cfg(test)]
492mod tests {
493    use super::*;
494    use crate::{
495        ArtifactForm, ArtifactRecord, BuildStrategy, CandidateArchitecture, CandidateFormat,
496        CommandOutcome, CompatibilityFloor, HostArch, HostOs, HostRequirement, PackConfig,
497        Qualification, QualificationMethod, QualifiedCandidateEvidence, SupportTier, TargetPolicy,
498        ToolchainRequirement,
499    };
500    use eggpack_contract::DistributionContract;
501    use sha2::Digest;
502    use std::io::Read;
503
504    fn elf() -> Vec<u8> {
505        let mut bytes = vec![0; 64];
506        bytes[..4].copy_from_slice(b"\x7fELF");
507        bytes[4] = 2;
508        bytes[5] = 1;
509        bytes[18..20].copy_from_slice(&62u16.to_le_bytes());
510        bytes
511    }
512
513    fn digest(bytes: &[u8]) -> String {
514        sha2::Sha256::digest(bytes)
515            .iter()
516            .map(|byte| format!("{byte:02x}"))
517            .collect()
518    }
519
520    /// The manifest record must describe the bytes that are on disk.
521    fn assert_artifact_bytes(root: &Path, artifact: &ArtifactRecord) {
522        let bytes = fs::read(root.join(&artifact.name)).unwrap();
523        assert_eq!(artifact.size, bytes.len() as u64);
524        assert_eq!(artifact.sha256, digest(&bytes));
525    }
526
527    fn fixture(
528        contract_text: &str,
529        target_alias: &str,
530        release_id: &str,
531        root: &Path,
532    ) -> (
533        DistributionContract,
534        ReleasePlan,
535        FinalizationRequest,
536        PathBuf,
537    ) {
538        let contract = DistributionContract::parse_toml_str(contract_text).unwrap();
539        let config = PackConfig {
540            schema_version: 1,
541            targets: vec![TargetPolicy {
542                target: target_alias.into(),
543                strategy: BuildStrategy::NativeCargo,
544                host_os: HostOs::Linux,
545                host_arch: HostArch::X86_64,
546                qualification_host: None,
547                toolchain: ToolchainRequirement {
548                    rust: "1.89.0".into(),
549                    cargo_zigbuild: None,
550                    zig: None,
551                },
552                floor: CompatibilityFloor::None,
553                qualification: Qualification::Structural,
554                support: SupportTier::Required,
555            }],
556        };
557        let plan = config
558            .resolve(
559                &contract,
560                release_id,
561                &"a".repeat(40),
562                &[target_alias.into()],
563            )
564            .unwrap();
565        let planned = &plan.targets[0];
566        let expanded = contract.expand(target_alias, release_id).unwrap();
567        let selectors: Vec<_> = match expanded.assets {
568            ExpandedAssets::Direct(_) => vec![LogicalOutputSelector::Direct],
569            ExpandedAssets::Bundle(bundle) => (0..bundle.entries.len())
570                .map(|index| LogicalOutputSelector::BundleEntry { index })
571                .collect(),
572            ExpandedAssets::Archive(archive) => archive
573                .members
574                .into_iter()
575                .map(|member| LogicalOutputSelector::ArchiveMember {
576                    source: member.source,
577                })
578                .collect(),
579        };
580        let source_root = root.join("candidates");
581        fs::create_dir(&source_root).unwrap();
582        let bytes = elf();
583        let candidates: Vec<_> = selectors
584            .into_iter()
585            .enumerate()
586            .map(|(index, selector)| {
587                let path = source_root.join(format!("candidate-{index}"));
588                fs::write(&path, &bytes).unwrap();
589                CandidateArtifact {
590                    target: planned.target.clone(),
591                    selector,
592                    package: "fixture".into(),
593                    binary: format!("fixture-{index}"),
594                    path,
595                    size: bytes.len() as u64,
596                }
597            })
598            .collect();
599        let attempt = BuildAttempt {
600            release_id: plan.release_id.clone(),
601            source_revision: plan.source_revision.clone(),
602            target: planned.target.clone(),
603            strategy: BuildStrategy::NativeCargo,
604            tool_summary: "fixture".into(),
605            process: crate::ProcessEvidence {
606                outcome: CommandOutcome::Success,
607                stdout_bytes: 0,
608                stderr_bytes: 0,
609            },
610            candidates: candidates.clone(),
611        };
612        let mut qualified = candidates
613            .iter()
614            .map(|candidate| QualifiedCandidateEvidence {
615                selector: candidate.selector.clone(),
616                package: candidate.package.clone(),
617                binary: candidate.binary.clone(),
618                size: bytes.len() as u64,
619                sha256: digest(&bytes),
620                format: CandidateFormat::Elf,
621                architecture: CandidateArchitecture::X86_64,
622            })
623            .collect::<Vec<_>>();
624        qualified.sort_by(|a, b| a.selector.cmp(&b.selector));
625        let qualification = QualificationEvidence {
626            schema_version: 1,
627            release_id: plan.release_id.clone(),
628            source_revision: plan.source_revision.clone(),
629            target: planned.target.clone(),
630            planned_classification: Qualification::Structural,
631            method: QualificationMethod::Structural,
632            actual_host: HostRequirement {
633                os: HostOs::Linux,
634                arch: HostArch::X86_64,
635            },
636            support: SupportTier::Required,
637            status: QualificationStatus::Passed,
638            floor: crate::FloorVerificationStatus::NotDeclared,
639            candidates: qualified,
640            smoke_selector: None,
641            processes: vec![],
642        };
643        let request = FinalizationRequest {
644            product_id: contract.product.id.clone(),
645            release_id: plan.release_id.clone(),
646            source_revision: plan.source_revision.clone(),
647            targets: vec![FinalizationTargetInput {
648                target: target_alias.into(),
649                attempt,
650                qualification,
651            }],
652            evidence_references: vec!["qualification:fixture".into()],
653            archive_encoding: matches!(planned.artifact_form, crate::PlannedAssetForm::Archive)
654                .then_some(ArchiveEncoding::TarGzip),
655        };
656        (contract, plan, request, source_root)
657    }
658
659    #[test]
660    fn direct_and_bundle_finalization_produce_contract_inventory_and_final_hashes() {
661        for (name, contract_text, product, target, release) in [
662            (
663                "direct",
664                include_str!("../../eggpack-contract/tests/fixtures/simple-direct.toml"),
665                "eggsact",
666                "linux-x64",
667                "1.2.6",
668            ),
669            (
670                "bundle",
671                include_str!("../../eggpack-contract/tests/fixtures/codegg-bundle.toml"),
672                "codegg",
673                "linux-x64",
674                "2.4.0",
675            ),
676        ] {
677            let parent = crate::test_temp_dir(name);
678            let (contract, plan, request, candidates) =
679                fixture(contract_text, target, release, &parent);
680            assert_eq!(contract.product.id, product);
681            let output = parent.join("release");
682            let finalized = finalize_release(&contract, &plan, &request, &output).unwrap();
683            assert_eq!(
684                fs::canonicalize(&finalized.root).unwrap(),
685                fs::canonicalize(&output).unwrap()
686            );
687            assert_eq!(finalized.manifest.release_id, release);
688            match &finalized.manifest.targets[0].form {
689                ArtifactForm::Direct { artifact, .. } => {
690                    assert_eq!(artifact.size, 64);
691                    assert_eq!(artifact.sha256, digest(&elf()));
692                    assert_eq!(
693                        fs::read_to_string(
694                            finalized.root.join(format!("{}.sha256", artifact.name))
695                        )
696                        .unwrap()
697                        .trim(),
698                        format!("{}  {}", artifact.sha256, artifact.name)
699                    );
700                }
701                ArtifactForm::Bundle { entries } => assert_eq!(entries.len(), 3),
702                _ => panic!("unexpected finalized form"),
703            }
704            assert!(!finalized.root.join("unused").exists());
705            fs::remove_dir_all(parent).unwrap();
706            let _ = candidates;
707        }
708    }
709
710    #[test]
711    fn archive_is_explicit_deterministic_and_contains_exact_contract_members() {
712        let parent = crate::test_temp_dir("finalize-archive");
713        let (contract, plan, request, _) = fixture(
714            include_str!("../../eggpack-contract/tests/fixtures/egress-archive.toml"),
715            "linux-x64",
716            "3.1.0",
717            &parent,
718        );
719        let first_root = parent.join("first");
720        let second_root = parent.join("second");
721        let first = finalize_release(&contract, &plan, &request, &first_root).unwrap();
722        let second = finalize_release(&contract, &plan, &request, &second_root).unwrap();
723        assert_eq!(first.manifest, second.manifest);
724        let first_archive =
725            fs::read(first_root.join("egress-3.1.0-x86_64-unknown-linux-gnu.tar.gz")).unwrap();
726        let second_archive =
727            fs::read(second_root.join("egress-3.1.0-x86_64-unknown-linux-gnu.tar.gz")).unwrap();
728        assert_eq!(first_archive, second_archive);
729        let mut archive = tar::Archive::new(flate2::read::GzDecoder::new(first_archive.as_slice()));
730        let entries = archive
731            .entries()
732            .unwrap()
733            .map(|entry| {
734                let mut entry = entry.unwrap();
735                let name = entry.path().unwrap().to_string_lossy().into_owned();
736                let mut bytes = Vec::new();
737                entry.read_to_end(&mut bytes).unwrap();
738                (name, bytes)
739            })
740            .collect::<Vec<_>>();
741        assert_eq!(
742            entries,
743            vec![
744                ("egress".into(), elf()),
745                ("bin/egress-helper".into(), elf())
746            ]
747        );
748        assert!(
749            matches!(&first.manifest.targets[0].form, ArtifactForm::Archive { members, .. } if members.len() == 2)
750        );
751        fs::remove_dir_all(parent).unwrap();
752    }
753
754    #[cfg(unix)]
755    #[test]
756    fn finalization_refuses_a_symlinked_candidate() {
757        let parent = crate::test_temp_dir("finalize-symlink");
758        let (contract, plan, request, source_root) = fixture(
759            include_str!("../../eggpack-contract/tests/fixtures/simple-direct.toml"),
760            "linux-x64",
761            "1.2.6",
762            &parent,
763        );
764        let candidate = request.targets[0].attempt.candidates[0].path.clone();
765        let real = candidate.with_extension("real");
766        fs::rename(&candidate, &real).unwrap();
767        std::os::unix::fs::symlink(&real, &candidate).unwrap();
768        let output = parent.join("release");
769        let error = finalize_release(&contract, &plan, &request, &output).unwrap_err();
770        assert!(error.to_string().contains("non-symlink"), "{error}");
771        assert!(!output.exists());
772        assert!(source_root.exists());
773        fs::remove_dir_all(parent).unwrap();
774    }
775
776    #[test]
777    fn manifest_records_agree_with_the_finalized_bytes_for_every_artifact() {
778        for (name, fixture_text, target, release) in [
779            (
780                "direct",
781                include_str!("../../eggpack-contract/tests/fixtures/simple-direct.toml"),
782                "linux-x64",
783                "1.2.6",
784            ),
785            (
786                "bundle",
787                include_str!("../../eggpack-contract/tests/fixtures/codegg-bundle.toml"),
788                "linux-x64",
789                "2.4.0",
790            ),
791            (
792                "archive",
793                include_str!("../../eggpack-contract/tests/fixtures/egress-archive.toml"),
794                "linux-x64",
795                "3.1.0",
796            ),
797        ] {
798            let parent = crate::test_temp_dir(name);
799            let (contract, plan, request, _) = fixture(fixture_text, target, release, &parent);
800            let output = parent.join("release");
801            let finalized = finalize_release(&contract, &plan, &request, &output).unwrap();
802            let mut checked = 0usize;
803            match &finalized.manifest.targets[0].form {
804                ArtifactForm::Direct { artifact, .. } => {
805                    assert_artifact_bytes(&finalized.root, artifact);
806                    checked += 1;
807                }
808                ArtifactForm::Bundle { entries } => {
809                    for entry in entries {
810                        assert_artifact_bytes(&finalized.root, &entry.artifact);
811                        checked += 1;
812                    }
813                }
814                ArtifactForm::Archive { artifact, members } => {
815                    assert_artifact_bytes(&finalized.root, artifact);
816                    checked += 1;
817                    for member in members {
818                        assert_eq!(member.bytes.size, elf().len() as u64);
819                        assert_eq!(member.bytes.sha256, digest(&elf()));
820                        checked += 1;
821                    }
822                }
823            }
824            assert!(checked > 0);
825            fs::remove_dir_all(parent).unwrap();
826        }
827    }
828
829    #[test]
830    fn incomplete_qualification_tampering_and_existing_roots_fail_without_partial_success() {
831        let parent = crate::test_temp_dir("finalize-negative");
832        let (contract, plan, mut request, source_root) = fixture(
833            include_str!("../../eggpack-contract/tests/fixtures/simple-direct.toml"),
834            "linux-x64",
835            "1.2.6",
836            &parent,
837        );
838        let existing = parent.join("existing");
839        fs::create_dir(&existing).unwrap();
840        fs::write(existing.join("preserve"), b"sentinel").unwrap();
841        assert!(finalize_release(&contract, &plan, &request, &existing).is_err());
842        assert_eq!(fs::read(existing.join("preserve")).unwrap(), b"sentinel");
843
844        request.targets[0].qualification.status = QualificationStatus::Deferred;
845        assert!(finalize_release(
846            &contract,
847            &plan,
848            &request,
849            &parent.join("required-deferred")
850        )
851        .is_err());
852        request.targets[0].qualification.status = QualificationStatus::Passed;
853        fs::write(&request.targets[0].attempt.candidates[0].path, b"changed").unwrap();
854        let rejected_root = parent.join("rejected");
855        assert!(finalize_release(&contract, &plan, &request, &rejected_root).is_err());
856        assert!(!rejected_root.exists());
857        assert!(source_root.exists());
858        fs::remove_dir_all(parent).unwrap();
859    }
860
861    #[test]
862    fn finalization_rejects_mixed_identity_and_extra_candidate_slots() {
863        let parent = crate::test_temp_dir("finalize-inventory");
864        let (contract, plan, mut request, _) = fixture(
865            include_str!("../../eggpack-contract/tests/fixtures/simple-direct.toml"),
866            "linux-x64",
867            "1.2.6",
868            &parent,
869        );
870        request.targets[0].attempt.source_revision = "b".repeat(40);
871        assert!(
872            finalize_release(&contract, &plan, &request, &parent.join("mixed-source")).is_err()
873        );
874
875        request.targets[0].attempt.source_revision = plan.source_revision.clone();
876        let mut extra = request.targets[0].attempt.candidates[0].clone();
877        extra.selector = LogicalOutputSelector::BundleEntry { index: 0 };
878        request.targets[0].attempt.candidates.push(extra.clone());
879        let original = request.targets[0].qualification.candidates[0].clone();
880        request.targets[0]
881            .qualification
882            .candidates
883            .push(QualifiedCandidateEvidence {
884                selector: extra.selector,
885                ..original
886            });
887        request.targets[0]
888            .qualification
889            .candidates
890            .sort_by(|a, b| a.selector.cmp(&b.selector));
891        assert!(finalize_release(&contract, &plan, &request, &parent.join("extra-slot")).is_err());
892        assert!(!parent.join("mixed-source").exists());
893        assert!(!parent.join("extra-slot").exists());
894        fs::remove_dir_all(parent).unwrap();
895    }
896
897    #[test]
898    fn concurrent_invocations_with_distinct_roots_do_not_share_outputs() {
899        let parent = crate::test_temp_dir("finalize-concurrent");
900        let (contract, plan, request, _) = fixture(
901            include_str!("../../eggpack-contract/tests/fixtures/simple-direct.toml"),
902            "linux-x64",
903            "1.2.6",
904            &parent,
905        );
906        let contract_a = contract.clone();
907        let plan_a = plan.clone();
908        let request_a = request.clone();
909        let root_a = parent.join("release-a");
910        let root_b = parent.join("release-b");
911        let a = std::thread::spawn(move || {
912            finalize_release(&contract_a, &plan_a, &request_a, &root_a).unwrap()
913        });
914        let b = std::thread::spawn(move || {
915            finalize_release(&contract, &plan, &request, &root_b).unwrap()
916        });
917        let a = a.join().unwrap();
918        let b = b.join().unwrap();
919        assert_eq!(a.manifest, b.manifest);
920        let asset = "eggsact-1.2.6-x86_64-unknown-linux-gnu";
921        assert_eq!(
922            fs::read(a.root.join(asset)).unwrap(),
923            fs::read(b.root.join(asset)).unwrap()
924        );
925        assert!(a.root != b.root);
926        fs::remove_dir_all(parent).unwrap();
927    }
928}