namespace AutoForge.Core.Vehicles; public enum CapabilityStatus { Supported, Unsupported, Unknown, Inaccessible, Restricted } public enum EvidenceClassification { Verified, Unverified, Inferred, Synthetic } public sealed class VehicleIdentity { public VehicleIdentity( string vehicleIdentifier, string manufacturer, string model, int? modelYear = null, string? trim = null, string? engine = null, string? transmission = null, string? drivetrain = null, IEnumerable? evidenceReferences = null) { VehicleIdentifier = ProfileValidation.RequiredIdentifier(vehicleIdentifier, nameof(vehicleIdentifier)); Manufacturer = ProfileValidation.RequiredText(manufacturer, nameof(manufacturer)); Model = ProfileValidation.RequiredText(model, nameof(model)); if (modelYear is <= 0 or > 9999) { throw new ArgumentOutOfRangeException(nameof(modelYear), modelYear, "Model year must be unknown or between 1 and 9999."); } ModelYear = modelYear; Trim = ProfileValidation.OptionalText(trim, nameof(trim)); Engine = ProfileValidation.OptionalText(engine, nameof(engine)); Transmission = ProfileValidation.OptionalText(transmission, nameof(transmission)); Drivetrain = ProfileValidation.OptionalText(drivetrain, nameof(drivetrain)); EvidenceReferences = ProfileValidation.CopyIdentifiers(evidenceReferences, nameof(evidenceReferences)); } public string VehicleIdentifier { get; } public string Manufacturer { get; } public string Model { get; } public int? ModelYear { get; } public string? Trim { get; } public string? Engine { get; } public string? Transmission { get; } public string? Drivetrain { get; } public IReadOnlyList EvidenceReferences { get; } } public sealed class EvidenceApplicability { public EvidenceApplicability( string vehicleIdentifier, int? modelYear = null, string? profileIdentifier = null, int? profileRevision = null, string? moduleInstanceIdentifier = null, string? hardwareIdentifier = null, string? softwareIdentifier = null, string? firmwareIdentifier = null, string? calibrationIdentifier = null) { VehicleIdentifier = ProfileValidation.RequiredIdentifier(vehicleIdentifier, nameof(vehicleIdentifier)); if (modelYear is <= 0 or > 9999) { throw new ArgumentOutOfRangeException(nameof(modelYear), modelYear, "Applicable model year must be unknown or between 1 and 9999."); } ModelYear = modelYear; ProfileIdentifier = ProfileValidation.OptionalIdentifier(profileIdentifier, nameof(profileIdentifier)); ModuleInstanceIdentifier = ProfileValidation.OptionalIdentifier(moduleInstanceIdentifier, nameof(moduleInstanceIdentifier)); HardwareIdentifier = ProfileValidation.OptionalIdentifier(hardwareIdentifier, nameof(hardwareIdentifier)); SoftwareIdentifier = ProfileValidation.OptionalIdentifier(softwareIdentifier, nameof(softwareIdentifier)); FirmwareIdentifier = ProfileValidation.OptionalIdentifier(firmwareIdentifier, nameof(firmwareIdentifier)); CalibrationIdentifier = ProfileValidation.OptionalIdentifier(calibrationIdentifier, nameof(calibrationIdentifier)); if ((ProfileIdentifier is null) != (profileRevision is null) || profileRevision is <= 0) { throw new ArgumentException( "Profile applicability must specify both a profile identifier and a positive revision, or neither.", nameof(profileRevision)); } if (ModuleInstanceIdentifier is null && (HardwareIdentifier is not null || SoftwareIdentifier is not null || FirmwareIdentifier is not null || CalibrationIdentifier is not null)) { throw new ArgumentException( "Module identity context requires an explicit module instance identifier.", nameof(moduleInstanceIdentifier)); } ProfileRevision = profileRevision; } public string VehicleIdentifier { get; } public int? ModelYear { get; } public string? ProfileIdentifier { get; } public int? ProfileRevision { get; } public string? ModuleInstanceIdentifier { get; } public string? HardwareIdentifier { get; } public string? SoftwareIdentifier { get; } public string? FirmwareIdentifier { get; } public string? CalibrationIdentifier { get; } } public sealed class ProfileEvidence { public ProfileEvidence( string evidenceIdentifier, EvidenceClassification classification, string sourceReference, string description, EvidenceApplicability applicability, double? confidence = null, string? verificationInformation = null, DateTimeOffset? publishedAt = null, DateTimeOffset? retrievedAt = null, IEnumerable? limitations = null) { EvidenceIdentifier = ProfileValidation.RequiredIdentifier(evidenceIdentifier, nameof(evidenceIdentifier)); if (!Enum.IsDefined(classification)) { throw new ArgumentOutOfRangeException(nameof(classification), classification, "Specify a defined evidence classification."); } Classification = classification; SourceReference = ProfileValidation.RequiredText(sourceReference, nameof(sourceReference)); Description = ProfileValidation.RequiredText(description, nameof(description)); Applicability = applicability ?? throw new ArgumentNullException(nameof(applicability)); if (confidence is { } value && (!double.IsFinite(value) || value is < 0 or > 1)) { throw new ArgumentOutOfRangeException(nameof(confidence), confidence, "Confidence must be unknown or finite and between 0 and 1."); } Confidence = confidence; VerificationInformation = ProfileValidation.OptionalText(verificationInformation, nameof(verificationInformation)); PublishedAt = publishedAt; RetrievedAt = retrievedAt; Limitations = ProfileValidation.CopyText(limitations, nameof(limitations)); } public string EvidenceIdentifier { get; } public EvidenceClassification Classification { get; } public string SourceReference { get; } public string Description { get; } public EvidenceApplicability Applicability { get; } public double? Confidence { get; } public string? VerificationInformation { get; } public DateTimeOffset? PublishedAt { get; } public DateTimeOffset? RetrievedAt { get; } public IReadOnlyList Limitations { get; } } public sealed class CapabilityDeclaration { public CapabilityDeclaration( string operationIdentifier, CapabilityStatus status, string? explanation = null, IEnumerable? limitations = null, IEnumerable? evidenceReferences = null) { OperationIdentifier = ProfileValidation.RequiredIdentifier(operationIdentifier, nameof(operationIdentifier)); if (!Enum.IsDefined(status)) { throw new ArgumentOutOfRangeException(nameof(status), status, "Specify a defined capability status."); } Status = status; Explanation = ProfileValidation.OptionalText(explanation, nameof(explanation)); Limitations = ProfileValidation.CopyText(limitations, nameof(limitations)); EvidenceReferences = ProfileValidation.CopyIdentifiers(evidenceReferences, nameof(evidenceReferences)); } public string OperationIdentifier { get; } public CapabilityStatus Status { get; } public string? Explanation { get; } public IReadOnlyList Limitations { get; } public IReadOnlyList EvidenceReferences { get; } } public sealed class ModuleInstance { public ModuleInstance( string instanceIdentifier, string role, string name, string? hardwareIdentifier = null, string? softwareIdentifier = null, string? firmwareIdentifier = null, string? calibrationIdentifier = null, IEnumerable? capabilities = null, IEnumerable? evidenceReferences = null) { InstanceIdentifier = ProfileValidation.RequiredIdentifier(instanceIdentifier, nameof(instanceIdentifier)); Role = ProfileValidation.RequiredIdentifier(role, nameof(role)); Name = ProfileValidation.RequiredText(name, nameof(name)); HardwareIdentifier = ProfileValidation.OptionalIdentifier(hardwareIdentifier, nameof(hardwareIdentifier)); SoftwareIdentifier = ProfileValidation.OptionalIdentifier(softwareIdentifier, nameof(softwareIdentifier)); FirmwareIdentifier = ProfileValidation.OptionalIdentifier(firmwareIdentifier, nameof(firmwareIdentifier)); CalibrationIdentifier = ProfileValidation.OptionalIdentifier(calibrationIdentifier, nameof(calibrationIdentifier)); Capabilities = ProfileValidation.CopyItems(capabilities ?? [], nameof(capabilities)); EvidenceReferences = ProfileValidation.CopyIdentifiers(evidenceReferences, nameof(evidenceReferences)); ProfileValidation.EnsureUnique( Capabilities.Select(capability => capability.OperationIdentifier), StringComparer.OrdinalIgnoreCase, "Capability operation identifiers must be unique within a module."); } public string InstanceIdentifier { get; } public string Role { get; } public string Name { get; } public string? HardwareIdentifier { get; } public string? SoftwareIdentifier { get; } public string? FirmwareIdentifier { get; } public string? CalibrationIdentifier { get; } public IReadOnlyList Capabilities { get; } public IReadOnlyList EvidenceReferences { get; } public CapabilityAssessment GetCapability(string operationIdentifier) { var requested = ProfileValidation.RequiredIdentifier(operationIdentifier, nameof(operationIdentifier)); var declaration = Capabilities.FirstOrDefault( capability => StringComparer.OrdinalIgnoreCase.Equals(capability.OperationIdentifier, requested)); return declaration is null ? new CapabilityAssessment( requested, CapabilityStatus.Unknown, false, "No capability declaration exists for this operation.") : new CapabilityAssessment( declaration.OperationIdentifier, declaration.Status, true, declaration.Explanation ?? "The capability declaration has no additional explanation."); } } public sealed record CapabilityAssessment( string OperationIdentifier, CapabilityStatus Status, bool IsDeclared, string Explanation); public sealed class VehicleProfile { public VehicleProfile( string profileIdentifier, int revision, VehicleIdentity vehicle, IEnumerable? modules, IEnumerable? evidence) { ProfileIdentifier = ProfileValidation.RequiredIdentifier(profileIdentifier, nameof(profileIdentifier)); if (revision <= 0) { throw new ArgumentOutOfRangeException(nameof(revision), revision, "Profile revision must be positive."); } Revision = revision; Vehicle = vehicle ?? throw new ArgumentNullException(nameof(vehicle)); Modules = ProfileValidation.CopyItems(modules, nameof(modules)); Evidence = ProfileValidation.CopyItems(evidence, nameof(evidence)); ProfileValidation.EnsureUnique( Modules.Select(module => module.InstanceIdentifier), StringComparer.OrdinalIgnoreCase, "Module instance identifiers must be unique within a profile revision."); ProfileValidation.EnsureUnique( Evidence.Select(item => item.EvidenceIdentifier), StringComparer.OrdinalIgnoreCase, "Evidence identifiers must be unique within a profile revision."); ValidateEvidenceReferences(); } public string ProfileIdentifier { get; } public int Revision { get; } public VehicleIdentity Vehicle { get; } public IReadOnlyList Modules { get; } public IReadOnlyList Evidence { get; } public ModuleInstance GetModule(string instanceIdentifier) { var requested = ProfileValidation.RequiredIdentifier(instanceIdentifier, nameof(instanceIdentifier)); return Modules.FirstOrDefault( module => StringComparer.OrdinalIgnoreCase.Equals(module.InstanceIdentifier, requested)) ?? throw new KeyNotFoundException($"Module instance '{requested}' is not declared in this profile."); } private void ValidateEvidenceReferences() { var evidenceById = Evidence.ToDictionary( item => item.EvidenceIdentifier, StringComparer.OrdinalIgnoreCase); ValidateReferences(Vehicle.EvidenceReferences, evidenceById, null, "vehicle"); foreach (var module in Modules) { ValidateReferences(module.EvidenceReferences, evidenceById, module, $"module '{module.InstanceIdentifier}'"); foreach (var capability in module.Capabilities) { ValidateReferences( capability.EvidenceReferences, evidenceById, module, $"operation '{capability.OperationIdentifier}' on module '{module.InstanceIdentifier}'"); } } foreach (var item in Evidence) { var scope = item.Applicability; if (!StringComparer.OrdinalIgnoreCase.Equals(scope.VehicleIdentifier, Vehicle.VehicleIdentifier)) { throw new ArgumentException( $"Evidence '{item.EvidenceIdentifier}' applies to vehicle '{scope.VehicleIdentifier}', not '{Vehicle.VehicleIdentifier}'.", nameof(Evidence)); } if (scope.ModelYear is { } applicableYear && Vehicle.ModelYear is { } vehicleYear && applicableYear != vehicleYear) { throw new ArgumentException( $"Evidence '{item.EvidenceIdentifier}' applies to model year {applicableYear}, not {vehicleYear}.", nameof(Evidence)); } if (scope.ProfileIdentifier is not null && (!StringComparer.OrdinalIgnoreCase.Equals(scope.ProfileIdentifier, ProfileIdentifier) || scope.ProfileRevision != Revision)) { throw new ArgumentException( $"Evidence '{item.EvidenceIdentifier}' applies to a different profile identity or revision.", nameof(Evidence)); } if (scope.ModuleInstanceIdentifier is not null) { var module = Modules.FirstOrDefault( candidate => StringComparer.OrdinalIgnoreCase.Equals( candidate.InstanceIdentifier, scope.ModuleInstanceIdentifier)); if (module is null || !SameOptional(scope.HardwareIdentifier, module.HardwareIdentifier) || !SameOptional(scope.SoftwareIdentifier, module.SoftwareIdentifier) || !SameOptional(scope.FirmwareIdentifier, module.FirmwareIdentifier) || !SameOptional(scope.CalibrationIdentifier, module.CalibrationIdentifier)) { throw new ArgumentException( $"Evidence '{item.EvidenceIdentifier}' has dangling or conflicting module applicability.", nameof(Evidence)); } } } } private static void ValidateReferences( IReadOnlyList references, IReadOnlyDictionary evidenceById, ModuleInstance? module, string context) { foreach (var reference in references) { if (!evidenceById.TryGetValue(reference, out var item)) { throw new ArgumentException( $"Evidence reference '{reference}' for {context} does not resolve within this profile.", nameof(Evidence)); } var scope = item.Applicability; if (scope.ModuleInstanceIdentifier is not null && (module is null || !StringComparer.OrdinalIgnoreCase.Equals(scope.ModuleInstanceIdentifier, module.InstanceIdentifier))) { throw new ArgumentException( $"Evidence '{reference}' is not applicable to {context}.", nameof(Evidence)); } } } private static bool SameOptional(string? constraint, string? target) => constraint is null || (target is not null && StringComparer.OrdinalIgnoreCase.Equals(constraint, target)); } public sealed class VehicleProfileReference { public VehicleProfileReference(string profileIdentifier, int revision) { ProfileIdentifier = ProfileValidation.RequiredIdentifier(profileIdentifier, nameof(profileIdentifier)); if (revision <= 0) { throw new ArgumentOutOfRangeException(nameof(revision), revision, "Profile revision must be positive."); } Revision = revision; } public string ProfileIdentifier { get; } public int Revision { get; } } internal static class ProfileValidation { public static string RequiredIdentifier(string? value, string parameterName) { ArgumentException.ThrowIfNullOrWhiteSpace(value, parameterName); if (!StringComparer.Ordinal.Equals(value, value.Trim())) { throw new ArgumentException("Identifiers must not contain leading or trailing whitespace.", parameterName); } return value; } public static string? OptionalIdentifier(string? value, string parameterName) => value is null ? null : RequiredIdentifier(value, parameterName); public static string RequiredText(string? value, string parameterName) { ArgumentException.ThrowIfNullOrWhiteSpace(value, parameterName); if (!StringComparer.Ordinal.Equals(value, value.Trim())) { throw new ArgumentException("Text values must not contain leading or trailing whitespace.", parameterName); } return value; } public static string? OptionalText(string? value, string parameterName) => value is null ? null : RequiredText(value, parameterName); public static IReadOnlyList CopyIdentifiers(IEnumerable? values, string parameterName) { var copy = values?.Select(value => RequiredIdentifier(value, parameterName)).ToArray() ?? []; EnsureUnique(copy, StringComparer.OrdinalIgnoreCase, $"{parameterName} must not contain duplicates."); return Array.AsReadOnly(copy); } public static IReadOnlyList CopyText(IEnumerable? values, string parameterName) { var copy = values?.Select(value => RequiredText(value, parameterName)).ToArray() ?? []; return Array.AsReadOnly(copy); } public static IReadOnlyList CopyItems(IEnumerable? values, string parameterName) where T : class { if (values is null) { throw new ArgumentNullException(parameterName); } var copy = values.ToArray(); if (copy.Any(item => item is null)) { throw new ArgumentException("Collections must not contain null items.", parameterName); } return Array.AsReadOnly(copy); } public static void EnsureUnique(IEnumerable values, StringComparer comparer, string message) { var set = new HashSet(comparer); foreach (var value in values) { if (!set.Add(value)) { throw new ArgumentException(message); } } } }