Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning. Every package in the pain001 suite ships the same version number — the core, pain001-mcp, pain001-lsp, pain001-loader-xlsx and pain001-loader-mt101. If the core is at 0.0.60 then so is this package, so there is no compatibility table to consult. Versions advance in 0.0.1 steps along the 0.0.x line; 0.1.0 follows 0.0.999.

PAIN001_API_VERSION still guards the plugin contract at load time — a plugin built against a newer contract than its host raises rather than misbehaving — but it is a safety net, not the versioning rule. See pain001.suite, which a daily job checks against PyPI.

[Unreleased]

[0.0.90] - 2026-11-16

Changed

  • Release 0.0.90 in lockstep with the pain001 suite.

  • Requires pain001 0.0.90, the suite version this release ships in lockstep with.

[0.0.89] - 2026-11-16

Changed

  • Release 0.0.89 in lockstep with the pain001 suite.

  • Requires pain001 0.0.89, the suite version this release ships in lockstep with.

  • The hash-pinned development sets take this week’s Dependabot updates: ruff 0.17.5, filelock 4.2.10, myst-parser 5.2.0 with mdit-py-plugins 0.7.0, and complexipy 9.0.0.

  • The complexity ratchet’s compare() is split into _regressions() and _stale(): complexipy 9 scores it at cognitive 18, over the ceiling of 15. The report it produces is unchanged.

Fixed

  • make pip-compile resolves requirements/docs.in at Python 3.11.5, the oldest version soupsieve 4 supports, and stops on the first failure. At 3.11 the docs set could not resolve and the loop swallowed the error, leaving docs.txt stale. PIP_COMPILE_FLAGS passes extra uv flags, such as -P myst-parser.

  • The README’s Quick Start lists loaders with pain001 plugins list --kind loader --format json: pain001 0.0.89 removes the deprecated --json flag it used.

[0.0.88] - 2026-11-14

Changed

  • Release 0.0.88 in lockstep with the pain001 suite.

  • Requires pain001 0.0.88, the suite version this release ships in lockstep with.

  • Suite Consistency pins the core’s ecosystem check at 404ebb9, the pain001 0.0.88 release, which audits the five SDK repositories with the rest of the family; the job is now named “Every family publication agrees”. Regenerated from pain001’s scripts/render_ecosystem_workflows.py.

  • AGENTS.md counts the fourteen suite repositories: the Go, Java, Rust, .NET and C++ SDKs joined the family at 0.0.88.

Security

  • The docs toolchain requires soupsieve 4.0 or newer: earlier versions have a polynomial-time denial of service in the descendant combinator (GHSA-mmhr-3c5m-f64f). Only the hash-pinned docs set contained it, so the published package is unaffected. The docs set now compiles from Python 3.11.5, the oldest version soupsieve 4 supports.

[0.0.87] - 2026-11-12

Changed

  • Release 0.0.87 in lockstep with the pain001 suite.

  • Requires pain001 0.0.87, the suite version this release ships in lockstep with.

  • Suite Consistency no longer runs on another workflow’s completion (workflow_run). It audits the family daily and on dispatch, as the core’s does, since that trigger runs with the default branch’s trust whatever started it. Regenerated from pain001’s scripts/render_ecosystem_workflows.py.

Added

Fixed

  • Suite Consistency pins the core’s ecosystem check at febcd0a, which accepts the five pain001 SDK repositories as known members not yet released. From the 0.0.86 release until this change every scheduled run failed on them as undeclared repositories.

  • ROADMAP.md listed mutation testing as a candidate although mutation.yml already runs it; it is now under Shipped.

[0.0.86] - 2026-11-11

Added

  • Add a code of conduct (adapted from Contributor Covenant 2.1, the suite’s shared text), issue forms, a pull request template, AGENTS.md and a markdownlint CI job (docs-lint.yml, configured in .markdownlint-cli2.jsonc).

  • Run the README Quick Start verbatim in the test suite (tests/test_readme.py): it builds a workbook from core’s pain.001.001.03 template rows, lists the loaders and generates XML, so a CLI or entry-point change fails CI instead of a reader’s terminal.

  • Add .editorconfig, a .pre-commit-config.yaml with hooks pinned by commit SHA (pre-commit-hooks 6.0.0, ruff 0.17.4, codespell 2.4.3), a devcontainer that installs the new hash-pinned requirements/dev.txt and runs make check, and a codespell job in docs-lint.yml (make docs-lint runs it with markdownlint).

Changed

  • Release 0.0.86 in lockstep with the pain001 suite and require core pain001 0.0.86; the locks resolve its published artifacts.

  • Rewrite DEVELOPMENT.md as the single developer entry point: toolchain, the local command for every CI job, the test layout, the README pipeline and the release model. Correct CONTRIBUTING.md, which named a tests/test_stress.py and a perf marker that do not exist, and include ARCHITECTURE.md in the manual.

  • The README template is now byte-identical to the portfolio’s canonical README-TEMPLATE.md, the docs badge and Documentation links point at the published manual, and the Examples section indexes both scripts. tests/test_readme.py fails CI on drift from the sources, an unresolved {{TOKEN}}, a dangling relative link or a section out of the canonical order.

  • The manual’s footer links the author’s name on every page, and docs.yml fails a build where a page lacks it. A separate Link check job (make linkcheck) runs Sphinx linkcheck over external links, and tests/test_docs_links.py checks every repository-relative link in the Markdown sources offline.

[0.0.85] - 2026-11-10

Changed

  • Release 0.0.85 in lockstep with the pain001 suite and require core pain001 0.0.85; the locks resolve its published artifacts.

  • SUPPORT.md and GOVERNANCE.md point questions at GitHub issues (the suite does not use GitHub Discussions), say there is no paid tier, SLA or out-of-hours cover, and drop the commercial-support contact. The suite list names the MT101 loader and links the family map.

[0.0.84] - 2026-11-09

Added

  • Audit all nine suite repositories and their publication channels daily and after publishing workflows, using the shared checker pinned to a core commit.

Changed

  • CI actions: github/codeql-action 4.39.3, sigstore/cosign-installer 4.1.3 and softprops/action-gh-release 3.0.4 (Dependabot #59).

  • Release 0.0.84 with the suite and require core pain001 0.0.84. Regenerate dependency locks from the published core artifacts.

[0.0.83] - 2026-11-09

Released in lockstep with pain001 0.0.83. Nothing in this loader changed beyond the version and the pain001 floor. The core’s 0.0.83 changes are to XML signing and signature verification; the XML it writes from workbook rows is the same as with 0.0.82.

Changed

  • Requires pain001 >= 0.0.83, < 1 (pyproject.toml and requirements/runtime.in; every requirement file that pins pain001 regenerated with the command in its header).

[0.0.82] - 2026-11-09

Released in lockstep with pain001 0.0.82. Nothing in this loader changed beyond the version and the pain001 floor. The loader passes your workbook’s columns through, so the core’s 0.0.82 changes apply to them: for pain.001.001.04 to .08, a valid IBAN column is written as <IBAN> and a non-empty service_level_code column as PmtTpInf/SvcLvl/Cd, and rows whose service_level_code values differ are refused, as they already were for .03 and .09 to .13.

Changed

  • Requires pain001 >= 0.0.82, < 1 (pyproject.toml and requirements/runtime.in; every requirement file that pins pain001 regenerated with the command in its header).

  • Development tools: ruff 0.17.4 and filelock 4.2.9 (Dependabot #54 and #55).

[0.0.81] - 2026-11-08

Released in lockstep with pain001 0.0.81. Nothing in this loader changed beyond the version and the pain001 floor. In 0.0.81 the core checks every IBAN and BIC and refuses rows that mix payment batches when it loads them, so rows this loader returns are checked the same way as a CSV file’s.

Changed

  • Requires pain001 >= 0.0.81, < 1 (pyproject.toml and requirements/runtime.in; every requirement file that pins pain001 regenerated with the command in its header).

[0.0.80] - 2026-11-07

Released in lockstep with pain001 0.0.80, a security release of the core’s REST API (GHSA-vv3x-jpvc-w468). Nothing in this loader changed beyond the version and the pain001 floor.

Changed

  • Requires pain001 >= 0.0.80, < 1 (pyproject.toml and requirements/runtime.in); every hash-pinned requirements file that carries pain001 now pins 0.0.80.

[0.0.79] - 2026-11-07

Released in lockstep with pain001 0.0.79. The loader is unchanged: this release moves the pain001 floor to 0.0.79, as the suite’s lockstep policy requires, and has the release workflow write the release page itself.

Changed

  • Requires pain001 >= 0.0.79, < 1 (pyproject.toml and requirements/runtime.in); every hash-pinned requirements file that carries pain001 now pins 0.0.79.

  • The release page is written by the release workflow in the suite’s shape. A last release-notes job runs scripts/release_notes.py publish once every asset is attached: the title is pain001-loader-xlsx X.Y.Z, the Highlights come from releases/vX.Y.Z.md, What’s Changed lists the pull requests merged since the previous release, and Checksums gives the SHA-256 of every asset. The 0.0.77 and 0.0.78 pages had to be rewritten by hand.

  • tests/test_release_notes.py fails a pull request whose CHANGELOG dates the version while releases/vX.Y.Z.md is missing or has other than 2 to 4 highlights. Both files are vendored byte-identical from pain001.

[0.0.78] - 2026-11-07

Released in lockstep with pain001 0.0.78, which adds faces (projections of a pain.001 document into UK Open Banking, Berlin Group and ISO 20022 element names). The loader is unchanged: this release moves the pain001 floor to 0.0.78, as the suite’s lockstep policy requires.

Changed

  • Requires pain001 >= 0.0.78, < 1 (pyproject.toml and requirements/runtime.in).

[0.0.77] - 2026-11-06

Released in lockstep with pain001 0.0.77. The loader is unchanged: this release moves the pain001 floor to 0.0.77, as the suite’s lockstep policy requires, and carries the dependency updates merged since 0.0.75. 0.0.76 was prepared on 2026-11-05 but never tagged or published, so its changes ship here.

Changed

  • Requires pain001 >= 0.0.77, < 1 (pyproject.toml and requirements/runtime.in).

  • Development and CI tools: hatchling 1.33.0, pytest 9.2.0, pytest-benchmark 5.3.1, mypy 2.4.1, ruff 0.17.3, complexipy 8.3.0, mutmut 3.8.1 and certifi 2026.10.23; every requirement file regenerated with the command in its header.

  • CI: one stable required check per versioned matrix.

[0.0.75] - 2026-10-27

Released in lockstep with pain001 0.0.75. The loader is unchanged: this release moves the Python floor to 3.11 with the rest of the suite and clears an advised filelock from the audit tree.

Security

  • requirements/audit.txt pinned filelock 4.1.0 for Python 3.10 (GHSA-9vhv-jxww-xfm5, GHSA-567q-5qvw-pf92, GHSA-v4x8-3wr5-3wq8), which pip-audit on 3.12 skipped because of its marker. audit.in now floors filelock >= 4.2.1, and with the 3.10 entries gone the tree pins 4.2.4.

Removed

  • Python 3.10 support. The floor is 3.11 (requires-python = ">=3.11"), the pain001 suite’s decision for 0.0.75: 3.10 reaches end of life in October 2026, and current hypothesis releases need 3.11, which broke Dependabot’s resolver for siblings on a 3.10 floor. CI tests 3.11 to 3.14; ruff and mypy target 3.11; the 3.10 classifier, the tomli backport and the 3.10 branch in scripts/check_suite_consistency.py are gone, and make pip-compile compiles for 3.11 (only the packages for 3.10 leave). pip keeps 3.10 users on pain001-loader-xlsx 0.0.74.

Changed

  • ruff 0.17.2 in the lint tree (Dependabot #36) and the GitHub Actions group’s five updates (#37).

[0.0.74] - 2026-10-21

Aligns pain001-loader-xlsx on the suite’s 0.0.74. The suite skips 0.0.73, which only pain001-mcp published; this package goes from 0.0.72 to 0.0.74.

Changed

  • Requires pain001 >= 0.0.74, < 1, the family’s release; the floor was 0.0.56.

  • Behaviour change: the generated XML changes for cells starting with =, +, - or @. 0.0.72 prefixed them with a single quote, as the core’s CSV loader then did; pain001 0.0.74 keeps CSV values raw by default (its ADR-0008), because XML is never evaluated and the quote changed the payment (-5 became '-5, +44 20 7946 0000 gained a quote). This loader now keeps them raw too, numeric cells included, so a sheet and its CSV export render the same XML. The core’s opt-in sanitize_formula is a load_csv_data keyword, not part of the loader plugin interface, so there is no XLSX equivalent.

Fixed

  • Text cells now carry what Excel displays. OOXML stores a carriage return as _x000D_ and a literal _xHHHH_ as _x005F_xHHHH_ (ECMA-376, ST_Xstring); openpyxl returns them undecoded, so a multi-line cell reached the payment as Line1_x000D_ LF Line2 instead of the CR LF its CSV export carries. The escapes are now decoded, and the XML equals the equivalent CSV’s again.

  • A text cell holding a character XML 1.0 cannot carry (most C0 controls, lone surrogates, U+FFFE, U+FFFF) is refused with its column, row and code point. Before, the escape text itself, such as _x0007_, went into the payment field. A workbook that loaded with such a cell now raises ValueError.

  • scripts/check_suite_consistency.py compared the tree with the pain001 core’s PyPI release; it now compares it with this package’s own, so a bump that was never released is caught in the window after the core ships.

  • GitHub releases are titled pain001-loader-xlsx <version> by the release workflow, not with the bare tag.

  • Wheel metadata no longer carries an Apache-only licence classifier; License-Expression: Apache-2.0 OR MIT states the licence.

Security

  • Every pip install in CI installs a hash-pinned requirements/*.txt (OpenSSF Scorecard Pinned-Dependencies), and a new CI job runs pip-audit on each. The audit, build and docs trees require certifi >= 2026.10.19 (GHSA-6q48-6c7w-9gw2).

  • Text cells are fuzzed with Atheris on every change, from a committed corpus that tests/test_fuzz.py also replays.

Added

  • A complexity gate (scripts/check_complexity.py, cyclomatic 10, cognitive 15, Halstead difficulty 30, 60 lines per function) against an empty, CI-enforced baseline.

  • make audit, make pip-compile, make complexity, make fuzz and make demo; a VHS demo in the README.

[0.0.72] - 2026-09-28

Security

  • Shield cells from CSV/Excel formula injection by disarming leading formula triggers (=, +, -, @, \t, \r) in string fields when loading workbooks.

Added

  • Add SLSA Level 3 provenance attestations to release artifacts.

Changed

  • Version aligned to 0.0.72 across all pain001 suite packages.

  • The README and the documentation index link What is pain.001?, an explainer of the message’s structure, versions and a schema-valid example.

[0.0.71] - 2026-09-26

Documentation

  • Generate the canonical README, check drift in CI, and replace stale feature, tool-count and safety claims with current source-backed guidance.

Fixed

  • Close workbook resources on malformed input and early iterator termination, as well as after successful loading (pain001#180).

[0.0.70] - 2026-09-13

Aligns the pain001 suite on 0.0.70: the core’s rail rules now read the CSV pipeline’s column names, and its optional dependencies load on use rather than on import. Nothing in this package changed.

Changed

  • Version aligned to 0.0.70 across all five pain001 packages.

  • SECURITY.md’s supported-version table follows the bump.

[0.0.69] - 2026-09-12

Aligns the pain001 suite on 0.0.69, the core’s third example-corpus release: the tier 2 and 3 market packs, the CSV pipeline extension and the pain.001 twin foundation (lossless ISO JSON twins with their schemas). Nothing in this package changed.

Changed

  • Version aligned to 0.0.69 across all five pain001 packages.

  • SECURITY.md’s supported-version table follows the bump.

[0.0.68] - 2026-09-12

Aligns the pain001 suite on 0.0.68, the core’s second example-corpus release: the tier-1 market packs (UK, SEPA core, US, CH, SE), coverage files named by recipe and focus, and the tooling to apply a bank’s own guideline privately. Nothing in this package changed.

Changed

  • Version aligned to 0.0.68 across all five pain001 packages.

  • SECURITY.md’s supported-version table follows the bump.

[0.0.67] - 2026-09-12

Aligns the pain001 suite on 0.0.67, the core’s first example-corpus release: validated pain.001 example files per country and rail with their provenance, and the schema coverage sets. Nothing in this package changed.

Changed

  • Version aligned to 0.0.67 across all five pain001 packages.

  • SECURITY.md’s supported-version table follows the bump.

[0.0.66] - 2026-09-12

Aligns the pain001 suite on 0.0.66, the core release that adds cross-record duplicate detection, the /api/v1/ui dashboard, GPG flags and OpenTelemetry spans. Nothing in this package changed.

Changed

  • Version aligned to 0.0.66 across all five pain001 packages.

  • SECURITY.md’s supported-version table follows the bump.

[0.0.65] - 2026-08-29

Aligns the pain001 suite on one version number, and adds the gates this repository was missing.

Added

  • benches/bench_load_xlsx.py, which measures the only thing that separates load from load_streaming: peak memory. At 10,000 rows, streaming and releasing each chunk peaks 4.5× lower (1.96 MB against 8.73 MB) and stays roughly flat as the file grows. Time is unchanged — openpyxl’s parsing dominates both paths.

  • A third column, materialised, showing that list(load_streaming(...)) costs exactly what load() costs. It is there because the first version of this benchmark measured streaming that way and reported that streaming saves nothing — a wrong number that looked plausible. Callers make the same mistake in real code: the saving comes from consuming a chunk and letting it go.

  • docs/benchmarks.md, CONTRIBUTING.md.

  • scripts/check_suite_consistency.py and a scheduled Suite Consistency workflow comparing this tree, and every published member, against PyPI.

  • tests/test_suite_conformance.py, the shared suite conformance gate.

Changed

  • Version aligned to 0.0.65 across all five pain001 packages, which had drifted to 0.0.62, 0.0.64, 0.0.63, 0.0.62 and 0.0.63.

  • SECURITY.md’s supported-version table follows the bump.

Removed

  • The stray v0.1.0 tag. It was pushed in error on 2026-08-20 against a tree that briefly declared 0.1.0, was never released to PyPI and had no GitHub release, and contradicted the suite’s 0.0.x numbering. The line it interrupted continued correctly at 0.0.61.

[0.0.63] - 2026-08-28

Changed

  • A plain pytest now enforces the same 100% coverage floor CI does. --cov, --cov-branch and --cov-report=term-missing move into [tool.pytest.ini_options] addopts. Before this, running pytest locally measured no coverage at all: the developer saw green and learned otherwise from the build.

    The gate itself was never missing — CI has always run --cov-fail-under=100, so nothing could regress onto main unnoticed. What was missing was the local half of it.

  • The floor is stated once. It was in two places, the --cov-fail-under flag in ci.yml and fail_under under [tool.coverage.report], which is how two numbers meant to be equal stop being equal. pytest-cov honours fail_under from the coverage config, so the flag is gone from both addopts and the workflow and the number lives in exactly one place.

    CI now runs pytest tests/ --cov-report=xml -v; only the XML report is CI-specific.

Verification

Coverage was already 100% and remains so. The gate was mutation-tested: adding a function no test calls drops coverage below the floor and fails the run, locally as well as in CI.

[0.0.62] - 2026-08-21

Added

  • Benchmarks for streaming throughput and value normalisation. The 0.0.61 set measured a full load, its scaling, and that load_streaming does not hold every row. Two gaps remained.

    Streaming should also cost roughly what a full load costs, and does: 0.94x, 1.13x and 1.25x across chunk sizes. The guard is against chunking becoming expensive in its own right — re-opening the workbook per chunk, say — which would keep every row correct and leave the memory assertion passing while making the API pointless for the large files it exists for.

    to_text runs once per cell, so it scales with the sheet rather than the row count: ~1.67us per cell, roughly 30ms of a ~156ms 2000-row load. Not dominant — openpyxl’s parsing is — but the largest piece this package owns.

[0.0.61] - 2026-08-20

Suite release with pain001 0.0.61. No change in this package.

The core’s 0.0.61 is a performance release — libxml2 XSD validation and a fix for quadratic CSV diagnostics — and neither touches this loader, which reads spreadsheets and goes through neither path. The version moves because every member of the suite ships the same number.

Note that 0.0.60 was never published for this package. It was prepared and tagged, but the tag failed before the publish step and the suite had moved to 0.0.61 by the time it was corrected, so 0.0.60 is skipped and this release carries its contents: values normalised to text, and temporal cells refused. See the 0.0.60 entry below for the detail.

[0.0.60] - 2026-08-20

Joins the suite’s version line. The previous number said this package “targets the 0.0.X release of pain001” while 0.0.54 required pain001>=0.0.56 — a version claiming to belong to a release it predates.

An earlier draft resolved that by moving to 0.1.0 and declaring the loaders independently versioned. That was the wrong way round: the rule was right and the metadata was wrong. 0.0.60 matches the core and every other member, and carries the breaking change below.

Fixed

  • Cell values are strings, matching csv.DictReader. pain001 renders XML from whatever a loader returns, and its CSV loader yields strings. This loader returned Excel’s native types, so a cell displaying 100.00 — stored as the float 100.0 — reached the XML as 100.0 where the CSV path produced 100.00. Same spreadsheet, two different amounts, depending on which container it arrived in.

    Numeric cells are now rendered through the cell’s number_format, which is the only record of the intended precision, so 100.0 with format 0.00 emits "100.00".

    Breaking: callers reading result.rows[...] now receive str where they previously received int / float. That is the shape pain001 has always consumed.

  • Excel date/time cells are refused. They previously passed through untouched, so a datetime object reached pain001 and stringified as 2026-03-01 00:00:00 — a value no ISO 20022 date field accepts. Excel stores dates as offsets against a workbook epoch and the 1900 and 1904 systems differ by four years, so the loader will not guess. The error names the sheet, column and row, and says to format the column as Text and use ISO-8601 — completing the date-handling requirement of pain001#180.

[0.0.54] - 2026-07-18

Changed

  • Require pain001 >= 0.0.56 — the release that ships the pain001.plugins substrate this loader auto-discovers through. (The substrate landed on PyPI in pain001 0.0.56, alongside the 0.0.55 path-injection hardening; the CI git-branch fallback used while it was in flight is removed.)

[0.0.53] - 2026-06-20

Added

Initial release of pain001-loader-xlsx, a third-party loader plugin that teaches the pain001 ISO 20022 payment library to read payment data directly from Excel .xlsx / .xlsm files. Drop-in: install both packages and .xlsx files dispatch automatically.

  • XlsxLoader — implements the structural pain001.plugins.AbstractLoader Protocol without subclassing. Just exposes meta, extensions, load, and load_streaming.

  • First-sheet header dispatch — row 1 becomes the dict keys, rows 2..N become the records. Cells are read with openpyxl’s data_only=True so formulas resolve to their cached last-saved value.

  • Streaming variant — load_streaming(path, chunk_size) honours pain001’s --streaming mode.

  • IBAN safety guard — refuses any row whose debtor_account_IBAN / creditor_account_IBAN / charge_account_IBAN cell is typed as a number, surfacing a clear remediation pointing at Excel’s “Format Cells > Number > Text” workflow. Protects against the silent leading-zero-stripping that breaks SAP / Oracle / Workday exports.

  • Entry-point auto-discovery — registered via the standard pain001.loaders entry-point group in pyproject.toml; pain001 picks the loader up at process start with no manual wiring.

  • Two runnable examples at examples/ that double as integration tests in CI.

Requirements

  • Python 3.10 or later.

  • pain001 >= 0.0.54, < 1 — the plugin substrate (pain001.plugins) ships in pain001 v0.0.54. The package metadata declares this dependency explicitly; pip will pull a compatible pain001 automatically.

  • openpyxl >= 3.1, < 4.

Quality gates

Gate

Status

pytest

12 tests passing

Line + branch coverage

100% (enforced via --cov-fail-under=100)

Docstring coverage (interrogate)

100%

ruff lint + format

clean

mypy --strict

clean

Examples in CI

2/2 run as integration tests

Suite alignment

Package

Version

pain001

0.0.53

pain001-mcp

0.0.53

pain001-lsp

0.0.53

pain001-loader-xlsx (this release)

0.0.53