mock-edi 0.1.0__tar.gz

mock_edi-0.1.0/CHANGELOG.md

@@ -0,0 +1,71 @@
+# Changelog
+
+Every release of [mock-edi](https://pypi.org/project/mock-edi/). The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
+versions follow [semantic versioning](https://semver.org/spec/v2.0.0.html) -
+while the major version is 0, a minor bump may change behaviour, and each entry
+says so where it does.
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.1.0] - 2026-09-24
+
+The first release: a mock EDI trading partner that answers an order with the
+documents a real one sends.
+
+### Added
+
+- **The dictionary** (`schema.py`). Elements, segments, loops and transaction
+  sets for ten transaction sets across both dialects, with the code lists that
+  make validation mean something. Everything else is derived from it -
+  parsing, validation, generation, and the dictionary published at
+  `/_mock/dictionary`, which is therefore the rules themselves rather than a
+  description of them that can drift.
+- **ASC X12** (`x12.py`): the fixed-width ISA, with the delimiters read out of
+  it rather than assumed; GS/GE functional groups; ST/SE transaction sets with
+  the counts their trailers carry; 00401 and 00501, which differ in what ISA11
+  means.
+- **UN/EDIFACT** (`edifact.py`): the UNA service string advice, the `?`
+  release character, composite elements, and an implicit functional group so
+  that everything above the wire can treat both dialects alike.
+- **850/ORDERS in, 997/855/856/810 and CONTRL/ORDRSP/DESADV/INVOIC out.** One
+  pipeline drives both dialects, so what holds for an X12 flow holds for the
+  EDIFACT one. Documents reference each other the way real ones do: the
+  invoice names the shipment, the shipment names the order.
+- **Validation** (`validate.py`, `ack.py`) against the dictionary, rendered as
+  a real 997 (`AK3`/`AK4` with X12 error codes) or CONTRL (`UCS`/`UCD` with
+  EDIFACT ones), and as prose for humans. The fatal-versus-noted policy is the
+  mock's own, and is written down rather than left to be inferred.
+- **Partner behaviours**: `accept`, `short-ship`, `reject-line`, `reject-all`,
+  `no-ack`, `duplicate-invoice` and `strict`, changed at runtime through
+  `/_mock/partners/<id>`. Two rules outrank them, because real sellers apply
+  them too: an item not in the catalogue is rejected, and a price the seller
+  disagrees with is billed at the seller's price and flagged `IP`.
+- **AS2** (`as2.py`): `AS2-From`/`AS2-To`, synchronous and asynchronous MDNs,
+  and the `Received-Content-MIC` under sha1, sha256 or sha512. S/MIME is
+  deliberately absent - it needs certificates and a cryptography library, and
+  this package has no dependencies - so a signed or encrypted payload is
+  refused with an MDN that says so rather than mangled.
+- **Delivery** (`delivery.py`): a partner with an `as2_url` has its documents
+  POSTed to it, in the order they were queued, on one background thread, with
+  the header names spelled the way AS2 spells them. `urllib` re-cases them,
+  which is legal HTTP and an unusual spelling for AS2, so `http.client` is
+  used instead.
+- **A queue with due times** (`pipeline.py`). Every delay defaults to zero, so
+  a test reads four documents back on the next line; configure real delays and
+  release them with `POST /_mock/advance?all`, because a test that sleeps is
+  slow and flaky and one that advances a clock is neither.
+- **A control plane** under `/_mock`: health, state, partners, catalogue,
+  orders, the document archive with raw payloads, the mailbox and outbox,
+  `advance`, `send`, MDNs, the request log, `validate` and `reset`.
+- **Deterministic demo data**: four partners covering the interesting
+  behaviours, a twelve-item catalogue with valid UPC check digits, and two
+  finished orders so the endpoints are not empty on a cold start.
+- **228 tests**, every one of them over real HTTP. The one that matters most
+  validates every document the mock *writes* against the dictionary it uses to
+  check what it reads; it found six real bugs the first time it ran.
+
+[Unreleased]: https://github.com/rseufert/mock-edi/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/rseufert/mock-edi/releases/tag/v0.1.0

mock_edi-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# Contributing
+
+Thanks for looking. mock-edi is a mock trading partner: it speaks the wire
+shapes of ASC X12 and UN/EDIFACT over AS2 so that EDI integrations can be built
+and tested without a counterparty. Everything below is about keeping it useful
+for that.
+
+## What the project values
+
+These are not style preferences; they decide what gets merged.
+
+**Fidelity over convenience.** If a real partner behaves a certain way, the
+mock behaves that way - even when the real behaviour is inconvenient. ISA is
+padded to its fixed widths and its delimiters are read back out of it rather
+than assumed. `TDS` carries an integer with two implied decimals. A rejected
+line commits to no delivery date. A mock that accepts what a real translator
+rejects teaches a client a lie it will discover in production.
+
+**Say when you are guessing.** Where trading partners genuinely differ, the
+mock picks one profile and says so out loud rather than implying authority.
+Line-level status in an `ORDRSP` is the clearest case: the confirmed quantity
+goes in `QTY+113` with the shortfall in `QTY+83` and the reason in `FTX+AAO`,
+and both the code and the README state that this is a choice. Inventing a
+segment or a code that the standards do not have costs more than leaving a gap.
+
+**No dependencies.** The Python standard library and SQLite, nothing else. A
+mock you cannot install in a locked-down CI image is a mock nobody runs. This
+is not negotiable, and it is why S/MIME is refused rather than half-built.
+
+**Declare, do not hand-write.** Segments, elements, loops, code lists and
+transaction sets are declarations in `mockedi/schema.py`; parsing, validation,
+generation and the published dictionary are derived from them. If you find
+yourself writing the same shape in two places, the declaration is missing.
+
+**Refuse rather than half-implement.** An encrypted AS2 payload, an unknown
+transaction set and an interchange from an unregistered sender all produce an
+answer that names what *is* supported. Silently ignoring something is the one
+thing worse than not having it.
+
+**The wire is the product.** Behaviour a client cannot observe does not need to
+exist; behaviour it can observe needs to be right. Control numbers come from
+number ranges and shipment ids are derived so they are reproducible, because a
+client sees those. No warehouse is simulated, because no client can tell.
+
+## Getting set up
+
+Nothing to install:
+
+```bash
+git clone https://github.com/rseufert/mock-edi
+cd mock-edi
+python3 -m mockedi --port 8080        # it is already runnable
+python3 -m unittest discover -s tests -v
+python3 tools/check_docs.py
+python3 tools/check_changelog.py
+```
+
+Python 3.8 or newer. There is no build step, no virtualenv to create and
+nothing to compile.
+
+## Where things live
+
+| Adding this | Goes here | Notes |
+| --- | --- | --- |
+| A segment or element | `mockedi/schema.py` | Define it once and reference it; `N1`, `DTM` and `RFF` are shared across sets |
+| A code value | `mockedi/schema.py` | The code lists are what make validation mean something - a list that accepts everything acknowledges everything |
+| A transaction set | `mockedi/schema.py`, then `transactions.py` | The definition first, then a reader or a writer, then a row in `SET_FOR_KIND` |
+| A partner behaviour | `mockedi/documents.py` (`decide`) and `db.BEHAVIOURS` | Keep the precedence rules in the docstring true |
+| A validation check | `mockedi/validate.py` | Produce a finding, not a sentence: it has to render as both a 997 and a CONTRL |
+| An endpoint | `mockedi/server.py` | Add it to the index page and the README table too |
+| A CLI flag | `mockedi/__main__.py` and `server.Config` | |
+
+If a change touches more than one of these, it is usually two changes.
+
+## What a good pull request looks like
+
+- **A test that goes over HTTP.** Every test in `tests/` drives a real mock on
+  a real socket; nothing is stubbed. Put it in the module for the surface you
+  touched, or add one and give it a row in `docs/FILES.md`.
+- **Assertions that could fail.** Check a total against the lines it
+  summarises, not against itself. The nastiest bug in this project's short
+  history - a loop walker that treated a repeated `N1` as a second use -
+  produced plausible-looking 997s and was caught only by validating the mock's
+  own output against its own dictionary.
+- **Documentation that keeps up.** `tools/check_docs.py` fails the build if a
+  tracked file has no row in `docs/FILES.md`, if a row names a file that is
+  gone, or if a module is missing from the README's layout block. It checks
+  coverage, not prose - keeping the prose true is on you.
+- **A line in the changelog.** `tools/check_changelog.py` fails a pull request
+  that touches `mockedi/` without adding an entry under `## [Unreleased]` - an
+  entry, not merely a changed file. It is what a user of the published package
+  reads. The same check holds released sections to being history and refuses to
+  let an entry waiting for a release disappear. A change that genuinely needs
+  no entry - a comment, a rename, a pure refactor - can carry the
+  `no changelog` label, which lifts that one rule and leaves the others
+  standing.
+- **No new dependencies.** See above.
+- **A commit message that says what changed and why.** The why is the part a
+  reader cannot reconstruct. Wrap at 72 characters.
+
+Small, focused pull requests are easier to take than large ones. If you are
+unsure whether something fits, open an issue first and say what you are trying
+to test against the mock - that is usually the fastest way to the right shape.
+
+## Reporting a missing or wrong shape
+
+The most useful bug report contains the interchange a real trading partner
+sent, with anything sensitive removed, beside what the mock produced. Segment
+tags, element positions, the exact envelope and the version all matter. If you
+cannot share a document, the transaction set and a description of the
+difference is still plenty to work with.
+
+`POST /_mock/validate` is often the fastest way to show one: it returns the
+mock's reading of a document as prose, without changing anything.
+
+## Releasing (maintainers)
+
+`pyproject.toml` is the only place the version is written; `mockedi.__version__`
+reads it back from the installed package metadata.
+
+```bash
+# bump `version` in pyproject.toml, commit, then:
+git tag v0.2.0 && git push origin v0.2.0
+gh release create v0.2.0 --generate-notes     # or write the notes by hand
+```
+
+Publishing the GitHub Release runs the tests, builds the distributions, checks
+that the tag, `pyproject.toml` and the built wheel agree, and uploads to PyPI
+through [Trusted Publishing](https://docs.pypi.org/trusted-publishers/) - there
+is no API token anywhere. Running the `Publish` workflow by hand publishes to
+TestPyPI instead. Add the release to [`CHANGELOG.md`](CHANGELOG.md) in the same
+commit as the version bump.
+
+One practical note: PyPI's index propagates per edge node, so an install
+immediately after a release can still fetch the previous version. Pin the exact
+version when verifying (`pip install mock-edi==0.2.0`) rather than trusting a
+plain upgrade.
+
+## Licence
+
+By contributing you agree that your work is licensed under the
+[MIT Licence](LICENSE), the same terms as the rest of the project.

mock_edi-0.1.0/Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.12-slim
+WORKDIR /app
+COPY mockedi ./mockedi
+COPY pyproject.toml README.md LICENSE ./
+RUN pip install --no-cache-dir .
+EXPOSE 8080
+ENTRYPOINT ["mock-edi", "--host", "0.0.0.0", "--port", "8080"]

mock_edi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mock-edi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mock_edi-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include LICENSE README.md CHANGELOG.md CONTRIBUTING.md Dockerfile
+recursive-include examples *.py *.sh *.edi
+recursive-include tests *.py

mock_edi-0.1.0/PKG-INFO

@@ -0,0 +1,349 @@
+Metadata-Version: 2.4
+Name: mock-edi
+Version: 0.1.0
+Summary: A mock EDI trading partner: X12 and EDIFACT over AS2, with the whole order-to-cash choreography, over SQLite, with zero dependencies.
+License: MIT
+Project-URL: Homepage, https://github.com/rseufert/mock-edi
+Project-URL: Repository, https://github.com/rseufert/mock-edi
+Project-URL: Issues, https://github.com/rseufert/mock-edi/issues
+Project-URL: Changelog, https://github.com/rseufert/mock-edi/blob/main/CHANGELOG.md
+Keywords: edi,x12,edifact,as2,mock,850,856,810,997,orders,desadv,invoic,edi-integration,testing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Software Development :: Testing :: Mocking
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# mock-edi
+
+[![CI](https://github.com/rseufert/mock-edi/actions/workflows/ci.yml/badge.svg)](https://github.com/rseufert/mock-edi/actions/workflows/ci.yml)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/mock-edi)](https://pypi.org/project/mock-edi/)
+
+**A mock EDI trading partner.** Not an EDI library and not an AS2 server — the
+thing on the *other end*. Send it an 850 and it sends back a 997, then an 855
+that answers line by line, then an 856 with a shipment tree, then an 810 that
+bills what shipped. Send it an EDIFACT `ORDERS` and the same thing happens in
+`CONTRL` / `ORDRSP` / `DESADV` / `INVOIC`.
+
+```
+   you ──850──▶  mock-edi
+       ◀──997──  the syntax parsed
+       ◀──855──  2 lines: one confirmed, one short
+       ◀──856──  shipment / order / item, with a tracking number
+       ◀──810──  1132.80, terms 2% 10 net 30
+```
+
+There is plenty of open source for *speaking* EDI — OpenAS2 and mendelson will
+terminate an AS2 connection, and a dozen libraries will parse an X12 segment.
+What none of them is, is a counterparty. To test the code that runs when an
+856 arrives unannounced, or when the invoice comes twice, or when the
+acknowledgment never comes at all, you need a partner that does those things
+on demand. Real ones do them on their own schedule, and getting one to do it
+deliberately is a support ticket and a fortnight.
+
+- **Zero dependencies.** Python 3.8+ standard library and SQLite, nothing else.
+  It installs in a locked-down CI image.
+- **Real wire shapes.** A 106-character fixed-width ISA that declares its own
+  delimiters, EDIFACT's `?` release character, composite elements, `TDS` with
+  two implied decimals, `HL` parent pointers, `AK3`/`AK4` error codes, MDNs
+  with a `Received-Content-MIC`.
+- **Failure on demand.** Short shipments, rejected lines, refused orders,
+  duplicate invoices, a strict partner, and a partner that never answers —
+  each one PATCH away.
+- **It validates its own output.** Every document the mock writes is checked
+  against the same dictionary it checks yours against. There is a test for it.
+
+MIT licensed. ASC X12 and UN/EDIFACT are standards published by their
+respective bodies; AS2 is RFC 4130. This project implements publicly
+documented wire formats for testing purposes and is not affiliated with or
+endorsed by any standards body or vendor.
+
+---
+
+## Quick start
+
+```bash
+pip install mock-edi
+mock-edi --port 8080
+```
+
+```bash
+curl -X POST --data-binary @order.edi http://127.0.0.1:8080/edi
+```
+
+```json
+{
+  "accepted": true,
+  "partner": "ACME",
+  "dialect": "X12",
+  "orders": ["4500000042"],
+  "transactionSets": [
+    {"code": "850", "control": "0001", "kind": "order", "accepted": true, "findings": []}
+  ],
+  "queued": [
+    {"kind": "acknowledgment", "code": "997", "reference": "000000077", "dueAt": "..."},
+    {"kind": "response",       "code": "855", "reference": "4500000042", "dueAt": "..."},
+    {"kind": "despatch",       "code": "856", "reference": "4500000042", "dueAt": "..."},
+    {"kind": "invoice",        "code": "810", "reference": "4500000042", "dueAt": "..."}
+  ]
+}
+```
+
+Then collect what it sent you:
+
+```bash
+curl "http://127.0.0.1:8080/_mock/mailbox?raw"
+```
+
+```
+ISA*00*          *00*          *ZZ*MOCKEDI        *ZZ*ACME           *260924*1030*U*00401*000000001*0*T*>~
+GS*PR*MOCKEDI*ACME*20260924*1030*2*X*004010~
+ST*855*0002~
+BAK*00*AD*4500000042*20260924***20260924*5100002~
+...
+PO1*1*100*EA*12.50**VP*WIDGET-001*UP*076123400003~
+ACK*IA*100*EA*068*20260926~
+```
+
+Run it from a checkout with no install at all, or in a container:
+
+```bash
+python3 -m mockedi --port 8080
+docker build -t mock-edi . && docker run -p 8080:8080 mock-edi
+```
+
+A guided tour of every endpoint, in curl:
+
+```bash
+bash examples/demo.sh
+```
+
+## What it serves
+
+| Surface | Endpoint |
+| --- | --- |
+| AS2 inbound | `POST /as2` — answers with an MDN, synchronous or asynchronous |
+| Asynchronous MDN inbound | `POST /as2/mdn` — a partner's receipt for something the mock sent |
+| Plain EDI inbound | `POST /edi` — the same pipeline, answering with a JSON summary |
+| Validate only | `POST /_mock/validate` — findings, and nothing changed |
+| Mailbox | `GET /_mock/mailbox` — collect what is waiting; `?leave` to peek, `?raw` for payloads |
+| Outbox | `GET /_mock/outbox` — the queue, including what is not due yet |
+| Release the queue | `POST /_mock/advance` — `?seconds=N` or `?all` |
+| Send out of band | `POST /_mock/send` — replay an invoice, or send one unprompted |
+| Partners | `GET/POST /_mock/partners`, `GET/PATCH/DELETE /_mock/partners/<id>` |
+| Orders | `GET /_mock/orders`, `GET /_mock/orders/<po>` |
+| Archive | `GET /_mock/documents`, `GET /_mock/interchanges`, `GET /_mock/interchanges/<id>?raw` |
+| Receipts | `GET /_mock/mdns` |
+| The dictionary | `GET /_mock/dictionary`, `/_mock/dictionary/X12/850` |
+| Health and state | `GET /_mock/health`, `GET /_mock/state`, `GET /_mock/requests` |
+| Reset | `POST /_mock/reset` |
+| Index page | `GET /` |
+
+## The documents
+
+| Business document | X12 | EDIFACT |
+| --- | --- | --- |
+| Purchase order | **850** | **ORDERS** |
+| Purchase order response | **855** | **ORDRSP** |
+| Despatch advice / ship notice | **856** | **DESADV** |
+| Invoice | **810** | **INVOIC** |
+| Syntax acknowledgment | **997** | **CONTRL** |
+
+Both dialects are read and written from one dictionary
+([`mockedi/schema.py`](mockedi/schema.py)), and one pipeline drives both, so
+what you assert about an X12 flow holds for the EDIFACT one. `GET
+/_mock/dictionary/X12/850` serves that dictionary as JSON — the actual rules,
+not a description of them that can go stale.
+
+Coverage is the commonly traded core of each set, not the full standard. A
+real 850 admits some fifty segment types and almost nobody sends more than a
+dozen; the mock implements the dozen, validates them properly, and reports an
+unrecognised segment rather than pretending to understand it.
+
+## Partner behaviours
+
+Four partners are seeded. Change any of them at runtime:
+
+```bash
+curl -X PATCH -H 'Content-Type: application/json' \
+     -d '{"behaviour":"short-ship"}' \
+     http://127.0.0.1:8080/_mock/partners/ACME
+```
+
+| Behaviour | What the partner does |
+| --- | --- |
+| `accept` | Confirms everything in full and ships what was ordered. |
+| `short-ship` | Confirms less than was ordered (`855` `IQ`, `ORDRSP` `QTY+83`), and ships and invoices the confirmed quantity. |
+| `reject-line` | Refuses one line outright (`IR`) and leaves it out of the shipment and the invoice. |
+| `reject-all` | Acknowledges the syntax, then refuses the order (`BAK` `RJ`). |
+| `no-ack` | Says nothing at all. No 997, no 855. For testing your chase-up timer — the failure that actually costs money. |
+| `duplicate-invoice` | Sends the invoice twice with the same invoice number, as a partner with a retry bug does. |
+| `strict` | Rejects a transaction set for any finding, not only a fatal one. |
+
+Two rules apply whatever the behaviour says, because they are what real
+sellers actually do:
+
+- an item that is not in the catalogue is rejected (`IR`), and
+- a price the seller disagrees with is billed at the seller's price and
+  flagged `IP`. Price discrepancies are the commonest EDI dispute there is.
+
+## Timing
+
+By default every document is released the moment it is produced, so a test can
+POST an order and read four documents back on the next line. Give them delays
+when what you are testing is the waiting:
+
+```bash
+mock-edi --ack-delay 2000 --response-delay 30000 --invoice-delay 86400000
+```
+
+Nothing is released on a timer of its own. `POST /_mock/advance?all` releases
+whatever is queued, whenever it was due — a test that has to sleep is slow and
+flaky, and one that advances the clock is neither.
+
+## AS2
+
+```bash
+curl -X POST --data-binary @order.edi \
+  -H 'Content-Type: application/edi-x12' \
+  -H 'AS2-From: ACME' -H 'AS2-To: MOCKEDI' \
+  -H 'Message-ID: <po-1@acme.example>' \
+  -H 'Disposition-Notification-To: edi@acme.example' \
+  -H 'Disposition-Notification-Options: signed-receipt-protocol=optional, pkcs7-signature; signed-receipt-micalg=optional, sha256' \
+  http://127.0.0.1:8080/as2
+```
+
+comes back as a `multipart/report` MDN with the MIC of what arrived:
+
+```
+Disposition: automatic-action/MDN-sent-automatically; processed
+Received-Content-MIC: +H1EWvEMSJH/IHGsjy7c/dviFRwLgRoGBmxnTEbMkGA=, sha256
+```
+
+Name a `Receipt-Delivery-Option` and the response is `202` with the MDN posted
+back to that URL instead.
+
+**S/MIME is deliberately not implemented.** Signing and encrypting AS2
+payloads needs certificates and a cryptography library, and this project has no
+dependencies on purpose. A message that arrives encrypted or signed is refused
+with an MDN saying exactly that, rather than being mangled. If your integration
+must be tested against signed AS2, this mock is the wrong tool and will tell
+you so on the first message.
+
+## Making the mock come to you
+
+A partner with no `as2_url` is a mailbox. Give one a URL and the mock stops
+being something you poll and becomes something that *arrives*:
+
+```bash
+curl -X PATCH -H 'Content-Type: application/json' \
+     -d '{"as2_url":"http://localhost:9000/as2"}' \
+     http://127.0.0.1:8080/_mock/partners/ACME
+```
+
+Documents are then POSTed to your listener with AS2 headers, in the order they
+were queued, and whatever MDN you return is recorded against them in
+`/_mock/outbox`.
+
+## Validation
+
+Every inbound document is checked against the dictionary, and the findings
+become a real 997 or CONTRL — `AK3`/`AK4` with X12 error codes, `UCS`/`UCD`
+with EDIFACT ones. Ask for the findings as prose instead:
+
+```bash
+curl -X POST --data-binary @broken.edi http://127.0.0.1:8080/_mock/validate
+```
+
+```json
+{
+  "clean": false,
+  "groupCode": "R",
+  "explain": [
+    "850/0001: rejected",
+    "  BEG at segment 2: ZZ is not a code BEG01 accepts (00, 01, 04, 05, 06, 07, ...)",
+    "  BEG at segment 2: BEG05 is not a valid date: '2026-09-24'",
+    "  PO1 at segment 3 in the PO1 loop: PO102 must be a number, got 'ten'",
+    "  SE01 counts 99 segments, the message holds 6 (4)"
+  ]
+}
+```
+
+Severity is the mock's own policy, and it is stated rather than implied. A
+*fatal* finding rejects the transaction set — an unknown set, a missing
+mandatory segment or element, a control number that does not match its
+trailer, a segment count that does not add up. Everything else is accepted
+with errors noted: an invalid code, a length violation, a malformed date, a
+segment the set does not define. A partner set to `strict` rejects on either.
+
+Two limits, stated plainly: loop *membership* and repetition counts are
+checked but loop *sequence* is not, and conditional requirements ("if PO104 is
+present then PO103 must be") are not modelled. Both would need a rule language
+to express, and the mock would rather leave them out than pretend.
+
+## Layout
+
+```
+mockedi/schema.py        elements, segments, loops, transaction sets  (add shapes here)
+mockedi/envelope.py      the shape both dialects share, and delimiter handling
+mockedi/x12.py           reading and writing ASC X12 interchanges
+mockedi/edifact.py       reading and writing UN/EDIFACT interchanges
+mockedi/validate.py      checking a document against the dictionary
+mockedi/ack.py           turning findings into a 997 or a CONTRL
+mockedi/transactions.py  business documents in, business documents out
+mockedi/documents.py     what the seller decides, and the shipment and invoice
+mockedi/partners.py      who we trade with, and how each one misbehaves
+mockedi/pipeline.py      the choreography: an order in, four documents back
+mockedi/delivery.py      posting to a partner that has somewhere to receive
+mockedi/as2.py           AS2 headers, the MIC, and the MDN
+mockedi/db.py            SQLite: schema, number ranges, demo data
+mockedi/server.py        HTTP: AS2, /edi, and the control plane
+```
+
+[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) explains how they fit together;
+[`docs/FILES.md`](docs/FILES.md) is an index of every file in the repository.
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+228 tests, every one of them talking to a real mock over real HTTP. Nothing is
+stubbed. The most valuable one is in `tests/test_dictionary.py`: every document
+the mock generates is validated against the same dictionary it validates yours
+with, so the day someone adds a segment to a writer and forgets the
+definition, the suite says so.
+
+## Extending it
+
+Add a segment or a transaction set in `schema.py` and it is parsed, validated
+and published in `/_mock/dictionary` without touching anything else. Add a
+*behaviour* in `documents.decide()`. Add an endpoint in `server.py`.
+[CONTRIBUTING.md](CONTRIBUTING.md) says where each kind of change goes and what
+a good pull request carries.
+
+## See also
+
+[mock-sap](https://github.com/rseufert/mock-sap) — the same idea for SAP:
+OData V2 and V4, BAPI/RFC and IDoc shapes over SQLite, also with zero
+dependencies. An IDoc `ORDERS05` and an X12 850 are the same business
+document, so the two mocks make a reasonable pair of ends for testing a
+middleware layer.