facturx

# Changelog

All notable changes to this project are documented here.
Format based on [Keep a Changelog](https://keepachangelog.com/).

## [0.7.0] - 2026-08-31

### Security
- **`:decimal` moves to `~> 3.0`, a breaking dependency change.** Every 2.x is
  affected by CVE-2026-32686 (GHSA-rhv4-8758-jx7v): the exponent of a parsed
  decimal was unbounded, so `Decimal.parse("1e10000000")` succeeded and the
  first arithmetic on the result — comparing two totals, say — allocated a
  ten-million-digit coefficient and could exhaust the BEAM's memory on a single
  request. `Facturx.CII.parse/1` takes invoices from third parties and handed
  such a value straight back, so this was reachable through the public API on
  untrusted input. decimal 3 caps the exponent at 6144, the IEEE 754 decimal128
  Emax. Found by `mix hex.audit`, on its first run in CI.

  A wider requirement (`~> 2.0 or ~> 3.0`) was rejected: the resolver would keep
  picking 2.x in existing projects, which is precisely the case that needs
  fixing.

- **A non-finite amount no longer reaches an `Invoice`.** `Decimal.parse/1`
  accepts `"NaN"` and `"Infinity"`, and a hostile document could put either in a
  monetary field — where it would propagate through the caller's arithmetic and
  come back out of `build/2` as `<ram:GrandTotalAmount>NaN</ram:GrandTotalAmount>`.
  `parse/1` now reads those as absent, like any other malformed amount.

### Fixed
- **A stream is no longer cut short by its own contents.** `/Length` is now
  authoritative in both `Facturx.Embed` and `Facturx.Extract`; `endstream` and
  `endobj` are no longer located by scanning from the front of the object.
  Stream data does contain those bytes: deflate emits stored blocks that copy
  their input verbatim, and an uncompressed XMP packet can simply mention the
  word. Two failures followed, both silent until now — an embedded payload came
  back as `{:error, :inflate_failed}`, and a base whose `/Metadata` contained the
  keyword had its XMP truncated before promotion, so the output PDF lost the
  Factur-X extension schema without any error being raised. Found by the new
  property tests.

- **`Facturx.Embed.embed/3` no longer raises.** It declared
  `{:ok, binary()} | {:error, term()}` while `raise "unbalanced dictionary"` and
  a `MatchError` (no `<<` after the trailer) could both reach the caller. A
  malformed PDF is an input, not a programming error: the two sites now return
  `{:error, :malformed_dictionary}` / `{:error, :dictionary_not_found}`, and both
  `embed/3` and `Facturx.Extract.extract/1` carry a last-resort `rescue`. Pinned
  by a property over arbitrary truncations and junk suffixes.
- **Encrypted PDFs are refused instead of misread**, and only on the strength
  of a trailer dictionary. Nothing looked for
  `/Encrypt`, so an encrypted file failed to inflate or produced meaningless
  bytes. Both paths now return `{:error, :encrypted_pdf_unsupported}` — and on
  extraction that is reported in place of `:no_embedded_file`, since an
  unreadable attachment is not an absent one.

### Added
- **PDF 1.5+ files are read and written.** Cross-reference streams
  (`/Type /XRef`) and object streams (`/ObjStm`) were refused outright, which
  ruled out most current producers. Both are supported now:

    * `Facturx.Extract` builds its object index by scanning for `N G obj` and
      then expanding every object stream. It never reads the cross-reference
      table — a scan is what survives an incremental update, where the previous
      revision's table still points at the objects the update replaced.
    * `Facturx.Embed` writes the update back in the form the base uses, and never
      a hybrid: a classic table appended to a stream-based document is what a
      strict PDF/A reader is entitled to reject. A catalog compressed inside an
      object stream is read from there and rewritten at top level.

  Verified on a real file rather than a synthetic one. No tool on the development
  machine writes cross-reference streams — Ghostscript's pdfwrite emits a classic
  table, pypdf's writer likewise — so `dev/tools/xref_stream_base.py`
  re-serialises the PDF/A base with an object stream and a cross-reference
  stream, and `mix facturx.harness` has veraPDF vouch for that base before
  concluding anything from what we write to it. The output is PDF/A-3b with zero
  failed rules, and the Python `akretion/factur-x` reference navigates our
  cross-reference stream and extracts the payload byte-identically — which is
  what says it is correct rather than merely self-consistent.

- **`Facturx.totals/2` derives the document arithmetic.** The line net amounts,
  the VAT breakdown grouped by category and rate, and BT-106 to BT-115 —
  `BR-CO-10` to `BR-CO-17` and the per-category basis rules. None of it is
  checked by the XSD; until now the caller computed all of it by hand and found
  out from a Schematron report, or from a rejected invoice.

  A figure the caller supplied is kept, and a disagreement is **reported**
  rather than resolved: `{:error, {:totals_mismatch, [{path, given, computed}]}}`.
  Pass `overwrite: true` to take the computed figures. `:prepaid` (BT-113) and
  `:rounding` (BT-114) are never derived — nothing in the invoice determines
  them.

- **`Facturx.new/1` builds an invoice from a plain map**, reporting every problem
  at once rather than the first, and coercing integers and strings to `Decimal`.
  **Floats are refused.** `Decimal.from_float/1` is faithful, so this is not
  about that conversion: a float reaching the boundary has usually been through
  float arithmetic already, and `0.1 + 0.2` is `0.30000000000000004` before
  anything here can see it. Accepting it would record the drift and call it
  validated.

  `totals/2` refuses rather than guesses. An invoice with **no lines** returns
  `{:error, :no_lines}`: everything it derives is founded on the line amounts, and
  deriving zero would be a lie — a BASIC WL or MINIMUM invoice carries no lines
  and still has a VAT liability. A breakdown entry matching no line returns
  `{:error, {:orphan_tax_breakdown, …}}` rather than being dropped. An amount
  that is not a `Decimal` returns `{:error, {:not_a_decimal, path, value}}`,
  because this module both adds and sorts them and coercing quietly is the float
  mistake again.

  `new/1` also requires `:vat_category` and `:vat_rate` on every line (BR-CO-4).
  Without them a line cannot be placed in any VAT breakdown group: it would count
  towards the invoice total while contributing no VAT, which is a wrong invoice
  rather than an incomplete one.

  Both are optional — `build/2` and `generate/3` still take a bare struct or map.
  `docs/adr/0001-perimetre-et-architecture.md` records why the original "no
  struct-level validation" decision was revised.

- `Facturx.CII.build/2` refuses a non-finite amount rather than emitting
  `<ram:GrandTotalAmount>NaN</ram:GrandTotalAmount>`. The list of fields that
  hold an amount is now shared by `new/1`, the totals and the builder, so the
  field none of them knew about cannot be the one carrying the NaN.

- **The MINIMUM, BASIC WL and BASIC profiles are real.** `Facturx.CII.build/2`
  used to emit the same document whatever the profile and change only the
  guideline URN, so those three produced non-conformant files carrying a
  conformant claim — and, their schemas not being bundled, nothing in the library
  could tell. `build/2` now restricts what it emits to what each profile allows,
  and all five XSDs ship (80 KB in total), along with all five schematrons. Each
  profile is checked against its own schema *and* its own rule set in CI.

  On the schematrons: `priv/` is now 4.4 MB on disk, which is what made the
  first pass bundle only two of them. That was the wrong unit — the published
  tarball goes from 217 KB to 295 KB, the five rule sets costing 78 KB between
  them. `{:error, {:schematron_not_bundled, _}}` is now reachable only for a
  profile that does not exist.

  Two findings from that work, neither visible in the XSD:

    * BT-111 (the VAT total in the accounting currency) only goes where BT-6
      goes. MINIMUM has no `TaxCurrencyCode`, so emitting it there stated an
      amount in a currency the document never declared. Every profile's schema
      allows two `TaxTotalAmount`; the build/parse fixed point is what caught it.
    * In MINIMUM the postal address and the tax registration belong to the seller
      alone — required there (BR-08, BR-09), refused on the buyer. The XSD types
      every party alike and accepts both; only the schematron says otherwise.

- `mix facturx.harness`: the PDF/A-3 conformance and Python-parity oracle, until
  now a Livebook run by hand. veraPDF over the output of all five profiles, plus
  byte parity of the payload against `akretion/factur-x`. It lives under `dev/`,
  compiled in `:dev` only, so it never reaches the published package.
- Property-based tests (`stream_data`): the build/parse fixed point over
  randomly pruned invoices, `Decimal` value *and* scale preservation, XMP
  promotion idempotence and well-formedness, and PDF payload round-trips over
  arbitrary bytes.
- Quality gates that did not exist: Dialyzer (the public API is almost entirely
  `@spec`-ed and nothing checked those specs), Credo, and coverage.
- CI now runs an OTP/Elixir matrix down to the `~> 1.15` floor declared in
  `mix.exs`, which had never been compiled.

### Changed
- The Saxon image passes `--timeout 300000`. Its help text says "the maximum
  time a transformation is allowed to run" without a unit, and the unit is
  **milliseconds** — `--timeout 300` gives 300 ms and fails nearly every
  transformation. It needs raising because the stock default is short enough that
  the emulated arm64 run exceeds it under concurrent requests.
- `Facturx.ValidateTest` is no longer `async`. Every `:saxon` test posts to one
  shared server, and sixteen concurrent transformations of a multi-megabyte
  stylesheet is how that timeout started firing, as an HTTP 400 on whichever test
  was unlucky. The concurrency bought nothing: the work is all on the far side of
  one socket.
- The byte-level PDF rules shared by `Facturx.Embed` and `Facturx.Extract` —
  where a stream stops, where a dictionary closes, how an EOL is skipped — move
  to a single internal module, Facturx.PDF. They had been written twice and had
  to be fixed twice for the same bug.
- `README.md` documents which PDFs the library accepts and which it refuses,
  error tuple by error tuple, plus the one limit no error can express: an
  incremental update invalidates an existing digital signature.
- `Facturx.XSD.Cache` is documented rather than hidden, clearing the two
  long-standing ExDoc warnings.

## [0.6.0] - 2026-08-11

Full coverage of the French regulatory Flux 1 data set — **96/116 → 116/116** —
and the first breaking change since 0.1.0. Read the note on `:notes` below
before upgrading.

### Changed — breaking
- **A line's `:note` becomes `:notes`, a list**, taking the same
  `%{content: …, subject_code: …}` shape as the document-level field. Callers
  passing `note: "…"` must pass `notes: [%{content: "…"}]`.

  What the profile allows is no longer the caller's problem:

    * `:en16931` — one note, content only. Extra notes and any `:subject_code`
      are dropped, because emitting them gets the document rejected.
    * `:extended` — as many notes as you like, each free to carry a subject code.

  That covers **BT-127-00** (the repeated container) and **EXT-FR-FE-183** (the
  subject code), the first two of the twenty items annexe B still listed as not
  emitted.

  Note the consequence for round-tripping: an EN 16931 document cannot return
  what a caller supplied if that caller supplied more than the profile carries.

### Added
- **A line may carry its own delivery address and date** — `:ship_to` and
  `:delivery_date` on a line (`EXT-FR-FE-BG-10` and `EXT-FR-FE-BG-11` with their
  children), for the multi-delivery case where one line ships elsewhere, or on
  another date, than the document says. Same shapes as their document-level
  counterparts, both `0..1`, both `:extended` only.

  With these, **annexe B reaches 116/116** — every regulatory Flux 1 data item is
  emitted. Note the condition: 20 of them (the 19 `EXT-FR-FE-*` plus
  `BT-127-00`) exist **only in `:extended`**. `Facturx.build(inv)` still emits
  96/116 and drops the rest on purpose, rather than produce a document the schema
  and the platform would reject.

- **A line may reference a preceding invoice** — `:preceding_invoice` on a line
  (`EXT-FR-FE-BG-06` / `-136` / `-138`), what a line points at to net off a down
  payment invoiced earlier. Singular, not a list: the CII element is `0..1` at
  line level (`minOccurs="0"`, no `maxOccurs`), unlike the document-level
  `:preceding_invoices`.

  Emitted in `:extended` only, being a French extension. Two things the compiler
  will not tell you: `LineTradeSettlementType` puts it **after** the line
  monetary summation, and its date is a `qdt:DateTimeString` — the `qdt`
  namespace, not the `udt` every other date in the document uses.


- **The EXTENDED profile XSD is bundled** (`priv/xsd/extended/`), so
  `Facturx.validate_xsd/2` now accepts an EXTENDED document instead of answering
  `{:error, {:xsd_not_bundled, :extended}}`. The schema is picked from the
  document's own guideline URN, so no option is needed. This is the groundwork
  for the line-level French extensions `EXT-FR-FE-*`, which the EN 16931 schema
  rejects as out of profile.

- **The EXTENDED schematron is bundled too** (`priv/schematron/extended/`), so
  `Facturx.validate/2` checks an EXTENDED document's business rules the way it
  already did for EN 16931 — the step that catches what no XSD can see. The
  Docker image carries the matching code-list DB.

  Cost of both, measured on the published artifact rather than on disk: the Hex
  package goes from **125 KB to 209 KB**. XSLT compresses well, so the 2.2 MB
  those files occupy unpacked is not what users download.

### Fixed
- **Streams whose data ends on CR or LF were truncated by one byte.** Both
  `Facturx.Embed` and `Facturx.Extract` used to guess where a stream stopped, by
  removing the end-of-line that precedes `endstream`. When the data itself ended
  with `\r` or `\n` that guess ate a real byte. For a deflate stream the last
  byte is the low byte of the adler32, so it hit roughly **one document in
  256**: `Facturx.extract/1` returned `{:error, :inflate_failed}` on a file it
  had just produced, and a base whose `/Metadata` was deflated and ended the
  same way made `Facturx.generate/3` fail outright.

  Both now take `/Length` when it is a direct integer *and* lands on
  `endstream` with nothing but an end-of-line in between, falling back to the
  scan otherwise — producers do get `/Length` wrong, and trusting a wrong one
  would truncate where the scan worked.

### Changed
- **The PDF paths are now exercised by CI.** `Facturx.Embed` and
  `Facturx.Extract` were only ever tested against private fixtures under
  `test/fixtures/local/`, which are not committed — so every run outside the
  author's machine skipped them silently. A new test-only builder
  (`test/support/pdf_builder.ex`) assembles a minimal PDF/A base in the test
  process, and 22 tests now cover the round-trip, the XMP promotion, the catalog
  merge branches (`/Names`, `/AF`, `/PageMode`, and the shapes that are refused
  rather than corrupted), the input contract, the cross-reference offsets and
  `/Prev` chain of the incremental update, and the truncation bug above.

  The synthetic base is a structural fixture, not a PDF/A producer: real
  conformance is still proven only by the `:local` tests, which run veraPDF over
  real producer output.

- **The coverage count is now verified rather than declared.** The "Émis"
  column of annexe B (`docs/reference/mapping-cii-flux1.md`) is written by hand,
  and the count derived from it appears in the README, both ADRs and this file;
  the annexe itself records a past drift on BT-111. `Facturx.MappingAnnexeTest`
  reads the table and evaluates each of the 116 CII paths against the document
  `Facturx.CII.build/2` produces from `Facturx.TestInvoice.maximal/0`. The
  maximal invoice is also asserted XSD-valid and to round-trip exactly, which is
  what makes it a fair witness.

  What is checked is the **occurrence count**, not mere existence: nine paths are
  claimed by two rows each — BT-110 and BT-111 are both `ram:TaxTotalAmount`,
  told apart only by their `currencyID`, and the four allowance/charge families
  only by their `ChargeIndicator`. Existence alone would let one of each pair
  vanish unnoticed. A path carrying fewer nodes than it has ticked rows, or a
  path with no ticked row carrying any, fails the suite.

## [0.5.0] - 2026-07-30

The French regulatory core, complete within the EN 16931 profile: **50/116 → 96/116**
data items emitted. Additive throughout — new fields default to empty, so existing
callers see byte-identical output.

### Added
- **Notes** (BG-1) — `Facturx.Invoice.notes`, a list of
  `%{content: …, subject_code: …}` (BT-22 / BT-21). CII orders the content before
  the code, the reverse of the BT numbering.
- **Invoicing period** (BG-14) — `Facturx.Invoice.billing_period`, a
  `%{start_date: …, end_date: …}` (BT-73 / BT-74). Either date may stand alone; an
  empty map emits nothing.
- **Gross price and price discount** (BT-148 / BT-147) — `:gross_price` and
  `:price_discount` on a line. `BT-148` was the **only unconditional gap** left in
  the regulatory core: mandatory inside `BG-29`, which is itself mandatory. A
  discount without a gross price is dropped, the CII price container requiring an
  amount.
- **VAT exemption reason** (BT-120 / BT-121) — `:exemption_reason` and
  `:exemption_reason_code` on a VAT breakdown entry. Note that `BR-E-01` also wants
  a line in the matching exempt category; the XSD cannot see that, the schematron
  can, and a test now pins it.

- **Preceding invoice references** (BG-3) — `Facturx.Invoice.preceding_invoices`, a
  list of `%{number: …, issue_date: …}` (BT-25 / BT-26). This is what a final
  invoice points at to net off down payments already invoiced, so it goes with the
  `B4`/`S4`/`M4` invoicing frameworks. Careful with BT-26: `FormattedIssueDateTime`
  is a `qdt:FormattedDateTimeType`, so its child is `qdt:DateTimeString` — every
  other date in the document is `udt:`. The reference block is also emitted *after*
  the monetary summation, per `HeaderTradeSettlementType`.

- **Allowances and charges** (BG-20 / BG-21 at document level, BG-27 / BG-28 on a
  line) — `:allowances` and `:charges`, both on the invoice and on a line. All four
  map to one CII element told apart by `ChargeIndicator`; which list you use decides
  it, so there is no flag to get wrong. Each entry takes `:amount` (the only
  required field), `:basis_amount`, `:percent`, `:vat_category`, `:vat_rate`,
  `:reason` and `:reason_code`.
- **The remaining document totals** — `:allowance_total` (BT-107),
  `:charge_total` (BT-108), `:prepaid` (BT-113) and `:rounding` (BT-114) on
  `:totals`. `:prepaid` is what down payments already covered, so it pairs with
  `:preceding_invoices`.

  ⚠️ Two things only the schematron enforces, and which the XSD accepts happily:
  every allowance/charge needs a **`:reason` or `:reason_code`** (`BR-33`,
  `BR-38`, `BR-42`, `BR-44`) — an amount alone gets the invoice rejected; and
  document-level entries must **match their totals**, which feed
  `:tax_basis_total` in turn (`BR-CO-11`, `BR-CO-12`, `BR-CO-13`). That arithmetic
  is not computed for you.

  Note the wire order, which does not follow the numbering: CII emits
  `ChargeTotalAmount` **before** `AllowanceTotalAmount`, and
  `TradeAllowanceChargeType` puts `ReasonCode` before `Reason`.

- **Line invoicing period** (BG-26) — `:billing_period` on a line, same shape as
  the document-level one (BT-134 / BT-135). Reuses the BG-14 emitter, the CII type
  being identical; what needed care was its position, after the line's VAT and
  before its allowances.

  A note on `BR-FX-EN-04`, which lists BT-72, BG-14 and BG-26 and reads like a
  general rule: it is not one. Its template only matches invoices whose seller
  *and* buyer are in DE, so it never fires on a French invoice, and its assertion
  is a conjunction — a line period satisfies the first half only, the second still
  wanting BT-72 or a non-empty delivery container.
- **The last five core items** — `:tax_representative` (BG-11, whose BT-63 VAT id is
  the point), `:global_id` on a party (BT-29d, the SIREN of an *assujetti unique*,
  scheme `0231`), the full delivery address (`:line_two`, `:line_three`,
  `:country_subdivision` — BT-76 / BT-165 / BT-79), `:note` on a line (BT-127) and
  `:tax_currency` + `:tax_total_in_tax_currency` (BT-6 / BT-111).

  ⚠️ Two constraints the schematron caught and the XSD does not see:

  - A **line note must not carry a subject code**. That is `EXT-FR-FE-183`, a French
    extension on the target trajectory, not part of EN 16931 — emitting one gets the
    invoice rejected. Hence `:note` on a line is a plain string, with no way to ask
    for one.
  - **`:tax_currency` must differ from `:currency`.** BT-110 and BT-111 are two
    occurrences of the same element, told apart by their `currencyID`; identical
    currencies make them indistinguishable and trip `BR-53`, cascading into
    `BR-CO-15`.

  Note also that the scheme defaults (`0002`, `0231`) are written into the XML, so
  parsing a document built without them returns them anyway — the document is
  unchanged, the struct normalised.

- **Payment means** (BG-16) — `Facturx.Invoice.payment_means`, a list covering the
  credited account (`:iban` / `:account_name` / `:account_id`, BT-84 / BT-85), its
  institution (`:bic`, BT-86), a direct debit's debited account (`:payer_iban`,
  BT-91) and card details (`:card_id` / `:cardholder_name`, BT-87 / BT-88), plus
  BT-81 / BT-82. **Not** part of the regulatory Flux 1 set — the tax administration
  does not need them — so they do not enter the 96/116 count; but an invoice without
  payment details is unusable in practice.

  ⚠️ `:card_id` must be **at most 10 characters** (rule `BR-51`, the PCI standard of
  showing at most the first 6 and last 4 digits). A masked 16-character PAN like
  `"************1234"` is *too long* and gets the invoice rejected. The XSD accepts
  any length, so only the schematron catches it — pinned by a test.
- **Rule G1.60 is now enforced**, alongside the G1.02 closed list and under the
  same `:validate_business_process` opt-in. A `B4`/`S4`/`M4` framework means "final
  invoice after a down payment", so it cannot be paired with a down-payment
  `:type_code` (`386`, `500`, `503`); that returns
  `{:error, {:final_invoice_type_conflict, %{business_process: …, type_code: …}}}`.
  Being a cross-field constraint, **neither the XSD nor the EN 16931 schematron
  sees it** — without the check, the first sign would be a platform refusing the
  invoice. The legitimate combinations still pass: a down-payment invoice under a
  standard framework (`S1` + `386`), and a final invoice with an ordinary type.

Coverage of the regulatory Flux 1 data set goes from 50/116 to **96/116** — see
`docs/reference/mapping-cii-flux1.md`.

### Added (tooling)
- `docker/` — a Saxon image for the bundled Schematron. It starts Saxon with
  `--insecure` (required for the `document()` call that loads the code-list DB)
  and bakes the DB in, so validation no longer fetches it over the network on
  every call. Point `:codedb_url` at `file:///opt/facturx/FACTUR-X_EN16931_codedb.xml`.
  Not shipped in the Hex package.
- **Tests against the bundled EN 16931 Schematron**, over invoices the library
  builds — until now the `:saxon` tests only exercised the HTTP transport with
  toy stylesheets, so not a single business rule was covered. Notably, one test
  pins that a BT-8 outside UNTDID 2475 is rejected *even though the XSD accepts
  it*: that is the exact defect shipped in 0.3.0, which no automated check could
  have caught.
- A `schematron` CI job running those tests. It builds the image from the commit
  under test rather than pulling a published one, so the ruleset always matches
  the code and nothing is redistributed.

## [0.4.0] - 2026-07-30

### Fixed
- **`validate/2` reported every conformant invoice as invalid.** SVRL findings
  were collected without looking at their severity, so a single `flag="warning"`
  produced `{:error, {:invalid, …}}`. The EN 16931 schematron flags
  `PEPPOL-EN16931-R008` ("no empty elements") as a warning, and CII *requires*
  `ram:ApplicableHeaderTradeDelivery` even when there is no delivery data — so any
  invoice built without `:ship_to` or `:delivery_date` tripped it and could never
  come back valid. Warnings also drowned out real errors in the same list.

### Changed (breaking)
- `Facturx.validate/2` gains a third return shape, for documents that are valid
  but carried non-blocking findings:

  ```elixir
  {:ok, :valid}
  {:ok, {:valid_with_warnings, findings}}   # new
  {:error, {:invalid, errors}}
  ```

  Callers matching on the previous two shapes must handle the new one.

  ⚠️ **Read this before upgrading.** The break has a quiet half. Code matching the
  old shapes raises a `MatchError` and fails loudly, which is fine — but code
  written as `with {:ok, _} <- Facturx.validate(xml)` or
  `match?({:ok, _}, Facturx.validate(xml))` does **not** fail. It silently starts
  accepting invoices that 0.3.0 rejected, because `{:ok, _}` can now carry failed
  assertions. Three rules are affected — every assertion the bundled schematron
  flags as `warning` — and two of them are substantive, not cosmetic:

  | Rule | What it checks | Nature |
  |---|---|---|
  | `PEPPOL-EN16931-R008` | document must not contain empty elements | cosmetic |
  | `BR-29` | if BT-73 and BT-74 are both given, BT-74 must be ≥ BT-73 | business rule |
  | `BR-FX-EN-04` | an invoice that is not a down payment (386) must carry BT-72, BG-14 or BG-26 | business rule |

  The severities are the schematron's own, not this library's choice: 0.3.0 simply
  ignored them and treated all three as blocking. If you relied on that, match on
  `{:ok, :valid}` specifically, or inspect the findings returned by
  `{:ok, {:valid_with_warnings, findings}}`.
- Findings gain a `:flag` key carrying the SVRL severity (`nil` when the rule
  declares none). Only `"warning"` and `"info"` are non-blocking; anything else,
  **including an absent flag**, counts as an error — defaulting to "invalid" is
  the safe way round. In the bundled schematron only 3 of 621 assertions are
  flagged, all as `warning`.

### Notes
- Running the bundled Schematron locally needs Saxon's `--insecure` flag, which
  permits the `document()` call that loads the code-list DB. Mind that the image's
  `CMD` must be rebuilt rather than appended to:

  ```
  docker run -d --rm -p 5000:5000 ghcr.io/willemvlh/saxon-server \
    /bin/sh -c 'java $JAVA_OPTS -jar app.jar --insecure'
  ```

## [0.3.0] - 2026-07-30

Support of the two data items the French e-invoicing mandate requires on top of
plain EN 16931. Both fields default to `nil` and emit nothing, so **generated
output is unchanged** for callers that don't set them.

### Changed
- `parse/1` now populates `business_process` (BT-23), which in 0.2.0 was always
  `nil`. Emitting is unaffected: the French closed-list check is **opt-in**, so
  `Facturx.parse(xml) |> Facturx.build()` still succeeds on a non-French document
  (a German ZUGFeRD or Peppol invoice carrying its own BT-23).

### Added
- `Facturx.Invoice.business_process` — **BT-23** "cadre de facturation"
  (`ram:BusinessProcessSpecifiedDocumentContextParameter/ram:ID`), mandatory
  `1..1` for the mandate and previously not emitted at all. This is the field
  that carries the nature of the transaction (goods / services / mixed) and
  therefore VAT chargeability.
- `Facturx.Invoice.tax_due_date_type_code` — **BT-8** VAT point date code
  (`ram:ApplicableTradeTax/ram:DueDateTypeCode`), i.e. the option to pay VAT on
  debits. Document-level and replicated onto every VAT breakdown entry, which
  satisfies rule S1.13 by construction.
- `Facturx.business_processes/0` — the closed list of 13 BT-23 codes of rule
  G1.02 (`B1`/`S1`/`M1`, `B2`/`S2`/`M2`, `B4`/`S4`/`M4`, `S5`, `S6`, `B7`/`S7`).
- `Facturx.vat_point_date_codes/0` — the BT-8 code list, `5` (invoice date, VAT on
  debits) / `29` (delivery date, goods) / `72` (payment date, VAT on collection).
  BT-8 is validated against it **by default** (`:validate_vat_point_date`, set it
  to `false` to reproduce a nonconformant third-party document), returning
  `{:error, {:invalid_vat_point_date_code, code}}`. The restriction comes from
  EN 16931 (`BR-CL-06`), not from France, and the enumeration ships in
  `priv/schematron/en16931/FACTUR-X_EN16931_codedb.xml` (code list `id=28`). Note
  that `3`/`35`/`432` are the **UBL** (UNTDID 2005) values and are invalid in CII
  — the XSD accepts them (unrestricted `xs:token`) but the Schematron does not.
- Per-entry BT-8: a `tax_breakdown` entry may carry its own `:due_date_type_code`,
  which overrides the document-level field. EN 16931 allows the code to differ
  between VAT breakdown entries even though French rule S1.13 does not, so parsing
  hoists a uniform code to the document level and keeps divergent codes per entry
  instead of collapsing them onto one value.

### Fixed
- A `:tax_due_date_type_code` with an empty `:tax_breakdown` had nowhere to be
  emitted and was dropped silently; `build/2` now returns
  `{:error, {:vat_point_date_unemittable, code}}`.
- `""` in `:business_process` or `:tax_due_date_type_code` produced an empty
  element that parsed back as `nil`, breaking the round-trip invariant. Empty
  strings are now treated as absent, like `nil`.
- `Facturx.CII.build/2` output is now covered against the bundled XSD by the test
  suite. That path had never been exercised: element order had only ever been
  checked by reading the schema.
- `:validate_business_process` option on `build/2` (and therefore `generate/3`),
  **defaulting to `false`**, also settable once via
  `config :facturx, Facturx.CII, validate_business_process: true` (the option
  overrides the config in both directions). Enabled, an unknown BT-23 code
  returns `{:error, {:invalid_business_process, code}}`. It is opt-in because
  BT-23 is an EN 16931 term whose values are *not* restricted to the French list
  — Peppol, Chorus Pro and other national specifications use their own.
- `parse/1` reads both fields back, preserving the `parse(build(inv)) == inv`
  round-trip invariant.
- Documentation, sourced against the **v3.2 (2026-04-30)** external
  specifications: `docs/reference/reforme-fr.md` (business reference, primary
  sources, and three widely repeated claims that the sources contradict),
  `docs/reference/mapping-cii-flux1.md` (all 116 regulatory Flux 1 data items
  mapped to CII, with coverage status — 50 emitted), and ADR 0002.

### Notes
- No new schema is bundled: BT-23 and BT-8 are already declared `minOccurs="0"`
  in the EN 16931 XSD shipped since 0.2.0.
- Rule **G1.60** (a `B4`/`S4`/`M4` framework forbids `type_code` `386`/`500`/`503`)
  is **not** enforced — the closed list is not full BT-23 conformance.
- There is no `:extended_ctc_fr` profile, deliberately. The PPF profile is
  declared by the transmitted file's name prefix (`Base_`/`Full_`, rule S1.06),
  which is the caller's responsibility; the URN
  `…#conformant#urn.cpro.gouv.fr:1p0:extended-ctc-fr` found in much secondary
  writing does not appear anywhere in the official specifications.

## [0.2.0] - 2026-07-24

### Added
- `Facturx.XSD.validate/2` + `Facturx.validate_xsd/2`: validate CII XML against
  the EN 16931 **XSD**, in **pure Elixir, in-process** via OTP `:xmerl_xsd` — no
  external tool, no network, no Port. Catches missing mandatory elements, wrong
  data types, unexpected elements, wrong order and cardinality. Bundled schema:
  `priv/xsd/en16931/`.
- `Facturx.XSD.Cache` (supervised): compiles each bundled schema once and shares
  it via `:persistent_term`, so validation runs in the caller process — in
  parallel, ~0.6 ms/call (vs ~5 ms recompiling per call). Falls back to per-call
  compilation in a short-lived task when no cached schema is available.

### Security
- XSD validation treats input as untrusted: a `<!DOCTYPE>` is rejected and
  external entity/DTD fetching is disabled, preventing XXE and entity-expansion
  ("billion laughs") attacks.

### Notes
- `:xmerl_xsd` is a partial XSD 1.0 implementation; it validates the CII EN 16931
  schema well but is not a guarantee of full XSD 1.0 conformance. Business-rule
  validation remains in `Facturx.Validate` (Schematron).

## [0.1.0] - 2026-07-24

First public release. Pure-Elixir generation and extraction of Factur-X /
ZUGFeRD invoices (EN 16931), with optional Schematron validation.

### Added
- Project skeleton and scope ADR.
- Public API surface: `Facturx.generate/3`, `extract/1`, `parse/1`, `build/2`, `validate/2`.
- `Facturx.Extract.extract/1`: locate and decode the embedded CII XML from a
  Factur-X PDF (classic xref), with profile detection and refc-binary-safe
  results (`:binary.copy`). Validated against a real EN 16931 fixture.
- `Facturx.Embed.embed/3` + `Facturx.generate/3`: embed CII XML into a PDF/A-2
  or PDF/A-3 base via an incremental update (embedded-file stream, `/Filespec`,
  `/AF`, `EmbeddedFiles` name tree, overridden catalog + XMP). Promotes PDF/A-2
  → PDF/A-3; refuses PDF/A-1 and non-PDF/A input. Output verified
  **PDF/A-3b-compliant by veraPDF** and semantically identical to the Python
  reference (`akretion/factur-x`).
- `Facturx.Xmp.promote/3`: bump `pdfaid:part` 2 → 3 and inject the Factur-X
  extension schema + `fx:*` properties.
- `Facturx.CII.build/2` + `parse/1`: map `Facturx.Invoice` (Decimal amounts) to
  and from EN 16931 CII XML (header, seller/buyer/ship-to, lines, VAT breakdown,
  monetary totals). Output validated against the CII XSD; `build`/`parse`
  round-trip the modelled fields (`build` fills conventional defaults — unit
  `C62`, legal scheme `0002` — which `parse` reads back).
  `Facturx.generate/3` now accepts an `Invoice` struct
  directly (struct → CII → embed → veraPDF-valid Factur-X).
- `Facturx.Validate.validate/2`: optional EN 16931 Schematron validation. Sends
  the XML + bundled compiled schematron (`priv/schematron/`) to a Saxon server
  over `multipart/form-data` (via optional `:req`) and interprets the SVRL report
  into violations. Supports a `:xsl` override for custom rule sets. Proven
  end-to-end against a live Saxon server. Note: the EN 16931 XSLT resolves a
  code-list DB via `document(...)`; the Saxon server must be configured to allow
  that URI (`:codedb_url` overrides the location).

### Known limitations
- Classic cross-reference tables only; object/xref streams (`/Type /ObjStm`,
  `/Type /XRef`) are not yet handled (`Extract` reports
  `:object_streams_unsupported`, `Embed` `:xref_streams_unsupported`).
- `Embed` uses an incremental update, so the pre-promotion (part-2) XMP remains
  earlier in the file; conformant readers resolve the latest object (veraPDF
  confirms). A full-rewrite mode may be added later.
- `Embed` merges `/AF`, `/Names` and `/PageMode` into the existing catalog
  (preserving e.g. `/Dests`). Shapes it cannot safely merge in place are
  refused, never corrupted: an indirect `/AF`/`/Names` reference, or a base that
  already carries embedded files (re-embedding into a Factur-X).