@cosyte/x12 0.0.14 → 0.0.15

package/CHANGELOG.md

@@ -9,6 +9,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **🩺 `Build837EnvelopeSpec.implementationConventionReference` - the caller now states the ST-03 /
+  GS-08 implementation convention reference `build837P` / `build837I` / `build837D` declares**
+  (`X12-837-EMIT-IDENTIFIER-FIXED`). One value, **both elements**; omit it and the builders emit
+  exactly what they always have.
+
+  **What this fixes, and it is a rejected claim rather than a mis-read one.** The builders stamped
+  `005010X222A2` / `005010X223A3` / `005010X224A2` with no way to change them. Two of those are not
+  what CMS and several state Medicaid companion guides require in ST-03 and GS-08 on production
+  professional and institutional claims, which ask for `005010X222A1` and `005010X223A2`, so **a
+  partner on one of those guides rejected every 837 this library built and a caller had no remedy.**
+  The read side of the same fact was grounded in the release before this one; this is the emit side.
+
+  **🛑 The defaults are UNCHANGED, on purpose, and that is the whole shape of the fix.** Which
+  published guide identifier a trading partner accepts is a **partner fact, not a spec fact**.
+  Re-stamping the default would silently change bytes this library already puts on the wire and
+  break the partners it works with today, so the default stays and the caller states what its own
+  partner asked for. Nothing about an existing call changes.
+
+  **What it refuses of its own, all `Claim837BuildError` with code `X12_837_BUILD_INVALID_SPEC`, and
+  none of them echoes the value you passed.** These 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, so read the list
+  as what this field adds and not as a closed account of everything that can refuse. No total is
+  published.
+  - **Empty.** A trailing empty element is not emitted at all, so an empty reference would remove
+    ST-03 and GS-08 rather than send them empty - a silent structural loss on two required elements.
+  - **Carrying an active delimiter or the release character.** The value is refused rather than
+    escaped. A trading partner's parser is not obliged to honour the release escape, and a published
+    guide identifier has no legitimate use for a delimiter, so the refusal is kept even now that
+    this library's own reader would carry it (see the envelope-splitter entry below).
+  - **A reference this library's own reader resolves to a DIFFERENT 837 variant** (`005010X223A2`
+    handed to `build837P`). The emitted file would declare one variant and carry another's service
+    segments, and `get837Claims` would decode none of its service lines. Same class as the existing
+    refusal for a service line whose `variant` disagrees with the builder's. The message names the
+    variant the builder emits and deliberately not the one the reference belongs to.
+
+  **A reference outside the read table is emitted as given, and that is deliberate.** Nothing makes
+  the published-errata set provably exhaustive, so refusing an unrecognised identifier would claim
+  an exhaustiveness this library does not claim when reading either. The honest cost is pinned as a
+  test: on such a file this library's own reader falls back to the `SVx` scan, exactly as it does
+  for any unrecognised ST-03. The **length** is not bounded either, and the two elements' maxima
+  differ: GS-08 is data element 480 (`AN 1/12`), ST-03 is element 1705 (`AN 1/35`).
+
+  **🩺 A guard on this element cannot make the element trustworthy, and the disclosure above is
+  therefore about the whole envelope segment rather than these two elements.** An **unescaped**
+  active delimiter in a _different_ `GS` or `ST` element still ends its own element and shifts every
+  element after it, so ST-03 and GS-08 are then read out of a neighbour's slot, and no refusal here
+  can reach it. A **release-escaped** one no longer does - see the entry below, which landed after
+  this one and retracts the part of it that said escaping could not help.
+
 - **🩺 `X12_837_SERVICE_SEGMENT_REPEATED`, the 33rd Tier-2 warning code, plus the public factory
   `serviceSegmentRepeated(position)`** (`X12-837-SV1-OVERWRITE`). A **second** `SV1` / `SV2` / `SV3`
   arriving inside an **already-open** Loop 2400 now says so, at that repeated segment. Through
@@ -901,6 +950,166 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **🩺 `buildTA1` now release-escapes its five caller-supplied elements, so an Accept acknowledgment
+  this library emits no longer reads back as a Reject** (`X12-TA1-EMIT-NOT-RELEASE-AWARE`).
+  Reproduced on the base tree at `e8f34b9`. `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, 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 entry below 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 emitted.
+
+  **The grounding is inside this package rather than in a spec clause**, the same tiebreak the entry
+  below 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.
+
+  **🛑 It changes bytes this library already put on the wire, and that is the cost.** A value
+  containing none of the four delimiters and no `?` is emitted byte-for-byte as before, which 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.
+
+  **🛑 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"` at `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`,
+  `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. 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. If you were escaping the value yourself, as `KNOWN-LIMITATIONS.md`
+  advised while this was open, drop that - you are now escaping twice on both kinds of surface
+  (`"00000001??"` in, `TA1*00000001????*…` out, `getSegmentValue` answering `"00000001??"`).
+
+  **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"`. 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.
+
+  **`BuildTA1Options` gained `repetitionSeparator`, `componentSeparator` and `segmentTerminator`**
+  beside the existing `elementSeparator`, the same four `build999` already takes. They exist for
+  escaping and nothing else - `buildTA1` still emits no segment terminator, no repetition and no
+  composite. Escaping against a guessed delimiter set is a value corruption rather than a safe
+  default: `unescapeRelease` preserves `?X` verbatim for any `X` outside the reader's declared set,
+  so a value released against the wrong delimiter comes back carrying a stray `?`. The defaults are
+  unchanged and are the cosyte archetype, which this function cannot verify, so state the separators
+  if you embed a TA1 in an envelope that declares different ones.
+
+  **A non-string element now refuses** with `AckBuildError` and the existing `X12_ACK_INVALID_SPEC`
+  code, and that is a prerequisite of the escape rather than a separate guard: releasing a value
+  routes 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 `interchangeControlNumber` emitted `TA1*12345*260601*1200*A*000`
+  before, with the number surviving onto `elements` inside a value typed `readonly string[]`, and an
+  absent one emitted `TA1**250101*1200*A*000`. The accept-with-note refusal still runs first and
+  still reports `X12_TA1_ACCEPT_WITH_NOTE`, so no existing refusal moves code.
+
+  **What this does not close:** `buildTA1` still uses no segment joiner, so its refusal names the
+  builder and never `TA1-01`; `buildInterchange` still does not escape GS-04, GS-05 or GS-07; and an
+  unescaped active delimiter is still not safe anywhere. Measured in `KNOWN-LIMITATIONS.md`.
+
+- **🩺 A `?` immediately before the element separator inside an envelope segment now frames as ONE
+  element, which fixes a released delimiter and is a SYMMETRIC change**
+  (`X12-ENVELOPE-SPLITTER-NOT-RELEASE-AWARE`). Reproduced on the base
+  tree at `1b71733`. `src/parser/envelope.ts`'s `splitElements` - the splitter for `GS`, `GE`, `ST`,
+  `SE`, `IEA` and `TA1` - was a plain `String.prototype.split` on the element separator, so a `?*`
+  ended the element anyway and every element after it moved down a slot:
+
+  ```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 - the BODY control, always correct
+  ```
+
+  **What made it a defect rather than a tolerance is that this package's own two halves disagreed
+  inside a single call:** `buildInterchange` maps its release escaper over GS-02 / GS-03 / GS-06 /
+  GS-08 and ST-01 / ST-02 / ST-03, then returns `parseX12` of the bytes it just wrote, so
+  `applicationSenderCode: "SEND*ER"` emitted a correct `GS*HC*SEND?*ER*...` and handed back a model
+  whose GS-08 answered `"X"`, with `warnings: []`.
+
+  **🛑 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, `0.0.14` framed it wrongly and this release frames it correctly: a correction, the rows
+  above. Where the sender sent a **literal `?`** as the element's last byte, `0.0.14` framed it
+  correctly and this release 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 and reads **eight** here, GS-06 answering `"X"` and GS-08 gone. Every other release
+  sequence in an envelope element (`??`, `?:`, `?^`, `?~`, `?A`) framed identically before and after
+  and still does, pinned as invariance controls.
+
+  **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**. Both are pinned, alongside a
+  genuine mismatch that raises it on either tree.
+
+  **🩺 The regression direction reaches an 837's variant and its money, by one route.** `ST-03`
+  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` at
+  `0.0.14`, and reads `variant` `"I"` with `charge` `150.00` and that warning silent here. **A warned
+  non-decode becomes a decoded amount.** Re-check any routing driven off `submission.variant` if your
+  partners send envelope elements that can end in a literal `?`.
+
+  **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), so
+  the envelope now obeys the one rule the rest of the package already obeyed.
+
+  **🩺 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: 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**: a `groupDate` of
+  `"2026060?"` read nine GS elements at `0.0.14` and reads eight here, GS-08 gone. If you emit one
+  of those, escape or reject a `?` yourself.
+
+  **Values are still RAW, pre-`?`-unescape**, exactly as `X12Segment.elements` has always documented:
+  `gs.elements[2]` reads `"SEND?*ER"`, not `"SEND*ER"`. `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.** ASC X12 .5 makes it fixed-width, which is what lets the
+  delimiter set be recovered from it before anything is parsed, so a `?` in an ISA element is content
+  and never an escape; release-splitting it would collapse a well-formed ISA below its 17 entries.
+  A degenerate delimiter set whose element separator IS `?` also falls back to the literal split,
+  the same guard the segment-terminator scanner already carried. Both are pinned, each with a red
+  negative control.
+
+  **🛑 An UNESCAPED delimiter is still not safe and nothing here claims otherwise** - a bare active
+  delimiter ends its element, because that is what a delimiter is. `build837`'s
+  `implementationConventionReference` still refuses a value carrying one, deliberately not relaxed:
+  a partner's parser is not obliged to be release-aware either, and widening an emit surface is its
+  own decision rather than a side effect of a reader fix.
+
 - **🩺 An `AMT` / `ADX` row whose amount decodes nothing is no longer dropped in silence**
   (`X12-AMT-ADX-ABSENT-AMOUNT`). Reproduced on the base tree at `9db104b` across all four readers,
   and the report it now raises is the `X12_AMOUNT_ROW_DROPPED` entry under **Added** above. The

package/KNOWN-LIMITATIONS.md

@@ -53,14 +53,200 @@ 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` does not escape GS-04, GS-05 or GS-07** (`groupDate`, `groupTime`,
+    `responsibleAgencyCode`). A `groupDate` of `"2026060?"` emits
+    `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`.
+
+  - **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
+    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.
+  - **🩺 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.
+
+- **🩺 `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`, `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.
+    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 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.
+  - **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` 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.
 
 - **🩺 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**
@@ -913,10 +1099,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 +1116,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

package/dist/index.cjs

@@ -1097,7 +1097,10 @@ function splitSegments(text, start, delimiters) {
   return { segments, endIndex: lastEnd };
 }
 function splitElements(segment, delimiters) {
-  return Object.freeze(segment.split(delimiters.element));
+  if (delimiters.element === RELEASE_CHAR) {
+    return Object.freeze(segment.split(delimiters.element));
+  }
+  return Object.freeze(splitWithRelease(segment, delimiters.element));
 }
 function el(elements, index) {
   return elements[index] ?? "";
@@ -4569,6 +4572,29 @@ var VERSION_BY_VARIANT = {
   I: "005010X223A3",
   D: "005010X224A2"
 };
+function resolveVersionRelease(variant, reference, esc) {
+  if (reference === void 0) return VERSION_BY_VARIANT[variant];
+  if (reference === "") {
+    throw new Claim837BuildError(
+      CLAIM_837_BUILD_ERROR_CODES.X12_837_BUILD_INVALID_SPEC,
+      "build837: envelope.implementationConventionReference is empty. ST-03 and GS-08 are required elements and a trailing empty element is not emitted, so an empty reference would remove them rather than send them empty. Omit the field to take the builder's default."
+    );
+  }
+  if (esc(reference) !== reference) {
+    throw new Claim837BuildError(
+      CLAIM_837_BUILD_ERROR_CODES.X12_837_BUILD_INVALID_SPEC,
+      "build837: envelope.implementationConventionReference carries an active delimiter or the release character. Escaping does not make it safe here: the ST and GS segments are read by a splitter that is not release-aware, so a released delimiter still splits the segment and the declaration silently becomes two elements. State a reference that carries neither, or choose different delimiters."
+    );
+  }
+  const named = Object.hasOwn(VARIANT_BY_ICR, reference) ? VARIANT_BY_ICR[reference] : void 0;
+  if (named !== void 0 && named !== variant) {
+    throw new Claim837BuildError(
+      CLAIM_837_BUILD_ERROR_CODES.X12_837_BUILD_INVALID_SPEC,
+      `build837: envelope.implementationConventionReference names an implementation guide this library reads as a DIFFERENT 837 variant, but this is build837${variant}. The emitted file would declare one variant and carry another's service segments, and this library's own reader would then decode none of its service lines. State a reference for the ${variant} 837, or build with the entry point that matches the reference.`
+    );
+  }
+  return reference;
+}
 var X12_837_FUNCTIONAL_ID = "HC";
 var X12_AGENCY_CODE2 = "X";
 var HL_LEVEL = { BILLING: "20", SUBSCRIBER: "22", PATIENT: "23" };
@@ -4583,7 +4609,6 @@ function build837D(spec) {
 }
 function buildClaim837(variant, spec) {
   const { envelope } = spec;
-  const versionRelease = VERSION_BY_VARIANT[variant];
   enforceStructuralSpec2(variant, spec);
   const elementSeparator = envelope.elementSeparator ?? "*";
   const repetitionSeparator = envelope.repetitionSeparator ?? "^";
@@ -4609,6 +4634,11 @@ function buildClaim837(variant, spec) {
     return escaped.slice(0, end).join(componentSeparator);
   };
   const ctx = { seg, esc, comp };
+  const versionRelease = resolveVersionRelease(
+    variant,
+    envelope.implementationConventionReference,
+    esc
+  );
   const senderQualifier = envelope.senderQualifier ?? "ZZ";
   const receiverQualifier = envelope.receiverQualifier ?? "ZZ";
   const usageIndicator = envelope.usageIndicator ?? "P";
@@ -9733,18 +9763,27 @@ function expandYY8(yymmdd) {
 // src/transactions/ack/build-ta1.ts
 function buildTA1(spec, options = {}) {
   enforceAcceptIsClean2(spec);
-  const elementSeparator = options.elementSeparator ?? "*";
+  const delimiters = {
+    element: options.elementSeparator ?? "*",
+    repetition: options.repetitionSeparator ?? "^",
+    component: options.componentSeparator ?? ":",
+    segment: options.segmentTerminator ?? "~"
+  };
+  const esc = makeCallerEscaper(delimiters, "buildTA1", refuseSpec9);
   const elements = Object.freeze([
     "TA1",
-    spec.interchangeControlNumber,
-    spec.interchangeDate,
-    spec.interchangeTime,
-    spec.ackCode,
-    spec.noteCode
+    esc(spec.interchangeControlNumber),
+    esc(spec.interchangeDate),
+    esc(spec.interchangeTime),
+    esc(spec.ackCode),
+    esc(spec.noteCode)
   ]);
-  const raw = elements.join(elementSeparator);
+  const raw = elements.join(delimiters.element);
   return Object.freeze({ raw, elements });
 }
+function refuseSpec9(message) {
+  throw new AckBuildError(ACK_BUILD_ERROR_CODES.X12_ACK_INVALID_SPEC, message);
+}
 function enforceAcceptIsClean2(spec) {
   if (spec.ackCode === TA1_ACK_CODES.A && spec.noteCode !== "000") {
     throw new AckBuildError(
@@ -9933,7 +9972,7 @@ var X12BuildError = class extends Error {
 };
 
 // src/builder/build-interchange.ts
-function refuseSpec9(message) {
+function refuseSpec10(message) {
   throw new X12BuildError(X12_BUILD_ERROR_CODES.X12_BUILD_INVALID_SPEC, message);
 }
 function buildInterchange(spec) {
@@ -9947,7 +9986,7 @@ function buildInterchange(spec) {
     component: componentSeparator,
     segment: segmentTerminator
   };
-  const esc = makeCallerEscaper(delimiters, "buildInterchange", refuseSpec9);
+  const esc = makeCallerEscaper(delimiters, "buildInterchange", refuseSpec10);
   const senderQualifier = spec.senderQualifier ?? "ZZ";
   const receiverQualifier = spec.receiverQualifier ?? "ZZ";
   const usageIndicator = spec.usageIndicator ?? "P";
@@ -10061,7 +10100,7 @@ function buildTransaction(tx, esc, elementSeparator, segmentTerminator) {
   return st + bodySegments + se;
 }
 function joinSeg2(parts, elementSeparator, segmentTerminator) {
-  requireCallerSegment(parts, "buildInterchange", refuseSpec9);
+  requireCallerSegment(parts, "buildInterchange", refuseSpec10);
   return parts.join(elementSeparator) + segmentTerminator;
 }
 function pad9(value, width) {
@@ -10370,7 +10409,7 @@ var profiles = Object.freeze({
 });
 
 // src/index.ts
-var VERSION = "0.0.14";
+var VERSION = "0.0.15";
 
 exports.ACK_BUILD_ERROR_CODES = ACK_BUILD_ERROR_CODES;
 exports.ALL_WARNING_MESSAGES = ALL_WARNING_MESSAGES;