@cosyte/x12 0.0.8 → 0.0.10

package/CHANGELOG.md

@@ -9,6 +9,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **🩺 `X12ServiceLineStatus.unitsOfService` and `Build277ServiceLineSpec.unitsOfService`, the 277
+  Loop 2220 SVC-07 units of service count** (`X12-277-SVC07-NOT-DECODED`). X12 element 380
+  (Quantity), decoded as an `X12Decimal` like every other quantity in this library and never via
+  `parseFloat`. It had no representation on either side before, which is why an X212 277 this
+  library emitted was short a required element; see `### Fixed`. `undefined` still means **not
+  decoded** rather than absent, and an SVC-07 that is present but does not decode raises
+  `X12_UNPARSEABLE_DECIMAL` at `position.elementIndex` 7 while an absent one raises nothing. **SVC-05
+  stays unread on the 277 on purpose:** it is usage N in both 277 TR3s, unlike the 835 where it is
+  the Units of Service **Paid** Count. The warning registry is unchanged at 25 codes plus 4 Tier-3
+  fatals.
+
+- **🩺 `X12_837_SERVICE_LINE_DROPPED`, the 25th Tier-2 warning code, plus the public factory
+  `serviceLineDropped(position)`** (`X12-VARIANT-LOOKUP-PROTOTYPE`). Raised when an 837 `LX` opens
+  no Loop 2400 at all, so the service line reaches **no claim's** `serviceLines` - either because no
+  `CLM` is open at that point in the walk, or because the submission's variant never resolved to
+  `P` / `I` / `D`. Distinct from `X12_837_SERVICE_LINE_NOT_DECODED`, where the line is retained and
+  only its service segment went unread. `position.segmentIndex` names the `LX`, the same anchor and
+  for the same reason: it is the one segment present in every case. Nothing is fabricated to stand
+  in for the missing line and no claim is synthesized; the segments stay verbatim on `tx.segments`.
+  The registry stays additions-only.
+
+- **🩺 `X12_837_SERVICE_LINE_NOT_DECODED`, the 24th Tier-2 warning code, plus the public factory
+  `serviceLineNotDecoded(position)`** (`X12-837-SV-SILENT-ZERO`). Raised when an 837 Loop 2400
+  service line is closed without ever having decoded an `SV1` / `SV2` / `SV3` for the variant the
+  submission resolved to; see `### Fixed` for what that line was reporting instead.
+  `position.segmentIndex` names the `LX` that opened the line rather than the `SVx`, because the
+  no-`SVx`-at-all case has no `SVx` to point at. The registry stays additions-only.
+
+- **🩺 `X12_UNPARSEABLE_DECIMAL`, the 23rd Tier-2 warning code, plus `readElementDecimal` and
+  `X12DecimalWarningSink`** (`X12-QUANTITY-SILENT-DEFAULTS`). A decimal element that is **present**
+  and is not an X12 R-type decimal now says so; see `### Fixed` for what it was doing instead.
+  `readElementDecimal(seg, n, delimiters)` is the pure primitive underneath both existing helpers and
+  returns `{ value, status }` with `status` one of `"decoded"` / `"absent"` / `"unparseable"`, which
+  is the distinction a bare `undefined` could not carry. `elementDecimal` and `elementDecimalOrZero`
+  each gained an optional 4th `X12DecimalWarningSink` argument (`{ warnings, position }`); the helper
+  narrows the position to the failing `elementIndex` itself, so a caller passes the position of the
+  segment and never has to remember to do it per element. Existing 3-argument calls still compile and
+  are still silent, on purpose.
+
+- **`X12RemitServiceLine.originalUnitsOfService` / `Build835ServiceLineSpec.originalUnitsOfService`**,
+  the 835 SVC-07 Original Units of Service Count: the units as **submitted**, which a payer sends only
+  when they differ from the paid count in SVC-05. It is not a convenience field - without it the
+  corrected SVC map (see `### Changed`) would have left SVC-07 unread and unwritten, converting a
+  mis-read into a fresh silent drop. `undefined` means "same as paid", not "zero submitted".
+
+- **`requireCallerString` / `makeCallerEscaper`** (internal), the single route a caller-supplied
+  element value takes **through a builder's `esc` helper**. Read that scope literally: it is not
+  every route into an emitted segment, and the `### Fixed` entry below says which positions bypass
+  it. All nine builders now build their `esc` helper through
+  `makeCallerEscaper`, which type-checks the value before escaping and refuses through the calling
+  module's own `refuse` callback, so a wrong-typed element draws that builder's existing typed error
+  and code rather than a new shared one. `buildInterchange`, `build999`, `build271` and `build278`
+  each gained the one-line `refuseSpec` thrower they needed for it.
+
 - **`renderCallerJson`** (internal), the type-preserving half of the caller-value bound, held to the
   same `BUILD_REFUSAL_VALUE_MAX_RENDERED` ceiling as `renderCallerValue`. It exists because
   `defineProfile()` reports a bad `name` / `id` / `effect` / `fixture` with `JSON.stringify`, and that
@@ -42,6 +96,81 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a warning `message` is a frozen-registry lookup with positional metadata only, but an orphan is
   document content, verbatim, exactly like `tx.rawSegments`. Log `context` and `segmentIndex`.
 
+### Changed
+
+- **🩺 BREAKING: `build277` now REFUSES a Loop 2220 service line that carries no `unitsOfService`
+  (`X12-277-SVC07-NOT-DECODED`).** SVC-07 is usage **R** in TR3 `005010X212`, so a service line
+  without it cannot be emitted as a conformant 277. The refusal is the existing
+  `ClaimStatus277BuildError` with code `X12_277_BUILD_INVALID_SPEC`, raised as a precondition before
+  any segment is built, and its message names `SVC-07`, the TR3, and the structural locator of the
+  offending line (indices only, never a member id, name, trace or claim id). **`build277CA` is
+  deliberately unaffected:** in `005010X214` the same element is usage **S**, so the identical spec
+  still builds and simply omits the element. **The count is never defaulted in either direction** -
+  a quantity the caller did not supply is a quantity nobody sent, and a units figure is one a payer
+  reprices against. If you emit X212 277s with service lines, the first build after upgrading throws
+  until you supply the submitted count. Usage taken from the pyx12 005010 maps
+  (`277.5010.X212.xml`, `277.5010.X214.xml`), outside this repository, rather than from this
+  library's own reader.
+
+- **The committed canonical 277 fixture and its serializer golden now carry SVC-07**
+  (`test/fixtures/status/277-canonical.edi`, `test/fixtures/golden/277.edi`). The X212 fixture was
+  itself short the required element, which is part of why nothing in the suite noticed. The other
+  twelve goldens regenerate byte-identically.
+
+- **🩺 BREAKING: the 835 Loop 2110 SVC element map is corrected, in both directions
+  (`X12-SVC-ELEMENT-MAP-OFF-BY-ONE`).** Through `0.0.9` `get835` read `revenueCode` from **SVC-05**
+  and `paidUnitsOfService` from **SVC-07**, and `build835` wrote them to those same two positions
+  while hard-coding SVC-04 empty behind a comment asserting "revenue code is SVC-05 in X221A1;
+  SVC-04 unused". That comment was wrong. SVC-04 is the NUBC revenue code (X12 element 234, a
+  string), SVC-05 is the Units of Service **Paid** Count (element 380, a Quantity), and SVC-07 is
+  the **Original** Units of Service Count (element 380) - a different quantity, sent only when the
+  submitted count differs from the paid one. `revenueCode` now reads and writes **SVC-04** and
+  `paidUnitsOfService` now reads and writes **SVC-05**.
+
+  **The harm was a mis-read code system and a mis-read quantity, in both directions, silently.**
+  Measured across the six committed remit fixtures plus the golden, **8 of 8 service lines** read
+  back `revenueCode: "1"` at `0.0.9` - `1` is not a valid NUBC revenue code, it is the paid-unit
+  count from SVC-05 - while `paidUnitsOfService` came back `undefined` because SVC-07 was absent.
+  On emit, a line with revenue code `0300` and 2 paid units produced
+  `SVC*HC:99213*600.00*550.00**0300*HC:99212*2`, putting a revenue code into a **Quantity**
+  element, so a conformant receiver read `0300` as 300 units of service. It now produces
+  `SVC*HC:99213*600.00*550.00*0300*2*HC:99212`.
+
+  **Nothing in the suite could detect this and that is why it shipped.** Every existing assertion
+  was a `build835` -> `get835` round trip, which is green for any pair of positions the two modules
+  agree on. All 1,227 tests stayed green with the fix applied. The map is now pinned against literal
+  bytes in `test/transactions-remit-835-svc-element-map.test.ts`; all 11 of its cases fail on
+  `e3cdf49` and pass at head.
+
+  **The repo already contradicted itself:** `build277` / `get277Status` read and write the revenue
+  code at SVC-04, `build-277-types.ts` says so in prose, and every committed 835 fixture is written
+  to the correct map (`SVC*…**1` is an empty SVC-04 and one unit paid). Only the 835 module
+  disagreed, and only with itself.
+
+  **Sources, and what was not read. TR3 005010X221A1 is a paid X12 document; nobody here has read
+  it**, and every claim is traceable to something publicly checkable: pyx12's machine-readable
+  `835.5010.X221.A1.xml`, an independent open-source implementation of the same guide, which carries
+  the whole table and is **the source for SVC-04**; X12's own RFI #2163 for SVC-05; the base 005010
+  element dictionary, where SVC-04 is a string and SVC-05/07 are Quantities, which rules out a
+  revenue code at SVC-05 on type alone; and two published payer companion guides. **Agreement with
+  this repo's own 277 modules is corroborating, not a source** - checking a spec claim against the
+  implementation only proves the two agree, which is how the wrong map survived. Listed with links
+  in `KNOWN-LIMITATIONS.md`.
+
+  **Also disclosed rather than fixed:** `undefined` on either quantity means "not decoded", not
+  "absent" - the element may have been present and unparseable, which raises no warning and is
+  pre-existing at every quantity site. And **835s this library emitted at `0.0.9` or earlier are
+  non-conformant on the wire and should be re-emitted**: their revenue code sits in SVC-05, so this
+  release reads it back as a paid quantity and reports no revenue code.
+
+- **`escapeRelease` now throws `TypeError` on a non-string instead of returning `""`.** Previously it
+  gave three different wrong answers depending on what arrived: a number, a boolean or a plain object
+  returned the empty string silently; `null` and `undefined` threw on the property read; an array or
+  an array-like threw on `charAt`. All three now terminate the same way. A `TypeError` rather than a
+  code-tagged library error is deliberate: it is a pure text utility with no spec, element or caller
+  context to name. Nothing inside the library can reach it, because all nine builders refuse
+  first with their own typed, code-tagged error.
+
 ### Security
 
 - **The PHI scanner refuses an in-scope entry that is not a regular file, on both of its enumerating
@@ -111,6 +240,292 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **🩺 An X212 277 this library emitted with a service line was short a required element, and every
+  277 it read silently discarded the submitted units** (`X12-277-SVC07-NOT-DECODED`). `get277Status`
+  read SVC-01 through SVC-04 and stopped; `build277` emitted exactly those four. SVC-07, the units of
+  service count, is usage **R** in `005010X212`, so **every X212 277 this library produced with a
+  Loop 2220 service line was non-conformant on the wire**, and the count a submitter sent never
+  reached the model on the way back in. Both directions now carry it, and `build277` refuses rather
+  than emit a line without it (see `### Changed`).
+
+  **Only bytes could have caught this.** Every service-line assertion in the suite was a `build277`
+  to `get277Status` round trip through one self-consistent four-element map, so it was green for any
+  subset the two modules agreed on, including a subset missing a required element. A round trip
+  cannot test an element map, and it cannot test an element usage at all. The new pins in
+  `test/transactions-status-277-svc07.test.ts` parse literal EDI and compare literal segment strings:
+  **16 of its 21 cases are red against a clean `c34770c` checkout**, and the five that are green are
+  the negative pins that were already true (SVC-05 stays unread, an absent SVC-07 warns nothing, a
+  277CA line with no units emits no placeholder).
+
+  **🩺 Read the scope literally: ONE element's usage was fixed, and an emitted service line is NOT
+  thereby conformant.** This was not a 277 usage audit and **no census of what remains is published**,
+  on purpose: other required elements of the same `SVC` are still unguarded and finding another is
+  expected rather than a new defect. To name two, `SVC-01` and `SVC-02` are both usage **R** in X212
+  and both optional on `Build277ServiceLineSpec`, so a line supplying only `unitsOfService` still
+  emits `SVC*******1~` with no refusal. **The missing guard is what is pre-existing, not that byte
+  string** - at base the same spec emitted a bare `SVC~`, because the slot did not exist. `SVC-03` is usage **R**
+  in X212 and usage **N** in X214 and is optional in both builders. And the read side still raises
+  **no** warning for an X212 277 that arrives with no SVC-07, because a lenient reader saying so
+  needs a new Tier-2 registry code. 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.
+  `KNOWN-LIMITATIONS.md` carries the same statement.
+
+- **🩺 A lookup keyed by document bytes can no longer be defeated by a key inherited from
+  `Object.prototype` (`X12-VARIANT-LOOKUP-PROTOTYPE`).** Several lookup tables were plain object
+  literals, which inherit `Object.prototype`, so an inbound value matching **any own property of
+  `Object.prototype`** resolved TRUTHY against them. That set is engine- and version-dependent and
+  is deliberately not enumerated here; on the Node 22 this package targets it is twelve members, and
+  a draft of this entry listed eight. `Object.freeze` did not help: it seals the own properties and
+  changes nothing about the prototype chain. What that cost, measured at `a33c208`:
+  - **🩺 An ST-03 of `constructor` took every 837 service line off the model, silently.**
+    `VARIANT_BY_ICR` answered the `Object` constructor, so `submission.variant` was a **function**
+    rather than one of `P` / `I` / `D` / `unknown`, `X12_837_UNKNOWN_VARIANT` never fired, and
+    `openServiceLine` - which answers `undefined` for anything that is not a known variant - dropped
+    **every Loop 2400**, its charge, its units and its procedure code, with `warnings: []`.
+  - **🩺 `lookupCarc("constructor")` answered a `CodeListEntry` whose `description` was a function**,
+    on a field typed `string`, and suppressed `X12_UNKNOWN_CARC`. The guard is now in `makeLookup`,
+    the single factory every bundled snapshot is read through, so the other bundled lists are
+    covered by the same fix.
+  - **🩺 An HI qualifier of `constructor` suppressed `X12_UNKNOWN_HI_QUALIFIER`** while still
+    landing the code with `codeSystem: "unknown"` - an unresolvable code system on a diagnosis, with
+    nothing on any channel to say so.
+  - **An HL-03 of `constructor` raised `X12_HL_PARENT_LEVEL_INVALID`** against a level code the
+    walker has no expectation for: a structural violation the document never made. The 271 / 277 /
+    278 readers were never exposed - they share `src/transactions/shared/hl.ts`, which has always
+    guarded this read with `hasOwnProperty`; the 837's local copy did not.
+  - **`isClaimAdjustmentGroupCode("constructor")` answered `true`** and narrowed a non-code to
+    `ClaimAdjustmentGroupCode`. It used `in`, which **walks the prototype chain**: the safe-looking
+    form, not the safe form. It is now `Object.hasOwn`.
+
+  Every one of these now behaves exactly as it does for any other unrecognized value, which is the
+  whole of the claim: each fixed case is pinned against an honest-control case in the same slot, and
+  the suite derives its key list from `Object.getOwnPropertyNames(Object.prototype)` at run time
+  rather than from a list anyone maintains.
+  Tables this package declares itself are built through the new internal
+  `wireLookup` (`Object.create(null)`, then frozen), so the absent prototype protects future read
+  sites too; tables it receives from a caller are guarded with `Object.hasOwn` at the read, the form
+  `shared/hl.ts` already used. **No model shape and no message text changed**, and no code-list
+  content changed.
+
+- **🩺 An 837 `LX` that opens no Loop 2400 no longer drops the whole service line in silence
+  (`X12-VARIANT-LOOKUP-PROTOTYPE`).** Two routes reached it: an `LX` arriving before any `CLM`,
+  which produced `claims: []` and `warnings: []` even with a charge and units on the wire; and a
+  submission whose variant is not one of `P` / `I` / `D`, where `openServiceLine` answers
+  `undefined` and the line was never opened. Both now raise `X12_837_SERVICE_LINE_DROPPED` at the
+  `LX`. **Retention is unchanged and nothing is invented**: no claim is synthesized to hold an
+  orphan line and no variant is guessed, because either would put structure on the model that the
+  sender did not send. The segments were, and remain, verbatim on `tx.segments`.
+  **Read the scope of this code literally, because three things sit just outside it and all three
+  are unchanged.** It is anchored at the `LX`, so an `SVx` arriving with **no `LX` at all** is still
+  dropped in silence (`PRE-EXISTING`, disclosed not fixed). It does **not** travel with
+  `X12_837_UNKNOWN_VARIANT`: a caller-supplied `type` outside `"P" | "I" | "D"`, which only a
+  JavaScript or `JSON.parse`d caller can pass, reaches the second route without it, so read
+  `submission.variant` to tell the routes apart. And what becomes of a `DTP` / `AMT` / `NTE` /
+  `REF` following a dropped `LX` is route-dependent and is **not** simply "absent": see
+  `KNOWN-LIMITATIONS.md`, which states both routes.
+
+- **🩺 An 837 service line whose `SVx` never decoded no longer reads `0` / `0` in silence
+  (`X12-837-SV-SILENT-ZERO`).** `get837Claims` resolves ONE variant for the whole submission (the
+  caller's `type` option, else ST-03's implementation-convention reference, else the first `SVx`
+  present). `openServiceLine` seeds a line's `charge` and `units` at `X12Decimal.ZERO`, and
+  `decodeSv1` / `decodeSv2` / `decodeSv3` each **return before reading anything** when the line's
+  variant is not theirs. So an `SV2` line on a submission that resolved to Professional read back as
+  a `$0.00` charge for `0` units with `warnings: []`, with the procedure code, modifiers, unit of
+  measure and place of service equally undecoded; a line carrying no `SVx` at all did the same. This
+  is the residual `X12-QUANTITY-SILENT-DEFAULTS` disclosed rather than fixed, and it is the same
+  fabrication one level up: a slot a reader never read cannot warn on the decimal channel.
+
+  Measured against `d8b5085`: a conformant 837I whose ST-03 is flipped to `005010X222A2` read back
+  `0` / `0` on both service lines with `warnings: []`, where the same bytes read with their own
+  variant give `1500` / `1`. Three further probes were equally silent at base (the same file with
+  `{ type: "P" }`, an `LX` with no `SVx` at all, and the 837D fixture with `{ type: "I" }`). All four
+  now raise `X12_837_SERVICE_LINE_NOT_DECODED`; the honest 837P and 837I controls stay silent.
+
+  **Not decoding the foreign `SVx` is unchanged and is not the defect.** `SV1-02` and `SV2-03` are
+  both the line charge, so reading an `SV2` into a Professional-shaped line would mis-read money
+  rather than fail to read it. **The model is unchanged too:** `charge` and `units` are still typed
+  `X12Decimal` and still read `0`, so a consumer that never looks at `.warnings` sees what it saw
+  before. Making those slots `X12Decimal | undefined` remains a breaking change and its own slice.
+  The line is still retained, every segment stays verbatim on `tx.segments`, and a variant that
+  resolves to nothing at all is still the separate `X12_837_UNKNOWN_VARIANT` case, where no line is
+  opened and no `0` is fabricated. `KNOWN-LIMITATIONS.md` says how far that second case reaches.
+
+- **🩺 An unparseable decimal no longer becomes a confident zero in silence
+  (`X12-QUANTITY-SILENT-DEFAULTS`).** `elementDecimalOrZero` returned `X12Decimal.ZERO` for an
+  element that was **present** and did not decode, with no warning on any channel. A payer amount of
+  `1,234.56` (a thousands separator, which X12 forbids in an R-type element), `$450.00`, `450.00USD`
+  or `N/A` read back as `0` and was indistinguishable from a payer that paid nothing. A fabricated
+  amount presented as read is the same harm class as a mis-read quantity: a number nobody sent,
+  arriving as though somebody had.
+
+  The same root cause one type away: `elementDecimal` answered `undefined` for **both** "the sender
+  omitted this element" and "the sender sent bytes this library could not read", also unwarned, so
+  `undefined` at a quantity site meant "not decoded" rather than "absent" and no consumer could tell
+  which.
+
+  Every decimal read in all six transaction readers (835, 837P/I/D, 277 / 277CA, 271, 834, 820) now
+  routes through a sink and emits `X12_UNPARSEABLE_DECIMAL` at the failing `position.elementIndex`.
+  Measured on nine probes across those readers, one per site class, each substituting a single
+  numeric token in a committed fixture: at `0.0.9` **seven of the nine were completely silent**, and
+  the two that were not were the 835's `BPR-02` and `CLP-04`, which produced only
+  `X12_835_REMIT_BALANCE_MISMATCH` - a warning that names an equation, never an element, and that
+  exists in no other reader. All nine now carry `X12_UNPARSEABLE_DECIMAL` naming the element.
+
+  **What did NOT change, deliberately.** The model is unchanged: a slot typed `X12Decimal` still
+  reads `X12Decimal.ZERO`, an optional slot still reads `undefined`, and some rows are dropped whole.
+  The warning is a property of the READ rather than of what the reader then does with the result, so
+  every one of those outcomes carries it; no list of them is published, because a first draft
+  enumerated three and a review measured a fourth. A slot typed `X12Decimal` cannot express "did not
+  decode", and changing every such slot to `X12Decimal | undefined` is a breaking model change that
+  belongs in its own slice. So a consumer that reads only the model and never looks at `.warnings`
+  sees exactly what it saw before. **Gate on the warning.** Also unchanged: an **absent** element
+  still returns `X12Decimal.ZERO` and still does **not** warn, because "missing means zero" is the
+  documented convention of those slots. That does **not** make every unwarned `0` trustworthy: the
+  guarantee is exactly that an unwarned `0` **at an element a reader decoded** is a zero the sender
+  sent or omitted, and a slot a reader never read cannot warn. `KNOWN-LIMITATIONS.md` carries the
+  residual and the one measured instance of that inversion in full.
+
+- **A number passed where a builder's types say `string` no longer emits an EMPTY element. It is now
+  REFUSED, and it is deliberately not coerced.** `escapeRelease` opened with
+  `if (value.length === 0) return value;` and then looped to `value.length`. On a number `.length` is
+  `undefined`, so the early return did not fire, `i < undefined` was false, the loop body never ran,
+  and the function returned its empty accumulator. **The value vanished with no warning and no
+  error.** The types say `string`, so a TypeScript caller could not reach it; a JavaScript or
+  JSON-driven caller could, and `@cosyte/cli` is such a caller.
+
+  Measured at `0.0.8` on an otherwise valid `build835` spec with only `patientControlNumber` changed:
+  `CLP**1*500.00*450.00*50.00*MB*ICN-9001*11::1`, `ix.warnings.length === 0`, and a frozen interchange
+  that looks successful. CLP-01 is required by TR3 005010X221A1 Loop 2100 and is the key that
+  reassociates the remittance back to the 837's CLM-01. The builder's own
+  `patientControlNumber === ""` guard did not catch it, because the value was not yet a string when it
+  was checked.
+
+  **The same one line reached every escaped slot in all nine builders**, including the 837's own
+  CLM-01, the other end of that reassociation link. Measured at base by driving the shipped table
+  against a `143a6ea` worktree, one element each: `BPR*A1*450.00` became `BPR**450.00`,
+  `AK2*837*A1*005010X222A2` became `AK2*837**005010X222A2`, `NM1*IL*1*DOE*JANE****34*A1` became
+  `NM1*IL*1*DOE*JANE****34`, `ENT**2J*34*A1` became `ENT**2J*34`, `NM1*1P*2*A1` became `NM1*1P*2`,
+  `UM*HS*I*A1` became `UM*HS*I`, and `CLM*A1*150.00***11:B:1*Y*A*Y*Y` became
+  `CLM**150.00***11:B:1*Y*A*Y*Y`. Where the dropped element was trailing, the trailing-empty trim
+  removed it outright, so it is not even positionally recoverable.
+
+  **It refuses rather than coercing, and that choice is the substance of the fix.** Coercion would
+  mint a _different_ identifier: a JSON payload that carried `"0012345"` as a number has already lost
+  the leading zeros, so `String(12345)` emits a well-formed identifier that is not the one the caller
+  sent, and a remittance that reassociates to the wrong claim is worse than one that fails to
+  reassociate at all. `String(1e21)` is `"1e+21"`, `String(NaN)` is `"NaN"` and `String(0.1 + 0.2)` is
+  `"0.30000000000000004"`, none valid in an `AN`, `ID` or `Nn` element, and `X12Decimal` is already
+  the sanctioned route for numeric content. No working caller is broken, because the numeric path did
+  not work; it silently lost the field. The refusal message says why, so a caller is not nudged
+  straight into `String(value)` at the wrong boundary.
+
+  This is deliberately the OPPOSITE answer to `renderCallerValue`, which coerces for the same caller
+  mistake. A refusal message that throws replaces a typed, code-tagged error with an uncaught
+  `TypeError`, so its duty is to survive anything; an emitted document's duty is to invent nothing.
+
+  **The guard is on values routed through the escape helper, and not every element position goes
+  through it.** All of what follows was pre-existing, measured and unchanged here; it is **closed by
+  the `X12-DECIMAL-BYPASSES-THE-GUARD` entry below**, in the same unreleased window, so the residual
+  described here never reached a published version. **`esc` slots read `.toString()` off what the
+  types say is an `X12Decimal`**, so a raw number arrives already a string and is passed through: a
+  `patientResponsibilityAmount` of `0.1 + 0.2` still emits `…*0.30000000000000004*…`, `1e21` still
+  emits `…*1e+21*…` and `NaN` still emits `…*NaN*…`, each with zero warnings, which are the exact
+  three renderings this entry names as disqualifying, and an 837 service-line `units` reaches SV1-04
+  the same way. **That is a set of examples too, not a count** - a draft of this entry said the class
+  was exactly 36 slots and closed, and adversarial review measured it open. **Some string-typed
+  positions never call the escape helper at all** and emit a
+  number, or an unescaped delimiter, verbatim: the 999's `groupControlNumber` (GS-06 / GE-02),
+  `transactionSetControlNumber` (ST-02 / SE-02) and `disposition` (AK9-01 and IK5-01), the 278's
+  `levelCode` (HL-03), `groupDate` / `groupTime` (GS-04 / GS-05), and the 837's `lineNumber`
+  (LX-01). **Those are examples and not a census, deliberately:** two drafts of this
+  entry published an exhaustive count and adversarial review measured both incomplete, so the claim
+  is cut back rather than grown a third time. AK9-01 is an `ID` element bound to X12 code list 715,
+  and `build999`'s own accept-with-errors guard compares it against `"A"`, so a number walks past it
+  the same way it walked past `patientControlNumber === ""`. **The fixed-width ISA slots** go through
+  `pad` / `padControl`, so a number throws an untyped `TypeError` and a numeric
+  `interchangeControlNumber` throws a typed refusal whose text misleadingly says "exceeds the 9-char
+  spec limit"; `buildTA1` has no escape helper at all.
+
+  **The "no working caller is broken" claim holds with one measured exception:** a boxed
+  `new String("PT-ACCT-001")` built cleanly at `0.0.8` and is refused now, because `typeof` it is
+  `"object"`.
+
+- **A raw `number` in an `X12Decimal` slot is refused instead of rendered, and the type check now
+  covers every element of every segment emitted through a builder's segment joiner**
+  (`X12-DECIMAL-BYPASSES-THE-GUARD`). This closes the
+  two classes the entry above disclosed and deliberately did not fix.
+
+  **The decimal half.** `makeCallerEscaper` type-checks what reaches `esc`, but an `X12Decimal` slot
+  hands `esc` a `value.toString()`, and a raw `number` answers that with a perfectly good string. So
+  the value arrived already a string and the guard never applied. Measured at `15abbd4` with
+  `warnings.length === 0` in every case: a `patientResponsibilityAmount` of `0.1 + 0.2` emitted
+  `CLP*PT-ACCT-001*1*500.00*450.00*0.30000000000000004*…`, `1e21` emitted `…*1e+21*…`, `NaN` emitted
+  `…*NaN*…`, an 837 service-line `units` of `0.1 + 0.2` emitted
+  `SV1*HC:99213*150.00*UN*0.30000000000000004***1`, and a diagnosis `monetaryAmount` reached
+  `HI*ABK:J20.9:::0.30000000000000004`. **Two of those three renderings the library cannot parse
+  back** - `X12_DECIMAL_RE` rejects exponent notation and `NaN` - so they did not round-trip; the
+  IEEE-754 artifact is worse in the other direction, being well-formed enough that nothing downstream
+  refuses it. Every such slot now emits through that builder's `escDec`, over `requireCallerDecimal`.
+
+  **Why refuse and not round, which is the decision:** rounding `0.1 + 0.2` to `0.30` guesses cents
+  and to `0.3` guesses tenths, and guessing the scale of a monetary amount is what `X12Decimal` exists
+  to prevent. Same answer as the entry above, for a reason specific to this slot: every one of these
+  is _typed_ `X12Decimal` already, so a raw `number` is a caller who defeated their own type checker
+  and no supported numeric path is taken away.
+
+  **The raw-slot half.** The string-typed positions that never called the escape helper at all are
+  routed through it: `build999`'s `groupControlNumber` (GS-06 / GE-02), `transactionSetControlNumber`
+  (ST-02 / SE-02), `disposition` (AK9-01 and IK5-01) and `groupResponsibleAgency` (GS-07);
+  `groupDate` / `groupTime` (GS-04 / GS-05) in all seven domain builders; `build278`'s `levelCode`
+  (HL-03); and `build837`'s `lineNumber` (LX-01). That closes the delimiter hole on them too -
+  `build999` with a `groupControlNumber` of `"1*BOGUS"` emitted `GS*FA*…*1*BOGUS*X*005010X231A1`,
+  shifting GS-07 and GS-08 by one, and now emits `1?*BOGUS`.
+
+  **And the part that is a property rather than a list.** Three consecutive drafts of the entry above
+  published an exhaustive counted census of the slots that bypass `esc`, and adversarial review
+  measured all three false, each time by finding one more. Counting a fourth time would repeat that,
+  so the check moved to the one place every element must pass: **the segment join**.
+  `requireCallerSegment` type-checks every element of every segment emitted **through a builder's
+  `seg` / `joinSeg` helper**, on every route in, `escDec` included. `esc` is optional on a slot; the
+  join is not. It also names the slot the way the spec does - `build999: "AK9"-01 must be a
+string, …` - which `esc` cannot, being unary.
+
+  **What is deliberately still NOT claimed.** Type safety is structural here; **delimiter safety is
+  per-slot**. A `string` carrying an active delimiter in a slot that skipped `esc` is still emitted
+  verbatim, because the segment guard passes it - only the slots named above were routed. And the
+  fixed-width ISA slots go through `pad` / `padControl` and not through the segment joiner either, so
+  they remain as the entry above describes them: an untyped `TypeError`, or for
+  `interchangeControlNumber` a typed refusal whose text misleadingly says "exceeds the 9-char spec
+  limit". Both terminate; neither is silent; neither is improved here.
+
+  **Two more exclusions, both found by the refuter against a draft that claimed more than the code
+  did, both `PRE-EXISTING` and both now pinned by tests rather than argued away.** `buildTA1` uses no
+  segment joiner and no escape helper - it joins its five caller-supplied elements directly - so a
+  numeric or `undefined` `interchangeControlNumber` still emits silently as `TA1**250101*1200*A*000`;
+  TA1-01 is the reassociation key back to the acknowledged interchange, so it is filed as its own
+  item rather than widened into here. And **`build835`'s balance-equation amounts refuse UNTYPED**:
+  `enforceBalance(spec)` runs before the escaper is built and calls `X12Decimal` methods on the
+  caller's value, so `requireCallerDecimal` is unreachable on them and the caller gets a plain
+  `TypeError` with no `code` (some saying the value was "tampered with") instead of the typed
+  refusal. **The rule, rather than a list, because a first draft of this disclosure published a
+  closed list of four and a refuter measured it incomplete:** a slot refuses untyped exactly when the
+  balance guard reads it as a term of one of the three TR3 X221A1 §1.10.2 invariants in
+  `src/transactions/remit/balance.ts`. **Named by SPEC FIELD and not by element number, because the
+  next draft used element numbers and got one wrong:** `payment.totalActualPayment`,
+  `claim.totalChargeAmount`, `claim.totalPaymentAmount`, every `adjustments[].amount` at claim and
+  line level, `serviceLine.chargeAmount`, `serviceLine.paymentAmount` and
+  `providerAdjustments[].amount`. Every other `X12Decimal` field refuses typed, including
+  `claim.patientResponsibilityAmount`, `serviceLine.paidUnitsOfService` and every `amounts[].amount`.
+  Both arms are pinned. Reordering the balance guard changes the refusal precedence of an
+  out-of-balance remit, which is its own decision.
+
+  **AK9-01 was the sharpest of the raw slots** - an `ID` element bound to X12 code list **715**
+  (a data element number, and its values are a code _list_; this repo's own `src/transactions/ack/codes.ts`
+  had it right and four other places said "code source"), so a number there told a receiver nothing
+  about whether the functional group was accepted, and `build999`'s own `X12_ACK_ACCEPT_WITH_ERRORS`
+  guard compares `disposition === "A"`, which a number walked past exactly as it walked past
+  `patientControlNumber === ""`.
+
 - **The `attw` publish gate no longer passes a tarball that carries no type declarations.** The
   `attw` script was the bare CLI, and `@arethetypeswrong/cli` returns 0 whenever its analysis found
   no types at all, before it reads the problem list. For a package that ships types, "This package
@@ -365,6 +780,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Tests
 
+- **`test/builder-string-type.test.ts`**, the emit gate for the fix above and the third member of the
+  builder-gate family (`builder-refusal-bounds` guards what a refusal says, `builder-array-bounds`
+  guards whether a refusal happens, this one guards whether the caller's value reaches the document).
+  The source scan is the exhaustive half: it requires every builder module's `esc` to be built by
+  `makeCallerEscaper` and requires no builder module to call `escapeRelease` itself, so a tenth
+  builder writing the old one-liner reds it without anyone adding a case. Negative-controlled by
+  putting the defect back: reverting one module's `esc` reds the scan by file and line **and** reds
+  the behavioural half, which is a cleaner control than the array gate gets, since there is no loop
+  here to wedge the runner.
+
 - **The PHI-scanner suite stopped paying 30 of its 32 `tsx` start-ups, and the global `testTimeout`
   now says what it does and does not cover.** No library code, no public surface and no timeout value
   changed; `scripts/phi-scan.ts` and `scripts/attw.mjs` are untouched.