@cosyte/x12 0.0.12 → 0.0.13

package/dist/index.cjs

@@ -145,7 +145,11 @@ 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_ENTITY_SEGMENT_DISCARDED_AFTER_LX: "X12_837_ENTITY_SEGMENT_DISCARDED_AFTER_LX"
+  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",
+  X12_AMOUNT_ROW_DROPPED: "X12_AMOUNT_ROW_DROPPED",
+  X12_STATED_AMOUNT_DISCARDED: "X12_STATED_AMOUNT_DISCARDED"
 };
 var CONTROL_NUMBER_PAIRS = {
   /** ISA-13 against IEA-02. */
@@ -206,6 +210,9 @@ var WARNING_MESSAGES = {
   X12_835_REMIT_BALANCE_MISMATCH_CLAIM: "835 balance invariant violated [CLP-04 + \u03A3(claim CAS + line CAS) == CLP-03]: the claim does not balance. Every amount is preserved verbatim on the model as an X12Decimal and is NEVER silently rebalanced.",
   X12_835_REMIT_BALANCE_MISMATCH_SERVICE_LINE: "835 balance invariant violated [SVC-03 + \u03A3(line CAS) == SVC-02]: the service line does not balance. Every amount is preserved verbatim on the model as an X12Decimal and is NEVER silently rebalanced.",
   X12_835_REMIT_BALANCE_MISMATCH_REMIT_TOTAL: "835 balance invariant violated [\u03A3(CLP-04) - \u03A3(PLB amounts) == BPR-02]: the remittance total does not balance. Every amount is preserved verbatim on the model as an X12Decimal and is NEVER silently rebalanced.",
+  X12_835_BALANCE_NOT_EVALUABLE_CLAIM: "835 balance invariant [CLP-04 + \u03A3(claim CAS + line CAS) == CLP-03] could not be evaluated: at least one term of it is `undefined` on the model, meaning this library decoded no value from that element. The equation is NOT reported as violated and NOT reported as satisfied, because an absent term has no value to compare - substituting 0 for it would be this library asserting a total the sender never sent. Which term is missing is read off the model, never from this message. Compare `X12_835_REMIT_BALANCE_MISMATCH`, which is raised only where every term decoded and the equation is genuinely out of balance.",
+  X12_835_BALANCE_NOT_EVALUABLE_SERVICE_LINE: "835 balance invariant [SVC-03 + \u03A3(line CAS) == SVC-02] could not be evaluated: at least one term of it is `undefined` on the model, meaning this library decoded no value from that element. The equation is NOT reported as violated and NOT reported as satisfied, because an absent term has no value to compare - substituting 0 for it would be this library asserting a total the sender never sent. Which term is missing is read off the model, never from this message. Compare `X12_835_REMIT_BALANCE_MISMATCH`, which is raised only where every term decoded and the equation is genuinely out of balance.",
+  X12_835_BALANCE_NOT_EVALUABLE_REMIT_TOTAL: "835 balance invariant [\u03A3(CLP-04) - \u03A3(PLB amounts) == BPR-02] could not be evaluated: at least one term of it is `undefined` on the model, meaning this library decoded no value from that element. The equation is NOT reported as violated and NOT reported as satisfied, because an absent term has no value to compare - substituting 0 for it would be this library asserting a total the sender never sent. Which term is missing is read off the model, never from this message. Compare `X12_835_REMIT_BALANCE_MISMATCH`, which is raised only where every term decoded and the equation is genuinely out of balance.",
   X12_UNKNOWN_CARC: "Unknown CARC: the claim adjustment reason code is outside the bundled snapshot. The verbatim code is preserved on the adjustment; only its description is unavailable.",
   X12_UNKNOWN_RARC: "Unknown RARC: the remittance advice remark code is outside the bundled snapshot. The verbatim code is preserved on the remark; only its description is unavailable.",
   X12_HL_PARENT_MISMATCH: "HL-02 declares a parent id that no earlier HL in this transaction set emitted as its HL-01. The declared pointer is preserved verbatim and the hierarchy is NEVER silently re-numbered.",
@@ -220,10 +227,13 @@ var WARNING_MESSAGES = {
   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.",
   X12_UNPARSEABLE_DECIMAL: "Unparseable decimal: the element at `position.elementIndex` held bytes this library could not decode as a decimal, so NO value was decoded from it. Whatever occupies that slot on the model, including 0 and undefined, is a stand-in and is NOT a value the sender supplied. The verbatim bytes are preserved on the segment; read them there before acting on the amount, quantity or percent.",
-  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` hold 0 as a stand-in and are NOT values the sender supplied; 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_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_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_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.",
+  X12_STATED_AMOUNT_DISCARDED: "Stated amount discarded: the RMR or AMT at `position.segmentIndex` populated its amount element and this reader built NO row for it, for a reason that is not a failure to decode that amount. What the sender wrote reaches no part of the typed model, so an empty list of open items or amounts is not evidence the sender stated none. Read that as the only claim made here: this code does NOT assert the amount is decodable, and on the RMR route below it is raised without the bytes ever being DECODED, so they may be unreadable, blank-but-present, or a lone component separator. Two routes reach it and this code does not say which. First, an 820 RMR whose RMR-01 and RMR-02 are BOTH empty while a remittance loop is open: the open item is refused on identity before RMR-04 or RMR-05 is read at all, so a stated payment amount, a stated amount due and the payment action code beside them go together. Second, an 837 AMT arriving while a Loop 2430 line adjudication is open: AMT-02 decoded, and the v1 adjudication model carries no amount row to put it on, so the row is skipped. Compare `X12_AMOUNT_ROW_DROPPED`, which reports the other situation on the same segments: there the amount element decoded no value, so there was no row to build at all. The two can never name the same segment. Read the bound literally, as a property of the READ: this reports a segment whose amount element the sender populated, arriving while the loop that would carry its row was open. It does NOT report an AMT or ADX that reaches a reader with no such loop open, which stays silent and is recorded in KNOWN-LIMITATIONS.md. And on the RMR route it says nothing about whether that 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. Nothing is fabricated to stand in. The verbatim segments are preserved on the transaction set; read them there before concluding the document stated no such amount."
 };
 var ALL_WARNING_MESSAGES = new Set(
   Object.values(WARNING_MESSAGES)
@@ -245,6 +255,11 @@ var BALANCE_INVARIANT_MESSAGES = {
   [BALANCE_INVARIANTS.SERVICE_LINE]: WARNING_MESSAGES.X12_835_REMIT_BALANCE_MISMATCH_SERVICE_LINE,
   [BALANCE_INVARIANTS.REMIT_TOTAL]: WARNING_MESSAGES.X12_835_REMIT_BALANCE_MISMATCH_REMIT_TOTAL
 };
+var BALANCE_NOT_EVALUABLE_MESSAGES = {
+  [BALANCE_INVARIANTS.CLAIM]: WARNING_MESSAGES.X12_835_BALANCE_NOT_EVALUABLE_CLAIM,
+  [BALANCE_INVARIANTS.SERVICE_LINE]: WARNING_MESSAGES.X12_835_BALANCE_NOT_EVALUABLE_SERVICE_LINE,
+  [BALANCE_INVARIANTS.REMIT_TOTAL]: WARNING_MESSAGES.X12_835_BALANCE_NOT_EVALUABLE_REMIT_TOTAL
+};
 var REQUIRED_LOOP_MESSAGES = {
   [REQUIRED_LOOPS.BILLING_PROVIDER_2000A]: WARNING_MESSAGES.X12_MISSING_REQUIRED_LOOP_2000A,
   [REQUIRED_LOOPS.SUBSCRIBER_2000B]: WARNING_MESSAGES.X12_MISSING_REQUIRED_LOOP_2000B,
@@ -335,6 +350,13 @@ function remitBalanceMismatch(position, invariant) {
     position
   };
 }
+function balanceNotEvaluable(position, invariant) {
+  return {
+    code: WARNING_CODES.X12_835_BALANCE_NOT_EVALUABLE,
+    message: BALANCE_NOT_EVALUABLE_MESSAGES[invariant],
+    position
+  };
+}
 function unknownCarc(position) {
   return {
     code: WARNING_CODES.X12_UNKNOWN_CARC,
@@ -412,6 +434,13 @@ function entitySegmentDiscardedAfterLx(position) {
     position
   };
 }
+function payToAddressRepeated(position) {
+  return {
+    code: WARNING_CODES.X12_837_PAY_TO_ADDRESS_REPEATED,
+    message: WARNING_MESSAGES.X12_837_PAY_TO_ADDRESS_REPEATED,
+    position
+  };
+}
 function unknownClaimStatusCategory(position) {
   return {
     code: WARNING_CODES.X12_UNKNOWN_CLAIM_STATUS_CATEGORY,
@@ -440,6 +469,20 @@ function unparseableDecimal(position) {
     position
   };
 }
+function amountRowDropped(position) {
+  return {
+    code: WARNING_CODES.X12_AMOUNT_ROW_DROPPED,
+    message: WARNING_MESSAGES.X12_AMOUNT_ROW_DROPPED,
+    position
+  };
+}
+function statedAmountDiscarded(position) {
+  return {
+    code: WARNING_CODES.X12_STATED_AMOUNT_DISCARDED,
+    message: WARNING_MESSAGES.X12_STATED_AMOUNT_DISCARDED,
+    position
+  };
+}
 
 // src/parser/release.ts
 var RELEASE_CHAR = "?";
@@ -1900,11 +1943,13 @@ function isProcedureQualifier(qualifier) {
 // src/transactions/remit/balance.ts
 function checkClaimBalance(claim, position) {
   const claimCasSum = sumAmounts(claim.adjustments);
-  const lineCasSum = claim.serviceLines.reduce(
-    (acc, sl) => acc.add(sumAmounts(sl.adjustments)),
-    X12Decimal.ZERO
+  const lineCasSum = sumOptional(
+    claim.serviceLines.map((sl) => sumAmounts(sl.adjustments))
   );
-  const computed = claim.totalPaymentAmount.add(claimCasSum).add(lineCasSum);
+  const computed = sumOptional([claim.totalPaymentAmount, claimCasSum, lineCasSum]);
+  if (computed === void 0 || claim.totalChargeAmount === void 0) {
+    return balanceNotEvaluable(position, BALANCE_INVARIANTS.CLAIM);
+  }
   if (computed.equals(claim.totalChargeAmount)) return void 0;
   return remitBalanceMismatch(position, BALANCE_INVARIANTS.CLAIM);
 }
@@ -1914,35 +1959,37 @@ function checkServiceLineBalance(claim, position) {
     const line = claim.serviceLines[i];
     if (line === void 0) continue;
     const lineCasSum = sumAmounts(line.adjustments);
-    const computed = line.paymentAmount.add(lineCasSum);
+    const linePosition = { ...position, segmentIndex: position.segmentIndex + i + 1 };
+    const computed = sumOptional([line.paymentAmount, lineCasSum]);
+    if (computed === void 0 || line.chargeAmount === void 0) {
+      out.push(balanceNotEvaluable(linePosition, BALANCE_INVARIANTS.SERVICE_LINE));
+      continue;
+    }
     if (computed.equals(line.chargeAmount)) continue;
-    out.push(
-      remitBalanceMismatch(
-        { ...position, segmentIndex: position.segmentIndex + i + 1 },
-        BALANCE_INVARIANTS.SERVICE_LINE
-      )
-    );
+    out.push(remitBalanceMismatch(linePosition, BALANCE_INVARIANTS.SERVICE_LINE));
   }
   return out;
 }
 function checkRemitTotalBalance(bpr02, claims, providerAdjustments, position) {
-  const claimSum = claims.reduce(
-    (acc, c) => acc.add(c.totalPaymentAmount),
-    X12Decimal.ZERO
-  );
-  const plbSum = providerAdjustments.reduce(
-    (acc, p) => acc.add(p.amount),
-    X12Decimal.ZERO
-  );
+  const claimSum = sumOptional(claims.map((c) => c.totalPaymentAmount));
+  const plbSum = sumOptional(providerAdjustments.map((p) => p.amount));
+  if (bpr02 === void 0 || claimSum === void 0 || plbSum === void 0) {
+    return balanceNotEvaluable(position, BALANCE_INVARIANTS.REMIT_TOTAL);
+  }
   const computed = claimSum.subtract(plbSum);
   if (computed.equals(bpr02)) return void 0;
   return remitBalanceMismatch(position, BALANCE_INVARIANTS.REMIT_TOTAL);
 }
 function sumAmounts(adjustments) {
-  return adjustments.reduce(
-    (acc, a) => acc.add(a.amount),
-    X12Decimal.ZERO
-  );
+  return sumOptional(adjustments.map((a) => a.amount));
+}
+function sumOptional(terms) {
+  let acc = X12Decimal.ZERO;
+  for (const term of terms) {
+    if (term === void 0) return void 0;
+    acc = acc.add(term);
+  }
+  return acc;
 }
 
 // src/transactions/remit/get-835.ts
@@ -2108,7 +2155,10 @@ function get835(delimiters, tx) {
       }
       case "AMT": {
         const amount = decodeAmt(seg, delimiters, sink);
-        if (amount === void 0) break;
+        if (amount === void 0) {
+          warnings.push(amountRowDropped(position));
+          break;
+        }
         if (currentServiceLine !== void 0) currentServiceLine.amounts.push(amount);
         else if (currentClaim !== void 0) currentClaim.amounts.push(amount);
         break;
@@ -2165,7 +2215,7 @@ function get835(delimiters, tx) {
 function decodeBpr(seg, delimiters, sink) {
   return Object.freeze({
     transactionHandlingCode: elementValue(seg, 1, delimiters),
-    totalActualPayment: elementDecimalOrZero(seg, 2, delimiters, sink),
+    totalActualPayment: elementDecimal(seg, 2, delimiters, sink),
     creditDebitFlag: elementValue(seg, 3, delimiters),
     method: elementValue(seg, 4, delimiters),
     paymentFormatCode: elementOptional(seg, 5, delimiters),
@@ -2278,7 +2328,7 @@ function decodeCasAdjustments(seg, delimiters, warnings, position) {
         groupCode,
         reasonCode: code,
         reasonDescription: entry?.description,
-        amount: amount ?? X12Decimal.ZERO,
+        amount,
         quantity
       })
     );
@@ -2322,9 +2372,9 @@ function openClaim(seg, delimiters, clpSegmentIndex, sink) {
     patientControlNumber: elementValue(seg, 1, delimiters),
     claimStatusCode,
     claimStatusDescription,
-    totalChargeAmount: elementDecimalOrZero(seg, 3, delimiters, sink),
-    totalPaymentAmount: elementDecimalOrZero(seg, 4, delimiters, sink),
-    patientResponsibilityAmount: elementDecimalOrZero(seg, 5, delimiters, sink),
+    totalChargeAmount: elementDecimal(seg, 3, delimiters, sink),
+    totalPaymentAmount: elementDecimal(seg, 4, delimiters, sink),
+    patientResponsibilityAmount: elementDecimal(seg, 5, delimiters, sink),
     claimFilingIndicatorCode: elementOptional(seg, 6, delimiters),
     payerClaimControlNumber: elementOptional(seg, 7, delimiters),
     facilityTypeCode,
@@ -2360,8 +2410,8 @@ function openServiceLine(seg, delimiters, sink) {
     productServiceIdQualifier,
     productServiceId,
     modifiers,
-    chargeAmount: elementDecimalOrZero(seg, 2, delimiters, sink),
-    paymentAmount: elementDecimalOrZero(seg, 3, delimiters, sink),
+    chargeAmount: elementDecimal(seg, 2, delimiters, sink),
+    paymentAmount: elementDecimal(seg, 3, delimiters, sink),
     revenueCode,
     paidUnitsOfService,
     originalUnitsOfService,
@@ -2406,7 +2456,7 @@ function decodePlb(seg, delimiters, sink) {
         fiscalPeriodDate,
         reasonCode: reasonCode ?? "",
         subCode,
-        amount: amount ?? X12Decimal.ZERO
+        amount
       })
     );
   }
@@ -2421,7 +2471,7 @@ var EMPTY_ADDRESS = Object.freeze({
 });
 var EMPTY_HEADER = Object.freeze({
   transactionHandlingCode: "",
-  totalActualPayment: X12Decimal.ZERO,
+  totalActualPayment: void 0,
   creditDebitFlag: "",
   method: "",
   paymentFormatCode: void 0,
@@ -2841,12 +2891,24 @@ function enforceBalance(spec) {
   for (const claim of claims) {
     const claimWarn = checkClaimBalance(claim, position);
     if (claimWarn !== void 0) {
+      if (notEvaluable(claimWarn)) {
+        throw new Remit835BuildError(
+          REMIT_835_BUILD_ERROR_CODES.X12_835_BUILD_INVALID_SPEC,
+          `build835 refuses a claim whose balance cannot be checked: ${claimWarn.message}`
+        );
+      }
       throw new Remit835BuildError(
         REMIT_835_BUILD_ERROR_CODES.X12_835_BUILD_BALANCE_MISMATCH,
         `build835 refuses an out-of-balance claim: ${claimWarn.message}`
       );
     }
     for (const lineWarn of checkServiceLineBalance(claim, position)) {
+      if (notEvaluable(lineWarn)) {
+        throw new Remit835BuildError(
+          REMIT_835_BUILD_ERROR_CODES.X12_835_BUILD_INVALID_SPEC,
+          `build835 refuses a service line whose balance cannot be checked: ${lineWarn.message}`
+        );
+      }
       throw new Remit835BuildError(
         REMIT_835_BUILD_ERROR_CODES.X12_835_BUILD_BALANCE_MISMATCH,
         `build835 refuses an out-of-balance service line: ${lineWarn.message}`
@@ -2860,12 +2922,21 @@ function enforceBalance(spec) {
     position
   );
   if (totalWarn !== void 0) {
+    if (notEvaluable(totalWarn)) {
+      throw new Remit835BuildError(
+        REMIT_835_BUILD_ERROR_CODES.X12_835_BUILD_INVALID_SPEC,
+        `build835 refuses a remit whose balance cannot be checked: ${totalWarn.message}`
+      );
+    }
     throw new Remit835BuildError(
       REMIT_835_BUILD_ERROR_CODES.X12_835_BUILD_BALANCE_MISMATCH,
       `build835 refuses an out-of-balance remit: ${totalWarn.message}`
     );
   }
 }
+function notEvaluable(warn) {
+  return warn.code === WARNING_CODES.X12_835_BALANCE_NOT_EVALUABLE;
+}
 function materializeAdjustment(spec) {
   return {
     groupCode: spec.groupCode,
@@ -3239,6 +3310,17 @@ function wireLookup(entries) {
   return Object.freeze(table);
 }
 
+// src/transactions/claim/address-segments.ts
+function emitsStreetLines(address) {
+  return address.lines.length > 0;
+}
+function emitsGeographicFields(address) {
+  return address.city !== void 0 || address.state !== void 0 || address.postalCode !== void 0 || address.countryCode !== void 0;
+}
+function statesAnAddress(address) {
+  return emitsStreetLines(address) || emitsGeographicFields(address);
+}
+
 // src/transactions/claim/get-837.ts
 var VARIANT_BY_ICR = wireLookup({
   "005010X222A2": "P",
@@ -3299,6 +3381,8 @@ function get837Claims(delimiters, tx, opts) {
   let receiver;
   let billingProvider;
   let payToAddress;
+  let pendingPayToAddress;
+  let payToAddressNamed = false;
   let payToPlan;
   let currentSubscriberMember;
   let currentPayer;
@@ -3385,7 +3469,8 @@ function get837Claims(delimiters, tx, opts) {
       currentPatientMember = { ...currentPatientMember, entity: next };
     },
     setPayToAddress: (next) => {
-      payToAddress = next;
+      pendingPayToAddress = next;
+      if (statesAnAddress(next) || payToAddress === void 0) payToAddress = next;
     },
     setOtherSubscriber: (next) => {
       currentOtherSubscriber.otherSubscriber = next;
@@ -3400,7 +3485,10 @@ function get837Claims(delimiters, tx, opts) {
     getCurrentSubscriber: () => currentSubscriberMember?.entity,
     getCurrentPayer: () => currentPayer,
     getCurrentPatient: () => currentPatientMember?.entity,
-    getCurrentPayToAddress: () => payToAddress,
+    // Deliberately the CURRENT occurrence's accumulator, never the committed
+    // slot: this is the getter both address arms build onto, and reading the
+    // committed slot here is exactly what fused two `NM1*87`s.
+    getCurrentPayToAddress: () => pendingPayToAddress,
     getCurrentOtherSubscriber: () => currentOtherSubscriber?.otherSubscriber,
     getCurrentOtherPayer: () => currentOtherSubscriber?.otherPayer
   };
@@ -3422,6 +3510,8 @@ function get837Claims(delimiters, tx, opts) {
           currentPatientHl = void 0;
           billingProvider = void 0;
           payToAddress = void 0;
+          pendingPayToAddress = void 0;
+          payToAddressNamed = false;
           payToPlan = void 0;
           context = { kind: "loop2000A" };
         } else if (hl.levelCode === HL_LEVEL_CODES.SUBSCRIBER) {
@@ -3485,6 +3575,9 @@ function get837Claims(delimiters, tx, opts) {
           billingProvider = entity;
           activeEntity = { kind: "billingProvider" };
         } else if (qualifier === NM1_QUALIFIERS.PAY_TO_ADDRESS && context.kind === "loop2000A") {
+          if (payToAddressNamed) warnings.push(payToAddressRepeated(position));
+          payToAddressNamed = true;
+          pendingPayToAddress = void 0;
           activeEntity = { kind: "payToAddress" };
         } else if (qualifier === NM1_QUALIFIERS.PAY_TO_PLAN && context.kind === "loop2000A" && variant === "I") {
           payToPlan = entity;
@@ -3618,8 +3711,14 @@ function get837Claims(delimiters, tx, opts) {
       }
       case "AMT": {
         const amount = decodeAmt2(seg, delimiters, sink);
-        if (amount === void 0) break;
-        if (currentAdjudication !== void 0) break;
+        if (amount === void 0) {
+          warnings.push(amountRowDropped(position));
+          break;
+        }
+        if (currentAdjudication !== void 0) {
+          warnings.push(statedAmountDiscarded(position));
+          break;
+        }
         if (currentServiceLine !== void 0) currentServiceLine.amounts.push(amount);
         else if (currentClaim !== void 0) currentClaim.amounts.push(amount);
         break;
@@ -3909,7 +4008,7 @@ function decodeCas(seg, delimiters, warnings, position) {
         groupCode,
         reasonCode: code,
         reasonDescription: entry?.description,
-        amount: amount ?? X12Decimal.ZERO,
+        amount,
         quantity
       })
     );
@@ -3955,7 +4054,7 @@ function openClaim2(seg, delimiters, ctx, sink) {
     payer,
     patient,
     claimId: elementValue(seg, 1, delimiters),
-    totalCharge: elementDecimalOrZero(seg, 2, delimiters, sink),
+    totalCharge: elementDecimal(seg, 2, delimiters, sink),
     placeOfServiceCode: componentOptional(seg, 5, 1, delimiters),
     facilityCodeQualifier: componentOptional(seg, 5, 2, delimiters),
     claimFrequencyCode: componentOptional(seg, 5, 3, delimiters),
@@ -3981,8 +4080,8 @@ function openServiceLine2(seg, delimiters, variant, position) {
     lineNumber,
     position,
     serviceSegmentDecoded: false,
-    charge: X12Decimal.ZERO,
-    units: X12Decimal.ZERO,
+    charge: void 0,
+    units: void 0,
     unitOfMeasure: void 0,
     placeOfServiceCode: void 0,
     dates: [],
@@ -4043,9 +4142,9 @@ function decodeSv1(acc, seg, delimiters, sink) {
     if (m !== void 0) mods.push(m);
   }
   acc.modifiers = mods;
-  acc.charge = elementDecimalOrZero(seg, 2, delimiters, sink);
+  acc.charge = elementDecimal(seg, 2, delimiters, sink);
   acc.unitOfMeasure = elementOptional(seg, 3, delimiters);
-  acc.units = elementDecimalOrZero(seg, 4, delimiters, sink);
+  acc.units = elementDecimal(seg, 4, delimiters, sink);
   acc.placeOfServiceCode = elementOptional(seg, 5, delimiters);
   const pointers = [];
   for (let p = 1; p <= 4; p += 1) {
@@ -4069,9 +4168,9 @@ function decodeSv2(acc, seg, delimiters, sink) {
     if (m !== void 0) mods.push(m);
   }
   acc.modifiers = mods;
-  acc.charge = elementDecimalOrZero(seg, 3, delimiters, sink);
+  acc.charge = elementDecimal(seg, 3, delimiters, sink);
   acc.unitOfMeasure = elementOptional(seg, 4, delimiters);
-  acc.units = elementDecimalOrZero(seg, 5, delimiters, sink);
+  acc.units = elementDecimal(seg, 5, delimiters, sink);
   acc.serviceLineRate = elementDecimal(seg, 6, delimiters, sink);
   acc.nonCoveredCharge = elementDecimal(seg, 7, delimiters, sink);
 }
@@ -4086,7 +4185,7 @@ function decodeSv3(acc, seg, delimiters, sink) {
     if (m !== void 0) mods.push(m);
   }
   acc.modifiers = mods;
-  acc.charge = elementDecimalOrZero(seg, 2, delimiters, sink);
+  acc.charge = elementDecimal(seg, 2, delimiters, sink);
   acc.placeOfServiceCode = elementOptional(seg, 3, delimiters);
   const cavities = [];
   for (let p = 1; p <= 5; p += 1) {
@@ -4095,12 +4194,12 @@ function decodeSv3(acc, seg, delimiters, sink) {
   }
   acc.oralCavityArea = cavities;
   acc.prosthesisCrownInlayCode = elementOptional(seg, 5, delimiters);
-  acc.units = elementDecimalOrZero(seg, 6, delimiters, sink);
+  acc.units = elementDecimal(seg, 6, delimiters, sink);
 }
 function openAdjudication(seg, delimiters, sink) {
   return {
     otherPayerId: elementValue(seg, 1, delimiters),
-    amountPaid: elementDecimalOrZero(seg, 2, delimiters, sink),
+    amountPaid: elementDecimal(seg, 2, delimiters, sink),
     procedureQualifier: componentOptional(seg, 3, 1, delimiters),
     procedureCode: componentOptional(seg, 3, 2, delimiters),
     paidUnits: elementDecimal(seg, 5, delimiters, sink),
@@ -4629,6 +4728,12 @@ function enforceClaim(variant, claim, locator) {
         `build837${variant}: claim at ${locator} has a service line at index ${String(l)} with an empty ${line.variant === "I" ? "revenue" : "procedure"} code.`
       );
     }
+    if (line.units === void 0) {
+      throw new Claim837BuildError(
+        CLAIM_837_BUILD_ERROR_CODES.X12_837_BUILD_INVALID_SPEC,
+        `build837${variant}: claim at ${locator} has a service line at index ${String(l)} with no units. This builder will not emit a service unit count the caller did not supply; set units to an X12Decimal rather than leaving it undefined.`
+      );
+    }
   }
 }
 function emitBillingProvider(variant, billing, body, ctx, counter) {
@@ -4743,7 +4848,7 @@ function emitOtherSubscriber(other, body, ctx) {
 }
 function emitServiceLine2(variant, line, lineNumber, body, ctx) {
   body.push(ctx.seg(["LX", ctx.esc(line.lineNumber ?? String(lineNumber))]));
-  const units = line.units === void 0 ? "0" : decStr(line.units);
+  const units = decStr(line.units);
   if (line.variant === "P") {
     const proc = ctx.comp([line.procedureQualifier, line.procedureCode, ...line.modifiers ?? []]);
     const pointers = ctx.comp(line.diagnosisPointers ?? []);
@@ -4895,10 +5000,10 @@ function emitEntity(entity, body, ctx) {
   for (const ref of entity.references ?? []) body.push(emitRef2(ref, ctx));
 }
 function emitAddress(address, body, ctx) {
-  if (address.lines.length > 0) {
+  if (emitsStreetLines(address)) {
     body.push(ctx.seg(["N3", ...address.lines.map(ctx.esc)]));
   }
-  if (address.city !== void 0 || address.state !== void 0 || address.postalCode !== void 0 || address.countryCode !== void 0) {
+  if (emitsGeographicFields(address)) {
     body.push(
       ctx.seg([
         "N4",
@@ -6892,13 +6997,18 @@ function get820Payments(delimiters, tx) {
       case "RMR": {
         if (current === void 0) break;
         const item = decodeRmr(seg, delimiters, sink);
-        if (item !== void 0) current.openItems.push(item);
+        if (item !== void 0) {
+          current.openItems.push(item);
+          break;
+        }
+        if (statesAnAmount(seg, delimiters)) warnings.push(statedAmountDiscarded(position));
         break;
       }
       case "ADX": {
         if (current === void 0) break;
         const adjustment = decodeAdx(seg, delimiters, sink);
-        if (adjustment !== void 0) current.adjustments.push(adjustment);
+        if (adjustment === void 0) warnings.push(amountRowDropped(position));
+        else current.adjustments.push(adjustment);
         break;
       }
       case "REF": {
@@ -6952,7 +7062,7 @@ function freezeRemittance(acc) {
 function decodeBpr2(seg, delimiters, sink) {
   return Object.freeze({
     transactionHandlingCode: elementValue(seg, 1, delimiters),
-    totalPremiumAmount: elementDecimalOrZero(seg, 2, delimiters, sink),
+    totalPremiumAmount: elementDecimal(seg, 2, delimiters, sink),
     creditDebitFlag: elementValue(seg, 3, delimiters),
     method: elementValue(seg, 4, delimiters),
     paymentFormatCode: elementOptional(seg, 5, delimiters),
@@ -7020,6 +7130,9 @@ function decodeNm13(seg, delimiters) {
     idCode: elementOptional(seg, 9, delimiters)
   });
 }
+function statesAnAmount(seg, delimiters) {
+  return elementValue(seg, 4, delimiters) !== "" || elementValue(seg, 5, delimiters) !== "";
+}
 function decodeRmr(seg, delimiters, sink) {
   const qualifier = elementValue(seg, 1, delimiters);
   const referenceId = elementValue(seg, 2, delimiters);
@@ -7028,7 +7141,7 @@ function decodeRmr(seg, delimiters, sink) {
     qualifier,
     referenceId,
     paymentActionCode: elementOptional(seg, 3, delimiters),
-    amountPaid: elementDecimalOrZero(seg, 4, delimiters, sink),
+    amountPaid: elementDecimal(seg, 4, delimiters, sink),
     amountDue: elementDecimal(seg, 5, delimiters, sink)
   });
 }
@@ -7051,7 +7164,7 @@ var EMPTY_ADDRESS3 = Object.freeze({
 });
 var EMPTY_HEADER2 = Object.freeze({
   transactionHandlingCode: "",
-  totalPremiumAmount: X12Decimal.ZERO,
+  totalPremiumAmount: void 0,
   creditDebitFlag: "",
   method: "",
   paymentFormatCode: void 0,
@@ -7610,7 +7723,8 @@ async function* get834Enrollments(delimiters, tx) {
         if (currentCoverage === void 0) break;
         const sink = { warnings: current.warnings, position };
         const amount = decodeAmt3(seg, delimiters, sink);
-        if (amount !== void 0) currentCoverage.amounts.push(amount);
+        if (amount === void 0) current.warnings.push(amountRowDropped(position));
+        else currentCoverage.amounts.push(amount);
         break;
       }
     }
@@ -10192,7 +10306,7 @@ var profiles = Object.freeze({
 });
 
 // src/index.ts
-var VERSION = "0.0.12";
+var VERSION = "0.0.13";
 
 exports.ACK_BUILD_ERROR_CODES = ACK_BUILD_ERROR_CODES;
 exports.ALL_WARNING_MESSAGES = ALL_WARNING_MESSAGES;
@@ -10300,6 +10414,8 @@ 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.amountRowDropped = amountRowDropped;
+exports.balanceNotEvaluable = balanceNotEvaluable;
 exports.build271 = build271;
 exports.build277 = build277;
 exports.build277CA = build277CA;
@@ -10366,6 +10482,7 @@ exports.parse999 = parse999;
 exports.parseTA1 = parseTA1;
 exports.parseX12 = parseX12;
 exports.partitionWarnings = partitionWarnings;
+exports.payToAddressRepeated = payToAddressRepeated;
 exports.pre005010 = pre005010;
 exports.profiles = profiles;
 exports.readElementDecimal = readElementDecimal;
@@ -10378,6 +10495,7 @@ exports.serviceLineDropped = serviceLineDropped;
 exports.serviceLineNotDecoded = serviceLineNotDecoded;
 exports.serviceSegmentWithoutLx = serviceSegmentWithoutLx;
 exports.setDefaultProfile = setDefaultProfile;
+exports.statedAmountDiscarded = statedAmountDiscarded;
 exports.trailingGarbage = trailingGarbage;
 exports.transactionCountMismatch = transactionCountMismatch;
 exports.unescapeRelease = unescapeRelease;