@cosyte/x12 0.0.11 → 0.0.13

package/CHANGELOG.md

@@ -9,6 +9,137 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **🩺 `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 +270,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **🩺 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 +743,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
@@ -1166,6 +1404,29 @@ string, …` - which `esc` cannot, being unary.
   slot for a silent normalization; the tiers now name it, and note that a Tier-2 unexpected segment is
   warned about but not kept.
 
+- **The universal about a stray 837 `LX` is cut back in the `src/` comments and 837 test-file headers
+  the release before this one disclosed it in** (`X12-837-LOOP-RESIDUALS`). That release deleted it
+  from the documents this package publishes and disclosed, rather than claimed closed, that it still
+  stood in those two places; this is the rest of that sweep. **No count and no completeness claim is
+  published**, because both are what went stale twice here: the sites swept are the `NM1` and `LX`
+  case comments in `src/transactions/claim/get-837.ts`, and the headers, section comments and case
+  titles of `test/transactions-claim-837-loop-residuals.test.ts`,
+  `test/transactions-claim-837-discard-after-stray-lx.test.ts` and
+  `test/transactions-claim-837-variant-lookup.test.ts`. Each said a trailing `N3` / `N4` / `PER` /
+  `REF` "attached to" or "landed on" whichever party the last `NM1` left active, or that a party
+  named after the `LX` "is addressable again", all of which read as all four kinds reaching every
+  party. They do not: this reader does not surface every one of those kinds on every party. Each copy
+  takes the qualifier already graded on the shipped surfaces, "wherever this reader surfaces that
+  segment kind on that party at all", or is cut back to the measured instance beside it and that
+  instance is named - a payer in every case but one, where it is a Loop 2320 other subscriber; no
+  copy is given a new wording and **no per-kind, per-party map is published.** Counterfactual headings ("no longer attaches", "no longer leaves the last `NM1`
+  addressable") lose the counterfactual only. The bullet in `documentation/agent-notes.md` beginning
+  "RESIDUAL 1, MEASURED AT `93b2428`", and the identically-scoped paragraph in the test header it was
+  written from, are **not** copies - both are scoped by "every trailing segment that attaches to a
+  named party" - and are deliberately left alone. Nothing a consumer reads at runtime changed:
+  neither the warning registry nor any `docs-content/` page nor the README carried the wording, and
+  the executable behaviour of the swept comments is nil.
+
 ### Documented, not fixed
 
 > **Superseded in part by the "Fixed" entry above, which ships in the same release.** The model half
@@ -1174,6 +1435,20 @@ string, …` - which `esc` cannot, being unary.
 > not re-emit an orphan, so the warning still does not survive. The two entries are kept separate
 > because they were separate changes, and the sentences below describe the release before this one.
 
+- **🩺 A repeated `NM1*87` inside one 837 Loop 2000A fuses two pay-to addresses into one**
+  (`X12-837-LOOP-RESIDUALS`). The `N3` line collector appends and the `N4` merge falls back, so
+  `X12Claim.payToAddress` carries a street from each of two addresses and an `N4` field the second
+  address omitted. Reproduces unchanged at `0.0.11` and is **not** fixed here: two remedies were
+  built and both were refuted for moving the loss rather than removing it, so per ADR 0016 the unit
+  was cut back rather than given a third. Clearing the accumulator at the `NM1*87` erases the
+  address a repeat with no `N3` / `N4` of its own did state; replacing at the first following write
+  erases it on a VALUELESS `N3~` / `N4~`. **Neither erasure is a neutral absence, and that is the
+  constraint the next attempt starts from:** `build837P/I/D` emits Loop 2010AB only where the slot
+  is defined, and `emitAddress` emits `N3` only for a non-empty `lines` and `N4` only for a defined
+  field, so an emptied slot re-emits as **no pay-to loop at all** and a half-emptied one re-emits a
+  bare `NM1*87` with neither. **The emit side is therefore in scope for that fix from the start**,
+  which is what makes it its own unit. `documentation/agent-notes.md` carries the measurements.
+
 - **A segment that falls outside a transaction is dropped from the model, and its warning does not
   survive a round trip.** The envelope walker keeps body segments only while an ST..SE transaction is
   open; anything else raises `X12_UNEXPECTED_SEGMENT` and is then discarded. A **blank** line between

package/KNOWN-LIMITATIONS.md

@@ -56,28 +56,34 @@ model.
   on the emit side. All of it is pre-existing and reproduces at `e3cdf49`; widening the guard would
   have turned this into that audit, which is its own item.
 
-- **🩺 An unparseable decimal still lands on the model as a stand-in; what changed is that it warns.**
-  A decimal element that is present and that this library cannot decode as a decimal (`1,234.56`,
-  `$450.00`, `N/A`) yields no value, and the reader has to put something in its place: a slot typed
-  `X12Decimal` gets `X12Decimal.ZERO`, an optional slot gets `undefined`, and some rows are dropped
-  whole. **Every one of those outcomes now emits `X12_UNPARSEABLE_DECIMAL` at the failing
-  `position.elementIndex`, because the warning is a property of the READ rather than of what the
-  reader then does with it. No outcome is otherwise changed.** No list of the outcomes is published
-  here, on purpose: a first draft enumerated three and a review measured a fourth, and the rule is
-  what holds, not the census. So a consumer that reads only the model, and never looks at
-  `.warnings`, sees exactly what it saw before: a `0` where the payer sent something unreadable.
-  **That is the residual, stated plainly.** Closing it further means changing every `X12Decimal`
-  model slot to `X12Decimal | undefined`, which is a breaking model change and is deliberately not in
-  this slice. Gate on the warning, or read `readElementDecimal` yourself.
+- **🩺 An unparseable decimal reads `undefined`, and it warns.** A decimal element that is present
+  and that this library cannot decode as a decimal (`1,234.56`, `$450.00`, `N/A`) yields no value,
+  and the reader has to put something in its place. **Through `0.0.12` a slot typed `X12Decimal` got
+  `X12Decimal.ZERO`**, so a consumer that read only the model saw a `0` where the payer sent
+  something unreadable; **as of `0.0.13` no reader substitutes `X12Decimal.ZERO` for a value it did
+  not decode** - every slot that used to get one is `X12Decimal | undefined` and reads `undefined`,
+  which is a breaking type change on the read model and is the point of it. **Read that as a rule
+  about the substitution, not as a census of the model:** an optional slot already read `undefined`,
+  and some rows are dropped whole, which is a different shape with a report of its own
+  (`X12_AMOUNT_ROW_DROPPED`, the next entry). **Every one of those
+  outcomes emits `X12_UNPARSEABLE_DECIMAL` at the failing `position.elementIndex`, because the
+  warning is a property of the READ rather than of what the reader then does with it.** No list of
+  the outcomes is published here, on purpose: a first draft enumerated three and a review measured a
+  fourth, and the rule is what holds, not the census.
 
   Three scoping facts that are easy to get wrong in the other direction:
-  - **An ABSENT element does not warn.** "Missing means zero" is the documented convention of the
-    slots that use `elementDecimalOrZero` and is unchanged.
-  - **🩺 That does NOT make an unwarned `0` trustworthy in general, and this is the one inversion to
+  - **An ABSENT element does not raise this code.** It reads `undefined` and
+    `X12_UNPARSEABLE_DECIMAL` is not emitted for it, so `undefined` alone does not tell you which of
+    the two happened - the warning at that `elementIndex` does, and `readElementDecimal` gives you
+    the same distinction in band. Read that as a statement about **this code**, not as "an absent
+    element is silent": where the absent element takes a whole `AMT` / `ADX` row off the model, the
+    drop is reported by `X12_AMOUNT_ROW_DROPPED` at that segment (the next entry), which is
+    raised for both routes and therefore separates neither.
+  - **🩺 An unwarned value is not thereby trustworthy in general, and this is the one inversion to
     refuse.** The warning is a property of a decimal READ, not a property of a model slot. A slot
     the reader never read at all cannot warn, and it still holds whatever the accumulator was seeded
-    with. **What this guarantees is narrower and exact: an unwarned `0` AT AN ELEMENT A READER
-    DECODED is a zero the sender sent or omitted.** The known slot of the other kind, an 837 service
+    with. **What this guarantees is narrower and exact: an unwarned value AT AN ELEMENT A READER
+    DECODED is what the sender sent.** The known slot of the other kind, an 837 service
     line whose `SVx` never decoded, is covered by a warning of its own (next entry) rather than by
     this one. **No census of never-read slots is published**, on purpose: the rule is what holds.
   - **The public helpers are silent without a sink.** `elementDecimal` / `elementDecimalOrZero` take
@@ -91,23 +97,120 @@ model.
     comments. It says nothing about a decimal decoded some other way, and no exhaustive census of
     such routes is published here, on purpose.
 
-- **🩺 An 837 service line whose `SVx` never decoded still ships with `charge` and `units` at `0`;
-  what changed is that it warns.** `get837Claims` resolves ONE variant for the submission, from the
+- **🩺 An `AMT` or `ADX` whose amount does not decode loses its WHOLE row, and says so as of
+  `0.0.13`.** These segments carry an amount plus the thing the amount is about - AMT-01's qualifier,
+  ADX-02's adjustment reason code, ADX-03 / ADX-04's reference. The readers build no row at all when
+  the amount (AMT-02, ADX-01) decodes no value, so what the sender did state goes with it: through
+  `0.0.12` `AMT*B6~` gave `claim.amounts: []` and `warnings: []`, which reads exactly like a document
+  that never carried the segment. **`X12_AMOUNT_ROW_DROPPED` now reports it**, anchored at the
+  `AMT` / `ADX` and carrying **no `elementIndex`**, because one of its two routes is an absent
+  element and an absent element has no index to name. Four surfaces raise it: the 835's `AMT`, the
+  837's `AMT`, the 834's coverage `AMT` (on that **member's** own `warnings`, exactly as the decimal
+  sink beside it is scoped) and the 820's `ADX`. 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** - do not read an unchanged `claim.amounts` as evidence the warning is stale. Four
+  bounds worth stating:
+  - **It is additive, and no case moved onto it.** A present-but-undecodable amount still raises
+    `X12_UNPARSEABLE_DECIMAL` at its own `elementIndex`, now alongside this code rather than instead
+    of it, so a predicate written against that code fires on exactly the documents it fired on
+    before. Whether one accompanies this code at the same `segmentIndex` is what tells the absent
+    route from the unparseable one, since this code is raised for both and discriminates neither.
+  - **It reports a row whose AMOUNT was read and decoded no value, and nothing wider.** State it as
+    a property of the READ, not of the walker's control flow. 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 to attach to
+    (the 835's and the 837's `AMT` before any claim). **Do not write it as "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, and the reason is NOT that its row survives.**
+    `decodeRmr` drops on open-item identity (RMR-01 and RMR-02 both empty), **before** RMR-04 is
+    read. So an `RMR` that states an open item and no amount keeps its row with `amountPaid` left
+    `undefined` and there is nothing to report - but an `RMR` that states an **amount and no open
+    item** is dropped whole, taking a stated payment, its payment-action code and its amount due
+    with it. Nothing failed to decode there, so it is not this code's shape;
+    `X12_STATED_AMOUNT_DISCARDED`, below, is what reports it.
+  - **A Loop 2430 `AMT` under an open `SVD` is discarded outright, and this code is not what says
+    so.** With a claim and a line open, the 837's adjudication skip drops an `AMT` that decoded
+    perfectly well. Through `0.0.12` that was silent while one that decoded nothing raised this
+    code, so the report was present exactly where less was lost;
+    `X12_STATED_AMOUNT_DISCARDED`, below, closed that.
+
+- **🩺 A row the sender DID state can still be discarded, and says so as of `0.0.13`.** The code
+  above is about an amount this library could not read. This 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. Through `0.0.12` both routes were silent on every
+  channel. **`X12_STATED_AMOUNT_DISCARDED` reports them**, anchored at
+  the segment and carrying **no `elementIndex`**. 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 a stated payment, a stated amount due and RMR-03's payment action
+    code leave the model together. A bare `RMR~` states nothing and stays silent.
+  - 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 the row is skipped.
+    `AMT*EAF` (Remaining Patient Liability) on a Loop 2430 is exactly the shape being lost.
+
+  Three bounds worth stating:
+  - **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. The code you get is the discriminant.
+  - **It reports a segment that arrived while the loop that would carry its row was open.** An
+    `AMT` or `ADX` 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 is open. **🔴 Read "still silent"
+    literally and no wider: at those last two sites the inversion above SURVIVES.** With no claim
+    open an 835 `AMT*B6~` raises `X12_AMOUNT_ROW_DROPPED` while `AMT*B6*500.00~` raises nothing, so
+    the channel still reports the smaller loss there. `PRE-EXISTING` and unchanged by this release. And on the `RMR` route this
+    code says nothing about whether the amount would have decoded, because the row is refused before
+    the decode is attempted, so **no `X12_UNPARSEABLE_DECIMAL` accompanies it even where the bytes
+    are unreadable.** It is raised on `RMR****1,234.56~` exactly as on `RMR****150.00*150.00~`, so
+    **never 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.
+
+- **🩺 An 835 balance invariant with an undecoded term is reported as UNEVALUABLE, not as a
+  mismatch.** The three TR3 005010X221A1 §1.10.2 equations (line, claim, top-of-remit) read amounts
+  that are all `X12Decimal | undefined` as of `0.0.13`. Where any term of an equation is
+  `undefined`, the equation is not run and `X12_835_BALANCE_NOT_EVALUABLE` is emitted instead of
+  `X12_835_REMIT_BALANCE_MISMATCH`, because nothing was measured out of balance: substituting `0`
+  for the missing term would be this library asserting a total nobody sent. **Through `0.0.12` that
+  substitution is exactly what happened**, so an 835 with an absent `CLP-03` reported a mismatch
+  between the payer's own amounts and an invented zero. Two bounds worth stating:
+  - **An EMPTY list is not an absent term.** A claim carrying no `CAS` really did state no
+    adjustments, and that sums to `X12Decimal.ZERO`. Only a term this library decoded no value from
+    stops the equation.
+  - **`build835` cannot reach it from TypeScript.** Every balance term on `Build835Spec` is a
+    required `X12Decimal`. A JS caller passing `undefined` gets `X12_835_BUILD_INVALID_SPEC` (an
+    untyped `TypeError` through `0.0.12`), deliberately NOT the build-side balance-mismatch code.
+
+- **The public `elementDecimalOrZero` helper still substitutes `X12Decimal.ZERO`, and no reader in
+  this library calls it any more.** Its documented behaviour is unchanged and it stays exported, so
+  a consumer walking segments itself can still opt into the substitution - knowingly, rather than by
+  inheriting a convention the `get*` readers no longer follow. `elementDecimal` and
+  `readElementDecimal` are the honest routes.
+
+- **🩺 An 837 service line whose `SVx` never decoded ships with `charge` and `units` `undefined`,
+  and it warns.** `get837Claims` resolves ONE variant for the submission, from the
   caller's `type` option, else ST-03's implementation-convention reference, else the first `SVx`
   segment present. A Loop 2400 line is then decoded only by the `SV1` / `SV2` / `SV3` that matches
   that variant. When none arrives, because the line carries an `SVx` for a different variant (an
   ST-03 of `005010X222A2` on a file whose lines are `SV2`, or a `{ type: "P" }` over the same) or
   because it carries no `SVx` at all, **nothing on the service segment is read**: the line's
-  `charge` and `units` hold the accumulator's seeded `X12Decimal.ZERO`, and its procedure code,
+  `charge` and `units` hold the accumulator's seeded `undefined`, and its procedure code,
   modifiers, unit of measure and place of service are equally undecoded. **That line now emits
   `X12_837_SERVICE_LINE_NOT_DECODED`, anchored at the `LX` that opened it.** Read the values off
   `tx.segments[…].raw` and decide which of the two disagreeing signals the sender meant.
   - **Ignoring the foreign `SVx` is deliberate and is not the limitation.** `SV1-02` and `SV2-03`
     are both the line charge, so decoding an `SV2` into a Professional line would mis-read money.
     Refusing to read is the safe half; doing it silently was the defect.
-  - **The model is unchanged.** `charge` and `units` are still typed `X12Decimal`, so the stand-in
-    `0` is still what a consumer that never reads `.warnings` sees. Making them
-    `X12Decimal | undefined` is a breaking model change and is deliberately not in this slice.
+  - **`undefined` does not say WHY, which is what the warning is for.** `charge` and `units` are
+    `X12Decimal | undefined` as of `0.0.13` (`X12Decimal` reading a fabricated `0` through
+    `0.0.12`), so a consumer that never reads `.warnings` at least sees that nothing was decoded -
+    but it cannot tell this case, where no `SVx` was read at all, from an `SVx` that WAS read and
+    carried no charge element. Only `X12_837_SERVICE_LINE_NOT_DECODED` separates them.
   - **The line is still retained, and so are the bytes.** Nothing is dropped: the service line is
     on the claim, and every segment, decoded or not, stays verbatim on `tx.segments`.
   - **Neither cause is attributed to the sender.** A `type` option that disagrees with a perfectly
@@ -214,14 +317,15 @@ model.
   - **The segment is NOT decoded into any line.** `SV1-02` and `SV2-03` 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 does not change the `SV1-02` case
-    above:** an absent `SV1-02` on a line that DID open still reads a confident `0`, which closes
-    only with the deferred `X12Decimal | undefined` model change.
+    above:** an absent `SV1-02` on a line that DID open reads `undefined` as of `0.0.13`, a
+    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
     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
-    conformant `SV1` line in it then reads `charge` `0`, `units` `0` and an `undefined` procedure
+    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
     `{ type: "P" }` reads the same document correctly. Measured, both trees: `PRE-EXISTING`,
     identical at `0.0.10`, **not** introduced or changed by this code, and **not** narrowed here - excluding
@@ -265,6 +369,58 @@ model.
     following a **stray** `LX` belongs to is not derivable from the TR3s in either direction, so the
     reader refuses to attribute it rather than guessing.
 
+- **🩺 An 837 Loop 2000A that names the pay-to address more than once has only ONE slot on the model
+  to put it in, and the model carries one of the addresses rather than both.** The TR3s allow Loop
+  2010AB at most once per Loop 2000A, so a repeated `NM1*87` is a non-conformant document. Each one
+  raises `X12_837_PAY_TO_ADDRESS_REPEATED`, anchored at the repeated `NM1*87`, so the choice below is
+  never made in silence.
+
+  **🩺 Through `0.0.12` the two addresses were FUSED, and that is what changed.** `payToAddress` is a
+  bare accumulator with no entity object to own it, so unlike every other party there was nothing to
+  be replaced at the repeat: `withLines` appended and `mergeAddress` fell back, and two `NM1*87`s
+  each carrying an `N3` and an `N4` read back a street line from **each** address plus a
+  `countryCode` off the **first** `N4`, on an address whose own `N4` names no country, with
+  `warnings: []`. Re-emitted through `build837P` that was one Loop 2010AB naming a payment
+  destination no sender stated. **If you read a repeated `NM1*87` on `0.0.12` or earlier, treat that
+  claim's `payToAddress` as unreliable rather than as either sender's address.**
+
+  **The rule now applied, and it is stated in the emit side's terms because the emit side reads this
+  slot:** occurrences are never merged; the **last occurrence that states an address of its own**
+  takes the slot; and an occurrence that states none - one with no `N3` or `N4` at all, or only a
+  valueless `N3` / `N4` whose elements are empty - **does not blank one that did**. "States an
+  address" means exactly what `emitAddress` would write a segment for, and reader and writer share
+  one predicate so they cannot disagree. That last clause is not a nicety: `build837P/I/D` gates Loop
+  2010AB on `payToAddress !== undefined`, so a slot cleared or blanked by a repeat that stated
+  nothing would re-emit as **no pay-to loop**, or as a **bare `NM1*87`** carrying neither `N3` nor
+  `N4`. Both say something about where a payment goes that the sender did not.
+
+  **🩺 The cost, which is real and is not argued away: a repeat that states only PART of an address
+  puts only that part on the model, and 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`,
+  where `0.0.12` emitted a complete-looking address assembled from two. Keeping the earlier street
+  lines is the fusion itself, so they are not kept. **Which occurrence the sender meant is not
+  derivable from the TR3s**, and the losing occurrence's address is **not on the model in any form** -
+  `tx.segments` is where its bytes are, and remains the only complete account of the document.
+
+  **Two bounds, both measured.** This is scoped to the pay-to route, which lives in Loop 2000A: an
+  `NM1*87` arriving while a `CLM` is open never reaches that route, and is neither resolved nor
+  warned by this code. **Where it lands instead depends on whether a service line is open, and this
+  document does not state a single destination for it**, because two were measured: with a Loop 2400
+  open it joins that line's `serviceLine.providers` (a line-level provider is 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`. And a document with **at most one** `NM1*87` per Loop 2000A is unaffected in
+  every respect, warning channel included - including the pre-existing case of a lone `NM1*87` with a
+  valueless `N3`, which still reads an address with no elements and still re-emits a bare `NM1*87`.
+
+  **🩺 One thing the cost above shares with the shape that refuted remedy 2, stated so the two are
+  not read as different in kind.** In Loop 2010AB the TR3s make `NM1`, `N3` **and** `N4` all Required,
+  so a re-emitted loop carrying only the winning occurrence's `N4` is short a Required `N3`, exactly
+  as a bare `NM1*87` is short both. The difference is not conformance, it is provenance: every
+  element that IS emitted was stated by the occurrence the model kept, where the fused address
+  contained elements no single occurrence stated. Emitting a Loop 2010AB short a Required segment is
+  a pre-existing property of `emitAddress`, reachable at `0.0.12` from a lone `NM1*87` with an
+  `N4` and no `N3`, and is not introduced here.
+
 - **🩺 Through `0.0.9`, a lookup keyed by document bytes could be defeated by a key inherited from
   `Object.prototype`, and the affected code paths reported nothing.** The bundled code lists, the
   837's variant resolution, and the 837's HL parent-level map were built as plain object literals,

package/README.md

@@ -34,7 +34,7 @@ const ix = parseX12(rawEdi); // never throws except on 4 structural fatals
 const tx = ix.groups[0]?.transactions.find((t) => t.st.elements[1] === "835");
 const remit = tx ? get835(ix.delimiters, tx) : undefined;
 
-remit?.payment.totalActualPayment.toString(); // "450.00": BigInt-exact, never a float
+remit?.payment.totalActualPayment?.toString(); // "450.00": BigInt-exact, never a float
 remit?.claims[0]?.patientControlNumber; // "PT-ACCT-001": your account number, echoed back
 remit?.claims[0]?.serviceLines[0]?.adjustments[0]?.reasonCode; // "1": CARC (why it was adjusted)
 ```
@@ -45,7 +45,7 @@ That's the pitch: no schema upload, no spec knowledge. The parser accepts vendor
 
 - **Typed read + emit, per transaction**: 271, 277/277CA, 278, 820, 834, 835, 837P/I/D, plus 999/TA1 acknowledgments. Per-transaction helpers (`get835`, `get837Claims`, `get271Eligibility`, …) and a matching domain builder for each (`build835`, `build837P/I/D`, `build271`, …). The 270 and 276 inquiries parse as generic segments; they have no typed model yet.
 - **Postel's Law**: a lenient parser (deviations → warnings with a stable code + positional context) and a conservative serializer. `serializeX12` is byte-faithful **for the segments on the model** by default: each comes back verbatim, including element padding, composites, and `?`-release escapes. **`serialize(parse(s)) === s` is not guaranteed in general.** Six constructs are known not to survive: line breaks between segments (any run of CR / LF between segments is absorbed at parse, so a pretty-printed or double-spaced file emits compact), a doubled terminator outside a transaction, a missing final terminator (the emit supplies one), post-IEA `trailingBytes` (re-joined, not verbatim), a TA1 that followed a functional group (emitted right after the ISA, so it is **reordered**, though nothing is lost), and a segment whose first element is empty outside a transaction (skipped entirely, with no warning at all). A **segment outside a transaction is not on that list**: it is reported as `X12_UNEXPECTED_SEGMENT`, kept on the model at `ix.orphanSegments` with a structural `anchor`, and re-emitted at that anchor, so the segment, its value and its warning all survive the round trip - placement is by the anchor and never by `segmentIndex`, which indexes the input stream the emit does not follow. The last five break the round trip on inputs with no line breaks at all, so do not treat "no line breaks" as sufficient; five of the six are silent, so a clean warnings list does not mean byte-exact either. Measured across this repo's 56 fixtures: every emit is a fixed point and re-parses to an identical model with an identical warning stream, the 14 with no line breaks return byte-identical, and the other 42 differ by line breaks and nothing else. See [Line endings between segments](./docs-content/spec-notes-envelope.md). `{ specClean: true }` reconciles the envelope, and `{ specClean: true, recomputeCounts: true }` also emits the corrected counts (`recomputeCounts` does nothing on its own). A mismatch is always warned, never silently corrected. Only **4 structural failures** are ever fatal.
-- **Money is exact**: every monetary/percent/quantity field decodes as `X12Decimal` (string-backed, BigInt arithmetic). The library **never `parseFloat`s** an EDI amount.
+- **Money is exact, and never invented**: every monetary/percent/quantity field decodes as `X12Decimal` (string-backed, BigInt arithmetic), and the library **never `parseFloat`s** an EDI amount. **No slot holds an amount this library did not decode.** Where a reader used to substitute `X12Decimal.ZERO` the slot is now `X12Decimal | undefined` and reads `undefined`, so "the sender stated zero" and "the sender stated nothing" are different readings; through `0.0.12` they were the same `0`. That is a rule about the substitution, not a census of the model: some rows are dropped whole instead, which is a different and pre-existing shape, and no total is published here. Read [KNOWN-LIMITATIONS.md](./KNOWN-LIMITATIONS.md).
 - **Safety-critical fidelity**: TRN reassociation traces, 835 balance invariants, 837 HL hierarchy integrity, 834 maintenance types, and 278 certification actions are preserved **verbatim** and never inferred; ambiguity yields a warning or a typed refusal, never a confident wrong answer.
 - **PHI-disciplined**: synthetic-only fixtures, a PHI commit-gate, and a warning `message` that is a **lookup into a frozen registry**, not something built from your document. No warning factory in the library takes a value parameter, so no element can reach a diagnostic: the code and `position` say what and where, and the bytes stay on the model. `ALL_WARNING_MESSAGES` is exported so you can assert it. **Builder refusals are a different, and deliberately weaker, surface:** twenty-four refusal sites across ten builder modules name a value you passed in, so you can see which control number, count or code was refused. **What they will never name is a `claimId`, a member id, a member name, a trace or a diagnosis code** - a guarantee that held for the refusal templates and, until the release after `0.0.10`, did not hold for the shared type guards underneath them: a JSON-driven caller who sent a number where the types say string got `a number ("900412345678")` back, bounded but not redacted, from a guard standing on every element of every builder. Those guards report the type now and never the value. Only the segment-join guard names the slot as well; the `esc` and `X12Decimal` guards name the builder, which is a diagnostic cost stated rather than hidden. The array guard's primitive arm is redacted with them, but it still reports the `length` and the class tag of a forged array-like, bounded, because those describe the shape you forged rather than the contents of a document element. Each goes through `renderCallerValue`, capping the rendered **fragment** at `BUILD_REFUSAL_VALUE_MAX_RENDERED` (90 characters); all three names are exported so you can assert the ceiling. The whole `message` is that plus the site's own fixed text, so it is bounded by a constant but a larger one: a 120,000-character control number gave a 120,066-character `X12BuildError.message` before this and gives 150 now. That is robustness, not redaction: the value is one you supplied and bounding it hides nothing from you. It is also not escaped, and on the **ack** path it is not always strictly your own, since `build999`'s AK2-02 and `buildTA1` echo an inbound document's control numbers by design. Log `err.code`, not `err.message`, from a builder. **`defineProfile()` is bounded on the same terms since `0.0.6`** (twelve refusal sites, twenty-three caller values; the worst message measured **360,181 characters** before and **431** now, both at the `fixture` refusal, which names three caller values; the ceiling for that site is 443 and the suite asserts every site under 500; `X12ProfileError.profileName` is deliberately left unbounded so it still matches the name you passed). **And a forged non-array in a builder spec now refuses instead of hanging:** every indexed loop takes its bound from a checked array, so `{ length: "9".repeat(120000) }` draws a typed refusal rather than coercing to `Infinity` and looping forever. A few `for…of` reads still throw an untyped `TypeError` instead; both are in [KNOWN-LIMITATIONS.md](./KNOWN-LIMITATIONS.md). **The one deliberate exception:** `X12ParseError.snippet` on the four Tier-3 structural fatals is a bounded (≤ 64 character) copy of the start of the input, so on real traffic it can carry PHI. The library does not redact it. Redact at your call site, or log `err.code` and `err.position` instead. See [Keeping PHI out of logs](./docs-content/troubleshooting.md).