@cosyte/x12 0.0.15 → 0.0.16

package/CHANGELOG.md

@@ -7,6 +7,225 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Documentation
+
+- **The documentation carriers that told you to read an envelope element's logical value through
+  `getSegmentValue` are corrected** (`X12-ENVELOPE-VALUE-ROUTES`). **Documentation and tests only: no
+  runtime line changed and the emitted JS is byte-identical, so no behaviour moved.**
+
+  `getSegmentValue` takes an `X12Segment`, which requires `id`. `IsaSegment`, `IeaSegment`,
+  `GsSegment`, `GeSegment`, `Ta1Segment` and the inline ST/SE types on `X12TransactionSet` declare
+  only `raw` and `elements`, so passing any one of them is `TS2345`, "Property 'id' is missing".
+  **All seven are measured here.** The carriers include
+  `KNOWN-LIMITATIONS.md`'s _"Read through `getSegmentValue` if you want the logical value"_ for a
+  `gs`, which is the one that owed you a route and so is the one replaced rather than cut.
+
+  **Two routes reach the decoded text, both were already published in this package, and neither is
+  universal.** `unescapeRelease` on the element string is a public export. Adding an `id` and taking
+  the dot-path is what `buildTA1`'s own JSDoc prescribes ("add one to read a TA1 through it") and
+  what this repo's tests do. They are not interchangeable:
+
+  ```text
+  element                     raw            unescapeRelease   add id + dot-path   transmitted
+  GS-04, a released `*`       "2026?*0601"   "2026*0601"       "2026*0601"         "2026*0601"
+  GS-07, a REAL repetition    "A^B"          "A^B"             "A"                 "A^B"
+  TA1-01, a released `^`      "0000?^0001"   "0000^0001"       "0000^0001"         "0000^0001"
+  ```
+
+  Every row `warnings: []`. A bare dot-path means repetition 0, which is why the GS-07 row differs.
+
+  **The public signature was NOT widened, and that was the decision rather than the cheap way out.**
+  `getSegmentValue`'s body never reads `id`, so widening its parameter to an `elements`-only
+  structural type is free, non-breaking and emits nothing. It was refused because the function
+  unescapes unconditionally while the ISA is positional, where a `?` is content and never an escape.
+  Widening admits `IsaSegment` and makes a silently wrong read of ISA-13, the reassociation key,
+  compile:
+
+  ```text
+  transmitted ISA-13   arity   elements[13]   decoded (both routes)   elements[16]
+  "000000??1"          17      "000000??1"    "000000?1"              ":"
+  "0000?*001"          18      "0000?"        "0000?"                 "P"
+  "00000001?"          17      "00000001?"    "00000001?"             ":"
+  ```
+
+  No route reads an ISA element correctly across those rows. On the middle one `decodeIsa` split on
+  the element separator, so `elements[13]` is a prefix and ISA-16 re-indexed onto ISA-15's value.
+  **So no route is prescribed for the ISA at all**, and the missing arity check on that split is
+  filed rather than fixed here. A capability that is right on six envelope types and silently wrong
+  on the seventh is not an ergonomic win, so the claim was cut instead and no code grew.
+
+  `test/parser-envelope-value-routes.test.ts` pins all of it. Seven `@ts-expect-error` assertions
+  cover the seven types, and `typecheck` runs over `test/`, so **they red if the signature is ever
+  widened**: widening is not forbidden, it is made loud, because the assertions have to be deleted
+  and that is where the ISA question gets answered. Under a mutation that widens the signature the
+  file reports seven unused directives, not one, which is what distinguishes it from a green vacuous
+  test.
+
+  Two earlier statements are deleted rather than reworded, because both are measured false. _"There
+  is no decoded read for an envelope element; `unescapeRelease` on the string is the only route"_:
+  there are two, and the second is prescribed inside this package. _"A raw-vs-`unescapeRelease` cell
+  on the ISA is a tautology that detects nothing"_: `unescapeRelease` does not know the ISA is
+  exempt, so on `"000000??1"` the cell differs.
+
+  Unchanged and filed: `parse-ta1.ts` and `KNOWN-LIMITATIONS.md` still mis-cite `X12Segment.elements`
+  for types that are not one. That statement is true where these were false, and it has a twin, so it
+  stays its own slice. `docs-content`'s dot-path example is scoped to body segments and was already
+  correct.
+
+- **Eleven JSDoc pointers that sent a consumer to an envelope `elements[n]` for a value are deleted**
+  (`X12-ENVELOPE-VALUE-POINTERS`). **Documentation only: the diff is comment-only and the emitted JS
+  is byte-identical, so no behaviour changed.**
+
+  `X12_CONTROL_NUMBER_MISMATCH`'s JSDoc told you to read `isa.elements[13]`, `iea.elements[2]`,
+  `gs.elements[6]`, `ge.elements[2]`, `st.elements[2]` and `se.elements[2]` "off the model when you
+  need the values". Envelope element values are stored RAW, pre-`?`-unescape, so on a document whose
+  control number carries a release escape those reads hand back the framed bytes and not the value:
+  `gs.elements[6]` reads `"000?*99"` where the value is `"000*99"`. The same shape sat in
+  `X12_GROUP_COUNT_MISMATCH`'s and `X12_TRANSACTION_COUNT_MISMATCH`'s "both numbers stay on the model
+  (`iea.elements[1]` …)" parentheticals and in `serializeX12`'s module doc, which named three more.
+  All of those are **deleted**; nothing was added to make one true, and no accessor, guard or test
+  assertion was minted.
+
+  The surviving sentences still say the bytes stay on the model, which is true. What is gone is the
+  promise that a raw element index yields the decoded value.
+
+  Pointers that **label** their surface as raw are correct and are untouched: `raw.elements[5]` "is
+  the byte surface", `gs.elements[8]` gets "the sender's bytes rather than a normalization",
+  `seg.elements[0]` stays "verbatim".
+
+  **This does not bound the class.** `src/parser/types.ts` still names `iea.elements[2]`,
+  `gs.elements[6]`, `ge.elements[2]` and `ta1.elements[1]` for values in the `@example` blocks of the
+  envelope types, with no raw label; those are unchanged here and filed. `ta1.elements[1]` is the one
+  to know about: TA1-01 is the reassociation key, so a consumer following that example compares
+  framed bytes to the ISA-13 it acknowledges.
+
+  Two more pre-existing limits, unchanged and filed. **`getSegmentValue` cannot read an envelope
+  segment**: it takes an `X12Segment`, which requires `id`, and `IsaSegment`, `IeaSegment`,
+  `GsSegment`, `GeSegment`, `Ta1Segment` and the ST/SE types declare only `raw` and `elements`, so
+  passing one is a `TS2345`. And **the ISA element
+  split has no arity check**: `decodeIsa` splits on the element separator, so an ISA-13 carrying a raw
+  separator yields 18 elements where 17 are documented and silently re-indexes ISA-14/15/16.
+
+### Fixed
+
+- **🩺 `implementationConventionReference` is POST-`?`-unescape in every typed reader that publishes
+  it** (`X12-ST03-READ-NOT-RELEASE-AWARE`). A behaviour change on any document whose `ST-03` carries
+  a release escape.
+
+  `X12TransactionSet.st.elements` is the ST segment as framed - post-element-split and PRE-unescape -
+  and five public readers were handing one
+  of those strings straight back on the model: `get837Claims`, `get277Status`,
+  `get277CADisposition`, `get278Request` and `get278Response` (`walk277` and `walk278` are shared, so
+  three reads serve the five). A sender that escaped a delimiter inside `ST-03` got the escape back
+  rather than the value it stated. The cells that were run, framed element text on the left:
+
+  ```text
+  ST-03 as framed    published through 0.0.15    published now
+  "A??B"             "A??B"                      "A?B"
+  "A?*B"             "A?*B"                      "A*B"
+  "A?:B"             "A?:B"                      "A:B"
+  "A?~B"             "A?~B"                      "A~B"
+  "A?^B"             "A?^B"                      "A^B"
+  ```
+
+  The grounding is this package disagreeing with itself and nothing else: every dot-path read
+  (`elementValue`, `elementOptional`, `componentOptional`) already unescaped, and `parse999` already
+  decoded `AK2-03`, the identically-named field. No TR3 clause is claimed, on either side.
+
+  **🛑 What DECIDES an outcome did not move, and that was a deliberate scope call.** 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.** They can differ: a letter is an admissible delimiter, so with
+  `componentSeparator: "X"` an `ST-03` framed as `005010?X222A1` decodes to `005010X222A1`, which the
+  variant table holds. Keying on the decoded text would make the declaration beat the `SVx` fallback
+  there, and on a document whose only service segment is an `SV2` that stops the 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, so it is left open. **The difference is one-way:
+  no document that resolved a variant, or was admitted by `get277CADisposition`, stops doing so** -
+  no identifier any of the three tests is keyed on carries a delimiter or the release character, so
+  raw text equal to one decodes to itself.
+
+  **🛑 The consumer-visible consequence, stated rather than left to be inferred: 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` at all 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` - in both cases
+  the code that fired says `ST-03` named no identifier this reader recognises while the model field
+  holds one it does. **That is why `X12_837_UNKNOWN_VARIANT`'s closing pointer at the model is
+  deleted rather than reworded.** The 277 shape is the
+  same:
+  the model publishes `005010X214` while `transactionType` is `claim-status` and
+  `get277CADisposition` returns `undefined`. **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.** No code moved and no code was minted.
+
+  **No normalisation and no new warning.** Nothing is trimmed, case-folded or prefix-matched, and a
+  whitespace-only `ST-03` is still published untrimmed. A dangling `?` at the end of the element
+  still raises no `X12_DANGLING_RELEASE_CHAR` here: the sink is a no-op, matching `getSegmentValue`'s
+  default, `parseTA1` and `parse999`, so every other element these readers decode drops it too.
+  Each reader's own empty / absent mapping is unchanged - `walk278` still collapses `""` to
+  `undefined`, the other two still publish `""`. **`tx.st.elements` is untouched and is still the
+  verbatim framed surface.** If you were applying `unescapeRelease` to
+  `submission.implementationConventionReference` yourself, drop that call.
+
+- **🩺 `parseTA1`'s five decoded fields are POST-`?`-unescape, and an empty TA1-02 / TA1-03 / TA1-04
+  / TA1-05 is refused on emit** (`X12-TA1-RESIDUALS`). Both are behaviour changes. They ship as one
+  entry 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.** The entry below made `buildTA1` release all five caller elements; `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.
+
+  **`raw` is untouched and is still the verbatim byte surface**, so `ta1.raw.elements` still answers
+  the bytes. A value with no `?` in it is unchanged on both surfaces, which is every conformant TA1.
+  **If you were applying `unescapeRelease` to `parseTA1`'s output yourself, as `KNOWN-LIMITATIONS.md`
+  advised while this was open, drop that call.** The dangling-`?` warning
+  `X12_DANGLING_RELEASE_CHAR` is not surfaced here, because `parseTA1` returns no warnings channel;
+  `parse999` drops the same warning from the same helper for the same reason.
+
+  **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: []`:
+
+  ```text
+  interchangeDate: ""   TA1*000000001**1200*A*000       interchangeTime: ""  TA1*000000001*260601**A*000
+  ackCode: ""           TA1*000000001*260601*1200**000  noteCode: ""         TA1*000000001*260601*1200*R*
+  ```
+
+  Each now draws `AckBuildError` with the existing code `X12_ACK_INVALID_SPEC`, naming the slot and
+  the spec property and never the value. **No new error code is minted and no warning code moves.**
+  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.
+
+  **🛑 It does NOT trim, at any of the five slots** - a whitespace-only element still builds, exactly
+  as at TA1-01, because trimming is a normalisation rule and no source consulted for this package
+  states one. **🛑 It does not narrow what a NON-empty element may contain**: an out-of-enum
+  `ackCode: "X"` still builds and the read half still applies its documented fail-safe narrow to
+  `R`, which is the same answer an empty one gave. **🛑 Every guard that stood before it keeps its
+  precedence** - `enforceAcceptIsClean` still runs first, 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 change is refused
+  differently by it.
+
 ### Added
 
 - **🩺 `Build837EnvelopeSpec.implementationConventionReference` - the caller now states the ST-03 /
@@ -409,6 +628,80 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **🩺 An EMPTY control number is now REFUSED on emit, where ISA-13 / IEA-02 used to be FABRICATED
+  out of it** (`X12-EMPTY-CONTROL-NUMBER-FABRICATED`). Reproduced on the base tree at `28b417f`,
+  which is `main` at published `0.0.15`.
+
+  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 helper;
+  `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 the caller never supplied, ISA-13 reconciling perfectly against IEA-02, with an
+  empty warning array. **A control number is how an interchange is reconciled and acknowledged, so a
+  fabricated one does not fail: it succeeds against the wrong thing, and the sender gets no signal.**
+
+  **The class is wider than that slot, and it has two mechanisms rather than one.** The group and
+  transaction-set control numbers reach the wire through the release escaper, which early-returns on
+  `""`, so an empty one lost the required element. **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 one variable at a time, 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`. The `buildTA1` case was already disclosed in
+  `KNOWN-LIMITATIONS.md` as tracked and open; `AK1-02` and `AK2-02` were not disclosed anywhere.
+
+  All of them now draw that builder's own typed, code-tagged refusal before anything is emitted,
+  naming the slot and the spec property: `build837: groupControlNumber is empty. GS-06 / GE-02 is a
+required control number and this builder never invents one, so nothing is emitted.` **No new error
+  code is minted and no warning code moves.** What changes is that a call which used to hand you a
+  document now throws, and that a spec which is wrong in two ways can now report a different one of
+  the two. See the precedence bullet below: this is not "nothing a consumer branches on changes", and
+  a draft of this entry said exactly that.
+
+  **Why refuse rather than warn, stated as a decision because the standard does not settle it.**
+  005010 says nothing about what a builder should do with an absent control number. The tiebreak is
+  CONSISTENCY inside this package: every other empty required element on the emit side is already
+  refused by name (`build835`'s `patientControlNumber`, `build837`'s `claimId`, `build834`'s
+  `maintenanceTypeCode`, `build278`'s `requestCategoryCode`, `build277`'s `categoryCode`), emit is
+  the deliberately strict half of this library, and a warning would have had to travel the parse
+  channel a builder returns, which is the registry consumers use to grade INBOUND documents.
+
+  **What it costs, and it is a real break:** a caller relying on `""` to mean "pad me a control
+  number" is broken by this, deliberately. What they were shipping was `000000000`, a real value a
+  trading partner may already have assigned to something else.
+  - **🛑 The guard is byte-strict `=== ""` and does NOT trim.** A whitespace-only control number is
+    still accepted and still padded: `" "` emits ISA-13 as `00000000 `. `buildTA1` does no padding at
+    all, so it emits whatever whitespace it was handed, verbatim. Trimming would be a normalisation
+    rule, no source consulted for this package states one, and the five in-package guards this
+    mirrors are byte-strict for the same reason. Pinned as a test and disclosed in
+    `KNOWN-LIMITATIONS.md` as the one shape still worth screening at your own boundary.
+  - **A SHORT control number still zero-pads.** The guard is not "ISA-13 must be nine characters":
+    `"1"` still emits `000000001`, which is what the padding 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 count
+    reconciliation, `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, each
+    verified. **What it does NOT preserve is an ordering against a defect detected LATER**, during
+    body assembly, which now reports the control-number refusal instead. Measured: `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` here. If you branch on a specific builder error code,
+    that pairing moved.
+  - **No census of the slots that are NOT routed through the guard is published**, here or anywhere
+    else in the package. The claim is the property: a control number routed through the new guard is
+    refused when empty.
+
 - **🩺 `get837Claims` now recognises every published `ST-03` implementation-convention reference for
   the three 837 guides, and some already-published files therefore decode differently**
   (`X12-VARIANT-ICR-UNGROUNDED`). This is a grounding unit: the table `VARIANT_BY_ICR` had three keys
@@ -684,13 +977,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   "An `X12Decimal` slot holds no identifier today" would have been the wrong kind of argument: a fact
   about today's slots rather than a property of the guard.
 
-  **Two things that property does NOT say, and both were drafted as absolutes first.** The array
+  **What that property does NOT say, and it was drafted as an absolute first.** The array
   guard still renders a forged array-like's `length` and its class tag through `renderCallerValue`,
   bounded: those describe the SHAPE a caller forged rather than an element's contents, and they are
-  the whole diagnostic for `{ length: "9".repeat(120000) }`. And **only the segment-join guard names
-  the SLOT** - `esc` and `escDec` name the BUILDER, a limit `caller-string.ts` already recorded, so on
-  those two the echoed value used to stand in for a locator and now nothing does. That is a real
-  diagnostic cost and it is disclosed rather than argued away.
+  the whole diagnostic for `{ length: "9".repeat(120000) }`.
 
   **The segment guard's slot locator is now bounded by GRAMMAR rather than by length.** `parts[0]` is
   caller-supplied in `buildInterchange`, which takes `[segmentId, ...elements]` wholesale, so it is
@@ -950,6 +1240,303 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **🩺 BREAKING (emit side): a delimiter that is not SHAPED like a delimiter is REFUSED by every
+  builder** (`X12-EMIT-DELIMITER-SHAPE-UNCHECKED`). Each of the four roles must be a **string of
+  exactly one visible character**, and the four must be **mutually distinct**. Reproduced on the base
+  tree at `a21f8ea`.
+
+  **The rule is not invented for emit.** `detectDelimiters` already decides what a delimiter is for
+  this package, and decides it as a Tier-3 fatal: one character at each of four fixed ISA positions, each
+  visible, the four distinct, else `X12_INVALID_DELIMITERS` thrown even in lenient mode. The
+  builders now import that predicate rather than restating it, so the emit refusal and the read fatal
+  cannot drift apart into two ideas of what a delimiter is. **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. The one-character requirement is structural rather than conventional, because
+  the ISA is fixed-width per ASC X12 .5 and `Delimiters` records exactly one character per role.
+
+  **🛑 It is a UTF-16 code-unit rule and NOT a byte rule, and that difference is a residual it does
+  not close.** A character that is one code unit but several bytes on the wire satisfies it and still
+  displaces every ISA position after it: `componentSeparator: "\u00a7"` builds with `warnings: []`,
+  and a byte-oriented receiver reads ISA-16 as `0xC2` and the terminator as `0xA7`. The smart quote
+  `"\u2019"` that a companion-guide PDF gives you instead of `'` does the same. Disclosed, not
+  guarded: the read side counts code units too, so moving one side alone would put them back out of
+  step.
+
+  **Three mechanisms, and they are not one defect.**
+  - **LENGTH.** `build837P` with `segmentTerminator: "~~"` built with `warnings: []` and put 31
+    segment rows on a transaction whose `SE-01` declares 16, every other row a phantom the caller
+    never wrote. **No claim is published about which roles were silent** - two drafts of this entry
+    stated an asymmetry and both were measured false, the second inside the fix for the first.
+    `buildTA1` with `{ 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. And `buildInterchange` with `componentSeparator: ":~"` built with `warnings: []` too,
+    reading back through a well-formed ISA while the builder's own terminator became an uncounted
+    empty segment, with no element value escaped against `:`.
+  - **TYPE, where the join coerces and the escape does not.** `Array.prototype.join` coerces a
+    non-string delimiter and the document frames on the coerced byte, but `escapeRelease` compares
+    delimiters with `===`, so no element value is escaped against it. `build837P` with
+    `componentSeparator: 1` emitted `SV1*HC199213`, which reads `SV1-01-2` back as `992` rather than
+    the procedure code `99213`, and `CLM-05`'s place-of-service composite as `111B11`; `build271`
+    with `repetitionSeparator: 1` emitted `EB*1**3011`, and `EB-03`'s two service type codes stopped
+    reading back as two. `warnings: []` on both. 🩺 No unusual caller value is involved, and a
+    length rule cannot reach this at all.
+  - **`buildTA1` had no net.** It is the only builder that does not end in `parseX12`, so
+    `elementSeparator: ""` RETURNED `TA10000000012606011200A000`: the reassociation key, the date,
+    the time, the disposition and the note code in one undelimited blob.
+
+  **⚖️ Refuse rather than warn, and no code is minted.** The tiebreak is consistency with the two
+  guards that shipped before it, not a 005010 clause; a warning would have to travel the READ
+  registry a builder returns, which `#83` was refuted for. Each builder refuses with its own existing
+  typed error. The check runs immediately after the release-character guard, so nothing that guard
+  pinned moves and its equality test is byte for byte unchanged.
+
+  **🛑 What a caller catches MOVES, in both directions.** At base most mis-shaped sets failed as an
+  `X12ParseError` with `X12_INVALID_DELIMITERS` escaping out of the `build*` call, carrying a 64-byte
+  `snippet` of the interchange just composed. They now refuse earlier with that builder's own error
+  and its existing code, **so a consumer catching the parse class around a `build*` call stops
+  catching and one catching the build class starts.**
+
+  **🛑 It refuses shapes that built with `warnings: []`, and no count of them is published** - a
+  draft said "two" and one more turned up the moment a shape the census had not enumerated was tried.
+  **The plausible one is `segmentTerminator: "~\r\n"`.** If you declared that to get line-broken output it never produced
+  any: CR/LF between segments is tolerated on READ, so the model recorded `~` and `serializeX12`
+  emitted no line breaks. Reading a file written that way is unaffected; only declaring it on emit
+  is.
+
+  **🛑 The read side and `serializeX12` are untouched.** `parseX12` accepts everything it accepted
+  before, because documents declaring these sets exist and Postel's Law puts them on the lenient
+  half. A letter or digit is still an admissible delimiter: ASC X12 constrains a delimiter by
+  position, not by character class, and a delimiter that collides with the DATA is a different
+  family that this does not close.
+
+- **🩺 BREAKING (emit side): a delimiter set in which the release character `?` is also a delimiter
+  is REFUSED by every builder, in all FOUR roles** (`X12-EMIT-DEGENERATE-RELEASE-DELIMITER`).
+  Reproduced on the base tree at `51de7b2`.
+
+  **The property, stated so one more trigger byte cannot falsify it.** `escapeRelease` protects a
+  byte by **prefixing** `?` to it, in whatever role `?` was declared, so when `?` is one of the four
+  delimiters the protection is emitted as structure. The inverse holds at the same time: a builder
+  joins composites with the component separator and repetitions with the repetition separator, so
+  where either of those IS `?` the library's own structural join is emitted as an escape sequence.
+
+  **Two mechanisms, and only the first involves a caller's value.** The filed defect named the first
+  and reached three roles; measured, the class is four roles, and the second mechanism fires on
+  documents in which no value carries any trigger byte at all:
+
+  ```text
+  elementSeparator "?"     buildInterchange ["CLM","PATIENT?ACCT","150.00"]
+                             reads ["CLM","PATIENT","","ACCT","150.00"]
+  segmentTerminator "?"    buildInterchange ["CLM","PAT*ACCT","150.00"]
+                             CLM-01 reads "PAT", a phantom segment follows
+  componentSeparator "?"   build837P, EVERY document, no trigger byte:
+                             SV1-01-2 (the procedure code) reads undefined
+                             HI-01-2 (the diagnosis code) reads undefined
+  repetitionSeparator "?"  build271, EVERY document, no trigger byte:
+                             EB-03 "30" + "1" reads back as one code "30?1"
+  warnings: [] on every row.
+  ```
+
+  🩺 The second mechanism is the sharper one: a procedure code and a diagnosis code are what a claim
+  is adjudicated on, and neither the caller nor the receiver had any signal that they were fused.
+
+  **⚖️ REFUSE rather than warn, and the whole SET rather than the values that trip.** 005010 does not
+  transmit a release character at all and settles none of this, so the tiebreak is CONSISTENCY with
+  the guards this package already carries on emit and with emit being the strict half of Postel's
+  Law here - the same call `X12-EMPTY-CONTROL-NUMBER-FABRICATED` made one slice earlier. A
+  value-level guard was rejected on measurement: it cannot reach the second mechanism at all, and
+  _"keep `?` out of your values"_ was already refuted once in this arc for protecting nobody. **No
+  warning code is minted and no case moves onto a new code** - each builder refuses with its own
+  existing typed error.
+
+  **🛑 It refuses specs that built at `0.0.15`, including ones that round-tripped through this
+  library's own parser** - `componentSeparator: "?"` with a scalar value did. That round trip is not
+  the bar: ISA-11 and ISA-16 transmit the declared set, so a conformant receiver splits on it, and
+  what this library could read back says nothing about what they read.
+
+  **🛑 A message moves, never a code, and no count of what moved is published.** The check runs where
+  a builder resolves its delimiters, so every guard a builder runs earlier keeps precedence
+  (`build835`'s balance equations, `build837`'s spine, `build999`'s AK9 counts and `buildTA1`'s
+  `enforceAcceptIsClean` all still report first, measured base vs head) and everything later yields.
+  `requireControlNumber` is later in **every** builder that has one, so on a degenerate set both the
+  empty-control-number and the non-string-control-number refusals above are preempted at every one of
+  their slots - same code, different message. A draft of this bullet said _"one report moved"_ and a
+  refuter measured that false, so the ordering is stated and the sites are not counted.
+
+  **🛑 It is an equality test on the value you declare, not a guarantee about the documents this
+  library can compose.** State the bound as a property of the SET, never of the document. Whether a
+  declared value is even shaped like a delimiter is the separate refusal below.
+
+  **🛑 The READ side is deliberately untouched, and so is `serializeX12`.** `parseX12` still accepts
+  every degenerate set and still frames a degenerate body segment; `serializeX12` re-emits one byte
+  for byte, because it works from a model a SENDER's bytes produced. Documents this library emitted
+  before this guard exist, and Postel's Law puts them on the lenient half.
+
+- **🩺 A control number that is not a STRING is refused on emit, so `interchangeControlNumber: []`
+  and `new String("")` no longer fabricate ISA-13 as `000000000`**
+  (`X12-CONTROL-NUMBER-GUARD-NOT-TYPE-CHECKED`). Reproduced on the base tree at `a226595`. The
+  empty-control-number guard above is byte-strict, and byte-strict means a value that is not a string
+  is not `""`, so a non-string walked past it and reached `padControl`, which reads `.length` and
+  then concatenates. Measured through `buildInterchange`:
+
+  ```text
+  interchangeControlNumber: []                 ISA-13 = "000000000"   warnings: []
+  interchangeControlNumber: new String("")     ISA-13 = "000000000"   warnings: []
+  interchangeControlNumber: new String("ABC")  ISA-13 = "000000ABC"   warnings: []
+  interchangeControlNumber: new String(" ")    ISA-13 = "00000000 "   warnings: []
+  ```
+
+  The first two are the **same fabricated `000000000`** the empty guard closed, reached through a
+  different input type. The other two are silent **coercions** of a boxed string, a value this
+  library refuses by name wherever it escapes one. `requireControlNumber` refuses a non-string ahead
+  of the empty test now, reporting the TYPE through `caller-string.ts`'s describer and never echoing
+  the value.
+  - **🛑 No error code is minted and no warning code moves, but DIAGNOSTICS DO MOVE, so "nothing
+    else changed" would be false.** `undefined` and `null` threw a bare `TypeError` with no `code`
+    and now throw the builder's typed refusal, so **a consumer catching `TypeError` there no longer
+    catches**. Shapes that used to make the builder write a malformed fixed-width ISA its own
+    re-parse rejected as `X12_INVALID_DELIMITERS` refuse before anything is written now, so **a
+    predicate on that code stops firing for them**. And **the MESSAGE moved at the control-number
+    slots that already refused a non-string**, because they refuse from this guard one step earlier:
+    same class, same code, wording that names the slot and the spec property. Read that as the
+    property and not as a claim about what the old message said. **If you match on message text at a
+    control-number slot, re-read it.**
+  - **It narrows what a control number may BE, never what it may CONTAIN.** A whitespace-only
+    control number is still accepted, unchanged and by design: trimming would be a
+    normalisation rule and no source consulted for this package states one. The asymmetry that
+    creates is stated rather than smoothed over - `new String(" ")` is refused because it is not a
+    string, and the primitive `" "` is not. A SHORT control number still zero-pads. The ISA's other
+    fixed-width slots go through `pad` rather than `padControl`, are guarded by no control-number
+    test, and a numeric one still throws a bare `TypeError`; disclosed rather than closed.
+
+- **🩺 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`). Reproduced on the base tree at `72bafc2`.
+  `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` accepts `elementSeparator: "?"` from a caller. `src/parser/envelope.ts` guarded
+  that degenerate set in both of its own splitters, once for the segment terminator and once for an
+  envelope segment's elements. `decodeSegment` - which every BODY segment plus the `ST`, the `SE`
+  and every retained orphan goes through - did not. It used the release-aware splitter, where a `?`
+  consumes the byte after it, so on such an interchange no split ever happened:
+
+  ```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 out of a well-formed document.
+  `buildInterchange` disagreed with itself the same way: it returns `parseX12` of the bytes it just
+  wrote, so a caller passing `elementSeparator: "?"` got back a model holding none of the segments
+  it had supplied. **It now reports the segments it wrote, for a value with no `?` in it - read that
+  qualifier, it is load-bearing and the paragraph on the emit side below says why.**
+
+  **🛑 It changes how an already-published document decodes, deliberately**, exactly as the envelope
+  splitter did in the release before it, and on the same tiebreak: CONSISTENCY with the guard this
+  package already carried twice, not a spec clause. 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: this 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`, so unlike that slice there is no direction in
+  which the old framing was the right one.
+
+  **No warning code is added and no case 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 and 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. `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. A literal split of those two
+  roles 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 entry above: those documents exist.**
+
+  **🩺 What else it does not close, pinned rather than left to be rediscovered.** On a degenerate set
+  a `?~` still swallows the segment terminator: `findUnescapedTerminator` guards its own role only,
+  so a segment ending in an empty last element puts a `?` immediately before the terminator and
+  merges with its successor (`PER?IC?NAME?TE?5551234?EX?~SE?3?0001~` frames as one segment and raises
+  `X12_MISSING_SE`). Framing is untouched - but the READ of that merged blob did move, so do not take
+  it as "nothing moved": it now frames, so `~SE` and the SE's control number land in `PER`'s
+  communication-number slots where at base they sat inside one `(non-spec)` element. Values are still
+  RAW, `elements.join(sep)` still reproduces the segment byte for byte, and the ISA stays positional.
+
+- **🩺 `buildInterchange` now release-escapes GS-04, GS-05 and GS-07, so the interchange it hands
+  back reports the group date, group time and responsible agency code you passed**
+  (`X12-INTERCHANGE-GS-EMIT-NOT-RELEASE-AWARE`). Reproduced on the base tree at `837d4bc`. The
+  builder mapped its escaper over GS-01, GS-02, GS-03, GS-06 and GS-08 and wrote `groupDate`,
+  `groupTime` and `responsibleAgencyCode` raw, and 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; what moved was GS-08, the
+  version / release / industry identifier code, which is the element the entry above lets a caller
+  state. All five rows now read the values the caller passed, with an empty warning array.
+
+  **The grounding is inside this package rather than in a spec clause**, the same tiebreak the two
+  entries below record: one function disagreed with itself. It returns `parseX12` of bytes it wrote
+  and then answers a slot out of its neighbour's, and `SegmentSpec`'s documented contract already
+  said the builder applies the release escape so an active delimiter inside a value survives.
+
+  **🛑 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 GS-04 / GS-05 / GS-07.
+
+  **🛑 No warning code is added and no case moves onto a new code. Read the property rather than a
+  direction list:** the interchange the call returns now reports the values the caller passed, where
+  before it reported whatever the shift left in each slot. **What is narrower here than in the two
+  entries below, and is the part to carry away: no reader moved.** No executable line under
+  `src/parser/` changed, so an inbound document from a trading partner decodes exactly as it did at
+  `0.0.15`; what changed is what this library emits, and therefore how its own output reads back.
+  **Say it that way rather than "the parser is untouched"** - this slice's own graded review forced a
+  JSDoc correction in `src/parser/envelope.ts`, where a stale census of the released GS/ST slots had
+  been published.
+
+  **State 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: "|"` a GS-07 of
+  `"X|Y"` is what took GS-08's slot and `"X*Y"` 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** and should drop the hand-rolled escape.
+
+  **A wrong-typed GS element still names its slot.** The type check runs over the unescaped parts, so
+  a numeric `groupDate` refuses with `buildInterchange: "GS"-04 must be a string` rather than
+  degrading to the builder-named message the escaper alone would produce; the five slots that already
+  escaped gained the slot name with it. Same class, same `X12_BUILD_INVALID_SPEC`, and still no echo
+  of the value. **`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.** `esc` releases against the
+  delimiter set the CALLER declared, and a `componentSeparator` of `"S"` is admissible, so mapping
+  the escaper over element 0 would turn the literal `"GS"` into `G?S` and the group header would stop
+  being a `GS`. `GE` / `ST` / `SE` / `IEA` already followed that rule. **Read "literal" strictly:** a
+  `SegmentSpec` body segment carries a CALLER-supplied id, `buildTransaction` has released it since
+  before this slice, and `SegmentSpec`'s own JSDoc still says it is emitted verbatim. That
+  disagreement predates this slice, is unchanged by it, and is filed rather than closed here.
+
+  **What this does not close:** `buildInterchange`'s IEA-02 is padded rather than escaped 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 remain outside both guards; and an unescaped active delimiter is still
+  not safe anywhere, because that is what a delimiter is.
+
 - **🩺 `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
@@ -999,19 +1586,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `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
+  **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. 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.
+  **The read half did not move in THIS entry**, so a control number of `"00000001?"` read back as
+  `"00000001??"` rather than as `"00000001?*260601"`. The `X12-TA1-RESIDUALS` entry above is the one
+  that moved it, and the clause that stood here telling you to apply `unescapeRelease` yourself is
+  **deleted** rather than reworded: the library does it now.
 
   **`BuildTA1Options` gained `repetitionSeparator`, `componentSeparator` and `segmentTerminator`**
   beside the existing `elementSeparator`, the same four `build999` already takes. They exist for