@cosyte/x12 0.0.12 → 0.0.14

package/CHANGELOG.md

@@ -9,6 +9,227 @@ 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
+  the row for a reason that is not about the amount at all**, so the amount was never the problem
+  and, on one of the two routes, was never even looked at. The bytes stay verbatim on
+  `tx.segments[…].raw`; decode them yourself before posting. Through `0.0.12` both routes were
+  silent on every channel.
+
+  **The two routes, enumerated.** An **820 `RMR`** under an open remittance loop whose `RMR-01` and
+  `RMR-02` are **both empty** while `RMR-04` or `RMR-05` is populated: `decodeRmr` refuses the open
+  item on identity **before** either amount element is read, so `RMR****150.00*150.00~` gave
+  `openItems: []` and `warnings: []`, taking a stated payment, a stated amount due and `RMR-03`'s
+  payment action code together. And an **837 `AMT`** arriving while a Loop 2430 line adjudication
+  (`SVD`) is open, whose `AMT-02` decoded: the v1 adjudication model carries no amount row, and
+  attaching one to this submission's own service line would put another payer's figure on it, so
+  `AMT*EAF*75.00~` (Remaining Patient Liability) was skipped in silence.
+
+  **🩺 That second route is where the channel read BACKWARDS, and squaring it is the point.** Under
+  an open `SVD`, `AMT*EAF~` raised `X12_AMOUNT_ROW_DROPPED` and `AMT*EAF*75.00~` raised nothing: the
+  report was present exactly where **less** was lost. Both report now, and which code arrives is
+  what says which loss it was.
+
+  **It carries no `position.elementIndex`.** On the `RMR` route the loss spans `RMR-04` and
+  `RMR-05` and no single element names it; on the `AMT` route the element is fixed by the segment.
+
+  **🩺 It is additive, and nothing moved onto it.** `X12_AMOUNT_ROW_DROPPED` and
+  `X12_UNPARSEABLE_DECIMAL` fire on exactly the documents they fired on before, pinned by committed
+  tests. **The two amount-row codes are disjoint and can never name the same segment**, because this
+  one requires an amount element the sender populated and the other requires one that decoded no
+  value, so the code you get is the discriminant. **Gate on both.** `KNOWN-LIMITATIONS.md`, the
+  money spec-note and the troubleshooting table were corrected with the code.
+
+  **Bounds, stated as properties of the READ.** What is reported is a segment that populated its
+  amount element and arrived **while the loop that would carry its row was open**. One reaching a
+  reader with no such loop open is a different loss and is **still silent**: the 834's `AMT` with no
+  `HD` open, the 820's `ADX` with no remittance open, and the 835's and the 837's `AMT` before any
+  claim or service line. A bare `RMR~` states nothing and is silent, as is an identity-less `RMR`
+  carrying only a payment action code. And this code says **nothing** about whether the amount would
+  have decoded: the `RMR` route refuses the row before attempting the decode, so it is raised on
+  `RMR****1,234.56~` exactly as on `RMR****150.00*150.00~`, with **no `X12_UNPARSEABLE_DECIMAL`
+  beside it in either case**, on this release and on every earlier one. **Do not read an
+  unaccompanied instance as evidence the bytes are postable.** Only the `AMT` route guarantees a
+  decodable amount, because there `AMT-02` decoded before the row was skipped.
+
+- **🩺 `X12_AMOUNT_ROW_DROPPED`, the 30th Tier-2 warning code, plus the public factory
+  `amountRowDropped(position)`** (`X12-AMT-ADX-ABSENT-AMOUNT`). An `AMT` or `ADX` is not a slot on a
+  bigger record: each one **is** a record, carrying an amount plus the thing the amount is about. So
+  when the amount element (`AMT-02`, `ADX-01`) decodes no value there is no row to build, and
+  `AMT-01`'s qualifier or `ADX-02`'s adjustment reason code is dropped with it. Through `0.0.12`
+  that happened with **no diagnostic on any channel**: `AMT*B6~` gave `claim.amounts: []` and
+  `warnings: []`, which reads exactly like a document that never carried the segment. It is now
+  reported, at the `AMT` / `ADX` itself.
+
+  Raised by four surfaces: the 835's `AMT`, the 837's `AMT`, the 834's coverage `AMT` and the 820's
+  `ADX`. The 834's lands on that **member's** own `warnings`, the same per-member scoping the
+  decimal sink beside it already used, because a roster-level report would say a premium was lost
+  without saying whose. **On the 835 and the 837 the `AMT` attaches to the open SERVICE LINE first
+  and to the claim only when there is none, so the row lost may be a line-level one** - an unchanged
+  `claim.amounts` is not evidence the warning is stale.
+
+  **It carries no `position.elementIndex`**, deliberately. One of its two routes is an absent
+  element, and an absent element has no index to name; the segment fixes which element was being
+  read anyway.
+
+  **🩺 It is additive, and no case moved onto it.** An amount that is present and does not decode
+  still raises `X12_UNPARSEABLE_DECIMAL` at its own `elementIndex`, now **alongside** this code
+  rather than instead of it, so a gate you already wrote against that code fires on exactly the
+  documents it fired on before. Whether one accompanies this code at the same `position.segmentIndex`
+  is what separates the absent route from the unparseable one, since this code is raised for both
+  and discriminates neither. What a one-code gate never caught, on any release, is the
+  absent-amount row: **gate on both.** `KNOWN-LIMITATIONS.md`, the money spec-note and the
+  troubleshooting table were corrected with the code, and a committed test pins both halves - that
+  the one-code gate misses the absent-amount document, and that it still fires where it always did.
+
+  **Bounds, stated because the wider reading is the tempting one, and stated as properties of the
+  READ rather than of the walker's control flow.** What is reported is a row whose amount was read
+  and decoded no value. A segment discarded **before** its amount is read is not on this channel
+  (the 834's `AMT` with no `HD` open, the 820's `ADX` with no remittance open), and neither is one
+  whose amount decoded and then found nothing open to attach the row to. **Do not shorten that to
+  "nothing open means silent"** - the 835 and the 837 decode first, so an `AMT` with an absent
+  amount and no claim open does raise this code. An 820 `RMR` is not on this channel either, and
+  **not** because its row survives: `decodeRmr` drops on open-item identity (`RMR-01` and `RMR-02`
+  both empty) **before** `RMR-04` is read, so an `RMR` stating an open item and no amount keeps its
+  row with `amountPaid` left `undefined`, while one stating an amount and **no** open item is
+  dropped whole. That second case, and the 837's Loop 2430 `AMT` which an open `SVD` discards
+  outright, are separate losses: nothing failed to decode in either, so neither is this code's
+  shape, and `X12_STATED_AMOUNT_DISCARDED` above is what reports them.
+
+- **🩺 `X12_835_BALANCE_NOT_EVALUABLE`, the 29th Tier-2 warning code, plus the public factory
+  `balanceNotEvaluable(position, invariant)`** (`X12-837-SV-UNDEFINED-DECIMAL`). Raised where a term
+  of one of the three TR3 005010X221A1 §1.10.2 balance equations is `undefined` on the model, so the
+  equation has nothing to compare on one side. `invariant` is the same library-owned
+  `BALANCE_INVARIANTS` discriminant `X12_835_REMIT_BALANCE_MISMATCH` takes, and the message names the
+  equation and carries no amount, like every other warning in this registry.
+
+  **It is a different code from the mismatch on purpose.** The mismatch asserts a computed inequality
+  between amounts the sender supplied; this one asserts only that the comparison could not be made.
+  Through `0.0.12` an undecoded term collapsed to `X12Decimal.ZERO` and the equation then reported a
+  mismatch between the payer's own amounts and a zero this library invented, which is the reading
+  that made an absent `CLP-03` indistinguishable from a claim submitted at zero.
+
+  **An EMPTY list of adjustments is NOT an absent term** and does not raise it: a claim carrying no
+  `CAS` really did state no adjustments, so its sum is `X12Decimal.ZERO`. Only a term this library
+  decoded no value from stops the equation. `build835` reaches the same verdict as
+  `X12_835_BUILD_INVALID_SPEC` rather than as its balance-mismatch code, and is unreachable there
+  from TypeScript because every balance term on `Build835Spec` is a required `X12Decimal`.
+
+  **🩺 GATE ON BOTH CODES.** A posting gate written against `X12_835_REMIT_BALANCE_MISMATCH` alone
+  **stops firing** on these documents when you upgrade, because through `0.0.12` the undecoded term
+  collapsed to zero and raised the mismatch. This library warns either way; your gate has to look
+  for both. The recipes in `docs-content/quickstart.md` and `docs-content/cookbook.md` and the
+  triage table in `docs-content/troubleshooting.md` were corrected with the code, and a committed
+  test pins that the one-code gate misses a document the two-code gate catches.
+
+- **🩺 `X12_837_PAY_TO_ADDRESS_REPEATED`, the 28th Tier-2 warning code, plus the public factory
+  `payToAddressRepeated(position)`** (`X12-PAY-TO-FUSION`). Raised at the **second and each
+  subsequent `NM1*87` within one Loop 2000A**, where the TR3s allow Loop 2010AB at most once.
+  `position.segmentIndex` names the repeated `NM1*87` itself and carries no `elementIndex`: what is
+  reported is a second occurrence of the segment, not a defect in any element of it. The counter
+  resets at the Loop 2000A `HL`, beside the pay-to slot it guards, so a first `NM1*87` under a later
+  billing provider is a first and not a repeat.
+
+  The model has **one** pay-to address slot, so it cannot carry two, and this code is the only thing
+  that says the document named two. It reports that the **document** repeated the loop; it does not
+  report that anything was mis-read, and it says nothing about the subjects of the other 837 codes.
+  An `NM1*87` arriving while a `CLM` is open never reaches the pay-to route at all, so it neither
+  warns nor arms the warning. **Where it lands instead is not stated as one destination, because two
+  were measured:** with a Loop 2400 open it joins that line's `serviceLine.providers` (TR3 Loop
+  2420), and with a claim but no line open it joins `claim.providers` (Loop 2310). Both are
+  pre-existing and identical at `0.0.12`.
+
 - **🩺 `X12_837_ENTITY_SEGMENT_DISCARDED_AFTER_LX`, the 27th Tier-2 warning code, plus the public
   factory `entitySegmentDiscardedAfterLx(position)`** (`X12-DISCARD-AFTER-STRAY-LX`). Raised for
   each 837 `N3` / `N4` / `PER` / `REF` that reached **no party at all** because an earlier `LX` with
@@ -139,6 +360,130 @@ 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
+  as `X12Decimal.ZERO`, so a consumer could not tell "the sender stated zero" from "the sender stated
+  nothing" and this library presented the second as the first. Fourteen model slots carried that
+  fabrication: `X12Claim.totalCharge` (CLM-02), a service line's `charge` and `units` (SV1-02 /
+  SV2-03 / SV3-02 and SV1-04 / SV2-05 / SV3-06), `X12LineAdjudication.amountPaid` (SVD-02),
+  `X12RemitClaim.totalChargeAmount` / `totalPaymentAmount` / `patientResponsibilityAmount` (CLP-03 /
+  04 / 05), `X12RemitServiceLine.chargeAmount` / `paymentAmount` (SVC-02 / SVC-03),
+  `X12RemitPaymentHeader.totalActualPayment` and `X12PremiumPaymentHeader.totalPremiumAmount`
+  (BPR-02), `X12PremiumOpenItem.amountPaid` (RMR-04), `X12RemitAdjustment.amount` (a `CAS` triple,
+  read by both the 835 and the 837) and `X12RemitProviderAdjustment.amount` (a `PLB` pair).
+
+  **`undefined` means "this library decoded no value from that element", NOT "the element was
+  absent."** A present element holding bytes that do not decode lands there too, and
+  `X12_UNPARSEABLE_DECIMAL` at that `position.elementIndex` is the only thing that separates them.
+  Read it in exactly that direction. A **stated** zero is untouched: it still decodes, still reads
+  `0`, and keeps its lexical form, so `0.00` is still `0.00`.
+
+  **Migrating:** `x.toString()` becomes `x?.toString()` at every one of those slots, and each site is
+  a decision rather than a rewrite - an `undefined` amount is not zero, and a `?? 0` reinstates the
+  defect. If you posted cash off a slot that read `0` on `0.0.12` or earlier without also gating on
+  `.warnings`, re-read those files.
+
+  Two things this did **not** do. `elementDecimalOrZero` is a public export and is unchanged: it
+  still substitutes `X12Decimal.ZERO`, because that is its documented behaviour and a consumer
+  walking segments itself may still want it. What changed is that no reader in this library calls it
+  any more. And the 837's `X12_837_SERVICE_LINE_NOT_DECODED` is still the only thing that says WHY a
+  line's `charge` and `units` are empty: `undefined` alone does not separate "no `SVx` was decoded
+  onto this line" from "an `SVx` was decoded and carried no charge element".
+
+- **🩺 BREAKING (emit side): `Build837ServiceLineSpec.units` is now required, and `build837P` /
+  `build837I` / `build837D` refuse a service line without it** (`X12-837-SV-UNDEFINED-DECIMAL`).
+  Through `0.0.12` an omitted `units` was emitted as the literal `0` into SV1-04 / SV2-05 / SV3-06,
+  so the builder stated a service unit count no caller supplied - the read-side fabrication above,
+  running the other way. Measured on `0.0.12`: a Professional line with no `units` emitted
+  `SV1*HC:99213*8500*UN*0*11**1~`. The refusal is `X12_837_BUILD_INVALID_SPEC`, naming the structural
+  locator (`billing[0].subscriber[0].claim[0]`) and no caller value.
+
+  **Refusing rather than emitting an empty element is the stance, and it is not new here:**
+  `build277` already refuses a service line without `SVC-07` on the same grounds. The parser is
+  liberal and the serializer conservative, and a count is not something a serializer may leave for
+  the receiver to guess at. A caller that supplies `units` is unaffected in every respect, including
+  one that supplies a zero, which is emitted because the caller did state it.
+
+- **`build835` refuses a JS caller's `undefined` balance term as an invalid spec rather than throwing
+  an untyped `TypeError`** (`X12-837-SV-UNDEFINED-DECIMAL`). Unreachable from TypeScript: every term
+  of the three §1.10.2 invariants is a required `X12Decimal` on `Build835Spec`. Through `0.0.12` a JS
+  caller passing `undefined` reached `undefined.add` inside the balance guard. It is now
+  `X12_835_BUILD_INVALID_SPEC` with the registry text, and deliberately **not**
+  `X12_835_BUILD_BALANCE_MISMATCH`: nothing was measured out of balance, a required amount is simply
+  missing. Passing a raw `number` into a balance term still throws **an** untyped `TypeError` from
+  the same guard, so the documented dichotomy did not move; on some slots the message is now
+  `X12Decimal`'s own tampering text where it used to be `.add is not a function`, which the pinned
+  regex already admitted. Still disclosed in `KNOWN-LIMITATIONS.md`.
+
 - **`KNOWN-LIMITATIONS.md` now ships in the published tarball** (`X12-837-LOOP-RESIDUALS`). Two
   shipped warning messages, `X12_837_SERVICE_LINE_DROPPED` and
   `X12_837_ENTITY_SEGMENT_DISCARDED_AFTER_LX`, name that document ("see KNOWN-LIMITATIONS.md", each
@@ -556,6 +901,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **🩺 An `AMT` / `ADX` row whose amount decodes nothing is no longer dropped in silence**
+  (`X12-AMT-ADX-ABSENT-AMOUNT`). Reproduced on the base tree at `9db104b` across all four readers,
+  and the report it now raises is the `X12_AMOUNT_ROW_DROPPED` entry under **Added** above. The
+  filing that named this defect stated the bound precisely and it is repeated here because the wider
+  form is false: an **absent** amount element was silent on every channel, while a **present** one
+  holding undecodable bytes was already reported by `X12_UNPARSEABLE_DECIMAL` at its own
+  `elementIndex`. Both now also raise the new code; nothing moved off the old one.
+
+- **A cookbook sentence said an undecoded 837 service line ships `charge` and `units` as `0`.** It
+  reads `undefined` on the same release that made the rest of that page true, so the page contradicted
+  the money spec-note it links to. Corrected in passing while sweeping that paragraph for the new
+  code. This is a documentation correction only; no behaviour changed with it.
+
+- **🩺 A repeated `NM1*87` in one 837 Loop 2000A no longer fuses two pay-to addresses into one the
+  sender never sent** (`X12-PAY-TO-FUSION`). Reproduced at `0.0.12`: `payToAddress` is a bare
+  accumulator with no entity object to own it, cleared only at the next Loop 2000A `HL`. Every other
+  party gets a fresh object at its `NM1`, so a trailing `N3` / `N4` found `address === undefined` and
+  its write replaced; the two pay-to arms had nothing replaced under them and wrote onto whatever the
+  previous `NM1*87` left, `withLines` appending and `mergeAddress` falling back. Two `NM1*87`s each
+  with an `N3` and an `N4` read back **a street line from each of two addresses** plus a
+  `countryCode` taken off the **first** `N4`, on an address whose own `N4` names no country, with
+  `warnings: []`. Re-emitted through `build837P` that became a single Loop 2010AB stating a payment
+  destination no sender had stated.
+
+  **The fix is the missing object identity, not a clear.** Each `NM1*87` now opens a fresh
+  accumulator that the address arms read and write, so values from two occurrences can never meet.
+
+  **🛑 Two earlier remedies were refuted, both for one reason, and it is why the emit side was in
+  scope from the start: on this slot an emptied value is not a neutral absence, because the emit side
+  reads it.** `build837P/I/D` gates Loop 2010AB on `payToAddress !== undefined` and `emitAddress`
+  writes `N3` only for non-empty `lines` and `N4` only for a defined field. Clearing the accumulator
+  at the `NM1*87` therefore erased an address a repeat carrying no `N3` / `N4` did state, re-emitting
+  as **no pay-to loop at all**; a flag consumed by the first write after it did the same on a
+  valueless `N3` or `N4`, re-emitting as a **bare `NM1*87`**. Both are positive statements about
+  where a payment goes that no sender made. So the rule is stated in the emit side's own terms: the
+  current occurrence takes the slot **only when it states an address the emit would write at least
+  one segment for**, and an occurrence that states none leaves a stated one alone. The predicate is a
+  single shared module (`src/transactions/claim/address-segments.ts`) that `emitAddress` also asks,
+  so the reader and the writer cannot drift apart. This is the discipline the 835 already uses, where
+  the emit guard reuses the read side's own balance validators.
+
+  **A document with at most one `NM1*87` per Loop 2000A is byte-for-byte unaffected**, warning
+  channel included, and that is pinned both ways.
+
+  **🩺 The cost, stated rather than argued away: a repeat that states only part of an address now
+  re-emits only that part.** A second `NM1*87` followed by an `N4` and no `N3` reads back that `N4`
+  with `lines: []` and re-emits a Loop 2010AB with no `N3`. Keeping the earlier occurrence's street
+  lines there **is** the fusion: one sender's street under another sender's city. The loop is still
+  present, the warning is on the channel, and what is gone is the fabricated street.
+  `KNOWN-LIMITATIONS.md` records it.
+
 - **🩺 `build278Request` / `build278Response` refuse a review whose HL-03 level code is outside `EV`
   and `SS`, instead of emitting a review its own reader cannot decode**
   (`REFUSAL-MESSAGE-PHI-ECHO`). `Build278ReviewSpec.levelCode` is the **one** caller-supplied HL-03 in
@@ -633,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.