messagefoundry 0.2.1__tar.gz → 0.2.2__tar.gz

{messagefoundry-0.2.1 → messagefoundry-0.2.2}/.github/SECURITY.md

@@ -12,9 +12,14 @@ verify a report against current `main` before filing.
 
 **Do not open a public issue for a vulnerability.** Instead, report it privately:
 
-- Preferred: open a [GitHub private security advisory](https://github.com/wshallwshall/MessageFoundry/security/advisories/new)
-  ("Report a vulnerability"), or
-- Email the maintainer at the address on the GitHub profile.
+- **Preferred (always available, fully private):** open a [GitHub private security advisory](https://github.com/wshallwshall/MessageFoundry/security/advisories/new)
+  ("Report a vulnerability") — GitHub keeps it private to the maintainers until coordinated disclosure.
+  This is the recommended channel on both this repository and the public mirror.
+- Alternatively, email the maintainer at the address on the GitHub profile.
+
+If you cannot reach a maintainer privately within a few business days, you may request a contact via a
+**non-detail** public issue (title only, e.g. "requesting a private security contact") — **never** put
+vulnerability details, reproduction steps, or any message content in a public issue.
 
 Please include: affected component (e.g. MLLP/file transport, store, API/auth, console),
 a description and impact, and reproduction steps or a proof of concept. Do **not** include

{messagefoundry-0.2.1 → messagefoundry-0.2.2}/.github/workflows/benchmark.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
       - name: Install project (dev)
         run: |
           python -m pip install --upgrade pip
@@ -92,7 +92,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
       - name: Install project (dev + postgres)
         run: |
           python -m pip install --upgrade pip
@@ -159,7 +159,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
       - name: Install Microsoft ODBC Driver 18 + sqlcmd
         run: |
           curl -fsSL https://packages.microsoft.com/keys/microsoft.asc \

{messagefoundry-0.2.1 → messagefoundry-0.2.2}/.github/workflows/ci.yml

@@ -11,37 +11,23 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  # Lint + type-check + unit tests. Linux carries the cheap breadth — the 3.11
-  # floor plus a fast early-fail leg on the newest 3.14 (1x minutes). Windows
-  # Server 2022 + 2025 is the primary deployment target, so it covers BOTH the
-  # current (3.13) and the new (3.14) deploy Python on each Server SKU, even
-  # though Windows bills at 2x — testing the version we ship on the OS we ship it
-  # on is worth the minutes.
+  # Lint + type-check + unit tests. The project supports a single Python — 3.14 — so every leg runs it.
+  # Linux carries the cheap breadth (1x minutes); Windows Server 2022 + 2025 is the primary deployment
+  # target, so 3.14 is also exercised on both Server SKUs even though Windows bills at 2x — testing the
+  # version we ship on the OS we ship it on is worth the minutes.
   test:
     name: test (${{ matrix.os }}, py${{ matrix.python-version }})
     runs-on: ${{ matrix.os }}
-    # py3.11 is a REQUIRED gate again (BACKLOG #17 RESOLVED in PR #448). The intermittent py3.11-only hang
-    # was root-caused — and reproduced on a Docker py3.11 box — as a CPython 3.11 asyncio cancellation race:
-    # cancelling a task parked in asyncio.Queue.get() can intermittently never complete (fixed in CPython
-    # 3.12, hence py3.13 was always clean and production — one long-lived loop — never hit it). TeeRelay.stop()
-    # tripped it; fixed via a sentinel shutdown in tee/relay.py, validated at 0 hangs across 24 full-suite +
-    # 40 isolated runs in the repro container and green on CI. So the advisory `continue-on-error` is removed
-    # and a py3.11 failure reds the build again. (The dormant `MEFOR_PY311_QUARANTINE` conftest lever stays as
-    # an off-by-default safety net; it is no longer needed.)
     # Wall-clock backstop: bound each leg so a hung test fails in minutes, not the 6h default. The
     # pytest-timeout watchdog (60s/test) should catch a culprit first; this is the belt-and-suspenders cap
-    # if a whole process ever deadlocks below pytest (e.g. a future regression of BACKLOG #17).
+    # if a whole process ever deadlocks below pytest.
     timeout-minutes: 15
     strategy:
       fail-fast: false
       matrix:
         include:
-          - { os: ubuntu-latest, python-version: "3.11" }
-          - { os: ubuntu-latest, python-version: "3.13" }
           - { os: ubuntu-latest, python-version: "3.14" }
-          - { os: windows-2022, python-version: "3.13" }
           - { os: windows-2022, python-version: "3.14" }
-          - { os: windows-2025, python-version: "3.13" }
           - { os: windows-2025, python-version: "3.14" }
     defaults:
       run:
@@ -89,36 +75,6 @@ jobs:
           QT_QPA_PLATFORM: offscreen
         run: pytest -q
 
-  # BACKLOG #17 production-bug check. The intermittent py3.11 asyncio<->aiosqlite lost-wakeup hang has
-  # only ever surfaced under pytest (per-test event-loop churn + log-capture teardown are the suspected
-  # triggers). This job runs the store the way the engine does in PRODUCTION — one asyncio.run() loop,
-  # no pytest — and hammers aiosqlite with concurrent DB ops on py3.11. A clean pass is evidence the
-  # hang is a test-lifecycle artifact, not a product defect; a hang here (caught by the per-run
-  # `timeout`, exit 124) would be a real, pytest-free repro that flips it to a confirmed product bug.
-  py311-store-soak:
-    name: py3.11 store soak (BACKLOG #17)
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
-      - name: Set up Python 3.11
-        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
-        with:
-          python-version: "3.11"
-          cache: pip
-          cache-dependency-path: pyproject.toml
-      - name: Install project (base — no pytest, no console)
-        run: |
-          python -m pip install --upgrade pip
-          pip install -e .
-      - name: Soak the aiosqlite store on one long-lived loop (5x)
-        run: |
-          for run in $(seq 1 5); do
-            echo "::group::soak run $run"
-            timeout 150 python scripts/soak/store_soak.py 64 300
-            echo "::endgroup::"
-          done
-
   # Build + type-check the VS Code extension, and run its integration tests. The Python jobs never
   # touch ide/, so a dep bump or IDE code change that breaks the bundle or the types would otherwise
   # pass CI unbuilt (this job exists because an esbuild bump merged "green" without anything having
@@ -235,7 +191,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
 
       - name: Install Microsoft ODBC Driver 18 + sqlcmd
         run: |
@@ -379,7 +335,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
 
       - name: Install project (dev + postgres extras)
         run: |
@@ -437,7 +393,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
 
       - name: Install project (dev — engine + httpx client; no Qt needed for the headless load path)
         run: |
@@ -509,7 +465,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
 
       - name: Install Microsoft ODBC Driver 18 + sqlcmd
         run: |
@@ -590,12 +546,11 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        # Windows Server 2022 + 2025 on the current deploy Python (3.13); plus the new 3.14 deploy
-        # target on 2025 (newest Server) so the real NSSM install->serve->MLLP path is validated on
-        # the version we will ship. This job is push/dispatch-only, so the extra leg costs no PR time.
+        # Windows Server 2022 + 2025 on the supported deploy Python (3.14), so the real NSSM
+        # install->serve->MLLP path is validated on the version we ship, on each Server SKU. This job
+        # is push/dispatch-only, so the Windows minutes cost no PR time.
         include:
-          - { os: windows-2022, python-version: "3.13" }
-          - { os: windows-2025, python-version: "3.13" }
+          - { os: windows-2022, python-version: "3.14" }
           - { os: windows-2025, python-version: "3.14" }
     defaults:
       run:
@@ -802,9 +757,19 @@ jobs:
           # A fully graceful shutdown exits 0 (uvicorn handles SIGTERM, runs the lifespan, returns); 143
           # (128+SIGTERM) is acceptable too. 137 = SIGKILL after the grace expired = ungraceful.
           if [ "$code" = "137" ]; then echo "FAIL: ungraceful shutdown (SIGKILL after grace)"; exit 1; fi
-          docker logs mefor 2>&1 | grep -q "Application shutdown complete" \
-            || { echo "FAIL: no clean-shutdown marker (lifespan shutdown did not complete)"; exit 1; }
-          echo "graceful shutdown verified"
+          # Poll for the marker: `docker stop` returns the instant the container exits, but the final
+          # buffered log line ("Application shutdown complete") can land in `docker logs` a beat later, so
+          # grepping once immediately is racy (a clean 143 shutdown then read as a missing marker). Retry
+          # for ~10s so a slow log flush is not misread as an incomplete lifespan shutdown.
+          for _ in $(seq 1 20); do
+            if docker logs mefor 2>&1 | grep -q "Application shutdown complete"; then
+              echo "graceful shutdown verified"; exit 0
+            fi
+            sleep 0.5
+          done
+          echo "FAIL: no clean-shutdown marker (lifespan shutdown did not complete)"
+          docker logs mefor 2>&1 | tail -20
+          exit 1
 
       - name: Engine log (always)
         if: always()
@@ -820,7 +785,7 @@ jobs:
   #     `windows-service-smoke`) report `skipped` on every PR — never the required context a PR waits
   #     on — so requiring them either no-ops or wedges; and
   #   * the matrix legs report an UNEXPANDED name when skipped (`... ${{ matrix.label }}`) but
-  #     EXPANDED names when they run (`... 2022`/`2025`, `(windows-2022, py3.13)`), so no single
+  #     EXPANDED names when they run (`... 2022`/`2025`, `(windows-2022, py3.14)`), so no single
   #     context string matches both the skipped and the run state.
   # This gate ALWAYS runs (if: always()), so it reports ONE fixed context ("CI gate") regardless of
   # which legs ran, and fails iff a gated leg actually FAILED or was cancelled — a `skipped` leg

{messagefoundry-0.2.1 → messagefoundry-0.2.2}/.github/workflows/dependabot-lock-resync.yml

@@ -60,7 +60,7 @@ jobs:
           # code runs in this job (uv lock --check + uv export only).
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # v8.2.0
 
       - name: Re-export the lock files (DEP-1 — byte-for-byte identical flags/paths)
         run: |

{messagefoundry-0.2.1 → messagefoundry-0.2.2}/.github/workflows/release-sync-check.yml

@@ -29,7 +29,7 @@ jobs:
           fetch-depth: 0 # need the vX.Y.Z tags (the private-tag side of the check)
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
       - name: Check tag / PyPI / mirror are in sync
         run: |
           # The script lives under the deny-listed scripts/publish/, so it is ABSENT on the OSS mirror;

{messagefoundry-0.2.1 → messagefoundry-0.2.2}/.github/workflows/release.yml

@@ -40,7 +40,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
 
       - name: Build sdist + wheel
         run: |

{messagefoundry-0.2.1 → messagefoundry-0.2.2}/.github/workflows/security.yml

@@ -32,7 +32,7 @@ jobs:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
       - name: Check the lockfile is in sync with pyproject (DEP-1)
         run: |
           python -m pip install --upgrade pip uv
@@ -94,11 +94,14 @@ jobs:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
       - name: Generate a CycloneDX SBOM from the lockfile
         run: |
-          python -m pip install --upgrade pip "cyclonedx-bom~=4.6"
-          cyclonedx-py requirements requirements.lock --output-format JSON --outfile sbom.cdx.json
+          # cyclonedx-bom~=7.3 (was ~=4.6): the 4.x line drags cyclonedx-python-lib 7.x → lxml<6, which
+          # has no cp314 wheel, so on the 3.14 runner pip source-builds lxml and fails. 7.3 → lxml 6.x
+          # (cp314 wheels). The 7.x `requirements` CLI renamed `--outfile` → `--output-file`.
+          python -m pip install --upgrade pip "cyclonedx-bom~=7.3"
+          cyclonedx-py requirements requirements.lock --output-format JSON --output-file sbom.cdx.json
       - name: Upload the SBOM artifact
         # SHA-pinned for supply-chain integrity, matching ci.yml's upload-artifact pin.
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
@@ -115,7 +118,7 @@ jobs:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
       - name: Scan source for insecure patterns
         run: |
           # Pin bandit: an unpinned upgrade once silently changed `# nosec` parsing (1.9.x requires
@@ -162,7 +165,7 @@ jobs:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
       - name: Run the MessageFoundry rules
         run: |
           python -m pip install --upgrade pip "semgrep~=1.90"
@@ -182,7 +185,7 @@ jobs:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
       - name: Diff crypto call sites against the inventory
         # Stdlib-only (no install). Exits non-zero — failing the build — on any drift.
         run: python scripts/security/crypto_inventory_check.py
@@ -200,7 +203,7 @@ jobs:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
       - name: Scan the publishable subset for forbidden content
         # Stdlib-only scanner (no install). Exits non-zero — failing the build — on any hit. The scanner
         # lives under the deny-listed scripts/publish/, so it is ABSENT on the OSS mirror — there's

{messagefoundry-0.2.1 → messagefoundry-0.2.2}/.github/workflows/vuln-metrics.yml

@@ -25,7 +25,7 @@ jobs:
       - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
       - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
         with:
-          python-version: "3.13"
+          python-version: "3.14"
       - name: Compute the metrics (real Dependabot PRs + CISA KEV + FIRST EPSS)
         env:
           GH_TOKEN: ${{ github.token }} # gh auth for the read-only Dependabot-PR query

{messagefoundry-0.2.1 → messagefoundry-0.2.2}/CHANGELOG.md

@@ -6,6 +6,57 @@ All notable changes to MessageFoundry are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.2.2] — 2026-06-24 — Early Access
+
+A security-hardening release: PHI-at-rest encryption is closed across every backend, the active-passive
+cluster gains a store-checked split-brain fence, outbound delivery is effectively-once, and the at-rest
+cipher becomes crypto-agile — all additive, with the on-disk `mfenc:v1` format byte-identical.
+
+### Changed
+- **BREAKING — Python 3.14 is now the only supported runtime.** `requires-python` is raised to `>=3.14`
+  (was `>=3.11`), and the ruff/mypy targets, CI matrix (Linux + Windows Server 2022/2025, all on 3.14),
+  Docker base image, lockfiles, and adopter scaffold move with it. **Adopters and engine hosts must be on
+  Python 3.14** — a 3.11/3.12/3.13 host will refuse to install the wheel. The 3.11/3.12/3.13-specific test
+  apparatus is retired with this change (the `MEFOR_PY311_QUARANTINE` conftest lever, the `py3.11 store
+  soak` CI job, and `scripts/soak/store_soak.py`; the underlying BACKLOG #17 asyncio↔aiosqlite concern is
+  still mitigated by the shared session loop in `pyproject.toml`).
+
+### Security
+- **PHI-at-rest encryption closed across all three backends.** The patient `summary` (MRN + name) and
+  `metadata` columns are now encrypted at rest (previously cleartext even with encryption enabled), and the
+  SQL Server `error` / `last_error` / `message_events.detail` columns are brought to parity with SQLite and
+  Postgres — every cipher column is now AES-256-GCM at rest. Coverage is surfaced by a new authenticated,
+  audited `GET /security/posture` route (reports the active-key fingerprint + per-backend column coverage;
+  never key bytes).
+- **Fail-closed for PHI without a key.** An instance declared `data_class = phi` now **refuses to start**
+  without an encryption key (previously it started in cleartext with a warning), unless explicitly overridden
+  by the new, audited `[store].allow_unencrypted_phi`.
+- **Crypto-agility marker (additive).** The at-rest cipher marker is now version/algorithm-aware
+  (`mfenc:v2:<alg>:…`) so a future algorithm can be introduced without a data migration. The `mfenc:v1`
+  format is byte-identical and AES-256-GCM remains the only algorithm; decryption fails closed on an unknown
+  marker version or algorithm.
+- **Database-TLS hardening.** A new `[store].ssl_root_cert` pins a private database CA (Postgres), with
+  machine-store CA-import and certificate-rotation operator runbooks. The DPAPI key file's ACL now grants the
+  service account read access without broadening exposure.
+
+### Added
+- **Active-passive split-brain fence.** A monotonic leader-epoch fencing token on the leadership lease,
+  validated inside the FIFO claim transaction, so a superseded or paused ex-leader that resumes is fenced out
+  (it claims nothing) — backed by continuous "at most one leader" SLO checks and a real-handover failover
+  test. SQLite (single-node) behavior is unchanged.
+- **Effectively-once outbound delivery.** A same-transaction idempotency ledger skips re-delivery of an
+  already-delivered message after a failover or crash-recovery re-claim, without re-ordering a lane; an
+  operator-initiated replay still re-sends.
+- **Pre-side-effect leadership re-checks** so a node that loses leadership between claiming and sending
+  re-queues the work rather than emitting it as a stale leader.
+- `messagefoundry verify --check-disposition` for post-deploy disposition validation.
+
+### Fixed
+- CycloneDX SBOM generation on Python 3.14.
+- PyPI long-description rendering (version pins, links).
+- De-flaked several intermittent CI tests (failover-load timeouts, a harness server port-bind race, the
+  startup fault-isolation recovery assertion, and the docker-smoke shutdown-marker check).
+
 ## [0.2.1] — 2026-06-23 — Early Access
 
 ### Fixed

{messagefoundry-0.2.1 → messagefoundry-0.2.2}/CLAUDE.md

@@ -242,7 +242,7 @@ diverge enough to warrant it; keep this root file general.
 
 ## 6. Python Code Standards
 
-- Target **Python 3.11+**. Type-hint all public functions/attributes — **mypy runs in strict
+- Target **Python 3.14+** (the project requires `>=3.14`). Type-hint all public functions/attributes — **mypy runs in strict
   mode**.
 - **asyncio core:** never block the event loop; use `aiosqlite` and async connectors. Long
   loops/workers must be **cooperatively cancellable** (respond to the connection's stop signal)

{messagefoundry-0.2.1 → messagefoundry-0.2.2}/CONTRIBUTING.md

@@ -41,7 +41,7 @@ maintainer.)
    to `main` are blocked. Keep commits coherent (one logical layer per commit) with clear messages.
 2. **Set up the environment** (Windows/PowerShell shown; adapt for your OS):
    ```powershell
-   py -3.11 -m venv .venv
+   py -3.14 -m venv .venv
    .\.venv\Scripts\Activate.ps1
    pip install -e ".[dev,console]"
    ```

{messagefoundry-0.2.1 → messagefoundry-0.2.2}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: messagefoundry
-Version: 0.2.1
+Version: 0.2.2
 Summary: Open-source healthcare integration engine — route, transform, and validate messages across many formats and connection types
 License-Expression: AGPL-3.0-or-later
 License-File: LICENSE
 License-File: NOTICE
-Requires-Python: >=3.11
+Requires-Python: >=3.14
 Requires-Dist: aiosqlite>=0.20
 Requires-Dist: argon2-cffi>=23.1
 Requires-Dist: cryptography>=48.0.1
@@ -55,14 +55,15 @@ Description-Content-Type: text/markdown
 
 [![CI](https://github.com/wshallwshall/MessageFoundry/actions/workflows/ci.yml/badge.svg)](https://github.com/wshallwshall/MessageFoundry/actions/workflows/ci.yml)
 [![Security](https://github.com/wshallwshall/MessageFoundry/actions/workflows/security.yml/badge.svg)](https://github.com/wshallwshall/MessageFoundry/actions/workflows/security.yml)
-[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
-[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](pyproject.toml)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://github.com/wshallwshall/MessageFoundry/blob/main/LICENSE)
+[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue.svg)](https://github.com/wshallwshall/MessageFoundry/blob/main/pyproject.toml)
 
-MessageFoundry is an **open-source integration engine for healthcare**. It connects clinical and
-business systems — routing, transforming, and validating messages across many formats (HL7 v2, JSON,
-XML/SOAP, X12, database records) and connection types (MLLP, TCP, HTTP/REST, SOAP, database, files,
-SFTP/FTP). Configure it with guided tooling or extend it in Python; it runs on SQLite or PostgreSQL
-with authentication, RBAC, audit, and encryption-at-rest built in.
+MessageFoundry is an **open-source healthcare integration engine** — a modern, Python-native HL7
+interface engine. It connects clinical and business systems by routing, transforming, and validating
+messages across many formats (HL7 v2, JSON, XML/SOAP, X12, database records) and connection types
+(MLLP, MLLP-over-TLS, TCP, HTTP/REST, SOAP, FHIR, DICOM, database, files, SFTP/FTP). Configure it with
+guided tooling or extend it in Python; it runs on SQLite, PostgreSQL, or SQL Server with
+authentication, RBAC, audit logging, and encryption-at-rest built in.
 
 > Python import package: `messagefoundry`. Built with **hl7apy** + **python-hl7** (HL7 parsing/
 > validation), **FastAPI** (engine API), and **PySide6** (admin console).
@@ -82,10 +83,10 @@ The PySide6 console talks to it over a localhost HTTP + WebSocket API — the sa
 whether the engine runs in-process, as a local daemon, or (later) on a remote host.
 No hand-rolled IPC; the deployment split is a config choice, not an architectural fork.
 
-See **[docs/architecture-diagram.md](docs/architecture-diagram.md)** for the rendered diagrams —
+See **[docs/architecture-diagram.md](https://github.com/wshallwshall/MessageFoundry/blob/main/docs/architecture-diagram.md)** for the rendered diagrams —
 system topology, runtime message flow through the staged queue, and the config wiring graph (Mermaid,
 renders on GitHub and in the VS Code preview). The prose source of truth is
-[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+[docs/ARCHITECTURE.md](https://github.com/wshallwshall/MessageFoundry/blob/main/docs/ARCHITECTURE.md).
 
 ### Key decisions
 - **Reliable by default.** A durable, transactional pipeline gives at-least-once delivery,
@@ -97,9 +98,9 @@ renders on GitHub and in the VS Code preview). The prose source of truth is
   Python (`inbound`/`outbound`/`@router`/`@handler`) for full control — always version-controlled.
   The database holds runtime state and messages only, never configuration.
 - **PHI is first-class.** Authentication, RBAC, a user-attributed audit log of message
-  views/replays, and **encryption-at-rest** for message bodies (AES-256-GCM) are **built**; log
-  redaction and MLLPS/TLS are on the roadmap. See [docs/PHI.md](docs/PHI.md) for the built-vs-planned
-  data-protection map.
+  views/replays, **encryption-at-rest** for message bodies (AES-256-GCM), **global PHI log redaction**,
+  and **transport TLS** (HTTPS/WSS for the API plus MLLP-over-TLS) are **built**; MFA and off-box log
+  shipping remain on the roadmap. See [docs/PHI.md](https://github.com/wshallwshall/MessageFoundry/blob/main/docs/PHI.md) for the full data-protection map.
 
 ## Roadmap
 
@@ -132,26 +133,26 @@ renders on GitHub and in the VS Code preview). The prose source of truth is
       failover-load test harness (kill-the-primary-under-load), on **both** PostgreSQL and SQL Server
 - [x] **Native transport TLS** — in-process API TLS (HTTPS/WSS) and MLLP-over-TLS, with an off-loopback
       bind guard and a certificate-expiry monitor
-- [x] Published throughput + active-passive failover **baseline** ([docs/benchmarks/TUNING-BASELINE.md](docs/benchmarks/TUNING-BASELINE.md))
+- [x] Published throughput + active-passive failover **baseline** ([docs/benchmarks/TUNING-BASELINE.md](https://github.com/wshallwshall/MessageFoundry/blob/main/docs/benchmarks/TUNING-BASELINE.md))
 - [x] **SMART Backend Services token provider** — OAuth2 `client_credentials` + signed-JWT
       `client_assertion` (RS384/ES384) authenticating the FHIR/REST outbound against real SMART-secured
       servers (Epic, Oracle Health); a `with_smart_backend()` composer over `FHIR()`/`Rest()` that mints,
       caches, and re-mints (on 401) a short-lived bearer, token endpoint gated by `[egress].allowed_http`
-      ([ADR 0024](docs/adr/0024-smart-backend-services-token-provider.md))
+      ([ADR 0024](https://github.com/wshallwshall/MessageFoundry/blob/main/docs/adr/0024-smart-backend-services-token-provider.md))
 - [x] **base64 binary-carriage codec** — an `mfb64:v1:` marker carries arbitrary NUL-safe **bytes** over
       the str/TEXT ingress + store (`RawMessage.from_bytes()`/`.raw_bytes`/`.binary()`/`.is_binary`), plus
-      HL7 OBX-5 ED (Encapsulated Data) embedding helpers ([ADR 0028](docs/adr/0028-base64-binary-carriage-codec.md))
+      HL7 OBX-5 ED (Encapsulated Data) embedding helpers ([ADR 0028](https://github.com/wshallwshall/MessageFoundry/blob/main/docs/adr/0028-base64-binary-carriage-codec.md))
 - [x] **DICOM codec + C-STORE SCP** (Phase 1) — a pure codec (routing peek, headers/Structured Report,
       code-first SR→HL7 mapping helpers; **headers + SR only, no pixel data**) on `content_type=dicom`
-      payload-agnostic ingress, plus an inbound C-STORE SCP listener (`DICOM()`) ([ADR 0025](docs/adr/0025-dicom-codec-store-connectors.md))
+      payload-agnostic ingress, plus an inbound C-STORE SCP listener (`DICOM()`) ([ADR 0025](https://github.com/wshallwshall/MessageFoundry/blob/main/docs/adr/0025-dicom-codec-store-connectors.md))
 - [x] **Anonymizer / de-identification** — builds PHI-free test datasets from real traffic with
       deterministic secret-per-dataset pseudonymization, field-anchored site-code scrub, and fail-closed
       emission (never an un-scrubbed body), via a `tee anonymize-captures` subcommand and test-harness
-      hooks ([ADR 0030](docs/adr/0030-anonymization-test-harness-tee.md))
+      hooks ([ADR 0030](https://github.com/wshallwshall/MessageFoundry/blob/main/docs/adr/0030-anonymization-test-harness-tee.md))
 
 **Later** — higher-throughput delivery (a pooled/persistent MLLP connector); a read-only **component
 SDK** (fork-to-customize); DICOM Phase 2 (C-STORE SCU + C-ECHO + DICOMweb STOW-RS, designed); MFA and
-off-box log shipping. See [docs/EARLY-ADOPTER-GUIDE.md](docs/EARLY-ADOPTER-GUIDE.md) §2 for the current
+off-box log shipping. See [docs/EARLY-ADOPTER-GUIDE.md](https://github.com/wshallwshall/MessageFoundry/blob/main/docs/EARLY-ADOPTER-GUIDE.md) §2 for the current
 built-vs-experimental map.
 
 Horizontal **active-active** scale-out (the multi-node cluster path) was **dropped on 2026-06-18 and
@@ -163,24 +164,24 @@ supported HA model.
 **The recommended way to deploy MessageFoundry is to install the published package from
 [PyPI](https://pypi.org/project/messagefoundry/)** — a signed, version-pinned wheel is the
 supported production artifact, with no source checkout required. Install it as a **pinned
-dependency**, then scaffold your own config repo ([ADR 0017](docs/adr/0017-consumer-deployment-model.md)):
+dependency**, then scaffold your own config repo ([ADR 0017](https://github.com/wshallwshall/MessageFoundry/blob/main/docs/adr/0017-consumer-deployment-model.md)):
 
 ```bash
-pip install "messagefoundry==0.2.0"   # pin the exact engine version (core runtime, SQLite store)
+pip install "messagefoundry==0.2.1"   # pin the exact engine version (core runtime, SQLite store)
 messagefoundry init ./my-config-repo     # scaffold a standalone config repo
 cd ./my-config-repo
 messagefoundry serve --config config --env dev
 ```
 
-`0.2.0` is the current **Early Access** release on PyPI. Always **pin the exact version** so
+`0.2.1` is the current **Early Access** release on PyPI. Always **pin the exact version** so
 upgrades stay deliberate. Add the extras your deployment needs (each is opt-in and lazy-imported):
 
 ```bash
-pip install "messagefoundry[postgres]==0.2.0"    # PostgreSQL store backend (production server DB)
-pip install "messagefoundry[sqlserver]==0.2.0"   # SQL Server store backend (+ OS-level ODBC Driver 18)
-pip install "messagefoundry[console]==0.2.0"     # PySide6 admin console
-pip install "messagefoundry[sftp]==0.2.0"        # SFTP transport for the REMOTEFILE connector
-pip install "messagefoundry[dicom]==0.2.0"       # DICOM codec + C-STORE SCP (pydicom + pynetdicom)
+pip install "messagefoundry[postgres]==0.2.1"    # PostgreSQL store backend (production server DB)
+pip install "messagefoundry[sqlserver]==0.2.1"   # SQL Server store backend (+ OS-level ODBC Driver 18)
+pip install "messagefoundry[console]==0.2.1"     # PySide6 admin console
+pip install "messagefoundry[sftp]==0.2.1"        # SFTP transport for the REMOTEFILE connector
+pip install "messagefoundry[dicom]==0.2.1"       # DICOM codec + C-STORE SCP (pydicom + pynetdicom)
 ```
 
 > **Verify before you install (supply chain).** Every release is built by a GitHub Actions workflow,
@@ -192,7 +193,7 @@ pip install "messagefoundry[dicom]==0.2.0"       # DICOM codec + C-STORE SCP (py
 >
 > *(Engine developers install from a checkout instead — see [Development](#development).)*
 
-Piloting MessageFoundry? The **[Early-Adopter Installation & Rollout Guide](docs/EARLY-ADOPTER-GUIDE.md)**
+Piloting MessageFoundry? The **[Early-Adopter Installation & Rollout Guide](https://github.com/wshallwshall/MessageFoundry/blob/main/docs/EARLY-ADOPTER-GUIDE.md)**
 takes you from first install through a staged, go/no-go-gated path to full production
 (Lab → Shadow/Parallel → Limited → Full). It leads with an honest built-vs-experimental
 maturity map and covers prerequisites, install, security/PHI hardening, reliability
@@ -224,24 +225,24 @@ python -m messagefoundry.console --url http://127.0.0.1:8765
 
 ### VS Code extension & test harness
 
-- **VS Code extension** ([`ide/`](ide/)) — author and test interfaces in your editor: a New Route
+- **VS Code extension** ([`ide/`](https://github.com/wshallwshall/MessageFoundry/tree/main/ide/)) — author and test interfaces in your editor: a New Route
   Wizard, validate-on-save, a Test Bench (dry-run `.hl7` files with before/after diffs), Stage →
   Promote to a running engine, and an HL7-aware `@messagefoundry` chat participant. Open the `ide/`
-  folder in VS Code and press **F5**, or see [ide/README.md](ide/README.md).
+  folder in VS Code and press **F5**, or see [ide/README.md](https://github.com/wshallwshall/MessageFoundry/blob/main/ide/README.md).
 - **Test harness** — a standalone PySide6 send/receive MLLP tool for exercising the engine with
   synthetic, PHI-free traffic: `python -m harness`.
 
 ## License
 
 MessageFoundry is licensed under the **GNU Affero General Public License v3.0 or later**
-(`AGPL-3.0-or-later`) — see [LICENSE](LICENSE). Running a modified version as a network service
+(`AGPL-3.0-or-later`) — see [LICENSE](https://github.com/wshallwshall/MessageFoundry/blob/main/LICENSE). Running a modified version as a network service
 triggers the AGPL's §13 source-offer obligation. A separately-licensed commercial edition is planned
 by **MessageFoundry Organization** under the standard open-core model — see
-[COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md) (terms pending legal review). See [NOTICE](NOTICE)
+[COMMERCIAL-LICENSE.md](https://github.com/wshallwshall/MessageFoundry/blob/main/COMMERCIAL-LICENSE.md) (terms pending legal review). See [NOTICE](https://github.com/wshallwshall/MessageFoundry/blob/main/NOTICE)
 for copyright and attribution.
 
 ## Contributing
 
-Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md), our
-[Code of Conduct](CODE_OF_CONDUCT.md), and how the project is governed in [GOVERNANCE.md](GOVERNANCE.md).
-A signed [Contributor License Agreement](CLA.md) is required before a pull request can be merged.
+Contributions are welcome — see [CONTRIBUTING.md](https://github.com/wshallwshall/MessageFoundry/blob/main/CONTRIBUTING.md), our
+[Code of Conduct](https://github.com/wshallwshall/MessageFoundry/blob/main/CODE_OF_CONDUCT.md), and how the project is governed in [GOVERNANCE.md](https://github.com/wshallwshall/MessageFoundry/blob/main/GOVERNANCE.md).
+A signed [Contributor License Agreement](https://github.com/wshallwshall/MessageFoundry/blob/main/CLA.md) is required before a pull request can be merged.