messagefoundry 0.2.2__tar.gz → 0.2.4__tar.gz

messagefoundry-0.2.4/.github/workflows/codeql.yml

@@ -0,0 +1,67 @@
+name: CodeQL
+
+# Deep semantic SAST (taint / data-flow analysis) that complements bandit and the curated semgrep
+# rules in security.yml — it finds vulnerable flows those pattern matchers can't, e.g. untrusted
+# HL7/config data reaching a sink across function boundaries.
+#
+# WHY THIS IS GUARDED TO THE MIRROR: CodeQL uploads results to GitHub code scanning, which on a
+# PRIVATE repo requires paid GitHub Advanced Security (see security.yml's header note). This repo's
+# source of truth is private, but the OSS mirror MEFORORG/MessageFoundry is PUBLIC, where CodeQL +
+# code scanning are FREE. So the analyze job is gated on the repo slug: it is SKIPPED (a no-op) on the
+# private source repo and runs only once publish.ps1 mirrors this file to MEFORORG/MessageFoundry.
+# Nothing to pay, nothing to fail on the private side.
+#
+# PINNING CAVEAT: this repo SHA-pins every Action for supply-chain integrity. actions/checkout below
+# reuses the repo's existing v7.0.0 pin; the github/codeql-action steps are on the v3 tag for now
+# because the live commit SHA must be looked up at authoring — SHA-pin them before treating this as a
+# hardened gate (OSSF Scorecard / zizmor would flag the unpinned tags).
+#
+# ALTERNATIVE (no file): on the public mirror you can instead enable CodeQL "default setup" from
+# Settings -> Security -> Code scanning (one toggle, auto-pinned, auto-updated). Default setup and this
+# advanced workflow are mutually exclusive — if you turn default setup ON, delete this file.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Weekly, so newly-shipped CodeQL queries run against unchanged code (same rationale as the daily
+    # pip-audit cron: a fresh finding against a quiet codebase shouldn't wait for the next push).
+    - cron: "0 7 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  analyze:
+    name: CodeQL (${{ matrix.language }})
+    # ONLY on the public mirror — code scanning is free there; on the private source repo it would need
+    # paid GHAS, so this is a skipped no-op there. (GitHub Actions string == is case-insensitive.)
+    if: github.repository == 'MEFORORG/MessageFoundry'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write # upload the SARIF results to code scanning
+      actions: read
+    strategy:
+      fail-fast: false
+      matrix:
+        # python = the engine; javascript-typescript = the ide/ VS Code extension (both ship to the
+        # mirror). Both are interpreted — CodeQL needs no build step. Drop a language to narrow scope.
+        language: [python, javascript-typescript]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false # CodeQL uploads via the job token, not a persisted git credential
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3 # TODO: SHA-pin (repo convention)
+        with:
+          languages: ${{ matrix.language }}
+          # security-extended adds higher-recall security queries on top of the default suite.
+          queries: security-extended
+      - name: Analyze
+        uses: github/codeql-action/analyze@v3 # TODO: SHA-pin (repo convention)
+        with:
+          category: "/language:${{ matrix.language }}"

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

@@ -15,6 +15,14 @@
 # `-*` tags publish to PRODUCTION PyPI (a TestPyPI route would need its own Trusted Publisher). Cut the tag
 # only AFTER the py.typed marker (WS-3) is on main — the wheel smoke step enforces this on a tag.
 #
+# SECOND distribution — `messagefoundry-harness` (the synthetic test/load/failover harness,
+# packaging/messagefoundry-harness/) — is built + published in lockstep by the `release-harness` job
+# below (same version, same tag). Its PyPI publish is GATED on the `PUBLISH_HARNESS` repo variable so it
+# stays a no-op until the OWNER (one-time): (1) configures a `messagefoundry-harness` PyPI Trusted
+# Publisher — a PENDING publisher for repo wshallwshall/MessageFoundry + workflow `release.yml` (blank
+# environment, matching the engine) — then (2) sets repo variable PUBLISH_HARNESS=true. Until then the
+# job still BUILDS + version-checks the harness wheel each release and attaches it to the GitHub release.
+#
 # The version is single-sourced from messagefoundry/__init__.py (hatchling dynamic version), so the built
 # artifact's version must match the tag.
 name: release
@@ -151,3 +159,64 @@ jobs:
           packages-dir: dist-pub/
           skip-existing: true
           attestations: true
+
+  release-harness:
+    # Build + publish the SEPARATE `messagefoundry-harness` distribution (the synthetic test/load/failover
+    # harness, packaging/messagefoundry-harness/) in lockstep with the engine — same version, same tag.
+    # Isolated from the `release` job so a harness-side issue can never jeopardize the engine release;
+    # `needs: release` so the engine ships (and its GitHub release exists) first. Inherits the workflow's
+    # contents:write + id-token:write. The PyPI publish is GATED on the `PUBLISH_HARNESS` repo variable:
+    # until the owner sets up the harness Trusted Publisher AND PUBLISH_HARNESS=true (see the header note),
+    # this job still BUILDS + version-checks the wheel and attaches it to the GitHub release, but does not
+    # publish — so a missing harness PyPI project can never red a release.
+    needs: release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.14"
+
+      - name: Build the harness wheel (wheel-only — harness/ is force-included from the repo root)
+        run: |
+          python -m pip install --upgrade pip build
+          # Wheel-only on purpose: the harness source (harness/) lives OUTSIDE this project dir (it is
+          # force-included from ../../harness), so an sdist would not be self-contained. Pure-Python, so a
+          # wheel suffices. Version is read from messagefoundry/__init__.py (lockstep with the engine).
+          python -m build --wheel ./packaging/messagefoundry-harness --outdir harness-dist
+          ls -l harness-dist/
+
+      - name: Smoke-check the harness wheel (version == engine == tag)
+        run: |
+          built=$(python -c "import glob,re; print(re.search(r'messagefoundry_harness-([^-]+)-', glob.glob('harness-dist/*.whl')[0]).group(1))")
+          echo "harness wheel version: $built"
+          if [ "${GITHUB_REF_TYPE:-}" = "tag" ]; then
+            want="${GITHUB_REF_NAME#v}"
+            [ "$built" = "$want" ] || { echo "::error::harness wheel version $built != tag $want"; exit 1; }
+          fi
+
+      - name: Attach the harness wheel to the GitHub release
+        if: startsWith(github.ref, 'refs/tags/')
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "${GITHUB_REF_NAME}" harness-dist/*.whl --clobber
+
+      - name: Upload harness artifact (dry-run / always)
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: harness-artifacts
+          path: harness-dist/
+          if-no-files-found: ignore
+
+      # GATED: no-op until the owner configures the messagefoundry-harness PyPI Trusted Publisher AND sets
+      # repo variable PUBLISH_HARNESS=true. The build + version-check above still run every release.
+      - name: Publish messagefoundry-harness to PyPI (Trusted Publishing / OIDC)
+        if: ${{ startsWith(github.ref, 'refs/tags/') && vars.PUBLISH_HARNESS == 'true' }}
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
+        with:
+          packages-dir: harness-dist/
+          skip-existing: true
+          attestations: true

messagefoundry-0.2.4/.github/workflows/scorecard.yml

@@ -0,0 +1,59 @@
+name: Scorecard
+
+# OpenSSF Scorecard — a holistic supply-chain hygiene score (Pinned-Dependencies, Dangerous-Workflow,
+# Token-Permissions, Branch-Protection, Maintained, SAST-present, ...). It validates the hardening this
+# repo already does (SHA-pinned Actions, least-privilege tokens) and catches regressions, and yields a
+# public OpenSSF badge.
+#
+# WHY GUARDED TO THE MIRROR: like CodeQL, Scorecard uploads SARIF to GitHub code scanning (paid GHAS on
+# a private repo) and `publish_results: true` requires a PUBLIC repo. So this is gated to the public
+# mirror MEFORORG/MessageFoundry — a skipped no-op on the private source repo, free on the mirror after
+# publish.ps1 mirrors this file. NOTE: the Branch-Protection check then reflects the MIRROR's settings,
+# not the private repo's; the workflow-hardening checks (Pinned-Dependencies / Dangerous-Workflow /
+# Token-Permissions) assess the shared source and are the signal that transfers.
+#
+# PINNING CAVEAT: actions/checkout + actions/upload-artifact reuse this repo's existing SHA pins; the
+# ossf/scorecard-action and github/codeql-action/upload-sarif steps are on version tags pending a
+# SHA-pin lookup (zizmor / Scorecard itself will flag them).
+on:
+  branch_protection_rule:
+  schedule:
+    - cron: "0 8 * * 1" # weekly (Mon 08:00 UTC)
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions: read-all
+
+jobs:
+  analysis:
+    name: Scorecard analysis
+    # ONLY on the public mirror (free code scanning + public badge); skipped no-op on the private repo.
+    if: github.repository == 'MEFORORG/MessageFoundry'
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write # upload the SARIF results to code scanning
+      id-token: write # publish results to the public OpenSSF Scorecard API (the badge)
+      contents: read
+      actions: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - name: Run Scorecard
+        uses: ossf/scorecard-action@v2 # TODO: SHA-pin (repo convention)
+        with:
+          results_file: results.sarif
+          results_format: sarif
+          publish_results: true
+      - name: Upload the SARIF artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: scorecard-sarif
+          path: results.sarif
+          retention-days: 5
+      - name: Upload to code scanning
+        uses: github/codeql-action/upload-sarif@v3 # TODO: SHA-pin (repo convention)
+        with:
+          sarif_file: results.sarif

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

@@ -109,6 +109,43 @@ jobs:
           name: sbom-cyclonedx
           path: sbom.cdx.json
 
+  trivy:
+    name: trivy (container image vulnerabilities)
+    runs-on: ubuntu-latest
+    # ADVISORY for its first cycle (continue-on-error): scan the built engine image for OS-package and
+    # Python CVEs — the supply-chain layer pip-audit (lockfile only) and bandit/semgrep (source only)
+    # never see: the Debian base, system libs, and (on the -sqlserver variant) the msodbcsql18/unixODBC
+    # apt layer. Once a baseline run confirms it's clean, DELETE `continue-on-error` to make it BLOCKING
+    # like the other gates here. There's now a real docker/Dockerfile, so the image is a live surface.
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - name: Build the slim engine image
+        # The slim default the docker-smoke leg (ci.yml) and the Dockerfile's `docker build` docs produce.
+        run: docker build -f docker/Dockerfile -t messagefoundry:scan .
+      - name: Install Trivy (pinned)
+        run: |
+          # Pin the release; bump deliberately (same posture as the gitleaks job). Verify the tag exists
+          # at https://github.com/aquasecurity/trivy/releases if this step 404s.
+          VER=0.71.2
+          curl -sSfL "https://github.com/aquasecurity/trivy/releases/download/v${VER}/trivy_${VER}_Linux-64bit.tar.gz" \
+            | tar -xz -C /tmp trivy
+          sudo install -m 0755 /tmp/trivy /usr/local/bin/trivy
+          trivy --version
+      - name: Scan the image (fixable HIGH/CRITICAL fail the build)
+        # --ignore-unfixed keeps the gate ACTIONABLE: a Debian CVE with no upstream fix can't be
+        # remediated by us and shouldn't redden CI; only patchable HIGH/CRITICAL fail. --scanners vuln
+        # keeps this to CVEs (secrets stay gitleaks' job). Extend to `--target runtime-sqlserver` (more
+        # OS surface) once this is green. Trivy auto-pulls its vuln DB from ghcr.io on first run.
+        run: |
+          trivy image --no-progress --scanners vuln \
+            --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 \
+            messagefoundry:scan
+      - name: Lint the Dockerfile for misconfig (informational)
+        # IaC checks (non-root USER, pinned base, secrets in layers). Informational only — never fails.
+        if: always()
+        run: trivy config --no-progress --severity HIGH,CRITICAL docker/Dockerfile || true
+
   bandit:
     name: bandit (Python SAST)
     runs-on: ubuntu-latest
@@ -174,6 +211,32 @@ jobs:
           # dangerous-sink rules as the engine.
           semgrep --config .semgrep --error --metrics off messagefoundry tee
 
+  zizmor:
+    name: zizmor (GitHub Actions static analysis)
+    runs-on: ubuntu-latest
+    # ADVISORY for its first cycle (continue-on-error): static analysis of the workflow files THEMSELVES
+    # (Trail of Bits) — template injection, over-broad GITHUB_TOKEN permissions, unpinned `uses:`,
+    # artifact poisoning. Complements (and enforces) the by-hand SHA-pinning across these workflows.
+    # Once a baseline run is reviewed/clean, DELETE `continue-on-error` to make it blocking. (It will
+    # flag the `@v3` codeql-action tags in codeql.yml — that's the intended forcing function to pin them.)
+    continue-on-error: true
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+        with:
+          python-version: "3.14"
+      - name: Install zizmor (pinned)
+        run: |
+          # Pin deliberately; verify the tag at https://github.com/zizmorcore/zizmor/releases if it 404s.
+          python -m pip install --upgrade pip "zizmor==1.5.2"
+      - name: Analyze the workflows
+        env:
+          # Lets zizmor run its online audits (e.g. unpinned / known-problematic action refs).
+          GH_TOKEN: ${{ github.token }}
+        run: zizmor .github/workflows
+
   crypto-inventory:
     name: crypto-inventory (ASVS 11.1.3 discovery gate)
     runs-on: ubuntu-latest

{messagefoundry-0.2.2 → messagefoundry-0.2.4}/.gitignore

@@ -74,3 +74,9 @@ TRANSCRIPTS.md
 /docs/security/DEPENDENCY-RESPONSE-A4-HANDOFF.md
 # vuln_metrics.py local CSV output (the CI run uploads it as an artifact; not committed)
 /docs/security/metrics/
+
+# Operator-local load/throughput profiles — tuned to a specific deployment's volume; kept OUT of the
+# OSS repo + public mirror (the plan itself lives on the operator share, WIN2025-LOAD-THROUGHPUT-MATRIX.md).
+# Still usable by name (they sit in PROFILES_DIR) and copy-on to the test box.
+/harness/load/profiles/hospital-baseline.toml
+/harness/load/profiles/soak-12h.toml

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

@@ -6,6 +6,51 @@ All notable changes to MessageFoundry are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.2.4] — 2026-06-26 — Early Access
+
+A bug-fix release that completes the EF-6 SQL Server fix shipped in 0.2.3.
+
+### Fixed
+- **SQL Server: EF-6 "Connection is busy with results for another command" fully resolved (0.2.3's fix
+  was incomplete).** v0.2.3 (#543) switched the FIFO claim read to `fetchall`, but draining the
+  `UPDATE...OUTPUT` *rows* does not free the *statement handle* — without MARS the pooled connection was
+  still returned to the aioodbc pool busy, so the error reproduced at every cold start. All pooled cursor
+  sites now close the cursor (`SQLFreeStmt`/`SQLCloseCursor`) via a new `_cursor` context manager before
+  the connection is released, on both the success and exception paths; `claim_ready` (another
+  `UPDATE...OUTPUT`) and the `DELETE...OUTPUT` handoffs had the same latent gap and are covered too. A
+  driver-free unit test now asserts the close-before-release invariant so the regression can't recur.
+  SQLite and PostgreSQL were unaffected. (#550)
+
+## [0.2.3] — 2026-06-26 — Early Access
+
+A bug-fix + feature release: the SQL Server store no longer raises "connection busy" errors under
+concurrent load, plus connection/transport event logging, GUI-managed translation tables, and inbound
+listener port-conflict detection.
+
+### Fixed
+- **SQL Server: "Connection is busy with results for another command" under concurrent load (EF-6).**
+  `claim_next_fifo` — and three sibling sites (`_maybe_finalize`, `consume_recovery_code_hash`,
+  `consume_totp_step`) — read a result-set-returning statement with a lone `fetchone()` and could return
+  the pooled connection to the pool with the result set still pending, so the next borrower's first
+  command raced an `HY000` busy error (ODBC Driver 18, no MARS). All affected sites now fully drain the
+  result set (`fetchall`) before commit/release. SQLite and PostgreSQL were unaffected (asyncpg
+  materializes rows; SQLite has no shared pooled-connection single-result-set constraint). (#543)
+
+### Added
+- **Connection/transport event log + "Response Sent" ACK capture** (ADR 0020 / ADR 0021). A new id-keyed,
+  metadata-only `connection_event` table records inbound connection lifecycle, pre-ingress failures, and
+  outbound lane transitions, with a `[diagnostics]` config block (per-connection overrides + retention),
+  a `GET /events` read API, and a console **Event Log** page. Event reasons are scrubbed and encrypted at
+  rest. (#541)
+- **GUI-managed translation tables (code sets)** (ADR 0033). A code-set CLI + writer and a VS Code
+  extension grid editor / **Translation Tables** view for maintaining code-set mappings. (#540)
+- **Inbound listener port-conflict detection** — static + runtime checks that flag two inbound
+  connections bound to the same host:port before they collide at startup. (#538)
+
+### Changed
+- Docs: README install instructions are now version-agnostic and link the website docs; the roadmap
+  section is replaced with a features summary. (#542, #544)
+
 ## [0.2.2] — 2026-06-24 — Early Access
 
 A security-hardening release: PHI-at-rest encryption is closed across every backend, the active-passive
@@ -141,7 +186,10 @@ tests, but the external code review + penetration test (the bar for a security-c
 - Releases are built, SBOM'd (CycloneDX), and signed with [Sigstore](https://www.sigstore.dev/) — see the
   `release` workflow.
 
-[Unreleased]: https://github.com/wshallwshall/MessageFoundry/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/wshallwshall/MessageFoundry/compare/v0.2.4...HEAD
+[0.2.4]: https://github.com/wshallwshall/MessageFoundry/compare/v0.2.3...v0.2.4
+[0.2.3]: https://github.com/wshallwshall/MessageFoundry/compare/v0.2.2...v0.2.3
+[0.2.2]: https://github.com/wshallwshall/MessageFoundry/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/wshallwshall/MessageFoundry/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/wshallwshall/MessageFoundry/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/wshallwshall/MessageFoundry/releases/tag/v0.1.0

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

@@ -1,10 +1,23 @@
 Metadata-Version: 2.4
 Name: messagefoundry
-Version: 0.2.2
+Version: 0.2.4
 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
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
 Requires-Python: >=3.14
 Requires-Dist: aiosqlite>=0.20
 Requires-Dist: argon2-cffi>=23.1
@@ -102,62 +115,34 @@ renders on GitHub and in the VS Code preview). The prose source of truth is
   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
-
-**Phase 1 — minimum reliable engine**
-- [x] Connection/Router/Handler model + config-module loader
-- [x] Durable message store / queue (SQLite WAL, outbox pattern)
-- [x] Parse / validate (tolerant peek + opt-in strict validation)
-- [x] MLLP source + destination (correct `0x0B … 0x1C 0x0D` framing, ACK/NACK)
-- [x] File source + destination
-- [x] Pipeline: source → parse/validate/filter/transform → outbox → per-dest workers,
-      with retry/backoff, dead-letter, and replay
-- [x] localhost API (connections start/stop, message track/search/detail, replay, stats,
-      live WebSocket feed) + `python -m messagefoundry serve`
-- [x] PySide6 console: connection dashboard, message browser, HL7 parse-tree viewer,
-      delivery/audit trail, replay (`python -m messagefoundry.console`)
-
-**Phase 1 complete.**
-
-**Since Phase 1 — now built**
-- [x] Staged pipeline (ingress → routed → outbound): at-least-once handoff, dead-letter, replay
-- [x] Authentication, RBAC, user-attributed audit log, at-rest body encryption (AES-256-GCM)
-- [x] **PostgreSQL** store backend (production, single-node)
-- [x] **Microsoft SQL Server** store backend (production, single-node)
-- [x] REST, SOAP, and Database destinations
-- [x] Database poll source
-- [x] Reference / lookup tables (`code_set`) for enrichment
-- [x] Alerting — logging sink + webhook/email notifier
-- [x] Connections-as-data (`connections.toml`) editable by hand or a VS Code GUI
-- [x] **Active-passive high availability** — self-fencing leadership lease, leader-gated graph, and a
-      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](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](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](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](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](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](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
-its code removed** — it is not a planned milestone; single-leader **active-passive** HA (above) is the
-supported HA model.
+## Features
+
+MessageFoundry ships a reliable, PHI-aware engine today: the Connection/Router/Handler graph
+over a durable staged pipeline (at-least-once delivery, retries, dead-letter, replay), backed by
+SQLite, PostgreSQL, or SQL Server. It speaks MLLP (plain and over TLS), file/SFTP, REST, SOAP,
+FHIR, database, and DICOM (C-STORE SCP), parses HL7 v2 tolerantly (with opt-in strict validation)
+and carries other formats payload-agnostically (JSON, XML/SOAP, X12, binary). Security is
+first-class — authentication, RBAC, a user-attributed audit log, at-rest body encryption, and
+transport TLS — and it runs single-node or in active-passive high availability.
+
+**See the full, up-to-date feature breakdown — built vs. planned — at
+[messagefoundry.org/features-table.html](https://messagefoundry.org/features-table.html).**
+
+## Documentation
+
+Full documentation lives on **[messagefoundry.org](https://messagefoundry.org/)**:
+
+- **[Mental map](https://messagefoundry.org/assets/docs/MessageFoundry-Mental-Model.pdf)** — a one-page
+  picture of how the pieces fit: Connections → Router → Handlers → Connections, with the headless
+  engine and the console/IDE that drive it.
+- **[Install Guide](https://messagefoundry.org/assets/docs/MessageFoundry-Install-Guide.pdf)** — install,
+  configure, secure, and roll out to production.
+- **[User Guide](https://messagefoundry.org/assets/docs/MessageFoundry-User-Guide.pdf)** — author and
+  operate interfaces day to day.
+
+**Get started:** [Quickstart](https://messagefoundry.org/getting-started.html) ·
+[Guides](https://messagefoundry.org/guides/) ·
+[Documents](https://messagefoundry.org/documents.html)
 
 ## Installing & rolling out
 
@@ -167,23 +152,32 @@ supported production artifact, with no source checkout required. Install it as a
 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.1"   # pin the exact engine version (core runtime, SQLite store)
-messagefoundry init ./my-config-repo     # scaffold a standalone config repo
+pip install "messagefoundry==<version>"   # 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.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):
+MessageFoundry is in **Early Access**. Always **pin the exact version** so upgrades stay
+deliberate — replace `<version>` with the current release shown at the top of the
+[PyPI project page](https://pypi.org/project/messagefoundry/). Add the extras your deployment
+needs (each is opt-in and lazy-imported):
 
 ```bash
-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)
+pip install "messagefoundry[console]==<version>"     # admin console (PySide6 GUI) — the operator UI; most operators want this
+pip install "messagefoundry[postgres]==<version>"    # PostgreSQL store backend (production server DB)
+pip install "messagefoundry[sqlserver]==<version>"   # SQL Server store backend (+ OS-level ODBC Driver 18)
+pip install "messagefoundry[sftp]==<version>"        # SFTP transport for the REMOTEFILE connector
+pip install "messagefoundry[dicom]==<version>"       # DICOM codec + C-STORE SCP (pydicom + pynetdicom)
 ```
 
+**What's in the `messagefoundry` package — and what isn't.** It is the **engine plus the admin
+console**: the console ships in the same wheel, with its PySide6/GUI dependencies as the opt-in
+`[console]` extra, so a headless server, container, or adopter install stays lean — the console is one
+flag away (`messagefoundry[console]`) when you want the operator UI. The **VS Code extension is a
+separate product, not on PyPI** (a VS Code extension is a different ecosystem); see *VS Code extension &
+test harness* below for where to get it.
+
 > **Verify before you install (supply chain).** Every release is built by a GitHub Actions workflow,
 > Sigstore-signed, and carries SLSA build-provenance + PEP 740 attestations. Verify a downloaded
 > wheel against its source commit with
@@ -193,7 +187,7 @@ pip install "messagefoundry[dicom]==0.2.1"       # DICOM codec + C-STORE SCP (py
 >
 > *(Engine developers install from a checkout instead — see [Development](#development).)*
 
-Piloting MessageFoundry? The **[Early-Adopter Installation & Rollout Guide](https://github.com/wshallwshall/MessageFoundry/blob/main/docs/EARLY-ADOPTER-GUIDE.md)**
+Piloting MessageFoundry? The **[Install Guide](https://messagefoundry.org/assets/docs/MessageFoundry-Install-Guide.pdf)**
 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
@@ -227,10 +221,16 @@ python -m messagefoundry.console --url http://127.0.0.1:8765
 
 - **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](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`.
+  Promote to a running engine, and an HL7-aware `@messagefoundry` chat participant. **It is not on PyPI**
+  (a VS Code extension is a different ecosystem) **and not yet on the VS Code Marketplace** — Marketplace
+  + Open VSX publishing is **planned** (see [the backlog](https://github.com/wshallwshall/MessageFoundry/blob/main/docs/BACKLOG.md)). Until then, get it from
+  this repo: open the `ide/` folder in VS Code and press **F5** (Extension Development Host), or build the
+  VSIX (`cd ide && npm install && npx @vscode/vsce package`) and install the `.vsix`. See
+  [ide/README.md](https://github.com/wshallwshall/MessageFoundry/blob/main/ide/README.md).
+- **Test harness** — synthetic-only send/receive (MLLP), load, and failover tooling for exercising a
+  running engine. It ships as a **separate distribution, `messagefoundry-harness`**, released in lockstep
+  with the engine (it is *not* in the engine wheel): `pip install messagefoundry-harness`, then
+  `python -m harness`. From a checkout, run `python -m harness` directly. Synthetic, PHI-free traffic only.
 
 ## License