@cosyte/x12 0.0.16 → 0.0.17

package/CHANGELOG.md

@@ -7,8 +7,110 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **🩺 `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
 
+- **`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 `IsaSegment` block is deliberately unchanged**, and no rule about the ISA is stated here in
+  either direction.
+
 - **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,6 +16,70 @@ 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`** (`X12-ISA-ELEMENT-ARITY`). **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:

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",
@@ -196,6 +197,7 @@ var WARNING_MESSAGES = {
   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_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.17";
 
 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;