@cosyte/x12 0.0.14 → 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`
@@ -53,14 +209,392 @@ model.
   - **The set is not claimed exhaustive and no count of it is published**, here or in any warning
     message. Both variant messages named the three old keys literally and were wrong the moment the
     table was corrected, so neither enumerates the set any more.
-  - **🩺 OPEN, and NOT fixed here: the EMIT side still stamps the old three.** `build837P` /
-    `build837I` / `build837D` write `005010X222A2` / `005010X223A3` / `005010X224A2` into ST-03 and
-    GS-08, and **a caller cannot override the value**. Two of those are not what the companion guides
-    above require, so **a trading partner that requires `005010X222A1` or `005010X223A2` will reject
-    an 837 this builder emits.** Deliberately not re-stamped: which published guide identifier a
-    partner accepts is a partner fact rather than a spec fact, and changing bytes this library
-    already emitted would break the partners it works with today. The remedy is a caller-supplied
-    override, which is a public-surface addition and its own slice.
+  - **🩺 CLOSED, in the slice after this one: the emit side takes a caller override**
+    (`X12-837-EMIT-IDENTIFIER-FIXED`). `build837P` / `build837I` / `build837D` still DEFAULT to
+    `005010X222A2` / `005010X223A3` / `005010X224A2` in ST-03 and GS-08, and
+    **`Build837EnvelopeSpec.implementationConventionReference` now states another** - one value,
+    both elements. Two of the defaults are not what the companion guides above require, so a partner
+    asking for `005010X222A1` or `005010X223A2` used to reject what this builder emitted and there
+    was no way to comply. **The default itself was deliberately NOT re-stamped:** which published
+    guide identifier a partner accepts is a partner fact rather than a spec fact, and changing bytes
+    this library already emitted would break the partners it works with today.
+    - **What the override refuses of its own, all `X12_837_BUILD_INVALID_SPEC`, and none of it
+      echoes your value back:** an empty reference (a trailing empty element is not emitted, so it
+      would delete ST-03 and GS-08 rather than send them empty); one carrying an active delimiter or
+      the release character; and one this library's own reader resolves to a **different** 837
+      variant, which would emit a file declaring one variant and carrying another's service
+      segments. **No total is published**, because those sit on top of the element-type guard every
+      string slot in every builder already has, which refuses a non-string with the same code. Take
+      the list as what this field adds, never as a closed account of everything that can refuse.
+    - **🩺 It bounds the VALUE, not the length, and the two elements' maxima differ.** GS-08 is data
+      element 480 (`AN 1/12`) and ST-03 is element 1705 (`AN 1/35`), so "one value, both elements"
+      is true of the bytes and not of what each element may legally hold. Nothing here refuses an
+      over-length reference, in line with every other envelope field this library takes.
+    - **A reference outside the read table is emitted as given, deliberately.** The published-errata
+      set is not provably exhaustive, so refusing an unrecognised identifier would claim an
+      exhaustiveness nothing here supports. The honest cost, pinned as a test: this library's own
+      reader falls back to the `SVx` scan on such a file, exactly as it does for any unrecognised
+      ST-03.
+
+- **🩺 A `?` immediately before the element separator inside an envelope segment now frames as ONE
+  element, and that is a SYMMETRIC behaviour change on already-published decoding**
+  (`X12-ENVELOPE-SPLITTER-NOT-RELEASE-AWARE`).
+  Through `0.0.14` the envelope segments' element splitter was a plain `String.prototype.split`, so a
+  released element separator (`?*`) still ended the element and SHIFTED every element after it down a
+  slot. It was a property of the whole envelope segment and never of one element, so the element a
+  reader went looking for came back out of its neighbour's slot. Measured then, through `parseX12`:
+
+  ```text
+  GS*HC*S*R*20260601*1200*1*X*005010?*X222A1~   ten elements, GS-08 read "005010?"
+  applicationSenderCode "SEND*ER"               GS-08 read "X", the GS-07 agency code
+  groupControlNumber    "1*2"                   GS-08 read "X";  warnings: []
+  transactionSetControlNumber "00*01"           ST-03 read "01"; warnings: []
+  CLM*PT?*ACCT*150.00~                          three elements, CLM-01 held "PT?*ACCT"
+  ```
+
+  The body element was the control and was always correct. `splitElements` now honours the release
+  character exactly as `decodeSegment` and the segment-terminator scanner already did, so every row
+  above reads one element fewer and the value lands in its own slot.
+  - **🛑 READ THE CHANGE AS SYMMETRIC. IT IS NOT ONLY A CORRECTION.** A `?` before the separator has
+    two readings and 005010 does not transmit which the sender meant. Where the sender **escaped** a
+    delimiter, the release before this one framed it wrongly and this one frames it correctly: a
+    correction, the rows above. Where the sender sent a **literal `?`** as the element's last byte,
+    the release before this one framed it correctly and this one merges the element with its
+    successor, so **the segment loses its LAST element**: a regression.
+    `GS*HC*SUB1*RCV?*20260601*1200*000000123*X*005010X222A1~` read nine entries through `0.0.14` and
+    reads **eight** here, with GS-06 answering `"X"` and GS-08 gone.
+  - **🛑 What this changes for a consumer.** One input class decodes differently: an envelope segment
+    (`GS`, `GE`, `ST`, `SE`, `IEA`, `TA1`) carrying a `?` immediately before the element separator.
+    Every other release sequence in an envelope element (`??`, `?:`, `?^`, `?~`, `?A`) framed
+    identically before and after and still does. **No warning code is added, and
+    `X12_CONTROL_NUMBER_MISMATCH` moves in BOTH DIRECTIONS.** Where the old shift displaced a control
+    number it STOPS firing, so a consumer that rejects on that code will now **accept** such a
+    document; where a literal `?` newly displaces one it STARTS firing, so that same consumer will
+    now **reject** a document `0.0.14` accepted. A genuine mismatch still raises it.
+  - **🩺 The regression direction reaches an 837's variant and its money, by one route.** `ST-03` is
+    what decides the 837 variant, so an `ST-02` ending in a literal `?` destroys `ST-03` and the
+    document falls back to the `SVx` scan. An 837 declaring `005010X222A1` whose only service segment
+    is an `SV2` read `variant` `"P"`, `charge` `undefined` and `X12_837_SERVICE_LINE_NOT_DECODED`
+    through `0.0.14`, and here reads `variant` `"I"` with `charge` `150.00` and that warning silent.
+    **A warned non-decode becomes a decoded amount.** If you receive envelope elements that may end
+    in a literal `?`, re-check any routing driven off `submission.variant`.
+  - **Why it was taken anyway, and it is CONSISTENCY rather than a spec clause.** The two readings
+    are mutually exclusive and nothing in 005010 picks between them. `decodeSegment` has read BODY
+    elements the escape-wins way on **every released version** (`REF*EA*RCV?*NEXT` has always been
+    two elements). The envelope now obeys the one rule the rest of the package already obeyed, and
+    `buildInterchange` stops disagreeing with itself: at `0.0.14` it released GS-02 on emit and then
+    answered GS-08 as `"X"` from its own return value.
+  - **🩺 THE EXPOSURE IS NOT INBOUND BYTES ONLY.** Envelope slots routed through the builders'
+    release escaper are safe. **Not every emit slot is routed through it, and no total is published
+    here** - what follows is the routes measured to REACH the regression direction, not a closed
+    account of what bypasses the escaper.
+
+    **`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 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"`. 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 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
+    `implementationConventionReference` still REFUSES a value carrying an active delimiter or the
+    release character, and is deliberately not relaxed on the strength of this fix: a partner's
+    parser is not obliged to be release-aware either. `buildInterchange` applies no domain guard to
+    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
+  element separator and escaped none of them, so a value carrying an active delimiter took a slot of
+  its own and shifted every element after it down one. TA1-04 is the disposition and TA1-05 the note,
+  and `parseTA1` narrows an out-of-enum TA1-04 to `R`. Measured with `parseX12` + `parseTA1` over
+  `ISA … <what buildTA1 returned> … IEA`, `ackCode` `"A"` and `noteCode` `"000"` throughout:
+
+  | `interchangeControlNumber` | emitted at `0.0.14`               | read `ackCode` | read TA1-01          | warnings                 |
+  | -------------------------- | --------------------------------- | -------------- | -------------------- | ------------------------ |
+  | `"000000001"`              | `TA1*000000001*260601*1200*A*000` | `"A"`          | `"000000001"`        | none                     |
+  | `"00000001?"`              | `TA1*00000001?*260601*1200*A*000` | `"R"`          | `"00000001?*260601"` | none                     |
+  | `"0000*0001"`              | `TA1*0000*0001*260601*1200*A*000` | `"R"`          | `"0000"`             | none                     |
+  | `"0000~0001"`              | `TA1*0000~0001*260601*1200*A*000` | `"R"`          | `"0000"`             | `X12_UNEXPECTED_SEGMENT` |
+
+  **An Accept acknowledgment this library emitted read back as a Reject, on the element that
+  reassociates it, with nothing raised on any channel.** The `*` and `~` rows did that on every
+  released version; the `?` row is the one the envelope-splitter entry above opened. **🩺 The inverse
+  exists and is the less safe direction:** the read narrows an out-of-enum TA1-04 to `R`, so a
+  well-typed shift always lands on Reject, but `noteCode` is checked by the type system and by
+  nothing at run time, so a `noteCode` of literally `"A"` shifted onto TA1-04 and made a **Reject
+  read back as an Accept** - and a sender who reads an Accept does not resubmit. All four now read
+  back the disposition that was emitted.
+  - **The grounding is inside this package, not in a spec clause**, the same tiebreak the
+    envelope-splitter entry records. `buildTA1` emitted bytes that this package's own reader decoded
+    into a different disposition than the caller asked for, while every other builder already
+    released the same class of element through the same helper. Nobody here has read a clause that
+    settles it, and nothing above claims one.
+  - **🛑 It changes bytes this library already put on the wire, which is the cost.** A value
+    containing none of the four delimiters and no `?` is emitted byte-for-byte as before, and that
+    is every conformant TA1: TA1-01 echoes ISA-13, TA1-02 / TA1-03 echo ISA-09 / ISA-10, and
+    TA1-04 / TA1-05 are code list values. A value containing one is now released.
+  - **🛑 No warning code is added and no case moves onto a new code, but the consumer predicate
+    MOVES IN BOTH DIRECTIONS.** `parseTA1` of a `buildTA1` output now reports the disposition and
+    note the caller passed; before, it reported whatever element the shift left in TA1-04, which
+    could be the caller's, a coincidental in-enum value, or an out-of-enum one narrowed to `"R"`. So
+    `ackCode === "R"` **stops** firing where an Accept had been shifted onto it, and **starts**
+    firing where a Reject had been shifted off it: `interchangeTime: "12*A"` with `ackCode: "R"`
+    read `"A"` before and reads `"R"` now, with every field a valid member of its union.
+    `ackCode === "A"` moves the same two ways. What is one-directional is the safety, which is a
+    different statement: nothing now reports a disposition the caller did not ask for.
+  - **What releasing the REST of the set costs, and where it does not cost.** Only `*`, `~` and a
+    `?` immediately before the separator ever shifted the segment's own element framing. **`^` and
+    `:` moved the dot-path reader instead, and releasing them is a gain there:**
+    `getSegmentValue(ta1, "01")` answered `"0000"` through `0.0.14` for a control number of
+    `"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` 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 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
+    nothing else - `buildTA1` still emits no terminator. Escaping against a guessed set is a value
+    corruption rather than a safe default: `unescapeRelease` preserves `?X` verbatim for any `X`
+    outside the declared set, so a value released against the wrong delimiter comes back carrying a
+    stray `?`. **The defaults are the cosyte archetype and this function cannot verify them** - if
+    you embed a TA1 in an envelope that declares different separators, state them.
+  - **A non-string element now REFUSES** with `AckBuildError` / `X12_ACK_INVALID_SPEC`, and that is a
+    prerequisite rather than a bonus. Releasing a value means routing it through the escape helper,
+    and the bare `escapeRelease` underneath it returns its empty accumulator for a `number`, so
+    escaping without the type check would have replaced a shifted TA1-01 with a vanished one. A
+    numeric control number emitted `TA1*12345*…` at `0.0.14` (the number surviving onto `elements`,
+    inside a value typed `readonly string[]`) and an absent one emitted `TA1**250101*…`; both refuse.
+    **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` 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**
@@ -830,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
@@ -913,10 +1443,12 @@ N-char spec limit` refusal, one per emitting module, where the branch fires **be
   than reaching the message.
 
   **Read the "through a builder's segment joiner" qualifier literally.** `buildTA1` does not use one,
-  and is therefore **not covered**: it emits its five caller-supplied elements with a direct join, no
-  escape and no padding, so a numeric or `undefined` `interchangeControlNumber` is emitted silently
-  (`TA1**250101*1200*A*000`). TA1-01 is the reassociation key from the acknowledgment back to the
-  interchange it acknowledges, so that matters. Unchanged from `0.0.9` and tracked as its own item.
+  and is therefore **not covered by the segment guard**. Through `0.0.14` that meant nothing checked
+  its five elements at all, and a numeric or `undefined` `interchangeControlNumber` was emitted
+  silently (`TA1**250101*1200*A*000`); `X12-TA1-EMIT-NOT-RELEASE-AWARE` closed that by routing them
+  through the escape helper, which type-checks first and refuses with `AckBuildError` /
+  `X12_ACK_INVALID_SPEC`. What being outside the segment guard still costs is the **slot** in the
+  refusal message: it names `buildTA1`, never `TA1-01`.
 
   The monetary slots got their own guard on top of it: a slot typed `X12Decimal` refuses anything that
   is not one, rather than rendering `number.toString()` into the document.
@@ -928,7 +1460,9 @@ N-char spec limit` refusal, one per emitting module, where the branch fires **be
      `1?*BOGUS`); the fixed-width ISA slots do not go through it at all.
   2. **Whether an `X12Decimal` carries the SCALE you meant.** `fromString("0.3")` and
      `fromString("0.30")` are both accepted and both emit verbatim. That choice is yours.
-  3. **Anything `buildTA1` emits**, per the paragraph above.
+  3. **The delimiter set `buildTA1` releases against**, per the paragraph above. It defaults to the
+     cosyte archetype and the function cannot verify it; state the separators on `BuildTA1Options`
+     if you embed a TA1 in an envelope that declares different ones.
   4. **`build835`'s balance-equation amounts, which refuse UNTYPED.** `build835` runs its balance
      guard before it builds the escape helper, and that guard calls `X12Decimal` methods on your
      value. So a raw `number` there throws a plain `TypeError` with **no `code`** - some saying the