messagefoundry 0.2.11__tar.gz → 0.2.13__tar.gz

{messagefoundry-0.2.11 → messagefoundry-0.2.13}/.github/workflows/benchmark.yml

@@ -84,7 +84,7 @@ jobs:
       MEFOR_STORE_DATABASE: messagefoundry
       MEFOR_STORE_USERNAME: postgres
       MEFOR_STORE_PASSWORD: mefor
-      MEFOR_STORE_POOL_SIZE: "5"
+      MEFOR_STORE_POOL_SIZE: "40"  # track the shipped default (ADR 0062: 5 -> 40)
       MEFOR_STORE_ENCRYPT: "false"  # plaintext to the container; the TLS-hardening guard needs the escape
       MEFOR_ALLOW_INSECURE_TLS: "1"
     steps:
@@ -151,7 +151,7 @@ jobs:
       MEFOR_STORE_AUTH: sql
       MEFOR_STORE_USERNAME: sa
       MEFOR_STORE_PASSWORD: "Str0ng_P@ssw0rd!"
-      MEFOR_STORE_POOL_SIZE: "5"
+      MEFOR_STORE_POOL_SIZE: "40"  # track the shipped default (ADR 0062: 5 -> 40)
       MEFOR_STORE_TRUST_SERVER_CERTIFICATE: "true"
       MEFOR_ALLOW_INSECURE_TLS: "1"
     steps:

{messagefoundry-0.2.11 → messagefoundry-0.2.13}/.github/workflows/ci.yml

@@ -431,6 +431,33 @@ jobs:
           MEFOR_ALLOW_INSECURE_TLS: "1"
         run: pytest tests/test_load_failover_sqlserver.py -v
 
+      - name: Run the throughput-lever backend invariants on real SQL Server (B1 inline, B2 batch-claim, ...)
+        env:
+          MEFOR_TEST_SQLSERVER: "1"
+          MEFOR_STORE_BACKEND: sqlserver
+          MEFOR_STORE_SERVER: localhost
+          MEFOR_STORE_PORT: "1433"
+          MEFOR_STORE_DATABASE: MessageFoundry
+          MEFOR_STORE_AUTH: sql
+          MEFOR_STORE_USERNAME: sa
+          MEFOR_STORE_PASSWORD: "Str0ng_P@ssw0rd!"
+          MEFOR_STORE_TRUST_SERVER_CERTIFICATE: "true"
+          MEFOR_ALLOW_INSECURE_TLS: "1"
+        # The staged-pipeline throughput levers (ADR 0057 inline fast-path, ADR 0058 batch-claim, ...) carry
+        # reliability-core invariant tests — crash-replay, poison-bound, and the per-lane-FIFO locked-head-
+        # BLOCKS (#285) gate — that are MEFOR_TEST_SQLSERVER-gated but live in their OWN files, so the named
+        # suites above never picked them up and they ran only on SQLite. Run them here against the real
+        # backend. APPEND each new lever's test file per docs/throughput-build-plan.md.
+        run: >-
+          pytest -v
+          tests/test_inline_fast_path.py
+          tests/test_batch_claim_fifo.py
+          tests/test_batch_claim_worker.py
+          tests/test_batch_claim_locking.py
+          tests/test_seq_only_fifo.py
+          tests/test_fifo_index_migration.py
+          tests/test_per_lane_wake.py
+
   # Postgres store backend (Track B): run the gated store suite against a real PostgreSQL service
   # container (Linux, so 1x minutes). Skipped on PRs like the other server-DB job to save spend; runs
   # on push to main and on-demand (workflow_dispatch — use `gh workflow run ci.yml --ref <branch>` to
@@ -504,6 +531,53 @@ jobs:
           MEFOR_ALLOW_INSECURE_TLS: "1"
         run: pytest tests/test_load_failover_postgres.py -v
 
+      - name: Run the throughput-lever backend invariants on real Postgres (B1 inline, B2 batch-claim, ...)
+        env:
+          MEFOR_TEST_POSTGRES: "1"
+          MEFOR_STORE_BACKEND: postgres
+          MEFOR_STORE_SERVER: localhost
+          MEFOR_STORE_PORT: "5432"
+          MEFOR_STORE_DATABASE: messagefoundry
+          MEFOR_STORE_USERNAME: postgres
+          MEFOR_STORE_PASSWORD: mefor
+          MEFOR_STORE_ENCRYPT: "false"
+          MEFOR_ALLOW_INSECURE_TLS: "1"
+        # The throughput levers' MEFOR_TEST_POSTGRES-gated invariants (esp. the FOR-UPDATE no-SKIP-LOCKED
+        # locked-head-BLOCKS twin of #285, and the batch FIFO/crash tests) live in their own files. APPEND
+        # each new lever's test file per docs/throughput-build-plan.md.
+        run: >-
+          pytest -v
+          tests/test_inline_fast_path.py
+          tests/test_batch_claim_fifo.py
+          tests/test_batch_claim_worker.py
+          tests/test_batch_claim_locking.py
+          tests/test_seq_only_fifo.py
+          tests/test_fifo_index_migration.py
+          tests/test_per_lane_wake.py
+
+      - name: Run the connection-scale pool-wait smoke on real Postgres (B11 wall #2, tiny pool)
+        env:
+          MEFOR_TEST_POSTGRES: "1"
+          MEFOR_STORE_BACKEND: postgres
+          MEFOR_STORE_SERVER: localhost
+          MEFOR_STORE_PORT: "5432"
+          MEFOR_STORE_DATABASE: messagefoundry
+          MEFOR_STORE_USERNAME: postgres
+          MEFOR_STORE_PASSWORD: mefor
+          MEFOR_STORE_ENCRYPT: "false"
+          MEFOR_ALLOW_INSECURE_TLS: "1"
+          # FORCE a below-default pool (4 connections) so the perf_counter-measured acquire-WAIT
+          # histogram (the PRIMARY pool-wait signal) is non-trivial even at small N: ~3N inbound workers
+          # contend for 4 connections, so acquires actually queue and the percentiles populate. The
+          # default pool (40) would mask the wall. 4 (not 1-2) is deliberate: GET /status runs
+          # db_status()'s four sequential COUNT(*) queries on every poll, and an extremely tiny pool
+          # starves those acquires past the poller's HTTP timeout under the empty-claim herd on a slow
+          # runner — every poll then fails and the drain loops burn the test budget (the PR #675 hang).
+          # This still gives the B11 pool-wait instrumentation real regression coverage SQLite (no pool)
+          # cannot — the connscale harness OWNS the engine subprocess and inherits this env.
+          MEFOR_STORE_POOL_SIZE: "4"
+        run: pytest tests/test_connscale_postgres.py -v
+
   # Headless load test (Track B / throughput): serve the synthetic high-fan-out load config (auth
   # off, small fan-out) and drive the smoke profile through the real `python -m harness --load` CLI,
   # asserting zero message loss + all SLOs (exit 0) and uploading the JSON/CSV report. Skipped on PRs

{messagefoundry-0.2.11 → messagefoundry-0.2.13}/.github/workflows/release.yml

@@ -347,7 +347,11 @@ jobs:
           MEFOR_FROZEN_CONSOLE_DIR: dist/messagefoundry-console
           QT_QPA_PLATFORM: offscreen
         run: |
-          pip install pytest
+          # pytest-timeout is required: the repo's pyproject `addopts` sets `--timeout=60
+          # --timeout-method=thread`, so a bare `pip install pytest` aborts the run with
+          # "unrecognized arguments: --timeout" before the smoke ever executes (it leaves the per-test
+          # watchdog intact instead of stripping addopts).
+          pip install pytest pytest-timeout
           python -m pytest tests/test_frozen_launch_smoke.py -v -p no:cacheprovider
 
       - name: Install Inno Setup (pinned)

{messagefoundry-0.2.11 → messagefoundry-0.2.13}/.gitignore

@@ -80,6 +80,10 @@ TRANSCRIPTS.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
+# Deep-research survey of alternative OSS DB backends for the shared-DB commit-wall — local working
+# note, not a committed artifact (the conclusion is carried in the throughput ADRs / AI memory).
+/docs/research/db-commit-wall-backend-survey.md
+
 # --- MessageFoundry ---
 .mefor/
 *.db*

{messagefoundry-0.2.11 → messagefoundry-0.2.13}/CHANGELOG.md

@@ -6,6 +6,103 @@ All notable changes to MessageFoundry are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.2.13] — 2026-07-01 — Early Access
+
+The **store connection-scale sizing** wave — right-size the server-DB connection pool to the measured
+inverted-U optimum, guard against over-provisioning, and guarantee the message store stays unified. All
+changes are **server-DB-only**; the single-node SQLite default is unaffected.
+
+### Added
+- **Soft store-pool over-provisioning warning** ([ADR 0062](docs/adr/0062-default-store-pool-size.md)) — a
+  server-DB engine now logs an advisory `WARNING` at graph start if `[store].pool_size` is sized past the
+  connection-pool inverted-U optimum: at/beyond the ~80 catastrophic cliff, or oversized for the engine's
+  inbound-interface count (`~2.5 ×` interfaces). Advisory only — it never blocks startup; SQLite has no pool
+  so it is skipped, and the default (40) never trips it. Guards the "set a huge pool for 1500 connections"
+  footgun (which is a *sharding* problem, not a pool one).
+
+### Changed
+- **Default server-DB store connection pool size raised 5 → 40** ([`[store].pool_size`](docs/CONFIGURATION.md),
+  env `MEFOR_STORE_POOL_SIZE`; [ADR 0062](docs/adr/0062-default-store-pool-size.md)). A three-sweep
+  connection-scale study found the pool is an **inverted-U**: it helps up to ~40 per engine, and
+  **over-provisioning is catastrophic** — past ~40 the extra connections thrash one shared SQL instance
+  (WRITELOG serialization + per-message finalizer applocks), and ACK latency explodes 30–90×. 40 is the
+  measured optimum — **do not set it higher to chase connection count.** **Server-DB backends only** (Postgres
+  / SQL Server) — the default **single-node SQLite** backend is unaffected (fixed read pool + single writer;
+  never reads `pool_size`). **Existing explicit `[store].pool_size` / `MEFOR_STORE_POOL_SIZE` values are
+  unchanged** — only the unset default moves. Behavioral deltas on server-DB engines: ~**8×** the steady-state
+  DB sessions per engine, and the startup pool pre-warm rises from ~2 to **~20 connections per engine**
+  (bounded by `warm_pool_timeout`, off the intake path, self-releasing, never raises). **Connection-budget
+  caution:** `pool_size` is **per engine**, so on a shared server DB `engines × pool_size` all count against
+  one `max_connections` (Postgres default ~100 → ~2 engines at 40) — raise `max_connections`, front the DB
+  with a pooler (PgBouncer), or use SQL Server; or size `pool_size` down. **Never split the store** to fit the
+  budget ([ADR 0063](docs/adr/0063-no-split-store-unified-store-for-sharding.md)). See
+  [`docs/DEPLOY-SERVER-DB.md`](docs/DEPLOY-SERVER-DB.md) §3.
+- **No split data store: multi-shard engine sharding now requires a server DB** ([ADR 0063](docs/adr/0063-no-split-store-unified-store-for-sharding.md),
+  amends [ADR 0037](docs/adr/0037-multi-process-sharding-l3.md)). `messagefoundry supervise` with **more than
+  one shard** on a **SQLite** store is now **refused at startup** — the old SQLite-file-per-shard behavior
+  split the message store into one database per shard, fragmenting search/reporting/audit/replay. A sharded
+  deployment must share **one unified store**, so `>1` shard requires `[store].backend = 'postgres'` or
+  `'sqlserver'` (every shard connects to the same database). **A single un-sharded engine on SQLite is
+  unaffected** (byte-identical to `serve`). Migrating an existing SQLite-sharded deployment: drain each shard
+  store to empty, then re-point `supervise` at one server DB (not an offline store merge).
+
+## [0.2.12] — 2026-07-01 — Early Access
+
+The **throughput & connection-scale wave.** The staged-queue per-message commit chain is shortened
+(opt-in inline fast-path + batch-claim, plus a result-preserving seq-only FIFO ordering that drops a
+per-handoff round-trip); a connection-scale measurement harness + read-only engine instrumentation lands;
+**per-lane wake events** (opt-in) eliminate the thundering-herd empty-claim storm that dominates at high
+connection counts; and ADR 0059's seq-only FIFO index re-key now reaches **upgraded** databases via a
+one-time on-open migration. All new *runtime* behavior is opt-in / off-by-default unless noted — the
+seq-only ordering (B3) and the index migration (B10) are result-preserving.
+
+### Added
+- **Inline Step-A fast-path** ([ADR 0057](docs/adr/0057-inline-step-a-fast-path.md)) — **opt-in per
+  inbound via `inline`**: for the pure all-deliver message (no filter/state/pass-through), fuse
+  route+transform+handoff into **one committed transaction**, cutting the per-message commit depth from 7
+  to 5 durable round-trips. Off by default → byte-identical to the split path; ineligible messages fall
+  back automatically.
+- **Batch-claim** (#671, [ADR 0058](docs/adr/0058-batch-claim-fifo-prefix.md)) — **opt-in via
+  `[store].fifo_claim_batch`** (>1): the INGRESS/ROUTED FIFO claim takes the contiguous due head-prefix in
+  one commit instead of one row per commit, processed in strict FIFO order. Default `1` = off
+  (byte-identical); preserves per-lane FIFO (#285) and at-least-once.
+- **Per-lane wake events** (#678, [ADR 0061](docs/adr/0061-per-lane-wake-events.md)) — **opt-in via
+  `[pipeline].per_lane_wake`**: a committed message wakes **only its own `(stage, lane)` worker** instead
+  of every worker of that stage, eliminating the thundering-herd empty-claim storm at high **connection**
+  counts (~1,500 inbounds). Default off + byte-identical; the FIFO claim and the lost-wakeup poll backstop
+  are unchanged (a missed wake self-heals). Env override `MEFOR_PIPELINE_PER_LANE_WAKE` for the harness A/B.
+- **Connection-scale measurement harness + read-only engine instrumentation** (#675) — a headless harness
+  that spins N inbound connections at a low per-connection rate and reads the connection-scale walls
+  (executor saturation, server-store pool wait, idle-poll storm, FD/socket count, config-reload + ACK
+  latency) vs connection count. The supporting engine instrumentation is **additive + read-only**, surfaced
+  via `/stats` + `/status`: empty-claim counters split into idle-poll vs per-commit wake-fanout, and (on a
+  server store) connection-pool acquire-wait percentiles + size/idle occupancy. Counters default to 0 /
+  `None` — byte-identical when unused.
+
+### Changed
+- **Seq-only per-lane FIFO ordering** (#673, [ADR 0059](docs/adr/0059-seq-only-fifo-ordering.md)) — the
+  per-lane FIFO claim now orders by the DB-assigned `seq` (rowid on SQLite) **alone** instead of
+  `(created_at, seq)`, and the per-insert `SELECT MAX(created_at)` clamp is removed from **every stage
+  handoff** (one fewer round-trip per produced row). **Result-preserving** (proven order-isomorphic to the
+  prior clamped ordering) and strictly more robust under clock skew / failover (`seq` has no wall-clock
+  dependence). `created_at` stays a real ingest-time/metrics timestamp — it is simply no longer an ordering
+  key. The FIFO covering indexes re-key to trail in `seq` (see the migration below).
+- **Rename-based FIFO covering-index migration** (#676, [ADR 0060](docs/adr/0060-rename-based-fifo-index-migration.md)) —
+  ADR 0059 re-keyed the per-lane FIFO indexes to trail in `seq` for the seq-only claim, but kept their names
+  under `IF NOT EXISTS` guards, so **only fresh databases** adopted the new index — an upgraded DB silently
+  kept its old `created_at`-trailing index and never got ADR 0059's throughput win. The seq-trailing indexes
+  are now named `ix_queue_fifo_in_seq` / `ix_queue_fifo_out_seq`, and a one-time, idempotent **on-open
+  migration drops the old-named index and builds the new one** on all three backends, so upgraded databases
+  adopt it. Correctness is unchanged (the claim orders by `seq`/`rowid` and names no index, so the migration
+  only restores speed). Operational notes: the first open after upgrade pays a **one-time index rebuild** on
+  the `queue` table (SQLite/Postgres blocking, SQL Server offline — bounded by live queue depth, at cold start
+  before serving); on a very large SQLite queue a *concurrent* second opener may hit a transient, non-corrupting
+  open failure during the rebuild; the shared-DB backends (SQL Server / Postgres) should upgrade **stop-the-world
+  / under a drain window** (a mixed-version fleet or a live rejoin can re-create or contend on the index); a
+  downgrade re-creates the old-named index (drop `ix_queue_fifo_in/out` manually if downgrading permanently).
+- **`/status` DB observability** — the SQLite journal mode and `synchronous` durability setting are now
+  surfaced in the DB status (`synchronous=NORMAL` remains the crash-safe-under-WAL default).
+
 ## [0.2.11] — 2026-06-29 — Early Access
 
 The **Plan-6 disaster-recovery + cloud/HA wave** — turnkey DR backup/restore-verify and a third-tier DR

{messagefoundry-0.2.11 → messagefoundry-0.2.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: messagefoundry
-Version: 0.2.11
+Version: 0.2.13
 Summary: Open-source healthcare integration engine — route, transform, and validate messages across many formats and connection types
 Project-URL: Homepage, https://messagefoundry.org/
 Project-URL: Documentation, https://messagefoundry.org/

{messagefoundry-0.2.11 → messagefoundry-0.2.13}/docker/compose.yaml

@@ -49,7 +49,7 @@ x-ha-engine-env: &ha-engine-env
   MEFOR_STORE_PORT: "5432"
   MEFOR_STORE_DATABASE: "messagefoundry"
   MEFOR_STORE_USERNAME: "mefor"
-  MEFOR_STORE_POOL_SIZE: "5"          # >= 2 required under [cluster]; >= 3 recommended
+  MEFOR_STORE_POOL_SIZE: "40"         # default (ADR 0062); >= 2 required under [cluster]
   MEFOR_CLUSTER_ENABLED: "true"
   # DEV-ONLY: the local Postgres has no CA-trusted cert, so verification can't succeed here. This
   # disables TLS verification across ALL transports — it is a CI/lab switch and must NEVER be set in

{messagefoundry-0.2.11 → messagefoundry-0.2.13}/docs/BACKLOG.md

@@ -114,6 +114,7 @@ protects the minimal-dep, on-prem, code-first identity.
 | **ASVS 4.1.5 per-message signing** | Med | **done** | — | #378 merged (`9c00b88`). Prune the stale `asvs-415-msg-signing` worktree. |
 | **#74 host CPU/mem metrics** | Med | **do-next** | S | Promoted from the #52 gap synthesis (2026-06-28) — the one zero-identity-tension additive win: host CPU/mem (psutil) on the metrics surface beside the #50 disk meter. Adds `psutil` (vet + re-lock). SQL-internals sub-scope demand-gated. |
 | **Publish the VS Code extension (Marketplace + Open VSX)** | Med | do-next | M | Publish the `ide/` extension to the **VS Code Marketplace** + **Open VSX** (`.vsix` via `vsce`/`ovsx`) so users install it instead of F5-from-source; add a CI publish leg + publisher accounts. **Owner: do soon, AFTER the planned IDE-focused improvements land** (not now — recorded 2026-06-26). Not a PyPI artifact (different ecosystem). |
+| **#95 engine-brokered AI assist** | Low | on-trigger | L | BYO already covers "use our existing AI subscription" (Copilot/Claude via `vscode.lm`, or an in-house model surfaced through VS Code) with **zero** engine work; this is the documented P1/P2 broker — engine-centralized, **per-use-audited** egress to a customer's managed subscription or self-hosted/in-house endpoint, wiring in the reserved `[ai]` `endpoint`/`provider`/`model` keys. ADR-first. **Trigger:** a customer wants engine-brokered AI to their own instance, or we have bandwidth. |
 
 **Top strategic calls** *(2026-06-19; updated 2026-06-28)*:
 1. ✅ **v0.2 locked and shipped** through `0.2.10` (#28/#29 evidence published; #22b shipped). The release-close move is done.
@@ -425,6 +426,14 @@ client. "Moderate risk"; not verifiable in offscreen Qt tests, so it deserves a
 **FIFO per outbound connection** (simple, safe). Per-key ordering is the leading-edge refinement to
 revisit once FIFO is solid and a real workload needs the parallelism.
 
+**Naming (locked 2026-06-30):** the canonical vocabulary for this concept is **sequence key** (the
+per-message partition value — ADT = `facility + MRN`; same key → same lane → FIFO preserved,
+different keys → parallel), **sequence group** (the set of messages sharing a sequence key), and
+**sequence-keyed lanes** / **sequence sharding** (the mechanism). The older terms used elsewhere in
+this item — `partition_key` (config setting) and "order-group sharding" — refer to the same thing.
+"Order-group" was retired because "order" collides with clinical orders (CPOE/ORM); "partition key"
+was retired because "partition" is reserved for the planned store-sharding-by-channel axis.
+
 **What:** preserve order only *within* a partition key (e.g. MRN / encounter / sending facility)
 while processing *across* keys in parallel — the sweet spot between strict per-connection FIFO (safe,
 serial) and unordered parallelism (fast, unsafe). Same idiom as a broker partition key. Recent
@@ -3062,11 +3071,11 @@ parity analysis.
 
 **Cluster:** Minor gaps. **Priority:** P3. **Verdict:** demand-gate.
 
-**Scope:** Per-connection send pacing, verify the reply's MSA-2 == the sent MSH-10, and keep-alive / persistent-reconnect on MLLP/TCP outbounds.
+**Scope:** Per-connection send pacing and verify the reply's MSA-2 == the sent MSH-10. *(Keep-alive / persistent-reconnect on MLLP/TCP outbounds was promoted out to its own tracked item — see [#97](#97-keep-alive--persistent-outbound-connections--per-connector-setting-p3-on-trigger).)*
 
-**Trigger:** build when a partner needs paced sending, strict response-correlation, or a persistent connection.
+**Trigger:** build when a partner needs paced sending or strict response-correlation.
 
-**Why:** All confirmed (no pacing/keepalive; `MLLPDestination._check_ack` reads MSA-1/MSA-3 only, never matches MSA-2↔MSH-10; `mllp.py` notes persistent/pooled "can come later"). Cheap per-connection-override additions; bundle on real partner need.
+**Why:** Both confirmed (no pacing; `MLLPDestination._check_ack` reads MSA-1/MSA-3 only, never matches MSA-2↔MSH-10). Cheap per-connection-override additions; bundle on real partner need. Keep-alive is tracked separately at #97.
 
 **Source:** promoted from [#52](#52-corepoint-capability-parity-gaps--prioritized-roadmap-input-2026-06-27) gap synthesis (adversarially reviewed, 2026-06-28).
 
@@ -3324,6 +3333,315 @@ deep-dive + console-medium evaluation (2026-06-29).
 
 ---
 
+## 93. Engine + database performance monitoring — engine-wide volume/connection KPI roll-up + a throughput-overload (saturation) alert (P2)
+
+**Type:** feature — observability + alerting. A **connective** item: most of the operator-facing monitoring
+surface this asks for is **already tracked** (and partly shipped) under sibling items — this entry exists to name
+the two genuine **net-new** slivers none of them owns and to cross-link the rest, not to re-pitch built work.
+
+**Already tracked / shipped (don't duplicate).** The request — "display total message volume + connection count;
+monitor everything that affects throughput; alert when the system is becoming overloaded" — is largely covered:
+- **#21 (DONE, PR #407)** — the Prometheus `/metrics` exporter (+ optional OpenTelemetry): per-connection
+  received / delivered / errored / `queue_depth` counters + a `delivery_latency_seconds` histogram (p50/p95/p99).
+  A scraping team gets per-connection throughput/latency and can `rate()`/`sum()` it in Grafana today.
+- **#56 (SHIPPED 0.2.10, ADR 0044)** — resolvable alert-state: the `alert_instance` table, `GET /alerts/active` +
+  ack/resolve, and the real `ConnectionRow.alerts_active` count (no longer the stubbed `0`).
+- **#74 (do-next)** — host CPU / memory via `psutil` on the metrics surface.
+- **#75 (scheduled)** — the zero-install **browser ops dashboard**: live per-connection **In/Out msgs/sec** over
+  `/ws/stats`, Queued / Errors / Last-Activity. The natural home for a live throughput view.
+- **#76 (demand-gate)** — historical-metrics charting + a status-colored data-flow graph.
+- **#81 (demand-gate)** — alert escalation tiers + day/time thresholds + content (Action-Point) alerting on top of #56.
+- **#64 (measure-gated)** — the throughput-*performance* roadmap (group-commit, DB durable-write IOPS as the
+  leading driver). That item makes the engine *faster*; this item *warns* when load approaches capacity — they pair.
+- **#50 (P3)** — app-log disk metering + a message-stall rule. **#28/#29** — the load/throughput runs that set the baseline.
+
+**Net-new gap (what no sibling owns):**
+1. **An engine-wide aggregate KPI headline.** Every count above is **per-connection** (#21) or a live per-connection
+   rate (#75); nothing rolls them up into the operator's literal ask — a single **total messages through the engine**
+   figure, a **combined inbound + outbound connection count** (with running / stopped breakdown), and an **engine-wide
+   msg/s rate** — surfaced as first-class top-line KPIs on `/status` (or a sibling route), the console Engine Status
+   page, and the #75 dashboard. Reuse the existing `recent_done` rate window that already powers `backlog_seconds`
+   — don't add a second sampler. Small; mostly rides #75.
+2. **A throughput-overload / saturation alert.** Every shipped alert (the **#5** framework, **#56** state, **#81**
+   escalation) keys on an **absolute** per-connection/per-resource snapshot — depth/oldest-age ceilings — so a bursty-
+   but-draining lane and a genuinely-overloaded engine look identical until the ceiling trips. Nothing fires on the
+   *derivative*: a **rising** `backlog_seconds`, a **growing** `in_pipeline`, or **ingest rate exceeding drain rate**
+   over a sampling window = "the system is *becoming* overloaded." Add a new ADR 0014 alert event keyed on that
+   comparison (new `AlertSink` event + emit site + `AlertRule` dimension + a small per-lane / engine-wide rate
+   history), bounded by the existing `realert_seconds` throttle and routed through the same notifier/rules path. It is
+   distinct from #81 (a policy layer *on top of* existing alerts, not a new detector) and from #64 (performance tuning,
+   not operational alerting). ADR 0014 already declined timed multi-stage escalation; this adds a rate/saturation
+   **dimension**, which wants that scope decision settled first.
+
+**Database performance monitoring.** Surface the throughput-affecting **DB** signals — write/commit latency and
+connection-pool busy/wait/saturation (the pipeline is commit-bound; `[store].pool_size` exists but emits no
+saturation metric) and router/transform-worker lag — as **metrics first** (extend `/metrics` + `db_status()`), then
+optionally as overload-alert inputs. `storage_threshold` today alerts only on DB **file size** vs
+`[retention].max_db_mb`, not commit/pool health. **SQL-internal** DB metrics stay **DBA-delegated / demand-gated**
+(parity with #74's SQL-internal sub-scope and the DB-tier-HA decline).
+
+**Why P2 / on-trigger.** #21 + the scheduled #74/#75 already answer the "where's the dashboard?" ask cheaply; the
+net-new is the small aggregate KPI roll-up (rides #75) + the overload/saturation alert, which is genuine new engine
+work and matters most once a real high-volume estate exists to overload. **Trigger:** a pilot/production estate
+approaching the commit-bound capacity ceiling that needs an *early-warning* overload signal rather than after-the-fact
+`queue_buildup`; calibrating the threshold wants a #28/#29/#64 capacity baseline first. Relates to **#21**, **#56**,
+**#64**, **#74**, **#75**, **#76**, **#81**, **#50**, **#28**/**#29**, and the **#5** AlertSink/rules framework it extends.
+
+**Source:** owner request (2026-06-30) — "engine + database performance monitoring and alerting; display the total
+volume of messages going through the engine and the number of connections; monitor for all the things that affect
+throughput and alert when the system(s) are becoming overloaded." Overlap against the existing observability/alerting
+items (#21/#56/#64/#74/#75/#76/#81) reconciled the same day.
+
+---
+
+## 94. External BLOB-server offload for embedded documents — replace inline base64 with a stored-object pointer (OBX-5 RP) (P2, on-trigger)
+
+**Type:** feature — storage minimization + customer-infrastructure integration. The ingest-time **offload**
+half of **#47** (its deferred fork (b)), but targeting the **customer's existing object/BLOB store** instead
+of a MessageFoundry-internal attachment table — and replacing the inline blob with an **in-message pointer**,
+not a private reattach token.
+
+**The ask.** Large base64 embedded documents (PDF reports, CCD/C-CDA, scanned images) ride inline in **OBX-5**
+(ED data type) and generically via the ADR 0028 `mfb64:v1:` carriage marker
+([`adr/0028-base64-binary-carriage-codec.md`](adr/0028-base64-binary-carriage-codec.md)). Today they are stored
+verbatim in the raw message at **every** persisted stage (`ingress` → `routed` → `outbound`), bloating the store
+far out of proportion to message count (#47's premise). Instead of pruning them *after* a window (#47(a)) or
+carrying them more compactly *inside* our store (#62), **offload the blob to the customer's BLOB server at
+ingest, take back the storage key/URL it returns, and embed that pointer into the corresponding OBX segment** —
+so the bulky document never persists in our store at all.
+
+**Why distinct from the siblings.**
+- **#47(a)** prunes the embedded doc *after* a per-connection window — the blob still bloats all three stages
+  until the window elapses, and it stays in our store meanwhile. This eliminates it *from the start*.
+- **#47(b)** is the same ingest-time-offload shape but offloads to a **MessageFoundry-managed attachment store**
+  (Mirth's `d_ma<channelId>` table + `${ATTACH:...}` token, reattached on outbound). This offloads to
+  **infrastructure the customer already owns** and leaves a **standards-shaped pointer in the message**, not a
+  private token.
+- **#62** keeps the bytes in our store, just as `VARBINARY`/`BLOB`/`bytea` instead of base64-in-text. Here the
+  bytes **leave** our store entirely.
+
+**Design forks (for the ADR):**
+- **Pointer representation.** Replace the OBX-5 **ED** embed with the HL7 **RP (reference pointer)** data type — a
+  `<pointer>^<application ID>^<type of data>^<subtype>` reference downstream systems understand natively — versus
+  an opaque MessageFoundry token (#47(b)-style) that we must reattach before delivery. RP is interoperable but
+  assumes the partner can dereference the BLOB; a token keeps the message self-contained but makes us re-fetch +
+  re-embed on outbound. For the generic `mfb64:v1:` carriage, a sibling `mfref:`-style pointer marker. **Never
+  string-slice raw HL7** (CLAUDE.md §8) — rewrite via the parsed model/codec and re-encode.
+- **Credential-bearing pointers — embed a reference, not a capability.** The message must carry a pointer a
+  consumer can resolve, but a BLOB store often hands back (or we would mint) a **presigned URL / SAS token with the
+  access grant baked into the string**. That must **not** be what we persist: a presigned URL in OBX-5 is a bearer
+  credential to PHI living in a persisted-and-forwarded artifact (store, outbox, the partner's inbox, our logs), it
+  **expires** — colliding with at-least-once **replay**, queued **retries**, **dead-letter**, and **retention** (a
+  message re-sent past the TTL carries a dead pointer) — and it can't be revoked independently of the document.
+  Separate the two capabilities: the **upload** grant (the presigned PUT, or MessageFoundry's own write creds) is
+  used **once and discarded**; what we **embed** is a **stable, opaque, non-capability reference** — ideally a
+  content-addressed object key plus the store identity (the HL7 **RP** components map cleanly: *Application ID* =
+  which BLOB store, *Pointer* = the opaque key), with the consumer authenticating to the store with its **own**
+  credentials (it owns the store — the premise of this feature). If a partner genuinely needs a no-auth
+  dereferenceable URL, **mint a short-lived presigned URL late, at delivery** (the reattach-on-outbound fork below),
+  never at ingest and never persisted — so the capability exists only transiently on the wire within a bounded TTL.
+  Clean default: MessageFoundry writes with its own creds, embeds the opaque key, readers use theirs, and no
+  credential URL ever touches the store or the logs.
+- **Reattach-on-outbound or not.** If the receiving partner reads the BLOB itself, the pointer *is* the
+  deliverable. If it needs the actual document, MessageFoundry must **re-fetch from the BLOB and re-embed** on the
+  outbound — or **mint a fresh short-lived pointer** at send time (above) — a new read side-effect + egress
+  dependency on delivery. Per-outbound choice.
+- **Where the offload runs vs the reliability invariant.** This is a **write side-effect**, which collides with
+  the "routers/transforms must be pure, every stage is at-least-once / re-runnable" invariant (CLAUDE.md §2). A
+  stage re-run must not double-store or orphan blobs — favor **content-addressed keys** (hash of the bytes) so a
+  PUT is idempotent. And it adds an **external dependency** to the path: if the offload sits *before* the ACK
+  (alongside ingress persistence), a BLOB-server outage blocks intake/ACK; if it sits as its own pipeline stage
+  *after* the ACK, intake survives but a failed offload dead-letters post-ACK (no NAK) — the ADR must pick.
+
+**Scope (when built):**
+- A **pluggable BLOB connector** registered like the destination transports (`transports/`, registry — never
+  special-cased in `pipeline/`): S3 / Azure Blob / GCS / on-prem object store / plain HTTP PUT, selected +
+  configured per connection. Gated by `[egress].allowed_*` allow-lists; credentials via `env()` / `MEFOR_*` (the
+  connector-credential SecretProvider-seam candidate). Off the event loop.
+- A **per-connection offload setting** (size threshold + target BLOB connection), layered over a global default —
+  the same **global-default + per-connection-override** model as FIFO / `RetryPolicy` / #34 / #47, authored on the
+  inbound `ConnectionSpec` and/or `connections.toml` (ADR 0007) so it stays hand-/GUI-editable.
+- Target **both** carriage forms (HL7 OBX-5 ED and the generic `mfb64:v1:` marker) across **all three** backends
+  (SQLite / Postgres / SQL Server). Preserve every invariant — never delete the row, message stays parseable after
+  the rewrite, **one audit entry per offload** (key + size + content-type + connection, no content). Offload is
+  irreversible from our side once the inline bytes are dropped — surface a distinct flag so an operator viewing the
+  message knows the document was externalized vs never present, and audit any later **retrieval**.
+
+**PHI note + scope boundary.** Offloading *shrinks our* at-rest PHI footprint (a data-minimization win) — the
+bulky document leaves our store for the customer's BLOB. **The security of that BLOB server is explicitly out of
+scope:** PHI handling, **encryption-at-rest**, and access control on the customer's store are the **customer's**
+responsibility — the same trust posture we already take toward a customer database in `db_lookup`
+([ADR 0010](adr/0010-handler-callable-db-lookup.md)). MessageFoundry treats the BLOB server as trusted customer-owned
+infrastructure and does **not** encrypt the offloaded objects or enforce remote-store PHI controls itself. What
+stays **in** scope (our responsibility): **never log a presigned/SAS URL or an identifier-bearing object key**
+(§9) — the former is a bearer credential to PHI, the latter is PHI itself; an opaque, auth-gated reference is safe
+to log. And **audit each retrieval** as a PHI access. (Logging is still stdlib with no structlog redaction yet, so
+this is a deliberate connector-level "log the object key/length, never the signed URL" discipline, not an
+automatic scrub.) The customer's BAA must cover the BLOB store; restate this boundary in [`PHI.md`](PHI.md) when
+built.
+
+**Why P2 / on-trigger.** This is the strongest store-bloat lever for heavy document feeds (radiology PDFs, CCDs)
+and the cleanest fit for a customer who **already runs** object/BLOB infrastructure and wants their documents
+living there. But it is a side-effecting pipeline change touching the purity / at-least-once invariant **plus** a
+new connector family — it wants its own ADR (the forks above) before code, and is not an open exposure on the
+shipping config. **Trigger:** an adopter with an existing BLOB/object store and a document-heavy feed who wants the
+documents offloaded out of our store. Relates to **#47** (the in-store prune/offload sibling — shared
+per-connection plumbing; this realizes its deferred fork (b) against external storage), **#62** (in-store binary
+carriage), **#34** (per-connection retention), **ADR 0028** (base64 carriage), **ADR 0007** (`connections.toml`),
+and the connector-credential **SecretProvider** seam.
+
+**Source:** owner request (2026-06-30) — "integrate with the customer's existing BLOB servers to offload base64
+documents; eliminate the base64 documents from our data store — instead get a pointer back from the BLOB and embed
+that into the corresponding OBX segment." Reconciled against the in-store siblings #47 / #62 the same day.
+
+---
+
+## 95. Engine-brokered AI assistance — integrate the IDE coding assistant with a customer's managed AI subscription or in-house LLM instance (P3, on-trigger)
+
+**Type:** feature — AI governance + customer-infrastructure integration. Turns the **reserved-but-unused**
+`[ai]` broker config keys into a real integration: let the **engine broker** the IDE assistant's model calls to a
+provider the *customer already runs* — their own cloud AI subscription (Azure OpenAI, Anthropic/Bedrock, an internal
+Copilot-compatible gateway) or a **self-hosted / on-prem LLM endpoint** (vLLM, Ollama, an internal inference service)
+— under central, **per-use-auditable** egress control. The policy model, config schema, RBAC, and policy endpoint
+**already exist** ([`AI.md`](AI.md)); this builds the broker they were designed for.
+
+**Already there (don't duplicate).** A customer's existing AI **subscription** is *already* the integration point
+today, via **BYO** ([`../ide/src/chat.ts`](../ide/src/chat.ts)): the assistant is provider-agnostic and uses whatever
+model the developer picked in VS Code's Chat view (Copilot / Copilot Enterprise under the org BAA, Claude, etc.)
+through the `vscode.lm` Language Model API — and **any in-house instance that registers as a VS Code language-model
+provider** (a Copilot-compatible internal proxy or a custom chat-model extension) is picked up the same way,
+engine-blind. The governance around it is built too — the `[ai]` policy (`mode` × `data_scope`,
+production-posture-clamped), the `ai:assist` RBAC permission, `GET /ai/policy` + the `messagefoundry ai-policy` CLI,
+and the central-*off* switch honored on every workstation. What is **not** built is the **engine-brokered** path:
+`managed_claude` / `managed_claude_baa` are accepted as policy values but the IDE deliberately refuses to service them
+(it will **not** silently fall back to BYO), and the `provider` / `model` / `baa_attested` / `endpoint` config keys
+are **accepted but unused** — placeholders the broker was meant to consume.
+
+**Net-new gap (what no sibling owns):**
+1. **The engine-side broker.** AI.md's *Future direction* (P1/P2) puts model egress behind the **engine** — not the
+   dev's IDE — so a central operator controls and **per-use audits** every call, and `phi` scope becomes reachable
+   only under `managed_claude_baa` over a **BAA + zero-data-retention** connection. None of this exists: it needs a
+   new engine API surface (the engine proxies the chat request), the IDE client switching from `vscode.lm` to the
+   engine for managed modes, and per-use egress auditing (today even policy *reads* aren't audited — that arrives
+   *with* the broker).
+2. **A generic customer-endpoint mode, beyond Anthropic-managed Claude.** The only future modes named today
+   (`managed_claude` / `managed_claude_baa`) are framed around an **Anthropic-managed** Claude. A customer's **own
+   subscription** (their Azure OpenAI / Bedrock keys, their internal gateway) or a **self-hosted endpoint** is a
+   *different* shape: the customer supplies `endpoint` + `provider` + `model` + credentials and MEFOR just brokers to
+   it. That wants either a new `managed_endpoint` (engine-brokered, customer-keyed) mode or an explicit
+   generalization of `managed_claude`, finally wiring in the reserved `endpoint` / `provider` / `model` keys.
+
+**Design forks (for the ADR):**
+- **Why broker at all when BYO already works?** BYO's limit is that it is **dev-machine-local and engine-blind** —
+  ops can centrally turn it *off* and cap scope, but cannot *see* or *audit* individual calls, and the model is
+  whatever the dev configured in VS Code. The broker buys central egress control, per-use audit, and a single
+  operator-pinned `endpoint` / `model` — at the cost of routing AI traffic through the engine. Some customers want
+  exactly the opposite (keep AI entirely off the engine), so this is **additive, never a replacement** for BYO.
+- **`managed_endpoint` vs generalize `managed_claude`.** A new mode keeps the existing Claude modes clean;
+  generalizing avoids mode-proliferation. Either way the IDE's current "managed → disabled" branch flips to
+  "managed → call the engine broker."
+- **Credentials + egress.** Customer keys / endpoint via `env()` / `MEFOR_*` (the connector-credential
+  **SecretProvider** seam), gated by an `[egress].allowed_http` allow-list like `fhir_lookup` / SMART; the broker
+  call runs **off the event loop**. A self-hosted endpoint (vLLM / Ollama) often needs no BAA (on-prem) — but the
+  **`data_scope` ceiling still applies**: `phi` stays reachable *only* under the BAA + ZDR attestation, never merely
+  because the endpoint is on-prem.
+- **PHI boundary unchanged for the MVP scopes.** Until de-id wiring into the AI scope path and the broker land
+  together, the assistant still attaches **`code_only`** context regardless of mode — the broker changes *who makes
+  the call and how it's audited*, not *what data* may be sent without a posture change.
+
+**Why P3 / on-trigger.** BYO already covers "use our existing AI subscription" for the common case
+(Copilot-under-BAA, or an in-house model surfaced through VS Code) with **zero** engine work — so this is genuine new
+engine + IDE + audit surface that earns its cost only when a customer specifically wants **engine-centralized,
+audited** AI egress to **their** managed / self-hosted endpoint (e.g. a security team that mandates all AI traffic
+flow through one audited choke point, or an estate whose only LLM is an internal one not exposed to VS Code).
+**Trigger:** a customer asks for engine-brokered AI to their own subscription / in-house instance, **or** we have the
+bandwidth to build out the documented P1/P2 broker. ADR-first (the forks above). Relates to [`AI.md`](AI.md) (the
+policy model + reserved keys this realizes), [`PHI.md`](PHI.md) §9 (de-id, the gate to scopes above `code_only`), the
+**SMART** / `fhir_lookup` egress-allow-list + off-loop precedent ([ADR 0024](adr/0024-smart-backend-services-token-provider.md) /
+[ADR 0043](adr/0043-fhir-read-lookup.md)), and the connector-credential **SecretProvider** seam.
+
+**Source:** owner request (2026-06-30) — add the engine-brokered "integrate the IDE coding assistant with a
+customer's existing AI subscriptions or in-house instances" capability as a demand-/bandwidth-gated item; build when
+a customer wants it or when we have bandwidth. The already-shipped BYO coverage + the reserved broker config keys were
+reconciled the same day.
+
+---
+
+## 96. Built-in "setup tester" — self-service capacity estimator that benchmarks the deployed setup and reports how much traffic it can handle (P2, adopter-facing)
+
+**Type:** feature — an operator/adopter-facing **capacity self-test** shipped *with the engine*. It runs the
+same style of measurement we do for throughput testing, but as a first-class, on-demand command an adopter
+points at **their own** setup (this box, this store backend, this config) to get back an **estimate of how
+much traffic that setup can sustain**.
+
+**What:** a `messagefoundry` subcommand (e.g. `messagefoundry capacity` / `setup-test`) that drives a
+controlled synthetic load through the real engine and reports an **estimated sustainable throughput** — a
+headline **msg/s** and **msg/day** figure, ideally **per-inbound-interface** *and* engine-wide, plus the
+**limiting factor** (commit-bound / pool-saturated / CPU / disk) and a confidence caveat. It ramps to the
+saturation knee (where `in_pipeline`/`backlog_seconds` start rising faster than drain — the #93 signal) and
+reports the last rate that drained cleanly with no loss, rather than a raw peak. Reuses the **BUILT load
+harness** measurement machinery ([`harness/load/`](../harness/load/), [`docs/LOAD-TESTING.md`](LOAD-TESTING.md))
+— the rate governor, the fast correlation sink (true end-to-end latency), the drain gauge (`in_pipeline`), and
+the no-loss reconciliation — packaged as a supported engine capability rather than a dev-only tool.
+
+**Distinct from what already exists (don't duplicate):**
+- **#28 / #29 (DONE)** are the *developer/benchmark* runs of the harness against a synthetic high-fan-out
+  system-under-test, producing the **project** [`benchmarks/TUNING-BASELINE.md`](benchmarks/TUNING-BASELINE.md)
+  baseline. This item is the *adopter-run* inverse: point it at **the real deployed config on the real box** and
+  get a sizing number for *that* deployment — not a project baseline, and not something that needs the harness's
+  synthetic SUT config or the denylist-guarded estate profiles.
+- **#93 (P2)** is the *passive, runtime* counterpart — it watches real traffic and **warns** when live load is
+  approaching capacity. This item is the *active, pre-cutover* counterpart — it **measures** where that capacity
+  is in the first place, so #93's overload threshold can be calibrated against it. They pair.
+- **#40** is the enterprise-hardware CI leg; this tester is what an adopter would run **on their own hardware**
+  to reproduce a sizing number without CI access.
+
+**Design constraints (for the eventual ADR):**
+- **Must not pollute production.** A capacity run generates real store writes and would otherwise inflate the
+  true inbound counts (the count-and-log invariant persists *every* received message). It must run against an
+  **isolated/ephemeral store** (temp DB) or a clearly-marked test namespace, and never leave synthetic rows in,
+  or skew the metrics of, the live message store.
+- **Synthetic payloads only — never real PHI.** Drive it from the conformant generators
+  ([`generators/`](../messagefoundry/generators/)) / the anon framework (ADR 0030), consistent with the
+  dryrun/generate PHI rule (never against real PHI, never redirected to a committed file/CI log).
+- **Respect the per-interface bound.** Report capacity **per inbound interface** and note that a single strictly-
+  ordered feed is core-bound (owner principle: fan out feeds at source, not infinite single-feed speed) — an
+  engine-wide total is the sum across interfaces, not a single-feed number. Sequence-keyed lanes (#3) are the
+  sanctioned single-feed escape hatch when one feed outgrows a core.
+- **Name the limiting factor**, reusing the #93/#64 signals (commit/write latency, `[store].pool_size`
+  busy/wait, CPU/mem via #74, `in_pipeline` growth) so the output is *"~N msg/s, commit-bound"* rather than a
+  bare number — the sizing memos already conclude the pipeline is serial-per-inbound commit-bound, not
+  disk/CPU/pool-bound on the tested boxes.
+
+**Why P2 / on-trigger.** Turns capacity sizing — today a manual "run the dev harness + read TUNING-BASELINE by
+hand" exercise — into a **supported operation** an adopter can self-serve before a cutover (*"will this box carry
+our ~1.6M ADT/day?"*). The measurement machinery already exists; the net-new is the operator-facing command, the
+isolated-store harness, the ramp-to-knee estimator, and the capacity report. **Trigger:** a pilot/adopter needing
+a self-service pre-cutover capacity check on their own hardware (the ADR 0017 consumer-deployment pattern), or the
+#93 overload-alert threshold needing a per-deployment capacity baseline to calibrate against. Relates to
+**#28**/**#29** (the harness it wraps), **#40** (enterprise-box runs), **#64** (the throughput-performance
+roadmap), **#93** (the runtime overload-alert counterpart), and the recorded sizing work (throughput matrix /
+per-interface bound / commit-bottleneck analyses).
+
+**Source:** owner request (2026-06-30) — "add a setup tester to the engine … do tests like we're doing for
+throughput testing and report back an estimate of how much traffic the setup can handle."
+
+---
+
+## 97. Keep-alive / persistent outbound connections — per-connector setting (P3, on-trigger)
+
+> **On-trigger / demand-gate.** Numbered for tracking only — build when the trigger below fires (“demand-gate, don’t schedule”). Promotes the keep-alive sub-scope of [#82](#82-sender-transport-polish-bundle--pacing--msa-2msh-10-matching--tcp-keep-alive) into its own tracked item at the owner's request.
+
+**Type:** feature — a per-outbound-connection option to **hold the TCP link open across deliveries** (keep-alive / persistent) instead of the current connect-per-message behavior.
+
+**What:** an opt-in **per-connector setting** (e.g. `keepalive = true` / a `connection_mode = "persistent" | "on_demand"` knob in the outbound's `settings`, default `on_demand` so existing configs stay byte-identical) on the MLLP / raw-TCP / X12 outbound connectors. When enabled, the delivery worker reuses one open connection (reconnecting on drop/idle), rather than opening + closing a fresh socket every message as it does today. Wants: a bounded idle-close / max-lifetime, reconnect-with-backoff on a dropped link, and clean teardown on `stop()`/reload — all per-connection, with the setting validated at build (dry-run / `check`), consistent with the other outbound knobs.
+
+**Why:** confirmed gap — every TCP-family outbound opens a **fresh connection per delivery** today and there is no toggle: `MLLPDestination` ([`transports/mllp.py`](../messagefoundry/transports/mllp.py), *"Phase 1 opens a fresh connection per delivery … a persistent/pooled connection can come later"*) and `TcpDestination` ([`transports/tcp.py`](../messagefoundry/transports/tcp.py), *"Opens a fresh connection per delivery … pooling can come later"*); listed as an unbuilt MLLP feature gap in [`CONNECTIONS.md`](CONNECTIONS.md) ("keep-connection-open/pooling"). Inbound listeners are already persistent (peer-driven, idle-bounded by `receive_timeout`) — this closes the outbound half. The connect-per-message default is simple and robust to flaky peers, so this is genuinely additive and stays **off by default**; the at-least-once / idempotent-receiver contract is unchanged (a reused link that drops mid-ACK still retries, same as today). **Trigger:** a partner that needs a held-open link (a persistent-session receiver, or a high-rate feed where per-message connect setup is measurable overhead). Relates to **#82** (the sender-polish bundle this splits from — pacing + MSA-2↔MSH-10 matching stay there), **#46** (connection lifecycle events would gain reconnect/retry signals), and **#65** (outbound-connector option surface).
+
+**Source:** owner request (2026-06-30) — "add keepalive feature for outbound connections, controlled by a setting per outbound connector."
+
+---
+
 *Everything else from the 2026-06-10 full-codebase review (1 critical, 13 high, 33 medium, 31 low —
 78 findings) has been remediated; see the review report's §6 action order. The two items it still
 sourced — **#1 (SQL Server concurrency)** and **#2 (console off-thread)** — are now both **DONE**