boxferry_compose/

import.rs

//! Compose-to-application mapping with explicit fidelity decisions.
mod deferred;
mod metadata;

use boxferry_engine::{
    ConversionKind, ConversionOutcome, Diagnostic, DiagnosticCode, DiagnosticField, DiagnosticValue, ImportAdapter,
    ImportResult, InvalidDiagnosticCode, NativeFinding, RuleId, Severity,
};
use std::collections::BTreeSet;

use boxferry_model::{
    Annotation, Application, BuildAttestation, BuildContext, BuildSettingValues, BuildSourceDeclaration, BuildSyntax,
    Command, Config, ConfigMaterial, Device, Entrypoint as NeutralEntrypoint,
    EnvironmentFile as NeutralEnvironmentFile, EnvironmentFileFormat as NeutralEnvironmentFileFormat,
    EnvironmentFileSyntax, EnvironmentValue, EnvironmentVariable, ExposedPort, Healthcheck, HealthcheckCommand,
    HealthcheckDuration as NeutralHealthcheckDuration, HealthcheckRetries as NeutralHealthcheckRetries, HostAddress,
    HostMapping, Identifier, ImageArtifactAssignment, ImageBuild, ImageBuildSetting, ImageReference, KernelParameter,
    Logging, LoggingOption, MetadataLabel, ModelError, Mount, MountSource, Network, NetworkAttachment,
    NetworkDriverOption, NetworkIpamConfig, Port, ProtectedString, Protocol, Provenance,
    PullPolicy as NeutralPullPolicy, ResourceGrant, ResourceGrantSyntax, ResourceLimit, ResourceOwnership,
    RestartPolicy as NeutralRestartPolicy, Secret, SecretMaterial, SecurityOption, SelinuxRelabel, Service,
    ServiceDependency, ServiceDependencyCondition, SourceBuildSecret, SourceBuildSetting, SourceSpan, Sourced,
    StopTimeout, Volume,
};
use compose_lens::merge::{MergeProvenance, MergedProject};
use compose_lens::model::{
    BooleanValue, ComposeScalar, ConfigDefinition, DependencyCondition as ComposeDependencyCondition,
    Entrypoint as ComposeEntrypoint, EnvironmentFileFormatKind, ExposeItemKind, ExposeProtocol,
    HealthcheckDuration as ComposeHealthcheckDuration, HealthcheckRetries as ComposeHealthcheckRetries,
    HealthcheckTest, HealthcheckTestKind, HostnameKind, Labels, LimitValue, LongPort, LongVolumeMount, MemLimitKind,
    MountType, NetworkDefinition, PidsLimitKind, Port as ComposePort, PullPolicyKind, ResourceExternal,
    RestartPolicyKind as ComposeRestartPolicyKind, SecretDefinition, SecurityOptionKind,
    SelinuxRelabel as ComposeSelinuxRelabel, ServiceNetwork, ServiceNetworks, ShmSizeKind, ShmSizeUnit,
    ShortDeviceKind, ShortPort, ShortVolumeMount, TmpfsItemKind, VolumeDefinition, VolumeMount,
};
use compose_lens::project::{
    ProjectBuild, ProjectBuildAdditionalContexts, ProjectBuildArgs, ProjectBuildDefinition, ProjectBuildExtraHosts,
    ProjectBuildLabels, ProjectBuildNoCacheFilter, ProjectBuildSsh, ProjectDependsOn, ProjectDevice, ProjectDns,
    ProjectDnsSearch, ProjectEnvironment, ProjectEnvironmentFile, ProjectFieldReference, ProjectGrant,
    ProjectHealthcheck, ProjectLabels, ProjectLoggingOptionValue, ProjectResource, ProjectService, ProjectSysctls,
    ProjectTmpfs, ProjectUlimitValue, ProjectValue, ProjectView, build_project_view,
};
use compose_lens::source::SourceSpan as ComposeSpan;

use crate::ComposeSource;

/// Maps an explicitly processed Compose source into `BoxFerry`'s neutral model.
#[derive(Clone, Debug)]
pub struct ComposeImporter {
    codes: Codes,
}

impl ComposeImporter {
    /// Creates an importer and validates its stable machine-readable diagnostic codes.
    ///
    /// # Errors
    ///
    /// Returns [`InvalidDiagnosticCode`] only when a code embedded in this adapter is invalid.
    pub fn new() -> Result<Self, InvalidDiagnosticCode> {
        Ok(Self {
            codes: Codes {
                invalid_model: RuleId::ComposeModelInvalid.definition().diagnostic_code()?,
                profile_required: RuleId::ComposeProfileRequired.definition().diagnostic_code()?,
                profile_mismatch: RuleId::ComposeProfileMismatch.definition().diagnostic_code()?,
                unsupported: RuleId::ComposeIntentUnsupported.definition().diagnostic_code()?,
                invalid_value: RuleId::ComposeValueInvalid.definition().diagnostic_code()?,
                unset_variable: RuleId::ComposeUnsetVariable.definition().diagnostic_code()?,
                required_variable: RuleId::ComposeRequiredVariable.definition().diagnostic_code()?,
                interpolation_invalid: RuleId::ComposeInterpolationInvalid.definition().diagnostic_code()?,
                interpolation_nesting: RuleId::ComposeInterpolationNestingLimit
                    .definition()
                    .diagnostic_code()?,
                unresolved_variable: RuleId::ComposeUnresolvedVariable.definition().diagnostic_code()?,
                native_error: RuleId::ComposeNativeError.definition().diagnostic_code()?,
                native_warning: RuleId::ComposeNativeWarning.definition().diagnostic_code()?,
                native_note: RuleId::ComposeNativeNote.definition().diagnostic_code()?,
            },
        })
    }
}

impl ImportAdapter for ComposeImporter {
    type Source = ComposeSource;

    fn import(&self, source: &Self::Source) -> ImportResult {
        let mut mapping = Mapping::new(&self.codes, source);
        mapping.report_native_findings(source.native_findings());
        if !source.deferred_options().is_empty() && source.interpolation_applied() {
            mapping.invalid_optional_span(self.codes.invalid_value.clone(), "services.execution_environment", "deferred mode requires uninterpolated input and cannot consume previously acquired interpolation values", "service execution environment", source.project().root().provenance().effective_source());
            return ImportResult::new(None, mapping.outcomes, mapping.diagnostics);
        }

        let project_result = build_project_view(source.project(), source.profile_selection());
        let Some(view) = project_result.view() else {
            mapping.invalid_optional_span(
                self.codes.profile_mismatch.clone(),
                "services.profiles",
                "profile selection does not belong to the merged Compose project",
                "profile selection",
                source.project().root().provenance().effective_source(),
            );
            return ImportResult::new(None, mapping.outcomes, mapping.diagnostics);
        };
        mapping.report_project_diagnostics(project_result.diagnostics());

        let application_name = view.name().map_or_else(
            || source.fallback_application_name().clone(),
            |name| {
                Identifier::new(name.value().clone()).unwrap_or_else(|error| {
                    mapping.invalid_model_optional("application.name", &error, name.effective_source());
                    source.fallback_application_name().clone()
                })
            },
        );
        let mut application = Application::new(application_name);
        mapping.exact_provenance("application", view.provenance());
        if let Some(version) = view.version() {
            // Compose `version` is an obsolete marker, not a provider selector. Dropping it at
            // this cross-format neutral boundary is therefore exact normalization; ComposeLens
            // retains and reports its native obsolete-version warning independently.
            mapping.exact_provenance("application.version", version.provenance());
        }

        let profiles_valid = mapping.validate_profiles(view, source);

        for definition in view.volumes() {
            if let Some(volume) = mapping.map_volume_definition(definition)
                && let Err(error) = application.add_volume(volume)
            {
                mapping.invalid_model_optional("volumes", &error, definition.definition().effective_source());
            }
        }
        for definition in view.networks() {
            if let Some(network) = mapping.map_network_definition(definition)
                && let Err(error) = application.add_network(network)
            {
                mapping.invalid_model_optional("networks", &error, definition.definition().effective_source());
            }
        }
        for definition in view.configs() {
            if let Some(config) = mapping.map_config_definition(definition)
                && let Err(error) = application.add_config(config)
            {
                mapping.invalid_model_optional("configs", &error, definition.definition().effective_source());
            }
        }
        for definition in view.secrets() {
            if let Some(secret) = mapping.map_secret_definition(definition)
                && let Err(error) = application.add_secret(secret)
            {
                mapping.invalid_model_optional("secrets", &error, definition.definition().effective_source());
            }
        }
        mapping.import_services(view, &mut application, profiles_valid);
        mapping.validate_deferred_services(&application);
        mapping.import_metadata(&mut application);
        mapping.report_document_unsupported(view);
        ImportResult::new(Some(application), mapping.outcomes, mapping.diagnostics)
    }
}

#[derive(Clone, Debug)]
struct Codes {
    invalid_model: DiagnosticCode,
    profile_required: DiagnosticCode,
    profile_mismatch: DiagnosticCode,
    unsupported: DiagnosticCode,
    invalid_value: DiagnosticCode,
    unset_variable: DiagnosticCode,
    required_variable: DiagnosticCode,
    interpolation_invalid: DiagnosticCode,
    interpolation_nesting: DiagnosticCode,
    unresolved_variable: DiagnosticCode,
    native_error: DiagnosticCode,
    native_warning: DiagnosticCode,
    native_note: DiagnosticCode,
}

enum SecurityOptionMapping {
    Exact(SecurityOption),
    Invalid(&'static str),
    Unsupported(&'static str),
}

struct Mapping<'a> {
    codes: &'a Codes,
    source: &'a ComposeSource,
    outcomes: Vec<ConversionOutcome>,
    diagnostics: Vec<Diagnostic>,
}

impl<'a> Mapping<'a> {
    const fn new(codes: &'a Codes, source: &'a ComposeSource) -> Self {
        Self {
            codes,
            source,
            outcomes: Vec::new(),
            diagnostics: Vec::new(),
        }
    }

    fn import_services(&mut self, view: &ProjectView, application: &mut Application, profiles_valid: bool) {
        for native_service in view.services() {
            let active = if native_service
                .profiles()
                .is_none_or(|profiles| profiles.value().is_empty())
            {
                true
            } else {
                profiles_valid
                    && self
                        .source
                        .profile_selection()
                        .is_some_and(|selection| selection.is_active(native_service.name().value()))
            };
            if !active {
                continue;
            }
            if let Some(service) = self.map_service(native_service) {
                let (mut service, origins) = service.into_parts();
                if let Some(build) = self.map_service_build(service.name(), service.image(), native_service) {
                    let build_name = build.value().name().clone();
                    let build_origins = build.origins().to_vec();
                    if let Err(error) = application.add_image_build(build) {
                        self.invalid_model_optional("image_builds", &error, view.provenance().effective_source());
                    } else {
                        let mut reference = Sourced::generated(build_name);
                        for origin in build_origins {
                            reference.add_origin(origin);
                        }
                        service.set_image_build(reference);
                    }
                }
                let mut service = Sourced::generated(service);
                for origin in origins {
                    service.add_origin(origin);
                }
                if let Err(error) = application.add_service(service) {
                    self.invalid_model_optional("services", &error, view.provenance().effective_source());
                }
            }
        }
    }

    fn validate_profiles(&mut self, view: &ProjectView, source: &ComposeSource) -> bool {
        if view
            .services()
            .iter()
            .all(|service| service.profiles().is_none_or(|profiles| profiles.value().is_empty()))
        {
            return true;
        }
        let Some(selection) = source.profile_selection() else {
            self.invalid_optional_span(
                self.codes.profile_required.clone(),
                "services.profiles",
                "profiled Compose services require an explicit ComposeLens profile selection",
                "profile selection",
                view.provenance().effective_source(),
            );
            return false;
        };
        if !selection.is_valid() {
            self.invalid_optional_span(
                self.codes.profile_mismatch.clone(),
                "services.profiles",
                "profile selection is invalid or does not belong to the merged Compose project",
                "profile selection",
                view.provenance().effective_source(),
            );
            return false;
        }
        true
    }

    fn map_service(&mut self, native: &ProjectService) -> Option<Sourced<Service>> {
        let subject = format!("services.{}", native.name().value());
        let name = self.identifier_optional(
            &format!("{subject}.name"),
            native.name().value(),
            native.name().effective_source(),
        )?;
        let mut service = Service::new(name);

        self.map_runtime_name(&subject, native, &mut service);
        self.map_restart_policy(&subject, native, &mut service);
        self.map_service_image(&subject, native, &mut service);
        if let Some(command) = native.command()
            && let Some(value) = Self::map_command(command.value(), command.is_sensitive())
        {
            service.set_command(self.sourced_provenance(value, command.provenance()));
            self.exact_provenance(format!("{subject}.command"), command.provenance());
        }
        if let Some(healthcheck) = native.healthcheck() {
            service.set_healthcheck(self.map_healthcheck(&subject, healthcheck));
        }
        self.map_execution_context(&subject, native, &mut service);
        self.map_released_container_settings(&subject, native, &mut service);
        self.map_dns(&subject, native, &mut service);
        self.map_security_options(&subject, native, &mut service);
        if !self.map_deferred_service_environment(&subject, native, &mut service) {
            self.map_service_environment(&subject, native, &mut service);
        }
        self.map_service_labels(&subject, native, &mut service);
        if let Some(extra_hosts) = native.extra_hosts() {
            for (index, entry) in extra_hosts.value().entries().iter().enumerate() {
                let host_subject = format!("{subject}.extra_hosts[{index}]");
                let Some(hostname) = self.identifier_optional(
                    &host_subject,
                    entry.hostname().value(),
                    entry.hostname().effective_source(),
                ) else {
                    continue;
                };
                let address = match HostAddress::new(entry.address().value().raw()) {
                    Ok(address) => address,
                    Err(error) => {
                        self.invalid_model_optional(&host_subject, &error, entry.address().effective_source());
                        continue;
                    }
                };
                let mapping = self.sourced_host_mapping(
                    HostMapping::new(hostname, address),
                    entry.hostname().sources(),
                    entry.address().provenance(),
                );
                self.exact_origins(host_subject, mapping.origins());
                service.add_host_mapping(mapping);
            }
        }
        if let Some(ports) = native.ports() {
            for (index, port) in ports.value().iter().enumerate() {
                let port_subject = format!("{subject}.ports[{index}]");
                if let Some(value) = self.map_port(&port_subject, port.value()) {
                    service.add_port(self.sourced_provenance(value, port.provenance()));
                    self.exact_provenance(port_subject, port.provenance());
                }
            }
        }
        self.map_service_mounts(&subject, native, &mut service);
        if let Some(configs) = native.configs() {
            self.map_service_grants(&subject, "configs", configs, false, &mut service);
        }
        if let Some(secrets) = native.secrets() {
            self.map_service_grants(&subject, "secrets", secrets, true, &mut service);
        }
        if let Some(networks) = native.networks() {
            self.map_service_networks(
                &subject,
                native.name().value(),
                networks.value(),
                networks.provenance(),
                &mut service,
            );
        }
        if let Some(profiles) = native.profiles()
            && !profiles.value().is_empty()
        {
            self.exact_provenance(format!("{subject}.profiles"), profiles.provenance());
        }
        if let Some(dependencies) = native.depends_on() {
            self.map_service_dependencies(&subject, dependencies, &mut service);
        }

        self.report_service_unsupported(&subject, native);
        self.exact_provenance(&subject, native.provenance());
        Some(self.sourced_provenance(service, native.provenance()))
    }

    fn map_service_image(&mut self, service_subject: &str, native: &ProjectService, service: &mut Service) {
        let Some(image) = native.image() else {
            return;
        };
        let subject = format!("{service_subject}.image");
        if image.value().raw().contains('$') {
            self.report_unresolved_variable(
                &subject,
                image.value().raw(),
                "image reference contains unresolved Compose variable syntax",
            );
        }
        match ImageReference::parse(image.value().raw()) {
            Ok(value) => {
                service.set_image(self.sourced_provenance(value, image.provenance()));
                self.exact_provenance(subject, image.provenance());
            }
            Err(error) => self.invalid_model_optional(&subject, &error, image.effective_source()),
        }
    }

    fn map_runtime_name(&mut self, subject: &str, native: &ProjectService, service: &mut Service) {
        let Some(container_name) = native.container_name() else {
            return;
        };
        service.set_runtime_name(self.sourced_provenance(
            Self::protected(container_name.value(), container_name.is_sensitive()),
            container_name.provenance(),
        ));
        self.exact_provenance(format!("{subject}.container_name"), container_name.provenance());
    }

    fn map_service_build(
        &mut self,
        service_name: &Identifier,
        service_image: Option<&Sourced<ImageReference>>,
        native: &ProjectService,
    ) -> Option<Sourced<ImageBuild>> {
        let build = native.build()?;
        let subject = format!("services.{}.build", service_name.as_str());
        let name = match Identifier::new(format!("{}-build", service_name.as_str())) {
            Ok(name) => name,
            Err(error) => {
                self.invalid_model_optional(&subject, &error, build.effective_source());
                return None;
            }
        };
        let mut neutral = ImageBuild::new(name);
        match build.value() {
            ProjectBuild::Context(context) => {
                neutral.set_source_declaration(self.sourced_provenance(
                    BuildSourceDeclaration::Scalar(Self::protected(context.value(), context.is_sensitive())),
                    context.provenance(),
                ));
                self.exact_provenance(&subject, context.provenance());
            }
            ProjectBuild::Definition(definition) => self.map_build_definition(&subject, definition, &mut neutral),
            _ => self.unsupported_optional(
                &subject,
                "build declaration variant is newer than this Compose adapter",
                build.effective_source(),
            ),
        }
        Self::add_service_image_build_tag(&mut neutral, service_image);
        Some(self.sourced_provenance(neutral, build.provenance()))
    }

    fn add_service_image_build_tag(build: &mut ImageBuild, service_image: Option<&Sourced<ImageReference>>) {
        let Some(service_image) = service_image else { return };
        let image = service_image.value().as_str();
        let mut settings = build.settings().map_or_else(Vec::new, <[_]>::to_vec);
        let duplicate = settings.iter().any(|setting| {
            matches!(
                setting.value(),
                ImageBuildSetting::ImageTags(values)
                    if values.values().iter().any(|value| value.value().expose() == image)
            )
        });
        if !duplicate {
            let mut tag = Sourced::generated(ProtectedString::plain(image));
            for origin in service_image.origins() {
                tag.add_origin(origin.clone());
            }
            let mut setting = Sourced::generated(ImageBuildSetting::ImageTags(BuildSettingValues::new(
                BuildSyntax::Scalar,
                vec![tag],
            )));
            for origin in service_image.origins() {
                setting.add_origin(origin.clone());
            }
            settings.insert(0, setting);
        }
        build.set_settings(settings);
    }

    fn map_build_definition(&mut self, subject: &str, definition: &ProjectBuildDefinition, build: &mut ImageBuild) {
        let mut settings = Vec::new();
        let mut overlap = Vec::new();

        self.map_build_direct_settings(definition, &mut settings, &mut overlap);
        self.map_build_boolean_settings(subject, definition, &mut settings);
        self.map_build_attestations(definition, &mut settings);
        self.map_build_string_collections(definition, &mut settings, &mut overlap);
        self.map_build_additional_contexts(definition.additional_contexts(), &mut settings);
        self.map_build_args(definition.args(), &mut settings, &mut overlap);
        self.map_build_labels(definition.labels(), &mut settings, &mut overlap);
        self.map_build_extra_hosts(definition.extra_hosts(), &mut settings);
        self.map_build_no_cache_filter(definition.no_cache_filter(), &mut settings);
        self.map_build_ssh(definition.ssh(), &mut settings);
        self.map_build_secrets(definition.secrets(), &mut settings);
        self.map_build_ulimits(definition.ulimits(), &mut settings);
        self.report_project_fields(subject, "build field", definition.unmodeled_fields());

        settings.sort_by_key(|setting| {
            setting
                .origins()
                .last()
                .and_then(Provenance::span)
                .map_or(usize::MAX, SourceSpan::start)
        });
        build.set_source_declaration(Sourced::generated(BuildSourceDeclaration::Structured(settings)));
        if !overlap.is_empty() {
            build.set_settings(overlap);
        }
    }

    fn map_build_direct_settings(
        &self,
        definition: &ProjectBuildDefinition,
        settings: &mut Vec<Sourced<SourceBuildSetting>>,
        overlap: &mut Vec<Sourced<ImageBuildSetting>>,
    ) {
        if let Some(context) = definition.context() {
            settings.push(self.sourced_provenance(
                SourceBuildSetting::Context(Self::protected(context.value(), context.is_sensitive())),
                context.provenance(),
            ));
        }
        if let Some(dockerfile) = definition.dockerfile() {
            let value = Self::protected(dockerfile.value(), dockerfile.is_sensitive());
            settings
                .push(self.sourced_provenance(SourceBuildSetting::RecipeFile(value.clone()), dockerfile.provenance()));
            overlap.push(self.sourced_provenance(ImageBuildSetting::RecipeFile(value), dockerfile.provenance()));
        }
        if let Some(inline) = definition.dockerfile_inline() {
            settings.push(self.sourced_provenance(
                SourceBuildSetting::InlineRecipe(Self::protected(inline.value(), inline.is_sensitive())),
                inline.provenance(),
            ));
        }
        if let Some(target) = definition.target() {
            let value = Self::protected(target.value(), target.is_sensitive());
            settings.push(self.sourced_provenance(SourceBuildSetting::Target(value.clone()), target.provenance()));
            overlap.push(self.sourced_provenance(ImageBuildSetting::Target(value), target.provenance()));
        }
        if let Some(network) = definition.network() {
            settings.push(self.sourced_provenance(
                SourceBuildSetting::Network(Self::protected(network.value(), network.is_sensitive())),
                network.provenance(),
            ));
        }
        if let Some(isolation) = definition.isolation() {
            settings.push(self.sourced_provenance(
                SourceBuildSetting::Isolation(Self::protected(isolation.value(), isolation.is_sensitive())),
                isolation.provenance(),
            ));
        }
        if let Some(shm_size) = definition.shm_size() {
            settings.push(self.sourced_provenance(
                SourceBuildSetting::ShmSize(Self::protected(shm_size.value().raw().value(), shm_size.is_sensitive())),
                shm_size.provenance(),
            ));
        }
    }

    fn map_build_boolean_settings(
        &mut self,
        subject: &str,
        definition: &ProjectBuildDefinition,
        settings: &mut Vec<Sourced<SourceBuildSetting>>,
    ) {
        if let Some(privileged) = definition.privileged() {
            if let BooleanValue::Literal(value) = privileged.value() {
                settings.push(self.sourced_provenance(SourceBuildSetting::Privileged(*value), privileged.provenance()));
            } else {
                self.invalid_value_optional(
                    &format!("{subject}.privileged"),
                    "build privileged expression was not resolved",
                    privileged.effective_source(),
                );
            }
        }
        if let Some(pull) = definition.pull() {
            if let BooleanValue::Literal(value) = pull.value() {
                settings.push(self.sourced_provenance(SourceBuildSetting::Pull(*value), pull.provenance()));
            } else {
                self.invalid_value_optional(
                    &format!("{subject}.pull"),
                    "build pull expression was not resolved",
                    pull.effective_source(),
                );
            }
        }
        if let Some(no_cache) = definition.no_cache() {
            match no_cache.value() {
                compose_lens::model::BuildNoCache::Boolean(value) => {
                    settings.push(self.sourced_provenance(SourceBuildSetting::NoCache(*value), no_cache.provenance()));
                }
                compose_lens::model::BuildNoCache::String(_) => self.unsupported_optional(
                    &format!("{subject}.no_cache"),
                    "string build no_cache values have no equivalent boolean neutral value",
                    no_cache.effective_source(),
                ),
            }
        }
    }

    fn map_build_attestations(
        &self,
        definition: &ProjectBuildDefinition,
        settings: &mut Vec<Sourced<SourceBuildSetting>>,
    ) {
        if let Some(sbom) = definition.sbom() {
            let value = match sbom.value() {
                compose_lens::model::BuildSbom::Boolean(value) => BuildAttestation::Boolean(*value),
                compose_lens::model::BuildSbom::String(value) => {
                    BuildAttestation::Value(Self::protected(value, sbom.is_sensitive()))
                }
            };
            settings.push(self.sourced_provenance(SourceBuildSetting::Sbom(value), sbom.provenance()));
        }
        if let Some(provenance) = definition.provenance() {
            let value = match provenance.value() {
                compose_lens::model::BuildProvenance::Boolean(value) => BuildAttestation::Boolean(*value),
                compose_lens::model::BuildProvenance::String(value) => {
                    BuildAttestation::Value(Self::protected(value, provenance.is_sensitive()))
                }
            };
            settings.push(self.sourced_provenance(SourceBuildSetting::Provenance(value), provenance.provenance()));
        }
    }

    fn map_build_string_collections(
        &self,
        definition: &ProjectBuildDefinition,
        settings: &mut Vec<Sourced<SourceBuildSetting>>,
        overlap: &mut Vec<Sourced<ImageBuildSetting>>,
    ) {
        self.map_build_string_list(
            definition.entitlements(),
            BuildSyntax::Sequence,
            SourceBuildSetting::Entitlements,
            settings,
        );
        self.map_build_string_list(
            definition.cache_from(),
            BuildSyntax::Sequence,
            SourceBuildSetting::CacheFrom,
            settings,
        );
        self.map_build_string_list(
            definition.cache_to(),
            BuildSyntax::Sequence,
            SourceBuildSetting::CacheTo,
            settings,
        );
        self.map_build_string_list(
            definition.platforms(),
            BuildSyntax::Sequence,
            SourceBuildSetting::Platforms,
            settings,
        );
        self.map_build_string_list(
            definition.tags(),
            BuildSyntax::Sequence,
            SourceBuildSetting::Tags,
            settings,
        );
        if let Some(tags) = definition.tags() {
            let values = tags
                .value()
                .iter()
                .map(|value| {
                    self.sourced_provenance(Self::protected(value.value(), value.is_sensitive()), value.provenance())
                })
                .collect();
            overlap.push(self.sourced_provenance(
                ImageBuildSetting::ImageTags(BuildSettingValues::new(BuildSyntax::Sequence, values)),
                tags.provenance(),
            ));
        }
    }

    fn map_build_string_list(
        &self,
        native: Option<&ProjectValue<Vec<ProjectValue<String>>>>,
        syntax: BuildSyntax,
        constructor: fn(BuildSettingValues<ProtectedString>) -> SourceBuildSetting,
        settings: &mut Vec<Sourced<SourceBuildSetting>>,
    ) {
        let Some(native) = native else { return };
        let values = native
            .value()
            .iter()
            .map(|value| {
                self.sourced_provenance(Self::protected(value.value(), value.is_sensitive()), value.provenance())
            })
            .collect();
        settings.push(self.sourced_provenance(
            constructor(BuildSettingValues::new(syntax, values)),
            native.provenance(),
        ));
    }

    fn map_build_additional_contexts(
        &self,
        native: Option<&ProjectValue<ProjectBuildAdditionalContexts>>,
        settings: &mut Vec<Sourced<SourceBuildSetting>>,
    ) {
        let Some(native) = native else { return };
        let (syntax, values) = match native.value() {
            ProjectBuildAdditionalContexts::Map(entries) => (
                BuildSyntax::Mapping,
                entries
                    .iter()
                    .map(|entry| {
                        self.sourced_project_key_value(
                            BuildContext::new(
                                Self::protected(entry.name().value(), entry.name().is_sensitive()),
                                Self::protected(
                                    scalar_text(entry.value().value()).as_str(),
                                    entry.value().is_sensitive(),
                                ),
                            ),
                            entry.name().sources(),
                            entry.value().provenance(),
                        )
                    })
                    .collect::<Vec<_>>(),
            ),
            ProjectBuildAdditionalContexts::List(entries) => (
                BuildSyntax::Sequence,
                entries
                    .iter()
                    .map(|entry| {
                        self.sourced_provenance(
                            BuildContext::new(
                                Self::protected(entry.value(), entry.is_sensitive()),
                                ProtectedString::plain(""),
                            ),
                            entry.provenance(),
                        )
                    })
                    .collect::<Vec<_>>(),
            ),
            _ => return,
        };
        settings.push(self.sourced_provenance(
            SourceBuildSetting::AdditionalContexts(BuildSettingValues::new(syntax, values)),
            native.provenance(),
        ));
    }

    fn map_build_args(
        &self,
        native: Option<&ProjectValue<ProjectBuildArgs>>,
        settings: &mut Vec<Sourced<SourceBuildSetting>>,
        overlap: &mut Vec<Sourced<ImageBuildSetting>>,
    ) {
        let Some(native) = native else { return };
        let (syntax, values, overlap_values) = match native.value() {
            ProjectBuildArgs::Map(entries) => (
                BuildSyntax::Mapping,
                entries
                    .iter()
                    .map(|entry| {
                        self.sourced_project_key_value(
                            ImageArtifactAssignment::new(
                                Self::protected(entry.name().value(), entry.name().is_sensitive()),
                                scalar_option(entry.value().value())
                                    .map(|value| Self::protected(&value, entry.value().is_sensitive())),
                            ),
                            entry.name().sources(),
                            entry.value().provenance(),
                        )
                    })
                    .collect::<Vec<_>>(),
                entries
                    .iter()
                    .filter(|entry| scalar_option(entry.value().value()).is_some())
                    .map(|entry| {
                        self.sourced_project_key_value(
                            ImageArtifactAssignment::new(
                                Self::protected(entry.name().value(), entry.name().is_sensitive()),
                                scalar_option(entry.value().value())
                                    .map(|value| Self::protected(&value, entry.value().is_sensitive())),
                            ),
                            entry.name().sources(),
                            entry.value().provenance(),
                        )
                    })
                    .collect::<Vec<_>>(),
            ),
            ProjectBuildArgs::List(entries) => (
                BuildSyntax::Sequence,
                entries
                    .iter()
                    .map(|entry| {
                        self.sourced_provenance(
                            ImageArtifactAssignment::new(Self::protected(entry.value(), entry.is_sensitive()), None),
                            entry.provenance(),
                        )
                    })
                    .collect(),
                entries
                    .iter()
                    .filter_map(|entry| {
                        let (name, value) = literal_assignment(entry.value())?;
                        Some(self.sourced_provenance(
                            ImageArtifactAssignment::new(
                                Self::protected(name, entry.is_sensitive()),
                                Some(Self::protected(value, entry.is_sensitive())),
                            ),
                            entry.provenance(),
                        ))
                    })
                    .collect(),
            ),
            _ => return,
        };
        let source_values = BuildSettingValues::new(syntax, values.clone());
        settings.push(self.sourced_provenance(SourceBuildSetting::Arguments(source_values), native.provenance()));
        if !overlap_values.is_empty() {
            overlap.push(self.sourced_provenance(
                ImageBuildSetting::BuildArguments(BuildSettingValues::new(syntax, overlap_values)),
                native.provenance(),
            ));
        }
    }

    fn map_build_labels(
        &self,
        native: Option<&ProjectValue<ProjectBuildLabels>>,
        settings: &mut Vec<Sourced<SourceBuildSetting>>,
        overlap: &mut Vec<Sourced<ImageBuildSetting>>,
    ) {
        let Some(native) = native else { return };
        let (syntax, values) = match native.value() {
            ProjectBuildLabels::Map(entries) => (
                BuildSyntax::Mapping,
                entries
                    .iter()
                    .map(|entry| {
                        self.sourced_project_key_value(
                            ImageArtifactAssignment::new(
                                Self::protected(entry.name().value(), entry.name().is_sensitive()),
                                scalar_option(entry.value().value())
                                    .map(|value| Self::protected(&value, entry.value().is_sensitive())),
                            ),
                            entry.name().sources(),
                            entry.value().provenance(),
                        )
                    })
                    .collect::<Vec<_>>(),
            ),
            ProjectBuildLabels::List(entries) => (
                BuildSyntax::Sequence,
                entries
                    .iter()
                    .map(|entry| {
                        self.sourced_provenance(
                            ImageArtifactAssignment::new(Self::protected(entry.value(), entry.is_sensitive()), None),
                            entry.provenance(),
                        )
                    })
                    .collect(),
            ),
            _ => return,
        };
        settings.push(self.sourced_provenance(
            SourceBuildSetting::Labels(BuildSettingValues::new(syntax, values.clone())),
            native.provenance(),
        ));
        overlap.push(self.sourced_provenance(
            ImageBuildSetting::Labels(BuildSettingValues::new(syntax, values)),
            native.provenance(),
        ));
    }

    fn map_build_extra_hosts(
        &self,
        native: Option<&ProjectValue<ProjectBuildExtraHosts>>,
        settings: &mut Vec<Sourced<SourceBuildSetting>>,
    ) {
        let Some(native) = native else { return };
        let (syntax, values) = match native.value() {
            ProjectBuildExtraHosts::List(entries) => (
                BuildSyntax::Sequence,
                entries
                    .iter()
                    .map(|entry| {
                        self.sourced_provenance(
                            ImageArtifactAssignment::new(Self::protected(entry.value(), entry.is_sensitive()), None),
                            entry.provenance(),
                        )
                    })
                    .collect(),
            ),
            ProjectBuildExtraHosts::Map(entries) => (
                BuildSyntax::Mapping,
                entries
                    .iter()
                    .flat_map(|entry| match entry.addresses() {
                        compose_lens::project::ProjectBuildExtraHostAddresses::Scalar(value) => {
                            vec![self.sourced_project_key_value(
                                ImageArtifactAssignment::new(
                                    Self::protected(entry.hostname().value(), entry.hostname().is_sensitive()),
                                    Some(Self::protected(value.value(), value.is_sensitive())),
                                ),
                                entry.hostname().sources(),
                                value.provenance(),
                            )]
                        }
                        compose_lens::project::ProjectBuildExtraHostAddresses::List(values) => values
                            .iter()
                            .map(|value| {
                                self.sourced_project_key_value(
                                    ImageArtifactAssignment::new(
                                        Self::protected(entry.hostname().value(), entry.hostname().is_sensitive()),
                                        Some(Self::protected(value.value(), value.is_sensitive())),
                                    ),
                                    entry.hostname().sources(),
                                    value.provenance(),
                                )
                            })
                            .collect(),
                        _ => Vec::new(),
                    })
                    .collect(),
            ),
            _ => return,
        };
        settings.push(self.sourced_provenance(
            SourceBuildSetting::ExtraHosts(BuildSettingValues::new(syntax, values)),
            native.provenance(),
        ));
    }

    fn map_build_no_cache_filter(
        &self,
        native: Option<&ProjectValue<ProjectBuildNoCacheFilter>>,
        settings: &mut Vec<Sourced<SourceBuildSetting>>,
    ) {
        let Some(native) = native else { return };
        let (syntax, values) = match native.value() {
            ProjectBuildNoCacheFilter::Scalar(value) => (
                BuildSyntax::Scalar,
                vec![self.sourced_provenance(Self::protected(value.value(), value.is_sensitive()), value.provenance())],
            ),
            ProjectBuildNoCacheFilter::List(values) => (
                BuildSyntax::Sequence,
                values
                    .iter()
                    .map(|value| {
                        self.sourced_provenance(
                            Self::protected(value.value(), value.is_sensitive()),
                            value.provenance(),
                        )
                    })
                    .collect(),
            ),
            _ => return,
        };
        settings.push(self.sourced_provenance(
            SourceBuildSetting::NoCacheFilters(BuildSettingValues::new(syntax, values)),
            native.provenance(),
        ));
    }

    fn map_build_ssh(
        &self,
        native: Option<&ProjectValue<ProjectBuildSsh>>,
        settings: &mut Vec<Sourced<SourceBuildSetting>>,
    ) {
        let Some(native) = native else { return };
        let (syntax, values) = match native.value() {
            ProjectBuildSsh::List(entries) => (
                BuildSyntax::Sequence,
                entries
                    .iter()
                    .map(|entry| self.sourced_provenance(ProtectedString::sensitive(entry.value()), entry.provenance()))
                    .collect(),
            ),
            ProjectBuildSsh::Map(entries) => (
                BuildSyntax::Mapping,
                entries
                    .iter()
                    .map(|entry| {
                        self.sourced_project_key_value(
                            ProtectedString::sensitive(format!(
                                "{}={}",
                                entry.name().value(),
                                scalar_text(entry.value().value())
                            )),
                            entry.name().sources(),
                            entry.value().provenance(),
                        )
                    })
                    .collect(),
            ),
            _ => return,
        };
        settings.push(self.sourced_provenance(
            SourceBuildSetting::Ssh(BuildSettingValues::new(syntax, values)),
            native.provenance(),
        ));
    }

    fn map_build_secrets(
        &self,
        native: Option<&ProjectValue<Vec<ProjectValue<ProjectGrant>>>>,
        settings: &mut Vec<Sourced<SourceBuildSetting>>,
    ) {
        let Some(native) = native else { return };
        let values = native
            .value()
            .iter()
            .filter_map(|grant| match grant.value() {
                ProjectGrant::Short(source) => Some(self.sourced_provenance(
                    SourceBuildSecret::new(Self::protected(source, grant.is_sensitive())),
                    grant.provenance(),
                )),
                ProjectGrant::Long(long) => {
                    let source = long.source()?;
                    let mut secret = SourceBuildSecret::new(Self::protected(source.value(), source.is_sensitive()));
                    if let Some(target) = long.target() {
                        secret.set_target(Self::protected(target.value(), target.is_sensitive()));
                    }
                    if let Some(uid) = long.uid() {
                        secret.set_uid(Self::protected(uid.value(), uid.is_sensitive()));
                    }
                    if let Some(gid) = long.gid() {
                        secret.set_gid(Self::protected(gid.value(), gid.is_sensitive()));
                    }
                    if let Some(mode) = long.mode() {
                        secret.set_mode(Self::protected(mode.value(), mode.is_sensitive()));
                    }
                    Some(self.sourced_provenance(secret, grant.provenance()))
                }
            })
            .collect();
        settings.push(self.sourced_provenance(
            SourceBuildSetting::Secrets(BuildSettingValues::new(BuildSyntax::Sequence, values)),
            native.provenance(),
        ));
    }

    fn map_build_ulimits(
        &self,
        native: Option<&ProjectValue<compose_lens::project::ProjectUlimits>>,
        settings: &mut Vec<Sourced<SourceBuildSetting>>,
    ) {
        let Some(native) = native else { return };
        let values = native
            .value()
            .entries()
            .iter()
            .map(|entry| {
                let value = entry.value();
                let (soft, hard) = match value.value() {
                    ProjectUlimitValue::Single(value) => {
                        let value = self.sourced_provenance(
                            Self::protected(value.value().value().raw(), value.is_sensitive()),
                            value.provenance(),
                        );
                        (Some(value.clone()), Some(value))
                    }
                    ProjectUlimitValue::Range(range) => (
                        range.soft().map(|value| {
                            self.sourced_provenance(
                                Self::protected(value.value().value().raw(), value.is_sensitive()),
                                value.provenance(),
                            )
                        }),
                        range.hard().map(|value| {
                            self.sourced_provenance(
                                Self::protected(value.value().value().raw(), value.is_sensitive()),
                                value.provenance(),
                            )
                        }),
                    ),
                    _ => (None, None),
                };
                self.sourced_project_key_value(
                    ResourceLimit::new(
                        Self::protected(entry.value().name().value(), entry.value().name().is_sensitive()),
                        soft,
                        hard,
                    ),
                    entry.value().name().sources(),
                    entry.provenance(),
                )
            })
            .collect();
        settings.push(self.sourced_provenance(
            SourceBuildSetting::Ulimits(BuildSettingValues::new(BuildSyntax::Mapping, values)),
            native.provenance(),
        ));
    }

    fn map_service_labels(&mut self, subject: &str, native: &ProjectService, service: &mut Service) {
        if let Some(labels) = native.labels() {
            self.map_labels(subject, labels.value(), service);
        }
    }

    fn map_restart_policy(&mut self, subject: &str, native: &ProjectService, service: &mut Service) {
        let Some(restart) = native.restart() else {
            return;
        };
        let restart_subject = format!("{subject}.restart_policy");
        let policy = match restart.value().kind() {
            ComposeRestartPolicyKind::No => NeutralRestartPolicy::Never,
            ComposeRestartPolicyKind::Always => NeutralRestartPolicy::Always,
            ComposeRestartPolicyKind::OnFailure { maximum_retries: None } => NeutralRestartPolicy::on_failure(None),
            ComposeRestartPolicyKind::OnFailure {
                maximum_retries: Some(maximum_retries),
            } => {
                let Ok(maximum_retries) = maximum_retries.parse::<u64>() else {
                    self.invalid_value_optional(
                        &restart_subject,
                        "restart maximum retry count exceeds the neutral model's unsigned 64-bit range",
                        restart.effective_source(),
                    );
                    return;
                };
                let Some(maximum_retries) = std::num::NonZeroU64::new(maximum_retries) else {
                    self.invalid_value_optional(
                        &restart_subject,
                        "an explicitly authored restart maximum retry count must be greater than zero",
                        restart.effective_source(),
                    );
                    return;
                };
                NeutralRestartPolicy::on_failure(Some(maximum_retries))
            }
            ComposeRestartPolicyKind::UnlessStopped => NeutralRestartPolicy::UnlessStopped,
            ComposeRestartPolicyKind::Expression => {
                self.invalid_value_optional(
                    &restart_subject,
                    "restart policy expression was not resolved before conversion",
                    restart.effective_source(),
                );
                return;
            }
            ComposeRestartPolicyKind::Other => {
                self.invalid_value_optional(
                    &restart_subject,
                    "restart policy is not a Compose-defined service-level policy",
                    restart.effective_source(),
                );
                return;
            }
            _ => {
                self.unsupported_optional(
                    &restart_subject,
                    "restart policy variant is newer than this Compose adapter",
                    restart.effective_source(),
                );
                return;
            }
        };
        service.set_restart_policy(self.sourced_provenance(policy, restart.provenance()));
        self.exact_provenance(restart_subject, restart.provenance());
    }

    fn map_execution_context(&mut self, service_subject: &str, native: &ProjectService, service: &mut Service) {
        if let Some(user) = native.user() {
            let sensitive = user.is_sensitive();
            let primary = Self::protected(user.value().user().raw(), sensitive);
            service.set_user(self.sourced_provenance(primary, user.provenance()));
            self.exact_provenance(format!("{service_subject}.user"), user.provenance());

            if let Some(group) = user.value().group() {
                service.set_group(self.sourced_provenance(Self::protected(group.raw(), sensitive), user.provenance()));
                self.exact_provenance(format!("{service_subject}.group"), user.provenance());
            }
        }
        if let Some(user_namespace) = native.userns_mode() {
            service.set_user_namespace(self.sourced_provenance(
                Self::protected(user_namespace.value().raw().value(), user_namespace.is_sensitive()),
                user_namespace.provenance(),
            ));
            self.exact_provenance(format!("{service_subject}.user_namespace"), user_namespace.provenance());
        }
        if let Some(groups) = native.group_add() {
            for (index, group) in groups.value().iter().enumerate() {
                service.add_supplementary_group(
                    self.sourced_provenance(Self::protected(group.value(), group.is_sensitive()), group.provenance()),
                );
                self.exact_provenance(
                    format!("{service_subject}.supplementary_groups[{index}]"),
                    group.provenance(),
                );
            }
        }
        if let Some(working_directory) = native.working_dir() {
            service.set_working_directory(self.sourced_provenance(
                Self::protected(working_directory.value(), working_directory.is_sensitive()),
                working_directory.provenance(),
            ));
            self.exact_provenance(
                format!("{service_subject}.working_directory"),
                working_directory.provenance(),
            );
        }
        if let Some(read_only) = native.read_only() {
            let subject = format!("{service_subject}.read_only_root_filesystem");
            match read_only.value() {
                BooleanValue::Literal(value) => {
                    service.set_read_only_root_filesystem(self.sourced_provenance(*value, read_only.provenance()));
                    self.exact_provenance(subject, read_only.provenance());
                }
                BooleanValue::Expression(_) => self.invalid_value_optional(
                    &subject,
                    "read-only root-filesystem expression was not resolved",
                    read_only.effective_source(),
                ),
            }
        }
    }

    fn map_released_container_settings(
        &mut self,
        service_subject: &str,
        native: &ProjectService,
        service: &mut Service,
    ) {
        self.map_entrypoint_lifecycle_and_pull(service_subject, native, service);
        self.map_hostname_pids_and_shm(service_subject, native, service);
        self.map_memory_and_expose(service_subject, native, service);
        self.map_capabilities_and_tmpfs(service_subject, native, service);
        self.map_sysctls(service_subject, native, service);
        self.map_ulimits(service_subject, native, service);
        self.map_devices_and_stop_signal(service_subject, native, service);
        self.map_annotations_and_logging(service_subject, native, service);
    }

    fn map_entrypoint_lifecycle_and_pull(
        &mut self,
        service_subject: &str,
        native: &ProjectService,
        service: &mut Service,
    ) {
        if let Some(entrypoint) = native.entrypoint() {
            let subject = format!("{service_subject}.entrypoint");
            let value = match entrypoint.value() {
                ComposeEntrypoint::String(value) if value.value().is_empty() => Some(NeutralEntrypoint::Empty),
                ComposeEntrypoint::String(value) => Some(NeutralEntrypoint::Shell(Self::protected(
                    value.value(),
                    entrypoint.is_sensitive(),
                ))),
                ComposeEntrypoint::List { values, .. } if values.is_empty() => Some(NeutralEntrypoint::Empty),
                ComposeEntrypoint::List { values, .. } => Some(NeutralEntrypoint::Exec(
                    values
                        .iter()
                        .map(|value| Self::protected(value.value(), entrypoint.is_sensitive()))
                        .collect(),
                )),
                ComposeEntrypoint::Null(_) => None,
            };
            if let Some(value) = value {
                service.set_entrypoint(self.sourced_provenance(value, entrypoint.provenance()));
                self.exact_provenance(subject, entrypoint.provenance());
            } else {
                self.unsupported_optional(&subject, "Compose null entrypoint restores the image default, which differs from a neutral explicit empty override", entrypoint.effective_source());
            }
        }
        if let Some(init) = native.init() {
            let subject = format!("{service_subject}.init");
            match init.value() {
                BooleanValue::Literal(value) => {
                    service.set_run_init(self.sourced_provenance(*value, init.provenance()));
                    self.exact_provenance(subject, init.provenance());
                }
                BooleanValue::Expression(_) => {
                    self.invalid_value_optional(&subject, "init expression was not resolved", init.effective_source());
                }
            }
        }
        if let Some(timeout) = native.stop_grace_period() {
            let subject = format!("{service_subject}.stop_grace_period");
            let value = timeout.value().raw();
            match StopTimeout::new(value) {
                Ok(value) => service.set_stop_timeout(self.sourced_provenance(value, timeout.provenance())),
                Err(error) => {
                    self.invalid_model_optional(&subject, &error, timeout.effective_source());
                    return;
                }
            }
            if timeout.value().is_valid() && !value.contains('$') {
                self.exact_provenance(subject, timeout.provenance());
            } else {
                self.invalid_value_optional(
                    &subject,
                    "stop_grace_period is unresolved or provider-specific",
                    timeout.effective_source(),
                );
            }
        }
        if let Some(policy) = native.pull_policy() {
            let subject = format!("{service_subject}.pull_policy");
            let raw = policy.value().raw().value();
            let value = match policy.value().kind() {
                PullPolicyKind::Always => NeutralPullPolicy::Always,
                PullPolicyKind::Never => NeutralPullPolicy::Never,
                PullPolicyKind::Missing => NeutralPullPolicy::Missing,
                PullPolicyKind::IfNotPresentAlias => NeutralPullPolicy::IfNotPresent,
                PullPolicyKind::Build => NeutralPullPolicy::Build,
                PullPolicyKind::Daily => NeutralPullPolicy::Daily,
                PullPolicyKind::Weekly => NeutralPullPolicy::Weekly,
                PullPolicyKind::Every { duration } => {
                    NeutralPullPolicy::Every(Self::protected(duration, policy.is_sensitive()))
                }
                PullPolicyKind::RefreshSchemaOnly | PullPolicyKind::Expression | PullPolicyKind::Other => {
                    NeutralPullPolicy::Raw(Self::protected(raw, policy.is_sensitive()))
                }
                _ => NeutralPullPolicy::Raw(Self::protected(raw, policy.is_sensitive())),
            };
            service.set_pull_policy(self.sourced_provenance(value, policy.provenance()));
            if matches!(
                policy.value().kind(),
                PullPolicyKind::RefreshSchemaOnly | PullPolicyKind::Expression | PullPolicyKind::Other
            ) {
                self.invalid_value_optional(
                    &subject,
                    "pull_policy is unresolved, schema-only, or provider-specific",
                    policy.effective_source(),
                );
            } else {
                self.exact_provenance(subject, policy.provenance());
            }
        }
    }

    fn map_memory_and_expose(&mut self, service_subject: &str, native: &ProjectService, service: &mut Service) {
        if let Some(limit) = native.mem_limit() {
            let subject = format!("{service_subject}.mem_limit");
            service.set_memory_limit(self.sourced_provenance(
                Self::protected(limit.value().raw().value(), limit.is_sensitive()),
                limit.provenance(),
            ));
            if matches!(limit.value().kind(), MemLimitKind::Documented { .. }) {
                self.exact_provenance(subject, limit.provenance());
            } else {
                self.invalid_value_optional(
                    &subject,
                    "mem_limit must use a documented positive lowercase-unit value",
                    limit.effective_source(),
                );
            }
        }
        if let Some(expose) = native.expose() {
            let subject = format!("{service_subject}.expose");
            let mut ports = Vec::new();
            let mut exact = true;
            for item in expose.value() {
                let kind = item.value().kind();
                let (port, protocol) = match kind {
                    ExposeItemKind::Documented { port, protocol } if port.end().is_none() => {
                        let Ok(port) = port.start().parse::<u16>() else {
                            exact = false;
                            continue;
                        };
                        let protocol = match protocol {
                            Some(ExposeProtocol::Udp) => Protocol::Udp,
                            Some(ExposeProtocol::Tcp) | None => Protocol::Tcp,
                            _ => {
                                exact = false;
                                continue;
                            }
                        };
                        (port, protocol)
                    }
                    _ => {
                        exact = false;
                        continue;
                    }
                };
                match ExposedPort::new(port, protocol) {
                    Ok(port) => ports.push(self.sourced_provenance(port, item.provenance())),
                    Err(error) => {
                        exact = false;
                        self.invalid_model_optional(&subject, &error, item.effective_source());
                    }
                }
            }
            service.set_exposed_ports_with_origins(ports, self.origins(expose.provenance()));
            if exact {
                self.exact_provenance(subject, expose.provenance());
            } else {
                self.invalid_value_optional(&subject, "expose accepts only safe single tcp or udp ports; ranges, SCTP, deferred, and unsafe forms remain explicit", expose.effective_source());
            }
        }
    }

    fn map_annotations_and_logging(&mut self, service_subject: &str, native: &ProjectService, service: &mut Service) {
        if let Some(annotations) = native.annotations() {
            let subject = format!("{service_subject}.annotations");
            let mut values = Vec::new();
            let mut exact = true;
            for entry in annotations.value().entries() {
                let Some(value) = entry.value() else {
                    exact = false;
                    continue;
                };
                let Some(name) =
                    self.identifier_optional(&subject, entry.name().value(), entry.name().effective_source())
                else {
                    exact = false;
                    continue;
                };
                let scalar = Self::compose_scalar(value.value().effective());
                values.push(self.sourced_project_key_value(
                    Annotation::new(
                        self.sourced_spans(name, entry.name().sources()),
                        self.sourced_provenance(Self::protected(&scalar, value.is_sensitive()), value.provenance()),
                    ),
                    entry.name().sources(),
                    value.provenance(),
                ));
            }
            service.set_annotations_with_origins(values, self.origins(annotations.provenance()));
            if exact {
                self.exact_provenance(subject, annotations.provenance());
            } else {
                self.invalid_value_optional(
                    &subject,
                    "annotations require explicit valid names and values",
                    annotations.effective_source(),
                );
            }
        }
        if let Some(logging) = native.logging() {
            let subject = format!("{service_subject}.logging");
            let mut value = Logging::new();
            if let Some(driver) = logging.value().driver() {
                value.set_driver(self.sourced_provenance(
                    Self::protected(driver.value(), driver.is_sensitive()),
                    driver.provenance(),
                ));
            } else {
                self.unsupported_optional(
                    &subject,
                    "logging options without a driver use provider-default semantics",
                    logging.effective_source(),
                );
            }
            if let Some(options) = logging.value().options() {
                let mut mapped = Vec::new();
                for option in options.value().entries() {
                    let raw = match option.value().value().value() {
                        ProjectLoggingOptionValue::String { value, .. } | ProjectLoggingOptionValue::Number(value) => {
                            value
                        }
                        ProjectLoggingOptionValue::Null => "",
                        _ => {
                            self.invalid_value_optional(
                                &subject,
                                "logging option variant is newer than this adapter",
                                option.effective_source(),
                            );
                            continue;
                        }
                    };
                    let Some(name) = self.identifier_optional(
                        &subject,
                        option.value().name().value(),
                        option.value().name().effective_source(),
                    ) else {
                        continue;
                    };
                    mapped.push(self.sourced_project_key_value(
                        LoggingOption::new(
                            self.sourced_spans(name, option.value().name().sources()),
                            self.sourced_provenance(
                                Self::protected(raw, option.value().value().is_sensitive()),
                                option.value().value().provenance(),
                            ),
                        ),
                        option.value().name().sources(),
                        option.value().value().provenance(),
                    ));
                }
                value.set_options_with_origins(mapped, self.origins(options.provenance()));
            }
            service.set_logging(self.sourced_provenance(value, logging.provenance()));
            if logging.value().driver().is_some() {
                self.exact_provenance(subject, logging.provenance());
            }
        }
    }

    fn map_dns(&mut self, subject: &str, native: &ProjectService, service: &mut Service) {
        if let Some(dns) = native.dns() {
            let values = match dns.value() {
                ProjectDns::Scalar(value) => Some(std::slice::from_ref(value)),
                ProjectDns::List(values) => Some(values.as_slice()),
                _ => {
                    self.unsupported_optional(
                        &format!("{subject}.dns"),
                        "DNS form is newer than this adapter",
                        dns.effective_source(),
                    );
                    None
                }
            };
            if let Some(values) = values {
                let mapped = values
                    .iter()
                    .map(|value| {
                        self.sourced_provenance(
                            Self::protected(value.value(), value.is_sensitive()),
                            value.provenance(),
                        )
                    })
                    .collect();
                service.set_dns_servers_with_origins(mapped, self.origins(dns.provenance()));
                self.dns_import_outcome(&format!("{subject}.dns"), values, dns.provenance(), "dns");
            }
        }
        if let Some(options) = native.dns_options() {
            let mapped = options
                .value()
                .iter()
                .map(|value| {
                    self.sourced_provenance(Self::protected(value.value(), value.is_sensitive()), value.provenance())
                })
                .collect();
            service.set_dns_options_with_origins(mapped, self.origins(options.provenance()));
            let duplicate = options.value().iter().enumerate().any(|(index, value)| {
                options.value()[..index]
                    .iter()
                    .any(|prior| prior.value() == value.value())
            });
            if duplicate {
                self.invalid_value_optional(
                    &format!("{subject}.dns_opt"),
                    "dns_opt contains duplicate resolver options",
                    options.effective_source(),
                );
            } else {
                self.dns_import_outcome(
                    &format!("{subject}.dns_opt"),
                    options.value(),
                    options.provenance(),
                    "dns_opt",
                );
            }
        }
        if let Some(search) = native.dns_search() {
            let values = match search.value() {
                ProjectDnsSearch::Scalar(value) => Some(std::slice::from_ref(value)),
                ProjectDnsSearch::List(values) => Some(values.as_slice()),
                _ => {
                    self.unsupported_optional(
                        &format!("{subject}.dns_search"),
                        "DNS search form is newer than this adapter",
                        search.effective_source(),
                    );
                    None
                }
            };
            if let Some(values) = values {
                let mapped = values
                    .iter()
                    .map(|value| {
                        self.sourced_provenance(
                            Self::protected(value.value(), value.is_sensitive()),
                            value.provenance(),
                        )
                    })
                    .collect();
                service.set_dns_search_domains_with_origins(mapped, self.origins(search.provenance()));
                self.dns_import_outcome(
                    &format!("{subject}.dns_search"),
                    values,
                    search.provenance(),
                    "dns_search",
                );
            }
        }
    }

    fn map_security_options(&mut self, service_subject: &str, native: &ProjectService, service: &mut Service) {
        let Some(options) = native.security_options() else {
            return;
        };
        let subject = format!("{service_subject}.security_opt");
        let mut mapped = Vec::new();
        let mut singleton_counts = [0_usize; 8];
        let mut has_label_disable = false;
        let mut has_other_label = false;

        for (index, item) in options.value().iter().enumerate() {
            let item_subject = format!("{subject}[{index}]");
            match Self::map_security_option(item.value().kind(), item.is_sensitive()) {
                SecurityOptionMapping::Exact(value) => {
                    Self::record_security_option_conflict(
                        &value,
                        &mut singleton_counts,
                        &mut has_label_disable,
                        &mut has_other_label,
                    );
                    mapped.push(self.sourced_provenance(value, item.provenance()));
                    self.exact_provenance(item_subject, item.provenance());
                }
                SecurityOptionMapping::Invalid(reason) => {
                    self.invalid_value_optional(&item_subject, reason, item.effective_source());
                }
                SecurityOptionMapping::Unsupported(reason) => {
                    self.unsupported_optional(&item_subject, reason, item.effective_source());
                }
            }
        }

        service.set_security_options_with_origins(mapped, self.origins(options.provenance()));
        let singleton_conflict = singleton_counts.iter().any(|count| *count > 1);
        if singleton_conflict {
            self.invalid_value_optional(
                &subject,
                "security_opt contains multiple candidates for a singleton security-option family",
                options.effective_source(),
            );
        }
        if has_label_disable && has_other_label {
            self.unsupported_optional(
                &subject,
                "label:disable conflicts semantically with other SELinux label candidates",
                options.effective_source(),
            );
        }
        if !(singleton_conflict || has_label_disable && has_other_label) {
            self.exact_provenance(subject, options.provenance());
        }
    }

    fn map_security_option(kind: &SecurityOptionKind, sensitive: bool) -> SecurityOptionMapping {
        let exact = match kind {
            SecurityOptionKind::AppArmor { profile } => SecurityOption::AppArmor(Self::protected(profile, sensitive)),
            SecurityOptionKind::NoNewPrivileges { enabled } => SecurityOption::NoNewPrivileges(*enabled),
            SecurityOptionKind::Seccomp { profile } => {
                SecurityOption::SeccompProfile(Self::protected(profile, sensitive))
            }
            SecurityOptionKind::SecurityLabelDisable { enabled } => SecurityOption::SecurityLabelDisable(*enabled),
            SecurityOptionKind::SecurityLabelFileType { file_type } => {
                SecurityOption::SecurityLabelFileType(Self::protected(file_type, sensitive))
            }
            SecurityOptionKind::SecurityLabelLevel { level } => {
                SecurityOption::SecurityLabelLevel(Self::protected(level, sensitive))
            }
            SecurityOptionKind::SecurityLabelNested { enabled } => SecurityOption::SecurityLabelNested(*enabled),
            SecurityOptionKind::SecurityLabelType { label_type } => {
                SecurityOption::SecurityLabelType(Self::protected(label_type, sensitive))
            }
            SecurityOptionKind::Mask { paths } => SecurityOption::Mask(Self::protected(paths, sensitive)),
            SecurityOptionKind::Unmask { paths } => SecurityOption::Unmask(Self::protected(paths, sensitive)),
            SecurityOptionKind::Expression => {
                return SecurityOptionMapping::Invalid("security option expression was not resolved before conversion");
            }
            SecurityOptionKind::Empty => {
                return SecurityOptionMapping::Invalid("security options must not contain empty strings");
            }
            SecurityOptionKind::AppArmorNearMiss
            | SecurityOptionKind::SeccompNearMiss
            | SecurityOptionKind::NoNewPrivilegesNearMiss
            | SecurityOptionKind::SecurityLabelDisableNearMiss
            | SecurityOptionKind::SecurityLabelFileTypeNearMiss
            | SecurityOptionKind::SecurityLabelLevelNearMiss
            | SecurityOptionKind::SecurityLabelNestedNearMiss
            | SecurityOptionKind::SecurityLabelTypeNearMiss
            | SecurityOptionKind::MaskNearMiss
            | SecurityOptionKind::UnmaskNearMiss => {
                return SecurityOptionMapping::Invalid(
                    "security option must use a released exact ComposeLens candidate spelling",
                );
            }
            SecurityOptionKind::Other => {
                return SecurityOptionMapping::Unsupported("raw security option has no neutral semantic mapping");
            }
            _ => {
                return SecurityOptionMapping::Unsupported(
                    "security option variant is newer than this Compose adapter",
                );
            }
        };
        SecurityOptionMapping::Exact(exact)
    }

    fn record_security_option_conflict(
        value: &SecurityOption,
        singleton_counts: &mut [usize; 8],
        has_label_disable: &mut bool,
        has_other_label: &mut bool,
    ) {
        let family = match value {
            SecurityOption::AppArmor(_) => Some(0),
            SecurityOption::NoNewPrivileges(_) => Some(1),
            SecurityOption::SeccompProfile(_) => Some(2),
            SecurityOption::SecurityLabelDisable(enabled) => {
                *has_label_disable |= *enabled;
                Some(3)
            }
            SecurityOption::SecurityLabelFileType(_) => Some(4),
            SecurityOption::SecurityLabelLevel(_) => Some(5),
            SecurityOption::SecurityLabelNested(_) => Some(6),
            SecurityOption::SecurityLabelType(_) => Some(7),
            _ => None,
        };
        *has_other_label |= matches!(
            value,
            SecurityOption::SecurityLabelFileType(_)
                | SecurityOption::SecurityLabelLevel(_)
                | SecurityOption::SecurityLabelNested(_)
                | SecurityOption::SecurityLabelType(_)
        );
        if let Some(family) = family {
            singleton_counts[family] += 1;
        }
    }

    fn dns_import_outcome(
        &mut self,
        subject: &str,
        values: &[ProjectValue<String>],
        provenance: &MergeProvenance,
        field: &str,
    ) {
        if values.is_empty() {
            self.unsupported_optional(
                subject,
                "explicit empty DNS collections have target-specific reset semantics",
                provenance.effective_source(),
            );
        } else if values
            .iter()
            .any(|value| value.value().is_empty() || value.value().contains(['\r', '\n']) || value.is_sensitive())
        {
            self.invalid_value_optional(
                subject,
                "DNS values must be resolved non-empty single physical lines",
                provenance.effective_source(),
            );
        } else if (field == "dns" && values.iter().any(|value| value.value() == "none"))
            || (field == "dns_search" && values.iter().any(|value| value.value() == "."))
        {
            self.unsupported_optional(
                subject,
                "special DNS values have target-specific resolver semantics",
                provenance.effective_source(),
            );
        } else {
            self.exact_provenance(subject, provenance);
        }
    }

    fn map_hostname_pids_and_shm(&mut self, service_subject: &str, native: &ProjectService, service: &mut Service) {
        if let Some(hostname) = native.hostname() {
            let subject = format!("{service_subject}.hostname");
            let value = hostname.value().raw().value();
            service.set_hostname(
                self.sourced_provenance(Self::protected(value, hostname.is_sensitive()), hostname.provenance()),
            );
            if native.uts().is_some() {
                self.unsupported_optional(
                    &subject,
                    "hostname cannot be emitted while host UTS mode remains unmodeled",
                    hostname.effective_source(),
                );
            } else if matches!(hostname.value().kind(), HostnameKind::Resolved) {
                self.exact_provenance(subject, hostname.provenance());
            } else {
                self.invalid_value_optional(
                    &subject,
                    "hostname is unresolved or outside the conservative portable hostname grammar",
                    hostname.effective_source(),
                );
            }
        }
        if let Some(uts) = native.uts() {
            self.unsupported_optional(
                &format!("{service_subject}.uts"),
                "Compose UTS namespace mode has no neutral-model mapping",
                uts.effective_source(),
            );
        }
        if let Some(limit) = native.pids_limit() {
            let subject = format!("{service_subject}.pids_limit");
            service.set_pids_limit(self.sourced_provenance(
                Self::protected(limit.value().raw().value(), limit.is_sensitive()),
                limit.provenance(),
            ));
            match limit.value().kind() {
                PidsLimitKind::Unlimited | PidsLimitKind::Finite { .. } => {
                    self.exact_provenance(subject, limit.provenance());
                }
                _ => self.invalid_value_optional(
                    &subject,
                    "PID limit must be -1 or a positive ASCII decimal before exact conversion",
                    limit.effective_source(),
                ),
            }
        }
        if let Some(size) = native.shm_size() {
            let subject = format!("{service_subject}.shm_size");
            let normalized = quadlet_shm_size(size.value().kind());
            service.set_shm_size(self.sourced_provenance(
                Self::protected(
                    normalized.as_deref().unwrap_or_else(|| size.value().raw().value()),
                    size.is_sensitive(),
                ),
                size.provenance(),
            ));
            if normalized.is_some() {
                self.exact_provenance(subject, size.provenance());
            } else {
                self.invalid_value_optional(
                    &subject,
                    "shared-memory size must be a positive ASCII decimal with b, k, kb, m, mb, g, or gb",
                    size.effective_source(),
                );
            }
        }
    }

    fn map_capabilities_and_tmpfs(&mut self, service_subject: &str, native: &ProjectService, service: &mut Service) {
        if let Some(values) = native.cap_add() {
            let subject = format!("{service_subject}.cap_add");
            let mut exact = true;
            let mapped = values
                .value()
                .iter()
                .map(|value| {
                    if !value.value().is_exact_candidate() || value.value().value().contains('$') {
                        exact = false;
                    }
                    self.sourced_provenance(
                        Self::protected(value.value().value(), value.is_sensitive()),
                        value.provenance(),
                    )
                })
                .collect();
            service.set_cap_add_with_origins(mapped, self.origins(values.provenance()));
            if exact {
                self.exact_provenance(subject, values.provenance());
            } else {
                self.invalid_value_optional(
                    &subject,
                    "capability entries must be resolved non-empty strings without whitespace",
                    values.effective_source(),
                );
            }
        }
        if let Some(values) = native.cap_drop() {
            let subject = format!("{service_subject}.cap_drop");
            let mut exact = true;
            let mapped = values
                .value()
                .iter()
                .map(|value| {
                    if !value.value().is_exact_candidate() || value.value().value().contains('$') {
                        exact = false;
                    }
                    self.sourced_provenance(
                        Self::protected(value.value().value(), value.is_sensitive()),
                        value.provenance(),
                    )
                })
                .collect();
            service.set_cap_drop_with_origins(mapped, self.origins(values.provenance()));
            if exact {
                self.exact_provenance(subject, values.provenance());
            } else {
                self.invalid_value_optional(
                    &subject,
                    "capability entries must be resolved non-empty strings without whitespace",
                    values.effective_source(),
                );
            }
        }
        if let Some(tmpfs) = native.tmpfs() {
            let (values, exact) = match tmpfs.value() {
                ProjectTmpfs::Scalar(value) => (vec![value], value.value().kind() == TmpfsItemKind::Documented),
                ProjectTmpfs::List(values) => (
                    values.iter().collect(),
                    values
                        .iter()
                        .all(|value| value.value().kind() == TmpfsItemKind::Documented),
                ),
                _ => (Vec::new(), false),
            };
            let mapped = values
                .into_iter()
                .map(|value| {
                    self.sourced_provenance(
                        Self::protected(value.value().value(), value.is_sensitive()),
                        value.provenance(),
                    )
                })
                .collect();
            service.set_tmpfs_with_origins(mapped, self.origins(tmpfs.provenance()));
            if exact {
                self.exact_provenance(format!("{service_subject}.tmpfs"), tmpfs.provenance());
            } else {
                self.invalid_value_optional(
                    &format!("{service_subject}.tmpfs"),
                    "tmpfs entries must be resolved documented declarations",
                    tmpfs.effective_source(),
                );
            }
        }
    }

    fn map_sysctls(&mut self, service_subject: &str, native: &ProjectService, service: &mut Service) {
        if let Some(sysctls) = native.sysctls() {
            let mut exact = true;
            let values = match sysctls.value() {
                ProjectSysctls::Map(values) => values
                    .iter()
                    .map(|value| {
                        let native = value.value();
                        let scalar = Self::compose_scalar(native.value().value());
                        if native.name().value().is_empty()
                            || native.name().value().contains('$')
                            || scalar.contains('$')
                            || matches!(native.value().value(), ComposeScalar::Null)
                        {
                            exact = false;
                        }
                        self.sourced_project_key_value(
                            KernelParameter::new(
                                Self::protected(native.name().value(), native.name().is_sensitive()),
                                Self::protected(&scalar, native.value().is_sensitive()),
                            ),
                            native.name().sources(),
                            native.value().provenance(),
                        )
                    })
                    .collect(),
                ProjectSysctls::List(values) => values
                    .iter()
                    .filter_map(|value| {
                        let Some((name, scalar)) = value.value().split_once('=') else {
                            exact = false;
                            self.invalid_value_optional(
                                &format!("{service_subject}.sysctls"),
                                "sysctl list entries must use unambiguous name=value spelling",
                                value.effective_source(),
                            );
                            return None;
                        };
                        if name.is_empty() || name.contains('$') || scalar.contains('$') {
                            exact = false;
                        }
                        Some(self.sourced_provenance(
                            KernelParameter::new(
                                Self::protected(name, value.is_sensitive()),
                                Self::protected(scalar, value.is_sensitive()),
                            ),
                            value.provenance(),
                        ))
                    })
                    .collect(),
                _ => {
                    exact = false;
                    Vec::new()
                }
            };
            service.set_sysctls_with_origins(values, self.origins(sysctls.provenance()));
            if exact {
                self.exact_provenance(format!("{service_subject}.sysctls"), sysctls.provenance());
            } else {
                self.invalid_value_optional(
                    &format!("{service_subject}.sysctls"),
                    "sysctl entries must use resolved unambiguous name=value spelling",
                    sysctls.effective_source(),
                );
            }
        }
    }

    fn map_ulimits(&mut self, service_subject: &str, native: &ProjectService, service: &mut Service) {
        if let Some(ulimits) = native.ulimits() {
            let mut mapped = Vec::new();
            let mut exact = true;
            for limit in ulimits.value().entries() {
                let name = limit.value().name();
                let (soft, hard) = match limit.value().value() {
                    ProjectUlimitValue::Single(value) => {
                        if !matches!(value.value().value(), LimitValue::Unlimited | LimitValue::Number(_)) {
                            exact = false;
                        }
                        let value = self.sourced_provenance(
                            Self::protected(value.value().authored(), value.is_sensitive()),
                            value.provenance(),
                        );
                        (Some(value.clone()), Some(value))
                    }
                    ProjectUlimitValue::Range(range) => (
                        range.soft().map(|value| {
                            if !matches!(value.value().value(), LimitValue::Unlimited | LimitValue::Number(_)) {
                                exact = false;
                            }
                            self.sourced_provenance(
                                Self::protected(value.value().authored(), value.is_sensitive()),
                                value.provenance(),
                            )
                        }),
                        range.hard().map(|value| {
                            if !matches!(value.value().value(), LimitValue::Unlimited | LimitValue::Number(_)) {
                                exact = false;
                            }
                            self.sourced_provenance(
                                Self::protected(value.value().authored(), value.is_sensitive()),
                                value.provenance(),
                            )
                        }),
                    ),
                    _ => {
                        exact = false;
                        (None, None)
                    }
                };
                if soft.is_none() || hard.is_none() {
                    exact = false;
                }
                let item = ResourceLimit::new(Self::protected(name.value(), name.is_sensitive()), soft, hard);
                mapped.push(self.sourced_spans(item, name.sources()));
            }
            service.set_ulimits_with_origins(mapped, self.origins(ulimits.provenance()));
            if exact {
                self.exact_provenance(format!("{service_subject}.ulimits"), ulimits.provenance());
            } else {
                self.invalid_value_optional(
                    &format!("{service_subject}.ulimits"),
                    "ulimits require complete resolved -1 or non-negative decimal values",
                    ulimits.effective_source(),
                );
            }
        }
    }

    fn map_devices_and_stop_signal(&mut self, service_subject: &str, native: &ProjectService, service: &mut Service) {
        if let Some(devices) = native.devices() {
            let mut exact = true;
            let mapped = devices
                .value()
                .iter()
                .filter_map(|device| match device.value() {
                    ProjectDevice::Short(short) => {
                        if matches!(short.kind(), ShortDeviceKind::Deferred) {
                            exact = false;
                        }
                        Some(self.sourced_provenance(
                            Device::Short(Self::protected(short.raw().value(), device.is_sensitive())),
                            device.provenance(),
                        ))
                    }
                    ProjectDevice::Long(long) => {
                        if long.source().is_none_or(|value| value.value().contains('$'))
                            || long.target().is_some_and(|value| value.value().contains('$'))
                            || long.permissions().is_some_and(|value| value.value().contains('$'))
                            || !long.extension_fields().is_empty()
                            || !long.unknown_fields().is_empty()
                        {
                            exact = false;
                        }
                        Some(self.sourced_provenance(
                            Device::Long {
                                source: long.source().map(|value| {
                                    self.sourced_provenance(
                                        Self::protected(value.value(), value.is_sensitive()),
                                        value.provenance(),
                                    )
                                }),
                                target: long.target().map(|value| {
                                    self.sourced_provenance(
                                        Self::protected(value.value(), value.is_sensitive()),
                                        value.provenance(),
                                    )
                                }),
                                permissions: long.permissions().map(|value| {
                                    self.sourced_provenance(
                                        Self::protected(value.value(), value.is_sensitive()),
                                        value.provenance(),
                                    )
                                }),
                            },
                            device.provenance(),
                        ))
                    }
                    _ => {
                        exact = false;
                        None
                    }
                })
                .collect();
            service.set_devices_with_origins(mapped, self.origins(devices.provenance()));
            if exact {
                self.exact_provenance(format!("{service_subject}.devices"), devices.provenance());
            } else {
                self.invalid_value_optional(
                    &format!("{service_subject}.devices"),
                    "devices require complete resolved short or long declarations",
                    devices.effective_source(),
                );
            }
        }
        if let Some(signal) = native.stop_signal() {
            service.set_stop_signal(self.sourced_provenance(
                Self::protected(signal.value(), signal.is_sensitive()),
                signal.provenance(),
            ));
            if Self::is_safe_stop_signal(signal.value()) {
                self.exact_provenance(format!("{service_subject}.stop_signal"), signal.provenance());
            } else {
                self.invalid_value_optional(
                    &format!("{service_subject}.stop_signal"),
                    "stop signal must be a non-empty resolved token or number",
                    signal.effective_source(),
                );
            }
        }
    }

    fn compose_scalar(value: &ComposeScalar) -> String {
        match value {
            ComposeScalar::Null => String::new(),
            ComposeScalar::Boolean(value) => value.to_string(),
            ComposeScalar::Number(value) | ComposeScalar::String(value) => value.clone(),
        }
    }

    fn is_safe_stop_signal(value: &str) -> bool {
        !value.is_empty()
            && value
                .bytes()
                .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-'))
    }

    fn protected(value: &str, sensitive: bool) -> ProtectedString {
        if sensitive {
            ProtectedString::sensitive(value)
        } else {
            ProtectedString::plain(value)
        }
    }

    fn map_service_dependencies(
        &mut self,
        service_subject: &str,
        dependencies: &ProjectValue<ProjectDependsOn>,
        service: &mut Service,
    ) {
        for (index, native) in dependencies.value().services().iter().enumerate() {
            let dependency_subject = format!("{service_subject}.depends_on[{index}]");
            let key = native.value().service();
            if key.is_sensitive() {
                self.invalid_value_optional(
                    &dependency_subject,
                    "dependency service name contains sensitive interpolated content",
                    key.effective_source(),
                );
                continue;
            }
            let Some(name) = self.identifier_optional(&dependency_subject, key.value(), key.effective_source()) else {
                continue;
            };
            let mut dependency = ServiceDependency::new(name);

            if let Some(condition) = native.value().condition() {
                if condition.is_sensitive() {
                    self.invalid_value_optional(
                        &format!("{dependency_subject}.condition"),
                        "dependency condition contains sensitive interpolated content",
                        condition.effective_source(),
                    );
                } else {
                    let value = match condition.value() {
                        ComposeDependencyCondition::ServiceStarted => ServiceDependencyCondition::Started,
                        ComposeDependencyCondition::ServiceHealthy => ServiceDependencyCondition::Healthy,
                        ComposeDependencyCondition::ServiceCompletedSuccessfully => {
                            ServiceDependencyCondition::CompletedSuccessfully
                        }
                        ComposeDependencyCondition::Other(value) => {
                            ServiceDependencyCondition::Other(ProtectedString::plain(value.clone()))
                        }
                    };
                    dependency.set_condition(self.sourced_provenance(value, condition.provenance()));
                    self.exact_provenance(format!("{dependency_subject}.condition"), condition.provenance());
                }
            }

            if let Some(restart) = native.value().restart() {
                self.map_dependency_boolean(&format!("{dependency_subject}.restart"), restart, |value| {
                    dependency.set_restart(value);
                });
            }
            if let Some(required) = native.value().required() {
                self.map_dependency_boolean(&format!("{dependency_subject}.required"), required, |value| {
                    dependency.set_required(value);
                });
            }
            self.report_project_fields(
                &dependency_subject,
                "dependency option",
                native.value().unmodeled_fields(),
            );

            let dependency = self.sourced_spans(dependency, key.sources());
            self.exact_origins(dependency_subject, dependency.origins());
            service.add_dependency(dependency);
        }
    }

    fn map_dependency_boolean(
        &mut self,
        subject: &str,
        native: &ProjectValue<BooleanValue>,
        set: impl FnOnce(Sourced<bool>),
    ) {
        match native.value() {
            BooleanValue::Literal(value) => {
                set(self.sourced_provenance(*value, native.provenance()));
                self.exact_provenance(subject, native.provenance());
            }
            BooleanValue::Expression(_) => self.invalid_value_optional(
                subject,
                "dependency boolean expression was not resolved",
                native.effective_source(),
            ),
        }
    }

    fn map_command(command: &compose_lens::model::Command, sensitive: bool) -> Option<Command> {
        let protect = |value: String| {
            if sensitive {
                ProtectedString::sensitive(value)
            } else {
                ProtectedString::plain(value)
            }
        };
        match command {
            compose_lens::model::Command::Null(_) => None,
            compose_lens::model::Command::String(value) if value.value().is_empty() => Some(Command::Empty),
            compose_lens::model::Command::String(value) => Some(Command::Shell(protect(value.value().clone()))),
            compose_lens::model::Command::List { values, .. } if values.is_empty() => Some(Command::Empty),
            compose_lens::model::Command::List { values, .. } => Some(Command::Exec(
                values.iter().map(|value| protect(value.value().clone())).collect(),
            )),
        }
    }

    fn map_healthcheck(
        &mut self,
        service_subject: &str,
        native: &ProjectValue<ProjectHealthcheck>,
    ) -> Sourced<Healthcheck> {
        let mut healthcheck = Healthcheck::new();

        if let Some(disable) = native.value().disable() {
            let subject = format!("{service_subject}.healthcheck.disable");
            match disable.value() {
                BooleanValue::Literal(value) => {
                    healthcheck.set_disabled(self.sourced_provenance(*value, disable.provenance()));
                    self.exact_provenance(subject, disable.provenance());
                }
                BooleanValue::Expression(_) => self.invalid_value_optional(
                    &subject,
                    "health-check disable expression was not resolved",
                    disable.effective_source(),
                ),
            }
        }

        if let Some(test) = native.value().test() {
            self.map_healthcheck_test(service_subject, test, &mut healthcheck);
        }
        if let Some(interval) = native.value().interval() {
            let subject = format!("{service_subject}.healthcheck.interval");
            if let Some(value) = self.map_healthcheck_duration(&subject, interval) {
                healthcheck.set_interval(value);
            }
        }
        if let Some(timeout) = native.value().timeout() {
            let subject = format!("{service_subject}.healthcheck.timeout");
            if let Some(value) = self.map_healthcheck_duration(&subject, timeout) {
                healthcheck.set_timeout(value);
            }
        }
        if let Some(retries) = native.value().retries() {
            let subject = format!("{service_subject}.healthcheck.retries");
            match retries.value() {
                ComposeHealthcheckRetries::Count(value) => match NeutralHealthcheckRetries::new(value.clone()) {
                    Ok(value) => {
                        healthcheck.set_retries(self.sourced_provenance(value, retries.provenance()));
                        self.exact_provenance(subject, retries.provenance());
                    }
                    Err(error) => self.invalid_model_optional(&subject, &error, retries.effective_source()),
                },
                ComposeHealthcheckRetries::Expression(_) => self.invalid_value_optional(
                    &subject,
                    "health-check retry expression was not resolved",
                    retries.effective_source(),
                ),
                ComposeHealthcheckRetries::Other(value) => self.invalid_value_optional(
                    &subject,
                    &format!("invalid health-check retry count `{value}`"),
                    retries.effective_source(),
                ),
            }
        }
        if let Some(start_period) = native.value().start_period() {
            let subject = format!("{service_subject}.healthcheck.start_period");
            if let Some(value) = self.map_healthcheck_duration(&subject, start_period) {
                healthcheck.set_start_period(value);
            }
        }
        if let Some(start_interval) = native.value().start_interval() {
            let subject = format!("{service_subject}.healthcheck.start_interval");
            if let Some(value) = self.map_healthcheck_duration(&subject, start_interval) {
                healthcheck.set_start_interval(value);
            }
        }
        self.report_project_fields(
            &format!("{service_subject}.healthcheck"),
            "health-check field",
            native.value().unmodeled_fields(),
        );

        self.sourced_provenance(healthcheck, native.provenance())
    }

    fn map_healthcheck_test(
        &mut self,
        service_subject: &str,
        test: &ProjectValue<HealthcheckTest>,
        healthcheck: &mut Healthcheck,
    ) {
        let subject = format!("{service_subject}.healthcheck.test");
        let protect = |value: String| {
            if test.is_sensitive() {
                ProtectedString::sensitive(value)
            } else {
                ProtectedString::plain(value)
            }
        };
        match test.value() {
            HealthcheckTest::String(value) => {
                healthcheck.set_command(self.sourced_provenance(
                    HealthcheckCommand::Shell(protect(value.value().clone())),
                    test.provenance(),
                ));
                self.exact_provenance(subject, test.provenance());
            }
            HealthcheckTest::List {
                kind: Some(HealthcheckTestKind::Cmd),
                values,
                ..
            } if values.len() > 1 => {
                healthcheck.set_command(self.sourced_provenance(
                    HealthcheckCommand::Exec(values[1..].iter().map(|value| protect(value.value().clone())).collect()),
                    test.provenance(),
                ));
                self.exact_provenance(subject, test.provenance());
            }
            HealthcheckTest::List {
                kind: Some(HealthcheckTestKind::CmdShell),
                values,
                ..
            } if values.len() == 2 => {
                healthcheck.set_command(self.sourced_provenance(
                    HealthcheckCommand::Shell(protect(values[1].value().clone())),
                    test.provenance(),
                ));
                self.exact_provenance(subject, test.provenance());
            }
            HealthcheckTest::List {
                kind: Some(HealthcheckTestKind::None),
                values,
                ..
            } if values.len() == 1 => {
                healthcheck.set_disabled(self.sourced_provenance(true, test.provenance()));
                self.exact_provenance(subject, test.provenance());
            }
            HealthcheckTest::List {
                kind: Some(HealthcheckTestKind::Cmd),
                ..
            } => self.invalid_value_optional(
                &subject,
                "CMD health check requires at least one command argument",
                test.effective_source(),
            ),
            HealthcheckTest::List {
                kind: Some(HealthcheckTestKind::CmdShell),
                ..
            } => self.unsupported_optional(
                &subject,
                "CMD-SHELL health check must contain exactly one shell string",
                test.effective_source(),
            ),
            HealthcheckTest::List {
                kind: Some(HealthcheckTestKind::None),
                ..
            } => self.invalid_value_optional(
                &subject,
                "NONE health check cannot contain command arguments",
                test.effective_source(),
            ),
            HealthcheckTest::List { kind: None, .. } => {
                self.invalid_value_optional(&subject, "health-check test list is empty", test.effective_source());
            }
            HealthcheckTest::List {
                kind: Some(HealthcheckTestKind::Other),
                ..
            } => self.unsupported_optional(&subject, "unknown health-check command mode", test.effective_source()),
        }
    }

    fn map_healthcheck_duration(
        &mut self,
        subject: &str,
        duration: &ProjectValue<ComposeHealthcheckDuration>,
    ) -> Option<Sourced<NeutralHealthcheckDuration>> {
        match duration.value() {
            ComposeHealthcheckDuration::Value(value) => match NeutralHealthcheckDuration::new(value.clone()) {
                Ok(value) => {
                    let value = self.sourced_provenance(value, duration.provenance());
                    self.exact_provenance(subject, duration.provenance());
                    Some(value)
                }
                Err(error) => {
                    self.invalid_model_optional(subject, &error, duration.effective_source());
                    None
                }
            },
            ComposeHealthcheckDuration::Expression(_) => {
                self.invalid_value_optional(
                    subject,
                    "health-check duration expression was not resolved",
                    duration.effective_source(),
                );
                None
            }
            ComposeHealthcheckDuration::Other(value) => {
                self.invalid_value_optional(
                    subject,
                    &format!("invalid health-check duration `{value}`"),
                    duration.effective_source(),
                );
                None
            }
        }
    }

    fn map_environment(&mut self, service_subject: &str, environment: &ProjectEnvironment, service: &mut Service) {
        for entry in environment.entries() {
            let subject = format!("{service_subject}.environment.{}", entry.name().value());
            let Some(name) = self.identifier_optional(&subject, entry.name().value(), entry.name().effective_source())
            else {
                continue;
            };
            let mut inspected_literal = false;
            let value = match entry.value().value() {
                ComposeScalar::Null => EnvironmentValue::Host,
                ComposeScalar::Boolean(value) => {
                    EnvironmentValue::Literal(ProtectedString::sensitive(value.to_string()))
                }
                ComposeScalar::Number(value) | ComposeScalar::String(value) => {
                    if self.source.interpolation_applied() {
                        inspected_literal = true;
                        EnvironmentValue::Literal(ProtectedString::sensitive(value.clone()))
                    } else if value.contains('$')
                        && self.eligible_authored_environment(
                            service_subject,
                            entry.name().value(),
                            entry.value().effective_source(),
                        )
                    {
                        self.report_unresolved_variable(
                            &subject,
                            value,
                            "environment value contains unresolved Compose variable syntax",
                        );
                        self.identifier_optional(&subject, "compose", entry.value().effective_source())
                            .map_or(EnvironmentValue::Required, |source_format| {
                                EnvironmentValue::UnresolvedSource {
                                    source_format,
                                    expression: ProtectedString::sensitive(value.clone()),
                                }
                            })
                    } else {
                        if value.contains('$') {
                            self.unsupported_optional(&subject, "dollar syntax in single-quoted or block environment scalar is excluded from deferral; use eligible authored syntax or conversion-time resolution", entry.value().effective_source());
                        }
                        EnvironmentValue::Literal(ProtectedString::sensitive(value.clone()))
                    }
                }
            };
            let mut mapped = self.sourced_provenance(EnvironmentVariable::new(name, value), entry.value().provenance());
            if inspected_literal && let Some(origin) = mapped.origins().first() {
                mapped.add_origin(Provenance::conversion_decision(origin.source_id().clone()));
            }
            service.add_environment(mapped);
            self.exact_provenance(subject, entry.value().provenance());
        }
    }

    fn map_service_environment(&mut self, service_subject: &str, native: &ProjectService, service: &mut Service) {
        if let Some(environment) = native.environment() {
            self.map_environment(service_subject, environment.value(), service);
        }
        if let Some(environment_files) = native.environment_files() {
            self.map_environment_files(service_subject, environment_files, service);
        }
    }

    fn map_environment_files(
        &mut self,
        service_subject: &str,
        environment_files: &ProjectValue<Vec<ProjectValue<ProjectEnvironmentFile>>>,
        service: &mut Service,
    ) {
        for (index, native) in environment_files.value().iter().enumerate() {
            let subject = format!("{service_subject}.env_file[{index}]");
            let environment_file = match native.value() {
                ProjectEnvironmentFile::Short(path) => match NeutralEnvironmentFile::new(
                    Self::protected(path, native.is_sensitive()),
                    EnvironmentFileSyntax::Short,
                ) {
                    Ok(value) => value,
                    Err(error) => {
                        self.invalid_model_optional(&subject, &error, native.effective_source());
                        continue;
                    }
                },
                ProjectEnvironmentFile::Long(long) => {
                    let Some(path) = long.path() else {
                        self.invalid_value_optional(
                            &subject,
                            "long-syntax environment file has no path",
                            native.effective_source(),
                        );
                        continue;
                    };
                    let mut value = match NeutralEnvironmentFile::new(
                        Self::protected(path.value(), path.is_sensitive()),
                        EnvironmentFileSyntax::Long,
                    ) {
                        Ok(value) => value,
                        Err(error) => {
                            self.invalid_model_optional(&subject, &error, path.effective_source());
                            continue;
                        }
                    };
                    if let Some(required) = long.required() {
                        match required.value() {
                            BooleanValue::Literal(required_value) => {
                                value.set_required(self.sourced_provenance(*required_value, required.provenance()));
                                self.exact_provenance(format!("{subject}.required"), required.provenance());
                            }
                            BooleanValue::Expression(_) => {
                                self.invalid_value_optional(
                                    &format!("{subject}.required"),
                                    "environment-file required expression was not resolved",
                                    required.effective_source(),
                                );
                                continue;
                            }
                        }
                    }
                    if let Some(format) = long.format() {
                        match format.value().kind() {
                            EnvironmentFileFormatKind::Raw => {
                                value.set_format(
                                    self.sourced_provenance(NeutralEnvironmentFileFormat::Raw, format.provenance()),
                                );
                                self.exact_provenance(format!("{subject}.format"), format.provenance());
                            }
                            EnvironmentFileFormatKind::Expression => {
                                self.invalid_value_optional(
                                    &format!("{subject}.format"),
                                    "environment-file format expression was not resolved",
                                    format.effective_source(),
                                );
                                continue;
                            }
                            EnvironmentFileFormatKind::Other => {
                                self.invalid_value_optional(
                                    &format!("{subject}.format"),
                                    "environment-file format is not supported by Compose",
                                    format.effective_source(),
                                );
                                continue;
                            }
                            _ => {
                                self.invalid_value_optional(
                                    &format!("{subject}.format"),
                                    "environment-file format is newer than this BoxFerry adapter",
                                    format.effective_source(),
                                );
                                continue;
                            }
                        }
                    }
                    self.report_project_fields(&subject, "environment-file option", long.unmodeled_fields());
                    value
                }
            };
            let sourced = self.sourced_provenance(environment_file, native.provenance());
            self.exact_origins(subject, sourced.origins());
            service.add_environment_file(sourced);
        }
    }

    fn map_labels(&mut self, service_subject: &str, labels: &ProjectLabels, service: &mut Service) {
        for (index, entry) in labels.entries().iter().enumerate() {
            if entry.name().is_sensitive() {
                self.unsupported_optional(
                    &format!("{service_subject}.labels[{index}]"),
                    "interpolated sensitive label names cannot be represented safely in the neutral model",
                    entry.name().effective_source(),
                );
                continue;
            }
            let subject = format!("{service_subject}.labels.{}", entry.name().value());
            let Some(name) = self.identifier_optional(&subject, entry.name().value(), entry.name().effective_source())
            else {
                continue;
            };
            let value = match entry.value().value() {
                ComposeScalar::Null => String::new(),
                ComposeScalar::Boolean(value) => value.to_string(),
                ComposeScalar::Number(value) | ComposeScalar::String(value) => value.clone(),
            };
            let label = MetadataLabel::new(name, Self::protected(&value, entry.value().is_sensitive()));
            let label = self.sourced_metadata_label(label, entry.name().sources(), entry.value().provenance());
            self.exact_origins(subject, label.origins());
            service.add_label(label);
        }
    }

    fn map_port(&mut self, subject: &str, port: &ComposePort) -> Option<Port> {
        match port {
            ComposePort::Short(value) => self.map_short_port(subject, value),
            ComposePort::Long(value) => self.map_long_port(subject, value),
        }
    }

    fn map_short_port(&mut self, subject: &str, port: &ShortPort) -> Option<Port> {
        let target = self.port_number(subject, "target", port.target(), port.raw().span())?;
        let published = match port.published() {
            Some(value) => Some(self.port_number(subject, "published", value, port.raw().span())?),
            None => None,
        };
        let protocol = map_protocol(port.protocol());
        match Port::new(target, published, port.host_ip().map(str::to_owned), protocol) {
            Ok(value) => Some(value),
            Err(error) => {
                self.invalid_model(subject, &error, port.raw().span());
                None
            }
        }
    }

    fn map_long_port(&mut self, subject: &str, port: &LongPort) -> Option<Port> {
        let Some(target) = port.target() else {
            self.invalid_value(subject, "long-syntax port has no target", port.span());
            return None;
        };
        let target = self.port_number(subject, "target", target.value(), target.span())?;
        let published = match port.published() {
            Some(value) => Some(self.port_number(subject, "published", value.value(), value.span())?),
            None => None,
        };
        if port.app_protocol().is_some() {
            self.unsupported(subject, "ports.app_protocol", port.span());
        }
        if port.mode().is_some() {
            self.unsupported(subject, "ports.mode", port.span());
        }
        if port.name().is_some() {
            self.unsupported(subject, "ports.name", port.span());
        }
        self.report_fields(subject, "port extension", port.extension_fields());
        self.report_fields(subject, "unknown port field", port.unknown_fields());

        match Port::new(
            target,
            published,
            port.host_ip().map(|value| value.value().clone()),
            map_protocol(port.protocol().map(|value| value.value().as_str())),
        ) {
            Ok(value) => Some(value),
            Err(error) => {
                self.invalid_model(subject, &error, port.span());
                None
            }
        }
    }

    fn port_number(&mut self, subject: &str, field: &str, value: &str, span: ComposeSpan) -> Option<u16> {
        match value.parse::<u16>() {
            Ok(0) => {
                self.invalid_value(subject, &format!("{field} port must not be zero"), span);
                None
            }
            Ok(value) => Some(value),
            Err(_) => {
                self.unsupported(subject, &format!("non-single {field} port `{value}`"), span);
                None
            }
        }
    }

    fn map_mount(&mut self, subject: &str, mount: &VolumeMount) -> Option<Mount> {
        match mount {
            VolumeMount::Short(value) => self.map_short_mount(subject, value),
            VolumeMount::Long(value) => self.map_long_mount(subject, value),
        }
    }

    fn map_short_mount(&mut self, subject: &str, mount: &ShortVolumeMount) -> Option<Mount> {
        let Some(target) = mount.target() else {
            self.invalid_value(subject, "short-syntax volume has no target", mount.raw().span());
            return None;
        };
        let source = match mount.source() {
            None => MountSource::Anonymous,
            Some(value) if is_host_path(value) => MountSource::HostPath(value.to_owned()),
            Some(value) if value.contains('$') => {
                self.unresolved_volume_variable(subject, value, mount.raw().span());
                return None;
            }
            Some(value) => MountSource::Volume(self.identifier(subject, value, mount.raw().span())?),
        };
        let mut read_only = false;
        let mut relabel = None;
        for option in mount.options() {
            match option.as_str() {
                "" | "rw" => {}
                "ro" => read_only = true,
                "z" => relabel = Some(SelinuxRelabel::Shared),
                "Z" => relabel = Some(SelinuxRelabel::Private),
                value => self.unsupported(subject, &format!("volume option `{value}`"), mount.raw().span()),
            }
        }
        let mut value = match Mount::new(source, target, read_only) {
            Ok(value) => value,
            Err(error) => {
                self.invalid_model(subject, &error, mount.raw().span());
                return None;
            }
        };
        if let Some(relabel) = relabel {
            value.set_selinux_relabel(relabel);
        }
        Some(value)
    }

    fn map_long_mount(&mut self, subject: &str, mount: &LongVolumeMount) -> Option<Mount> {
        let Some(mount_type) = mount.mount_type() else {
            self.invalid_value(subject, "long-syntax volume has no type", mount.span());
            return None;
        };
        let Some(target) = mount.target() else {
            self.invalid_value(subject, "long-syntax volume has no target", mount.span());
            return None;
        };
        let source = match mount_type.value() {
            MountType::Volume => match mount.source() {
                Some(value) => MountSource::Volume(self.identifier(subject, value.value(), value.span())?),
                None => MountSource::Anonymous,
            },
            MountType::Bind => {
                let Some(value) = mount.source() else {
                    self.invalid_value(subject, "long-syntax bind mount has no source", mount.span());
                    return None;
                };
                MountSource::HostPath(value.value().clone())
            }
            other => {
                self.unsupported(subject, &format!("mount type `{other:?}`"), mount.span());
                return None;
            }
        };
        let read_only = match mount.read_only().map(compose_lens::model::Located::value) {
            None | Some(BooleanValue::Literal(false)) => false,
            Some(BooleanValue::Literal(true)) => true,
            Some(BooleanValue::Expression(_)) => {
                self.invalid_value(subject, "read_only expression was not resolved", mount.span());
                return None;
            }
        };
        let mut value = match Mount::new(source, target.value(), read_only) {
            Ok(value) => value,
            Err(error) => {
                self.invalid_model(subject, &error, mount.span());
                return None;
            }
        };
        if let Some(bind) = mount.bind() {
            if bind.propagation().is_some() {
                self.unsupported(subject, "bind.propagation", bind.span());
            }
            if bind.create_host_path().is_some() {
                self.unsupported(subject, "bind.create_host_path", bind.span());
            }
            if let Some(relabel) = bind.selinux() {
                value.set_selinux_relabel(match relabel.value() {
                    ComposeSelinuxRelabel::Shared => SelinuxRelabel::Shared,
                    ComposeSelinuxRelabel::Private => SelinuxRelabel::Private,
                });
            }
            self.report_fields(subject, "bind extension", bind.extension_fields());
            self.report_fields(subject, "unknown bind field", bind.unknown_fields());
        }
        self.report_fields(subject, "volume extension", mount.extension_fields());
        self.report_fields(subject, "unknown volume field", mount.unknown_fields());
        Some(value)
    }

    fn map_service_networks(
        &mut self,
        service_subject: &str,
        service_name: &str,
        networks: &ServiceNetworks,
        provenance: &MergeProvenance,
        service: &mut Service,
    ) {
        match networks {
            ServiceNetworks::Short { names, .. } => {
                for name in names {
                    let subject = format!("{service_subject}.networks.{}", name.value());
                    let Some(identifier) = self.identifier(&subject, name.value(), name.span()) else {
                        continue;
                    };
                    service.add_network(
                        self.sourced_provenance(NetworkAttachment::new(identifier, Vec::new()), provenance),
                    );
                    self.exact_provenance(subject, provenance);
                }
            }
            ServiceNetworks::Long { networks, .. } => {
                for network in networks {
                    self.map_service_network(service_subject, service_name, network, provenance, service);
                }
            }
        }
    }

    fn map_service_network(
        &mut self,
        service_subject: &str,
        service_name: &str,
        network: &ServiceNetwork,
        provenance: &MergeProvenance,
        service: &mut Service,
    ) {
        let subject = format!("{service_subject}.networks.{}", network.name().value());
        let Some(identifier) = self.identifier(&subject, network.name().value(), network.name().span()) else {
            return;
        };
        let sensitivities = corroborated_alias_sensitivities(self.source.project(), service_name, network)
            .unwrap_or_else(|| vec![true; network.aliases().len()]);
        let aliases = network
            .aliases()
            .iter()
            .zip(sensitivities)
            .map(|(alias, sensitive)| self.sourced_spans(Self::protected(alias.value(), sensitive), &[alias.span()]))
            .collect();
        let mut attachment = NetworkAttachment::new(identifier, aliases);
        if let Some(address) = network.ipv4_address() {
            attachment.set_ipv4_address(self.sourced_spans(Self::protected(address.value(), true), &[address.span()]));
        }
        if let Some(address) = network.ipv6_address() {
            attachment.set_ipv6_address(self.sourced_spans(Self::protected(address.value(), true), &[address.span()]));
        }
        service.add_network(self.sourced_provenance(attachment, provenance));

        if network.interface_name().is_some() {
            self.unsupported(&subject, "networks.interface_name", network.span());
        }
        if !network.link_local_ips().is_empty() {
            self.unsupported(&subject, "networks.link_local_ips", network.span());
        }
        if network.mac_address().is_some() {
            self.unsupported(&subject, "networks.mac_address", network.span());
        }
        if !network.driver_opts().is_empty() {
            self.unsupported(&subject, "networks.driver_opts", network.span());
        }
        if network.gw_priority().is_some() {
            self.unsupported(&subject, "networks.gw_priority", network.span());
        }
        if network.priority().is_some() {
            self.unsupported(&subject, "networks.priority", network.span());
        }
        self.report_fields(&subject, "network attachment extension", network.extension_fields());
        self.report_fields(&subject, "unknown network attachment field", network.unknown_fields());
        self.exact_provenance(subject, provenance);
    }

    fn map_volume_definition(&mut self, resource: &ProjectResource<VolumeDefinition>) -> Option<Sourced<Volume>> {
        let native = resource.definition().value();
        let subject = format!("volumes.{}", resource.name().value());
        if self.reject_obsolete_external_name_mapping(&subject, native.external()) {
            return None;
        }
        let name = self.identifier_optional(&subject, resource.name().value(), resource.name().effective_source())?;
        let ownership = self.resource_ownership(&subject, native.external(), native.span());
        let definition_sensitive = resource.definition().is_sensitive();
        let external = ownership == ResourceOwnership::External;
        let mut volume = Volume::new(name, ownership);

        if let Some(runtime_name) = native.custom_name() {
            if runtime_name.value().contains('$') {
                self.invalid_value(
                    &format!("{subject}.name"),
                    "volume name expression was not resolved",
                    runtime_name.span(),
                );
            } else {
                volume.set_runtime_name(self.sourced_spans(
                    Self::protected(runtime_name.value(), definition_sensitive),
                    &[runtime_name.span()],
                ));
                self.exact_spans(format!("{subject}.name"), &[runtime_name.span()]);
            }
        }

        if external {
            for (field, present) in [
                ("driver", native.driver().is_some()),
                // ComposeLens exposes this as a vector, so an empty vector cannot distinguish
                // omission from an explicit empty mapping. Do not manufacture a reset.
                ("driver_opts", !native.driver_opts().is_empty()),
                ("labels", native.labels().is_some()),
            ] {
                if present {
                    self.unsupported(
                        &format!("{subject}.{field}"),
                        "Compose external volumes may only declare their platform name",
                        native.span(),
                    );
                }
            }
        } else {
            let local_driver = match native.driver() {
                Some(driver) if driver.value().contains('$') => {
                    self.invalid_value(
                        &format!("{subject}.driver"),
                        "volume driver expression was not resolved",
                        driver.span(),
                    );
                    false
                }
                Some(driver) => {
                    volume.set_driver(
                        self.sourced_spans(Self::protected(driver.value(), definition_sensitive), &[driver.span()]),
                    );
                    self.exact_spans(format!("{subject}.driver"), &[driver.span()]);
                    driver.value() == "local"
                }
                None => false,
            };

            if !native.driver_opts().is_empty() {
                if local_driver {
                    self.map_local_volume_driver_options(
                        &mut volume,
                        &subject,
                        native.driver_opts(),
                        resource.definition().provenance(),
                        definition_sensitive,
                    );
                } else {
                    self.unsupported(
                        &format!("{subject}.driver_opts"),
                        "Compose local-driver options require an explicit `driver: local`",
                        native.span(),
                    );
                }
            }
            if let Some(labels) = native.labels() {
                self.map_volume_labels(
                    &mut volume,
                    &subject,
                    labels,
                    resource.definition().provenance(),
                    definition_sensitive,
                );
            }
        }
        self.report_fields(&subject, "volume definition extension", native.extension_fields());
        self.report_fields(&subject, "unknown volume definition field", native.unknown_fields());
        self.exact_provenance(&subject, resource.definition().provenance());
        Some(self.sourced_provenance(volume, resource.definition().provenance()))
    }

    fn map_local_volume_driver_options(
        &mut self,
        volume: &mut Volume,
        subject: &str,
        options: &[compose_lens::model::KeyValueEntry],
        provenance: &MergeProvenance,
        definition_sensitive: bool,
    ) {
        let mut seen = BTreeSet::new();
        let mut exact = true;
        for (index, option) in options.iter().enumerate() {
            let option_subject = format!("{subject}.driver_opts[{index}]");
            let key = option.key().value();
            let value = match option.value().value() {
                ComposeScalar::String(value) | ComposeScalar::Number(value) if !value.is_empty() => value,
                _ => {
                    self.invalid_value(
                        &option_subject,
                        "local volume driver options require non-empty string or number values",
                        option.span(),
                    );
                    exact = false;
                    continue;
                }
            };
            if key.contains('$') || value.contains('$') {
                self.invalid_value(
                    &option_subject,
                    "local volume driver-option expression was not resolved",
                    option.span(),
                );
                exact = false;
                continue;
            }
            if !seen.insert(key) {
                self.invalid_value(
                    &option_subject,
                    "local volume driver option is duplicated",
                    option.span(),
                );
                exact = false;
                continue;
            }
            let value = self.sourced_spans(Self::protected(value, definition_sensitive), &[option.value().span()]);
            match key.as_str() {
                "type" => volume.set_volume_type(value),
                "device" => volume.set_device(value),
                "o" => volume.set_options(value),
                _ => {
                    self.unsupported(
                        &option_subject,
                        "only local volume driver options `type`, `device`, and `o` are modeled",
                        option.span(),
                    );
                    exact = false;
                }
            }
        }
        if exact {
            self.exact_provenance(format!("{subject}.driver_opts"), provenance);
        }
    }

    fn map_volume_labels(
        &mut self,
        volume: &mut Volume,
        subject: &str,
        labels: &Labels,
        provenance: &MergeProvenance,
        definition_sensitive: bool,
    ) {
        let mut mapped = Vec::new();
        let mut exact = true;
        match labels {
            Labels::Map { entries, .. } => {
                for (index, entry) in entries.iter().enumerate() {
                    let entry_subject = format!("{subject}.labels[{index}]");
                    let value = Self::compose_scalar(entry.value().value());
                    if entry.key().value().contains('$') || value.contains('$') {
                        self.invalid_value(&entry_subject, "volume label expression was not resolved", entry.span());
                        exact = false;
                        continue;
                    }
                    let Some(name) =
                        self.identifier_optional(&entry_subject, entry.key().value(), Some(entry.key().span()))
                    else {
                        exact = false;
                        continue;
                    };
                    mapped.push(self.sourced_spans(
                        MetadataLabel::new(name, Self::protected(&value, definition_sensitive)),
                        &[entry.key().span(), entry.value().span()],
                    ));
                }
            }
            Labels::List { values, .. } => {
                for (index, value) in values.iter().enumerate() {
                    let entry_subject = format!("{subject}.labels[{index}]");
                    let Some((name, label_value)) = literal_assignment(value.value()) else {
                        self.invalid_value(
                            &entry_subject,
                            "volume label list entries must use unambiguous name=value spelling",
                            value.span(),
                        );
                        exact = false;
                        continue;
                    };
                    if value.value().contains('$') {
                        self.invalid_value(&entry_subject, "volume label expression was not resolved", value.span());
                        exact = false;
                        continue;
                    }
                    let Some(name) = self.identifier_optional(&entry_subject, name, Some(value.span())) else {
                        exact = false;
                        continue;
                    };
                    mapped.push(self.sourced_spans(
                        MetadataLabel::new(name, Self::protected(label_value, definition_sensitive)),
                        &[value.span()],
                    ));
                }
            }
        }
        volume.set_labels_with_origins(mapped, self.origins(provenance));
        if exact {
            self.exact_provenance(format!("{subject}.labels"), provenance);
        }
    }

    #[allow(clippy::too_many_lines)]
    fn map_network_definition(&mut self, resource: &ProjectResource<NetworkDefinition>) -> Option<Sourced<Network>> {
        let native = resource.definition().value();
        let subject = format!("networks.{}", resource.name().value());
        if self.reject_obsolete_external_name_mapping(&subject, native.external()) {
            return None;
        }
        let name = self.identifier_optional(&subject, resource.name().value(), resource.name().effective_source())?;
        let ownership = self.resource_ownership(&subject, native.external(), native.span());
        let definition_sensitive = resource.definition().is_sensitive();
        let external = ownership == ResourceOwnership::External;
        let mut network = Network::new(name, ownership);

        if let Some(runtime_name) = native.custom_name() {
            if runtime_name.value().contains('$') {
                self.invalid_value(
                    &format!("{subject}.name"),
                    "network name expression was not resolved",
                    runtime_name.span(),
                );
            } else {
                network.set_runtime_name(self.sourced_spans(
                    Self::protected(runtime_name.value(), definition_sensitive),
                    &[runtime_name.span()],
                ));
                self.exact_spans(format!("{subject}.name"), &[runtime_name.span()]);
            }
        }

        if external {
            for (field, present) in [
                ("driver", native.driver().is_some()),
                ("driver_opts", !native.driver_opts().is_empty()),
                ("attachable", native.attachable().is_some()),
                ("enable_ipv4", native.enable_ipv4().is_some()),
                ("enable_ipv6", native.enable_ipv6().is_some()),
                ("internal", native.internal().is_some()),
                ("ipam", native.ipam().is_some()),
                ("labels", native.labels().is_some()),
            ] {
                if present {
                    self.unsupported(
                        &format!("{subject}.{field}"),
                        "Compose external networks may only declare their platform name",
                        native.span(),
                    );
                }
            }
        } else {
            if let Some(driver) = native.driver() {
                if driver.value().contains('$') {
                    self.invalid_value(
                        &format!("{subject}.driver"),
                        "network driver expression was not resolved",
                        driver.span(),
                    );
                } else {
                    network.set_driver(
                        self.sourced_spans(Self::protected(driver.value(), definition_sensitive), &[driver.span()]),
                    );
                    self.exact_spans(format!("{subject}.driver"), &[driver.span()]);
                }
            }

            if !native.driver_opts().is_empty() {
                let mut options = Vec::with_capacity(native.driver_opts().len());
                let mut exact = true;
                for (index, option) in native.driver_opts().iter().enumerate() {
                    let option_subject = format!("{subject}.driver_opts[{index}]");
                    let value = Self::compose_scalar(option.value().value());
                    if option.key().value().contains('$') || value.contains('$') {
                        self.invalid_value(
                            &option_subject,
                            "network driver-option expression was not resolved",
                            option.span(),
                        );
                        exact = false;
                        continue;
                    }
                    let Some(option_name) =
                        self.identifier_optional(&option_subject, option.key().value(), Some(option.key().span()))
                    else {
                        exact = false;
                        continue;
                    };
                    let option_span = option.span();
                    match NetworkDriverOption::new(
                        self.sourced_spans(option_name, &[option.key().span()]),
                        self.sourced_spans(Self::protected(&value, definition_sensitive), &[option.value().span()]),
                    ) {
                        Ok(option) => options.push(self.sourced_spans(option, &[option_span])),
                        Err(error) => {
                            self.invalid_model(&option_subject, &error, option.span());
                            exact = false;
                        }
                    }
                }
                network.set_driver_options_with_origins(options, self.origins(resource.definition().provenance()));
                if exact {
                    self.exact_provenance(format!("{subject}.driver_opts"), resource.definition().provenance());
                }
            }

            if native.attachable().is_some() {
                self.unsupported(&format!("{subject}.attachable"), "network.attachable", native.span());
            }
            if native.enable_ipv4().is_some() {
                self.unsupported(&format!("{subject}.enable_ipv4"), "network.enable_ipv4", native.span());
            }
            self.map_network_boolean(
                &mut network,
                &subject,
                "enable_ipv6",
                native.enable_ipv6(),
                Network::set_ipv6,
            );
            self.map_network_boolean(
                &mut network,
                &subject,
                "internal",
                native.internal(),
                Network::set_internal,
            );

            if let Some(ipam) = native.ipam() {
                if let Some(driver) = ipam.driver() {
                    if driver.value().contains('$') {
                        self.invalid_value(
                            &format!("{subject}.ipam.driver"),
                            "IPAM driver expression was not resolved",
                            driver.span(),
                        );
                    } else {
                        network.set_ipam_driver(
                            self.sourced_spans(Self::protected(driver.value(), definition_sensitive), &[driver.span()]),
                        );
                        self.exact_spans(format!("{subject}.ipam.driver"), &[driver.span()]);
                    }
                }
                if !ipam.options().is_empty() {
                    self.unsupported(&format!("{subject}.ipam.options"), "network.ipam.options", ipam.span());
                }
                if !ipam.config().is_empty() {
                    let mut configs = Vec::with_capacity(ipam.config().len());
                    let mut exact = true;
                    for (index, config) in ipam.config().iter().enumerate() {
                        let config_subject = format!("{subject}.ipam.config[{index}]");
                        let Some(subnet) = config.subnet() else {
                            self.invalid_value(&config_subject, "IPAM configuration requires a subnet", config.span());
                            exact = false;
                            continue;
                        };
                        if subnet.value().contains('$')
                            || config.gateway().is_some_and(|value| value.value().contains('$'))
                            || config.ip_range().is_some_and(|value| value.value().contains('$'))
                        {
                            self.invalid_value(&config_subject, "IPAM expression was not resolved", config.span());
                            exact = false;
                            continue;
                        }
                        let mut mapped = match NetworkIpamConfig::new(
                            self.sourced_spans(Self::protected(subnet.value(), definition_sensitive), &[subnet.span()]),
                        ) {
                            Ok(value) => value,
                            Err(error) => {
                                self.invalid_model(&config_subject, &error, subnet.span());
                                exact = false;
                                continue;
                            }
                        };
                        if let Some(gateway) = config.gateway()
                            && let Err(error) = mapped.set_gateway(self.sourced_spans(
                                Self::protected(gateway.value(), definition_sensitive),
                                &[gateway.span()],
                            ))
                        {
                            self.invalid_model(&config_subject, &error, gateway.span());
                            exact = false;
                            continue;
                        }
                        if let Some(ip_range) = config.ip_range()
                            && let Err(error) = mapped.set_ip_range(self.sourced_spans(
                                Self::protected(ip_range.value(), definition_sensitive),
                                &[ip_range.span()],
                            ))
                        {
                            self.invalid_model(&config_subject, &error, ip_range.span());
                            exact = false;
                            continue;
                        }
                        if !config.aux_addresses().is_empty() {
                            self.unsupported(
                                &format!("{config_subject}.aux_addresses"),
                                "network.ipam.config.aux_addresses",
                                config.span(),
                            );
                            exact = false;
                        }
                        self.report_fields(
                            &config_subject,
                            "IPAM configuration extension",
                            config.extension_fields(),
                        );
                        self.report_fields(
                            &config_subject,
                            "unknown IPAM configuration field",
                            config.unknown_fields(),
                        );
                        configs.push(self.sourced_spans(mapped, &[config.span()]));
                    }
                    network.set_ipam_configs_with_origins(configs, self.origins(resource.definition().provenance()));
                    if exact {
                        self.exact_provenance(format!("{subject}.ipam.config"), resource.definition().provenance());
                    }
                }
                self.report_fields(&format!("{subject}.ipam"), "IPAM extension", ipam.extension_fields());
                self.report_fields(&format!("{subject}.ipam"), "unknown IPAM field", ipam.unknown_fields());
            }

            if let Some(labels) = native.labels() {
                self.map_network_labels(
                    &mut network,
                    &subject,
                    labels,
                    resource.definition().provenance(),
                    definition_sensitive,
                );
            }
        }
        self.report_fields(&subject, "network definition extension", native.extension_fields());
        self.report_fields(&subject, "unknown network definition field", native.unknown_fields());
        self.exact_provenance(&subject, resource.definition().provenance());
        Some(self.sourced_provenance(network, resource.definition().provenance()))
    }

    fn map_network_boolean(
        &mut self,
        network: &mut Network,
        subject: &str,
        field: &str,
        value: Option<&compose_lens::model::Located<BooleanValue>>,
        setter: fn(&mut Network, Sourced<bool>),
    ) {
        let Some(value) = value else { return };
        match value.value() {
            BooleanValue::Literal(literal) => {
                setter(network, self.sourced_spans(*literal, &[value.span()]));
                self.exact_spans(format!("{subject}.{field}"), &[value.span()]);
            }
            BooleanValue::Expression(_) => self.invalid_value(
                &format!("{subject}.{field}"),
                "network boolean expression was not resolved",
                value.span(),
            ),
        }
    }

    fn map_network_labels(
        &mut self,
        network: &mut Network,
        subject: &str,
        labels: &Labels,
        provenance: &MergeProvenance,
        definition_sensitive: bool,
    ) {
        let mut mapped = Vec::new();
        let mut exact = true;
        match labels {
            Labels::Map { entries, .. } => {
                for (index, entry) in entries.iter().enumerate() {
                    let entry_subject = format!("{subject}.labels[{index}]");
                    let value = Self::compose_scalar(entry.value().value());
                    if entry.key().value().contains('$') || value.contains('$') {
                        self.invalid_value(
                            &entry_subject,
                            "network label expression was not resolved",
                            entry.span(),
                        );
                        exact = false;
                        continue;
                    }
                    let Some(name) =
                        self.identifier_optional(&entry_subject, entry.key().value(), Some(entry.key().span()))
                    else {
                        exact = false;
                        continue;
                    };
                    let label = MetadataLabel::new(name, Self::protected(&value, definition_sensitive));
                    mapped.push(self.sourced_spans(label, &[entry.key().span(), entry.value().span()]));
                }
            }
            Labels::List { values, .. } => {
                for (index, value) in values.iter().enumerate() {
                    let entry_subject = format!("{subject}.labels[{index}]");
                    let Some((name, label_value)) = literal_assignment(value.value()) else {
                        self.invalid_value(
                            &entry_subject,
                            "network label list entries must use unambiguous name=value spelling",
                            value.span(),
                        );
                        exact = false;
                        continue;
                    };
                    if value.value().contains('$') {
                        self.invalid_value(
                            &entry_subject,
                            "network label expression was not resolved",
                            value.span(),
                        );
                        exact = false;
                        continue;
                    }
                    let Some(name) = self.identifier_optional(&entry_subject, name, Some(value.span())) else {
                        exact = false;
                        continue;
                    };
                    mapped.push(self.sourced_spans(
                        MetadataLabel::new(name, Self::protected(label_value, definition_sensitive)),
                        &[value.span()],
                    ));
                }
            }
        }
        network.set_labels_with_origins(mapped, self.origins(provenance));
        if exact {
            self.exact_provenance(format!("{subject}.labels"), provenance);
        }
    }

    fn map_config_definition(&mut self, resource: &ProjectResource<ConfigDefinition>) -> Option<Sourced<Config>> {
        let native = resource.definition().value();
        let subject = format!("configs.{}", resource.name().value());
        if self.reject_obsolete_external_name_mapping(&subject, native.external()) {
            return None;
        }
        let name = self.identifier_optional(&subject, resource.name().value(), resource.name().effective_source())?;
        let ownership = self.resource_ownership(&subject, native.external(), native.span());
        let mut config = Config::new(name, ownership);

        if let Some(runtime_name) = native.custom_name() {
            if runtime_name.value().contains('$') {
                self.invalid_value(
                    &format!("{subject}.name"),
                    "config name expression was not resolved",
                    runtime_name.span(),
                );
            } else {
                config.set_runtime_name(self.sourced_spans(
                    Self::protected(runtime_name.value(), resource.definition().is_sensitive()),
                    &[runtime_name.span()],
                ));
                self.exact_spans(format!("{subject}.runtime_name"), &[runtime_name.span()]);
            }
        }

        let materials = [
            native.file().map(|value| {
                (
                    ConfigMaterial::File(Self::protected(value.value(), resource.definition().is_sensitive())),
                    value.span(),
                )
            }),
            native.environment().map(|value| {
                (
                    ConfigMaterial::Environment(Self::protected(value.value(), resource.definition().is_sensitive())),
                    value.span(),
                )
            }),
            native.content().map(|value| {
                (
                    ConfigMaterial::Content(Self::protected(value.value(), resource.definition().is_sensitive())),
                    value.span(),
                )
            }),
        ]
        .into_iter()
        .flatten()
        .collect::<Vec<_>>();
        self.map_config_material(&subject, ownership, &materials, &mut config, resource.definition());
        if let Some(labels) = native.labels() {
            self.unsupported(
                &format!("{subject}.labels"),
                "config metadata labels have no reviewed neutral-model mapping",
                labels.span(),
            );
        }
        if let Some(template_driver) = native.template_driver() {
            self.unsupported(
                &format!("{subject}.template_driver"),
                "config template driver has no reviewed neutral-model mapping",
                template_driver.span(),
            );
        }

        self.report_fields(&subject, "config definition extension", native.extension_fields());
        self.report_fields(&subject, "unknown config definition field", native.unknown_fields());
        self.exact_provenance(&subject, resource.definition().provenance());
        Some(self.sourced_provenance(config, resource.definition().provenance()))
    }

    fn map_config_material(
        &mut self,
        subject: &str,
        ownership: ResourceOwnership,
        materials: &[(ConfigMaterial, ComposeSpan)],
        config: &mut Config,
        definition: &ProjectValue<ConfigDefinition>,
    ) {
        match materials {
            [(material, span)] => {
                config.set_material(self.sourced_spans(material.clone(), &[*span]));
                self.exact_spans(format!("{subject}.material"), &[*span]);
                if ownership == ResourceOwnership::External {
                    self.invalid_value_optional(
                        subject,
                        "external config cannot also declare application-managed material",
                        Some(*span),
                    );
                }
            }
            [] if ownership != ResourceOwnership::External => self.invalid_value_optional(
                subject,
                "application-managed config requires exactly one of file, environment, or content",
                definition.effective_source(),
            ),
            [] => {}
            _ => self.invalid_value_optional(
                subject,
                "config declares multiple material sources; exactly one of file, environment, or content is allowed",
                definition.effective_source(),
            ),
        }
    }

    fn map_secret_definition(&mut self, resource: &ProjectResource<SecretDefinition>) -> Option<Sourced<Secret>> {
        let native = resource.definition().value();
        let subject = format!("secrets.{}", resource.name().value());
        if self.reject_obsolete_external_name_mapping(&subject, native.external()) {
            return None;
        }
        let name = self.identifier_optional(&subject, resource.name().value(), resource.name().effective_source())?;
        let ownership = self.resource_ownership(&subject, native.external(), native.span());
        let mut secret = Secret::new(name, ownership);

        if let Some(runtime_name) = native.custom_name() {
            if runtime_name.value().contains('$') {
                self.invalid_value(
                    &format!("{subject}.name"),
                    "secret name expression was not resolved",
                    runtime_name.span(),
                );
            } else {
                secret.set_runtime_name(self.sourced_spans(
                    Self::protected(runtime_name.value(), resource.definition().is_sensitive()),
                    &[runtime_name.span()],
                ));
                self.exact_spans(format!("{subject}.runtime_name"), &[runtime_name.span()]);
            }
        }

        let materials = [
            native.file().map(|value| {
                (
                    SecretMaterial::File(Self::protected(value.value(), resource.definition().is_sensitive())),
                    value.span(),
                )
            }),
            native.environment().map(|value| {
                (
                    SecretMaterial::Environment(Self::protected(value.value(), resource.definition().is_sensitive())),
                    value.span(),
                )
            }),
        ]
        .into_iter()
        .flatten()
        .collect::<Vec<_>>();
        self.map_secret_material(&subject, ownership, &materials, &mut secret, resource.definition());
        if let Some(driver) = native.driver() {
            self.unsupported(
                &format!("{subject}.driver"),
                "secret driver has no reviewed neutral-model mapping",
                driver.span(),
            );
        }
        let driver_option_spans = native
            .driver_opts()
            .iter()
            .map(compose_lens::model::KeyValueEntry::span)
            .collect::<Vec<_>>();
        if !driver_option_spans.is_empty() {
            self.unsupported_spans(
                &format!("{subject}.driver_opts"),
                "secret driver options have no reviewed neutral-model mapping",
                &driver_option_spans,
            );
        }
        if let Some(labels) = native.labels() {
            self.unsupported(
                &format!("{subject}.labels"),
                "secret metadata labels have no reviewed neutral-model mapping",
                labels.span(),
            );
        }
        if let Some(template_driver) = native.template_driver() {
            self.unsupported(
                &format!("{subject}.template_driver"),
                "secret template driver has no reviewed neutral-model mapping",
                template_driver.span(),
            );
        }

        self.report_fields(&subject, "secret definition extension", native.extension_fields());
        self.report_fields(&subject, "unknown secret definition field", native.unknown_fields());
        self.exact_provenance(&subject, resource.definition().provenance());
        Some(self.sourced_provenance(secret, resource.definition().provenance()))
    }

    fn map_secret_material(
        &mut self,
        subject: &str,
        ownership: ResourceOwnership,
        materials: &[(SecretMaterial, ComposeSpan)],
        secret: &mut Secret,
        definition: &ProjectValue<SecretDefinition>,
    ) {
        match materials {
            [(material, span)] => {
                secret.set_material(self.sourced_spans(material.clone(), &[*span]));
                self.exact_spans(format!("{subject}.material"), &[*span]);
                if ownership == ResourceOwnership::External {
                    self.invalid_value_optional(
                        subject,
                        "external secret cannot also declare application-managed material",
                        Some(*span),
                    );
                }
            }
            [] if ownership != ResourceOwnership::External => self.invalid_value_optional(
                subject,
                "application-managed secret requires exactly one of file or environment",
                definition.effective_source(),
            ),
            [] => {}
            _ => self.invalid_value_optional(
                subject,
                "secret declares multiple material sources; exactly one of file or environment is allowed",
                definition.effective_source(),
            ),
        }
    }

    fn map_service_grants(
        &mut self,
        service_subject: &str,
        field: &str,
        grants: &ProjectValue<Vec<ProjectValue<ProjectGrant>>>,
        secret: bool,
        service: &mut Service,
    ) {
        for (index, native) in grants.value().iter().enumerate() {
            let subject = format!("{service_subject}.{field}[{index}]");
            let grant = match native.value() {
                ProjectGrant::Short(source) => ResourceGrant::new(
                    Self::protected(source, native.is_sensitive()),
                    ResourceGrantSyntax::Short,
                ),
                ProjectGrant::Long(long) => {
                    let Some(source) = long.source() else {
                        self.invalid_value_optional(
                            &subject,
                            "long-syntax resource grant requires source",
                            native.effective_source(),
                        );
                        continue;
                    };
                    let mut grant = match ResourceGrant::new(
                        Self::protected(source.value(), source.is_sensitive()),
                        ResourceGrantSyntax::Long,
                    ) {
                        Ok(grant) => grant,
                        Err(error) => {
                            self.invalid_model_optional(&subject, &error, source.effective_source());
                            continue;
                        }
                    };
                    Self::set_grant_field(&mut grant, long.target(), ResourceGrant::set_target, self);
                    Self::set_grant_field(&mut grant, long.uid(), ResourceGrant::set_uid, self);
                    Self::set_grant_field(&mut grant, long.gid(), ResourceGrant::set_gid, self);
                    Self::set_grant_field(&mut grant, long.mode(), ResourceGrant::set_mode, self);
                    self.report_project_fields(&subject, "resource-grant field", long.unmodeled_fields());
                    Ok(grant)
                }
            };
            match grant {
                Ok(grant) => {
                    let grant = self.sourced_provenance(grant, native.provenance());
                    self.exact_origins(&subject, grant.origins());
                    if secret {
                        service.add_secret_grant(grant);
                    } else {
                        service.add_config_grant(grant);
                    }
                }
                Err(error) => self.invalid_model_optional(&subject, &error, native.effective_source()),
            }
        }
    }

    fn set_grant_field(
        grant: &mut ResourceGrant,
        value: Option<&ProjectValue<String>>,
        setter: fn(&mut ResourceGrant, Sourced<ProtectedString>),
        mapping: &Self,
    ) {
        if let Some(value) = value {
            setter(
                grant,
                mapping.sourced_provenance(Self::protected(value.value(), value.is_sensitive()), value.provenance()),
            );
        }
    }

    fn resource_ownership(
        &mut self,
        subject: &str,
        external: Option<&ResourceExternal>,
        span: ComposeSpan,
    ) -> ResourceOwnership {
        match external {
            Some(ResourceExternal::Boolean(value)) if matches!(value.value(), BooleanValue::Literal(true)) => {
                ResourceOwnership::External
            }
            None => ResourceOwnership::Application,
            Some(ResourceExternal::Boolean(value)) if matches!(value.value(), BooleanValue::Literal(false)) => {
                ResourceOwnership::Application
            }
            Some(ResourceExternal::Boolean(_)) => {
                self.invalid_value(subject, "external expression was not resolved", span);
                ResourceOwnership::Application
            }
            Some(ResourceExternal::NameMapping(mapping)) => {
                self.invalid_value(
                    subject,
                    "obsolete `external: {name: ...}` syntax is not accepted; use `external: true` and top-level `name: ...`",
                    mapping.span(),
                );
                ResourceOwnership::Application
            }
            Some(_) => {
                self.invalid_value(
                    subject,
                    "external lifecycle form is not supported by this BoxFerry version",
                    span,
                );
                ResourceOwnership::Application
            }
        }
    }

    fn reject_obsolete_external_name_mapping(&mut self, subject: &str, external: Option<&ResourceExternal>) -> bool {
        let Some(ResourceExternal::NameMapping(mapping)) = external else {
            return false;
        };
        self.invalid_value(
            subject,
            "obsolete `external: {name: ...}` syntax is not accepted; use `external: true` and top-level `name: ...`",
            mapping.span(),
        );
        true
    }

    fn report_service_unsupported(&mut self, subject: &str, service: &ProjectService) {
        macro_rules! report {
            ($field:ident, $name:literal) => {
                self.report_typed_service_value(subject, $name, service.$field());
            };
        }

        // ComposeLens 0.2 promotes these fields out of the generic unmodeled collection. Until
        // BoxFerry has a reviewed neutral contract for each one, retain their effective presence
        // as a policy-controlled outcome instead of silently dropping it.
        report!(domainname, "domainname");
        report!(platform, "platform");
        report!(isolation, "isolation");
        report!(mac_address, "mac_address");
        report!(credential_spec, "credential_spec");
        report!(extends, "extends");
        report!(provider, "provider");
        report!(post_start, "post_start");
        report!(pre_stop, "pre_stop");
        report!(pre_start, "pre_start");
        report!(blkio_config, "blkio_config");
        report!(cgroup, "cgroup");
        report!(cgroup_parent, "cgroup_parent");
        report!(runtime, "runtime");
        report!(pull_refresh_after, "pull_refresh_after");
        report!(attach, "attach");
        report!(stdin_open, "stdin_open");
        report!(tty, "tty");
        report!(privileged, "privileged");
        report!(use_api_socket, "use_api_socket");
        report!(label_files, "label_file");
        report!(external_links, "external_links");
        report!(links, "links");
        report!(storage_opt, "storage_opt");
        report!(models, "models");
        report!(gpus, "gpus");
        report!(develop, "develop");
        report!(deploy, "deploy");
        report!(cpu_count, "cpu_count");
        report!(cpu_percent, "cpu_percent");
        report!(cpu_period, "cpu_period");
        report!(cpu_quota, "cpu_quota");
        report!(cpu_rt_period, "cpu_rt_period");
        report!(cpu_rt_runtime, "cpu_rt_runtime");
        report!(cpu_shares, "cpu_shares");
        report!(cpus, "cpus");
        report!(cpuset, "cpuset");
        report!(device_cgroup_rules, "device_cgroup_rules");
        report!(ipc, "ipc");
        report!(mem_reservation, "mem_reservation");
        report!(mem_swappiness, "mem_swappiness");
        report!(memswap_limit, "memswap_limit");
        report!(network_mode, "network_mode");
        report!(oom_kill_disable, "oom_kill_disable");
        report!(oom_score_adj, "oom_score_adj");
        report!(pid, "pid");
        report!(scale, "scale");
        report!(volumes_from, "volumes_from");
        self.report_volume_mount_options(subject, service);
        for item in service.invalid_device_cgroup_rules() {
            self.unsupported(
                &format!("{subject}.device_cgroup_rules"),
                "invalid device_cgroup_rules item",
                item.span(),
            );
        }
        for item in service.invalid_volumes_from() {
            self.unsupported(
                &format!("{subject}.volumes_from"),
                "invalid volumes_from item",
                item.span(),
            );
        }
        self.report_project_fields(subject, "service field", service.unmodeled_fields());
    }

    fn report_document_unsupported(&mut self, view: &ProjectView) {
        self.report_typed_document_value("application.include", view.include());
        self.report_typed_document_value("application.models", view.models());
        self.report_project_fields("application", "document field", view.unmodeled_fields());
    }

    fn report_typed_service_value<T>(&mut self, service_subject: &str, field: &str, value: Option<&ProjectValue<T>>) {
        if let Some(value) = value {
            self.unsupported_optional(
                &format!("{service_subject}.{field}"),
                &format!("ComposeLens typed `{field}` has no reviewed neutral-model mapping"),
                value.effective_source(),
            );
        }
    }

    fn report_typed_document_value<T>(&mut self, subject: &str, value: Option<&ProjectValue<T>>) {
        if let Some(value) = value {
            self.unsupported_optional(
                subject,
                "ComposeLens typed document field has no reviewed neutral-model mapping",
                value.effective_source(),
            );
        }
    }

    fn report_volume_mount_options(&mut self, service_subject: &str, service: &ProjectService) {
        let Some(options) = service.volume_mount_options() else {
            return;
        };
        let has_unmapped_options = options.value().iter().any(|item| {
            let options = item.value();
            options.consistency().is_some()
                || options.bind().is_some_and(|bind| {
                    bind.recursive().is_some()
                        || !bind.extension_fields().is_empty()
                        || !bind.unknown_fields().is_empty()
                })
                || options.image().is_some_and(|image| {
                    image.subpath().is_some()
                        || !image.extension_fields().is_empty()
                        || !image.unknown_fields().is_empty()
                })
                || options.tmpfs().is_some_and(|tmpfs| {
                    tmpfs.size().is_some()
                        || tmpfs.mode().is_some()
                        || !tmpfs.extension_fields().is_empty()
                        || !tmpfs.unknown_fields().is_empty()
                })
                || options.volume().is_some_and(|volume| {
                    volume.nocopy().is_some()
                        || volume.subpath().is_some()
                        || volume.labels().is_some()
                        || !volume.extension_fields().is_empty()
                        || !volume.unknown_fields().is_empty()
                })
                || !options.unmodeled_fields().is_empty()
        });
        if has_unmapped_options {
            self.report_typed_service_value(service_subject, "volume_mount_options", Some(options));
        }
    }

    fn report_fields(&mut self, subject: &str, kind: &str, fields: &[compose_lens::model::FieldReference]) {
        for field in fields {
            // The merged metadata scan owns supported and unsupported extension scopes.
            if field.name().value().starts_with("x-") {
                continue;
            }
            self.unsupported(subject, &format!("{kind} `{}`", field.name().value()), field.span());
        }
    }

    fn report_project_fields(&mut self, subject: &str, kind: &str, fields: &[ProjectFieldReference]) {
        for field in fields {
            if field.path().last().is_some_and(|key| key.starts_with("x-")) {
                continue;
            }
            let feature = field.path().join(".");
            self.unsupported_optional(
                subject,
                &format!("{kind} `{feature}`"),
                field
                    .provenance()
                    .effective_source()
                    .or_else(|| field.key().effective_source()),
            );
        }
    }

    fn identifier(&mut self, subject: &str, value: &str, span: ComposeSpan) -> Option<Identifier> {
        self.identifier_optional(subject, value, Some(span))
    }

    fn identifier_optional(&mut self, subject: &str, value: &str, span: Option<ComposeSpan>) -> Option<Identifier> {
        match Identifier::new(value) {
            Ok(value) => Some(value),
            Err(error) => {
                self.invalid_model_optional(subject, &error, span);
                None
            }
        }
    }

    fn sourced_provenance<T>(&self, value: T, provenance: &MergeProvenance) -> Sourced<T> {
        let mut sourced = Sourced::generated(value);
        for origin in provenance.sources().iter().filter_map(|span| self.origin(*span)) {
            sourced.add_origin(origin);
        }
        sourced
    }

    fn origins(&self, provenance: &MergeProvenance) -> Vec<Provenance> {
        provenance
            .sources()
            .iter()
            .filter_map(|span| self.origin(*span))
            .collect()
    }

    fn sourced_spans<T>(&self, value: T, source_spans: &[ComposeSpan]) -> Sourced<T> {
        let mut result = Sourced::generated(value);
        for origin in source_spans.iter().filter_map(|span| self.origin(*span)) {
            if !result.origins().contains(&origin) {
                result.add_origin(origin);
            }
        }
        result
    }

    fn sourced_project_key_value<T>(
        &self,
        value: T,
        key_sources: &[ComposeSpan],
        value_provenance: &MergeProvenance,
    ) -> Sourced<T> {
        let mut result = self.sourced_spans(value, key_sources);
        for origin in value_provenance.sources().iter().filter_map(|span| self.origin(*span)) {
            if !result.origins().contains(&origin) {
                result.add_origin(origin);
            }
        }
        result
    }

    fn sourced_host_mapping(
        &self,
        value: HostMapping,
        hostname_sources: &[ComposeSpan],
        address_provenance: &MergeProvenance,
    ) -> Sourced<HostMapping> {
        let mut sourced = Sourced::generated(value);
        for origin in hostname_sources
            .iter()
            .chain(address_provenance.sources())
            .filter_map(|span| self.origin(*span))
        {
            if !sourced.origins().contains(&origin) {
                sourced.add_origin(origin);
            }
        }
        sourced
    }

    fn sourced_metadata_label(
        &self,
        value: MetadataLabel,
        name_sources: &[ComposeSpan],
        value_provenance: &MergeProvenance,
    ) -> Sourced<MetadataLabel> {
        let mut sourced = Sourced::generated(value);
        for origin in name_sources
            .iter()
            .chain(value_provenance.sources())
            .filter_map(|span| self.origin(*span))
        {
            if !sourced.origins().contains(&origin) {
                sourced.add_origin(origin);
            }
        }
        sourced
    }

    fn exact_provenance(&mut self, subject: impl Into<String>, provenance: &MergeProvenance) {
        let outcome = ConversionOutcome::exact(subject);
        let outcome = self.with_provenance(outcome, provenance);
        self.outcomes.push(outcome);
    }

    fn exact_origins(&mut self, subject: impl Into<String>, origins: &[Provenance]) {
        let mut outcome = ConversionOutcome::exact(subject);
        for origin in origins {
            outcome = outcome.with_origin(origin.clone());
        }
        self.outcomes.push(outcome);
    }

    fn exact_spans(&mut self, subject: impl Into<String>, spans: &[ComposeSpan]) {
        let value = self.sourced_spans((), spans);
        self.exact_origins(subject, value.origins());
    }

    fn unsupported(&mut self, subject: &str, feature: &str, span: ComposeSpan) {
        self.unsupported_optional(subject, feature, Some(span));
    }

    fn unsupported_spans(&mut self, subject: &str, feature: &str, spans: &[ComposeSpan]) {
        let code = self.codes.unsupported.clone();
        self.diagnostics.push(
            Diagnostic::new(
                code.clone(),
                Severity::Warning,
                "Compose intent is not represented by the current neutral-model subset",
            )
            .with_field(DiagnosticField::new("subject", DiagnosticValue::plain(subject)))
            .with_field(DiagnosticField::new("feature", DiagnosticValue::plain(feature))),
        );
        if let Ok(mut outcome) = ConversionOutcome::loss(subject, ConversionKind::Unsupported, code) {
            for span in spans {
                if let Some(origin) = self.origin(*span)
                    && !outcome.origins().contains(&origin)
                {
                    outcome = outcome.with_origin(origin);
                }
            }
            self.outcomes.push(outcome);
        }
    }

    fn unsupported_optional(&mut self, subject: &str, feature: &str, span: Option<ComposeSpan>) {
        let code = self.codes.unsupported.clone();
        self.diagnostics.push(
            Diagnostic::new(
                code.clone(),
                Severity::Warning,
                "Compose intent is not represented by the current neutral-model subset",
            )
            .with_field(DiagnosticField::new("subject", DiagnosticValue::plain(subject)))
            .with_field(DiagnosticField::new("feature", DiagnosticValue::plain(feature))),
        );
        if let Ok(outcome) = ConversionOutcome::loss(subject, ConversionKind::Unsupported, code) {
            self.outcomes.push(self.with_optional_origin(outcome, span));
        }
    }

    fn report_unresolved_variable(&mut self, subject: &str, value: &str, reason: &str) {
        let code = self.codes.unresolved_variable.clone();
        let mut diagnostic = Diagnostic::new(
            code,
            Severity::Warning,
            "Compose variable expression remains unresolved at the adapter boundary",
        )
        .with_field(DiagnosticField::new("subject", DiagnosticValue::plain(subject)))
        .with_field(DiagnosticField::new("reason", DiagnosticValue::plain(reason)));
        if let Some(variable) = first_compose_variable(value) {
            diagnostic = diagnostic.with_field(DiagnosticField::new("variable", DiagnosticValue::plain(variable)));
        }
        self.diagnostics.push(diagnostic);
    }

    fn unresolved_volume_variable(&mut self, subject: &str, value: &str, span: ComposeSpan) {
        self.report_unresolved_variable(
            subject,
            value,
            "volume source could resolve to either a host path or a named volume",
        );
        let code = self.codes.unresolved_variable.clone();
        if let Ok(outcome) = ConversionOutcome::loss(subject, ConversionKind::Unsupported, code) {
            self.outcomes.push(self.with_optional_origin(outcome, Some(span)));
        }
    }

    fn invalid_model(&mut self, subject: &str, error: &ModelError, span: ComposeSpan) {
        self.invalid_model_optional(subject, error, Some(span));
    }

    fn invalid_model_optional(&mut self, subject: &str, error: &ModelError, span: Option<ComposeSpan>) {
        self.invalid_optional_span(
            self.codes.invalid_model.clone(),
            subject,
            "Compose value cannot be represented in the neutral application model",
            &error.to_string(),
            span,
        );
    }

    fn invalid_value(&mut self, subject: &str, reason: &str, span: ComposeSpan) {
        self.invalid_with_code(
            self.codes.invalid_value.clone(),
            subject,
            "Compose value must be resolved or corrected before conversion",
            reason,
            span,
        );
    }

    fn invalid_value_optional(&mut self, subject: &str, reason: &str, span: Option<ComposeSpan>) {
        self.invalid_optional_span(
            self.codes.invalid_value.clone(),
            subject,
            "Compose value must be resolved or corrected before conversion",
            reason,
            span,
        );
    }

    fn invalid_with_code(
        &mut self,
        code: DiagnosticCode,
        subject: &str,
        summary: &str,
        reason: &str,
        span: ComposeSpan,
    ) {
        self.invalid_optional_span(code, subject, summary, reason, Some(span));
    }

    fn invalid_optional_span(
        &mut self,
        code: DiagnosticCode,
        subject: &str,
        summary: &str,
        reason: &str,
        span: Option<ComposeSpan>,
    ) {
        self.diagnostics.push(
            Diagnostic::new(code.clone(), Severity::Error, summary)
                .with_field(DiagnosticField::new("subject", DiagnosticValue::plain(subject)))
                .with_field(DiagnosticField::new("reason", DiagnosticValue::plain(reason))),
        );
        if let Ok(outcome) = ConversionOutcome::loss(subject, ConversionKind::Invalid, code) {
            self.outcomes.push(self.with_optional_origin(outcome, span));
        }
    }

    fn report_project_diagnostics(&mut self, diagnostics: &[compose_lens::diagnostic::Diagnostic]) {
        for diagnostic in diagnostics {
            let severity = match diagnostic.severity() {
                compose_lens::diagnostic::Severity::Error => Severity::Error,
                compose_lens::diagnostic::Severity::Warning => Severity::Warning,
                compose_lens::diagnostic::Severity::Note => Severity::Note,
            };
            let native = crate::source::native_project_finding(diagnostic);
            let code = if severity == Severity::Error {
                self.codes.invalid_value.clone()
            } else {
                self.native_code(&native)
            };
            self.diagnostics.push(
                Diagnostic::new(
                    code.clone(),
                    severity,
                    "ComposeLens could not fully type the merged project",
                )
                .with_native_finding(native),
            );
            let kind = if severity == Severity::Error {
                ConversionKind::Invalid
            } else {
                ConversionKind::Unsupported
            };
            if let Ok(mut outcome) = ConversionOutcome::loss("application", kind, code) {
                for origin in diagnostic.labels().iter().filter_map(|label| self.origin(label.span())) {
                    outcome = outcome.with_origin(origin);
                }
                self.outcomes.push(outcome);
            }
        }
    }

    fn report_native_findings(&mut self, findings: &[NativeFinding]) {
        for finding in findings {
            let diagnostic = Diagnostic::new(
                self.native_code(finding),
                finding.severity(),
                "ComposeLens reported a native Compose finding",
            )
            .with_native_finding(finding.clone());
            self.diagnostics.push(diagnostic);
        }
    }

    fn native_code(&self, finding: &NativeFinding) -> DiagnosticCode {
        match finding.code() {
            "compose.interpolation.unset-variable" => self.codes.unset_variable.clone(),
            "compose.interpolation.required-variable" => self.codes.required_variable.clone(),
            "compose.interpolation.invalid-expression" => self.codes.interpolation_invalid.clone(),
            "compose.interpolation.nesting-limit" => self.codes.interpolation_nesting.clone(),
            _ => match finding.severity() {
                Severity::Error => self.codes.native_error.clone(),
                Severity::Note => self.codes.native_note.clone(),
                _ => self.codes.native_warning.clone(),
            },
        }
    }

    fn with_origin(&self, outcome: ConversionOutcome, span: ComposeSpan) -> ConversionOutcome {
        match self.origin(span) {
            Some(origin) => outcome.with_origin(origin),
            None => outcome,
        }
    }

    fn with_optional_origin(&self, outcome: ConversionOutcome, span: Option<ComposeSpan>) -> ConversionOutcome {
        match span {
            Some(span) => self.with_origin(outcome, span),
            None => outcome,
        }
    }

    fn with_provenance(&self, mut outcome: ConversionOutcome, provenance: &MergeProvenance) -> ConversionOutcome {
        for origin in provenance.sources().iter().filter_map(|span| self.origin(*span)) {
            outcome = outcome.with_origin(origin);
        }
        outcome
    }

    fn origin(&self, span: ComposeSpan) -> Option<Provenance> {
        let source_id = self.source.source_id(span.source_id())?.clone();
        SourceSpan::new(span.start(), span.end())
            .ok()
            .map(|span| Provenance::spanned(source_id, span))
    }
}

fn quadlet_shm_size(value: &ShmSizeKind) -> Option<String> {
    let ShmSizeKind::Documented { amount_raw, unit } = value else {
        return None;
    };
    if !amount_raw.bytes().any(|byte| byte != b'0') || !amount_raw.bytes().all(|byte| byte.is_ascii_digit()) {
        return None;
    }
    let unit = match unit {
        ShmSizeUnit::B => "b",
        ShmSizeUnit::K | ShmSizeUnit::Kb => "k",
        ShmSizeUnit::M | ShmSizeUnit::Mb => "m",
        ShmSizeUnit::G | ShmSizeUnit::Gb => "g",
        _ => return None,
    };
    Some(format!("{amount_raw}{unit}"))
}

fn scalar_text(value: &ComposeScalar) -> String {
    match value {
        ComposeScalar::Null => String::new(),
        ComposeScalar::Boolean(value) => value.to_string(),
        ComposeScalar::Number(value) | ComposeScalar::String(value) => value.clone(),
    }
}

fn scalar_option(value: &ComposeScalar) -> Option<String> {
    match value {
        ComposeScalar::Null => None,
        value => Some(scalar_text(value)),
    }
}

fn literal_assignment(value: &str) -> Option<(&str, &str)> {
    let (name, value) = value.split_once('=')?;
    if name.is_empty() || name.contains('$') || value.contains('$') {
        return None;
    }
    Some((name, value))
}

fn first_compose_variable(value: &str) -> Option<&str> {
    let (_, remainder) = value.split_once('$')?;
    let remainder = remainder.strip_prefix('{').unwrap_or(remainder);
    let end = remainder
        .bytes()
        .position(|byte| byte != b'_' && !byte.is_ascii_alphanumeric())
        .unwrap_or(remainder.len());
    let variable = &remainder[..end];
    let mut bytes = variable.bytes();
    let first = bytes.next()?;
    ((first == b'_' || first.is_ascii_alphabetic()) && bytes.all(|byte| byte == b'_' || byte.is_ascii_alphanumeric()))
        .then_some(variable)
}

/// Correlates the typed ordered aliases with scalar evidence in their original merged project.
/// The complete tuple must agree before any scalar flag can authorize an ordinary alias. Missing
/// or malformed metadata never falls back to aggregate sensitivity, value guesses, or YAML parsing.
fn corroborated_alias_sensitivities(
    project: &MergedProject,
    service_name: &str,
    network: &ServiceNetwork,
) -> Option<Vec<bool>> {
    let values = project
        .value(&["services", service_name, "networks", network.name().value(), "aliases"])?
        .as_sequence()?;
    if values.len() != network.aliases().len() {
        return None;
    }
    values
        .iter()
        .zip(network.aliases())
        .map(|(value, alias)| {
            let scalar = value.as_scalar()?;
            if scalar.value() != alias.value() || value.provenance().effective_source() != Some(alias.span()) {
                return None;
            }
            Some(scalar.is_sensitive())
        })
        .collect()
}

fn map_protocol(protocol: Option<&str>) -> Protocol {
    match protocol.unwrap_or("tcp").to_ascii_lowercase().as_str() {
        "tcp" => Protocol::Tcp,
        "udp" => Protocol::Udp,
        "sctp" => Protocol::Sctp,
        value => Protocol::Other(value.to_owned()),
    }
}

fn is_host_path(value: &str) -> bool {
    value.starts_with('/')
        || value.starts_with("./")
        || value.starts_with("../")
        || value.starts_with('~')
        || value.starts_with('%')
        || value.starts_with("//")
        || value.starts_with(r"\\")
        || value
            .as_bytes()
            .get(0..2)
            .is_some_and(|prefix| prefix[0].is_ascii_alphabetic() && prefix[1] == b':')
}

#[cfg(test)]
#[path = "import_alias_tests.rs"]
mod alias_tests;