messagefoundry 0.1.0__py3-none-any.whl

messagefoundry/parsing/peek.py

@@ -0,0 +1,237 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Tolerant HL7 v2 *peek* — fast field extraction for routing/filtering.
+
+This is the hot path: every inbound message is peeked to pull the handful of MSH
+fields the engine routes on (message type, trigger event, control id, version) and to
+let channel/destination filters test arbitrary fields by path (e.g. ``MSH-9.1``).
+
+It is built on ``python-hl7``, which parses tolerantly — real-world feeds are routinely
+non-conformant and must still route. We never raise on a *structurally* odd-but-parseable
+message; we only raise :class:`HL7PeekError` when the bytes are not an HL7 message at all
+(no MSH) or a field *path* is malformed.
+
+HL7 uses a carriage return (``\\r``) between segments. Inbound bytes arrive with all
+manner of line endings (MLLP strips its own framing; files may be ``\\n`` or ``\\r\\n``),
+so :func:`normalize` collapses them to ``\\r`` before parsing.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+import hl7
+
+__all__ = [
+    "Peek",
+    "HL7PeekError",
+    "normalize",
+    "parse_path",
+    "DEFAULT_MAX_MESSAGE_BYTES",
+    "DEFAULT_MAX_SEGMENTS",
+    "enforce_size_limits",
+]
+
+# Pre-parse resource caps (DoS guards). A complete-but-pathological message — multi-MiB, or
+# tens of thousands of segments — would otherwise be parsed/walked whole (python-hl7 here,
+# hl7apy on the strict path), multiplying memory and CPU. Checked *before* parsing so an
+# oversized message is rejected cheaply. ``None`` disables a cap.
+DEFAULT_MAX_MESSAGE_BYTES = 16 * 1024 * 1024  # 16 MiB — matches the MLLP/file ingress caps
+DEFAULT_MAX_SEGMENTS = 10_000  # generous for big batches/ORUs, bounds segment-count blow-up
+
+
+class HL7PeekError(ValueError):
+    """Raised when bytes are not a parseable HL7 message, or a field path is malformed."""
+
+
+def enforce_size_limits(
+    norm: str,
+    *,
+    max_bytes: int | None = DEFAULT_MAX_MESSAGE_BYTES,
+    max_segments: int | None = DEFAULT_MAX_SEGMENTS,
+) -> None:
+    """Raise :class:`HL7PeekError` if the normalized message exceeds the size/segment caps.
+
+    Operates on the ``\\r``-normalized text so it covers every ingress (MLLP, file). Shared
+    by :meth:`Peek.parse`, :func:`~messagefoundry.parsing.validate.validate` and
+    :func:`~messagefoundry.parsing.tree.parse_tree`."""
+    if max_bytes is not None and len(norm) > max_bytes:
+        raise HL7PeekError(f"message exceeds max size ({len(norm)} > {max_bytes} bytes)")
+    if max_segments is not None:
+        segment_count = norm.count("\r") + 1
+        if segment_count > max_segments:
+            raise HL7PeekError(f"message exceeds max segments ({segment_count} > {max_segments})")
+
+
+# SEG-F[.C[.S]] — segment id, field, optional component, optional subcomponent.
+# Repetition defaults to the first; segment to its first occurrence (Phase 1).
+_PATH_RE = re.compile(
+    r"^(?P<seg>[A-Z][A-Z0-9]{2})-(?P<field>\d+)"
+    r"(?:\.(?P<comp>\d+)(?:\.(?P<sub>\d+))?)?$"
+)
+
+
+def parse_path(path: str) -> tuple[str, int, int | None, int | None]:
+    """Split an HL7 field path into ``(segment, field, component, subcomponent)``.
+
+    Component/subcomponent are ``None`` when omitted. Raises :class:`HL7PeekError` on a
+    malformed path. Shared by :meth:`Peek.field` (read) and the transform engine (write).
+    """
+    m = _PATH_RE.match(path)
+    if not m:
+        raise HL7PeekError(f"invalid HL7 field path: {path!r}")
+    return (
+        m["seg"],
+        int(m["field"]),
+        int(m["comp"]) if m["comp"] else None,
+        int(m["sub"]) if m["sub"] else None,
+    )
+
+
+def normalize(raw: str | bytes, *, encoding: str = "utf-8", errors: str = "replace") -> str:
+    """Decode (if ``raw`` is bytes) with ``encoding``/``errors`` and collapse all line endings to
+    HL7's ``\\r`` separator.
+
+    The default is tolerant (``utf-8``/``replace``) so the hot path keeps routing a slightly-off
+    message rather than choking. The engine's inbound path instead passes the connection's declared
+    encoding with ``errors="strict"`` and routes a genuine ``UnicodeDecodeError`` to the ERROR
+    disposition, so a wrong-charset feed isn't silently turned into U+FFFD in the stored raw and the
+    delivered copy (review H-3)."""
+    if isinstance(raw, (bytes, bytearray)):
+        raw = bytes(raw).decode(encoding, errors)
+    return raw.replace("\r\n", "\r").replace("\n", "\r")
+
+
+@dataclass(frozen=True)
+class Peek:
+    """A parsed view over an inbound message exposing routing fields + path access.
+
+    Construct via :meth:`parse`. ``message`` is the underlying ``python-hl7`` parse;
+    ``raw`` is the normalized (``\\r``-delimited) text it was parsed from.
+    """
+
+    message: hl7.Message
+    raw: str
+
+    @classmethod
+    def parse(
+        cls,
+        raw: str | bytes,
+        *,
+        max_bytes: int | None = DEFAULT_MAX_MESSAGE_BYTES,
+        max_segments: int | None = DEFAULT_MAX_SEGMENTS,
+    ) -> "Peek":
+        norm = normalize(raw)
+        if not norm.strip():
+            raise HL7PeekError("empty message")
+        enforce_size_limits(norm, max_bytes=max_bytes, max_segments=max_segments)
+        if not norm.lstrip().startswith("MSH"):
+            raise HL7PeekError("message does not start with an MSH segment")
+        try:
+            message = hl7.parse(norm)
+        except Exception as exc:  # python-hl7 raises a variety of ValueErrors
+            raise HL7PeekError(f"could not parse HL7 message: {exc}") from exc
+        return cls(message=message, raw=norm)
+
+    # --- generic field access (for filters) ----------------------------------
+
+    def field(self, path: str) -> str | None:
+        """Return the value at an HL7 path like ``MSH-9``, ``MSH-9.1`` or ``PID-5.1.1``.
+
+        Returns ``None`` if the segment/field/component is absent or empty. Uses the
+        first occurrence of the segment and the first repetition of the field.
+        """
+        seg, fld, comp, sub = parse_path(path)
+        return self._resolve(seg, fld, comp, sub)
+
+    def _resolve(self, seg: str, fld: int, comp: int | None, sub: int | None) -> str | None:
+        try:
+            segment = self.message.segment(seg)
+        except KeyError:
+            return None
+        try:
+            field_obj = segment[fld]
+        except (IndexError, KeyError):
+            return None
+        if comp is None:
+            return str(field_obj) or None
+        # For component/subcomponent access use python-hl7's extractor (first segment, first
+        # repetition). It correctly returns the whole value when the field carries no component
+        # separator — manual indexing would otherwise walk into the *string* and return a single
+        # character (e.g. "ORC-2.1" of "PLACER123" => "P"). Out-of-range parts raise IndexError.
+        try:
+            value = self.message.extract_field(seg, 1, fld, 1, comp, sub if sub is not None else 1)
+        except IndexError:
+            return None
+        return value or None
+
+    # --- named routing fields (the common case) ------------------------------
+
+    @property
+    def message_code(self) -> str | None:
+        """MSH-9.1, e.g. ``ADT``."""
+        return self.field("MSH-9.1")
+
+    @property
+    def trigger_event(self) -> str | None:
+        """MSH-9.2, e.g. ``A01``."""
+        return self.field("MSH-9.2")
+
+    @property
+    def message_structure(self) -> str | None:
+        """MSH-9.3, e.g. ``ADT_A01`` (often absent)."""
+        return self.field("MSH-9.3")
+
+    @property
+    def message_type(self) -> str | None:
+        """MSH-9 as sent, e.g. ``ADT^A01``."""
+        return self.field("MSH-9")
+
+    @property
+    def control_id(self) -> str | None:
+        """MSH-10 — the message control id, used for de-dup/correlation."""
+        return self.field("MSH-10")
+
+    @property
+    def version(self) -> str | None:
+        """MSH-12, e.g. ``2.5.1`` (None if the sender omitted it)."""
+        return self.field("MSH-12")
+
+    @property
+    def sending_app(self) -> str | None:
+        return self.field("MSH-3")
+
+    @property
+    def sending_facility(self) -> str | None:
+        return self.field("MSH-4")
+
+    @property
+    def receiving_app(self) -> str | None:
+        return self.field("MSH-5")
+
+    @property
+    def receiving_facility(self) -> str | None:
+        return self.field("MSH-6")
+
+    @property
+    def timestamp(self) -> str | None:
+        """MSH-7 — message date/time as sent."""
+        return self.field("MSH-7")
+
+    def routing(self) -> dict[str, str | None]:
+        """The routing/correlation fields the store records. No PHI segments here."""
+        return {
+            "message_type": self.message_type,
+            "control_id": self.control_id,
+            "version": self.version,
+            "sending_app": self.sending_app,
+            "sending_facility": self.sending_facility,
+            "receiving_app": self.receiving_app,
+            "receiving_facility": self.receiving_facility,
+            "timestamp": self.timestamp,
+        }
+
+    def segments(self) -> list[str]:
+        """Ordered segment ids, e.g. ``["MSH", "EVN", "PID", "PV1"]``."""
+        return [str(seg[0]) for seg in self.message]

messagefoundry/parsing/split.py

@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Splitting a single inbound payload into many messages (Corepoint-style "message split").
+
+Two independent splits, both pure (no I/O, no engine state) so they can run on the hot path and be
+reused by the dry-run / Test Bench:
+
+* :func:`split_batch` — a **batch** file (an ``FHS``/``BHS`` batch or just several ``MSH`` messages
+  concatenated) becomes one message per ``MSH`` boundary, in file order. This is the canonical
+  splitter the File source uses at ingress and that :func:`~messagefoundry.pipeline.dryrun.split_messages`
+  delegates to, so the live engine and a dry-run split identically (single source of truth).
+
+* :func:`split_by_obr` — one HL7 order message (an ORM/ORU carrying several ``OBR`` order groups)
+  becomes one message per ``OBR`` group, each re-attached to the shared header. This is the
+  handler-side equivalent of Corepoint's ``ItemSplit`` — a pure helper a Handler calls to fan one
+  order message out into per-order messages.
+
+Both read the message's **own** separators (MSH-1/MSH-2) and go through the :class:`Message`
+primitive — never raw string-slicing of structured HL7.
+"""
+
+from __future__ import annotations
+
+import re
+
+from messagefoundry.parsing.message import Message
+from messagefoundry.parsing.peek import normalize
+
+__all__ = ["split_batch", "split_by_obr"]
+
+# Split a normalized (``\r``-delimited) payload before each non-leading ``MSH`` segment. We match
+# ``\rMSH`` *without* the trailing field separator so a batch whose MSH-1 isn't ``|`` (e.g.
+# ``MSH^...``) still splits per-message instead of being read as one giant message — after a ``\r`` a
+# segment id is always exactly three chars, so only an ``MSH`` segment starts with the literal "MSH".
+_MSH_BOUNDARY = re.compile(r"(?=\rMSH)")
+
+
+def split_batch(raw: str | bytes) -> list[str]:
+    """Split a possibly-batched HL7 payload into individual messages on ``MSH`` boundaries.
+
+    A real file connection delivers each ``MSH``-delimited message separately; mirror that so a
+    batch file (or an ``FHS``/``BHS`` envelope wrapping several messages) yields every message, in
+    file order — not just the first. Each returned message is ``\r``-delimited and starts at its
+    ``MSH`` (any ``FHS``/``BHS``/``FTS``/``BTS`` batch-envelope lines around the messages are dropped,
+    since each split message is routed on its own and the batch framing has no per-message meaning).
+
+    A payload with a single message round-trips unchanged (a one-element list); an empty/whitespace
+    payload yields the normalized text as the sole element (the caller — e.g. the parser — then
+    reports it as malformed rather than silently dropping it).
+    """
+    text = normalize(raw)  # \r-delimited, decoupled from the inbound line endings
+    chunks = _MSH_BOUNDARY.split(text)
+    # Keep only the MSH-led chunks: a leading FHS/BHS envelope (or stray whitespace) before the first
+    # MSH is not itself a message. ``lstrip("\r")`` strips the boundary's own leading CR; a chunk that
+    # isn't MSH-led after stripping (the batch header) is dropped.
+    messages = [c.lstrip("\r") for c in chunks if c.strip() and c.lstrip("\r").startswith("MSH")]
+    return messages or [text]
+
+
+def split_by_obr(message: Message | str | bytes) -> list[str]:
+    """Split one HL7 order message into one message per ``OBR`` order group (Corepoint ``ItemSplit``).
+
+    **Grouping rule.** Everything *before the first* ``OBR`` is the shared **header** (``MSH`` plus
+    any patient-/visit-level segments — ``EVN``/``PID``/``PV1``/``ORC``/``NTE``…). Each ``OBR`` begins
+    a new **order group** that runs up to (but not including) the next ``OBR``; its group carries that
+    ``OBR`` and every segment after it (``OBX``/``NTE``/``SPM``…) until the next order. Each produced
+    message is ``header segments + that one order group``, re-encoded through :class:`Message` so it
+    re-parses cleanly.
+
+    **MSH-10 (control id) handling.** Splitting one message into N would otherwise emit N messages
+    sharing the original control id, breaking de-dup/correlation downstream. So each split message's
+    MSH-10 is **suffixed with its 1-based order index** using the message's own component separator
+    is *not* involved — the suffix is appended to the existing control id with a literal ``-`` (e.g.
+    ``MSG1`` → ``MSG1-1``, ``MSG1-2``). The first split is *not* special-cased (it too becomes
+    ``…-1``) so every emitted message is uniquely and predictably identifiable, and a 1-OBR message
+    that is "split" still gets ``…-1`` — a deliberate, documented contract a reviewer can rely on. A
+    message with **no** MSH-10 is left untouched (nothing to suffix).
+
+    **0 or 1 OBR.** A message with **one** ``OBR`` returns a single-element list (the whole message,
+    with MSH-10 suffixed ``-1`` per above). A message with **zero** ``OBR`` is *not* an order message
+    to split, so it is returned **as-is** in a single-element list with its control id **unchanged**
+    (no suffix) — the natural no-op for a non-order message.
+
+    Accepts a :class:`Message`, or a raw ``str``/``bytes`` (parsed here), matching how the other
+    parsing helpers take input. Returns re-encoded ``\r``-delimited HL7 strings.
+    """
+    msg = message if isinstance(message, Message) else Message.parse(message)
+    segments = msg.segments()
+    obr_count = segments.count("OBR")
+
+    # No order groups: not a splittable order message — return it verbatim (control id untouched).
+    if obr_count == 0:
+        return [msg.encode()]
+
+    # Index of each OBR among all segments (0-based positions in segment order). The shared header is
+    # every segment before the first OBR; each group spans one OBR up to the next.
+    obr_positions = [i for i, seg in enumerate(segments) if seg == "OBR"]
+    header_end = obr_positions[0]
+    boundaries = [*obr_positions, len(segments)]  # group i = [obr_positions[i], boundaries[i+1])
+
+    # Work from the raw segment *lines* so each group is re-attached to the header verbatim and
+    # re-parsed — no field-level reconstruction, and the original encoding characters are preserved.
+    lines = msg.encode().split("\r")
+    # encode() may leave a trailing "" after the final \r; align line count to the segment count so
+    # positional slicing matches segments() exactly.
+    seg_lines = [ln for ln in lines if ln]
+    header_lines = seg_lines[:header_end]
+
+    out: list[str] = []
+    control_id = msg.control_id
+    for idx, start in enumerate(obr_positions, start=1):
+        end = boundaries[idx]  # next OBR position (or end of message)
+        group_lines = seg_lines[start:end]
+        part = Message.parse("\r".join([*header_lines, *group_lines]) + "\r")
+        # Suffix the control id so the N split messages stay individually correlatable downstream;
+        # set() goes through the Message primitive (separator-aware, never raw slicing).
+        if control_id is not None:
+            part.set("MSH-10", f"{control_id}-{idx}")
+        out.append(part.encode())
+    return out

messagefoundry/parsing/summary.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Build a short, human-readable message summary from a :class:`Peek`.
+
+Computed once at ingest and stored in its own column (outside the serialized body) so the
+search/list view never reparses HL7. PHI-bearing (MRN, patient name) — see the store's audit
+note. Tolerant: any missing field is simply omitted.
+"""
+
+from __future__ import annotations
+
+from messagefoundry.parsing.peek import Peek
+
+__all__ = ["summarize"]
+
+_ORDER_TYPES = {"ORM", "ORU"}
+
+
+def _patient_name(peek: Peek) -> str | None:
+    family = peek.field("PID-5.1")
+    given = peek.field("PID-5.2")
+    if family and given:
+        return f"{family}, {given}"
+    return family
+
+
+def summarize(peek: Peek) -> str:
+    """e.g. ``MRN 100001 · DOE, JANE`` (+ ``· Order 12345 · Acc 67890`` for ORM/ORU)."""
+    parts: list[str] = []
+
+    mrn = peek.field("PID-3.1")
+    if mrn:
+        parts.append(f"MRN {mrn}")
+    name = _patient_name(peek)
+    if name:
+        parts.append(name)
+
+    if (peek.message_code or "") in _ORDER_TYPES:
+        order = peek.field("ORC-2.1") or peek.field("OBR-2.1")  # placer order number
+        accession = peek.field("OBR-3.1") or peek.field("ORC-3.1")  # filler / accession
+        if order:
+            parts.append(f"Order {order}")
+        if accession:
+            parts.append(f"Acc {accession}")
+
+    return " · ".join(parts)

messagefoundry/parsing/tree.py

@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Structured HL7 parse tree for the message viewer.
+
+Turns a raw message into a nested ``segment → field → repetition → component →
+subcomponent`` structure with HL7 paths and values, so the console can render an
+explorable tree without reaching into ``python-hl7`` internals. Pure and tolerant: it
+builds whatever parses (the viewer must show non-conformant messages too).
+
+Splitting is done from the message's own MSH-1/MSH-2 separators rather than assumed
+defaults, so messages using non-standard encoding characters render correctly. MSH-1
+(the field separator) and MSH-2 (the encoding characters) are represented as literal
+single-value fields, matching how operators expect to see them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from messagefoundry.parsing.peek import (
+    DEFAULT_MAX_MESSAGE_BYTES,
+    DEFAULT_MAX_SEGMENTS,
+    HL7PeekError,
+    enforce_size_limits,
+    normalize,
+)
+
+__all__ = ["TreeNode", "parse_tree"]
+
+
+@dataclass
+class TreeNode:
+    """One node in the parse tree.
+
+    ``label`` is a human/HL7 label (``MSH``, ``MSH-9``, ``MSH-9.1`` …); ``value`` is the
+    raw text of that node (empty for nodes that only group children); ``children`` are the
+    next level down. Leaf nodes (subcomponents, or atomic components/fields) have no
+    children and carry the value."""
+
+    label: str
+    value: str = ""
+    children: list["TreeNode"] = field(default_factory=list)
+
+
+def parse_tree(raw: str | bytes) -> list[TreeNode]:
+    """Build a list of segment :class:`TreeNode` from ``raw``.
+
+    Raises :class:`HL7PeekError` only when there is no parseable MSH to derive separators
+    from; otherwise it returns the best-effort structure of whatever is present.
+    """
+    text = normalize(raw).strip("\r")
+    if not text:
+        raise HL7PeekError("empty message")
+    enforce_size_limits(
+        text, max_bytes=DEFAULT_MAX_MESSAGE_BYTES, max_segments=DEFAULT_MAX_SEGMENTS
+    )
+    segments = [s for s in text.split("\r") if s]
+    if not segments or not segments[0].startswith("MSH"):
+        raise HL7PeekError("message does not start with an MSH segment")
+
+    field_sep, comp_sep, rep_sep, sub_sep = _separators(segments[0])
+    return [_segment_node(seg, field_sep, comp_sep, rep_sep, sub_sep) for seg in segments]
+
+
+def _separators(msh: str) -> tuple[str, str, str, str]:
+    """Derive (field, component, repetition, subcomponent) separators from the MSH line."""
+    field_sep = msh[3] if len(msh) > 3 else "|"
+    enc = msh[4:8] if len(msh) > 4 else "^~\\&"
+    comp_sep = enc[0] if len(enc) > 0 else "^"
+    rep_sep = enc[1] if len(enc) > 1 else "~"
+    sub_sep = enc[3] if len(enc) > 3 else "&"
+    return field_sep, comp_sep, rep_sep, sub_sep
+
+
+def _segment_node(
+    segment: str, field_sep: str, comp_sep: str, rep_sep: str, sub_sep: str
+) -> TreeNode:
+    parts = segment.split(field_sep)
+    seg_id = parts[0]
+    node = TreeNode(label=seg_id)
+
+    if seg_id == "MSH":
+        # MSH-1 is the field separator itself; MSH-2 the encoding chars. Render them as
+        # literal fields and number the rest from 3 so paths line up with the spec.
+        node.children.append(TreeNode(label="MSH-1", value=field_sep))
+        if len(parts) > 1:
+            node.children.append(TreeNode(label="MSH-2", value=parts[1]))
+        raw_fields = parts[2:]
+        start_index = 3
+    else:
+        raw_fields = parts[1:]
+        start_index = 1
+
+    for offset, raw_field in enumerate(raw_fields):
+        fld_index = start_index + offset
+        node.children.append(
+            _field_node(f"{seg_id}-{fld_index}", raw_field, comp_sep, rep_sep, sub_sep)
+        )
+    return node
+
+
+def _field_node(label: str, raw_field: str, comp_sep: str, rep_sep: str, sub_sep: str) -> TreeNode:
+    repetitions = raw_field.split(rep_sep)
+    if len(repetitions) > 1:
+        node = TreeNode(label=label, value=raw_field)
+        for i, rep in enumerate(repetitions, start=1):
+            node.children.append(_components_node(f"{label}[{i}]", rep, comp_sep, sub_sep))
+        return node
+    return _components_node(label, raw_field, comp_sep, sub_sep)
+
+
+def _components_node(label: str, raw_value: str, comp_sep: str, sub_sep: str) -> TreeNode:
+    components = raw_value.split(comp_sep)
+    if len(components) <= 1 and sub_sep not in raw_value:
+        # Atomic field/repetition: a single leaf carrying the value. (A lone component
+        # that itself has subcomponents, e.g. ``a&b&c``, still expands below.)
+        return TreeNode(label=label, value=raw_value)
+    node = TreeNode(label=label, value=raw_value)
+    for ci, comp in enumerate(components, start=1):
+        subs = comp.split(sub_sep)
+        if len(subs) <= 1:
+            node.children.append(TreeNode(label=f"{label}.{ci}", value=comp))
+        else:
+            comp_node = TreeNode(label=f"{label}.{ci}", value=comp)
+            for si, sub in enumerate(subs, start=1):
+                comp_node.children.append(TreeNode(label=f"{label}.{ci}.{si}", value=sub))
+            node.children.append(comp_node)
+    return node

messagefoundry/parsing/validate.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Strict, version-aware HL7 v2 validation — the opt-in tier.
+
+Built on ``hl7apy``, which knows the official HL7 message structures per version and
+checks segment cardinality, datatypes, table values and lengths. It is slower and far
+stricter than :mod:`~messagefoundry.parsing.peek`, so it runs only when a channel sets
+``validation.strict = true`` and is kept off the routing hot path.
+
+``hl7apy`` raises on the *first* problem it finds, which is exactly what a strict channel
+needs: one conformance error is enough to NACK. We surface that single message rather
+than writing a full multi-error report to disk — a report file of a PHI message is a
+data-leak we don't want by default. (Full reporting can become an explicit, opt-in,
+redaction-aware feature later.)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from messagefoundry.parsing.peek import (
+    DEFAULT_MAX_MESSAGE_BYTES,
+    DEFAULT_MAX_SEGMENTS,
+    HL7PeekError,
+    enforce_size_limits,
+    normalize,
+)
+
+__all__ = ["ValidationResult", "validate"]
+
+
+@dataclass(frozen=True)
+class ValidationResult:
+    """Outcome of strict validation. Truthy iff the message is conformant."""
+
+    ok: bool
+    version: str | None
+    errors: list[str]
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+
+def validate(
+    raw: str | bytes,
+    *,
+    expected_version: str | None = None,
+    profile: object | None = None,
+    max_bytes: int | None = DEFAULT_MAX_MESSAGE_BYTES,
+    max_segments: int | None = DEFAULT_MAX_SEGMENTS,
+) -> ValidationResult:
+    """Validate ``raw`` against the official structures for its (or ``expected_version``).
+
+    ``expected_version`` cross-checks MSH-12: if the message declares a different version
+    that is reported as an error (a feed sending the wrong version is a misconfiguration
+    a strict channel should reject). ``profile`` is reserved for a conformance-profile
+    object (Phase 2+); passing one today is accepted but not yet enforced. ``max_bytes`` /
+    ``max_segments`` reject an oversized message before the (slow) strict parse.
+    """
+    from hl7apy.exceptions import HL7apyException
+    from hl7apy.parser import parse_message
+    from hl7apy.validation import Validator
+
+    norm = normalize(raw).strip("\r")
+    if not norm:
+        return ValidationResult(False, expected_version, ["empty message"])
+
+    # Bound resource use before the (slow) strict parse — the MLLP frame cap doesn't protect
+    # a complete-but-huge message, and hl7apy's structure builder is the heavier amplifier.
+    try:
+        enforce_size_limits(norm, max_bytes=max_bytes, max_segments=max_segments)
+    except HL7PeekError as exc:
+        return ValidationResult(False, expected_version, [str(exc)])
+
+    try:
+        message = parse_message(norm, find_groups=True)
+    except HL7apyException as exc:
+        return ValidationResult(False, expected_version, [f"parse error: {exc}"])
+    except Exception as exc:  # defensive: never let validation crash the pipeline
+        return ValidationResult(False, expected_version, [f"parse error: {exc}"])
+
+    version = getattr(message, "version", None)
+    errors: list[str] = []
+
+    if expected_version and version and expected_version != version:
+        errors.append(f"version mismatch: message is {version}, channel expects {expected_version}")
+
+    try:
+        Validator.validate(message)
+    except HL7apyException as exc:
+        errors.append(str(exc))
+    except Exception as exc:  # defensive
+        errors.append(str(exc))
+
+    return ValidationResult(ok=not errors, version=version, errors=errors)

messagefoundry/parsing/x12/__init__.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Pure ASC X12 EDI codec (ADR 0012) — a tolerant routing peek, an interchange splitter/assembler, and
+a mutable message model, mirroring the HL7 :mod:`messagefoundry.parsing` library.
+
+It is **pure and side-effect-free** (no I/O, no engine state) and imports nothing from
+``messagefoundry.config`` / ``pipeline`` / ``store`` / ``transports`` — so the console may import it,
+and a code-first Router/Handler calls it **on demand** against a
+:class:`~messagefoundry.parsing.message.RawMessage` (``content_type="x12"``, ADR 0004): X12 is **not**
+pushed through the engine pipeline as a bespoke object. The X12 content type is referred to by the
+literal string ``"x12"`` (never imported from ``config``) to keep this purity.
+
+Two tiers, mirroring python-hl7 (tolerant) / hl7apy (strict):
+
+* **Tolerant (built here):** :class:`X12Peek` (cheap ISA + GS/ST peek for routing), :func:`split` /
+  :class:`X12FrameReader` (interchange framing), :class:`X12Message` (read/set/encode for transforms),
+  :func:`check_integrity` (envelope tie-out).
+* **Strict (deferred):** implementation-guide validation (e.g. 005010X222A1 for 837P) is future work.
+"""
+
+from __future__ import annotations
+
+from messagefoundry.parsing.x12.delimiters import (
+    Delimiters,
+    discover_delimiters,
+    find_isa_start,
+)
+from messagefoundry.parsing.x12.errors import X12Error, X12FrameError, X12PeekError
+from messagefoundry.parsing.x12.interchange import X12FrameReader, check_integrity, split
+from messagefoundry.parsing.x12.message import X12Message
+from messagefoundry.parsing.x12.peek import X12Group, X12Peek
+
+__all__ = [
+    "X12Peek",
+    "X12Group",
+    "X12Message",
+    "X12FrameReader",
+    "split",
+    "check_integrity",
+    "discover_delimiters",
+    "find_isa_start",
+    "Delimiters",
+    "X12Error",
+    "X12PeekError",
+    "X12FrameError",
+]