messagefoundry 0.1.0__py3-none-any.whl

messagefoundry/parsing/x12/delimiters.py

@@ -0,0 +1,140 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Fixed-offset X12 ISA delimiter discovery — the X12 analog of reading the HL7 MSH separators.
+
+An ASC X12 interchange opens with a **fixed-length 106-character ISA segment** whose element layout is
+rigid, so the four delimiters are read by *absolute offset* rather than guessed:
+
+* **element separator** — the character at offset ``+3`` (immediately after the literal ``ISA``);
+* **component separator** — ISA16, at offset ``+104``;
+* **segment terminator** — offset ``+105`` (or the two-character ``CR``+``LF`` at ``+105..+106`` when a
+  partner terminates segments that way);
+* **repetition separator** — ISA11, at offset ``+82`` — **but only from version 00501**; in 00401 and
+  earlier ISA11 carries the literal ``U`` (Interchange Control Standards Identifier) and there is no
+  repetition separator.
+
+Trading partners legitimately vary all four delimiters, so hardcoding ``*~:^`` is wrong. We discover
+them and **fail loud** (:class:`~messagefoundry.parsing.x12.errors.X12PeekError`) on a malformed /
+non-X12 header rather than guess — inbound EDI is untrusted, so bad input is routed to the
+error/dead-letter path. This module is **pure** (no I/O, no engine imports): it works on ``str`` only.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from messagefoundry.parsing.x12.errors import X12PeekError
+
+__all__ = [
+    "Delimiters",
+    "discover_delimiters",
+    "find_isa_start",
+    "ISA_SEGMENT_LEN",
+    "ELEMENT_SEP_OFFSETS",
+    "DEFAULT_MAX_INTERCHANGE_BYTES",
+]
+
+#: An ISA segment is ``ISA`` + 16 fixed-width elements + the segment terminator at offset 105.
+ISA_SEGMENT_LEN = 106
+
+#: A pathological interchange would otherwise be buffered/parsed whole; cap it (``None`` disables).
+#: Matches the HL7/MLLP/file ingress caps (16 MiB).
+DEFAULT_MAX_INTERCHANGE_BYTES = 16 * 1024 * 1024
+
+# ISA01..ISA16 fixed element widths (the X12 standard), used to *derive* the element-separator offsets
+# below instead of hand-typing them — so the rigid layout is documented once, in code.
+_ISA_ELEMENT_WIDTHS = (2, 10, 2, 10, 2, 15, 2, 15, 6, 4, 1, 5, 9, 1, 1, 1)
+
+
+def _element_separator_offsets() -> tuple[int, ...]:
+    """The absolute offsets that must all hold the element separator in a well-formed ISA, derived
+    from the fixed element widths: ``(3, 6, 17, 20, 31, 34, 50, 53, 69, 76, 81, 83, 89, 99, 101,
+    103)``. Offset 3 (the *defining* separator) is first; the rest are the sanity-gate positions."""
+    offsets: list[int] = []
+    pos = 3  # the first element separator sits immediately after the literal "ISA"
+    for width in _ISA_ELEMENT_WIDTHS:
+        offsets.append(pos)
+        pos += 1 + width
+    return tuple(offsets)
+
+
+ELEMENT_SEP_OFFSETS = _element_separator_offsets()
+_COMPONENT_SEP_OFFSET = 104  # ISA16
+_SEGMENT_TERM_OFFSET = 105
+_REPETITION_SEP_OFFSET = 82  # ISA11
+_VERSION_START, _VERSION_END = 84, 89  # ISA12 (5 chars), e.g. "00501"
+_REPETITION_MIN_VERSION = "00501"  # ISA11 is a repetition separator from 005010 onward
+
+# Leading characters tolerated before the ISA: whitespace + the UTF-8 BOM (U+FEFF) — pretty-printed or
+# BOM-prefixed feeds.
+_LEADING_NOISE = " \t\r\n\x0b\x0c\ufeff"
+
+
+@dataclass(frozen=True)
+class Delimiters:
+    r"""The four X12 delimiters discovered from an ISA header.
+
+    ``segment`` is the segment terminator — normally one character, but ``"\r\n"`` when a partner
+    terminates segments with ``CR``+``LF``. ``repetition`` is ``None`` for ISA12 < 00501 (ISA11 is the
+    literal ``"U"``, not a delimiter).
+    """
+
+    element: str
+    component: str
+    segment: str
+    repetition: str | None
+
+
+def find_isa_start(raw: str, start: int = 0) -> int:
+    """Index of the ``ISA`` that opens the next interchange at/after ``start`` (skipping leading
+    whitespace/BOM). Raises :class:`X12PeekError` if no ``ISA`` is found there."""
+    i = start
+    n = len(raw)
+    while i < n and raw[i] in _LEADING_NOISE:
+        i += 1
+    if raw[i : i + 3] != "ISA":
+        raise X12PeekError("X12 interchange does not begin with an ISA segment")
+    return i
+
+
+def discover_delimiters(raw: str, isa_start: int | None = None) -> Delimiters:
+    """Read the four delimiters by absolute offset from the ISA at ``isa_start`` (auto-located when
+    ``None``). Raises :class:`X12PeekError` on a truncated/malformed ISA or non-distinct delimiters."""
+    start = find_isa_start(raw) if isa_start is None else isa_start
+    if len(raw) < start + ISA_SEGMENT_LEN:
+        raise X12PeekError(
+            f"X12 ISA header truncated: need {ISA_SEGMENT_LEN} characters, got {len(raw) - start}"
+        )
+
+    element = raw[start + 3]
+    component = raw[start + _COMPONENT_SEP_OFFSET]
+    terminator = raw[start + _SEGMENT_TERM_OFFSET]
+    # The terminator is one character, or CR+LF when raw[+105]=CR is immediately followed by LF.
+    if terminator == "\r" and raw[start + 106 : start + 107] == "\n":
+        segment = "\r\n"
+    else:
+        segment = terminator
+
+    # ISA11 is a repetition separator only from version 00501; earlier it is the literal "U".
+    version = raw[start + _VERSION_START : start + _VERSION_END]
+    repetition: str | None = (
+        raw[start + _REPETITION_SEP_OFFSET] if version >= _REPETITION_MIN_VERSION else None
+    )
+
+    # Sanity gate: every fixed element-separator position (except the defining one at +3) must hold the
+    # element separator — catches a mis-sized / non-X12 header before we trust the offsets.
+    for offset in ELEMENT_SEP_OFFSETS[1:]:
+        if raw[start + offset] != element:
+            raise X12PeekError(
+                f"X12 ISA header malformed: expected element separator {element!r} at offset {offset}"
+            )
+
+    # The delimiters must be mutually distinct or tokenizing is ambiguous. Compare the single-character
+    # terminator (raw[+105]) so a CR+LF terminator is checked by its CR.
+    distinct = [element, component, terminator]
+    if repetition is not None:
+        distinct.append(repetition)
+    if len(set(distinct)) != len(distinct):
+        raise X12PeekError(f"X12 delimiters are not mutually distinct: {distinct!r}")
+
+    return Delimiters(element=element, component=component, segment=segment, repetition=repetition)

messagefoundry/parsing/x12/errors.py

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Exceptions for the X12 codec.
+
+Kept in their own module (mirroring how :mod:`messagefoundry.parsing.peek` owns ``HL7PeekError``) so
+the delimiter / peek / interchange / message modules can raise them without importing each other. All
+derive from :class:`ValueError`, so a Router/Handler that already routes ``ValueError`` to the
+error/dead-letter path catches them without special-casing X12.
+"""
+
+from __future__ import annotations
+
+__all__ = ["X12Error", "X12PeekError", "X12FrameError"]
+
+
+class X12Error(ValueError):
+    """Base class for every X12 codec error."""
+
+
+class X12PeekError(X12Error):
+    """The bytes are not a parseable X12 interchange (no ISA, a truncated/malformed ISA header,
+    non-mutually-distinct delimiters) or an X12 field path is malformed. The X12 analog of
+    :class:`~messagefoundry.parsing.peek.HL7PeekError` — a Router routes the message to the
+    error/dead-letter path rather than guessing."""
+
+
+class X12FrameError(X12Error):
+    """A streaming interchange exceeded its byte cap before the closing ``IEA`` segment — signals the
+    transport to drop the connection rather than buffer without bound (the X12 analog of
+    :class:`~messagefoundry.transports.framing.FrameError`)."""

messagefoundry/parsing/x12/interchange.py

@@ -0,0 +1,232 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""Interchange framing for X12 — splitting one stream into complete ``ISA…IEA`` interchanges.
+
+X12-over-TCP has **no transport sentinel**: the *frame is the interchange*, bounded by the opening
+``ISA`` and the closing ``IEA`` segment, and the segment terminator is **discovered from each ISA
+header** (it may even be a two-byte ``CR``+``LF``). The shared single-byte
+:class:`~messagefoundry.transports.framing.FrameDecoder` cannot express any of that, so X12 needs its
+own assembler. It lives **here**, in the pure parsing layer, so it is unit-testable without a socket
+and reusable by File/console paths; :mod:`messagefoundry.transports.x12` is a thin socket wrapper.
+
+Two surfaces:
+
+* :func:`split` — split a complete ``str`` buffer into interchange substrings (for a Router/console
+  handed a ``RawMessage`` that carries more than one interchange).
+* :class:`X12FrameReader` — a stateful **byte** reassembler (feed it socket chunks, it yields complete
+  interchange bytes) for the transport.
+
+The ``IEA`` trailer is recognised only at a **segment boundary** (the three bytes immediately after a
+segment terminator, tolerating cosmetic whitespace), so ``IEA`` appearing inside element data never
+truncates an interchange early. Both surfaces preserve the interchange **verbatim** (cosmetic newlines
+included) — re-encoding/normalisation is :class:`~messagefoundry.parsing.x12.message.X12Message`'s job.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from messagefoundry.parsing.x12.delimiters import (
+    ISA_SEGMENT_LEN,
+    discover_delimiters,
+    find_isa_start,
+)
+from messagefoundry.parsing.x12.errors import X12FrameError, X12PeekError
+
+__all__ = ["split", "X12FrameReader", "check_integrity"]
+
+# Offset of the segment terminator within the ISA (mirrors delimiters._SEGMENT_TERM_OFFSET, but kept
+# local so the byte reader needs only this module + the public ISA length).
+_SEGMENT_TERM_OFFSET = 105
+_WHITESPACE_BYTES = b" \t\r\n\x0b\x0c"
+_WHITESPACE_STR = " \t\r\n\x0b\x0c"
+
+
+def split(raw: str) -> list[str]:
+    """Split a complete buffer into its ``ISA…IEA`` interchange substrings (verbatim).
+
+    Inter-interchange whitespace/BOM is skipped. A trailing fragment that opens with ``ISA`` but never
+    closes with ``IEA`` is returned as the final (malformed) element so nothing is silently dropped —
+    the caller can dead-letter it. Raises :class:`X12PeekError` if a fragment's ISA header is itself
+    unparseable (truncated/malformed)."""
+    out: list[str] = []
+    pos = 0
+    n = len(raw)
+    while pos < n:
+        try:
+            isa = find_isa_start(raw, pos)
+        except X12PeekError:
+            break  # no further interchange — only trailing noise remains
+        terminator = discover_delimiters(raw, isa).segment
+        end = _find_iea_end_str(raw, isa, terminator)
+        if end is None:
+            out.append(raw[isa:])  # unterminated final interchange — surface it, don't lose it
+            break
+        out.append(raw[isa:end])
+        pos = end
+    return out
+
+
+def _find_iea_end_str(raw: str, isa: int, terminator: str) -> int | None:
+    """Index just past the terminator that closes the ``IEA`` segment of the interchange at ``isa``,
+    or None if it is not complete. ``IEA`` is matched only at a segment boundary."""
+    seg_start = isa
+    while True:
+        idx = raw.find(terminator, seg_start)
+        if idx == -1:
+            return None
+        if raw[seg_start:idx].lstrip(_WHITESPACE_STR)[:3] == "IEA":
+            return idx + len(terminator)
+        seg_start = idx + len(terminator)
+
+
+class X12FrameReader:
+    """Stateful byte reassembler that yields complete X12 interchanges from a raw TCP stream.
+
+    Feed it whatever bytes arrive; it yields each complete ``ISA…IEA<terminator>`` interchange (bytes,
+    verbatim) as it completes. Inter-interchange noise is discarded. ``max_interchange_bytes`` caps a
+    single open interchange (``None`` disables) — exceeding it raises :class:`X12FrameError` so the
+    transport drops the connection rather than buffer without bound.
+    """
+
+    def __init__(self, max_interchange_bytes: int | None = None) -> None:
+        self._buf = bytearray()
+        self.max_interchange_bytes = max_interchange_bytes
+
+    def feed(self, data: bytes) -> Iterator[bytes]:
+        self._buf.extend(data)
+        while True:
+            frame = self._take_one()
+            if frame is None:
+                return
+            yield frame
+
+    def _take_one(self) -> bytes | None:
+        buf = self._buf
+        isa = buf.find(b"ISA")
+        if isa == -1:
+            # No ISA yet: discard noise but keep a 2-byte tail in case "IS" straddles two reads.
+            if len(buf) > 2:
+                del buf[: len(buf) - 2]
+            self._check_cap()
+            return None
+        if isa > 0:
+            del buf[:isa]  # drop inter-interchange noise before the ISA
+        if len(buf) < ISA_SEGMENT_LEN:
+            self._check_cap()
+            return None  # need the full ISA to discover the terminator
+        if (
+            buf[_SEGMENT_TERM_OFFSET : _SEGMENT_TERM_OFFSET + 1] == b"\r"
+            and len(buf) < ISA_SEGMENT_LEN + 1
+        ):
+            # +105 is CR, so the terminator may be a 2-byte CR+LF; wait for +106 before reading it so a
+            # terminator split exactly across two socket reads is still read whole (not a bare CR).
+            self._check_cap()
+            return None
+        terminator = self._terminator(buf)
+        # Cheap guard: don't walk segments until an IEA could plausibly be present.
+        if buf.find(b"IEA", 3) == -1:
+            self._check_cap()
+            return None
+        seg_start = 0
+        while True:
+            idx = buf.find(terminator, seg_start)
+            if idx == -1:
+                self._check_cap()
+                return None  # IEA not complete yet
+            if bytes(buf[seg_start:idx]).lstrip(_WHITESPACE_BYTES)[:3] == b"IEA":
+                end = idx + len(terminator)
+                if self.max_interchange_bytes is not None and end > self.max_interchange_bytes:
+                    # A complete interchange that still exceeds the cap is rejected (a too-large
+                    # message), not relayed — mirrors the eager cap on the shared FrameDecoder.
+                    self._buf.clear()
+                    raise X12FrameError(
+                        f"X12 interchange ({end} bytes) exceeds the "
+                        f"{self.max_interchange_bytes}-byte cap"
+                    )
+                frame = bytes(buf[:end])
+                del buf[:end]
+                return frame
+            seg_start = idx + len(terminator)
+
+    @staticmethod
+    def _terminator(buf: bytearray) -> bytes:
+        """The segment terminator from the ISA at the front of ``buf`` — one byte, or CR+LF."""
+        term = bytes(buf[_SEGMENT_TERM_OFFSET : _SEGMENT_TERM_OFFSET + 1])
+        if term == b"\r" and buf[106:107] == b"\n":
+            return b"\r\n"
+        return term
+
+    def _check_cap(self) -> None:
+        if self.max_interchange_bytes is not None and len(self._buf) > self.max_interchange_bytes:
+            self._buf.clear()
+            raise X12FrameError(
+                f"X12 interchange exceeded {self.max_interchange_bytes} bytes before the IEA segment"
+            )
+
+
+def check_integrity(raw: str) -> list[str]:
+    """Structural integrity tie-out for one interchange (a pure helper, opt-in).
+
+    Returns a list of human-readable problems (empty when the interchange ties out): the control-number
+    pairs ISA13==IEA02, GS06==GE02, ST02==SE02, and the counts GE01==#ST, IEA01==#GS. This is *not*
+    implementation-guide validation (deferred) — just the envelope self-consistency a receiver can cheaply
+    confirm. Raises :class:`X12PeekError` only if the interchange header itself is unparseable."""
+    isa = find_isa_start(raw)
+    delims = discover_delimiters(raw, isa)
+    element, terminator = delims.element, delims.segment
+    segments: list[list[str]] = []
+    for chunk in raw[isa:].split(terminator):
+        stripped = chunk.lstrip(_WHITESPACE_STR)
+        if not stripped:
+            continue
+        segments.append(stripped.split(element))
+        if segments[-1][0] == "IEA":
+            break
+
+    problems: list[str] = []
+
+    def get(fields: list[str], i: int) -> str:
+        return fields[i].strip() if i < len(fields) else ""
+
+    isa_seg = segments[0] if segments and segments[0][0] == "ISA" else None
+    iea_seg = next((s for s in segments if s[0] == "IEA"), None)
+    if isa_seg is not None and iea_seg is not None:
+        # ISA13 is read by offset (fixed-width); IEA02 from the tokenized IEA segment.
+        isa13 = raw[isa + 90 : isa + 99].strip()
+        if isa13 != get(iea_seg, 2):
+            problems.append(f"ISA13 {isa13!r} != IEA02 {get(iea_seg, 2)!r}")
+        gs_count = sum(1 for s in segments if s[0] == "GS")
+        if get(iea_seg, 1) != str(gs_count):
+            problems.append(f"IEA01 {get(iea_seg, 1)!r} != actual GS count {gs_count}")
+
+    # Per functional group: GS06==GE02 and GE01==#ST in the group.
+    current_gs: list[str] | None = None
+    st_in_group = 0
+    # Per transaction set: ST02==SE02 and SE01==#segments in the set (inclusive of ST and SE).
+    current_st: list[str] | None = None
+    seg_in_set = 0
+    for fields in segments:
+        tag = fields[0]
+        if current_st is not None:
+            seg_in_set += 1
+        if tag == "GS":
+            current_gs, st_in_group = fields, 0
+        elif tag == "ST":
+            current_st, seg_in_set = fields, 1  # the ST itself is segment 1 of the set
+            st_in_group += 1
+        elif tag == "SE":
+            if current_st is not None:
+                if get(fields, 2) != get(current_st, 2):
+                    problems.append(f"SE02 {get(fields, 2)!r} != ST02 {get(current_st, 2)!r}")
+                if get(fields, 1) != str(seg_in_set):
+                    problems.append(f"SE01 {get(fields, 1)!r} != actual segment count {seg_in_set}")
+            current_st = None
+        elif tag == "GE":
+            if current_gs is not None:
+                if get(fields, 2) != get(current_gs, 6):
+                    problems.append(f"GE02 {get(fields, 2)!r} != GS06 {get(current_gs, 6)!r}")
+                if get(fields, 1) != str(st_in_group):
+                    problems.append(f"GE01 {get(fields, 1)!r} != actual ST count {st_in_group}")
+            current_gs = None
+    return problems

messagefoundry/parsing/x12/message.py

@@ -0,0 +1,200 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 MessageFoundry Organization and contributors
+"""A mutable X12 message — read and set elements by path, then re-encode (the HL7
+:class:`~messagefoundry.parsing.message.Message` analog for X12 EDI).
+
+Field paths use ``SEG-EE[.CC]`` syntax: a 2–3 char segment id, the 1-based element index (element 0
+is the segment tag, so ``NM1-03`` is the 3rd element of an ``NM1``; ``ISA-06`` the interchange sender
+id), and an optional 1-based component index. Reads/writes address the **first** occurrence of a
+segment unless ``occurrence=`` is given. All structure is rebuilt with the interchange's **own**
+discovered delimiters (never hardcoded), and a write rejects values carrying a delimiter so it can't
+inject new structure. Re-encoding uses the discovered delimiters only, so it is **not** guaranteed
+byte-identical when the source carried cosmetic whitespace between segments (the store keeps the raw
+verbatim — this model is for transforms). Pure: no I/O, no engine imports.
+"""
+
+from __future__ import annotations
+
+import re
+
+from messagefoundry.parsing.x12.delimiters import (
+    Delimiters,
+    discover_delimiters,
+    find_isa_start,
+)
+from messagefoundry.parsing.x12.errors import X12PeekError
+
+__all__ = ["X12Message"]
+
+# SEG-EE[.CC] — segment id (2–3 chars, alpha then alphanumerics), 1-based element, optional component.
+_X12_PATH = re.compile(r"^(?P<seg>[A-Z][A-Z0-9]{1,2})-(?P<elem>\d+)(?:\.(?P<comp>\d+))?$")
+_WHITESPACE = " \t\r\n\x0b\x0c"
+# Segment ids whose addition/removal would corrupt the interchange envelope.
+_ENVELOPE_SEGMENTS = {"ISA", "IEA"}
+
+
+def _parse_path(path: str) -> tuple[str, int, int | None]:
+    m = _X12_PATH.match(path)
+    if not m:
+        raise X12PeekError(f"invalid X12 field path: {path!r}")
+    elem = int(m["elem"])
+    if elem < 1:
+        raise X12PeekError(f"X12 element index is 1-based (>= 1): {path!r}")
+    comp = int(m["comp"]) if m["comp"] else None
+    if comp is not None and comp < 1:
+        raise X12PeekError(f"X12 component index is 1-based (>= 1): {path!r}")
+    return m["seg"], elem, comp
+
+
+class X12Message:
+    """A parsed X12 interchange you can read (``msg["NM1-03"]``), mutate (``msg["BHT-06"] = "RP"``),
+    and re-encode (``msg.encode()``)."""
+
+    def __init__(self, segments: list[list[str]], delimiters: Delimiters) -> None:
+        self._segments = segments
+        self._delims = delimiters
+
+    @classmethod
+    def parse(cls, raw: str | bytes) -> X12Message:
+        """Parse the interchange starting ``raw`` (after leading whitespace/BOM) into a mutable model.
+
+        Raises :class:`X12PeekError` if the ISA header is not parseable."""
+        if isinstance(raw, (bytes, bytearray)):
+            raw = bytes(raw).decode("utf-8", "replace")
+        isa = find_isa_start(raw)
+        delims = discover_delimiters(raw, isa)
+        segments: list[list[str]] = []
+        for chunk in raw[isa:].split(delims.segment):
+            stripped = chunk.lstrip(_WHITESPACE)
+            if not stripped:
+                continue
+            segments.append(stripped.split(delims.element))
+            if segments[-1][0] == "IEA":
+                break
+        return cls(segments, delims)
+
+    @property
+    def delimiters(self) -> Delimiters:
+        return self._delims
+
+    # --- read ----------------------------------------------------------------
+
+    def get(self, path: str, *, occurrence: int = 1) -> str | None:
+        """Value at ``path`` (``"ISA-06"``, ``"NM1-03"``, ``"NM1-03.1"``), or None if absent/empty.
+        ``occurrence`` (1-based) selects which segment of that id to read."""
+        seg_id, elem, comp = _parse_path(path)
+        seg = self._nth_segment(seg_id, occurrence)
+        if seg is None or elem >= len(seg):
+            return None
+        value = seg[elem]
+        if comp is None:
+            return value or None
+        comps = value.split(self._delims.component)
+        return (comps[comp - 1] or None) if comp <= len(comps) else None
+
+    def __getitem__(self, path: str) -> str | None:
+        return self.get(path)
+
+    def segment_ids(self) -> list[str]:
+        """Ordered segment ids, e.g. ``["ISA", "GS", "ST", "BHT", …, "IEA"]``."""
+        return [seg[0] for seg in self._segments]
+
+    def count_segments(self, segment_id: str) -> int:
+        """How many segments of ``segment_id`` the interchange has (0 if none)."""
+        return sum(1 for seg in self._segments if seg[0] == segment_id)
+
+    # --- mutate --------------------------------------------------------------
+
+    def set(self, path: str, value: str, *, occurrence: int = 1) -> None:
+        """Write ``value`` at ``path``, extending the element/components as needed.
+
+        ``value`` may not contain a delimiter (element/component/repetition separator or a segment
+        terminator character, incl. CR/LF) — that would inject new structure — and raises ``ValueError``
+        if it does. Raises ``KeyError`` if the target segment occurrence is absent."""
+        seg_id, elem, comp = _parse_path(path)
+        self._reject_delimiters(value, whole_element=comp is None)
+        seg = self._nth_segment(seg_id, occurrence)
+        if seg is None:
+            where = f"{seg_id!r}" + (f" occurrence {occurrence}" if occurrence > 1 else "")
+            raise KeyError(f"cannot set absent segment {where}")
+        while len(seg) <= elem:
+            seg.append("")
+        if comp is None:
+            seg[elem] = value
+            return
+        comps = seg[elem].split(self._delims.component) if seg[elem] else []
+        while len(comps) < comp:
+            comps.append("")
+        comps[comp - 1] = value
+        seg[elem] = self._delims.component.join(comps)
+
+    def __setitem__(self, path: str, value: str) -> None:
+        self.set(path, value)
+
+    def add_segment(self, line: str, *, index: int | None = None) -> None:
+        """Add a whole segment from a raw ``line`` like ``"REF*EI*123456789"`` (split on the
+        interchange's own element separator). It must be a single segment (no terminator/CR/LF) with a
+        valid 2–3 char id, and may not be an envelope segment (``ISA``/``IEA``). Appended by default;
+        pass a 1-based ``index`` to insert earlier. Raises ``ValueError`` on a malformed line/index."""
+        for ch in self._delims.segment + "\r\n":
+            if ch in line:
+                raise ValueError("add_segment takes one segment line (no terminator/CR/LF)")
+        fields = line.split(self._delims.element)
+        seg_id = fields[0]
+        if not re.fullmatch(r"[A-Z][A-Z0-9]{1,2}", seg_id):
+            raise ValueError(f"segment must begin with a 2-3 char id, got {seg_id!r}")
+        if seg_id in _ENVELOPE_SEGMENTS:
+            raise ValueError(f"refusing to add an envelope segment {seg_id!r}")
+        if index is None:
+            self._segments.append(fields)
+            return
+        if index < 1 or index > len(self._segments):
+            raise ValueError(f"index {index} out of range (1..{len(self._segments)})")
+        self._segments.insert(index, fields)
+
+    def delete_segments(self, segment_id: str) -> int:
+        """Remove every segment with ``segment_id`` and return how many were removed. Refuses to delete
+        an envelope segment (``ISA``/``IEA``)."""
+        if segment_id in _ENVELOPE_SEGMENTS:
+            raise ValueError(f"refusing to delete envelope segment {segment_id!r}")
+        before = len(self._segments)
+        self._segments = [seg for seg in self._segments if seg[0] != segment_id]
+        return before - len(self._segments)
+
+    # --- encode --------------------------------------------------------------
+
+    def encode(self) -> str:
+        """Serialize back to a delimited X12 string (each segment closed by the terminator)."""
+        element, terminator = self._delims.element, self._delims.segment
+        body = terminator.join(element.join(seg) for seg in self._segments)
+        return body + terminator if body else body
+
+    def __str__(self) -> str:
+        return self.encode()
+
+    # --- internals -----------------------------------------------------------
+
+    def _nth_segment(self, segment_id: str, occurrence: int) -> list[str] | None:
+        if occurrence < 1:
+            raise ValueError("occurrence is 1-based (>= 1)")
+        seen = 0
+        for seg in self._segments:
+            if seg[0] == segment_id:
+                seen += 1
+                if seen == occurrence:
+                    return seg
+        return None
+
+    def _reject_delimiters(self, value: str, *, whole_element: bool) -> None:
+        forbidden = {self._delims.element, "\r", "\n"}
+        forbidden.update(self._delims.segment)
+        if self._delims.repetition:
+            forbidden.add(self._delims.repetition)
+        if not whole_element:
+            forbidden.add(self._delims.component)
+        present = sorted(ch for ch in forbidden if ch in value)
+        if present:
+            raise ValueError(
+                f"X12 value may not contain delimiter character(s) {present!r}; "
+                "it would inject new structure"
+            )