@cosyte/x12 0.0.18 → 0.1.0

package/KNOWN-LIMITATIONS.md

@@ -136,6 +136,34 @@ model.
     refused before this change is refused differently by it.**
   - **No census of other builders' required elements is published here.** This change measured TA1.
 
+- **🩺 Every typed reader checks the implementation guide a transaction set declares against the
+  guides that reader implements, and WARNS rather than refuses where they differ.**
+  `X12_GUIDE_NOT_IMPLEMENTED` is raised where the declared guide is outside the reader's set and
+  `X12_GUIDE_NOT_DECLARED` where nothing is declared, both anchored at the ST. The reading is
+  decoded and returned either way, against the element positions of the guide the reader
+  implements, so on a warned document a value can sit at a position the declared guide defines
+  differently. What the check keys on, exactly:
+  - **The declaration is `ST-03` decoded, then `GS-08` decoded.** `ST-03` is read post-`?`-unescape,
+    exactly as `implementationConventionReference` is published. Only where `ST-03` is absent or
+    decodes to `""` is GS-08 of the enclosing functional group read, decoded the same way; a parsed
+    transaction set carries its group's GS header on `tx.gs` for this, and one assembled by hand
+    without it is read as GS-08 absent. Nothing is trimmed, case-folded or prefix-matched, so a
+    whitespace-only or lower-cased declaration is reported as not implemented.
+  - **🛑 `ST-03` and `GS-08` are NOT reconciled.** Where `ST-03` is non-empty it alone decides and
+    GS-08 is never read, so a document whose two declarations disagree is judged on `ST-03` and
+    nothing reports the disagreement.
+  - **The implemented set is `X12_TR3_CONFORMANCE`**, each of the reader's rows contributing its
+    `tr3` and every `cfrAdopted` entry. **The 837 reader also recognises every identifier its
+    variant table resolves**, which includes the companion-guide identifiers production claims carry,
+    so a conformant claim declaring one is not accused. A 278 declaring `005010X216`, the 278
+    notification guide, is warned on both 278 readers.
+  - **What the check decides is a warning, plus one label.** A 277 whose declared guide is outside
+    `get277Status`'s set, or absent, reads `transactionType: "unrecognized-guide"`. Everything else
+    that keys on `ST-03` - the 837 variant, the choice between `claim-status` and
+    `claim-acknowledgment`, and `get277CADisposition`'s admission - still keys on the raw text and
+    did not move, so the check and those decisions can read the same `ST-03` differently where a
+    release escape is involved (see the next entry).
+
 - **🩺 `implementationConventionReference` is POST-`?`-unescape as of this release, in every typed
   reader that publishes it, and that is a behaviour change on documents whose `ST-03` carries a
   release escape.** `tx.st.elements` is the ST segment as framed:
@@ -149,8 +177,8 @@ model.
   publishes `A*B`, `A?:B` publishes `A:B`, `A?~B` publishes `A~B`, `A?^B` publishes `A^B`. Every one
   of those published the framed bytes before.
   - **🛑 What decides an outcome did NOT move, deliberately.** The 837 variant lookup, the 277 /
-    277CA `transactionType` discriminator and `get277CADisposition`'s admission gate all still key on
-    the RAW element text, so no document changes variant, discriminator or admission because of this
+    277CA `transactionType` choice between its two claim labels and `get277CADisposition`'s
+    admission gate all still key on the RAW element text, so no document changes variant, discriminator or admission because of this
     entry. That matters because the two can differ: with `componentSeparator: "X"` - a letter is an
     admissible delimiter - an `ST-03` framed as `005010?X222A1` decodes to `005010X222A1`, an
     identifier the variant table holds. Keying on the decoded text would make the declaration beat
@@ -1259,9 +1287,11 @@ Code"`, `SVC05 / 380 / "Units of Service Paid Count"`, `SVC06 / C003`,
   the long-tail codes most workflows branch on. An inbound code **outside** a snapshot still parses:
   the verbatim code is preserved on the model and an `X12_UNKNOWN_*` warning is raised. Only the
   human-readable **description** is absent (`undefined`). A stale or partial snapshot therefore yields
-  a missing description, **never a wrong code**. Run `pnpm refresh:code-lists` to audit snapshot
-  freshness; regenerating the full lists (`--fetch`) is a redistribution-terms-gated release step (see
-  below), not a runtime fetch.
+  a missing description, **never a wrong code**. Every snapshot states which it is: `meta.completeness`
+  is `"cited-subset"` on all seven today, so a lookup miss means this package does not carry the code
+  and never that the publisher did not issue it. Run `pnpm refresh:code-lists` to audit snapshot
+  freshness; regenerating the full lists (`--fetch`) is a release step gated per list on that list's
+  own recorded redistribution terms (see below), not a runtime fetch.
 
 - **`serialize(parse(s)) === s` is NOT guaranteed.** `serializeX12` rebuilds the interchange from the
   model, so every segment the parser recorded comes back verbatim (element padding, composites, and
@@ -1328,14 +1358,15 @@ Code"`, `SVC05 / 380 / "Units of Service Paid Count"`, `SVC06 / C003`,
   context and anchor), `ta1Segments`, `trailingBytes` and the warning multiset are unchanged by the
   round trip, and every emit is a fixed point.
 
-  What is **measured** across the 56 committed fixtures: every emit is a fixed point (serializing it
+  What is **measured** across every committed fixture: each emit is a fixed point (serializing it
   again is a byte-level no-op) and re-parses to an identical model with an identical warning stream;
-  the 14 fixtures with no line breaks return byte-identical; and the other 42 differ from their source
+  the fixtures with no line breaks return byte-identical; and the rest differ from their source
   by **line breaks and nothing else**, with no element value lost, altered, reordered, or re-escaped.
-  Two caveats on that corpus, both of which limit how far the sweep can be pushed: it contains **no
-  instance of cases 2 to 6** (zero fixtures produce an `orphanSegments` entry, which is why the
-  orphan sweep above is constructed rather than drawn from it), and **13 of the 14
-  byte-identical fixtures are `golden/*.edi`**, which
+  No corpus size is quoted: it moves with every fixture added, and `test/serialize.test.ts`
+  re-derives the sweep from the tree on every run. Two caveats on that corpus, both of which limit
+  how far the sweep can be pushed: it contains **no instance of cases 2 to 6** (zero fixtures produce
+  an `orphanSegments` entry, which is why the orphan sweep above is constructed rather than drawn
+  from it), and **all but one of the byte-identical fixtures are `golden/*.edi`**, which
   are serializer output by construction, leaving `envelope/no-trailing-crlf.edi` as the only
   independent witness. Preserving the original framing byte-for-byte would need the model to carry
   per-segment framing and TA1 position it does not have today; that is a tracked model change, not a
@@ -1578,12 +1609,14 @@ N-char spec limit` refusal, one per emitting module, where the branch fires **be
 
 - **A forged non-array in a builder spec refuses; in a few places it throws an untyped `TypeError`.**
   The types say `readonly T[]`, but a JavaScript or JSON caller can hand a builder something else. As
-  of `0.0.6` every indexed loop in every builder takes its bound from a checked array (32 loops across
-  7 modules), so an object like `{ length: "9".repeat(120000) }` draws that builder's own typed
+  of `0.0.6` every indexed loop in every builder takes its bound from a checked array, so an object
+  like `{ length: "9".repeat(120000) }` draws that builder's own typed
   refusal - previously the length coerced to `Infinity` and the builder **looped forever instead of
-  refusing**. Measured across the nineteen probes the suite ships: at base **16 hung** and 3 threw an
-  untyped `TypeError`; at head **17 refuse with a typed, coded error** and 2 still throw the untyped
-  `TypeError`.
+  refusing**. No loop or probe count is quoted here: both move with every builder added, and
+  `test/builder-array-bounds.test.ts` re-derives them from the source on every run. Measured over the
+  probes that suite shipped at the `0.0.6` base: most **hung** with no refusal and the rest threw an
+  untyped `TypeError`. Each of those probes now refuses with a typed, coded error, except the
+  `for…of` reads below, which still throw the untyped `TypeError`.
 
   **`null` is treated as absent, not forged**, exactly as the `?? []` this replaced did, so an
   optional list you send as `null` still builds. On a required list `null` draws that builder's own
@@ -1593,11 +1626,24 @@ N-char spec limit` refusal, one per emitting module, where the branch fires **be
 
   Not covered, and disclosed rather than fixed: the places a builder reads a caller array with
   `for…of` - `buildInterchange`'s `spec.groups`, `build999`'s `functionalGroup.transactionResponses`,
-  and every optional leaf array such as `claim.dates` or `member.references`. Those throw
+  and the optional leaf arrays such as `claim.dates` or `member.references`. Those throw
   `TypeError: … is not iterable` immediately. They terminate, so they are not the hang, but they carry
   **no `code`**, so `err.code` is `undefined` and you cannot branch on it. Validate your spec shape at
   your own boundary if it comes from JSON.
 
+  **`build270` is the exception, and it is deliberately stricter than its siblings.** EVERY list slot
+  on `Build270Spec` - the spine (`informationSources`, `receivers`, `subscribers`, `dependents`,
+  `inquiries`, `serviceTypeCodes`) and the leaves (`traces`, `references`, `dates`, `address.lines`,
+  `diagnosisCodePointers`, `procedure.modifiers`) alike - is read through the same checked-array
+  chokepoint, so a forged array-like anywhere in a 270 spec draws a typed, code-tagged
+  `Eligibility270BuildError` rather than an untyped `TypeError`. **The same slots are checked for
+  HOLES at the same point**, because a real array with `undefined` or `null` sitting in a slot is a
+  list and clears the chokepoint: that is the shape a JSON payload with a dropped record carries, and
+  unguarded it reached an emitter and threw the untyped `TypeError` this whole section is about. A
+  hole refuses wherever it stands, naming the slot and nothing out of the inquiry. A name loop sent
+  as `null` is refused the same way, at every level. The other builders are unchanged: on those, a
+  hole in a list still reaches whatever dereferences it.
+
   **One qualification worth stating precisely: on the acknowledgment path the value is not always
   strictly your own.** TR3 005010X231A1 requires AK2-02 to be a verbatim copy of the acknowledged
   transaction set's ST-02, and `buildTA1` exists to echo an inbound ISA-13, so a _document's_ control
@@ -1644,39 +1690,392 @@ N-char spec limit` refusal, one per emitting module, where the branch fires **be
   mismatch and preserve the inbound values verbatim. The library will not "fix" a payer artifact for
   you. Gate your own posting/adjudication on the warning.
 
-## Conformance testing not yet wired
-
-- **No external-oracle differential corpus yet.** A best-effort differential harness against CMS
-  Medicare 835 public examples (and/or another external X12 reader) is planned for the first real
-  release but is **not yet wired**, pending a redistribution-terms review of the CMS sample material.
-  Conformance today rests on the three-tier synthetic corpus (spec-clean → vendor-quirk → round-trip
-  goldens), property/round-trip tests, and a nightly amplified byte-flip fuzz job, not on parity with
-  a third-party implementation. Do not assume byte-for-byte agreement with any specific vendor parser.
+## Trading-partner profiles: what a conformance classification is, and is not
+
+- **A profile never changes what this library emits.** A profile describes what a trading partner
+  SENDS. It attaches attribution to a parse and partitions that parse's warnings into expected and
+  unexpected, and that is the whole of its behaviour. It cannot loosen, tighten or otherwise touch
+  the emit side: `serializeX12`, `buildInterchange` and every `build*` domain builder produce
+  byte-identical output with any profile active and with none, and refuse the same specs with the
+  same error type, code and message. There is no opt-in flag that would change this, and
+  `test/profiles-emit-independence.test.ts` fails the build if the property is ever broken. The
+  reason it is a locked invariant rather than a convention: a profile that widened the emit would
+  put a non-conformant document on the wire, and 45 CFR 162.915 forbids the trading partner from
+  having asked for that in the first place.
+
+- **Each quirk's conformance classification is a RECORDED HUMAN JUDGEMENT, not a check this
+  library performed.** `describe()` states, per quirk, whether the deviation is one a trading partner
+  may lawfully require. Read that as documentation someone wrote down, and confirm it against your
+  own copy of the relevant implementation guide before you rely on it. In particular, **a
+  classification that turns on an element being marked "not used" in an adopted TR3 rests on someone
+  having read that TR3.** This package bundles none: 45 CFR 162.920(a) states a fee is charged for
+  the implementation specifications, so "is this element marked not used?" is not a question the
+  library can answer at run time, and it does not pretend to. Nothing in the classification is
+  derived from your document, from the quirk's `effect`, or from any code list shipped here.
+
+- **The axis is 45 CFR 162.915, and it has three states, not two.** `permitted` and `not-permitted`
+  are measured against that rule, which forbids a covered entity from entering a trading partner
+  agreement that would change the definition, data condition or use of a data element or segment in
+  a standard, add data elements or segments to the maximum defined data set, use any code or data
+  element marked "not used" in (or absent from) the standard's implementation specification, or
+  change the meaning or intent of that implementation specification. The third state,
+  `undetermined`, means **no judgement was recorded**, and it is the fail-safe default: a quirk that
+  says nothing about conformance renders as `undetermined`, never as `permitted`. Read
+  `undetermined` as "this package makes no claim", which is not the same as "harmless". Two of the
+  three quirks shipped by the built-in profiles are `undetermined` today for exactly the fee reason
+  above.
+
+- **A `requires` quirk is a record of what a partner MANDATES, never a claim that the standard
+  supports the mandate.** Those are two different statements and the buckets do not conflate them:
+  membership of `requires` confers nothing on the conformance axis, and a partner mandating an
+  element the adopted guide marks "not used" classifies as a deviation from the standard. If you
+  need to know whether your partner may lawfully require something, read `conformance`, not the
+  effect bucket.
+
+## What the differential corpus proves, and what it does not
+
+- **Every synthetic document this repository ships is read by this library and, where an independent
+  reader maps its transaction, by that reader too, and the two readings are compared element
+  position by element position.** Two independent, open-source X12 readers serve as oracles, each
+  pinned to one exact version and used only as a development tool: neither is ever a dependency of
+  this package, whose published runtime dependency set is empty. The first is pyx12, a BSD-licensed
+  HIPAA X12 parser and validator. The second is LinuxForHealth x12, an Apache-2.0-licensed X12
+  reader with a transaction model per implementation guide, pinned together with every package it
+  runs on and the Python version it runs under, because its own metadata leaves the Pydantic release
+  it needs free. A transaction is compared against the first oracle that maps it and against no
+  other. `pnpm run differential` runs the comparison and writes `test/differential/report.json`,
+  which carries each oracle's name, version and licence as the installed reader declares them (for
+  the second, also the Python version and every companion package version it ran with), the commit
+  this library was read from, which oracle each transaction was compared against with the
+  implementation guide and the map or model that oracle bound it to, the documents that went through
+  both readers, the number of element positions compared, every document the run looked at and did
+  not compare with the reason, and every disagreement found, with both readings left exactly as each
+  reader returned them. `pnpm run differential:check` runs the same comparison and succeeds only when
+  it reproduces the committed report. Which comparison a document belongs to is decided by the
+  document's own GS-08 and ST-01, never by where it is filed, so the awkward documents are in the
+  corpus rather than beside it.
+- **Which reader compares what.** pyx12 compares the 277 claim acknowledgment (005010X214), the 820,
+  the 834, the 835, the professional claim, the institutional claim and the 999. LinuxForHealth x12
+  compares the 270, the 271, the 276 and the 277 claim status response (005010X212), for which pyx12
+  publishes no 005010 implementation guide map. LinuxForHealth x12 also models the 834, the 835 and
+  both claims, and those are still compared against pyx12 alone: no transaction here is read by both
+  oracles, so no row carries two readers' agreement.
+- **🩺 The second oracle reads a document only through its transaction model for the guide the
+  document declares, and that model refuses much of this corpus, so its comparisons are narrower than
+  the documents filed under them.** A document the model refuses is recorded in the report as
+  unevaluated, with the oracle and the kind of refusal, and never counted as agreement. Among the
+  documents here that it refuses are the ones that deliberately break the hierarchy or a row, 271
+  documents whose AAA rejection reasons fall outside the codes it enumerates for that loop, the 270
+  and 271 documents carrying a dependent level, and the 276 documents whose subscriber carries a
+  dependent level beside a claim of its own, as the canonical 276 fixture does. A model can also
+  accept a document and set one of its segments aside without raising, so a document is compared only
+  when the model kept every segment of every transaction set, ST through SE, that the oracle framed
+  for it; one whose model kept fewer is recorded as unevaluated with its own refusal kind, and none of
+  its positions is counted as agreement. 🩺 The two readers place the 276 subscriber's demographics
+  segment (DMG) differently: that model reads it ahead of the subscriber's name and this library
+  after it. A document carrying one where this library puts it loses it to that model, which then
+  refuses the document; and this library's 276 reader keeps a DMG only after the name already read at
+  its level, so one sent ahead of the name is not on the decoded inquiry and no warning says so. Which
+  position the implementation guide specifies is not settled here, and nothing about either reader
+  moved to produce this. So the one 276 compared against it carries no subscriber DMG. Agreement on the
+  270, the 271, the 276 and the 277 claim status response is agreement over the documents that model
+  accepted whole, which the report lists by name, and nothing wider: in particular no document
+  compared against it carries a dependent level, and no 276 compared against it carries a DMG, so that
+  comparison says nothing about either.
+- **🩺 This library and pyx12 disagree about the release character, and the report records the
+  disagreement rather than settling it.** One synthetic document escapes the element separator with
+  `?` inside a transaction set body. This library reads `?` as a release character there, as it has
+  on every released version, so `REF*EA*ID?*WITH?*STAR` is two elements whose second value is
+  `ID*WITH*STAR`; pyx12 reads no release character, so the same segment is four elements whose second
+  value is `ID?`. 005010 transmits no release character at all and nothing in it picks between the
+  two readings, which is the same ambiguity the envelope-splitter entry above is about, and it is the
+  one input class in this corpus on which two conforming readers can genuinely differ. **The
+  disagreement is published, not resolved:** the report holds both readings verbatim for that
+  position, nothing about how this library reads the release character moved to produce it, and
+  `pnpm run differential` exits non-zero for as long as it stands. If you exchange documents that
+  escape a delimiter in a body element, do not assume your counterparty's parser frames that segment
+  the way this one does.
+- **The rows of this library's read scope that neither oracle maps are compared against nothing, and
+  the report names every one with the reason.** Neither reader publishes a 005010 implementation
+  guide map or model for the 278 in either direction or for the dental claim, neither has one for the
+  275 (006020X314) or the 277 request for additional information (006020X313), and neither can bind
+  the TA1 interchange acknowledgment, which sits in the envelope rather than in a functional group
+  and carries no implementation guide identifier. Read that as a statement about the maps and models
+  those readers publish and not about what they can frame: what is missing is the implementation
+  guide, not the ability to read bytes. Either way this library's reading of those transactions is
+  compared against nothing here, and silence about them is silence, never agreement.
+- **For two of the compared transactions the two implementations target different published errata of
+  the same implementation guide, and the report records both identifiers rather than implying one.**
+  pyx12 maps an earlier errata of the professional claim and of the institutional claim than this
+  library implements, so agreement there is agreement between two revisions of one guide.
+- **Agreement with either reader is not conformance to a Technical Report Type 3, and it is not a
+  compliance statement.** Two parsers can agree and both be wrong about the same clause; neither
+  reader is the standard, and each transaction here is compared against one of them, never both. No
+  report produced here says anything about HIPAA compliance, which is a property of a deployment and
+  never of a library. Conformance still rests on the three-tier synthetic corpus (spec-clean,
+  vendor-quirk, round-trip goldens), property and round-trip tests, and a nightly amplified byte-flip
+  fuzz job. Do not assume byte-for-byte agreement with any specific vendor parser.
+- **The corpus is this repository's own synthetic fixtures and nothing else.** No CMS Medicare 835
+  public sample material is in it: the redistribution-terms review of that material is not cleared,
+  and it is not used here until it is. What that bounds is the evidence, not the claim: two readers
+  agreeing over synthetic documents have agreed over synthetic documents.
 
 ## Scope (non-goals for v1)
 
-- **Healthcare HIPAA 005010 only.** Non-healthcare transaction sets (850/856/810/204, etc.), the
-  EDIFACT syntax family, and pre-005010 versions are out of v1 scope. Pre-005010 input is tolerated
-  and flagged (`X12_PRE_005010`), not decoded to those older field maps.
+- **Healthcare HIPAA 005010, and two 006020 guides: the claims attachments pair.** Beside the
+  005010 transaction sets, the package reads and builds the 277 Health Care Claim Request for
+  Additional Information (`006020X313`) and the 275 Additional Information to Support a Health Care
+  Claim or Encounter (`006020X314`), which 45 CFR 162.920(a)(20) and (a)(19) name and 45 CFR
+  162.2002 adopts for the period on and after May 26, 2028. No other 006020 guide is read or built:
+  the services review pair the same rule proposed and did not adopt, the 278 `006020X315` and the
+  275 Additional Information to Support a Health Care Services Review `006020X316`, is out of
+  scope, and a 275 declaring `006020X316` is read as a guide the 275 reader does not implement.
+  Non-healthcare transaction sets
+  (850/856/810/204, etc.), the EDIFACT syntax family, and pre-005010 versions are out of v1 scope.
+  Pre-005010 input is tolerated and flagged (`X12_PRE_005010`), not decoded to those older field
+  maps. What the attachments pair leaves open, stated here beside it:
+  - **The base X12 006020 transaction sets are typed; no implementation-guide usage is asserted.**
+    Both guides are sold and no source this package carries states which segments, qualifiers or
+    codes they make required, situational or repeatable. So the readers carry every code and
+    qualifier verbatim and decide nothing about whether it is valid for the guide, and the builders
+    write every BHT code, HL level and child code, entity, reference and date qualifier exactly as
+    given and supply none. `build277RequestForAdditionalInformation` refuses only the absences the
+    base 006020 277 makes mandatory (no level, no claim-level request, a request with no TRN, an
+    empty C043-01 or C043-02, a service line with no SVC); `build275` refuses only what would make a
+    BDS-02 untrue or a BDS empty (no attachment, empty data, a filter code that is not three
+    characters, a character above U+00FF). A document conformant to either guide can carry a segment
+    or qualifier these models leave untyped: the 277's SBR, PAT, DMG, heading name loop, PWK loops
+    and TOO, the 275's DTM, IN1, DMG, PRV, PER, NX1 and each line's NM1, HI, SVC, DTP, CAT, PID and
+    OOI. They stay verbatim on the transaction set, and neither builder writes them: `build275`
+    writes each BDS directly after its line's LX, TRN, STC and REF, with no DTP, CAT or OOI before
+    it, so a trading partner whose guide places the BDS inside those loops needs them added by hand
+    through `buildInterchange`.
+  - **The 277 request reader validates no hierarchy.** Each HL is carried with HL-01, HL-02, HL-03
+    and HL-04 as sent; no parent pointer is checked and no level code is expected, because no
+    carried source states the guide's hierarchy. A claim-level segment sent before the first HL
+    reaches no level and stays on the transaction set.
+  - **ISA-12 is not decided here.** Which ISA-12 a 006020 interchange carries is an open question no
+    carried source answers. Both builders write this package's default, `00501`, unless the caller
+    supplies `interchangeControlVersion`, and both readers key on ST-03 and GS-08 and never on
+    ISA-12.
+  - **`06020X314` is not an adopted identifier.** 45 CFR 162.2002(c) prints the 275's guide one digit
+    short, as `06020X314`, where 162.920(a)(19) prints `006020X314`. The conformance row adopts the
+    162.920 spelling and records the other on its note as a typographical variant, so a 275 declaring
+    `06020X314` is warned `X12_GUIDE_NOT_IMPLEMENTED`.
+  - **Only the attachment data refuses to print.** A 275 attachment's BDS-03 is held in
+    `X12AttachmentData`, whose string, JSON and `util.inspect` forms carry its octet count and no
+    octet. Every other field of both readings, the names, member and claim identifiers and trace
+    numbers included, is a plain string, as on every other reading in this package.
+  - **An attachment is octets, and a string is not.** Pass an interchange carrying attachments to
+    `parseX12` as a `Buffer`, which is read one character per octet. `serializeX12` of a built 275
+    is a string of one character per octet: write it as latin1 (`Buffer.from(text, "latin1")`),
+    because encoding a character above U+007F as UTF-8 makes two octets of one and BDS-02 stops being
+    true of what was sent. Nothing inside an attachment is decoded; BDS-01 names a filter the sender
+    applied and this package applies none.
 - **No transport.** AS2, SFTP, and MLLP-style delivery are out of scope. This is a parser/serializer,
   not a communications stack.
 - **Published, still pre-alpha.** The package is published on npm as `@cosyte/x12` from a public
   repo, but it stays on the `0.0.x`-until-first-alpha ladder. `npm view @cosyte/x12 version` is the
   only source of truth for the current version, so this page does not restate one. Treat the API as
   pre-alpha and pin the exact version until the first alpha.
-- **No typed model for the 270 and 276 inquiries.** Every other v1 transaction has both a
-  per-transaction reader and a domain builder. The 270 eligibility inquiry and the 276 claim-status
-  inquiry have neither: they parse into segments, composites, and dot-paths like any other X12 input,
-  and the responses (271, 277) decode fully, but the inquiry directions have no typed surface yet.
+- **A 276 hierarchical level whose declared parent does not resolve is left off the returned tree.**
+  The 276 reader attaches a level by its own HL-02 and by nothing else, so a pointer naming a level
+  that is not present, a pointer naming a level of the wrong kind, and a parent chain that returns
+  to itself each leave that level, and everything transmitted beneath it, absent from the model. The
+  loss is reported (`X12_276_LEVEL_DETACHED`, beside the code for the pointer defect itself), the
+  declared pointer stays verbatim on `hierarchies`, and the segments stay verbatim on the
+  transaction set. Nothing is re-parented onto whichever level happened to be open, because that
+  would be this library inventing the one structure a 276 exists to state: which provider is asking
+  about which patient's claim.
+- **A 276 REF, DTP or AMT short of what its row is built from loses the whole row, and says so.**
+  Each is a record and not a slot. Without both REF-01 and REF-02 there is no reference row; without
+  both DTP-01 and DTP-03 there is no date row, and the format qualifier that says single date or
+  range goes with it; without a decodable AMT-02 there is no amount row. The reader builds none,
+  fabricates nothing to stand in, and reports the loss (`X12_276_REFERENCE_ROW_DROPPED`,
+  `X12_276_DATE_ROW_DROPPED`, `X12_AMOUNT_ROW_DROPPED`) at that segment. **The report is bounded to
+  the row the reader tried to build.** A segment that decoded and then found no claim or service
+  line open to sit on is a different loss, it stays silent, and it is not on any of those channels.
+- **The 276 reader surfaces four of the SVC elements and no postal address.** SVC-01, SVC-02, SVC-04
+  and SVC-07 reach the typed service line; SVC-03, SVC-05 and SVC-06 are left unread, because this
+  is the request direction and a submitter states what it billed rather than what was paid. An N3 or
+  N4 a sender transmits under a 276 name loop reaches no typed field either, as it reaches none on
+  the 277 beside it. All of them stay verbatim on `tx.segments`; read them there.
+- **A 270 hierarchical level whose declared parent does not resolve is left off the returned tree.**
+  The 270 reader attaches a level by its own HL-02 and by nothing else, so a pointer naming a level
+  that is not present, a pointer naming a level of the wrong kind, and a parent chain that returns to
+  itself each leave that level, and everything transmitted beneath it, absent from the model. The
+  loss is reported (`X12_270_LEVEL_DETACHED`, beside the code for the pointer defect itself), the
+  declared pointer stays verbatim on `hierarchies`, and the segments stay verbatim on the transaction
+  set. Nothing is re-parented onto whichever level happened to be open, because that would be this
+  library inventing the one structure a 270 exists to state.
+- **A 270 DTP short of what a date row is built from loses the whole row, and says so.** A DTP is a
+  record and not a slot: without both the qualifier that says what the date is for (DTP-01) and the
+  value itself (DTP-03) there is no row to build, and the format qualifier that says single date or
+  range goes with it. The reader builds none, fabricates nothing to stand in, and reports the loss
+  (`X12_270_DATE_ROW_DROPPED`) at that segment, so an empty `dates` list can be told apart from a
+  date the sender stated and this reader could build no row from. **The report is bounded to the row
+  the reader tried to build.** A segment that would have attached to a level or an inquiry but
+  arrives before the first HL opens one reaches no part of the model and stays SILENT, the date row
+  included, so an empty list is evidence about a level this reader did return and about nothing else.
+  The segments stay verbatim on the transaction set either way.
+- **A 270's tolerated deviations are reported once per transaction set, not once per occurrence.**
+  A declared non-conventional delimiter raises `X12_270_NON_CONVENTIONAL_DELIMITER` once however many
+  of the four roles deviate, and a line break between segments raises
+  `X12_270_INTER_SEGMENT_LINE_BREAK` once however many runs the document carries. Both anchor at the
+  ISA. The framing run is also consumed by the shared parse and recorded nowhere on the model, so
+  only `parse270Inquiries`, which receives the bytes, can report it: `get270Inquiry` is handed the
+  model and reports the delimiter half alone.
+- **Between segments, only CR and LF are absorbed. A space or a tab there costs you the whole
+  interchange, on every transaction set.** The shared parse consumes a run of CR / LF before the next
+  segment opens; any other whitespace becomes the head of the next segment's identifier, so `GS` is
+  read as a non-spec segment id, no functional group frames, every segment after the ISA lands on
+  `ix.orphanSegments` with an `X12_UNEXPECTED_SEGMENT` warning, and the interchange also reports
+  `X12_MISSING_IEA`. Nothing is silent at the interchange level, but the typed readers see no
+  transaction set at all: `parse270Inquiries` answers the EMPTY list, which is the same value it uses
+  for an interchange that genuinely carries no 270, so **do not read an empty result as evidence the
+  sender sent no inquiry without checking `ix.warnings` first.** This is long-standing shared-parse
+  behaviour and the 270 work deliberately did not widen it: framing tolerance is shared by every
+  transaction set, and moving it is a change to all of them rather than to one reader.
+- **A BDS or BIN segment's binary data is framed by the octet count its length element declares,
+  never by delimiters, and where that count cannot be honoured it is reported, never corrected.**
+  BDS-03 and BIN-02 are read as exactly the number of octets BDS-02 or BIN-01 declares, anywhere after
+  the ISA, so an element, repetition or component separator, a segment terminator, a `?`, a CR or an
+  LF inside the data is data: the segment is one segment, the data is one element, and the segments
+  after it frame as sent. **`?` has no effect inside the declared span**, not even immediately before
+  the terminator that follows it. `getSegmentValue`, `getAllSegmentValues` and `elementValue` return
+  the data element verbatim, with no release unescape and no split on the repetition or component
+  separator. **Nothing inside it is decoded**: BDS-01's filter (`B64`, for example) is not applied,
+  and no typed reader decodes an attachment. **The count is in octets.** A `Buffer` is read one character
+  per octet, so its count is exact; a string is counted one UTF-16 code unit per octet, which is exact
+  at or below U+00FF, and a span holding anything above that raises `X12_BINARY_LENGTH_UNVERIFIABLE`
+  and is still carried verbatim, so pass an interchange that carries attachments as a `Buffer`. The
+  three ways the count can fail, each warned at the segment:
+  - `X12_BINARY_LENGTH_INVALID`: the length element is absent, empty, or not 1 to 15 ASCII digits (a
+    sign, a decimal point or whitespace is malformed; leading zeros are not). **No length is inferred,
+    so this is the one case the count does not protect**: the segment is framed by its delimiters
+    exactly as a segment of any other id is, and a delimiter inside its data splits it and can
+    mis-frame every segment after it.
+  - `X12_BINARY_DATA_TRUNCATED`: the input ends inside the declared span. The data element holds
+    only the octets present and nothing past the end is read, and because the span runs to the end
+    of the input, the transaction, group and interchange trailers are reported missing.
+  - `X12_BINARY_LENGTH_MISMATCH`: the byte after the declared span is not the segment terminator (a
+    length shorter or longer than the data), or the segment ends before a data element begins
+    although a non-zero length was declared. The data element is exactly the declared span; the
+    bytes from its end to the next terminator stay on the segment's `raw`, so a length longer than
+    the data carries the start of the next segment into this one, and the default `serializeX12` emit
+    still reproduces the input byte for byte.
+
+  **The length element is never rewritten on emit**, in either `serializeX12` mode, including where
+  it disagrees with the data: that would be a silent correction. A span that ends exactly at the end
+  of the input is complete and raises no binary warning; its missing terminator is supplied on emit,
+  as for any unterminated final segment, so where a truncated span fell exactly one octet short, a
+  re-parse of that emit reads the supplied terminator as the last octet of the data. Where `?` is the
+  declared element separator or segment terminator, the elements before the data element are split
+  literally, as that role's splitter already does.
+
+## Code-list validity dates
+
+- **🩺 A published Stop date is read as the FIRST day the code is no longer valid, and the
+  maintainer does not say whether that is right.** `x12.org` renders a code's dates as
+  `Start: 01/01/1995 | Last Modified: 11/01/2017 | Stop: 05/01/2018` and states nowhere whether the
+  Stop date is the LAST day the code was valid or the FIRST day it was not. The two readings differ
+  by exactly one day, on exactly the boundary a document produced that day sits on.
+
+  This package reads it as the first day the code is NOT valid, so the valid interval is half-open:
+  a document date on or after the Stop date reports `not-valid`, and the day before it reports
+  `valid`. The ground is the shape of the source and not a statement by the maintainer: the
+  published dates are first-of-month publication-cycle dates, so the Stop date reads as the
+  publication on which the code left the list rather than the last day it was on it. **That is a
+  judgement, not a fact, and a consumer whose contract turns on the boundary day itself should
+  confirm it with the maintainer rather than with this package.** `CARC.dates` and `RARC.dates`
+  carry the published values unchanged, so a consumer who reads the boundary the other way has
+  everything needed to compute it.
+
+  Two further bounds on the same data, neither of them a defect:
+  - **A code with no published start date is `indeterminate`, never `valid` and never `not-valid`.**
+    Validity is an interval and there is no interval without a start. No bundled code is in this
+    state at the capture the dates were transcribed from; the answer exists because the fail-safe
+    has to hold if one ever is.
+  - **The dates describe the bundled subset and nothing wider.** A code outside it answers
+    `indeterminate` with the inbound value echoed verbatim, which is a statement about what this
+    package bundles rather than about what the maintainer publishes.
 
 ## Code-list `--fetch` regeneration
 
 `pnpm refresh:code-lists` (default) validates the bundled snapshots and prints a freshness audit,
 offline and CI-safe. The `--fetch` mode that would **regenerate** the full lists from their canonical
-WPC / X12 sources is deliberately **not** run in automation: redistributing the full WPC code
-descriptions requires a redistribution-terms review that has not cleared, and it needs outbound
-network. The tool prints the canonical source manifest and exits rather than fabricating descriptions
-the maintainers have not reviewed.
+sources is deliberately **not** run in automation: regeneration needs outbound network and is a human
+release step, and the tool fetches nothing and fabricates no description a maintainer has not
+published.
+
+**Whether a bundled list's descriptions may be redistributed is answered PER LIST, and the lists do
+not agree.** Each bundled snapshot carries its own maintaining organisation and its own
+redistribution record on `meta`, so a consumer deciding whether a description is theirs to display,
+cache or re-publish reads that list's answer rather than a single sentence covering all seven:
+
+| Bundled list                          | External code list | Maintained by | Redistribution        | Approach for permission |
+| ------------------------------------- | ------------------ | ------------- | --------------------- | ----------------------- |
+| CARC (Claim Adjustment Reason Codes)  | 139                | ASC X12       | licence required      | ASC X12 (see below)     |
+| RARC (Remittance Advice Remark Codes) | 411                | CMS           | permitted, no licence | none needed             |
+| CSCC (Claim Status Category Codes)    | 507                | ASC X12       | licence required      | ASC X12 (see below)     |
+| CSC (Claim Status Codes)              | 508                | ASC X12       | licence required      | ASC X12 (see below)     |
+| Service type (EB-03)                  | 958                | ASC X12       | licence required      | ASC X12 (see below)     |
+| CLP-02 claim status                   | none               | ASC X12       | **not established**   | ASC X12 (see below)     |
+| INS-03 maintenance type               | none               | ASC X12       | **not established**   | ASC X12 (see below)     |
+
+The **External code list** column is the list's id on the X12 External Code Lists index. It is the
+column that decides the one beside it: a list with a row there is answered from that row, and only a
+list with no row can be one the carried sources never name. `none` means exactly that the index
+publishes no row for the list, not that the list is unimportant.
+
+**The approach, for every row that needs one:** ASC X12, which publishes that it is the only
+organisation authorised to grant permission for the use of X12 products. Permission to reproduce X12
+intellectual property is requested through the licensing programme X12 publishes at
+<https://x12.org/products/licensing-program>, by email to the intellectual-property address given
+there, naming the requester and their organisation and describing both the artifact and its intended
+distribution. Subscriptions to X12-maintained code lists are bought through the Code List Update
+Subscription page linked from <https://x12.org/codes>.
+
+The evidence behind each row is quoted on the list itself, at `meta.redistribution.terms`. In short:
+the X12 External Code Lists index records CARC as external code list 139, the two claim-status lists
+as 507 and 508, and the service type codes as 958, all maintained by an X12 code maintenance
+committee group, under the statement that all X12 work products are copyrighted and that
+subscriptions to X12-maintained code lists are purchased. X12's own intellectual-property policy,
+reproduced in HL7's CARIN Consumer Directed Payer Data Exchange code system stubs, adds that all X12
+products are subject to it and that X12 is the only organisation authorised to grant permission for
+their use. The same index records RARC as external code list 411 maintained by CMS, and HL7's CARIN
+terminology licensure page puts CARC among the code systems that require a purchased licence and RARC
+among those requiring none.
+
+**Being cited from a TR3 is not evidence of a missing publisher.** Three bundled lists point their
+`meta.source` at a purchased Technical Report Type 3: the service type codes, the CLP-02 dispositions
+and the INS-03 maintenance types. Only the last two are absent from the External Code Lists index;
+the service type codes have a row there, so they are answered from it. Where a bundled subset was
+read is a different question from what the publisher publishes, and only the second decides the
+terms.
+
+**"Not established" is a recorded answer here, not a gap waiting to be tidied.** The last two lists,
+the CLP-02 dispositions and the INS-03 maintenance types, are printed inside a purchased ASC X12
+Technical Report Type 3 and have no row on the External Code Lists index at all, and no source
+obtained for this package names them or states whether their descriptions may be redistributed. They
+are therefore treated as **not redistributable** wherever a permission decision is made, exactly as a
+licence-restricted list is: an unsettled question is never read as a permission.
+
+Consequences you can rely on:
+
+- **A list whose descriptions may not be redistributed stays exactly the cited part it already
+  ships.** Nothing is enlarged, refetched or relicensed by recording the terms, and the record names
+  the licensor who could change that.
+- **`--fetch` answers each list on its own terms.** It reports each bundled list's regeneration
+  permission independently, refuses only the lists whose own record forbids it, prints the licensor
+  to approach beside each refusal, and never refuses a list because a different list is restricted.
+  It exits `2` while any list is refused and `0` when none is.
+- **Snapshot validation refuses an unlabelled list.** A bundled list carrying no maintaining
+  organisation, or no redistribution record, fails `pnpm refresh:code-lists` with a message naming
+  that list, so it cannot reach a release unlabelled.
+- **`codeListRedistributionIsPermitted(meta)` is the single decision point**, and it is exported.
+  Only a recorded permission answers `true`; a licence requirement, an unsettled status and a missing
+  record all answer `false`.
 
 ---