@cosyte/x12 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -9,6 +9,357 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`renderCallerValue`**, plus the `BUILD_REFUSAL_VALUE_MAX_LENGTH` (63) and
+  `BUILD_REFUSAL_VALUE_MAX_RENDERED` (90) bounds. This is the single sanctioned route a
+  caller-supplied value takes into a `build*` refusal message, and both ceilings are exported so a
+  consumer can assert them rather than take them on trust - the builder-side counterpart to
+  `ALL_WARNING_MESSAGES` on the parse side. `BUILD_REFUSAL_VALUE_MAX_RENDERED` bounds the rendered
+  **fragment**, not the whole message: a message is that plus the site's own fixed template text.
+- **`X12OrphanSegment.anchor`**, plus the `X12OrphanAnchor` / `X12OrphanAnchorKind` types. Every
+  retained orphan now records **where it sat in the structure** rather than only where it sat in the
+  byte stream: `{ kind: "interchange", groupIndex }` for a segment outside every functional group,
+  `{ kind: "group", groupIndex, transactionIndex }` for one inside a group but outside every
+  transaction set, and `{ kind: "transaction", groupIndex, transactionIndex, segmentOffset }` for one
+  inside an open `ST..SE` - which only a `TA1` can be, since anything else arriving there is body
+  content. An index equal to the eventual length means "after the last one" (immediately before the
+  `GE` or the `IEA`), and `segmentOffset` is never `0` because `rawSegments[0]` is always the `ST`.
+- **`X12Interchange.orphanSegments`** and the `X12OrphanSegment` type. Every segment that falls
+  outside an `ST..SE` transaction set is now retained verbatim (`raw`, the decoded `segment`, its
+  `segmentIndex`, and the library-owned `context` discriminant) instead of being discarded.
+  `segmentIndex` equals the `position.segmentIndex` of that segment's `X12_UNEXPECTED_SEGMENT`
+  warning, so the two surfaces join without string matching. Empty for a well-formed interchange.
+  **Treat it as PHI when logging.** It sits on the model side of this library's diagnostic boundary:
+  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`.
+
+### Fixed
+
+- **A `build*` refusal message no longer grows with the value you passed in.** All twenty-three
+  caller-value slots across the ten builder modules route through `renderCallerValue`, capping the
+  rendered fragment at 90 characters. Nine are the `control number "…" exceeds the N-char spec limit`
+  refusal, where the branch fires _because_ the value is over-long; seven had no length gate at all
+  (`build999`'s ST-02 trace twice, `buildInterchange`'s transaction-set id, `build837`'s service-line
+  variant, `build834`'s INS-03 and HD-01 maintenance types, `buildTA1`'s note code); and seven are in
+  `build999`, found by adversarial review rather than by the census - the AK9-02 / AK9-03 / AK9-04
+  counts, typed `number` but reachable with a string from a `JSON.parse`d spec at 120,063 characters,
+  and three `.length` reads on caller-supplied arrays that a forged `{ length: … }` drove to 120,152.
+  Measured: a 120,000-character control number produced a **120,066-character**
+  `X12BuildError.message` from `buildInterchange` and now produces a **150-character** one. (150, not
+  90: the 90 is the ceiling on the interpolated fragment, not on the message.) **This is robustness
+  and log hygiene, not redaction, and the docs now say so** - you passed the value in and still hold
+  it, so bounding it hides nothing from you; what it buys is a fixed ceiling on anything that reaches
+  a log line or a JSON error envelope. The surviving characters are bounded but **not escaped**, and
+  on the ack path the value is not always strictly your own (TR3 005010X231A1 has AK2-02 echo the
+  acknowledged ST-02 verbatim). `err.code` remains the thing to branch on.
+- **A builder refusal handed a non-string where the types say `string` stays a typed error.**
+  `renderCallerValue` coerces rather than reading `.length` off whatever it is given, so a spec built
+  from `JSON.parse` that carries a numeric control number still raises `X12BuildError` with its
+  `code`, instead of an uncaught `TypeError` with none.
+- **The 835 remit-total balance warning points at the BPR instead of at the ST.** Its
+  `position.segmentIndex` was a literal `0`, which reads like "no segment" but is not one:
+  `tx.segments[0]` is the `ST`, so a consumer resolving the position landed on a segment with nothing
+  to do with the invariant. It is now the BPR's own 1-based body index, so
+  `tx.segments[w.position.segmentIndex]` is the segment carrying the BPR-02 the equation compares
+  against, matching the treatment claim-level and service-line warnings already had. The only
+  remaining `0` is a transaction that carries no BPR at all. The corresponding position inside
+  `build835` stays synthetic and is now named and documented as such: the builder has no parsed
+  segment stream to index into, and it consumes only the warning's `message`, which is a
+  registry lookup keyed by the invariant and therefore position-independent.
+- **A segment outside a transaction now survives a round trip, and so does its warning.**
+  `serializeX12` re-emits every entry of `ix.orphanSegments` at its structural `anchor`, so a
+  consumer who serializes an interchange and re-derives warnings from the copy no longer loses the
+  segment or the `X12_UNEXPECTED_SEGMENT` that described it. Placement is **by the anchor and never
+  by `segmentIndex`** - that index addresses the _input_ stream, which the emit does not follow, and
+  a replay keyed on it was measured splicing a stray segment into an 835's `ST..SE` body with no
+  warning on the re-parse. An anchor names a slot in the typed tree, which is invariant under both
+  the `ta1Segments` hoist and the skipped zero-length segment. Use `segmentIndex` to join an orphan
+  to its warning, never to place it.
+
+  Measured on a stray segment inserted at every position of a two-group, three-transaction
+  interchange, over five segment ids (`ZZ`, `SE`, `GE`, `ST`, `TA1`) covering all five orphan
+  `context` values and all three anchor kinds: **50 of the 50 insertions that produce an orphan
+  round-trip byte-exactly** on a base with no envelope-level `TA1`. On the same base _with_ one, all
+  **54** differ - and all 54 are byte-identical once the `TA1` is removed from both sides, so the
+  only thing that moved is the `TA1`, which moves on that base with no orphan present at all. Across
+  all 104: transaction bodies, `orphanSegments` (raw, context, anchor), `ta1Segments`,
+  `trailingBytes` and the warning multiset are unchanged by the round trip, and every emit is a fixed
+  point.
+
+  **SE-01 now counts an orphan re-emitted between the `ST` and the `SE`.** A `TA1` that arrived
+  inside an open transaction set is lifted off `tx.rawSegments` by the walker but is re-emitted
+  where it came from, so it is a segment of that transaction set for SE-01 purposes ("segments
+  included in the transaction set, including ST and SE", X12.6). Reconciling against the model alone
+  would describe bytes the serializer did not write: `{ specClean: true, recomputeCounts: true }`
+  would shrink a **correct** `SE*4*` to `SE*3*` over four emitted segments, and the inverse input
+  would draw no mismatch warning at all. Both counts now come from the emitted range, so recompute
+  is idempotent under the library's own reconciliation. An orphan emitted before the `ST` or after
+  the `SE` is outside the range and is not counted, and GE-01 / IEA-01 are unaffected because an
+  orphan is never a `GS` and never opens a transaction set.
+
+  **`KNOWN-LIMITATIONS.md` is therefore down from seven constructs to six**, and the remaining five
+  silent ones no longer include anything that loses a warning: line breaks, a doubled terminator, a
+  missing final terminator, the `TA1` reorder, and a segment whose first element is empty outside a
+  transaction (still the one construct that loses a value with no diagnostic at all - it is skipped
+  by the walker, so there is nothing on the model to re-emit, and it is deliberately unchanged here).
+  Retention and placement are still **not** promotion: no `get*` reader sees an orphan, and a `TA1`
+  inside a group still does not join `ta1Segments`. No new warning code (registry unchanged at 22
+  codes, 4 fatals), and no construct became fatal.
+
+- **Silent data loss: a segment outside a transaction was dropped from the model, and a
+  double-spaced file lost its entire interchange body.** Two defects with one cause. The envelope
+  walker raised `X12_UNEXPECTED_SEGMENT` for a segment it could not place and then discarded it, so
+  the segment's bytes were unrecoverable. Separately the line-break tolerance was exactly one
+  optional CR then one optional LF, which admitted **4 of the 15** CR/LF sequences of length 0 to 3;
+  the other 11 left a break in the stream that opened an unrecognized segment, so via the first
+  defect a uniformly **double-spaced file returned `groups: []`**.
+
+  The parser now absorbs any run of CR / LF bytes between segments (safe because a CR or LF in the
+  segment-terminator position, the byte immediately after ISA-16, is refused as the Tier-3 fatal
+  `X12_INVALID_DELIMITERS` (as it is at all four delimiter positions), so such a run is never
+  structural), and every unplaceable segment is retained on `ix.orphanSegments` through a
+  single chokepoint that raises the warning and records the segment together, so the two can never
+  disagree. Measured before, then after: CR/LF sequences of length 0 to 3 that frame correctly, **4
+  of 15 then 15 of 15**; orphan cases that retain the segment, **0 of 10 then 10 of 10** (ten
+  constructed cases over nine distinct positions). Across the
+  56 committed fixtures nothing changed: zero model divergences, zero warning divergences, zero
+  fixed-point failures, and no fixture produces an orphan.
+
+  **This fixed the model; the emit was closed separately, by anchor.** See the round-trip entry
+  below. A positional replay keyed on `segmentIndex` was built and then removed during _this_ change
+  because it was unsound: the emit is not in input order (it hoists `ta1Segments`) and skips the
+  zero-length segment a doubled terminator produces, so replaying by input index spliced the orphan
+  into whatever occupied that slot. Measured on a two-group interchange with a TA1 after the first
+  group, that put a stray segment inside an 835's `ST..SE` body between `CLP` and `SE` with **no
+  warning at all** on the re-parse, made a stray `SE` close the transaction early and corrupt SE-01,
+  and carried an orphan across the IEA into `trailingBytes`. A documented omission was preferable to
+  silent structural corruption, and there are regression tests fencing each of those shapes.
+
+  **Retention is not placement.** An orphan is not decoded by any `get*` reader, and a `TA1` inside
+  an open group is not added to `ta1Segments` (that surface means "envelope-level TA1", and is what
+  `parseTA1` reads). Neither a doubled segment terminator nor a segment whose first element is empty
+  is recorded as an orphan; both are long-standing behaviour, now stated rather than implied.
+
+  Also in this change: a trailing CR/LF run after the final segment terminator is absorbed rather
+  than surfacing as `trailingBytes` (previously `~\n\n` there produced a `trailingBytes` of `"\n~"`,
+  a byte the input never contained, plus an `X12_TRAILING_GARBAGE` warning); a double-spaced file
+  that previously produced 7 warnings now parses cleanly with none; and the five
+  `X12_UNEXPECTED_SEGMENT` messages were rewritten, since each stated that the segment was not
+  retained. No warning code was added or removed (registry unchanged at 22 warnings and 4 fatals) and
+  nothing new throws.
+
+### Documentation
+
+> **Read the "Fixed" entry above first: it ships in the same release and supersedes two statements
+> made below.** The entry below describes the state of the parser BEFORE that fix, and two of its
+> present-tense sentences are no longer true as of this release: the parser now absorbs **any run of
+> CR / LF** between segments, not "an optional CR then an optional LF"; and a segment outside a
+> transaction is **retained on `ix.orphanSegments`**, not "discarded". What still holds from it, and
+> is the reason it is kept, is the round-trip scope: `serialize(parse(s)) === s` is not guaranteed,
+> the absence of line breaks is not sufficient, `KNOWN-LIMITATIONS.md` is the canonical list at
+> **seven** constructs, and an orphan is still not re-emitted.
+
+- **Corrected the round-trip claim: `serialize(parse(s)) === s` is NOT guaranteed, and the emit is
+  byte-faithful only for the segments the parser recorded on the model.** The README described the
+  default emit mode as "byte-faithful by default" with no qualification, and line-ending handling was
+  absent from the entire consumer surface (zero mentions across the README, all nine `docs-content/`
+  pages, and `KNOWN-LIMITATIONS.md`). Meanwhile the parser absorbs an optional CR then an optional LF
+  after every segment terminator and the model has nowhere to record it. Re-measured against the
+  committed corpus: **42 of the 56 fixtures do not return byte-identical, and all 42 differ from their
+  source by line breaks and nothing else**; the remaining 14 carry no line breaks and do return
+  byte-identical.
+
+  Nothing about the emit changed. What changed is the claim. Line breaks turned out to be only the
+  most common of **six** constructs the emit does not reproduce, and the other five fire on inputs
+  containing no line breaks at all, so "my file is compact" is not sufficient grounds to expect byte
+  equality: segments outside a transaction (raised as `X12_UNEXPECTED_SEGMENT` on the first parse, then
+  discarded, so the segment **and its warning** are absent from the emit), a doubled segment terminator
+  outside a transaction, a missing final terminator (the emit supplies one), post-IEA `trailingBytes`
+  (re-joined from segment slices rather than preserved verbatim), and a **TA1 that followed a
+  functional group**, which is collected onto `ix.ta1Segments` and emitted immediately after the ISA,
+  so the emit **reorders** it (nothing is lost there: the model and warning stream round-trip
+  identically, and no position is taken on where ASC X12 requires a TA1 to sit). **Four of the six are
+  silent**, so a clean `ix.warnings` is not evidence that a round trip will be byte-exact.
+  `KNOWN-LIMITATIONS.md` now holds the canonical list, and the other sites link to it and carry the
+  load-bearing warnings rather than restating a count: `serialize(parse(s)) === s` is not guaranteed,
+  the absence of line breaks is not sufficient, and `serializeX12(parseX12(source))` must not be used
+  as a normalization step before comparing warnings.
+
+  The properties that hold are now stated **as measured over the committed corpus** rather than as
+  universals: every emit is a fixed point and re-parses to an identical model with an identical warning
+  stream, the 14 line-break-free fixtures return byte-identical, and the other 42 differ by line breaks
+  and nothing else. Two caveats bound that sweep and are stated with it: the corpus contains no
+  instance of the five non-line-break cases, and 13 of the 14 byte-identical fixtures are
+  `golden/*.edi`, which are serializer output by construction, leaving `envelope/no-trailing-crlf.edi`
+  as the only independent witness.
+
+  Also corrected: `KNOWN-LIMITATIONS.md` and `troubleshooting.md` both opened by promising the lenient
+  parser "never silently drops or garbles data". Both now scope that to a **decoded value** and name
+  the two things that are discarded. `spec-notes-tolerance.md` presented a three-tier taxonomy with no
+  slot for a silent normalization; the tiers now name it, and note that a Tier-2 unexpected segment is
+  warned about but not kept.
+
+### Documented, not fixed
+
+> **Superseded in part by the "Fixed" entry above, which ships in the same release.** The model half
+> of the entry below is now fixed: the segment is retained on `ix.orphanSegments`, and a double-spaced
+> file no longer loses its interchange body. The **round-trip** half still stands: `serializeX12` does
+> 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 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
+  segments (`~\n\n`) exceeds the one-CR-plus-one-LF tolerance and triggers exactly this, so a uniformly
+  double-spaced file loses its **entire interchange body** and parses to `groups: []`. The first parse
+  does warn, so it is detectable rather than silent, but the warning is the only signal and it cannot
+  be recovered from the emit. Long-standing behaviour, unchanged here and reproducing on the previous
+  release; now disclosed in `README`, `KNOWN-LIMITATIONS.md`, `troubleshooting.md` and
+  `spec-notes-envelope.md` rather than latent, and pinned by tests, while the fix is scoped as its own
+  item.
+
+### Tests
+
+- **The default emit mode's guarantees are locked against the whole committed corpus, not just the 13
+  goldens.** The goldens are already in the serializer's image, so they could only ever demonstrate
+  the easy half of the round trip. `test/serialize.test.ts` now discovers every `.edi` fixture from
+  disk (so a fixture added later is covered without anyone remembering) and asserts four properties per
+  fixture: the emit differs from its source by line breaks and nothing else, it re-parses to an
+  identical model with an identical warning stream, it is a fixed point, and it is byte-identical to
+  its source exactly when the source has no line breaks. A guard test asserts the corpus really
+  contains both pretty-printed and compact fixtures, so the sweep cannot pass vacuously. Separate cases
+  lock that LF, CRLF, and bare CR all normalize to one identical compact form.
+
+- **A `round-trip escape hatches` suite pins the five inputs that falsify the corpus sweep's
+  biconditional**, none of which contains a line break: a segment outside a transaction (asserting
+  both that the value is gone from the emit and that its warning does not recur on re-parse), a
+  doubled terminator, a missing final terminator, post-IEA trailing bytes, and a TA1 following a
+  functional group (asserting it is reordered ahead of the GS but not lost, and still a fixed point).
+  Each case asserts its own warning count rather than describing it, so the fact that three of them
+  are silent is pinned rather than claimed. The committed corpus contains no instance of any of them,
+  so without these the sweep would stay green while the prose around it claimed more than the sweep
+  could see. The blank-line case now asserts the actual outcome (`groups: []` and an empty emit body)
+  instead of only the warning; an earlier revision described that input as "reported not swallowed",
+  which is exactly backwards.
+
+### Security
+
+- **Warning messages are built from a frozen registry instead of from the document, closing a PHI
+  leak in every envelope control number and declared count.** Before this change
+  `X12_CONTROL_NUMBER_MISMATCH` rendered **both** sides of the disagreeing pair into `message`
+  verbatim and unbounded, on all six slots (`ISA-13`/`IEA-02`, `GS-06`/`GE-02`, `ST-02`/`SE-02`); a
+  300,000-byte trailer control number produced a 300,062-byte `message`. `X12_GROUP_COUNT_MISMATCH`,
+  `X12_TRANSACTION_COUNT_MISMATCH`, `X12_SEGMENT_COUNT_MISMATCH` and `X12_PRE_005010` did the same
+  with `IEA-01`, `GE-01`, `SE-01` and `ISA-12`, and `X12_835_REMIT_BALANCE_MISMATCH` rendered three
+  monetary amounts. Five of those six control-number slots are variable-width, so "it is only a
+  control number" was never a bound: it is free-form trading-partner text that routinely carries a
+  batch or patient-account identifier.
+
+  **No warning factory takes a value parameter any more.** Each takes a `X12Position` plus, where one
+  code covers several situations, a library-owned discriminant (`CONTROL_NUMBER_PAIRS`,
+  `UNEXPECTED_SEGMENT_CONTEXTS`, `BALANCE_INVARIANTS`, `REQUIRED_LOOPS`), and `message` is a lookup
+  into a frozen table. That replaces the previous posture, which shape-validated an echoed value
+  against a spec grammar and substituted `(non-spec)` when it did not match. The shape test held for
+  the code-list slots (CARC, RARC, HI qualifier, CSCC, CSC, maintenance type, 837 variant, segment
+  id) and could not hold for a control number, whose grammar is whatever the sender sent. Taking no
+  value at all is a property of the signature rather than a filter someone has to remember to apply.
+
+  Nothing is discarded: every value is still preserved verbatim on the model, which is where a
+  consumer that has decided it may handle PHI reads it.
+
+- **A strict-mode escalation no longer carries a snippet.** `parseX12(raw, { strict: true })` turned
+  the first Tier-2 warning into an `X12ParseError` carrying 64 bytes of the interchange, which put
+  document bytes into `err.stack` and from there into any error reporter. The escalated error now
+  carries `snippet: ""`; its `message` is the registry entry the warning carried and `position`
+  locates it. `snippet` remains on the four Tier-3 structural fatals, which are raised before the
+  envelope is readable, and remains the library's one deliberate exception.
+
+- **`X12Segment.id` is bounded to the X12 segment-id grammar.** It is a derived structural
+  identifier, the field a downstream package interpolates to say where something is, and it was a
+  verbatim copy of the segment's first element. A sender that put a 300,000-byte value there had it
+  copied into any locus built from `seg.id`. A first element outside the grammar now yields the
+  exported `NON_SPEC_SEGMENT_ID` sentinel; `seg.raw` and `seg.elements[0]` keep the bytes, so
+  round-trip stays byte-exact.
+
+- **`X12_INVALID_DELIMITERS` no longer echoes the detected element separator byte.** The message names
+  the fixed ISA position that broke instead.
+
+### Added
+
+- **`ALL_WARNING_MESSAGES`**, the frozen set of every message string the library can emit, so a
+  consumer or a conformance gate can assert `ix.warnings.every((w) => ALL_WARNING_MESSAGES.has(w.message))`.
+- **`CONTROL_NUMBER_PAIRS`, `UNEXPECTED_SEGMENT_CONTEXTS`, `BALANCE_INVARIANTS`, `REQUIRED_LOOPS`**
+  and their `X12ControlNumberPair` / `X12UnexpectedSegmentContext` / `X12BalanceInvariant` /
+  `X12RequiredLoop` types: the library-owned discriminants the warning factories now take in place of
+  a value.
+- **`NON_SPEC_SEGMENT_ID`**, the sentinel `X12Segment.id` takes when the first element is not a spec
+  segment id.
+
+### Changed
+
+- **BREAKING (pre-alpha): every exported warning factory changed signature.**
+  `controlNumberMismatch(position, pair)`, `unexpectedSegment(position, context)`,
+  `remitBalanceMismatch(position, invariant)` and `missingRequiredLoop(position, loop)` now take a
+  discriminant from the constants above; `pre005010`, `groupCountMismatch`,
+  `transactionCountMismatch`, `segmentCountMismatch`, `trailingGarbage`, `unknownCarc`,
+  `unknownRarc`, `hlParentMismatch`, `hlParentLevelInvalid`, `unknownHiQualifier`,
+  `unknown837Variant`, `unknownClaimStatusCategory`, `unknownClaimStatus` and
+  `unknownMaintenanceType` now take a `position` only.
+- **Warning messages no longer carry the declared-versus-actual counts or the balance amounts.** Both
+  sides of each are on the model (`iea.elements[1]` against `ix.groups.length`,
+  `claim.totalChargeAmount` against `claim.totalPaymentAmount` and the CAS adjustments), so the
+  information is one dereference away rather than rendered into a string a consumer logs by default.
+
+### Fixed
+
+- **Every out-of-balance claim and service line now gets a distinct warning position.** `CLP`
+  segment positions were hard-coded to `0` (`clpSegmentIndex: 0, // populated in the future`), which
+  was harmless while the message rendered the amounts and is not once the message names only the
+  equation: two claims failing the same invariant produced byte-identical warnings at byte-identical
+  positions. `position.segmentIndex` is now the CLP's own 1-based index in the transaction body, so
+  `tx.segments[position.segmentIndex]` is that exact CLP. A service-line warning's is that index plus
+  the line's zero-based ordinal plus one, which is a **unique locator rather than a pointer at the
+  SVC**: read it as "the claim whose CLP is at `segmentIndex - (ordinal + 1)`, service line
+  `ordinal`". Those cannot collide across claims: a claim with `n` service lines spans at least
+  `n + 1` body segments.
+
+- **Five `X12_UNEXPECTED_SEGMENT` messages claimed the segment was preserved; it is not.** A `GE`
+  with no open `GS`, an `ST` with no open group, an `SE` with no open transaction set, a `TA1` inside
+  a group, and a body segment outside any transaction set are all warned about and then dropped, so
+  "preserved on the prior open container" (and, in the last case, "its bytes are on `seg.raw`") named
+  a field that does not exist. Each message now says the segment is not retained and points at
+  `position.segmentIndex` in the input.
+
+- **The disclosure overclaimed on the builders, and the first correction of it still did.** It said
+  builder refusals carry structural locators and numeric totals only. Measured against the source:
+  at least **sixteen** refusal sites across **ten** `build*` modules interpolate a caller-supplied
+  value verbatim and unbounded. Nine are the shared over-long-control-number template, where the
+  branch fires **because** the value is over-long. Seven are not gated on length at all:
+  `build999` echoes the supplied ST-02 transaction-set control number in two refusals,
+  `buildInterchange` the supplied transaction-set id code, `build837` a service line's `variant`,
+  `build834` an unrecognized INS-03 and an unrecognized HD-01 maintenance type, and `buildTA1` an
+  unrecognized TA1-05 note code. Measured with a 120,000-byte value: a 120,155-byte
+  `AckBuildError.message` from `build999` (with a longer `stack` still, whose exact size depends on
+  the frame text and so is not quoted), and a 120,069-byte
+  `X12BuildError.message` from `buildInterchange`. The README, `docs-content/troubleshooting.md` and
+  `KNOWN-LIMITATIONS.md` now name the whole surface, including the ungated sites, and say to log
+  `err.code` from a builder. Bounding the builders is a separate change.
+
+- **The shipped PHI disclosure said the opposite of what the code did, in five places.**
+  `README.md`, `docs-content/troubleshooting.md`, `docs-content/spec-notes-tolerance.md`,
+  `docs-content/cookbook.md` and `KNOWN-LIMITATIONS.md` described warning messages as "bounded and
+  PHI-free by construction" and told consumers "you can log the full `.warnings` array without
+  leaking", naming `.snippet` as the one exception. The leak was in `.message`, and `.snippet` is not
+  a field on a warning at all, so the disclosure was actively green-lighting bulk logging of the
+  field that leaked. Each now describes the frozen registry, and `troubleshooting.md` states plainly
+  what `0.0.3` and earlier did so a reader on an older version is not misled.
+- **The PHI tests were green over unreachable space.** `test/transactions-remit-835.test.ts` swept a
+  fixture whose CARC and RARC values were clean for shapes that could never have appeared there, and
+  its balance-mismatch assertion **required** the leak (it matched `/spec="\d/` and `/computed=/`).
+  `test/parser-envelope.test.ts` proved the hostile segment id was filtered and said nothing about
+  the spec-shaped one. All three are replaced.
+
+### Added
+
 - **Brand lockup on the README, following the reader's colour scheme (ASSETS-P8).** The README now
   opens with the shared Cosyte lockup, above the `# @cosyte/x12` heading. It is a `<picture>`
   element: a `<source>` carrying the on-dark cut for `prefers-color-scheme: dark`
@@ -540,9 +891,12 @@ EV/SS`), and HL-04 has-child flag from the nested input tree, so an
     byte-faithful: reconstructed purely from the verbatim `.raw`
     strings the parser preserved (ISA + terminator, then each
     TA1 / GS / segment / GE / IEA terminator-joined, then any
-    `trailingBytes`), so for a Tier-1 input it reproduces the source
-    bytes exactly: the idempotency fixed point
-    `serialize(parse(s)) === s`. With `{ specClean: true }` it ALSO
+    `trailingBytes`), so for an input carrying none of the known
+    unrecorded constructs catalogued in `KNOWN-LIMITATIONS.md` it
+    reproduces the source bytes exactly. (As shipped, this
+    entry said "for a Tier-1 input", which later proved too weak: a
+    pretty-printed file is Tier 1 and does NOT reproduce exactly.)
+    With `{ specClean: true }` it ALSO
     reconciles the envelope (SE-01 / GE-01 / IEA-01 counts + the
     ISA-13↔IEA-02 / GS-06↔GE-02 / ST-02↔SE-02 control pairs),
     surfacing every mismatch via `opts.onWarning` and NEVER silently

package/README.md

@@ -42,10 +42,10 @@ That's the pitch: no schema upload, no spec knowledge. The parser accepts vendor
 ## What's inside
 
 - **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 by default; `{ 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.
+- **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.
 - **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, warning messages that carry a code and a position but never patient data, and builder refusals that carry structural locators and numeric totals only. **The one deliberate exception:** `X12ParseError.snippet` is a bounded (≤ 64 character) copy of the offending 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.
+- **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-three refusal sites across ten builder modules name a value you passed in, so you can see which control number, count or code was refused. 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. Tracked 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).
 
 See the [**Cookbook**](./docs-content/cookbook.md) for task-oriented recipes (post an 835, route 277CA rejections, round-trip a 271, walk an 837, read a 999) and [**KNOWN-LIMITATIONS.md**](./KNOWN-LIMITATIONS.md) for the honest do-not-over-trust list.