Use this first, before any generation or validation call, to discover
the exact ``message_type`` strings this server accepts. Do not use it to
fetch a type's fields or schema — call ``get_required_fields`` or
``get_input_schema`` for that.

Returns a list of ``{"message_type": ..., "name": ...}`` dictionaries,
one per supported message type (e.g. ``pain.001.001.09``).

Use this for a quick checklist of the mandatory columns before building
records. When you need full type/format constraints (not just which
fields are required), call ``get_input_schema`` instead.

Args:
    message_type: A supported ISO 20022 pain message type.

Use this to learn every field, its type, and its constraints before
assembling records, or to drive a form/UI. For just the required-field
names use ``get_required_fields``; to actually check records against
this schema use ``validate_records``.

Args:
    message_type: A supported ISO 20022 pain message type.

Use this before ``generate_message`` to catch structural/type errors
per record and get a row-by-row error report. This checks JSON-Schema
shape only; for payment-scheme rulebook checks (SEPA field lengths,
charset, etc.) also run ``validate_payment_scheme``.

Returns a report ``{"valid": bool, "total": int, "valid_count": int,
"errors": [...]}``.

Args:
    message_type: A supported ISO 20022 pain message type.
    records: One or more flat payment records to validate.

Returns patches or a cannot_autofix reason. Never changes IBANs, BICs,
accounts, amounts or currencies, even for whitespace. Review every
candidate and validate the full record before generating a payment.

Args:
    record: A flat payment record, left unchanged.
    validation_error: Finding with field (or path) and rule keys.
    message_type: Supported schema supplying trusted field bounds.

Use this for a one-off identifier check with a clear pass/fail and
reason. To validate identifiers embedded across a whole batch, prefer
``validate_records`` / ``validate_payment_scheme`` instead of calling
this per field.

Returns ``{"kind": str, "value": str, "valid": bool, "error": str}``
(the ``error`` key is present only when ``valid`` is ``False``).

Args:
    kind: One of ``"iban"`` or ``"bic"`` (case-insensitive).
    value: The identifier value to check.

This is the primary generation tool: pass records you already hold in
memory. Use ``generate_message_from_file`` when the data lives in a CSV
on disk, and ``generate_message_async`` for very large batches you want
to run off the event loop. The result is XSD-validated before return; no
file is written.

Records are normalized before rendering: 'amount'/'currency' aliases,
JSON booleans, and bare 'YYYY-MM-DD' dates are accepted, and
nb_of_txs/ctrl_sum are computed from the records. On failure the
``{"error": ...}`` payload lists every missing or invalid field at
once. IBAN/BIC values are strictly validated, never coerced.

Returns the validated XML document as a string, or a JSON-encoded
``{"error": ...}`` payload if generation fails.

Args:
    message_type: A supported ISO 20022 pain message type.
    records: One or more flat payment records.

Use this to tell a user which file types they may supply to
``generate_message_from_file``. This lists *data-source* formats (CSV,
SQLite, …); for the list of ISO 20022 *message* types call
``list_message_types`` instead.

Returns a list of ``{"id", "name", "extension"}`` dictionaries
covering CSV, SQLite, JSON, JSONL, and Parquet (the last requires the
``pain001[parquet]`` extra).

Behaves exactly like ``generate_message`` but runs the synchronous
renderer in a worker thread so an agent can interleave a long
generation with other tool calls. Use ``generate_message`` for small
or interactive batches; use this only when the record count is large
enough that blocking would matter.

Delegates to :func:`pain001.async_adapter.generate_xml_string_async`.
Returns the validated XML, or a JSON-encoded ``{"error": ...}`` payload.

Args:
    message_type: A supported ISO 20022 pain message type.
    records: One or more flat payment records.

Use this when the records live in a CSV file rather than in memory; it
reads ``data_file_path`` from the local filesystem, then delegates to
``generate_message``. If you already have the records as dicts, call
``generate_message`` directly. Only CSV is supported today (JSON / JSONL
/ SQLite / Parquet are planned for a follow-up release).

Loads ``data_file_path`` via :func:`pain001.csv.load_csv_data.load_csv_data`
so the same path-safety guards apply as in the core library.

Args:
    message_type: A supported ISO 20022 pain message type.
    data_file_path: Path to a CSV file with one record per row.

Returns:
    The validated XML, or a JSON-encoded ``{"error": ...}`` payload.

Use this to read a bank's account statement (the reply that confirms
settlement) into a header + entry list. Reads ``xml_file_path`` from the
local filesystem. For the payment-status reply (accepted/rejected per
transaction) use ``parse_pain002`` instead; to validate a camt.053
string you already hold, this is not it — this tool needs a file path.

Wraps :func:`pain001.parse_camt053_statement`. When ``xsd_file_path``
is provided, the document is first validated against that XSD; on a
schema or parse error the tool returns ``{"error": ...}`` rather than
raising.

Args:
    xml_file_path: Filesystem path to the camt.053 XML statement.
    xsd_file_path: Optional path to a camt.053 XSD for upfront
        validation.

Returns:
    A compact dict with the statement header and entry list, or an
    ``{"error": ...}`` payload on failure.

Use this to read the bank's acknowledgement of a submitted pain.001 —
the per-transaction accepted/rejected status and reason codes. Reads
``xml_file_path`` from the local filesystem. For the account statement
that later confirms booked entries, use ``parse_camt053`` instead.

Wraps :func:`pain001.parse_pain002_report`. When ``xsd_file_path`` is
provided, the document is first validated against that XSD; on a
schema or parse error the tool returns ``{"error": ...}`` rather than
raising.

Args:
    xml_file_path: Filesystem path to the pain.002 XML report.
    xsd_file_path: Optional path to a pain.002 XSD for upfront
        validation.

Returns:
    A dict with the group header and transaction statuses, or an
    ``{"error": ...}`` payload on failure.

Use this to see the exact column order for hand-building a CSV before
``generate_message_from_file``. This returns column *names* from the
bundled sample; for the typed JSON contract (types, required flags) use
``get_input_schema``.

Mirrors the in-tree ``pain001.mcp.server.inspect_template`` tool so an
agent can introspect the column layout before assembling rows.

Args:
    message_type: A supported ISO 20022 pain message type.

Returns:
    ``{"message_type": str, "columns": list[str]}`` or
    ``{"error": ...}`` if the type is unsupported or no template ships.

Use this after ``validate_records`` to enforce scheme-specific business
rules (SEPA field lengths, allowed characters, currency/BIC constraints)
that JSON-Schema validation alone does not cover. ``validate_records``
checks structural shape; this checks rulebook compliance for one profile.

Delegates to :func:`pain001.validate_scheme`. Supported profiles:
``sepa-sct``, ``sepa-sdd``, ``sepa-inst``, ``xborder-ct``.

Args:
    records: Payment records as a list of flat dicts.
    profile: The scheme profile name.

Returns:
    ``{"profile", "is_valid", "violations": [...]}`` with structured
    ``violations`` (each with ``rule``, ``severity``, ``field``,
    ``message``, ``remediation`` keys), or ``{"error": ...}`` for an
    unknown profile.

Performs comprehensive pre-flight verification without generating XML
or staging files:
1. Validates records against the message type's JSON Schema.
2. Validates records against an optional payment-scheme rulebook.
3. Computes control sums grouped by currency.
4. Calculates unique debtor and creditor account counts.
5. Detects intra-batch duplicate transactions (same debtor, creditor,
   amount, currency, and execution date).

Returns a structured verdict with totals, sums by currency, duplicate
findings, and schema/scheme errors.

Args:
    message_type: A supported ISO 20022 pain message type.
    records: One or more flat payment records to simulate.
    scheme: Optional payment scheme profile to validate against.

Use this to upgrade/downgrade records when your bank requires a
different pain.001 version than your source data uses (e.g. move
``.03`` rows to ``.09``); it reports which fields were renamed, derived,
or dropped. This transforms records only — run ``validate_records``
afterwards, then ``generate_message`` to emit XML.

Wraps :class:`pain001.migration.VersionMapper`. Returns the
migrated rows plus a summary of which fields were renamed,
derived, or dropped; ``{"error": ...}`` if either version is
unsupported.

Args:
    records: Records in the ``from_version`` shape.
    from_version: Source pain.001 version (e.g. ``"pain.001.001.03"``).
    to_version: Target pain.001 version (e.g. ``"pain.001.001.09"``).

Returns:
    ``{"records": [...], "migrated": int, "from": str, "to": str}``
    or ``{"error": ...}``.

Use this to check XML you already have as a string (e.g. received from
another system) without touching the filesystem. To validate records
*before* they become XML, use ``validate_records``; to parse a statement
or status-report file, use ``parse_camt053`` / ``parse_pain002``.

Wraps :func:`pain001.xml.validate_via_xsd.validate_xml_string_via_xsd`.

Args:
    xml_content: The XML document as a string.
    message_type: A supported ISO 20022 pain message type.

Returns:
    ``{"valid": bool, "message_type": str, "error": str?}`` -
    ``error`` is present only when ``valid`` is ``False``.

Use this on a single free-text value (name, remittance info) to
transliterate accents and drop unsupported symbols before placing it in
a record, and to see whether the value changed. Operates on one string;
to check a whole batch's rulebook compliance use ``validate_payment_scheme``.

Two character sets are supported via ``charset``:

* ``"SWIFT_X"`` (default, backward-compatible) - the basic set used in
  most ISO 20022 / pain.001 fields. Delegates to
  :func:`pain001.sanitize_to_charset`.
* ``"SWIFT_Z"`` - the SWIFT extended set, a strict superset of X that also
  permits ``= ! " % & * < > ; { @ # _`` (used in narrative / envelope
  fields). It does not permit ``|`` or ``}``.

In both cases accents are transliterated (``é`` -> ``e``) and any remaining
out-of-set character is replaced with a space. The result includes flags
for whether the original was already valid and whether it changed - useful
for surfacing the change to the user before writing it back to a record.

Args:
    value: The text to sanitise.
    charset: ``"SWIFT_X"`` (default) or ``"SWIFT_Z"``.

Returns:
    ``{"value": str, "sanitised": str, "was_valid": bool, "changed": bool}``.

Use this to bridge the Nov-2025+ SWIFT MT→MX migration: parse an MT101
(*Request for Transfer*) into the flat records the other tools consume —
feed the result straight to ``validate_records`` /
``validate_payment_scheme`` and then ``generate_message`` to emit
pain.001.001.09 XML. An MT101 can request many transfers (repeating
sequence B), so this returns *one record per transaction*. Operates on
the supplied text only; no file is read or written.

Wraps :func:`pain001_loader_mt101.loader.parse_mt101`. Sequence-A
ordering-customer / account-servicing fields apply to every transaction
unless a sequence-B block overrides them; fields the MT101 does not
carry are synthesised to schema defaults (``payment_method`` ``"TRF"``,
``service_level_code`` ``"SEPA"``, etc.).

Args:
    mt101_text: The MT101 payload as a string.

Returns:
    A list of flat pain.001 records (one per transaction), or an
    ``{"error": ...}`` dict if the MT101 is missing a mandatory field
    (``:20:``, ``:30:``, or per transaction ``:21:`` / ``:32B:`` /
    a named beneficiary) or is otherwise malformed.

Use this to discover what ready-made, validated ISO 20022 files exist
before calling ``get_corpus_file`` or ``get_corpus_provenance``. Market
files are realistic payments per country and rail (``scenario_id``
like ``gb.chaps.property-purchase``); a ``variant`` names the bank
overlay a file was built with. Coverage files exercise every element
and choice branch of one message type and carry no scenario.

Delegates to :func:`pain001.corpus.list_files`.

Args:
    kind: ``market``, ``coverage`` or ``None`` for both.
    country: Optional two-letter country filter for market files.
    version: Optional message-type filter.

Returns:
    ``{"count", "files": [{"kind", "scenario_id", "version", "country",
    "family", "variant", "file"}, ...]}``, or ``{"error": ...}`` when
    the installed pain001 has no corpus.

Use this to show a model, a tester or a mapping exercise what a
correct file for a given country and rail looks like in a given
edition. The text is exactly what pain001 ships; it passed the XSD,
the ISO MDR rules, the rail profile and the overlay when it was built.

Delegates to :func:`pain001.corpus.get_file`.

Args:
    scenario_id: The scenario.
    version: The message type.
    variant: The overlay id of a bank variant, else ``None``.

Returns:
    ``{"scenario_id", "version", "variant", "xml"}``, or
    ``{"error": ...}`` when there is no such file or no corpus.

Use this to know how far to trust a file: the sources it was derived
from, the confidence of the evidence (``verified``, ``derived`` or
``assumed``), the validation ladder result per rung, what the builder
renamed or dropped to fit the edition, and the file's SHA-256.

Delegates to :func:`pain001.corpus.provenance`.

Args:
    scenario_id: The scenario.
    version: The message type.
    variant: The overlay id of a bank variant, else ``None``.

Returns:
    The parsed sidecar as a dict, or ``{"error": ...}`` when there is
    no such file or no corpus.

Use this to check that the shipped coverage files reach every element
path and choice branch of an edition's XSD before relying on them to
smoke a parser or a mapping.

Delegates to :func:`pain001.corpus.coverage_report`.

Args:
    version: The message type.

Returns:
    The ``coverage.json`` content (path and branch counts and
    percentages, completeness, missing and exempt lists), or
    ``{"error": ...}`` when the edition has no set or there is no
    corpus.

Creates an in-memory staged payment order with zero fund movement and
a 1-hour expiration window. Computes:
1. Schema validation against the message type's JSON Schema.
2. Optional scheme compliance verification (SEPA, BACS, etc.).
3. Multi-currency control sums and fee estimation.
4. Multi-factor risk scoring (detecting duplicates, high transaction
   amounts, and generic remittance narratives).
5. In-memory XML compilation and SHA-256 fingerprinting.
6. Cryptographic dual-control confirmation token for subsequent authorization.

Args:
    message_type: A supported ISO 20022 pain message type.
    records: One or more flat payment records to stage.
    scheme: Optional payment scheme profile to validate against.

Returns:
    StagedBatchResult with staging metadata, risk assessment, fingerprint,
    and confirmation token, or {"error": ...}.

Evaluates network-specific rulebooks and clearing constraints:
- EPC-SEPA: EUR currency mandate, SEPA-zone IBAN prefixes, SLEV charge bearer.
- FedNow: USD instant gross settlement eligibility.
- US-ACH: USD next-day clearing cycle routing.
- SWIFT-MX: Cross-border correspondent banking BIC routing.
- CHAPS: Same-day RTGS high-value GBP clearing.
- BACS: Three-day GBP direct credit clearing.

Args:
    stage_id: Staging identifier from stage_payment_batch.
    clearing_system: Clearing rail profile to simulate.

Returns:
    SimulateClearingResult with verdict (ACCEPTED / REJECTED), detailed
    checks, and estimated settlement window, or {"error": ...}.

Verifies the stage ID and validates the secondary confirmation token
using constant-time cryptographic comparison (preventing timing attacks).
Transitions the order status from 'staged' to 'committed'. Optionally
writes the verified XML payload to the specified destination path.

Args:
    stage_id: Staging identifier from stage_payment_batch.
    confirmation_token: Secondary secret confirmation token.
    output_file_path: Optional path to write the committed XML document.

Returns:
    CommitPaymentBatchResult with commit timestamp and fingerprint,
    or {"error": ...}.