@cosyte/x12 0.0.13 → 0.0.14

package/CHANGELOG.md

@@ -9,6 +9,96 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **🩺 `X12_837_SERVICE_SEGMENT_REPEATED`, the 33rd Tier-2 warning code, plus the public factory
+  `serviceSegmentRepeated(position)`** (`X12-837-SV1-OVERWRITE`). A **second** `SV1` / `SV2` / `SV3`
+  arriving inside an **already-open** Loop 2400 now says so, at that repeated segment. Through
+  `0.0.13` it said nothing at all.
+
+  **🩺 What that cost, and it is money and a procedure code.** A service line carries **one** service
+  segment's worth of slots, and every decoder writes **all** of the slots its kind writes. Under an
+  `ST-03` of `005010X222A2`, `SV1*HC:99213*8500*UN*4***1~` followed by `SV1*HC:99999*12*UN*1***1~`
+  inside one `LX` left ONE line reading `charge` **`12`** and `procedureCode` **`99999`**, with
+  `warnings: []`. `8500` became `12`, CPT `99213` became `99999`, and nothing was raised on any
+  channel. **The worst corner is a repeat whose own charge element is ABSENT:** it writes `undefined`
+  over the amount the first one stated, and `X12_837_SERVICE_LINE_NOT_DECODED` does **not** fire
+  there, because a service segment did decode.
+
+  **🛑 THIS CLOSES ONLY THE SILENCE, AND THE RESTRAINT IS THE POINT.** The decode is **not** narrowed:
+  last-wins is unchanged, element for element, so which values a document decodes to are byte-for-byte
+  what they were at `0.0.13`. This reader cannot tell a stray service segment from a conformant one,
+  so choosing the first would be inventing; and changing which occurrence wins changes how
+  **already-published documents decode**. That is the same call made for the `SVx` variant fallback.
+
+  **It fires on a repeat of ANY kind, decoded or not.** One whose kind does not match the resolved
+  variant is read into nothing and overwrites nothing - what it carries reaches no part of the typed
+  model - and it is reported the same way, before or after the matching one.
+
+  **Anchored at the repeated service segment**, with **no `elementIndex`**: what is reported is a
+  second occurrence of the segment, not a defect in an element of it. **Once per repeat**, and the
+  count is scoped to the LINE and never latched, so a first service segment under a later `LX` is a
+  first. It can never name the same segment as `X12_837_SERVICE_SEGMENT_WITHOUT_LX`, which requires
+  that no Loop 2400 be open.
+
+  **It is additive and nothing moved onto it**, pinned by committed tests asserting the whole warning
+  channel with the new code filtered out. **No consumer predicate written against any existing code
+  changes meaning.** Read that as invariance, not as a list of what else you will see.
+
+  **🛑 The package's own documentation was a consumer, and it was blind.** The cookbook's "gate before
+  you post a line amount" recipe named four codes and **none** of them fires on the overwrite
+  document, so a consumer following it posted `12` for a line the sender also sent as `8500`. The
+  cookbook, the troubleshooting table and `KNOWN-LIMITATIONS.md` now name this code beside the other
+  four, and a committed test pins that the four-code gate misses what the five-code gate catches.
+  **The recipe was not the only page:** `spec-notes-money` named `X12_837_SERVICE_LINE_NOT_DECODED`
+  as "the known instance" of an 837 charge reading `undefined` from a slot no reader read, and the
+  repeat corner is a second instance by a different route on which that code does not fire. It now
+  says so.
+
+- **🩺 `X12_837_AMBIGUOUS_VARIANT`, the 32nd Tier-2 warning code, plus the public factory
+  `ambiguous837Variant(position)`** (`X12-837-RESIDUALS`). An 837 whose variant was decided by the
+  `SVx` fallback, in a transaction body that carries service segments for **more than one variant**,
+  now says so at the `ST`. Through `0.0.13` it said nothing at all about that resolution.
+
+  **What that cost.** Variant resolution runs before the walk as
+  `explicitType ?? variantFromIcr ?? variantFromSegment`. Absent a caller `type` option, and where
+  `ST-03` names no implementation convention this reader recognises, the reader falls back to the
+  **first** `SV1` / `SV2` / `SV3` in the body, orphans included. One stray `SV2` ahead of a conformant
+  Professional claim therefore re-types the whole submission Institutional: `submission.variant` reads
+  `"I"`, and a consumer routing on that field sends a Professional claim down an Institutional path.
+  The line-level consequences were reported; **the submission-level typing that produced them was on
+  no channel**, so `submission.variant` carried a confident value with nothing to contradict it.
+
+  **🛑 THIS CLOSES ONLY THE SILENCE, AND THE RESTRAINT IS THE POINT.** The fallback is **not**
+  narrowed and first-wins is unchanged, so on every document that reaches the fallback the variant
+  resolved and the lines decoded are byte-for-byte what they were at `0.0.13`, and this code is added
+  beside whatever the walk already raised. (`X12-VARIANT-ICR-UNGROUNDED`, in this same release,
+  changed WHICH documents reach the fallback; read its entry for what decodes differently.) Excluding orphans from
+  the fallback would change how already-published documents decode and is its own slice.
+
+  **🩺 Which service segment is the stray one is NOT decided.** This reader cannot tell a stray
+  service segment from a conformant one, and the fallback takes the first whether or not a Loop 2400
+  was open at it. Reporting the conflict is honest; picking a winner would be inventing. Re-read with
+  `get837Claims(delimiters, tx, { type })` to decode against a variant you trust.
+
+  **It reports the RESOLUTION, never the document.** A caller `type`, or an `ST-03` naming a known
+  convention, means no guess was made and this code is **not** raised however mixed the body is.
+
+  **Anchored at the `ST`** (`tx.segments[0]`, which carries `ST-03`), with **no `elementIndex`**: the
+  conflict is a property of the body rather than of an element, and one route into it is an `ST-03`
+  that is absent altogether. Raised **once per transaction**, because there is one resolution per
+  transaction, and it can never travel with `X12_837_UNKNOWN_VARIANT`, which is the other outcome of
+  that same resolution.
+
+  **🩺 It is additive, and nothing moved onto it.** `X12_837_SERVICE_LINE_NOT_DECODED`,
+  `X12_837_SERVICE_SEGMENT_WITHOUT_LX` and `X12_837_SERVICE_LINE_DROPPED` fire on exactly the
+  documents they fired on before **this code was added**, in the same positions, pinned by committed
+  tests that assert the whole warning channel with the new code filtered out. **No consumer predicate
+  changes meaning because of this code.** (`X12-VARIANT-ICR-UNGROUNDED`, in this same release, DID
+  change which documents reach the `SVx` fallback; read its entry above.) Read that as **invariance and not as a list of what else you will
+  see** on a contested document: it does not promise that any particular loss on one is reported at
+  all, and one that is not was not reported before this code existed either. A stray `LX` that opened
+  no line, for one, already suppressed `X12_837_SERVICE_SEGMENT_WITHOUT_LX` for the service segments
+  inside it, and still does.
+
 - **🩺 `X12_STATED_AMOUNT_DISCARDED`, the 31st Tier-2 warning code, plus the public factory
   `statedAmountDiscarded(position)`** (`X12-STATED-AMOUNT-DISCARDED`). The entry below reports a row
   whose amount this library could not read. This one is the opposite case: **the reader discarded
@@ -270,6 +360,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **🩺 `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
+  and they were grounded against nothing.
+
+  **🩺 What that cost, measured at `668afea`, which is `main` at published `0.0.13`.** The table held exactly
+  `005010X222A2`, `005010X223A3` and `005010X224A2`. **It contained none of the identifiers HIPAA
+  adopts at 45 CFR 162.1102** (`005010X222`; `005010X223` with its `005010X223A1` Type 1 errata;
+  `005010X224` with `005010X224A1`), **and it was missing `005010X222A1` and `005010X223A2`**, which
+  CMS and state Medicaid companion guides require in ST-03 and GS-08 on production professional and
+  institutional claims. So a conformant, HIPAA-mandated 837P declaring `005010X222A1` resolved to no
+  variant at all, fell through to the `SVx` scan, and one stray `SV2` anywhere in the body re-typed
+  the whole submission Institutional. **The `SVx` fallback was the NORMAL path on production
+  professional and institutional traffic rather than the exception**, and `X12_837_UNKNOWN_VARIANT`
+  on such a file was a fabricated non-conformance claim about a document that was not
+  non-conformant. The sources for every key are named beside the table and in
+  `documentation/agent-notes/x12-variant-icr-ungrounded.md`; the three later published errata guides
+  are the weakest leg and say so in place.
+
+  **🛑 This IS a behaviour change on already-published decoding, and it is disclosed rather than
+  buried.** On a file whose `ST-03` is now recognised: `submission.variant` can differ from what
+  `0.0.13` read, wherever the first `SVx` in the body disagreed with the declaration; and
+  **`X12_837_AMBIGUOUS_VARIANT` and `X12_837_UNKNOWN_VARIANT` no longer fire on it at all**, because
+  no guess was made. **A predicate written against either code goes quiet on such a file.**
+
+  **🩺 And a service line whose `SVx` kind disagrees with the declaration is no longer DECODED, so a
+  code STARTS firing on a document that may have carried `warnings: []`.** Under an `ST-03` of
+  `005010X222A1` with a body whose only service segment is an `SV2`, `0.0.13` read `variant` `"I"`,
+  `charge` `7300`, `units` `2` and `warnings: []`; this release reads `variant` `"P"`, `charge` and
+  `units` `undefined` with the rest of the service segment undecoded, and
+  `X12_837_SERVICE_LINE_NOT_DECODED` at that line's `LX`. **Read only the decimal slots as
+  `undefined`:** an undecoded line SEEDS its identity fields, so `procedureCode` is `""` on a P or D
+  line and `revenueCode` is `""` on an I one. A predicate of `procedureCode === undefined` does NOT
+  detect this.
+  A mis-stamped envelope is an ordinary vendor variant and this reader can no more tell one from a
+  conformant document than it can tell a stray `SVx` from a conformant one, so the loss is **warned
+  rather than silent**, and the cookbook's post-a-line-amount gate already names that code first.
+
+  **🛑 Read all of that as ONE property and never as a closed list of consequences:** where `ST-03`
+  is now recognised, **the document's own declaration decides the variant instead of its first
+  service segment**, and everything downstream follows from that single substitution. A first draft
+  of this entry published a census of three and a refuter measured it false by finding a fourth.
+
+  That is
+  the hazard a widening onto a new code carries, taken here in the opposite direction from the two
+  slices before it: they refused to narrow a fallback because the reader had no evidence beyond the
+  segments, and here the reader had the evidence in ST-03 and was ignoring it. Re-check any routing
+  driven off `submission.variant` for 837s you read on `0.0.13` or earlier.
+
+  **🛑 The `SVx` fallback is NOT narrowed.** First-wins still takes the first `SV1` / `SV2` / `SV3` in
+  the body, orphans included, on every document that still reaches it, and precedence is unchanged:
+  a caller `type` still wins ahead of ST-03, and ST-03 ahead of the segments. What changed is which
+  documents reach the fallback.
+
+  **It is a LIST of cited identifiers, never a pattern.** A reference outside the set, in a different
+  case, or carrying leading whitespace still falls through exactly as before. The set is **not
+  claimed exhaustive and no count of it is published**: both variant-resolution messages named the
+  three old keys literally, so both were wrong the moment the table was corrected, and neither
+  enumerates the set any more. A committed tripwire reds if any registry message quotes a TR3
+  identifier again.
+
+  **🩺 OPEN, and deliberately not fixed here: the EMIT side still stamps the old three.** `build837P`
+  / `build837I` / `build837D` write `005010X222A2` / `005010X223A3` / `005010X224A2` and a caller
+  cannot override them, so **a partner that requires `005010X222A1` or `005010X223A2` will reject an
+  837 this builder emits.** Which published guide identifier a partner accepts is a partner fact
+  rather than a spec fact, and changing bytes this library already emitted would break the partners
+  it works with today. `KNOWN-LIMITATIONS.md` carries it as an open residual.
+
 - **🩺 BREAKING (read model): every monetary, percent and quantity slot the readers used to fill with
   a fabricated `X12Decimal.ZERO` is now `X12Decimal | undefined`** (`X12-837-SV-UNDEFINED-DECIMAL`).
   Through `0.0.12` an **absent** `SV1-02` - a monetary field on an 837 claim service line - read back
@@ -871,8 +1029,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   are both the line charge, so reading a service segment into a line the walker never opened
   mis-reads money. Refusing to read is the safe half; doing it silently was the defect. **This says
   nothing about how the variant resolved**, and `KNOWN-LIMITATIONS.md` now discloses why: a caller's
-  `type` option wins first, and absent one, where `ST-03` names none of the three known
-  implementation conventions, the reader falls back to the first `SVx` in the transaction body,
+  `type` option wins first, and absent one, where `ST-03` names no implementation convention this
+  reader recognises, the reader falls back to the first `SVx` in the transaction body,
   orphans included, so a stray `SV2` re-types the whole submission. That is pre-existing behaviour, measured identical at `0.0.10`, and is deliberately
   not narrowed here.
 

package/KNOWN-LIMITATIONS.md

@@ -16,6 +16,52 @@ model.
 
 ## Data / decode boundaries
 
+- **🩺 Which `ST-03` implementation-convention references resolve to an 837 variant CHANGED in this
+  release, and some already-published files therefore decode differently** (`X12-VARIANT-ICR-UNGROUNDED`).
+  Through `0.0.13` `get837Claims` recognised exactly three references: `005010X222A2`, `005010X223A3`
+  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
+  `005010X222A1` and `005010X223A2`**, which CMS and state Medicaid companion guides require in ST-03
+  and GS-08 on production professional and institutional claims. A conformant 837P declaring
+  `005010X222A1` therefore resolved to no variant at all and fell through to the `SVx` scan, where a
+  single stray `SV2` anywhere in the body re-typed the whole submission, and
+  `X12_837_UNKNOWN_VARIANT` accused a document that was not non-conformant. The reader now recognises
+  each base guide and each of its published errata. Sources for every key are named beside the table
+  in `src/transactions/claim/get-837.ts` and in
+  `documentation/agent-notes/x12-variant-icr-ungrounded.md`.
+  - **🛑 What this changes for a consumer, and it is a behaviour change on already-published
+    decoding.** On a file whose `ST-03` is now recognised: `submission.variant` can differ from what
+    `0.0.13` read, where the first `SVx` in the body disagreed with the declaration; and
+    **`X12_837_AMBIGUOUS_VARIANT` and `X12_837_UNKNOWN_VARIANT` no longer fire at all**, because no
+    guess was made. A predicate written against either code goes quiet on such a file. **🩺 And a
+    service line whose `SVx` kind disagrees with the declaration is no longer DECODED, so a code
+    STARTS firing on a document that may have carried `warnings: []`**: under `005010X222A1` with a
+    body whose only service segment is an `SV2`, `0.0.13` read `variant` `"I"` and `charge` `7300`
+    with no warnings, and this release reads `variant` `"P"`, `charge` `undefined`, and
+    `X12_837_SERVICE_LINE_NOT_DECODED` at that line's `LX`. A mis-stamped envelope is an ordinary
+    vendor variant and this reader cannot tell one from a conformant document; the loss is warned
+    rather than silent. **Read all of this as ONE property and never as a closed list: where `ST-03`
+    is now recognised the document's own declaration decides the variant instead of its first
+    service segment, and everything downstream follows from that.** Re-check any routing driven off
+    `submission.variant` for 837s read on `0.0.13` or earlier.
+  - **🛑 The `SVx` fallback is NOT narrowed.** First-wins still takes the first service segment in the
+    body, orphans included, on every document that still reaches it. What changed is which documents
+    reach it.
+  - **It is a LIST of cited identifiers, never a pattern.** A reference outside the set, in a
+    different case, or carrying leading whitespace, still falls through exactly as before. Nothing
+    trims, lower-cases or prefix-matches `ST-03`, because no source says to.
+  - **The set is not claimed exhaustive and no count of it is published**, here or in any warning
+    message. Both variant messages named the three old keys literally and were wrong the moment the
+    table was corrected, so neither enumerates the set any more.
+  - **🩺 OPEN, and NOT fixed here: the EMIT side still stamps the old three.** `build837P` /
+    `build837I` / `build837D` write `005010X222A2` / `005010X223A3` / `005010X224A2` into ST-03 and
+    GS-08, and **a caller cannot override the value**. Two of those are not what the companion guides
+    above require, so **a trading partner that requires `005010X222A1` or `005010X223A2` will reject
+    an 837 this builder emits.** Deliberately not re-stamped: which published guide identifier a
+    partner accepts is a partner fact rather than a spec fact, and changing bytes this library
+    already emitted would break the partners it works with today. The remedy is a caller-supplied
+    override, which is a public-surface addition and its own slice.
+
 - **🩺 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
@@ -321,9 +367,9 @@ model.
     confident `0` through `0.0.12`, and this code has nothing to do with either.
   - **🩺 IT SAYS NOTHING ABOUT THE VARIANT, AND A FIRST DRAFT OF THIS BOUND CLAIMED IT DID.** Variant
     resolution runs before the walk. A caller-supplied `type` option wins first; absent one, and
-    where `ST-03` names none of the three known implementation conventions, it **falls back to the
+    where `ST-03` names no implementation convention this reader recognises, it **falls back to the
     first `SVx` segment id anywhere in the transaction body - orphans included**. So a stray `SV2`
-    under an `ST-03` of `005010X222A1` re-types the whole submission as Institutional, and every
+    under an unrecognised `ST-03` re-types the whole submission as Institutional, and every
     conformant `SV1` line in it then reads `charge` `undefined`, `units` `undefined` (both a
     fabricated `0` through `0.0.12`) and an `undefined` procedure
     code - `undefined`, not `""`, which on such a line is the `revenueCode`. Passing
@@ -331,7 +377,88 @@ model.
     identical at `0.0.10`, **not** introduced or changed by this code, and **not** narrowed here - excluding
     orphans from the fallback would change how existing documents decode and is its own slice. It
     is warned rather than silent (`X12_837_SERVICE_LINE_NOT_DECODED` at each `LX`), and
-    `submission.variant` is the field that tells you.
+    `submission.variant` is the field that tells you. **The resolution itself is now reported too
+    wherever it was contested**, which is the entry below; the fallback is still not narrowed.
+
+- **🩺 An 837 variant the `SVx` fallback resolved in a body that names more than one variant raises
+  `X12_837_AMBIGUOUS_VARIANT`, anchored at the `ST`.** The fallback is unchanged and is deliberately
+  NOT narrowed: it still takes the **first** `SV1` / `SV2` / `SV3` in the body, orphans included, so on
+  every document that reaches it the variant resolved is byte-for-byte what it was through `0.0.13`.
+  **WHICH documents reach it changed in this release** - see the ST-03 entry at the top of this list. What this code
+  adds is that the resolution said so. Through `0.0.13` a stray `SV2` re-typed a whole Professional
+  submission Institutional and **only the line-level consequences were on any channel** - a consumer
+  routing on `submission.variant` saw a confident `"I"` with nothing to contradict it. Four bounds,
+  each a committed test:
+  - **It reports the RESOLUTION, never the document.** A caller-supplied `type` wins ahead of the
+    fallback, and so does an `ST-03` this reader turns into a variant; in
+    either case no guess was made and this code is not raised **however mixed the body is**. Never
+    restate it as "the file carries more than one kind of service segment".
+  - **🩺 Which service segment is the stray one is NOT decided, and nothing here should ever start
+    deciding it.** This reader cannot tell a stray service segment from a conformant one, and the
+    fallback takes the first whether or not a Loop 2400 was open at it, so an orphan decides the
+    variant like any other. Reporting the conflict is honest; picking a winner would be inventing.
+  - **It is ADDITIVE and nothing moved onto it.** `X12_837_SERVICE_LINE_NOT_DECODED`,
+    `X12_837_SERVICE_SEGMENT_WITHOUT_LX` and `X12_837_SERVICE_LINE_DROPPED` fire on exactly the
+    documents they fired on before **this code was added**, in the same positions, and no predicate
+    changes meaning because of this code. **That is a claim about this code and NOT about the
+    release:** the ST-03 entry at the top of this list changed which documents reach the fallback at
+    all, and a line whose `SVx` kind disagrees with a now-recognised `ST-03` stops decoding and
+    starts raising `X12_837_SERVICE_LINE_NOT_DECODED`. Read that entry beside this bound.
+  - **It can never travel with `X12_837_UNKNOWN_VARIANT`**, which is the other outcome of the same
+    resolution: a body with conflicting service segments has, by construction, at least one to fall
+    back on. It fires **once per transaction**, because there is one resolution per transaction.
+  - **What it does NOT close:** narrowing the fallback, which is deliberately left alone. It no
+    longer leaves a second `SVx` inside an already-open Loop 2400 unreported: that was its own
+    slice, and it is the entry below. **Read the earlier wording as withdrawn** - it said such a
+    segment is "read into nothing", which was true only of one whose kind does not match the
+    resolved variant; a DUPLICATE of the matching kind is read into the line and REPLACES what the
+    first one wrote.
+
+- **🩺 A second `SV1` / `SV2` / `SV3` inside an ALREADY-OPEN Loop 2400 raises
+  `X12_837_SERVICE_SEGMENT_REPEATED`, anchored at the repeated service segment itself.** A service
+  line carries **one** service segment's worth of slots, and every decoder writes **all** of the
+  slots its kind writes, so the model holds what the **last** service segment matching the
+  submission's resolved variant wrote and nothing of any earlier one. **Through `0.0.13` that
+  happened in complete silence, and it is money and a procedure code:** under an `ST-03` of
+  `005010X222A2`, `SV1*HC:99213*8500*UN*4***1~` followed by `SV1*HC:99999*12*UN*1***1~` inside one
+  `LX` left ONE line reading `charge` `12` and `procedureCode` `99999`, with `warnings: []`. `8500`
+  became `12`, CPT `99213` became `99999`, and nothing was raised on any channel. Six bounds, each a
+  committed test:
+  - **🛑 The decode is NOT narrowed, and that is deliberate.** Last-wins is unchanged, element for
+    element, so which values a document decodes to are byte-for-byte what they were at `0.0.13`.
+    This reader cannot tell a stray service segment from a conformant one, so choosing the first
+    instead would be inventing; and changing which occurrence wins changes how **already-published
+    documents decode**, the same call made about the variant fallback in the entry above. **This
+    closes only the silence.**
+  - **🩺 The worst corner is a repeat whose own charge element is ABSENT.** It writes `undefined`
+    over the amount the first one stated, and `X12_837_SERVICE_LINE_NOT_DECODED` does **not** fire
+    on that line, because a service segment _did_ decode. This code is then the only thing on the
+    channel that says why the charge is empty.
+  - **It fires on a repeat of ANY kind, decoded or not.** A service segment whose kind does not
+    match the resolved variant is read into nothing and overwrites nothing - the loss there is that
+    what it carries reaches no part of the typed model - and it is reported the same way, whether it
+    arrives before or after the matching one. That case was silent at the segment through `0.0.13`
+    too, and the entry above recorded it as a deferred residual.
+  - **Once per repeat, and the count is scoped to the LINE, never latched.** Three service segments
+    in one Loop 2400 are two warnings at two positions; a first service segment under a later `LX`,
+    or in a later claim, is a first and never a repeat. A latching flag would report a conformant
+    second line.
+  - **It can never name the same segment as `X12_837_SERVICE_SEGMENT_WITHOUT_LX`**, which requires
+    that NO Loop 2400 be open where this one requires that one is. It can travel with
+    `X12_837_SERVICE_LINE_NOT_DECODED` (at the `LX`), with `X12_837_AMBIGUOUS_VARIANT` (at the
+    `ST`), and with `X12_UNPARSEABLE_DECIMAL` raised by the repeat's own amount bytes. **That last
+    pair sits at the SAME `position.segmentIndex`, separated only by the decimal code's own
+    `position.elementIndex`** - measured, and pinned by a committed test. Never read a co-occurring
+    pair here as two segments.
+  - **It is ADDITIVE and nothing moved onto it.** Every code this reader raised on a document of
+    this shape before **this code was added**, it still raises, at the same position, and no
+    predicate changes meaning because of this code. Read that as invariance and **not** as a list of
+    what else you will see, and **not** as a claim about the release: the ST-03 entry at the top of
+    this list changed which documents reach the variant fallback.
+    **The package's own documentation was a consumer that needed updating**: the cookbook's
+    "gate before you post a line amount" recipe named four codes, none of which fires on the
+    overwrite document, so it was blind to it - it now names this one too, and a committed test
+    pins that the four-code gate misses what the five-code gate catches.
 
 - **🩺 An `N3` / `N4` / `PER` / `REF` discarded after a stray `LX` raises
   `X12_837_ENTITY_SEGMENT_DISCARDED_AFTER_LX`, anchored at the discarded segment itself.** This is

package/dist/index.cjs

@@ -138,6 +138,7 @@ var WARNING_CODES = {
   X12_UNKNOWN_HI_QUALIFIER: "X12_UNKNOWN_HI_QUALIFIER",
   X12_MISSING_REQUIRED_LOOP: "X12_MISSING_REQUIRED_LOOP",
   X12_837_UNKNOWN_VARIANT: "X12_837_UNKNOWN_VARIANT",
+  X12_837_AMBIGUOUS_VARIANT: "X12_837_AMBIGUOUS_VARIANT",
   X12_UNKNOWN_CLAIM_STATUS_CATEGORY: "X12_UNKNOWN_CLAIM_STATUS_CATEGORY",
   X12_UNKNOWN_CLAIM_STATUS: "X12_UNKNOWN_CLAIM_STATUS",
   X12_834_UNKNOWN_MAINTENANCE_TYPE: "X12_834_UNKNOWN_MAINTENANCE_TYPE",
@@ -145,6 +146,7 @@ var WARNING_CODES = {
   X12_837_SERVICE_LINE_NOT_DECODED: "X12_837_SERVICE_LINE_NOT_DECODED",
   X12_837_SERVICE_LINE_DROPPED: "X12_837_SERVICE_LINE_DROPPED",
   X12_837_SERVICE_SEGMENT_WITHOUT_LX: "X12_837_SERVICE_SEGMENT_WITHOUT_LX",
+  X12_837_SERVICE_SEGMENT_REPEATED: "X12_837_SERVICE_SEGMENT_REPEATED",
   X12_837_ENTITY_SEGMENT_DISCARDED_AFTER_LX: "X12_837_ENTITY_SEGMENT_DISCARDED_AFTER_LX",
   X12_837_PAY_TO_ADDRESS_REPEATED: "X12_837_PAY_TO_ADDRESS_REPEATED",
   X12_835_BALANCE_NOT_EVALUABLE: "X12_835_BALANCE_NOT_EVALUABLE",
@@ -222,7 +224,8 @@ var WARNING_MESSAGES = {
   X12_MISSING_REQUIRED_LOOP_2000B: 'Missing required loop "2000B" (Subscriber HL): no Subscriber HL precedes the CLM.',
   X12_MISSING_REQUIRED_LOOP_2010BA: 'Missing required loop "2010BA" (Subscriber Name): no Subscriber Name follows the Subscriber HL.',
   X12_MISSING_REQUIRED_LOOP_2010BB: 'Missing required loop "2010BB" (Payer Name): no Payer Name follows the Subscriber HL.',
-  X12_837_UNKNOWN_VARIANT: `837 variant could not be resolved: ST-03's implementation convention reference is not one of "005010X222A2" / "005010X223A3" / "005010X224A2", and no SVx service-line segment was present to fall back on. The verbatim reference is preserved on the model.`,
+  X12_837_UNKNOWN_VARIANT: "837 variant could not be resolved: ST-03's implementation convention reference is absent, empty, or not an 837 Technical Report Type 3 identifier this reader recognises, and no SVx service-line segment was present to fall back on. The set of references it recognises covers the professional, institutional and dental 837 guides HIPAA adopts at 45 CFR 162.1102 together with their published errata; it is NOT claimed to be exhaustive, and this message deliberately does not enumerate it, because a list here goes stale the moment a guide is added. A reference outside that set is not asserted to be invalid - all this code reports is that this reader could not turn it into a variant and had nothing to fall back on. The verbatim reference is preserved on the model; read it there rather than inferring what the sender meant.",
+  X12_837_AMBIGUOUS_VARIANT: "837 variant resolved from a service segment while the transaction body carries service segments of more than one variant: no caller `type` option was supplied and ST-03's implementation convention reference is absent, empty, or not an 837 Technical Report Type 3 identifier this reader recognises, so this reader fell back to the FIRST SV1 / SV2 / SV3 in the body, and a later one names a different variant. `submission.variant` is therefore a guess between contradictory evidence, and every claim and service line in the submission was read against it. Which service segment is the stray one is NOT decided here and is not derivable from the TR3s: this reader cannot tell a stray service segment from a conformant one, and the fallback takes the first regardless of whether any Loop 2400 was open at it, so an orphan segment decides the variant like any other. Read the bound literally, as a property of the RESOLUTION rather than of the document: this reports the fallback's own ambiguity, so a caller-supplied `type`, or an ST-03 this reader does turn into a variant, means no guess was made and this code is NOT raised however mixed the body is. Whatever else this reader raised on a document that reaches this code, it still raises, at the same position, and this one is added beside them. It is NOT a list of what else you will see, and it does not promise that any particular loss on such a document is reported at all. Re-read with the `type` option to decode the document against a variant you trust. The verbatim segments are preserved on the transaction set; read them there before acting on the submission's type.",
   X12_UNKNOWN_CLAIM_STATUS_CATEGORY: "Unknown claim status category (CSCC): the STC composite's first component is outside the bundled snapshot. The verbatim code is preserved on the status; only its description is unavailable.",
   X12_UNKNOWN_CLAIM_STATUS: "Unknown claim status code (CSC): the STC composite's second component is outside the bundled snapshot. The verbatim code is preserved on the status; only its description is unavailable.",
   X12_834_UNKNOWN_MAINTENANCE_TYPE: "Unknown 834 maintenance type: the INS-03/HD-01 code is outside the bundled snapshot. The verbatim code is preserved on the enrollment and the action is NEVER inferred.",
@@ -230,6 +233,7 @@ var WARNING_MESSAGES = {
   X12_837_SERVICE_LINE_NOT_DECODED: "837 service line with no decoded service segment: the Loop 2400 line opened at `position.segmentIndex` is followed by no SV1 / SV2 / SV3 matching the variant this submission resolved to, so NOTHING carried by the service segment was read. The line's `charge` and `units` are `undefined`, which is what this library puts on a decimal slot it decoded no value into; its procedure code, modifiers, unit of measure and place of service are equally undecoded. Two common causes: the line carries no SVx at all, or it carries one for a different 837 variant than ST-03 (or the caller's `type` option) named. Which side is wrong is NOT decided here, because a caller-supplied `type` can disagree with a perfectly conformant document. The verbatim segments are preserved on the transaction set; read them there before acting on the charge or the quantity.",
   X12_837_SERVICE_LINE_DROPPED: "837 service line dropped from the typed model: the LX at `position.segmentIndex` opened no Loop 2400, so no line appears on any claim's `serviceLines` for it and the SV1 / SV2 / SV3 that followed - its charge, units, procedure code and modifiers - was read into nothing. Compare `X12_837_SERVICE_LINE_NOT_DECODED`, where the line IS on the model and only its service segment went unread. Two causes: no Loop 2300 (CLM) is open at this LX, so there is no claim to attach a line to; or the submission's variant is not one of P / I / D, so no variant-specific line shape could be built. Read `submission.variant` and `submission.claims` to tell them apart; do NOT expect `X12_837_UNKNOWN_VARIANT` alongside this code, because a caller-supplied `type` outside P / I / D reaches the second cause without it. Nothing is fabricated to stand in for the missing line and no claim is synthesized. What becomes of a DTP / AMT / NTE / REF that follows the dropped LX depends on the route and this message does not say; see KNOWN-LIMITATIONS.md. The verbatim segments are preserved on the transaction set; read them there before concluding the claim had no service lines.",
   X12_837_SERVICE_SEGMENT_WITHOUT_LX: "837 service segment with no Loop 2400 to read it into: no service line was open at the SV1 / SV2 / SV3 at `position.segmentIndex`, so NOTHING it carries - its charge, units, procedure code, modifiers, unit of measure and place of service - was read. Read that literally: an LX may well appear earlier in the transaction, and what this reports is that none of them had opened a Loop 2400 still current at this segment. No line appears on any claim's `serviceLines` for it and nothing is fabricated to stand in. Compare the two codes anchored at an LX: `X12_837_SERVICE_LINE_DROPPED`, where an LX IS present and opened no line, and `X12_837_SERVICE_LINE_NOT_DECODED`, where the line is on the model and only its service segment went unread. Neither of those can report the SAME service segment as this code, because both are raised at an LX and this one only where no Loop 2400 is open; a document with several claims can still carry all three. This says NOTHING about how the submission's variant resolved: absent a caller-supplied `type` option, and where ST-03 names no known implementation convention, the reader falls back to the first SV1 / SV2 / SV3 in the transaction, and a segment reported here is eligible for that fallback like any other, so a stray one can decide the variant every line is read against. Read `submission.variant`. The verbatim segments are preserved on the transaction set; read them there before concluding the claim had no service lines.",
+  X12_837_SERVICE_SEGMENT_REPEATED: "837 service segment repeated inside one Loop 2400: the SV1 / SV2 / SV3 at `position.segmentIndex` is not the first service segment to arrive in the service line the LX before it opened. This reader's line carries ONE service segment's worth of slots, so it cannot hold both, and this code is the only thing that tells you the document sent more than one. It asserts nothing about what usage the TR3s give the segment; what it reports is that this reader has one set of those slots per line. What the line carries is what the LAST service segment MATCHING the submission's resolved variant wrote onto it, and only that. Such a segment writes every slot its kind writes - the charge, the units and the procedure code among them - so a matching one arriving second leaves NOTHING an earlier matching one wrote, including where the later one's charge or units element is ABSENT: there the line is left with undefined, which is what this library puts on a decimal slot it decoded no value into, over an amount the earlier one stated. A service segment of a kind that does NOT match the resolved variant is read into nothing at all - it overwrites no slot, and what it carries reaches no part of the typed model. Which of them the sender meant is NOT decided here and is not derivable from the TR3s: this reader cannot tell a stray service segment from a conformant one, and picking a winner would be inventing. Nothing is fabricated to stand in, no second line is synthesized - an LX is what opens a line and there is none here - and no earlier value is kept in a second slot. Read the bound literally, as a property of the READ: this reports a second service segment arriving while a Loop 2400 IS open, whether or not it decoded. It is disjoint from `X12_837_SERVICE_SEGMENT_WITHOUT_LX`, which requires that NO Loop 2400 be open where this one requires that one is, so the two can never name the same segment; read that as disjointness and NOT as a promise that a service segment outside an open Loop 2400 is always named by that code, because a service segment FOLLOWING an LX that opened no line at all is named by neither of them, the loss having already been reported at that LX by `X12_837_SERVICE_LINE_DROPPED`. `X12_837_SERVICE_LINE_NOT_DECODED`, anchored at the LX, reports that no service segment matching the variant decoded onto the line at all, so a document can carry both codes on different segments. It fires once per repeat, so three service segments in one Loop 2400 are two warnings, and the count resets with the line: a first service segment under a later LX is a first and never a repeat. It says nothing about how the submission's variant resolved; where the fallback decided that and the body names more than one, `X12_837_AMBIGUOUS_VARIANT` reports it separately. The verbatim segments are preserved on the transaction set; read them there before acting on the charge, the quantity or the procedure code.",
   X12_837_ENTITY_SEGMENT_DISCARDED_AFTER_LX: "837 entity segment read into nothing after a dropped LX: the N3 / N4 / PER / REF at `position.segmentIndex` arrived while no entity loop was open, because an earlier LX in this transaction opened no Loop 2400 (no CLM was open at it) and closed the entity loop that was current there. NOTHING this segment carries reached the model: no party's `address`, `contacts` or `references` was written from it, and no party, claim or line was synthesized to hold it. This is the code that names THAT loss; `X12_837_SERVICE_LINE_DROPPED` is raised at the LX itself and names the SERVICE LINE's loss, never an entity segment, so the two report different things about the same stretch of the document. Read the bound literally, because this code does NOT report every unattached entity segment: it reports one discarded after such an LX and only while nothing since has opened a new loop, so an N3 / N4 / PER / REF that reaches no party by any other route is still silent, and one arriving after a later NM1 is outside this code's scope, whether or not this reader surfaces that segment kind on that party. It reports that the segment reached NO party; it does not claim it would have reached one had the LX been absent, because this reader does not surface every one of these segment kinds on every party (a PER on a patient or a pay-to address, for one). Which party a segment following a stray LX belongs to is not derivable from the TR3s in either direction, so it is discarded rather than attributed: see KNOWN-LIMITATIONS.md. The verbatim segments are preserved on the transaction set; read them there before concluding a party had no address, no secondary identifier or no contact.",
   X12_837_PAY_TO_ADDRESS_REPEATED: "837 pay-to address named more than once in one Loop 2000A: the NM1*87 at `position.segmentIndex` is not the first in this Loop 2000A, and the TR3s allow Loop 2010AB at most once there. The model has ONE pay-to address slot, so it cannot carry both, and this code is the only thing that tells you the document named more than one. The reader NEVER merges them: an N3 or N4 after this segment can no longer add a street line to, or fill a blank in, the address an earlier NM1*87 named, which is what this library did through 0.0.12 - it returned a fused address no sender sent, silently. What the slot carries instead is the LAST occurrence that stated an address of its own; an occurrence that states none - one carrying no N3 or N4 at all, or only a valueless N3 or N4 whose elements are empty - does NOT replace one that did, so nothing an earlier occurrence stated is blanked either. Where no occurrence states an address, the slot holds what the FIRST N3 or N4 to arrive under any of them produced, which may be an address with no elements at all, and which is not necessarily the first occurrence's: an occurrence that carries no N3 or N4 writes nothing, so a later one's valueless N3 is the first write and takes a slot still empty. Read that as the corner it is, and never restate it as the first OCCURRENCE winning. Which occurrence the sender meant is NOT decided here and is not derivable from the TR3s, and the losing occurrence's address is NOT on the model in any form. Read the bound literally: this reports repetition within one Loop 2000A, which is where the pay-to route lives, and an NM1*87 arriving while a CLM is open never reaches that route. The verbatim segments are preserved on the transaction set; read them there before acting on where a payment is to be sent.",
   X12_AMOUNT_ROW_DROPPED: "Amount row dropped from the typed model: the AMT or ADX at `position.segmentIndex` carried no decodable amount (AMT-02, ADX-01), so NO row was built for it and the rest of the segment went with it - its qualifier or adjustment reason code, and any reference qualifier and id. Nothing is fabricated to stand in: a row is not built around a zero this library did not read, which is why the loss is reported rather than papered over. Two routes reach it and this code does not say which: the amount element was ABSENT, or it was present and held bytes that do not decode as a decimal. On this segment only the second route also raises `X12_UNPARSEABLE_DECIMAL`, carrying the failing element in its own `position.elementIndex`, so whether one is present at this `position.segmentIndex` is what separates them - and that code is unchanged by this one, which is raised alongside it rather than in place of it. Read the bound literally: this reports a row whose AMOUNT was read and decoded no value, and it is NOT a general report that an amount segment reached no model. A segment a reader discards before reading its amount is not on this channel, and neither is one whose amount decoded and then found no claim, service line, coverage or remittance open to attach the row to. An 820 RMR is not on it either, for its own reason: that row is dropped on open-item IDENTITY, RMR-01 and RMR-02 both empty, before the amount is read at all, so an RMR that states an open item and no amount keeps its row with amountPaid undefined while one that states an amount and no open item is dropped whole. That second case is a separate loss, and so is an 837 AMT that decoded while a Loop 2430 adjudication was open; `X12_STATED_AMOUNT_DISCARDED` reports both, and this code reports neither. The two can never name the same segment, because this one requires an amount element that decoded no value and that one requires the opposite. The verbatim segments are preserved on the transaction set; read them there before concluding the document stated no such amount.",
@@ -406,6 +410,13 @@ function unknown837Variant(position) {
     position
   };
 }
+function ambiguous837Variant(position) {
+  return {
+    code: WARNING_CODES.X12_837_AMBIGUOUS_VARIANT,
+    message: WARNING_MESSAGES.X12_837_AMBIGUOUS_VARIANT,
+    position
+  };
+}
 function serviceLineNotDecoded(position) {
   return {
     code: WARNING_CODES.X12_837_SERVICE_LINE_NOT_DECODED,
@@ -427,6 +438,13 @@ function serviceSegmentWithoutLx(position) {
     position
   };
 }
+function serviceSegmentRepeated(position) {
+  return {
+    code: WARNING_CODES.X12_837_SERVICE_SEGMENT_REPEATED,
+    message: WARNING_MESSAGES.X12_837_SERVICE_SEGMENT_REPEATED,
+    position
+  };
+}
 function entitySegmentDiscardedAfterLx(position) {
   return {
     code: WARNING_CODES.X12_837_ENTITY_SEGMENT_DISCARDED_AFTER_LX,
@@ -3323,9 +3341,20 @@ function statesAnAddress(address) {
 
 // src/transactions/claim/get-837.ts
 var VARIANT_BY_ICR = wireLookup({
+  // Health Care Claim: Professional (837).
+  "005010X222": "P",
+  "005010X222A1": "P",
   "005010X222A2": "P",
+  // Health Care Claim: Institutional (837).
+  "005010X223": "I",
+  "005010X223A1": "I",
+  "005010X223A2": "I",
   "005010X223A3": "I",
-  "005010X224A2": "D"
+  // Health Care Claim: Dental (837).
+  "005010X224": "D",
+  "005010X224A1": "D",
+  "005010X224A2": "D",
+  "005010X224A3": "D"
 });
 var VARIANT_BY_SV_SEGMENT = wireLookup({
   SV1: "P",
@@ -3361,16 +3390,24 @@ function get837Claims(delimiters, tx, opts) {
   const explicitType = opts?.type;
   const variantFromIcr = implementationConventionReference !== void 0 && implementationConventionReference !== "" ? VARIANT_BY_ICR[implementationConventionReference] : void 0;
   let variantFromSegment;
-  for (const seg of body) {
-    const fromSv = VARIANT_BY_SV_SEGMENT[seg.id];
-    if (fromSv !== void 0) {
-      variantFromSegment = fromSv;
-      break;
+  let serviceSegmentVariantsConflict = false;
+  if (explicitType === void 0 && variantFromIcr === void 0) {
+    for (const seg of body) {
+      const fromSv = VARIANT_BY_SV_SEGMENT[seg.id];
+      if (fromSv === void 0) continue;
+      if (variantFromSegment === void 0) {
+        variantFromSegment = fromSv;
+      } else if (fromSv !== variantFromSegment) {
+        serviceSegmentVariantsConflict = true;
+        break;
+      }
     }
   }
   const variant = explicitType ?? variantFromIcr ?? variantFromSegment ?? "unknown";
   if (variant === "unknown") {
     warnings.push(unknown837Variant({ segmentIndex: 0, transactionIndex: 0 }));
+  } else if (serviceSegmentVariantsConflict) {
+    warnings.push(ambiguous837Variant({ segmentIndex: 0, transactionIndex: 0 }));
   }
   const hierarchies = [];
   const hlIndex = /* @__PURE__ */ new Map();
@@ -3419,6 +3456,10 @@ function get837Claims(delimiters, tx, opts) {
     if (droppedLineReported) return;
     warnings.push(serviceSegmentWithoutLx(position));
   };
+  const noteServiceSegment = (acc, position) => {
+    if (acc.serviceSegmentSeen) warnings.push(serviceSegmentRepeated(position));
+    acc.serviceSegmentSeen = true;
+  };
   const reportDiscardedEntitySegment = (position) => {
     if (!entityLoopClosedByStrayLx) return;
     warnings.push(entitySegmentDiscardedAfterLx(position));
@@ -3761,19 +3802,41 @@ function get837Claims(delimiters, tx, opts) {
       // before the walk and scans every SVx in the body: an orphan segment
       // is eligible for that fallback like any other, which is pre-existing
       // and disclosed in KNOWN-LIMITATIONS.md rather than changed here.
+      //
+      // A SECOND service segment inside an already-open Loop 2400 is the
+      // other silence on this segment, and it is a worse one: the line IS
+      // open, so the repeat decodes, and every decoder writes all of the
+      // slots its kind writes. `SV1*HC:99213*8500*…` followed by
+      // `SV1*HC:99999*12*…` left ONE line reading `charge` 12 and
+      // `procedureCode` 99999 through `0.0.13`, with `warnings: []` - money
+      // and a CPT code replaced on the model, on no channel at all.
+      // `noteServiceSegment` reports that, at the repeat itself, and changes
+      // NOTHING about which segment wins.
       case "SV1": {
-        if (currentServiceLine !== void 0) decodeSv1(currentServiceLine, seg, delimiters, sink);
-        else reportOrphanServiceSegment(position);
+        if (currentServiceLine === void 0) {
+          reportOrphanServiceSegment(position);
+          break;
+        }
+        noteServiceSegment(currentServiceLine, position);
+        decodeSv1(currentServiceLine, seg, delimiters, sink);
         break;
       }
       case "SV2": {
-        if (currentServiceLine !== void 0) decodeSv2(currentServiceLine, seg, delimiters, sink);
-        else reportOrphanServiceSegment(position);
+        if (currentServiceLine === void 0) {
+          reportOrphanServiceSegment(position);
+          break;
+        }
+        noteServiceSegment(currentServiceLine, position);
+        decodeSv2(currentServiceLine, seg, delimiters, sink);
         break;
       }
       case "SV3": {
-        if (currentServiceLine !== void 0) decodeSv3(currentServiceLine, seg, delimiters, sink);
-        else reportOrphanServiceSegment(position);
+        if (currentServiceLine === void 0) {
+          reportOrphanServiceSegment(position);
+          break;
+        }
+        noteServiceSegment(currentServiceLine, position);
+        decodeSv3(currentServiceLine, seg, delimiters, sink);
         break;
       }
       case "TOO": {
@@ -4080,6 +4143,7 @@ function openServiceLine2(seg, delimiters, variant, position) {
     lineNumber,
     position,
     serviceSegmentDecoded: false,
+    serviceSegmentSeen: false,
     charge: void 0,
     units: void 0,
     unitOfMeasure: void 0,
@@ -10306,7 +10370,7 @@ var profiles = Object.freeze({
 });
 
 // src/index.ts
-var VERSION = "0.0.13";
+var VERSION = "0.0.14";
 
 exports.ACK_BUILD_ERROR_CODES = ACK_BUILD_ERROR_CODES;
 exports.ALL_WARNING_MESSAGES = ALL_WARNING_MESSAGES;
@@ -10414,6 +10478,7 @@ exports.X12ParseError = X12ParseError;
 exports.X12ProfileError = X12ProfileError;
 exports.X12_ACK_DISPOSITION_CODES = X12_ACK_DISPOSITION_CODES;
 exports.X12_BUILD_ERROR_CODES = X12_BUILD_ERROR_CODES;
+exports.ambiguous837Variant = ambiguous837Variant;
 exports.amountRowDropped = amountRowDropped;
 exports.balanceNotEvaluable = balanceNotEvaluable;
 exports.build271 = build271;
@@ -10493,6 +10558,7 @@ exports.segmentCountMismatch = segmentCountMismatch;
 exports.serializeX12 = serializeX12;
 exports.serviceLineDropped = serviceLineDropped;
 exports.serviceLineNotDecoded = serviceLineNotDecoded;
+exports.serviceSegmentRepeated = serviceSegmentRepeated;
 exports.serviceSegmentWithoutLx = serviceSegmentWithoutLx;
 exports.setDefaultProfile = setDefaultProfile;
 exports.statedAmountDiscarded = statedAmountDiscarded;