@cosyte/x12 0.0.15 → 0.0.16

package/KNOWN-LIMITATIONS.md

@@ -16,6 +16,162 @@ model.
 
 ## Data / decode boundaries
 
+- **🩺 `parseTA1`'s five decoded fields are POST-`?`-unescape as of this release, and an EMPTY
+  TA1-02 / TA1-03 / TA1-04 / TA1-05 is REFUSED on emit. Both are behaviour changes**
+  (`X12-TA1-RESIDUALS`). They are one slice because they are the two ends of the same disagreement:
+  this package's emit half releases a TA1 element and its read half decoded the escape rather than
+  the value.
+
+  **The read half.** `X12-TA1-EMIT-NOT-RELEASE-AWARE` made `buildTA1` release all five caller
+  elements, and `parseTA1` kept reading `elements` verbatim, so a round trip through this package's
+  own halves was not an identity for any value carrying a delimiter or the release character.
+  Measured at `0.0.15`, over `parseX12` + `parseTA1` of what `buildTA1` had just emitted:
+
+  ```text
+  interchangeControlNumber   raw emitted                          parseTA1 read     dot-path read
+  "00000001?"                TA1*00000001??*260601*1200*A*000     "00000001??"      "00000001?"
+  "0000*0001"                TA1*0000?*0001*260601*1200*A*000     "0000?*0001"      "0000*0001"
+  "0000~0001"                TA1*0000?~0001*260601*1200*A*000     "0000?~0001"      "0000~0001"
+  "0000:0001"                TA1*0000?:0001*260601*1200*A*000     "0000?:0001"      "0000:0001"
+  "0000^0001"                TA1*0000?^0001*260601*1200*A*000     "0000?^0001"      "0000^0001"
+  ```
+
+  Every row `warnings: []`. TA1-01 is the reassociation key, so the left column is a key that
+  matches no ISA-13. The right column is the same element. The grounding is that
+  disagreement and nothing else - no clause anyone here has read settles what a TA1 element may
+  contain.
+
+  **What that costs, stated rather than argued away.** A consumer who was applying `unescapeRelease`
+  to `parseTA1`'s output themselves - the remedy this file used to prescribe - now has the library
+  doing it, so **drop the hand-rolled call**. And a value with no `?` in it is unchanged on both
+  surfaces, which is every conformant TA1. **`raw` is untouched and is still the verbatim byte
+  surface**: read `ta1.raw.elements` when you want the bytes.
+
+  **The emit half.** `escapeRelease` early-returns on `""` and `buildTA1` carried a required-field
+  guard for TA1-01 alone, so the other four slots emitted an absent element with `warnings: []`:
+  `interchangeDate: ""` gave `TA1*000000001**1200*A*000`, `interchangeTime: ""` gave
+  `TA1*000000001*260601**A*000`, `ackCode: ""` gave `TA1*000000001*260601*1200**000` and
+  `noteCode: ""` gave `TA1*000000001*260601*1200*R*`. **The item filed two of those four.** Each now
+  draws `AckBuildError` / `X12_ACK_INVALID_SPEC` naming the slot and the spec property and never the
+  value. **No new error code was minted and no warning code moved.** The grounding is again inside
+  the package: `BuildTA1Spec` declares all five properties as required `string`s, `""` is what
+  defeats that at run time, and the in-package answer to an empty required element is uniformly
+  refusal (`patientControlNumber`, `claimId`, `maintenanceTypeCode`, `requestCategoryCode`, the
+  277's `categoryCode`, and TA1-01 itself).
+  - **🛑 It does NOT trim, at any of the five slots.** A whitespace-only element still builds -
+    `TA1*000000001*260601*1200*R* ` is still emitted for `noteCode: " "`. Trimming is a
+    normalisation rule and no source consulted for this package states one, exactly as at TA1-01.
+  - **🛑 It does not narrow what a NON-empty element may contain, and the read half stays lenient.**
+    An out-of-enum `ackCode: "X"` still builds and still reads back as `R` through the documented
+    fail-safe narrow - the same answer an empty one gave. This guard bounds ABSENCE on the emit side
+    and nothing else.
+  - **🛑 Every guard that stood before it keeps its precedence.** `enforceAcceptIsClean` still runs
+    first, so an `ackCode: "A"` with an empty note still reports `X12_TA1_ACCEPT_WITH_NOTE`; TA1-01
+    still draws the control-number refusal; and every wrong-TYPED element still draws the escape
+    helper's refusal, because all five escapes run before any emptiness test. **No spec that was
+    refused before this slice is refused differently by it.**
+  - **No census of other builders' required elements is published here.** This slice measured TA1.
+
+- **🩺 `implementationConventionReference` is POST-`?`-unescape as of this release, in every typed
+  reader that publishes it, and that is a behaviour change on documents whose `ST-03` carries a
+  release escape** (`X12-ST03-READ-NOT-RELEASE-AWARE`). `tx.st.elements` is the ST segment as framed:
+  post-element-split and PRE-unescape. Five public
+  readers were handing one of those strings straight back on the model - `get837Claims`,
+  `get277Status`, `get277CADisposition`, `get278Request` and `get278Response` - so a sender that
+  escaped a delimiter inside `ST-03` got the escape rather than the value it stated. `parse999` has
+  always decoded the identically-named `AK2-03`, and every dot-path read already unescaped; that
+  disagreement inside this package is the whole grounding, and no TR3 clause is claimed. The cells
+  that were run, on the ST-03 element text a sender framed: `A??B` now publishes `A?B`, `A?*B`
+  publishes `A*B`, `A?:B` publishes `A:B`, `A?~B` publishes `A~B`, `A?^B` publishes `A^B`. Every one
+  of those published the framed bytes before.
+  - **🛑 What decides an outcome did NOT move, deliberately.** The 837 variant lookup, the 277 /
+    277CA `transactionType` discriminator and `get277CADisposition`'s admission gate all still key on
+    the RAW element text, so no document changes variant, discriminator or admission because of this
+    entry. That matters because the two can differ: with `componentSeparator: "X"` - a letter is an
+    admissible delimiter - an `ST-03` framed as `005010?X222A1` decodes to `005010X222A1`, an
+    identifier the variant table holds. Keying on the decoded text would make the declaration beat
+    the `SVx` fallback there, which on a document whose only service segment is an `SV2` stops that
+    line decoding and raises `X12_837_SERVICE_LINE_NOT_DECODED`. That is a change to how an already
+    published document decodes a service line rather than a decode fix, and it is **open**, not
+    taken here. **The difference is one-way: no document that resolved or was admitted before stops
+    doing so**, because no identifier any of the three tests is keyed on contains a delimiter or the
+    release character, so raw text equal to one decodes to itself.
+  - **🛑 The published reference can name a guide this reader did NOT resolve to, and nothing warns
+    about the divergence.** On the `componentSeparator: "X"` document above,
+    `submission.implementationConventionReference` reads `005010X222A1`, which the variant table
+    holds, while `submission.variant` is `I` from the `SVx` fallback. **"Nothing warns" is NOT the
+    boundary of it:** on the same delimiters a body with no `SVx` publishes `005010X222A1` with
+    `variant: "unknown"` and raises `X12_837_UNKNOWN_VARIANT`, and a body naming more than one
+    variant publishes it with `variant: "P"` and raises `X12_837_AMBIGUOUS_VARIANT` - each time the
+    code that fired says `ST-03` named no identifier this reader recognises while the model field
+    holds one it does. **`X12_837_UNKNOWN_VARIANT`'s closing pointer at the model is therefore
+    deleted.** **Through `0.0.15` the published value WAS the keyed value, so the model could not
+    disagree with itself. Gate on `variant` / `transactionType`, never on the published reference.**
+  - **🛑 It introduces no normalisation and no new warning.** Nothing is trimmed, case-folded or
+    prefix-matched; a whitespace-only `ST-03` is still published untrimmed. A dangling `?` at the end
+    of the element still raises no `X12_DANGLING_RELEASE_CHAR` on these readers: the sink is a no-op,
+    which is what `getSegmentValue` defaults to and what `parseTA1` and `parse999` do, so every other
+    element these readers decode drops it too. That residual is **unchanged and open.**
+  - **Each reader's own empty / absent mapping is unchanged.** `walk278` still collapses `""` to
+    `undefined`; `get837Claims` and `walk277` still publish `""`. Decoding cannot reach those
+    branches differently, because no non-empty element decodes to `""`.
+  - **`tx.st.elements` is untouched and is still the verbatim framed surface.** If you were applying
+    `unescapeRelease` to `submission.implementationConventionReference` yourself, drop that call.
+
+- **🩺 An EMPTY control number is REFUSED on emit as of this release, where it used to be
+  FABRICATED, and that is a behaviour change for any caller passing one**
+  (`X12-EMPTY-CONTROL-NUMBER-FABRICATED`). Every builder that assembles an ISA zero-pads its control
+  number to the nine characters ASC X12 .5 fixes ISA-13 at. `padControl("1", 9)` answering
+  `"000000001"` is the point of that; `padControl("", 9)` answering `"000000000"` was not, and
+  nothing stood in front of it, so `interchangeControlNumber: ""` produced a frozen, well-formed
+  interchange carrying a nine-digit control number nobody supplied, with `warnings: []` and ISA-13
+  reconciling perfectly against IEA-02. A control number is how an interchange is reconciled and
+  acknowledged, so a fabricated one does not fail: it succeeds against the wrong thing.
+
+  The other control numbers took the same input and were silent in a different way. They reach the
+  wire through the escape helper, which early-returns on `""`, so the required element was lost.
+  **The bytes are not the same in every builder**: `buildInterchange` and `build999` join without
+  trimming, so the element goes out empty, while the seven domain builders share a segment helper
+  that drops a trailing empty element, so the trailer loses it outright. Measured at `0.0.15`,
+  through `buildInterchange` and `build834`:
+
+  ```text
+  buildInterchange  interchangeControlNumber: ""  ISA*…*00501*000000000*0*P*:~ … ~IEA*1*000000000~
+  buildInterchange  groupControlNumber: ""        GS*HC*…*1200**X*005010X222A2~ … ~GE*1*~
+  buildInterchange  transactionSetControlNumber:  ST*837**005010X222A2~ … ~SE*3*~
+  build834          groupControlNumber: ""        GS*BE*…*1200**X*005010X220A1~ … ~GE*1~
+  build834          transactionSetControlNumber:  ST*834**005010X220A1~ … ~SE*21~
+  ```
+
+  Every one of those emitted `warnings: []`, which is the property that holds across both families:
+  no diagnostic on any channel separated an absent control number from a supplied one. The acknowledgment builders carried the same class at the slots
+  where they **echo** the document being acknowledged, which is the whole reason a sender can match
+  an ack to what they sent: `build999` emitted `AK1*HC**005010X222A2~` and `AK2*837*~`, and
+  `buildTA1` emitted `TA1**260601*1200*A*000`. Every one of these now draws that builder's own typed,
+  code-tagged refusal (`X12_BUILD_INVALID_SPEC` and its siblings; `X12_ACK_INVALID_SPEC` on the ack
+  path) naming the slot and the spec property, before anything is emitted. **No new error code was
+  minted and no warning code moved.** What changes is that a build that used to return a document now
+  throws, and that a spec wrong in two ways can now report a different one of the two: see the
+  precedence bullet below, which is the qualifier a draft of this entry left out.
+  - **🛑 The guard does NOT trim, and a whitespace-only control number is
+    still accepted**: `interchangeControlNumber: " "` still emits ISA-13 as `00000000 `, and
+    `buildTA1` does no padding at all, so it emits whatever whitespace it was handed, verbatim. This
+    is a real residual rather than an oversight. Trimming
+    would be a normalisation rule, no source consulted for this package states one, and every
+    empty-required-element guard this one mirrors (`patientControlNumber`, `claimId`,
+    `maintenanceTypeCode`, `requestCategoryCode`, the 277's `categoryCode`) is byte-strict for the
+    same reason. **Validate at your own boundary if your partner can send you blanks.**
+  - **A SHORT control number still zero-pads.** The guard is not "ISA-13 must be nine characters":
+    `interchangeControlNumber: "1"` still emits `000000001`, which is what `padControl` is for.
+  - **🛑 Every guard sits at the envelope-assembly site, so every guard that runs BEFORE it keeps its
+    precedence, and that is the whole claim.** `build835`'s balance equation, `build999`'s AK9
+    counts, `buildTA1`'s accept-must-mean-accept check, the 837's and 277's hierarchy checks and
+    `build834`'s unknown-maintenance-type refusal all still fire ahead of this one. **What it does
+    NOT preserve is an ordering against a defect detected LATER**, during body assembly, which now
+    reports the control-number refusal instead: `build999` with an empty `interchangeControlNumber`
+    and six AK9 syntax error codes threw `X12_ACK_COUNT_MISMATCH` at `0.0.15` and throws
+    `X12_ACK_INVALID_SPEC` now. If you branch on a specific builder error code, that pairing moved.
+
 - **🩺 Which `ST-03` implementation-convention references resolve to an 837 variant CHANGED in this
   release, and some already-published files therefore decode differently** (`X12-VARIANT-ICR-UNGROUNDED`).
   Through `0.0.13` `get837Claims` recognised exactly three references: `005010X222A2`, `005010X223A3`
@@ -133,27 +289,36 @@ model.
     here** - what follows is the routes measured to REACH the regression direction, not a closed
     account of what bypasses the escaper.
 
-    **`buildInterchange` does not escape GS-04, GS-05 or GS-07** (`groupDate`, `groupTime`,
-    `responsibleAgencyCode`). A `groupDate` of `"2026060?"` emits
+    **`buildInterchange` did not escape GS-04, GS-05 or GS-07** (`groupDate`, `groupTime`,
+    `responsibleAgencyCode`) at this release. A `groupDate` of `"2026060?"` emitted
     `GS*HC*SENDER*RECEIVER*2026060?*1200*1*X*005010X222A1`, which its own return value read as nine
-    elements with GS-08 intact through `0.0.14` and reads as **eight** here, GS-08 gone, plus
-    `X12_CONTROL_NUMBER_MISMATCH`.
+    elements with GS-08 intact through `0.0.14` and read as **eight** at `0.0.15`, GS-08 gone, plus
+    `X12_CONTROL_NUMBER_MISMATCH`. **Closed by `X12-INTERCHANGE-GS-EMIT-NOT-RELEASE-AWARE`** - that
+    entry is at the top of this section and it is the one that describes the current tree.
 
   - **An envelope element ending in a literal `?` is a dangling release character and is NOT warned.**
     `X12_DANGLING_RELEASE_CHAR` fires only for an odd run of `?` at the very END of a segment, so a
     mid-segment one reaches no check. That is true of body elements too and is unchanged here.
   - **Values are still RAW, pre-`?`-unescape**, exactly as `X12Segment.elements` has always
-    documented: `gs.elements[2]` on the first row reads `"SEND?*ER"`, not `"SEND*ER"`. Read through
-    `getSegmentValue` if you want the logical value. `elements.join(separator)` therefore still
+    documented: `gs.elements[2]` on the first row reads `"SEND?*ER"`, not `"SEND*ER"`. For the
+    logical value, `unescapeRelease` the element string. `GsSegment` carries no `id`, so
+    `getSegmentValue` does not accept a `gs` (`TS2345`); adding an `id` and taking the dot-path is
+    the other route, and **the two answer different questions**: a bare dot-path splits on the
+    repetition separator and answers repetition 0, so a GS-07 of `"A^B"` reads back `"A"` through it
+    and `"A^B"` through `unescapeRelease`, `warnings: []`.
+    `elements.join(separator)` therefore still
     reproduces the segment byte for byte, which is what `serializeX12` relies on when it substitutes
     a recomputed `SE-01` / `GE-01` / `IEA-01` into a control segment.
   - **🩺 The ISA is deliberately exempt and stays positional.** ASC X12 .5 makes the ISA fixed-width,
     which is what lets the delimiters be recovered from it before anything is parsed, so a `?` in an
     ISA element is content and never an escape. `buildInterchange` states the same rule from the emit
     side: it pads each ISA element and never escapes one.
-  - **A degenerate delimiter set whose element separator IS `?` is unchanged.** `?` cannot both
-    separate and escape, so the splitter falls back to the literal split, the same guard the
-    segment-terminator scanner already carried.
+  - **A degenerate delimiter set whose element separator IS `?` is unchanged by THIS entry.** `?`
+    cannot both separate and escape, so `splitElements` falls back to the literal split, the same
+    guard the segment-terminator scanner already carried. **Read that as the ENVELOPE splitter only:
+    this sentence used to say "the splitter", and `decodeSegment` did NOT carry the guard**, so a
+    degenerate interchange framed its envelope correctly and collapsed every BODY segment. The entry
+    below closes that half.
   - **🩺 This does NOT make an UNESCAPED delimiter safe, and nothing here claims it does.** A bare
     active delimiter in an envelope element still ends that element, because that is what a delimiter
     is; only the sender escaping it is now honoured. `build837`'s
@@ -163,6 +328,185 @@ model.
     any envelope field and will still emit all of them, though it now reports back what it wrote -
     at `0.0.14` it released GS-02 on emit and then answered GS-08 as `"X"` from its own return value.
 
+- **🩺 A BODY segment in an interchange whose ELEMENT SEPARATOR is `?` now frames its elements,
+  where it used to come back as ONE element with an id of `(non-spec)`**
+  (`X12-BODY-DEGENERATE-RELEASE-SEPARATOR`). `detectDelimiters` reads the element separator
+  positionally out of ISA byte 4 and rejects only control characters, whitespace and a non-distinct
+  set, so a sender may declare `?` there, and `buildInterchange` accepted `elementSeparator: "?"`
+  from a caller when this was measured (it refuses now - see the emit-side entry below).
+  `src/parser/envelope.ts` guarded that degenerate set in both of its own splitters;
+  `decodeSegment`, which every BODY segment plus the `ST`, the `SE` and every retained orphan goes
+  through, did not. It split with the release-aware splitter, where a `?` consumes the byte after it,
+  so no split ever happened. Measured through `parseX12` at `0.0.15`:
+
+  ```text
+  ST?837?0001?005010X222A1                 id "(non-spec)", 1 element
+  NM1?85?2?ACME CLINIC?????XX?1234567893   id "(non-spec)", 1 element
+  SE?3?0001                                id "(non-spec)", 1 element
+  warnings: []
+  ```
+
+  - **🩺 The envelope framed correctly the whole time, which is what made it silent.** One group,
+    one transaction, `GE-01`, `IEA-01`, `GS-06`/`GE-02` and `ST-02`/`SE-02` all reconciling, an empty
+    warning array - and a transaction body no reader could see, because every reader in this package
+    dispatches on `seg.id`. A consumer got an empty claim list from a well-formed document.
+  - **🛑 It changes how an already-published document decodes, deliberately, and the tiebreak is
+    CONSISTENCY rather than a spec clause** - the same call the envelope-splitter entry above made.
+    005010 does not transmit a release character at all, so nothing in it says what a `?` means once
+    a sender has declared `?` as structure. **What is NOT the same as that entry: the class is not
+    symmetric.** A one-element segment with an id of `(non-spec)` is not a second reading of
+    `NM1?85?2?ACME CLINIC`; there is no direction in which the old framing was the right one.
+  - **No warning code is added and nothing moves onto a new code.** One is SUBTRACTED, in one place:
+    `X12_DANGLING_RELEASE_CHAR` fired on any degenerate segment ending in an empty last element,
+    because the check keys on a trailing `?`. With `?` as the separator that trailing byte is an
+    empty element, not an unpaired escape, so `PER?IC?NAME?TE?5551234?` is silent now.
+  - **🛑 The guard is per ROLE, and it is a READ-side guard. A `?` REPETITION or COMPONENT separator
+    still does not split, and that is deliberate and measured.** `escapeRelease` writes `??` for a
+    literal `?` whatever role `?` was declared in, so documents this library emitted through `0.0.15`
+    carry `CLM*PATIENT??ACCT*150.00` and `getSegmentValue(clm, "01")` reads `"PATIENT?ACCT"` back out
+    of them. Splitting those two roles literally would re-frame that as two empty components, so it
+    would stop reading a value this library itself wrote. **That reason survives the emit-side
+    refusal below - those documents exist**, which is why the read side did not move with it.
+  - **🟢 CLOSED, in the slice after this one, and WIDER than it was filed
+    (`X12-EMIT-DEGENERATE-RELEASE-DELIMITER`): every builder REFUSES a delimiter set in which any of
+    the four roles is `?`.** The entry as filed named the element separator and one mechanism - a
+    caller VALUE the escape cannot protect, because the protecting `?` is itself the separator. Two
+    things were measured wrong about that:
+    - **The class is FOUR roles, not three.** The segment terminator does the same thing: a released
+      byte inside a value ends the segment early, so a phantom segment appears mid-transaction.
+    - **There is a SECOND mechanism, and it needs no caller value at all.** A builder joins
+      composites with the component separator and repetitions with the repetition separator, so
+      where either is `?` the library's own structural join is emitted as an escape. `build837P` on
+      `componentSeparator: "?"` emitted `SV1-01-2` (the procedure code) and `HI-01-2` (the diagnosis
+      code) fused into the preceding component **on every document, no trigger byte in any value**,
+      `warnings: []`. That is the sharper of the two: a claim is adjudicated on those codes.
+
+    A value-level mitigation was refused for a measured reason rather than a stylistic one: it
+    cannot reach the second mechanism, and _"keep `?` out of your values"_ had already been refuted
+    in this arc for protecting nobody. It refuses specs that built at `0.0.15`, some of which
+    round-tripped through this library's own parser - **that round trip is not the bar**, because
+    ISA-11 and ISA-16 transmit the declared set and a conformant receiver splits on it. Pinned in
+    `test/builder-degenerate-release-delimiter.test.ts` and, per builder, in each build suite.
+
+  - **🩺 A delimiter that is not SHAPED like one is refused on emit too, by every builder.** Each of
+    the four roles must be a **string of exactly one visible character**, and the four must be
+    **mutually distinct**. That is not a rule invented for emit: it is the predicate
+    `detectDelimiters` already applies to an inbound ISA, where failing it is the Tier-3 fatal
+    `X12_INVALID_DELIMITERS`. A builder composing a document its own parser refuses to read was
+    disagreeing with itself. Nothing is trimmed, coerced or substituted - the set is refused.
+
+    Three things it closed, and they are not one defect. A **multi-character** delimiter built with
+    `warnings: []`: a `segmentTerminator` of `"~~"` put phantom segments on the model that `SE-01`
+    never counted, and a `componentSeparator` of `":~"` read back through a well-formed ISA while the
+    builder's own terminator became an uncounted empty segment. **No claim is made about which roles
+    were affected**; declare one character per role. A **non-string** delimiter was coerced by the join but not by the
+    escape, so the document framed on a byte no element value was protected from: an 837 with
+    `componentSeparator: 1` read `SV1-01-2` back as `992` rather than the procedure code `99213`,
+    `warnings: []`. And **`buildTA1` had no net at all** - it is the one builder with no trailing
+    `parseX12`, so EVERY role and EVERY shape was silent there: `elementSeparator: ""` returned
+    `TA10000000012606011200A000`, the reassociation key and the disposition fused into one blob, and
+    `elementSeparator: "||"` returned `TA1||000000001||260601||1200||A||000`, which inside an ISA
+    reads back with `TA1-01` empty and `ackCode: "R"` - an Accept emitted as a Reject.
+
+    **🛑 Two things change for a caller.** A spec that failed at base with an `X12ParseError` /
+    `X12_INVALID_DELIMITERS` escaping out of the `build*` call now refuses earlier with that
+    builder's own typed error and its existing code, so a consumer catching the parse class stops
+    catching and one catching the build class starts; no code is minted. And a
+    `segmentTerminator` of `"~\r\n"` - asking for line-broken output - **built with `warnings: []`
+    before and is refused now** (no count of such shapes is published; that is not the only one).
+    The check also runs **before** the control-number guards, so a spec that is mis-shaped _and_
+    carries an empty control number now reports the delimiter refusal rather than the control-number
+    one, on the same code. A message moves; no code does. It never did what it looked like it did: `parseX12` tolerates CR/LF
+    between segments, so the model recorded `~` and `serializeX12` emitted no line breaks. Reading a
+    file that is written that way is unaffected; only declaring it on emit is.
+
+  - **🩺 `PRE-EXISTING` and NOT closed by that refusal: it is a UTF-16 CODE-UNIT rule, not a byte
+    rule.** A character that is one code unit but several bytes on the wire satisfies it and still
+    displaces every ISA position after it, so `componentSeparator: "\u00a7"` builds with
+    `warnings: []` and a byte-oriented receiver reads ISA-16 as `0xC2` and the terminator as `0xA7`.
+    The smart quote `"\u2019"` a companion-guide PDF gives you instead of `'` does the same.
+    Disclosed rather than guarded: the read side counts code units too (`charAt`), so moving one side
+    alone would put emit and read back out of step, which is exactly what that refusal exists to
+    prevent. **Declare delimiters from the basic single-byte set.**
+
+  - **🩺 PRE-EXISTING and NOT closed here: on a degenerate set a `?~` still swallows the segment
+    terminator.** `findUnescapedTerminator` guards its own role only, so with `?` as the element
+    separator a segment that ends in an EMPTY LAST ELEMENT puts a `?` immediately before the
+    terminator and the scanner reads it as an escape: `PER?IC?NAME?TE?5551234?EX?~SE?3?0001~` frames
+    as ONE segment and raises `X12_MISSING_SE`. This slice does not touch framing. But **the READ of
+    that merged blob did move, so do not take "framing is untouched" as "nothing about this residual
+    moved"**: at `0.0.15` the merge produced one `(non-spec)` element no walker looked at, and here
+    it frames, so `~SE` and the SE's own control number land in `PER`'s communication-number slots.
+    `X12_MISSING_SE` still fires, so it is not silent. Both are pinned in
+    `test/parser-segment-degenerate-release-separator.test.ts` so they cannot move unnoticed.
+  - **Values are still RAW, pre-`?`-unescape**, and `elements.join(separator)` still reproduces the
+    segment byte for byte, so `serializeX12`'s count substitution and the byte-exact round trip are
+    unaffected. Both are pinned.
+  - **The ISA is untouched and stays positional**, for the reason the envelope-splitter entry above
+    gives: it is fixed-width, which is what lets the delimiters be recovered from it at all.
+
+- **🩺 `buildInterchange` now RELEASES GS-04, GS-05 and GS-07, so the interchange it hands back
+  reports the values you passed, and the bytes it writes for such a value CHANGED**
+  (`X12-INTERCHANGE-GS-EMIT-NOT-RELEASE-AWARE`). Through `0.0.15` it mapped its release escaper over
+  GS-01, GS-02, GS-03, GS-06 and GS-08 and wrote `groupDate` (GS-04), `groupTime` (GS-05) and
+  `responsibleAgencyCode` (GS-07) raw. It returns `parseX12` of the bytes it just wrote, so a value
+  carrying an active delimiter in one of those three took a slot of its own and shifted every element
+  after it down one, inside a single call. Measured on one group with
+  `versionRelease: "005010X222A2"` and `groupControlNumber: "1"`:
+
+  | spec field                     | read GS-06 | read GS-08 | warnings                                                |
+  | ------------------------------ | ---------- | ---------- | ------------------------------------------------------- |
+  | `groupDate: "2026*0601"`       | `"1200"`   | `"X"`      | `X12_CONTROL_NUMBER_MISMATCH`                           |
+  | `groupTime: "12*00"`           | `"00"`     | `"X"`      | `X12_CONTROL_NUMBER_MISMATCH`                           |
+  | `responsibleAgencyCode: "X*Y"` | `"1"`      | `"Y"`      | none                                                    |
+  | `groupTime: "12~00"`           | absent     | absent     | `X12_UNEXPECTED_SEGMENT`, `X12_CONTROL_NUMBER_MISMATCH` |
+  | `groupDate: "20260601?"`       | `"X"`      | absent     | `X12_CONTROL_NUMBER_MISMATCH`                           |
+
+  **🩺 The `responsibleAgencyCode` row is the one to know about, because nothing was raised on any
+  channel.** GS-06 kept its own slot, so it still reconciled against GE-02 and no control-number
+  warning fired; what moved was GS-08, the version / release / industry identifier code. All five
+  rows now read the values the caller passed, with an empty warning array.
+  - **🛑 It changes bytes, and the bound is the same one the two entries below carry.** A value
+    containing none of the four delimiters and no `?` is emitted byte-for-byte as before, which is
+    every conformant GS-04 / GS-05 / GS-07. **Read the property rather than a direction list:** the
+    interchange the call returns now reports the values you passed, where before it reported whatever
+    the shift left in each slot. **What is narrower here than in the two entries below: no reader
+    moved.** An inbound document from a trading partner decodes exactly as it did at `0.0.15`; what
+    changed is what this library emits.
+  - **Read the delimiter set by ROLE, never by byte.** `InterchangeSpec` lets you declare all four,
+    so which BYTES shift is a property of the set you declared: with `elementSeparator: "|"` it was a
+    GS-07 of `"X|Y"` that took GS-08's slot and `"X*Y"` that was inert. **Only the element separator
+    and the segment terminator ever shifted the segment's own framing, plus a `?` immediately before
+    the element separator.** The **repetition** and **component** separators moved the dot-path
+    reader instead, and releasing them is a **gain** there: the
+    composite read `"07-1"` answered `"X"` for `"X:Y"`. **The measured cost is a mid-string `?`,
+    and only on the surfaces documented as raw** - `gs.elements[4]` reads `"2026??0601"` where it
+    read `"2026?0601"`, while the dot-path read of that value unescapes and is unchanged. No total is
+    published: that is what was measured, not a closed account.
+  - **A caller who was pre-releasing these values themselves is now escaping twice.** `"2026?*0601"`
+    in gives `2026???*0601` out and a dot-path read of `"2026?*0601"` where it read `"2026*0601"`.
+    Drop the hand-rolled escape.
+  - **A wrong-typed GS element now names its slot.** The type check runs over the unescaped parts, so
+    a numeric `groupDate` still refuses with `buildInterchange: "GS"-04 must be a string` rather than
+    degrading to the builder-named message the escaper alone would give. The five slots that already
+    escaped gained the slot name with it. **`null` and `undefined` in these three fields are ABSENT,
+    not refused** - each resolves through a default before either guard sees it.
+  - **A LITERAL segment id this library writes is never escaped, and that is a rule rather than an
+    omission.** `esc` releases against the delimiter set the CALLER declared, and a
+    `componentSeparator` of `"S"` is admissible, so escaping element 0 would turn the literal `"GS"`
+    into `G?S` and the group header would stop being a `GS`. `GE`, `ST`, `SE` and `IEA` already
+    followed that rule. **Read "literal" strictly, and this one is `PRE-EXISTING` rather than
+    anything this release changed:** a `SegmentSpec` body segment is `[segmentId, ...elements]`
+    supplied wholesale, `buildInterchange` has released that caller-supplied id since before this
+    release, and `SegmentSpec`'s JSDoc says it is emitted verbatim. The two disagree. It is noisy
+    rather than silent - a `?`-prefixed id is rejected by the envelope walker as an orphan with
+    `X12_UNEXPECTED_SEGMENT` - and which side is wrong is a decision, so it is recorded rather than
+    changed here.
+  - **What this does NOT close.** `buildInterchange`'s IEA-02 does not go through the escaper: it is
+    padded and has to stay byte-equal to the fixed-width ISA-13 it reconciles against, so that is a
+    decision of its own. The ISA fixed-width slots are still outside both guards. And an unescaped
+    active delimiter is still not safe anywhere, because that is what a delimiter is.
+
 - **🩺 `buildTA1` now RELEASES its five caller-supplied elements, so an Accept acknowledgment this
   library emits no longer reads back as a Reject, and the bytes it writes for such a value CHANGED**
   (`X12-TA1-EMIT-NOT-RELEASE-AWARE`). Through `0.0.14` `buildTA1` joined the five values with the
@@ -211,23 +555,26 @@ model.
     `"0000^0001"`, silently truncating the reassociation key to the first repetition, and answers
     `"0000^0001"` now; the composite read `"01-1"` answered `"0000"` for `"0000:0001"` and answers
     the whole value now. **The measured pure cost is a mid-string `?`, and only on the surfaces
-    documented as raw**: `raw`, `elements` and `parseTA1`'s fields read `"0000??0001"` where they
-    read `"0000?0001"`, while every dot-path read unescapes and answered `"0000?0001"` on both.
+    documented as raw**: `raw` and `elements` read `"0000??0001"` where they read `"0000?0001"`,
+    while every dot-path read unescapes and answered `"0000?0001"` on both.
     No total is published: that is what was measured, not a closed account. (`getSegmentValue`
     takes an `X12Segment` and `Ta1Segment` carries no `id`, so add one to read a TA1 through it.)
+    **🩺 A clause naming `parseTA1`'s fields as a third such surface stood here and is DELETED, not
+    reworded** - `X12-TA1-RESIDUALS` made those fields post-unescape, so it is measured false.
   - **A caller who was hand-rolling the escape** (the remedy this file named while the defect was
     open) regresses on both kinds of surface: `"00000001??"` in, `TA1*00000001????*…` out, and
     `getSegmentValue` answering `"00000001??"` where it answered `"00000001?"`. The framing and the
     disposition stay correct, but **drop the hand-rolled escape.**
-  - **An EMPTY control number is not refused and never was.** `escapeRelease` early-returns on `""`
-    and `buildTA1` carries no required-field guard, so `interchangeControlNumber: ""` emits
-    `TA1**260601*1200*A*000` with `warnings: []`, here and at every earlier release. Only a
-    NON-string refuses. Unchanged and tracked as its own item.
-  - **🩺 The READ half did not move. `parseTA1` still reads elements RAW, pre-`?`-unescape**, exactly
-    as `X12Segment.elements` has always documented, so a control number of `"00000001?"` now reads
-    back as `"00000001??"` rather than as `"00000001?*260601"`. The disposition is correct where it
-    was inverted; apply `unescapeRelease` if you need the value rather than the bytes. Unescaping on
-    the read side would move every TA1 a consumer already reads and is not done here.
+  - **An EMPTY control number was not refused by this slice, and is refused by the NEXT one.**
+    `escapeRelease` early-returns on `""` and `buildTA1` carried no required-field guard, so
+    `interchangeControlNumber: ""` emitted `TA1**260601*1200*A*000` with `warnings: []`, here and at
+    every earlier release. `X12-EMPTY-CONTROL-NUMBER-FABRICATED` closed it across every builder; see
+    the entry at the top of this file, including the whitespace-only residual it leaves open.
+  - **🩺 The READ half did not move IN THIS SLICE, and `X12-TA1-RESIDUALS` is the one that moved
+    it** - see the entry at the top of this file. A control number of `"00000001?"` read back as
+    `"00000001?*260601"` before this slice and as `"00000001??"` after it; the clause that stood
+    here telling callers to apply `unescapeRelease` themselves is **deleted, not reworded**, because
+    the library now does it.
   - **The release is scoped to the delimiter set the CALLER states.** `BuildTA1Options` gained
     `repetitionSeparator` / `componentSeparator` / `segmentTerminator` beside the existing
     `elementSeparator`, the same four `build999` already takes, and they exist for escaping and
@@ -245,8 +592,9 @@ model.
     **No existing refusal moves code:** `ackCode` `"A"` with a non-`000` note still reports
     `X12_TA1_ACCEPT_WITH_NOTE` and still runs first.
   - **What this does NOT close.** `buildTA1` still uses no segment joiner, so its refusal names the
-    builder and never the slot; `buildInterchange` still does not escape GS-04 / GS-05 / GS-07; and
-    an unescaped active delimiter is still not safe anywhere, because that is what a delimiter is.
+    builder and never the slot; `buildInterchange` did not escape GS-04 / GS-05 / GS-07 at this
+    release, which `X12-INTERCHANGE-GS-EMIT-NOT-RELEASE-AWARE` then closed; and an unescaped active
+    delimiter is still not safe anywhere, because that is what a delimiter is.
 
 - **🩺 BREAKING for `build277` callers: a 277 service line now REQUIRES `unitsOfService`, because
   SVC-07 is a required element in `005010X212` and this library was not emitting it at all**
@@ -1016,14 +1364,10 @@ N-char spec limit` refusal, one per emitting module, where the branch fires **be
   the array guard's primitive arm. If you were reading a value back out of one of those messages, that
   is a behaviour change.
 
-  **Two things that sentence does NOT say, both deliberate.** The array guard still reports the
+  **What that sentence does NOT say, and it is deliberate.** The array guard still reports the
   `length` and the class tag of a forged array-like, bounded through the same renderer: those describe
   the SHAPE you forged rather than the contents of a document element, and they are the whole
-  diagnostic for `{ length: "9".repeat(120000) }`. And only the segment-join guard names the SLOT
-  alongside the type (`build999: "AK9"-01 must be a string, ...`), because it holds the whole segment;
-  the escape-helper and `X12Decimal` guards name the **builder**, so on those two the value used to
-  stand in for a locator and now nothing does. That is a real diagnostic cost, and it is written down
-  rather than hidden.
+  diagnostic for `{ length: "9".repeat(120000) }`.
 
 - **`defineProfile()` refusals are bounded on the same terms, since `0.0.6`.** `X12ProfileError.message`
   used to interpolate your profile name, quirk id, effect, fixture path and expected-warning codes

package/README.md

@@ -47,7 +47,7 @@ That's the pitch: no schema upload, no spec knowledge. The parser accepts vendor
 - **Postel's Law**: a lenient parser (deviations → warnings with a stable code + positional context) and a conservative serializer. `serializeX12` is byte-faithful **for the segments on the model** by default: each comes back verbatim, including element padding, composites, and `?`-release escapes. **`serialize(parse(s)) === s` is not guaranteed in general.** Six constructs are known not to survive: line breaks between segments (any run of CR / LF between segments is absorbed at parse, so a pretty-printed or double-spaced file emits compact), a doubled terminator outside a transaction, a missing final terminator (the emit supplies one), post-IEA `trailingBytes` (re-joined, not verbatim), a TA1 that followed a functional group (emitted right after the ISA, so it is **reordered**, though nothing is lost), and a segment whose first element is empty outside a transaction (skipped entirely, with no warning at all). A **segment outside a transaction is not on that list**: it is reported as `X12_UNEXPECTED_SEGMENT`, kept on the model at `ix.orphanSegments` with a structural `anchor`, and re-emitted at that anchor, so the segment, its value and its warning all survive the round trip - placement is by the anchor and never by `segmentIndex`, which indexes the input stream the emit does not follow. The last five break the round trip on inputs with no line breaks at all, so do not treat "no line breaks" as sufficient; five of the six are silent, so a clean warnings list does not mean byte-exact either. Measured across this repo's 56 fixtures: every emit is a fixed point and re-parses to an identical model with an identical warning stream, the 14 with no line breaks return byte-identical, and the other 42 differ by line breaks and nothing else. See [Line endings between segments](./docs-content/spec-notes-envelope.md). `{ specClean: true }` reconciles the envelope, and `{ specClean: true, recomputeCounts: true }` also emits the corrected counts (`recomputeCounts` does nothing on its own). A mismatch is always warned, never silently corrected. Only **4 structural failures** are ever fatal.
 - **Money is exact, and never invented**: every monetary/percent/quantity field decodes as `X12Decimal` (string-backed, BigInt arithmetic), and the library **never `parseFloat`s** an EDI amount. **No slot holds an amount this library did not decode.** Where a reader used to substitute `X12Decimal.ZERO` the slot is now `X12Decimal | undefined` and reads `undefined`, so "the sender stated zero" and "the sender stated nothing" are different readings; through `0.0.12` they were the same `0`. That is a rule about the substitution, not a census of the model: some rows are dropped whole instead, which is a different and pre-existing shape, and no total is published here. Read [KNOWN-LIMITATIONS.md](./KNOWN-LIMITATIONS.md).
 - **Safety-critical fidelity**: TRN reassociation traces, 835 balance invariants, 837 HL hierarchy integrity, 834 maintenance types, and 278 certification actions are preserved **verbatim** and never inferred; ambiguity yields a warning or a typed refusal, never a confident wrong answer.
-- **PHI-disciplined**: synthetic-only fixtures, a PHI commit-gate, and a warning `message` that is a **lookup into a frozen registry**, not something built from your document. No warning factory in the library takes a value parameter, so no element can reach a diagnostic: the code and `position` say what and where, and the bytes stay on the model. `ALL_WARNING_MESSAGES` is exported so you can assert it. **Builder refusals are a different, and deliberately weaker, surface:** twenty-four refusal sites across ten builder modules name a value you passed in, so you can see which control number, count or code was refused. **What they will never name is a `claimId`, a member id, a member name, a trace or a diagnosis code** - a guarantee that held for the refusal templates and, until the release after `0.0.10`, did not hold for the shared type guards underneath them: a JSON-driven caller who sent a number where the types say string got `a number ("900412345678")` back, bounded but not redacted, from a guard standing on every element of every builder. Those guards report the type now and never the value. Only the segment-join guard names the slot as well; the `esc` and `X12Decimal` guards name the builder, which is a diagnostic cost stated rather than hidden. The array guard's primitive arm is redacted with them, but it still reports the `length` and the class tag of a forged array-like, bounded, because those describe the shape you forged rather than the contents of a document element. Each goes through `renderCallerValue`, capping the rendered **fragment** at `BUILD_REFUSAL_VALUE_MAX_RENDERED` (90 characters); all three names are exported so you can assert the ceiling. The whole `message` is that plus the site's own fixed text, so it is bounded by a constant but a larger one: a 120,000-character control number gave a 120,066-character `X12BuildError.message` before this and gives 150 now. That is robustness, not redaction: the value is one you supplied and bounding it hides nothing from you. It is also not escaped, and on the **ack** path it is not always strictly your own, since `build999`'s AK2-02 and `buildTA1` echo an inbound document's control numbers by design. Log `err.code`, not `err.message`, from a builder. **`defineProfile()` is bounded on the same terms since `0.0.6`** (twelve refusal sites, twenty-three caller values; the worst message measured **360,181 characters** before and **431** now, both at the `fixture` refusal, which names three caller values; the ceiling for that site is 443 and the suite asserts every site under 500; `X12ProfileError.profileName` is deliberately left unbounded so it still matches the name you passed). **And a forged non-array in a builder spec now refuses instead of hanging:** every indexed loop takes its bound from a checked array, so `{ length: "9".repeat(120000) }` draws a typed refusal rather than coercing to `Infinity` and looping forever. A few `for…of` reads still throw an untyped `TypeError` instead; both are in [KNOWN-LIMITATIONS.md](./KNOWN-LIMITATIONS.md). **The one deliberate exception:** `X12ParseError.snippet` on the four Tier-3 structural fatals is a bounded (≤ 64 character) copy of the start of the input, so on real traffic it can carry PHI. The library does not redact it. Redact at your call site, or log `err.code` and `err.position` instead. See [Keeping PHI out of logs](./docs-content/troubleshooting.md).
+- **PHI-disciplined**: synthetic-only fixtures, a PHI commit-gate, and a warning `message` that is a **lookup into a frozen registry**, not something built from your document. No warning factory in the library takes a value parameter, so no element can reach a diagnostic: the code and `position` say what and where, and the bytes stay on the model. `ALL_WARNING_MESSAGES` is exported so you can assert it. **Builder refusals are a different, and deliberately weaker, surface:** twenty-four refusal sites across ten builder modules name a value you passed in, so you can see which control number, count or code was refused. **What they will never name is a `claimId`, a member id, a member name, a trace or a diagnosis code** - a guarantee that held for the refusal templates and, until the release after `0.0.10`, did not hold for the shared type guards underneath them: a JSON-driven caller who sent a number where the types say string got `a number ("900412345678")` back, bounded but not redacted, from a guard standing on every element of every builder. Those guards report the type now and never the value. The array guard's primitive arm is redacted with them, but it still reports the `length` and the class tag of a forged array-like, bounded, because those describe the shape you forged rather than the contents of a document element. Each goes through `renderCallerValue`, capping the rendered **fragment** at `BUILD_REFUSAL_VALUE_MAX_RENDERED` (90 characters); all three names are exported so you can assert the ceiling. The whole `message` is that plus the site's own fixed text, so it is bounded by a constant but a larger one: a 120,000-character control number gave a 120,066-character `X12BuildError.message` before this and gives 150 now. That is robustness, not redaction: the value is one you supplied and bounding it hides nothing from you. It is also not escaped, and on the **ack** path it is not always strictly your own, since `build999`'s AK2-02 and `buildTA1` echo an inbound document's control numbers by design. Log `err.code`, not `err.message`, from a builder. **`defineProfile()` is bounded on the same terms since `0.0.6`** (twelve refusal sites, twenty-three caller values; the worst message measured **360,181 characters** before and **431** now, both at the `fixture` refusal, which names three caller values; the ceiling for that site is 443 and the suite asserts every site under 500; `X12ProfileError.profileName` is deliberately left unbounded so it still matches the name you passed). **And a forged non-array in a builder spec now refuses instead of hanging:** every indexed loop takes its bound from a checked array, so `{ length: "9".repeat(120000) }` draws a typed refusal rather than coercing to `Infinity` and looping forever. A few `for…of` reads still throw an untyped `TypeError` instead; both are in [KNOWN-LIMITATIONS.md](./KNOWN-LIMITATIONS.md). **The one deliberate exception:** `X12ParseError.snippet` on the four Tier-3 structural fatals is a bounded (≤ 64 character) copy of the start of the input, so on real traffic it can carry PHI. The library does not redact it. Redact at your call site, or log `err.code` and `err.position` instead. See [Keeping PHI out of logs](./docs-content/troubleshooting.md).
 
 See the [**Cookbook**](./docs-content/cookbook.md) for task-oriented recipes (post an 835, route 277CA rejections, round-trip a 271, walk an 837, read a 999) and [**KNOWN-LIMITATIONS.md**](./KNOWN-LIMITATIONS.md) for the honest do-not-over-trust list.