public extension PureYAML.Validation {
    /// Traverses a `Subject` tree and applies type-directed checks at each node. The validation value,
    /// its erasure, its context, the combinators, and this traversal engine are all the one shared
    /// framework (validation-rules.md, principle 10); each layer supplies only its own `Subject`/
    /// `Document` types (through `Traversable`), its built-in checks, and its own traversal shape.
    ///
    /// `@unchecked Sendable`: immutable after `init` (every stored validation list is a `let`), so
    /// concurrent reads race on nothing; the erased `AnyValidation` closures are simply not provably
    /// `Sendable` to the compiler.
    final class Validator<Subject: Traversable, Document: Sendable>: @unchecked Sendable {
        fileprivate let nonReferenceDefaultValidations: [AnyValidation<Document>]
        fileprivate let referenceDefaultValidations: [AnyValidation<Document>]
        fileprivate let customValidations: [AnyValidation<Document>]

        public init(
            nonReferenceDefaultValidations: [AnyValidation<Document>] = [],
            referenceDefaultValidations: [AnyValidation<Document>] = [],
            customValidations: [AnyValidation<Document>] = [],
        ) {
            self.nonReferenceDefaultValidations = nonReferenceDefaultValidations
            self.referenceDefaultValidations = referenceDefaultValidations
            self.customValidations = customValidations
        }

        /// A validator with no checks; add your own with `validating(_:)`.
        public static var blank: Validator {
            Validator()
        }

        /// The descriptions of every active check, in application order.
        public var validationDescriptions: [String] {
            validations.map(\.description)
        }

        /// Descriptions of the non-reference default tier, in order.
        public var nonReferenceValidationDescriptions: [String] {
            nonReferenceDefaultValidations.map(\.description)
        }

        /// Descriptions of the reference default tier, in order.
        public var referenceValidationDescriptions: [String] {
            referenceDefaultValidations.map(\.description)
        }

        /// Descriptions of the custom tier, in order.
        public var customValidationDescriptions: [String] {
            customValidations.map(\.description)
        }

        fileprivate var validations: [AnyValidation<Document>] {
            nonReferenceDefaultValidations + referenceDefaultValidations + customValidations
        }

        /// Returns a validator with `validation` appended to the custom tier.
        @discardableResult
        public func validating(_ validation: Validation<some Validatable, Document>) -> Validator {
            Validator(
                nonReferenceDefaultValidations: nonReferenceDefaultValidations,
                referenceDefaultValidations: referenceDefaultValidations,
                customValidations: customValidations + [AnyValidation(validation)],
            )
        }

        /// Returns a validator with the checks matching `descriptions` removed from every tier, the
        /// identity the validation idiom uses for removal. Descriptions are therefore required to be
        /// unique and stable.
        @discardableResult
        public func withoutValidating(_ descriptions: String...) -> Validator {
            let drop = Set(descriptions)
            func filter(_ tier: [AnyValidation<Document>]) -> [AnyValidation<Document>] {
                tier.filter { !drop.contains($0.description) }
            }
            return Validator(
                nonReferenceDefaultValidations: filter(nonReferenceDefaultValidations),
                referenceDefaultValidations: filter(referenceDefaultValidations),
                customValidations: filter(customValidations),
            )
        }

        public func collect(_ subject: Subject, in document: Document) -> Result {
            var errors: [ValidationError] = []
            walk(subject, at: .root, in: document, into: &errors)
            return Result(errors)
        }

        @discardableResult
        public func validate(
            _ subject: Subject,
            in document: Document,
            strict: Bool = true,
        ) throws -> [ValidationError] {
            let result = collect(subject, in: document)
            let failures = strict ? result.values : result.errors
            if !failures.isEmpty {
                throw ValidationErrorCollection(failures)
            }
            return strict ? [] : result.warnings
        }

        private func walk(_ subject: Subject, at path: Path, in document: Document, into errors: inout [ValidationError]) {
            // Offer the node itself, then any extra values this layer's Traversable conformance wants
            // offered here (a mapping's own type, its key nodes), then recurse into its children.
            offer(subject, at: path, in: document, into: &errors)
            for (component, value) in subject.extraOffers {
                offer(value, at: component.map(path.appending) ?? path, in: document, into: &errors)
            }
            for (component, child) in subject.children {
                walk(child, at: path.appending(component), in: document, into: &errors)
            }
        }

        private func offer(_ value: any Validatable, at path: Path, in document: Document, into errors: inout [ValidationError]) {
            for validation in validations {
                errors.append(contentsOf: validation.apply(to: value, at: path, in: document))
            }
        }
    }
}

public extension PureYAML.Validation.Validator where Subject == Document {
    /// Convenience for the common case where the walked tree's root doubles as the cross-cutting
    /// document (every PureYAML layer, today).
    func collect(_ subject: Subject) -> PureYAML.Validation.Result {
        collect(subject, in: subject)
    }

    @discardableResult
    func validate(_ subject: Subject, strict: Bool = true) throws -> [PureYAML.Validation.ValidationError] {
        try validate(subject, in: subject, strict: strict)
    }
}

public extension PureYAML.Validation.Validator where Subject == PureYAML.Model.Value, Document == PureYAML.Model.Value {
    /// The model layer's default checks: schema-independent structural rules.
    static var defaultValidations: [PureYAML.Validation.AnyValidation<PureYAML.Model.Value>] {
        [PureYAML.Validation.AnyValidation(PureYAML.Validation.BuiltinValidation.mappingKeysAreUnique)]
    }

    convenience init() {
        self.init(nonReferenceDefaultValidations: Self.defaultValidations)
    }

    @discardableResult
    func validate(
        _ documents: [PureYAML.Stream.Document],
        strict: Bool = true,
    ) throws -> [PureYAML.Stream.Issue] {
        let result = collect(documents)
        let failures = strict ? result.issues : result.errors
        if !failures.isEmpty {
            throw PureYAML.Stream.Issue.Collection(failures)
        }
        return strict ? [] : result.warnings
    }

    func collect(_ documents: [PureYAML.Stream.Document]) -> PureYAML.Stream.Result {
        var issues: [PureYAML.Stream.Issue] = []
        for document in documents {
            let result = collect(document.value)
            issues.append(contentsOf: result.values.map { error in
                PureYAML.Stream.Issue(documentIndex: document.index, issue: error)
            })
        }
        return PureYAML.Stream.Result(issues)
    }
}