fix(x12): record the seven ADR 0021 connection events its raw-TCP twin already records (BACKLOG #1665)

[wshallwshall]

What this is

X12Source carried no _emit_event call at all. An allow-list refusal, a capacity refusal, an over-cap interchange and a peer reset recorded nothing, where TcpSource -- the listener X12 is otherwise a near-copy of -- recorded a row for each.

On first deployment that would leave an X12 feed's connects and refusals absent from the one stream an operator reads to answer "did the sender connect, and why did it drop". Zero deployments, so no live stream is missing anything today. Severity is low and conditional, per the item.

Same shape as BACKLOG #1617, with a smaller reply surface.

The drain half of the item was ALREADY MERGED. Nothing here rebuilds it.

Item #1665 has two halves. The first -- bounding the inbound reply-write drain -- shipped in PR 1122, commit 87c83574c, merged 2026-09-14, under sibling row #1766, which is why a title grep for 1665 finds nothing.

Verified in the tree before writing anything, not taken on trust: _REPLY_DRAIN_GRACE and a _drain_reply wrapping writer.drain() in asyncio.wait_for are present in both messagefoundry/transports/x12.py and messagefoundry/transports/tcp.py. This PR touches that code only to correct a docstring it left behind, and to add the peer_reset assertion the docstring said was impossible.

SEVEN kinds, not the four the item names

Measured by walking the emit sites, not counted by eye. TcpSource emits seven, at seven call sites:

Kind	Where	Item named it
peer_not_allowlisted	allow-list gate	yes
at_capacity	max_connections gate	yes
established	slot taken	no
frame_oversize	the over-cap frame arm	yes
framing_error	the last-resort Exception arm	no
peer_reset	the outer OSError arm	yes
closed	the finally, when established and not failed	no

Nothing was dropped. The two listeners share an accept path, both gates, the per-chunk decode loop, the outer OSError arm and the finally, so every TCP kind has an exact X12 analogue. After the change both modules report 7 call sites and 7 distinct kinds, with identical sets.

Emitting only the four the item names would have left X12 asymmetric on the three paths an operator most wants -- did it connect at all, did it close cleanly, and was the close an idle drop or a hangup -- and would have left the docs/PHI.md row 7 sentence half-true rather than false, which is harder to notice.

No new kind name. frame_oversize is reused for the X12FrameError arm even though this listener's frame is an interchange. A second name for one condition would red the documented-vocabulary guard, the console filter tuple and the docs/PHI.md row together, and would split an operator's query across two spellings. The console tuple and docs/PHI.md row 7 therefore need no change: the vocabulary is unchanged, only its coverage.

The positive control

Built and confirmed before any code changed, because a search that finds nothing is indistinguishable from a clean repository.

test_allowlist_refusal_is_recorded_by_both_listeners drives the same refusal on TcpSource and X12Source, through the same capture sink, in the same test. Before the change it failed with:

the X12 listener refuses an out-of-allowlist peer identically to TcpSource but records a
different event set: [] vs ['peer_not_allowlisted']

The TCP arm was non-zero, so the zero on the X12 side was attributable to the listener rather than to a sink that is never called. All eight tests in the new file failed before; all eight pass after.

test_x12_emits_the_same_event_vocabulary_as_its_tcp_twin derives both kind sets by AST and asserts equality, so neither listener can grow a kind the other lacks without a red.

Doc repairs: SIX engine sites, not four

The item's own cited doc was one of them. All six read as correct English, and every guard stayed green with them in place -- confirmed by running the doc-drift suites before touching any prose. That is the whole reason they are corrected here rather than filed.

1. docs/PHI.md row 7 -- the connection_event stream's coverage statement.
2. docs/CONNECTIONS.md -- the accept-rate bullet in Resource management (also drops two transports/x12.py:NNN citations that had already drifted).
3. docs/CONNECTIONS.md Table B -- the X12 listener row.
4. docs/CONNECTIONS.md -- the timeout-and-failure table's X12 row. Missed on the first pass and found by re-sweeping, which is the argument for sweeping with a known population rather than stopping at the sites the item names. It asserted three false things at once.
5. docs/SECURITY.md -- the pre-auth DENY table's X12 row.
6. docs/SECURITY.md -- the "Telemetry honesty" note.

Three test-prose sites go with them, since a stale docstring misleads the next reader exactly as a stale doc does: the test_reply_write_drain_is_bounded docstring in tests/test_x12_transport.py, test_every_socket_listener_that_emits_nothing_is_named_in_row_7, and the CONNECTOR_ROW_TOKENS comment.

The DICOM half of every one of these sentences is left alone. transports/dicom.py still contains zero _emit_event calls, so each sentence names DICOM correctly and editing that half would turn a true statement false. The asymmetry the sentences exist to disclose is real; it is just smaller.

One pinned guard moved rather than being deleted

REQUIRED_TRUTHS in tests/test_communications_inventory.py pinned the literal sentence "No ADR 0021 connection_event is emitted" as present in the resource-management section -- a prior correction, pinned so it could not silently regress. This change makes that sentence false. The pin moved to the half that survives, "contains zero \_emit_event` call sites"`, which still names DICOM as the silent listener. Deleting it would have retired a live guard on the strength of a change that only narrowed what it guards.

FOR THE LANDER: a seventh site is in the vault and I cannot reach it

docs/security/ is gitignored in this repository (git ls-files docs/security returns 0, and the directory does not exist in this checkout), and the vault is held by another session on vault/close-six-shipped-rows. Naming it is the whole of what I can do.

• File: docs/security/THREAT-MODEL.md
• Table: Table B, the row labelled Raw TCP / X12 listener (its label is transcribed in tests/test_threat_model_doc_drift.py, in the row-token map and in the "covered by" map).
• What needs changing: any clause in that row, or the prose beside it, asserting that the X12 listener emits no ADR 0021 connection_event -- or that an X12 allow-list or capacity refusal is log-only or silent. Those are now false in the same way sites 1 to 6 were. Replace with the raw-TCP behaviour: the two listeners now emit the same seven kinds.
• Leave the DICOM half alone, for the reason above.
• tests/test_threat_model_doc_drift.py is structural and numeric, not prose-matching, and it is inert in a public checkout, so a prose edit there should not red it. Worth re-running in the vault after the edit.

I did not attempt this edit and made no change under docs/security/.

Checks

Run, from this worktree's venv:

• ruff check . -- pass
• ruff format --check . -- pass
• mypy messagefoundry (strict) -- pass, 275 source files
• pytest tests/test_x12_connection_events.py -- 8 passed (all 8 failed before the code change)
• pytest tests/test_x12_transport.py tests/test_tcp_transport.py -- pass
• pytest tests/test_phi_logging_inventory.py -- pass. Carries test_connection_event_vocabulary_is_derived_from_the_emit_sites, which is exactly what this change touches, plus the console filter-tuple cross-check.
• pytest tests/test_communications_inventory.py tests/test_security_doc_drift.py tests/test_connection_event_emit.py -- pass
• 20 further doc-drift guard suites (CONNECTIONS / SECURITY / PHI readers) -- 750 passed, 1 skipped

Skipped, and why: the full local suite. It has been measured not to finish under fleet contention, so targeted coverage plus named CI legs was the trade. Legs a reviewer must read on the hosted runner: the SQL Server and Postgres store legs, windows-service-smoke, and the web console leg -- none of which this change should touch, but none of which a Builder can see.

/simplify was run as a single review agent over all four angles (reuse, simplification, efficiency, altitude) rather than four passes, given the weekly pool.

Possible conflict with open PR 1214

PR 1214 (BACKLOG #1735) is rewriting tests/test_x12_transport.py's expect_reply round-trip tests. The seven new tests here live in their own file, tests/test_x12_connection_events.py, to stay out of its way. What does touch tests/test_x12_transport.py is a 14-line hunk in test_reply_write_drain_is_bounded -- a different function -- correcting its now-false docstring and adding the peer_reset assertion. That should merge cleanly, but it is the one place these two PRs meet.

Ledger

docs/BACKLOG.md is a policy stub here and is not edited by this PR. BACKLOG #1665 -- the X12 connection-event half is built; the drain half shipped earlier under #1766 in PR 1122 (87c83574c). One vault site remains, named above for the Lander.

#1766 and #1617 are referenced as context only. Neither is closed by this PR.