ksef_client 0.1.0.rc1 → 0.1.0

data/lib/ksef/upo/client.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Ksef
+  module UPO
+    # Retrieving UPO documents, by either of the two available routes
+    # (docs/REFERENCE.md §12, §14.2).
+    #
+    # ## Two routes, and which to prefer
+    #
+    # The **pre-signed link** in a session's `upo.pages[]` or an invoice's `upoDownloadUrl`
+    # is unmetered, carries an integrity hash, and expires. The **API route** is metered
+    # against a budget where `GET /sessions` already allows only 10 requests a minute (§6.1),
+    # and publishes no hash.
+    #
+    # So the link is preferred and the API route is the fallback, which is the resolution
+    # §14.2 arrived at — after an earlier revision of the ledger got it backwards and
+    # concluded the link should be ignored. {#fetch} implements that preference.
+    #
+    # ## The connection split is the safety mechanism
+    #
+    # Requests to a pre-signed link go over `storage`, a connection built by
+    # {Ksef::HTTP::Connection.storage} with **no credential and no base URL**. Sending the
+    # access token to third-party storage would leak it, and the contract says not to; using
+    # a separate connection means no code path here *can*.
+    class Client
+      # @param connection [Faraday::Connection] the authenticated API connection, for the
+      #   metered routes
+      # @param credential [Ksef::Auth::AccessToken, String] anything with `#bearer`
+      # @param storage [Faraday::Connection] from {Ksef::HTTP::Connection.storage} — must
+      #   not carry a credential
+      # @param clock [#call] returns the current {Time}. {#fetch} is the only route decision
+      #   in this library that depends on the clock, so it is the only reason this exists —
+      #   see there for what reading the wall clock instead cost.
+      def initialize(connection, credential, storage:, clock: -> { Time.now })
+        @connection = connection
+        @credential = credential
+        @storage = storage
+        @clock = clock
+      end
+
+      # Follows a pre-signed link, verifying the published hash.
+      #
+      # @param page [Ksef::Sessions::UpoPage, String] a page, or a bare URL
+      # @return [Document]
+      # @raise [Ksef::IntegrityError] when the bytes do not match `x-ms-meta-hash`
+      def download(page)
+        url = page.respond_to?(:download_url) ? page.download_url : page.to_s
+        raise ValidationError, "No download URL to follow" if url.to_s.empty?
+
+        # No Authorization header is set here, and `@storage` has none by construction.
+        response = @storage.get(absolute(url))
+        Document.new(
+          xml: response.body.to_s,
+          published_hash: response.headers[HASH_HEADER],
+          source: :storage
+        ).verify!
+      end
+
+      # The collective UPO for a whole session, over the metered API route.
+      def collective(session_reference, upo_reference)
+        session = Sessions.reference_number!(session_reference)
+        upo = Sessions.reference_number!(upo_reference)
+
+        via_api("sessions/#{session}/upo/#{upo}")
+      end
+
+      # One invoice's UPO, addressed by its submission reference.
+      def for_invoice(session_reference, invoice_reference)
+        session = Sessions.reference_number!(session_reference)
+        invoice = Sessions.reference_number!(invoice_reference)
+
+        via_api("sessions/#{session}/invoices/#{invoice}/upo")
+      end
+
+      # One invoice's UPO, addressed by its KSeF number.
+      #
+      # The number is parsed before use, so a mistyped one fails here on its checksum rather
+      # than as an opaque 404 (§13).
+      def for_ksef_number(session_reference, ksef_number)
+        session = Sessions.reference_number!(session_reference)
+        number = KsefNumber.parse(ksef_number)
+
+        via_api("sessions/#{session}/invoices/ksef/#{number}/upo")
+      end
+
+      # Prefers the unmetered link and falls back to the metered route when it has expired
+      # or is missing — the resolution of §14.2, in one call.
+      #
+      # **The expiry is judged against the injected clock, not `Time.now`.** This read the wall
+      # clock until 2026-09-03, which made it the one route decision in this library the
+      # recorded tier's pinned clock could not reach. KSeF signs the link for about three days,
+      # so `spec/recorded/invoice_download_spec.rb` replayed correctly for three and then
+      # started taking the metered fallback — a request its cassette had never recorded, since
+      # the recording itself took the link. The tier went red on 2026-08-29 with nothing
+      # changed, and nothing noticed until 2026-09-03 because no push ran the suite in between.
+      #
+      # Same failure as the fifteen-minute access token ({Ksef::Client#initialize}), one layer
+      # down: a recorded response is not a fixture, it decays, and every decision made against
+      # it has to be made against the moment it was recorded.
+      #
+      # @param page [Ksef::Sessions::UpoPage]
+      # @param session_reference [String] needed for the fallback
+      # @return [Document]
+      def fetch(page, session_reference:)
+        return download(page) unless page.download_url.to_s.empty? || page.expired?(@clock.call)
+
+        collective(session_reference, page.reference_number)
+      end
+
+      private
+
+      # **The metered routes publish `x-ms-meta-hash` too**, and an earlier version of this
+      # method threw it away with a comment claiming they did not. The pinned contract
+      # declares the header on all three UPO routes *and* on the invoice download — four
+      # `200` responses in total — which §5.5 of the ledger had recorded correctly all along.
+      # Discarding an available integrity check on legal proof of receipt was the wrong
+      # trade at any price. Corrected 2026-08-23.
+      #
+      # It is still read defensively rather than required: if the header is absent the
+      # document comes back unverifiable rather than failing, which is what {Document}'s
+      # `#verifiable?`/`#verified?` split is for.
+      def via_api(endpoint)
+        response = @connection.get(endpoint) do |request|
+          request.headers["Authorization"] = "Bearer #{bearer}"
+        end
+
+        Document.new(
+          xml: response.body.to_s,
+          published_hash: response.headers[HASH_HEADER],
+          source: :api
+        ).verify!
+      end
+
+      # §9 carries this as unverified: whether the live API returns `downloadUrl` absolute or
+      # host-relative is unsettled, and `srodowiska.md` says only that a returned URL's
+      # *host* matches the environment called. So an absolute URL is used untouched, and a
+      # relative one is resolved against the API host rather than guessed at.
+      def absolute(url)
+        uri = URI.parse(url)
+        return url if uri.absolute?
+
+        URI.join(@connection.url_prefix, url).to_s
+      rescue URI::InvalidURIError => e
+        raise ValidationError, "Malformed UPO download URL: #{e.message}"
+      end
+
+      def bearer
+        @credential.respond_to?(:bearer) ? @credential.bearer : @credential.to_s
+      end
+    end
+  end
+end

data/lib/ksef/upo/document.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Ksef
+  module UPO
+    # A retrieved UPO, held as the exact bytes received (docs/REFERENCE.md §12).
+    #
+    # `xml` is deliberately a raw `String` and not a parsed document. The Ministry's XAdES
+    # signature covers the octets, so anything that re-serialises them — even a lossless
+    # round-trip through an XML library — risks producing a document that no longer
+    # verifies. Parse a *copy* if you need to read it; archive this.
+    #
+    # `source` records where the bytes came from, because the two routes have different
+    # properties worth knowing after the fact: `:storage` is the unmetered pre-signed link
+    # (§14.2), `:api` the metered fallback.
+    Document = Data.define(:xml, :published_hash, :source) do
+      # SHA-256 of the bytes held, Base64 — the same form `x-ms-meta-hash` uses.
+      def sha256 = Ksef::Crypto::Digest.of(xml).base64
+
+      def size = xml.bytesize
+
+      # Whether there is anything to check against at all. The pre-signed storage link
+      # publishes `x-ms-meta-hash`; the metered API route publishes nothing.
+      #
+      # Split from {#verified?} rather than folded into it as a third state: "no hash was
+      # published" and "the hash did not match" call for completely different responses, and
+      # a predicate that answers both with one value invites treating an unverifiable
+      # document as a corrupt one.
+      def verifiable? = !published_hash.nil?
+
+      # True only when a hash was published **and** the bytes match it. False for an
+      # unverifiable document too — ask {#verifiable?} to tell the two apart.
+      def verified? = verifiable? && sha256 == published_hash
+
+      # @raise [Ksef::IntegrityError] when a published hash does not match the bytes
+      # @return [self]
+      def verify!
+        return self unless verifiable? && !verified?
+
+        raise IntegrityError,
+              "The UPO fetched from #{source} does not match the hash the server published: " \
+              "expected #{published_hash}, got #{sha256} over #{size} bytes. This is a corrupted " \
+              "transfer, not a bad request — fetch it again. Do not archive these bytes as proof " \
+              "of receipt (docs/REFERENCE.md §14.2)."
+      end
+
+      # Checks the document against the bundled schema — **a diagnostic, never a gate**
+      # (§14.3). Archive the bytes regardless of what this says; see {Validator} for why
+      # there is no raising counterpart.
+      #
+      # @return [Validation]
+      def validate = Validator.validate(xml)
+
+      # Writes the bytes untouched. Binary mode on purpose: this must not pick up a newline
+      # translation or a re-encode on the way to disk, or the archived file stops matching
+      # what the Ministry signed.
+      #
+      # @param path [String]
+      # @return [Integer] bytes written
+      def write(path)
+        File.binwrite(path, xml)
+      end
+
+      # Deliberately not the document: a UPO is a few kilobytes of XML, and putting it in a
+      # log line or an exception message helps nobody. DESIGN.md §4.5 forbids full invoice
+      # payloads at default log level, and the same reasoning applies here.
+      def to_s = "#<Ksef::UPO::Document #{size} bytes from #{source}>"
+
+      def inspect
+        state = verifiable? ? verified?.to_s : "unverifiable"
+        "#<data Ksef::UPO::Document size=#{size} source=#{source.inspect} verified=#{state}>"
+      end
+    end
+  end
+end

data/lib/ksef/upo/schema/upo-v4-3.xsd

@@ -0,0 +1,293 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+	xmlns:upo="http://upo.schematy.mf.gov.pl/KSeF/v4-3"
+	targetNamespace="http://upo.schematy.mf.gov.pl/KSeF/v4-3"
+	elementFormDefault="qualified" attributeFormDefault="unqualified"
+	version="1.0" xml:lang="PL">
+	<xsd:element name="Potwierdzenie">
+		<xsd:annotation>
+			<xsd:documentation>Element główny potwierdzenia</xsd:documentation>
+		</xsd:annotation>
+		<xsd:complexType>
+			<xsd:sequence>
+				<xsd:element name="NazwaPodmiotuPrzyjmujacego" fixed="Ministerstwo Finansów">
+					<xsd:annotation>
+						<xsd:documentation>Nazwa podmiotu przyjmującego dokument elektroniczny</xsd:documentation>
+					</xsd:annotation>
+					<xsd:simpleType>
+						<xsd:restriction base="xsd:token">
+							<xsd:minLength value="1"/>
+							<xsd:maxLength value="240"/>
+						</xsd:restriction>
+					</xsd:simpleType>
+				</xsd:element>
+				<xsd:element name="NumerReferencyjnySesji" type="upo:TNumerReferencyjny">
+					<xsd:annotation>
+						<xsd:documentation>Wartość numeru referencyjnego sesji</xsd:documentation>
+					</xsd:annotation>
+				</xsd:element>
+
+				<xsd:element name="Uwierzytelnienie">
+					<xsd:complexType>
+						<xsd:sequence>
+							<xsd:element name="IdKontekstu" >
+								<xsd:annotation>
+									<xsd:documentation>Identyfikator kontekstu uwierzytelnienia w systemie KSeF.</xsd:documentation>
+								</xsd:annotation>
+								<xsd:complexType>
+									<xsd:choice>
+										<xsd:element name="Nip" type="upo:TNip">
+											<xsd:annotation>
+												<xsd:documentation>Numer identyfikacyjny NIP</xsd:documentation>
+											</xsd:annotation>
+										</xsd:element>
+
+										<xsd:element name="IdWewnetrzny" type="upo:TIdWewnetrzny">
+											<xsd:annotation>
+												<xsd:documentation>Identyfikator wewnętrzny</xsd:documentation>
+											</xsd:annotation>
+										</xsd:element>
+
+										<xsd:element name="IdZlozonyVatUE" type="upo:TIdZlozonyVatUE">
+											<xsd:annotation>
+												<xsd:documentation>Kontekst złożony: NIP + numer VAT UE</xsd:documentation>
+											</xsd:annotation>
+										</xsd:element>
+
+										<xsd:element name="IdDostawcyUslugPeppol" type="upo:TIdDostawcyUslugPeppol">
+											<xsd:annotation>
+												<xsd:documentation>Identyfikator dostawcy usług Peppol</xsd:documentation>
+											</xsd:annotation>
+										</xsd:element>
+									</xsd:choice>
+								</xsd:complexType>
+							</xsd:element>
+							<xsd:choice>
+								
+								<xsd:element name="NumerReferencyjnyTokenaKSeF" type="upo:TNumerReferencyjny">
+									<xsd:annotation>
+										<xsd:documentation>Identyfikator tokenu uwierzytelniającego w systemie KSeF</xsd:documentation>
+									</xsd:annotation>
+								</xsd:element>
+
+								<xsd:element name="SkrotDokumentuUwierzytelniajacego" type="upo:TSkrotDokumentu">
+									<xsd:annotation>
+										<xsd:documentation>Wartość funkcji skrótu dokumentu uwierzytelniającego w postaci otrzymanej przez system (łącznie z podpisem elektronicznym)</xsd:documentation>
+									</xsd:annotation>
+								</xsd:element>
+							</xsd:choice>
+						</xsd:sequence>
+					</xsd:complexType>
+				</xsd:element>
+
+				<xsd:element name="OpisPotwierdzenia" minOccurs="0" maxOccurs="1">
+					<xsd:complexType>
+						<xsd:sequence>
+							<xsd:element name="Strona">
+								<xsd:annotation>
+									<xsd:documentation>Numer strony dokumentu UPO.</xsd:documentation>
+								</xsd:annotation>
+								<xsd:simpleType>
+									<xsd:restriction base="xsd:positiveInteger">
+										<xsd:whiteSpace value="collapse" />
+									</xsd:restriction>
+								</xsd:simpleType>
+							</xsd:element>
+							<xsd:element name="LiczbaStron">
+								<xsd:annotation>
+									<xsd:documentation>Całkowita liczba stron dokumentu UPO.</xsd:documentation>
+								</xsd:annotation>
+								<xsd:simpleType>
+									<xsd:restriction base="xsd:positiveInteger">
+										<xsd:whiteSpace value="collapse" />
+									</xsd:restriction>
+								</xsd:simpleType>
+							</xsd:element>
+							<xsd:element name="ZakresDokumentowOd">
+								<xsd:annotation>
+									<xsd:documentation>Początek zakresu dokumentów na stronie UPO (inclusive).</xsd:documentation>
+								</xsd:annotation>
+								<xsd:simpleType>
+									<xsd:restriction base="xsd:positiveInteger">
+										<xsd:whiteSpace value="collapse" />
+									</xsd:restriction>
+								</xsd:simpleType>
+							</xsd:element>
+							<xsd:element name="ZakresDokumentowDo">
+								<xsd:annotation>
+									<xsd:documentation>Koniec zakresu dokumentów na stronie UPO (exclusive).</xsd:documentation>
+								</xsd:annotation>
+								<xsd:simpleType>
+									<xsd:restriction base="xsd:positiveInteger">
+										<xsd:whiteSpace value="collapse" />
+									</xsd:restriction>
+								</xsd:simpleType>
+							</xsd:element>
+							<xsd:element name="CalkowitaLiczbaDokumentow">
+								<xsd:annotation>
+									<xsd:documentation>Całkowita liczba dokumentów na wszystkich stronach dokumentu UPO.</xsd:documentation>
+								</xsd:annotation>
+								<xsd:simpleType>
+									<xsd:restriction base="xsd:positiveInteger">
+										<xsd:whiteSpace value="collapse" />
+									</xsd:restriction>
+								</xsd:simpleType>
+							</xsd:element>
+						</xsd:sequence>
+					</xsd:complexType>
+				</xsd:element>
+
+				<xsd:element name="NazwaStrukturyLogicznej">
+					<xsd:annotation>
+						<xsd:documentation>Nazwa pliku XSD struktury logicznej dotycząca przesłanego dokumentu</xsd:documentation>
+					</xsd:annotation>
+					<xsd:simpleType>
+						<xsd:restriction base="xsd:token">
+							<xsd:minLength value="1"/>
+							<xsd:maxLength value="240"/>
+						</xsd:restriction>
+					</xsd:simpleType>
+				</xsd:element>
+				<xsd:element name="KodFormularza">
+					<xsd:annotation>
+						<xsd:documentation>Kod formularza przedłożonego dokumentu elektronicznego</xsd:documentation>
+					</xsd:annotation>
+					<xsd:simpleType>
+						<xsd:restriction base="xsd:token">
+							<xsd:minLength value="1"/>
+							<xsd:maxLength value="240"/>
+						</xsd:restriction>
+					</xsd:simpleType>
+				</xsd:element>
+				<xsd:element name="Dokument" maxOccurs="10000">
+					<xsd:complexType>
+						<xsd:sequence>
+							<xsd:element name="NipSprzedawcy" type="upo:TNip" >
+								<xsd:annotation>
+									<xsd:documentation>Nip sprzedawcy z faktury (Podmiot 1)</xsd:documentation>
+								</xsd:annotation>
+							</xsd:element>
+							<xsd:element name="NumerKSeFDokumentu">
+								<xsd:annotation>
+									<xsd:documentation>Numer identyfikujący fakturę w Krajowym Systemie e-Faktur (KSeF)</xsd:documentation>
+								</xsd:annotation>
+								<xsd:simpleType>
+									<xsd:restriction base="xsd:token">
+										<xsd:pattern value="([1-9](\d[1-9]|[1-9]\d)\d{7})-(20[2-9][0-9]|2[1-9]\d{2}|[3-9]\d{3})(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])-([0-9A-F]{6})-?([0-9A-F]{6})-([0-9A-F]{2})"/>
+									</xsd:restriction>
+								</xsd:simpleType>
+							</xsd:element>
+							<xsd:element name="NumerFaktury">
+								<xsd:annotation>
+									<xsd:documentation>Numer faktury</xsd:documentation>
+								</xsd:annotation>
+								<xsd:simpleType>
+									<xsd:restriction base="xsd:token">
+										<xsd:minLength value="1"/>
+										<xsd:maxLength value="256"/>
+									</xsd:restriction>
+								</xsd:simpleType>
+							</xsd:element>
+							<xsd:element name="DataWystawieniaFaktury">
+								<xsd:annotation>
+									<xsd:documentation>Data wystawienia faktury</xsd:documentation>
+								</xsd:annotation>
+								<xsd:simpleType>
+									<xsd:restriction base="xsd:date">
+										<xsd:minInclusive value="2006-01-01"/>
+									</xsd:restriction>
+								</xsd:simpleType>
+							</xsd:element>
+							<xsd:element name="DataPrzeslaniaDokumentu">
+								<xsd:annotation>
+									<xsd:documentation>Data przesłania dokumentu do systemu KSeF</xsd:documentation>
+								</xsd:annotation>
+								<xsd:simpleType>
+									<xsd:restriction base="xsd:dateTime">
+										<xsd:whiteSpace value="collapse"/>
+										<xsd:minInclusive value="2021-10-01T00:00:00Z"/>
+									</xsd:restriction>
+								</xsd:simpleType>
+							</xsd:element>
+							<xsd:element name="DataNadaniaNumeruKSeF">
+								<xsd:annotation>
+									<xsd:documentation>Czas i data wygenerowania numeru KSeF</xsd:documentation>
+								</xsd:annotation>
+								<xsd:simpleType>
+									<xsd:restriction base="xsd:dateTime">
+										<xsd:whiteSpace value="collapse"/>
+										<xsd:minInclusive value="2021-10-01T00:00:00Z"/>
+									</xsd:restriction>
+								</xsd:simpleType>
+							</xsd:element>
+							<xsd:element name="SkrotDokumentu" type="upo:TSkrotDokumentu">
+								<xsd:annotation>
+									<xsd:documentation>Wartość funkcji skrótu złożonego dokumentu</xsd:documentation>
+								</xsd:annotation>
+							</xsd:element>
+							<xsd:element name="TrybWysylki">
+								<xsd:annotation>
+									<xsd:documentation>Tryb wysyłki dokumentu do KSeF: Online lub Offline</xsd:documentation>
+								</xsd:annotation>
+								<xsd:simpleType>
+									<xsd:restriction base="xsd:string">
+										<xsd:enumeration value="Online"/>
+										<xsd:enumeration value="Offline"/>
+									</xsd:restriction>
+								</xsd:simpleType>
+							</xsd:element>
+
+						</xsd:sequence>
+					</xsd:complexType>
+				</xsd:element>
+			</xsd:sequence>
+			<xsd:attribute name="wersjaSchemy" type="xsd:string" use="optional">
+				<xsd:annotation>
+					<xsd:documentation>Wersja struktury logicznej UPO KSeF 2.0</xsd:documentation>
+				</xsd:annotation>
+			</xsd:attribute>
+		</xsd:complexType>
+		<xsd:unique name="NumerReferencyjnyDokumentuUnique">
+			<xsd:selector xpath="upo:Dokument"/>
+			<xsd:field xpath="upo:NumerKSeFDokumentu"/>
+		</xsd:unique>
+	</xsd:element>
+
+	<xsd:simpleType name="TNip">
+		<xsd:restriction base="xsd:token">
+			<xsd:pattern value="[1-9]((\d[1-9])|([1-9]\d))\d{7}"/>
+		</xsd:restriction>
+	</xsd:simpleType>
+
+	<xsd:simpleType name="TIdWewnetrzny">
+		<xsd:restriction base="xsd:token">
+			<xsd:pattern value="[1-9]((\d[1-9])|([1-9]\d))\d{7}-\d{5}"/>
+		</xsd:restriction>
+	</xsd:simpleType>
+
+	<xsd:simpleType name="TIdZlozonyVatUE">
+		<xsd:restriction base="xsd:token">
+			<xsd:pattern value="([1-9]((\d[1-9])|([1-9]\d))\d{7}-((AT)(U\d{8})|(BE)([01]{1}\d{9})|(BG)(\d{9,10})|(CY)(\d{8}[A-Z])|(CZ)(\d{8,10})|(DE)(\d{9})|(DK)(\d{8})|(EE)(\d{9})|(EL)(\d{9})|(ES)([A-Z]\d{8}|\d{8}[A-Z]|[A-Z]\d{7}[A-Z])|(FI)(\d{8})|(FR)[A-Z0-9]{2}\d{9}|(HR)(\d{11})|(HU)(\d{8})|(IE)(\d{7}[A-Z]{2}|\d[A-Z0-9+*]\d{5}[A-Z])|(IT)(\d{11})|(LT)(\d{9}|\d{12})|(LU)(\d{8})|(LV)(\d{11})|(MT)(\d{8})|(NL)([A-Z0-9+*]{12})|(PT)(\d{9})|(RO)(\d{2,10})|(SE)(\d{12})|(SI)(\d{8})|(SK)(\d{10})|(XI)((\d{9}|(\d{12}))|(GD|HA)(\d{3}))))"/>
+		</xsd:restriction>
+	</xsd:simpleType>
+
+	<xsd:simpleType name="TIdDostawcyUslugPeppol">
+		<xsd:restriction base="xsd:token">
+			<xsd:pattern value="P[A-Z]{2}[0-9]{6}"/>
+		</xsd:restriction>
+	</xsd:simpleType>
+
+	<xsd:simpleType name="TSkrotDokumentu">
+		<xsd:restriction base="xsd:token">
+			<xsd:minLength value="44"/>
+			<xsd:maxLength value="44"/>
+		</xsd:restriction>
+	</xsd:simpleType>
+
+	<xsd:simpleType name="TNumerReferencyjny">
+		<xsd:restriction base="xsd:token">
+			<xsd:pattern value="(20[2-9][0-9]|2[1-9][0-9]{2}|[3-9][0-9]{3})(0[1-9]|1[0-2])(0[1-9]|[1-2][0-9]|3[0-1])-([0-9A-Z]{2})-([0-9A-F]{10})-([0-9A-F]{10})-([0-9A-F]{2})"/>
+		</xsd:restriction>
+	</xsd:simpleType>
+
+</xsd:schema>

data/lib/ksef/upo/validation.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Ksef
+  module UPO
+    # The outcome of checking a UPO against the bundled schema (docs/REFERENCE.md §14.3).
+    #
+    # Two lists rather than one, because a UPO has a category of schema violation that is
+    # **upstream's fault and expected**: `upo-v4-3.xsd` fixes the receiving party's name to
+    # `"Ministerstwo Finansów"`, while every non-production environment appends a marker. All
+    # six of upstream's own worked examples fail upstream's own schema on exactly that
+    # element, and nothing else.
+    #
+    # So those go in {#warnings} and everything else in {#errors}, and {#valid?} ignores the
+    # warnings. A validator that reported them as errors would reject every UPO that TEST
+    # and DEMO issue — which is the trap this gem would otherwise have walked into, having
+    # already built strict XSD validation for FA(3).
+    Validation = Data.define(:errors, :warnings, :receiving_party) do
+      # True when nothing but the expected environment-marker discrepancy was found.
+      def valid? = errors.empty?
+
+      # True when the document also matched the `fixed` value — which in practice means it
+      # came from production, or from an environment that has stopped appending a marker.
+      def clean? = errors.empty? && warnings.empty?
+
+      # True when the only complaint was the known upstream defect.
+      def environment_marked? = errors.empty? && !warnings.empty?
+
+      def messages = errors + warnings
+
+      def to_s
+        return "valid" if clean?
+
+        "#{errors.size} error(s), #{warnings.size} warning(s)"
+      end
+    end
+  end
+end