@cosyte/x12 0.0.16 → 0.0.18

package/CHANGELOG.md

@@ -7,8 +7,240 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **`pnpm check:no-internal-refs` - a gate on internal project bookkeeping reaching a consumer**
+  (`X12-NO-INTERNAL-REFS-GATE`), with `.github/workflows/no-internal-refs.yml` running it on every
+  push and PR. Documentation and tooling only: the `src/` half of the diff is comment-only and
+  `dist/index.mjs` / `dist/index.cjs` are byte-identical base to head.
+
+  It scans `README.md`, `TRADEMARKS.md`, `LICENSE`, `KNOWN-LIMITATIONS.md`, `docs-content/`, the npm
+  `description` and `keywords`, and the `/** */` doc comments under `src/` (which tsup compiles into
+  `dist/index.d.ts` and `dist/index.d.cts`), against six rules: item identifiers, phase and wave
+  language, ADR references, "slice" as our word for a unit of work, meta-repo paths, and bracketed
+  traceability markers. Every rule runs line by line and again over paragraph-joined text, because
+  this repo hard-wraps and a multi-token violation that straddles a wrap is invisible to a line
+  scan: on the sweep this shipped with, 52 of 124 phase-rule hits and 29 of 76 identifier hits in
+  `src/` were visible only to the reflowed pass. `CHANGELOG.md`, `.changeset/`, `CLAUDE.md`,
+  `documentation/`, `scripts/`, `test/` and `//` comments are deliberately out of scope: the
+  convention names those as where the identifiers belong.
+
+  **It is derived from the sibling parsers' copy, not transcribed from it.** Every sibling excludes
+  `X12-\d{3}[A-Z]?` and `X12-\d{6}` as standards designations to protect. In this repo `X12` is also
+  our own project prefix. Counted here with two independent tools that agreed exactly, that pattern
+  matches 141 times across tracked files and **every one of the 141 is an internal identifier**, in
+  eight spellings, with no standards designation among them; the hyphenated standards spelling it
+  exists to protect occurs zero times, because this corpus writes transaction sets and guides bare
+  (`837P`, `005010X222A1`). Carrying the sibling line verbatim reported OK over six live violations
+  on shipping carriers. Both the item spellings and the hyphenated forms are now asserted
+  individually in the self-test, each on its own, after a control run showed a shared positive
+  sample was satisfied by its first entry and covered none of the rest.
+
+  `KNOWN-LIMITATIONS.md` is scanned and is the entry no sibling copy has: this package ships it in
+  `files`, and it held most of what the gate first found.
+
+  **What it cannot do**, stated so a green run is not over-read: it reads the `src/` doc comments
+  that are the SOURCE of the published declarations, never `dist/` itself, which is untracked build
+  output this script does not build. It catches identifiers and named patterns, not ordinary English
+  sentences about how the software came to exist, so the reviewer still owns half the rule. It reads
+  file contents and never file names. It is not yet a required check on this repo, so it reds
+  visibly without blocking a merge.
+
+### Changed
+
+- **`WARNING_MESSAGES.X12_PRE_005010` stops asserting what ISA-12 declares.** The message a consumer
+  reads off `w.message` said _"ISA-12 declares a version other than the HIPAA baseline `00501`, so
+  the input may diverge from 005010 semantics. The declared version is preserved verbatim on the
+  model."_ The guard behind it tests the twelfth element of the ISA split, so both the assertion
+  about ISA-12 and the phrase "the declared version" presuppose a header that framed. **This is a
+  runtime value, not a comment: `dist/index.mjs` and `dist/index.cjs` change here, and that is the
+  difference from the comment-only slice above.** No guard, no code, no position and no control flow
+  moved: the same interchanges raise the same codes at the same positions as before.
+
+  Measured on one interchange per row, reading ISA-12 at its own fixed byte offset and
+  again off the split:
+
+  ```text
+  construction             ISA-12 at its fixed offset  elements[12]  X12_PRE_005010  other codes
+  spec-clean               "00501"                     "00501"       silent          -
+  ISA-12 declares 00401    "00401"                     "00401"       FIRES           -
+  ISA-05 carries `*`       "00501"                     "^"           FIRES           X12_ISA_EXTRA_ELEMENT_SEPARATOR, X12_CONTROL_NUMBER_MISMATCH
+  ISA-06 carries `*`       "00501"                     "^"           FIRES           X12_ISA_EXTRA_ELEMENT_SEPARATOR, X12_CONTROL_NUMBER_MISMATCH
+  ISA-08 carries `*`       "00501"                     "^"           FIRES           X12_ISA_EXTRA_ELEMENT_SEPARATOR, X12_CONTROL_NUMBER_MISMATCH
+  ISA-13 carries `*`       "00501"                     "00501"       silent          X12_ISA_EXTRA_ELEMENT_SEPARATOR
+  ```
+
+  The replacement names the element the guard read, states that raising the code does not establish
+  that the header split into `ISA` plus 16 elements, and points at `isa.raw`. It echoes no value, so
+  the message stays a static table lookup with no consumer bytes in it. `pre005010`'s docblock twin
+  of the same clause moves with it, which is why the two were left in agreement rather than
+  corrected one at a time. The shipped troubleshooting table carried a third spelling of the same
+  assertion ("ISA-12 declares a version family other than `00501`") and is corrected too.
+
+- **Internal project bookkeeping removed from the markdown surface, the npm metadata and the
+  shipped doc comments.** Deliberately not "from every surface a consumer reads": source string
+  literals are outside this gate, and five bundled code-list snapshots still carry build-order
+  framing in an exported `note` field, which reaches `dist/index.mjs` and `dist/index.cjs` as a
+  runtime value. That is a different carrier with a different review path, it reproduces on the base,
+  and it is filed rather than folded in here. Item identifiers, "phase" build-order framing and
+  "slice" as a unit of work were translated into what the software does and what changed, in
+  `KNOWN-LIMITATIONS.md`, `docs-content/cookbook.md`, `docs-content/troubleshooting.md` and the doc
+  comments across `src/`. Nothing was deleted to
+  satisfy the gate: a doc comment removed rather than reworded would be a regression, since JSDoc
+  with `@example` on every public export is a guardrail neither lint nor coverage protects. Two
+  pages sent the reader to the package's `CLAUDE.md`, which the tarball does not ship; they now
+  point at `README.md` and the Cookbook. Measured on a local build of base commit `a3e081d`,
+  `dist/index.d.ts` carried 13 lines of item identifiers, 64 of phase and wave framing, 2 of
+  "slice" jargon and 1 meta-repo path, with `dist/index.d.cts` byte-identical to it; at head all
+  four counts are zero and the two twins remain byte-identical to each other. Zero on the rules is
+  the weaker statement: six lines of phase framing survived the first sweep while every rule read
+  zero, four ending in punctuation and two using the PLURAL `Phases`, which rule 2 cannot see because
+  it requires `phase` followed by an alphanumeric. All six were then translated, so the built
+  declaration file now contains no occurrence of the word at all. The plural form remains ungated and
+  is disclosed as such.
+
+- **🩺 `X12_ISA_EXTRA_ELEMENT_SEPARATOR` - the ISA element split now has an arity check**
+  (`X12-ISA-ELEMENT-ARITY`). Additions-only: no decoding moved, no existing warning was suppressed or
+  narrowed, and nothing is re-framed.
+
+  `decodeIsa` splits the 105-byte ISA element area on the element separator, and the comment above it
+  asserted the result was "exactly 17 entries by construction because the element-separator-position
+  guard in `delimiters.ts` already verified the layout". That guard verifies the separator at all 16
+  fixed 005010 positions, which bounds the split from BELOW - it can never come out short. It was
+  never bounded from above. An ISA element value carrying that same byte splits again, so the element
+  comes back a prefix and everything after it is displaced. **How far is not derivable from
+  `isa.elements`**: more than one element can carry an extra separator, and one sitting between two
+  of them is displaced less than one sitting after both. `isa.raw` plus the ISA's fixed widths is the
+  only route back.
+
+  Planting the element separator inside each of the 16 fixed elements of one conformant interchange,
+  measured at `0.0.16`:
+
+  ```text
+  planted in   split parts   warnings at 0.0.16
+  ISA-01..10   18            X12_PRE_005010, X12_CONTROL_NUMBER_MISMATCH
+  ISA-11       -             X12_INVALID_DELIMITERS (Tier-3, reached first)
+  ISA-12       18            X12_PRE_005010, X12_CONTROL_NUMBER_MISMATCH
+  ISA-13       18            X12_CONTROL_NUMBER_MISMATCH
+  ISA-14       18            (none)
+  ISA-15       18            (none)
+  ISA-16       -             X12_INVALID_DELIMITERS (Tier-3, reached first)
+  ```
+
+  ISA-11 and ISA-16 ARE the in-band repetition and component separator declarations, so the plant
+  collides with them and the Tier-3 refusal reaches it before any of this. That is a boundary of the
+  probe, not a property of those two elements.
+
+  On the `ISA-01..10` and `ISA-12` rows the document declares `00501` at ISA-12's own fixed offset and
+  `X12_PRE_005010` fires anyway; `elements[13]`, the interchange control number and the reassociation
+  key, answers `"00501"`; and `elements[15]`, the test/production usage indicator, answers `"0"` on a
+  document whose ISA-15 says `P`. The `ISA-14` and `ISA-15` rows were reported on no channel at all.
+
+  `parseX12` raises the new warning BEFORE the ISA-derived checks that read `elements[12]` and
+  `elements[13]` by index, because when it fires those two may be reading a displaced element rather
+  than the one they name. `{ strict: true }` therefore escalates on it rather than on the warning that
+  follows. **That is a statement about `ix.warnings` and `onWarning` only.** `serializeX12(ix,
+{ specClean: true })` reconciles ISA-13 against IEA-02 off `isa.elements[13]` with no arity
+  awareness and never raises this code, so on that channel a lone `X12_CONTROL_NUMBER_MISMATCH` can be
+  a displaced read of a control number that matches byte for byte at its fixed span, and the absence
+  of this warning there is not evidence the header framed. Pre-existing, disclosed, not fixed.
+
+  **It is a report, not a repair.** A byte that is both an element's content under the ISA's fixed
+  widths and the separator that same segment declares in-band has two readings; the interchange is
+  not 005010-conformant either way, and nothing anyone here has read settles which reading to take,
+  so `isa.elements` is left exactly as the split produced it and `isa.raw` still carries all 106
+  bytes, which is the route back.
+
+  **The emit side is untouched, and this is not a build-side guard.** The fixed-width ISA slots go
+  through `pad` / `padControl` and never through the caller escaper, so `buildInterchange` still
+  writes such a caller value straight onto the wire. It does now surface there, because
+  `buildInterchange` returns `parseX12` of the bytes it just wrote:
+  `interchangeControlNumber: "0000*0001"` came back with ISA-13 reading `"0000"`, ISA-15 reading
+  `"0"` instead of `"P"`, IEA-02 displaced the same way so the control-number reconciliation agreed
+  with the misreading, and `warnings: []`.
+
 ### Documentation
 
+- **`IsaSegment` and the `X12_PRE_005010` warning factory no longer document a raw ISA element as the
+  value it holds** (`X12-ISA-VALUE-POINTERS`). **Documentation only: the diff is comment-only, and
+  `dist/index.mjs` and `dist/index.cjs` are byte-identical before and after, so no behaviour moved.**
+  The corrected text ships in `dist/index.d.ts` and `dist/index.d.cts`.
+
+  `isa.elements` holds raw byte text. `IsaSegment` called it "the 16 ISA values" and its `@example`
+  handed out `isa.elements[12]; // ISA-12 - version, expected "00501"` and
+  `isa.elements[13]; // ISA-13 - interchange control number`, while `pre005010`'s JSDoc said "The
+  declared version stays on `isa.elements[12]`". Measured on 005010 interchanges, one per row, plus
+  two rows this library emitted and read back:
+
+  ```text
+  construction                         cell          stated / at that ISA offset  elements[n]  warnings
+  spec-clean                           elements[12]  "00501"                      "00501"      []
+  spec-clean                           elements[13]  "000000001"                  "000000001"  []
+  ISA-12 declares 00401                elements[12]  "00401"                      "00401"      X12_PRE_005010
+  ISA-06 carries `*`                   elements[12]  "00501"                      "^"          X12_ISA_EXTRA_ELEMENT_SEPARATOR, X12_PRE_005010, X12_CONTROL_NUMBER_MISMATCH
+  ISA-06 carries `*`                   elements[13]  "000000001"                  "00501"      X12_ISA_EXTRA_ELEMENT_SEPARATOR, X12_PRE_005010, X12_CONTROL_NUMBER_MISMATCH
+  ISA-13 carries `*`                   elements[12]  "00501"                      "00501"      X12_ISA_EXTRA_ELEMENT_SEPARATOR
+  ISA-13 carries `*`                   elements[13]  "0000*0001"                  "0000"       X12_ISA_EXTRA_ELEMENT_SEPARATOR
+  ISA-13 carries `?`                   elements[13]  "00000001?"                  "00000001?"  X12_CONTROL_NUMBER_MISMATCH
+  this library's own emit, stated " "  elements[13]  " "                          "00000000 "  []
+  this library's own emit, stated "1"  elements[13]  "1"                          "000000001"  []
+  ```
+
+  On the `ISA-06` rows the interchange declares `00501` at ISA-12's own fixed offset,
+  `X12_PRE_005010` fires anyway, and the sentence the consumer was holding sent them to an element
+  that answers `"^"`. On the `ISA-13 carries ?` row the `?` is content, because the ISA split is
+  deliberately not release-aware; its `X12_CONTROL_NUMBER_MISMATCH` is the fixture and not a finding.
+
+  **Two mechanisms falsify a cell on their own** - fixed-width padding, which needs no `?` and no
+  anomaly at all, and the arity displacement `X12_ISA_EXTRA_ELEMENT_SEPARATOR` reports - **so no
+  mechanism is named as the reason, the set of them is not published as closed, and nothing here says
+  which ISA element is special.**
+
+  The `pre005010` pointer is deleted outright, with nothing put back. `IsaSegment` gains the raw
+  label, keeps ISA-12's and ISA-13's semantics restated at segment level where they are true, and its
+  `@example` keeps one indexed pointer plus `.raw`, the same shape the four sibling envelope types
+  already carry. **The label is NOT the siblings' label**: theirs reads "pre-`?`-unescape", which is
+  false on the ISA. **The 1-indexed mapping onto ISA-01..ISA-16 is scoped to a 17-entry split rather
+  than deleted, and no shift is quantified.** No accessor, guard or test was added, and no route is
+  named as the route for reading an ISA element.
+
+- **`IeaSegment`, `GsSegment`, `GeSegment`, `Ta1Segment` and `X12FunctionalGroup` no longer document
+  a raw envelope element as the value it holds** (`X12-ENVELOPE-VALUE-EXAMPLES`). **Documentation
+  only: the diff is comment-only, and `dist/index.mjs` and `dist/index.cjs` are byte-identical
+  before and after, so no behaviour moved.** The corrected text ships in `dist/index.d.ts`.
+
+  **Element values on those segment types are stored RAW, pre-`?`-unescape.** Their JSDoc named the
+  index and then named the value it holds - "IEA-02 interchange control number - must match ISA-13",
+  "GS-06 group control number", "TA1-01 (echoes the prior interchange's ISA-13 control number)" -
+  and repeated the promise inside an `@example` fence, which is the form a consumer copies. Measured
+  on one interchange where each documented non-ISA slot carries the sender-intended value `A*B`,
+  written on the wire in released form `A?*B`, **every one of those cells reads back `"A?*B"` and
+  not `"A*B"`.**
+
+  The same correction is applied to `parseX12`'s own `@example`, which handed out `// "HC"` at
+  `gs.elements[1]`.
+
+  On a `TA1` that `buildTA1` emitted and `parseX12` read back:
+
+  ```text
+  stated TA1-01   emitted TA1                         elements[1]    parseTA1()
+  "000000001"     TA1*000000001*260601*1200*A*000     "000000001"    "000000001"
+  "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"
+  "00000001?"     TA1*00000001??*260601*1200*A*000    "00000001??"   "00000001?"
+  ```
+
+  Every row `warnings: []`. TA1-01 is the reassociation key, so a consumer following the shipped
+  `@example` compared framed bytes against the ISA-13 it was acknowledging. `parseTA1` already read
+  the same bytes correctly, so the package disagreed with itself.
+
+  **Each block now carries the label `X12Segment` has always carried** - "Element values are stored
+  RAW, pre-`?`-unescape" - and the `@example` pointers keep their index and lose the promise. The
+  slot mapping (`elements[2]` = IEA-02) was true and is kept, and so are the element names, the
+  formats and the code-list citations, restated where they are true: as facts about the segment's
+  fields rather than about a raw element. No accessor, guard or test was added, and **no route is
+  named as the route.**
+
 - **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.**

package/KNOWN-LIMITATIONS.md

@@ -16,13 +16,77 @@ model.
 
 ## Data / decode boundaries
 
+- **🩺 An ISA element carrying the element separator makes the header split into more than
+  `ISA` + 16 elements. Through `0.0.16` no check saw that at all; it is now reported as
+  `X12_ISA_EXTRA_ELEMENT_SEPARATOR`.** **Nothing is
+  re-framed: this is a report, not a repair, and no existing warning was suppressed or narrowed.**
+
+  `detectDelimiters` verifies the element separator at all 16 fixed 005010 byte positions, so the
+  ISA split can never come out SHORT. It was never bounded from ABOVE. An element value carrying
+  that same byte splits again, so that element comes back a **prefix** and everything after it is
+  **displaced**. **🛑 How far is NOT derivable from `isa.elements`, and no arithmetic on it works.**
+  More than one element can carry an extra separator, and an element sitting between two of them is
+  displaced less than one sitting after both; `isa.raw` plus the ISA's fixed widths is the only route
+  back. Measured on one conformant interchange, planting the element separator inside each of the 16
+  fixed elements in turn:
+
+  ```text
+  planted in   split parts   warnings through 0.0.16
+  ISA-01..10   18            X12_PRE_005010, X12_CONTROL_NUMBER_MISMATCH
+  ISA-11       -             X12_INVALID_DELIMITERS (Tier-3, thrown before any of this)
+  ISA-12       18            X12_PRE_005010, X12_CONTROL_NUMBER_MISMATCH
+  ISA-13       18            X12_CONTROL_NUMBER_MISMATCH
+  ISA-14       18            (none)
+  ISA-15       18            (none)
+  ISA-16       -             X12_INVALID_DELIMITERS (Tier-3, thrown before any of this)
+  ```
+
+  ISA-11 and ISA-16 **are** the in-band repetition and component separator declarations, so planting
+  the element separator there collides with them and the Tier-3 refusal reaches it first. That is a
+  boundary of the probe, not a claim that those two elements are special.
+
+  **What the displaced reads cost, on the rows that had a warning as much as on the rows that had
+  none.** On the `ISA-01..10` and `ISA-12` rows the interchange declares `00501` at ISA-12's own
+  fixed offset and `X12_PRE_005010` fires anyway, because `elements[12]` has become the repetition
+  separator; `elements[13]`, the interchange control number and the reassociation key, answers
+  `"00501"`; and `elements[15]`, the test/production usage indicator, answers `"0"` on a document
+  whose ISA-15 says `P`. On the `ISA-13` row the control number is a prefix. **The `ISA-14` and
+  `ISA-15` rows carried `warnings: []`** while the usage indicator read empty.
+
+  **The route back is `isa.raw`**, which still carries all 106 bytes verbatim, and the ISA's fixed
+  widths make the transmitted span of any element recoverable from it. Recovering it is **your**
+  decision, not this library's: a byte that is both an element's content under those fixed widths and
+  the separator the same segment declares in-band has two readings, the interchange is not
+  005010-conformant either way, and nothing anyone here has read says which reading to take. So the
+  parser reports that the header did not frame and leaves `isa.elements` exactly as the split
+  produced it.
+
+  **When this warning is present, treat every other ISA-derived diagnostic on that interchange as
+  provisional.** `parseX12` raises it ahead of the ones it raises after it for that reason, which
+  also means `{ strict: true }` escalates on it rather than on the displaced-value warning that
+  follows. **🩺 Read that as a statement about `ix.warnings` and `onWarning`, and about nothing
+  else.** `serializeX12(ix, { specClean: true })` reconciles ISA-13 against IEA-02 off
+  `isa.elements[13]` with no arity awareness and **never raises this code at all**, so on that
+  channel a lone `X12_CONTROL_NUMBER_MISMATCH` can be a displaced read of a control number that in
+  fact matches byte for byte at its fixed span, and **the absence of this warning there is not
+  evidence the header framed**. Pre-existing, disclosed, not fixed here.
+
+  **The emit side is unchanged and is NOT guarded by this.** The fixed-width ISA slots go through
+  `pad` / `padControl` and never through the caller escaper, so `buildInterchange` still writes a
+  caller value carrying the element separator straight onto the wire. What changed is that
+  `buildInterchange` returns `parseX12` of the bytes it just wrote, so the report now reaches that
+  path too: `interchangeControlNumber: "0000*0001"` used to come back with ISA-13 reading `"0000"`,
+  ISA-15 reading `"0"` instead of `"P"`, IEA-02 displaced the same way so the control-number
+  reconciliation **agreed with the misreading**, and `warnings: []`. Refusing such a value on emit is
+  a decision about the build side and is not taken here.
+
 - **🩺 `parseTA1`'s five decoded fields are POST-`?`-unescape as of this release, and an EMPTY
-  TA1-02 / TA1-03 / TA1-04 / TA1-05 is REFUSED on emit. Both are behaviour changes**
-  (`X12-TA1-RESIDUALS`). They are one slice because they are the two ends of the same disagreement:
+  TA1-02 / TA1-03 / TA1-04 / TA1-05 is REFUSED on emit. Both are behaviour changes.**
+  They are one change because they are the two ends of the same disagreement:
   this package's emit half releases a TA1 element and its read half decoded the escape rather than
   the value.
 
-  **The read half.** `X12-TA1-EMIT-NOT-RELEASE-AWARE` made `buildTA1` release all five caller
+  **The read half.** An earlier release made `buildTA1` release all five caller
   elements, and `parseTA1` kept reading `elements` verbatim, so a round trip through this package's
   own halves was not an identity for any value carrying a delimiter or the release character.
   Measured at `0.0.15`, over `parseX12` + `parseTA1` of what `buildTA1` had just emitted:
@@ -69,12 +133,12 @@ model.
     first, so an `ackCode: "A"` with an empty note still reports `X12_TA1_ACCEPT_WITH_NOTE`; TA1-01
     still draws the control-number refusal; and every wrong-TYPED element still draws the escape
     helper's refusal, because all five escapes run before any emptiness test. **No spec that was
-    refused before this slice is refused differently by it.**
-  - **No census of other builders' required elements is published here.** This slice measured TA1.
+    refused before this change is refused differently by it.**
+  - **No census of other builders' required elements is published here.** This change measured TA1.
 
 - **🩺 `implementationConventionReference` is POST-`?`-unescape as of this release, in every typed
   reader that publishes it, and that is a behaviour change on documents whose `ST-03` carries a
-  release escape** (`X12-ST03-READ-NOT-RELEASE-AWARE`). `tx.st.elements` is the ST segment as framed:
+  release escape.** `tx.st.elements` is the ST segment as framed:
   post-element-split and PRE-unescape. Five public
   readers were handing one of those strings straight back on the model - `get837Claims`,
   `get277Status`, `get277CADisposition`, `get278Request` and `get278Response` - so a sender that
@@ -119,8 +183,8 @@ model.
     `unescapeRelease` to `submission.implementationConventionReference` yourself, drop that call.
 
 - **🩺 An EMPTY control number is REFUSED on emit as of this release, where it used to be
-  FABRICATED, and that is a behaviour change for any caller passing one**
-  (`X12-EMPTY-CONTROL-NUMBER-FABRICATED`). Every builder that assembles an ISA zero-pads its control
+  FABRICATED, and that is a behaviour change for any caller passing one.**
+  Every builder that assembles an ISA zero-pads its control
   number to the nine characters ASC X12 .5 fixes ISA-13 at. `padControl("1", 9)` answering
   `"000000001"` is the point of that; `padControl("", 9)` answering `"000000000"` was not, and
   nothing stood in front of it, so `interchangeControlNumber: ""` produced a frozen, well-formed
@@ -173,7 +237,7 @@ model.
     `X12_ACK_INVALID_SPEC` now. If you branch on a specific builder error code, that pairing moved.
 
 - **🩺 Which `ST-03` implementation-convention references resolve to an 837 variant CHANGED in this
-  release, and some already-published files therefore decode differently** (`X12-VARIANT-ICR-UNGROUNDED`).
+  release, and some already-published files therefore decode differently.**
   Through `0.0.13` `get837Claims` recognised exactly three references: `005010X222A2`, `005010X223A3`
   and `005010X224A2`. **That set contained none of the identifiers HIPAA adopts at 45 CFR 162.1102**
   (`005010X222`, `005010X223` + `005010X223A1`, `005010X224` + `005010X224A1`), **and it was missing
@@ -209,8 +273,8 @@ 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.
-  - **🩺 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
+  - **🩺 CLOSED, in the change after this one: the emit side takes a caller override.**
+    `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
@@ -237,8 +301,7 @@ model.
       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`).
+  element, and that is a SYMMETRIC behaviour change on already-published decoding.**
   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
@@ -293,7 +356,7 @@ model.
     `responsibleAgencyCode`) at this release. A `groupDate` of `"2026060?"` emitted
     `GS*HC*SENDER*RECEIVER*2026060?*1200*1*X*005010X222A1`, which its own return value read as nine
     elements with GS-08 intact through `0.0.14` and read as **eight** at `0.0.15`, GS-08 gone, plus
-    `X12_CONTROL_NUMBER_MISMATCH`. **Closed by `X12-INTERCHANGE-GS-EMIT-NOT-RELEASE-AWARE`** - that
+    `X12_CONTROL_NUMBER_MISMATCH`. **Closed by a later release** - that
     entry is at the top of this section and it is the one that describes the current tree.
 
   - **An envelope element ending in a literal `?` is a dangling release character and is NOT warned.**
@@ -329,8 +392,8 @@ model.
     at `0.0.14` it released GS-02 on emit and then answered GS-08 as `"X"` from its own return value.
 
 - **🩺 A BODY segment in an interchange whose ELEMENT SEPARATOR is `?` now frames its elements,
-  where it used to come back as ONE element with an id of `(non-spec)`**
-  (`X12-BODY-DEGENERATE-RELEASE-SEPARATOR`). `detectDelimiters` reads the element separator
+  where it used to come back as ONE element with an id of `(non-spec)`.**
+  `detectDelimiters` reads the element separator
   positionally out of ISA byte 4 and rejects only control characters, whitespace and a non-distinct
   set, so a sender may declare `?` there, and `buildInterchange` accepted `elementSeparator: "?"`
   from a caller when this was measured (it refuses now - see the emit-side entry below).
@@ -367,8 +430,8 @@ model.
     of them. Splitting those two roles literally would re-frame that as two empty components, so it
     would stop reading a value this library itself wrote. **That reason survives the emit-side
     refusal below - those documents exist**, which is why the read side did not move with it.
-  - **🟢 CLOSED, in the slice after this one, and WIDER than it was filed
-    (`X12-EMIT-DEGENERATE-RELEASE-DELIMITER`): every builder REFUSES a delimiter set in which any of
+  - **🟢 CLOSED, in the change after this one, and WIDER than it was filed:
+    every builder REFUSES a delimiter set in which any of
     the four roles is `?`.** The entry as filed named the element separator and one mechanism - a
     caller VALUE the escape cannot protect, because the protecting `?` is itself the separator. Two
     things were measured wrong about that:
@@ -433,7 +496,7 @@ model.
     terminator.** `findUnescapedTerminator` guards its own role only, so with `?` as the element
     separator a segment that ends in an EMPTY LAST ELEMENT puts a `?` immediately before the
     terminator and the scanner reads it as an escape: `PER?IC?NAME?TE?5551234?EX?~SE?3?0001~` frames
-    as ONE segment and raises `X12_MISSING_SE`. This slice does not touch framing. But **the READ of
+    as ONE segment and raises `X12_MISSING_SE`. This change does not touch framing. But **the READ of
     that merged blob did move, so do not take "framing is untouched" as "nothing about this residual
     moved"**: at `0.0.15` the merge produced one `(non-spec)` element no walker looked at, and here
     it frames, so `~SE` and the SE's own control number land in `PER`'s communication-number slots.
@@ -446,8 +509,8 @@ model.
     gives: it is fixed-width, which is what lets the delimiters be recovered from it at all.
 
 - **🩺 `buildInterchange` now RELEASES GS-04, GS-05 and GS-07, so the interchange it hands back
-  reports the values you passed, and the bytes it writes for such a value CHANGED**
-  (`X12-INTERCHANGE-GS-EMIT-NOT-RELEASE-AWARE`). Through `0.0.15` it mapped its release escaper over
+  reports the values you passed, and the bytes it writes for such a value CHANGED.**
+  Through `0.0.15` it mapped its release escaper over
   GS-01, GS-02, GS-03, GS-06 and GS-08 and wrote `groupDate` (GS-04), `groupTime` (GS-05) and
   `responsibleAgencyCode` (GS-07) raw. It returns `parseX12` of the bytes it just wrote, so a value
   carrying an active delimiter in one of those three took a slot of its own and shifted every element
@@ -508,8 +571,8 @@ model.
     active delimiter is still not safe anywhere, because that is what a delimiter is.
 
 - **🩺 `buildTA1` now RELEASES its five caller-supplied elements, so an Accept acknowledgment this
-  library emits no longer reads back as a Reject, and the bytes it writes for such a value CHANGED**
-  (`X12-TA1-EMIT-NOT-RELEASE-AWARE`). Through `0.0.14` `buildTA1` joined the five values with the
+  library emits no longer reads back as a Reject, and the bytes it writes for such a value CHANGED.**
+  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
@@ -560,19 +623,19 @@ model.
     No total is published: that is what was measured, not a closed account. (`getSegmentValue`
     takes an `X12Segment` and `Ta1Segment` carries no `id`, so add one to read a TA1 through it.)
     **🩺 A clause naming `parseTA1`'s fields as a third such surface stood here and is DELETED, not
-    reworded** - `X12-TA1-RESIDUALS` made those fields post-unescape, so it is measured false.
+    reworded** - a later release made those fields post-unescape, so it is measured false.
   - **A caller who was hand-rolling the escape** (the remedy this file named while the defect was
     open) regresses on both kinds of surface: `"00000001??"` in, `TA1*00000001????*…` out, and
     `getSegmentValue` answering `"00000001??"` where it answered `"00000001?"`. The framing and the
     disposition stay correct, but **drop the hand-rolled escape.**
-  - **An EMPTY control number was not refused by this slice, and is refused by the NEXT one.**
+  - **An EMPTY control number was not refused by this change, and is refused by the NEXT one.**
     `escapeRelease` early-returns on `""` and `buildTA1` carried no required-field guard, so
     `interchangeControlNumber: ""` emitted `TA1**260601*1200*A*000` with `warnings: []`, here and at
-    every earlier release. `X12-EMPTY-CONTROL-NUMBER-FABRICATED` closed it across every builder; see
+    every earlier release. A later release closed it across every builder; see
     the entry at the top of this file, including the whitespace-only residual it leaves open.
-  - **🩺 The READ half did not move IN THIS SLICE, and `X12-TA1-RESIDUALS` is the one that moved
+  - **🩺 The READ half did not move IN THIS CHANGE, and a later release is the one that moved
     it** - see the entry at the top of this file. A control number of `"00000001?"` read back as
-    `"00000001?*260601"` before this slice and as `"00000001??"` after it; the clause that stood
+    `"00000001?*260601"` before the EMIT half moved and as `"00000001??"` after it; the clause that stood
     here telling callers to apply `unescapeRelease` themselves is **deleted, not reworded**, because
     the library now does it.
   - **The release is scoped to the delimiter set the CALLER states.** `BuildTA1Options` gained
@@ -593,12 +656,12 @@ model.
     `X12_TA1_ACCEPT_WITH_NOTE` and still runs first.
   - **What this does NOT close.** `buildTA1` still uses no segment joiner, so its refusal names the
     builder and never the slot; `buildInterchange` did not escape GS-04 / GS-05 / GS-07 at this
-    release, which `X12-INTERCHANGE-GS-EMIT-NOT-RELEASE-AWARE` then closed; and an unescaped active
+    release, which a later one then closed; and an unescaped active
     delimiter is still not safe anywhere, because that is what a delimiter is.
 
 - **🩺 BREAKING for `build277` callers: a 277 service line now REQUIRES `unitsOfService`, because
-  SVC-07 is a required element in `005010X212` and this library was not emitting it at all**
-  (`X12-277-SVC07-NOT-DECODED`). Through the release before this one `get277Status` read SVC-01
+  SVC-07 is a required element in `005010X212` and this library was not emitting it at all.**
+  Through the release before this one `get277Status` read SVC-01
   through SVC-04 and stopped, and `build277` emitted exactly those four, so **every X212 277 this
   library produced with a Loop 2220 service line was short a required element** and every 277 it read
   silently discarded the submitted units. Both sides are fixed: `X12ServiceLineStatus.unitsOfService`
@@ -632,7 +695,7 @@ model.
   string** - at base the same spec emitted a bare `SVC~`, because the SVC-07 slot did not exist. `SVC-03` (Line Item Payment
   Amount) is usage **R** in X212 and usage **N** in X214 and is optional in both builders. And the
   read side is unchanged and still lenient: an X212 277 arriving with no SVC-07 raises **no
-  warning**, because that would need a new Tier-2 registry code and the defect this slice closes is
+  warning**, because that would need a new Tier-2 registry code and the defect this change closes is
   on the emit side. All of it is pre-existing and reproduces at `e3cdf49`; widening the guard would
   have turned this into that audit, which is its own item.
 
@@ -1178,7 +1241,7 @@ Code"`, `SVC05 / 380 / "Units of Service Paid Count"`, `SVC06 / C003`,
 
   **`undefined` on either quantity still means "not decoded", not "absent".** The element may have
   been missing, or present and unparseable as a decimal; the two share one `undefined` on the model.
-  They no longer share a silence: as of `X12-QUANTITY-SILENT-DEFAULTS` the unparseable case raises
+  They no longer share a silence: as of an earlier release the unparseable case raises
   `X12_UNPARSEABLE_DECIMAL` at that `position.elementIndex` and the absent case raises nothing, so a
   warning at the element is what tells them apart. The verbatim element is still on `tx.segments`.
 
@@ -1188,7 +1251,7 @@ Code"`, `SVC05 / 380 / "Units of Service Paid Count"`, `SVC06 / C003`,
   no warning. Re-emitting from the model with this release produces conformant bytes.
 
   **The 277's SVC-07 is a different element in a different TR3 and is now decoded and emitted in its
-  own right** (`X12-277-SVC07-NOT-DECODED`, below). Do not read either field off the other.
+  own right** (see the 277 entry below). Do not read either field off the other.
 
 - **Bundled code-list snapshots are pre-launch initial subsets, not the full WPC-published lists.**
   CARC, RARC, Claim-Status-Category (CSCC), Claim-Status (CSC), service-type, CLP-status, and
@@ -1445,7 +1508,7 @@ N-char spec limit` refusal, one per emitting module, where the branch fires **be
   **Read the "through a builder's segment joiner" qualifier literally.** `buildTA1` does not use one,
   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
+  silently (`TA1**250101*1200*A*000`); a later release 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`.
@@ -1617,5 +1680,5 @@ the maintainers have not reviewed.
 
 ---
 
-For the phase-by-phase surface and the exact fields each helper decodes, see the package's
-[`CLAUDE.md`](./CLAUDE.md) status section and the [Cookbook](./docs-content/cookbook.md).
+For the per-transaction read and emit surface, and the exact fields each helper decodes, see
+[`README.md`](./README.md) and the Cookbook on the documentation site.

package/dist/index.cjs

@@ -121,6 +121,7 @@ function detectDelimiters(raw) {
 var WARNING_CODES = {
   X12_CONTROL_NUMBER_MISMATCH: "X12_CONTROL_NUMBER_MISMATCH",
   X12_PRE_005010: "X12_PRE_005010",
+  X12_ISA_EXTRA_ELEMENT_SEPARATOR: "X12_ISA_EXTRA_ELEMENT_SEPARATOR",
   X12_GROUP_COUNT_MISMATCH: "X12_GROUP_COUNT_MISMATCH",
   X12_TRANSACTION_COUNT_MISMATCH: "X12_TRANSACTION_COUNT_MISMATCH",
   X12_SEGMENT_COUNT_MISMATCH: "X12_SEGMENT_COUNT_MISMATCH",
@@ -195,7 +196,8 @@ var WARNING_MESSAGES = {
   X12_CONTROL_NUMBER_MISMATCH_INTERCHANGE: "Control number mismatch: ISA-13 (header) and IEA-02 (trailer) disagree. Both values are preserved verbatim on the model; neither is echoed here.",
   X12_CONTROL_NUMBER_MISMATCH_GROUP: "Control number mismatch: GS-06 (header) and GE-02 (trailer) disagree. Both values are preserved verbatim on the model; neither is echoed here.",
   X12_CONTROL_NUMBER_MISMATCH_TRANSACTION: "Control number mismatch: ST-02 (header) and SE-02 (trailer) disagree. Both values are preserved verbatim on the model; neither is echoed here.",
-  X12_PRE_005010: 'ISA-12 declares a version other than the HIPAA baseline "00501", so the input may diverge from 005010 semantics. The declared version is preserved verbatim on the model.',
+  X12_PRE_005010: 'The twelfth element of the ISA split does not read "00501", the HIPAA baseline interchange control version number, so the input may diverge from 005010 semantics. Whether that element is ISA-12 is NOT established here: where `X12_ISA_EXTRA_ELEMENT_SEPARATOR` is also present on this interchange the header did not split into `ISA` plus 16 elements, so the element read may be a displaced one. All 106 ISA bytes are preserved verbatim on `isa.raw`, which with the ISA fixed widths is the route back. Nothing is echoed here.',
+  X12_ISA_EXTRA_ELEMENT_SEPARATOR: "The ISA element area carries at least one element separator beyond the 16 sitting at their fixed 005010 byte positions, so the header does not split into `ISA` plus 16 elements. `isa.elements` is that split as it came out: an element containing an extra separator comes back a prefix and everything after it is displaced. How far is NOT derivable from `isa.elements`, so any other ISA-derived diagnostic on this interchange may be reporting a displaced value. All 106 bytes are preserved verbatim on `isa.raw`, which with the ISA's fixed widths is the route back. Which reading is correct - the byte as data under the ISA's fixed widths, or as a separator - is NOT decided here, and nothing is re-framed.",
   X12_GROUP_COUNT_MISMATCH: "IEA-01 does not equal the number of GS..GE groups actually present in the interchange. The declared count is preserved verbatim on the model and is NEVER silently corrected.",
   X12_TRANSACTION_COUNT_MISMATCH: "GE-01 does not equal the number of ST..SE transaction sets actually present in the group. The declared count is preserved verbatim on the model and is NEVER silently corrected.",
   X12_SEGMENT_COUNT_MISMATCH: "SE-01 does not equal the number of segments actually present in the transaction set it closes. The declared count is preserved verbatim and is corrected only on `serializeX12(ix, { specClean: true, recomputeCounts: true })`.",
@@ -284,6 +286,13 @@ function pre005010(position) {
     position
   };
 }
+function isaExtraElementSeparator(position) {
+  return {
+    code: WARNING_CODES.X12_ISA_EXTRA_ELEMENT_SEPARATOR,
+    message: WARNING_MESSAGES.X12_ISA_EXTRA_ELEMENT_SEPARATOR,
+    position
+  };
+}
 function groupCountMismatch(position) {
   return {
     code: WARNING_CODES.X12_GROUP_COUNT_MISMATCH,
@@ -1048,6 +1057,7 @@ function collectElementValues(seg, start, end, delimiters) {
 }
 
 // src/parser/envelope.ts
+var ISA_DECODED_PART_COUNT = 17;
 function decodeIsa(raw, delimiters) {
   const isaRaw = raw.slice(0, ISA_MIN_LENGTH);
   const isaHead = isaRaw.slice(0, ISA_MIN_LENGTH - 1);
@@ -1114,6 +1124,9 @@ function decodeEnvelope(raw, delimiters) {
     warnings.push(w);
   };
   const isa = decodeIsa(raw, delimiters);
+  if (isa.elements.length !== ISA_DECODED_PART_COUNT) {
+    warnings.push(isaExtraElementSeparator({ segmentIndex: 0, interchangeIndex: 0 }));
+  }
   const isa12 = el(isa.elements, 12);
   if (isa12 !== "00501") {
     warnings.push(pre005010({ segmentIndex: 0, interchangeIndex: 0, elementIndex: 12 }));
@@ -10723,7 +10736,7 @@ var profiles = Object.freeze({
 });
 
 // src/index.ts
-var VERSION = "0.0.16";
+var VERSION = "0.0.18";
 
 exports.ACK_BUILD_ERROR_CODES = ACK_BUILD_ERROR_CODES;
 exports.ALL_WARNING_MESSAGES = ALL_WARNING_MESSAGES;
@@ -10885,6 +10898,7 @@ exports.isAcceptDisposition = isAcceptDisposition;
 exports.isClaimAdjustmentGroupCode = isClaimAdjustmentGroupCode;
 exports.isDiagnosisQualifier = isDiagnosisQualifier;
 exports.isProcedureQualifier = isProcedureQualifier;
+exports.isaExtraElementSeparator = isaExtraElementSeparator;
 exports.lookupCarc = lookupCarc;
 exports.lookupClaimStatus = lookupClaimStatus;
 exports.lookupClaimStatusCategory = lookupClaimStatusCategory;