@cosyte/x12 0.0.10 → 0.0.11

package/README.md

@@ -1,7 +1,9 @@
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://cosyte.com/tile/cosyte-lockup-tile-on-dark-1200x300.png">
-  <img alt="Cosyte: a plus mark set in two overlapping rounded squares, one solid and one outlined, beside the Cosyte wordmark" src="https://cosyte.com/tile/cosyte-lockup-tile-on-light-1200x300.png">
-</picture>
+<a href="https://cosyte.com">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://cosyte.com/tile/cosyte-lockup-tile-on-dark-1200x300.png">
+    <img alt="Cosyte: a plus mark set in two overlapping rounded squares, one solid and one outlined, beside the Cosyte wordmark" src="https://cosyte.com/tile/cosyte-lockup-tile-on-light-1200x300.png">
+  </picture>
+</a>
 
 # @cosyte/x12
 
@@ -45,7 +47,7 @@ That's the pitch: no schema upload, no spec knowledge. The parser accepts vendor
 - **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, 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. **`defineProfile()` is bounded on the same terms since `0.0.6`** (twelve refusal sites, twenty-three caller values; the worst message measured **360,181 characters** before and **431** now, both at the `fixture` refusal, which names three caller values; the ceiling for that site is 443 and the suite asserts every site under 500; `X12ProfileError.profileName` is deliberately left unbounded so it still matches the name you passed). **And a forged non-array in a builder spec now refuses instead of hanging:** every indexed loop takes its bound from a checked array, so `{ length: "9".repeat(120000) }` draws a typed refusal rather than coercing to `Infinity` and looping forever. A few `for…of` reads still throw an untyped `TypeError` instead; both are in [KNOWN-LIMITATIONS.md](./KNOWN-LIMITATIONS.md). **The one deliberate exception:** `X12ParseError.snippet` on the four Tier-3 structural fatals is a bounded (≤ 64 character) copy of the start of the input, so on real traffic it can carry PHI. The library does not redact it. Redact at your call site, or log `err.code` and `err.position` instead. See [Keeping PHI out of logs](./docs-content/troubleshooting.md).
+- **PHI-disciplined**: synthetic-only fixtures, a PHI commit-gate, and a warning `message` that is a **lookup into a frozen registry**, not something built from your document. No warning factory in the library takes a value parameter, so no element can reach a diagnostic: the code and `position` say what and where, and the bytes stay on the model. `ALL_WARNING_MESSAGES` is exported so you can assert it. **Builder refusals are a different, and deliberately weaker, surface:** twenty-four refusal sites across ten builder modules name a value you passed in, so you can see which control number, count or code was refused. **What they will never name is a `claimId`, a member id, a member name, a trace or a diagnosis code** - a guarantee that held for the refusal templates and, until the release after `0.0.10`, did not hold for the shared type guards underneath them: a JSON-driven caller who sent a number where the types say string got `a number ("900412345678")` back, bounded but not redacted, from a guard standing on every element of every builder. Those guards report the type now and never the value. Only the segment-join guard names the slot as well; the `esc` and `X12Decimal` guards name the builder, which is a diagnostic cost stated rather than hidden. The array guard's primitive arm is redacted with them, but it still reports the `length` and the class tag of a forged array-like, bounded, because those describe the shape you forged rather than the contents of a document element. Each goes through `renderCallerValue`, capping the rendered **fragment** at `BUILD_REFUSAL_VALUE_MAX_RENDERED` (90 characters); all three names are exported so you can assert the ceiling. The whole `message` is that plus the site's own fixed text, so it is bounded by a constant but a larger one: a 120,000-character control number gave a 120,066-character `X12BuildError.message` before this and gives 150 now. That is robustness, not redaction: the value is one you supplied and bounding it hides nothing from you. It is also not escaped, and on the **ack** path it is not always strictly your own, since `build999`'s AK2-02 and `buildTA1` echo an inbound document's control numbers by design. Log `err.code`, not `err.message`, from a builder. **`defineProfile()` is bounded on the same terms since `0.0.6`** (twelve refusal sites, twenty-three caller values; the worst message measured **360,181 characters** before and **431** now, both at the `fixture` refusal, which names three caller values; the ceiling for that site is 443 and the suite asserts every site under 500; `X12ProfileError.profileName` is deliberately left unbounded so it still matches the name you passed). **And a forged non-array in a builder spec now refuses instead of hanging:** every indexed loop takes its bound from a checked array, so `{ length: "9".repeat(120000) }` draws a typed refusal rather than coercing to `Infinity` and looping forever. A few `for…of` reads still throw an untyped `TypeError` instead; both are in [KNOWN-LIMITATIONS.md](./KNOWN-LIMITATIONS.md). **The one deliberate exception:** `X12ParseError.snippet` on the four Tier-3 structural fatals is a bounded (≤ 64 character) copy of the start of the input, so on real traffic it can carry PHI. The library does not redact it. Redact at your call site, or log `err.code` and `err.position` instead. See [Keeping PHI out of logs](./docs-content/troubleshooting.md).
 
 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.
 

package/dist/index.cjs

@@ -143,7 +143,9 @@ var WARNING_CODES = {
   X12_834_UNKNOWN_MAINTENANCE_TYPE: "X12_834_UNKNOWN_MAINTENANCE_TYPE",
   X12_UNPARSEABLE_DECIMAL: "X12_UNPARSEABLE_DECIMAL",
   X12_837_SERVICE_LINE_NOT_DECODED: "X12_837_SERVICE_LINE_NOT_DECODED",
-  X12_837_SERVICE_LINE_DROPPED: "X12_837_SERVICE_LINE_DROPPED"
+  X12_837_SERVICE_LINE_DROPPED: "X12_837_SERVICE_LINE_DROPPED",
+  X12_837_SERVICE_SEGMENT_WITHOUT_LX: "X12_837_SERVICE_SEGMENT_WITHOUT_LX",
+  X12_837_ENTITY_SEGMENT_DISCARDED_AFTER_LX: "X12_837_ENTITY_SEGMENT_DISCARDED_AFTER_LX"
 };
 var CONTROL_NUMBER_PAIRS = {
   /** ISA-13 against IEA-02. */
@@ -219,7 +221,9 @@ var WARNING_MESSAGES = {
   X12_834_UNKNOWN_MAINTENANCE_TYPE: "Unknown 834 maintenance type: the INS-03/HD-01 code is outside the bundled snapshot. The verbatim code is preserved on the enrollment and the action is NEVER inferred.",
   X12_UNPARSEABLE_DECIMAL: "Unparseable decimal: the element at `position.elementIndex` held bytes this library could not decode as a decimal, so NO value was decoded from it. Whatever occupies that slot on the model, including 0 and undefined, is a stand-in and is NOT a value the sender supplied. The verbatim bytes are preserved on the segment; read them there before acting on the amount, quantity or percent.",
   X12_837_SERVICE_LINE_NOT_DECODED: "837 service line with no decoded service segment: the Loop 2400 line opened at `position.segmentIndex` is followed by no SV1 / SV2 / SV3 matching the variant this submission resolved to, so NOTHING carried by the service segment was read. The line's `charge` and `units` hold 0 as a stand-in and are NOT values the sender supplied; its procedure code, modifiers, unit of measure and place of service are equally undecoded. Two common causes: the line carries no SVx at all, or it carries one for a different 837 variant than ST-03 (or the caller's `type` option) named. Which side is wrong is NOT decided here, because a caller-supplied `type` can disagree with a perfectly conformant document. The verbatim segments are preserved on the transaction set; read them there before acting on the charge or the quantity.",
-  X12_837_SERVICE_LINE_DROPPED: "837 service line dropped from the typed model: the LX at `position.segmentIndex` opened no Loop 2400, so no line appears on any claim's `serviceLines` for it and the SV1 / SV2 / SV3 that followed - its charge, units, procedure code and modifiers - was read into nothing. Compare `X12_837_SERVICE_LINE_NOT_DECODED`, where the line IS on the model and only its service segment went unread. Two causes: no Loop 2300 (CLM) is open at this LX, so there is no claim to attach a line to; or the submission's variant is not one of P / I / D, so no variant-specific line shape could be built. Read `submission.variant` and `submission.claims` to tell them apart; do NOT expect `X12_837_UNKNOWN_VARIANT` alongside this code, because a caller-supplied `type` outside P / I / D reaches the second cause without it. Nothing is fabricated to stand in for the missing line and no claim is synthesized. What becomes of a DTP / AMT / NTE / REF that follows the dropped LX depends on the route and this message does not say; see KNOWN-LIMITATIONS.md. The verbatim segments are preserved on the transaction set; read them there before concluding the claim had no service lines."
+  X12_837_SERVICE_LINE_DROPPED: "837 service line dropped from the typed model: the LX at `position.segmentIndex` opened no Loop 2400, so no line appears on any claim's `serviceLines` for it and the SV1 / SV2 / SV3 that followed - its charge, units, procedure code and modifiers - was read into nothing. Compare `X12_837_SERVICE_LINE_NOT_DECODED`, where the line IS on the model and only its service segment went unread. Two causes: no Loop 2300 (CLM) is open at this LX, so there is no claim to attach a line to; or the submission's variant is not one of P / I / D, so no variant-specific line shape could be built. Read `submission.variant` and `submission.claims` to tell them apart; do NOT expect `X12_837_UNKNOWN_VARIANT` alongside this code, because a caller-supplied `type` outside P / I / D reaches the second cause without it. Nothing is fabricated to stand in for the missing line and no claim is synthesized. What becomes of a DTP / AMT / NTE / REF that follows the dropped LX depends on the route and this message does not say; see KNOWN-LIMITATIONS.md. The verbatim segments are preserved on the transaction set; read them there before concluding the claim had no service lines.",
+  X12_837_SERVICE_SEGMENT_WITHOUT_LX: "837 service segment with no Loop 2400 to read it into: no service line was open at the SV1 / SV2 / SV3 at `position.segmentIndex`, so NOTHING it carries - its charge, units, procedure code, modifiers, unit of measure and place of service - was read. Read that literally: an LX may well appear earlier in the transaction, and what this reports is that none of them had opened a Loop 2400 still current at this segment. No line appears on any claim's `serviceLines` for it and nothing is fabricated to stand in. Compare the two codes anchored at an LX: `X12_837_SERVICE_LINE_DROPPED`, where an LX IS present and opened no line, and `X12_837_SERVICE_LINE_NOT_DECODED`, where the line is on the model and only its service segment went unread. Neither of those can report the SAME service segment as this code, because both are raised at an LX and this one only where no Loop 2400 is open; a document with several claims can still carry all three. This says NOTHING about how the submission's variant resolved: absent a caller-supplied `type` option, and where ST-03 names no known implementation convention, the reader falls back to the first SV1 / SV2 / SV3 in the transaction, and a segment reported here is eligible for that fallback like any other, so a stray one can decide the variant every line is read against. Read `submission.variant`. The verbatim segments are preserved on the transaction set; read them there before concluding the claim had no service lines.",
+  X12_837_ENTITY_SEGMENT_DISCARDED_AFTER_LX: "837 entity segment read into nothing after a dropped LX: the N3 / N4 / PER / REF at `position.segmentIndex` arrived while no entity loop was open, because an earlier LX in this transaction opened no Loop 2400 (no CLM was open at it) and closed the entity loop that was current there. NOTHING this segment carries reached the model: no party's `address`, `contacts` or `references` was written from it, and no party, claim or line was synthesized to hold it. This is the code that names THAT loss; `X12_837_SERVICE_LINE_DROPPED` is raised at the LX itself and names the SERVICE LINE's loss, never an entity segment, so the two report different things about the same stretch of the document. Read the bound literally, because this code does NOT report every unattached entity segment: it reports one discarded after such an LX and only while nothing since has opened a new loop, so an N3 / N4 / PER / REF that reaches no party by any other route is still silent, and one arriving after a later NM1 is outside this code's scope, whether or not this reader surfaces that segment kind on that party. It reports that the segment reached NO party; it does not claim it would have reached one had the LX been absent, because this reader does not surface every one of these segment kinds on every party (a PER on a patient or a pay-to address, for one). Which party a segment following a stray LX belongs to is not derivable from the TR3s in either direction, so it is discarded rather than attributed: see KNOWN-LIMITATIONS.md. The verbatim segments are preserved on the transaction set; read them there before concluding a party had no address, no secondary identifier or no contact."
 };
 var ALL_WARNING_MESSAGES = new Set(
   Object.values(WARNING_MESSAGES)
@@ -394,6 +398,20 @@ function serviceLineDropped(position) {
     position
   };
 }
+function serviceSegmentWithoutLx(position) {
+  return {
+    code: WARNING_CODES.X12_837_SERVICE_SEGMENT_WITHOUT_LX,
+    message: WARNING_MESSAGES.X12_837_SERVICE_SEGMENT_WITHOUT_LX,
+    position
+  };
+}
+function entitySegmentDiscardedAfterLx(position) {
+  return {
+    code: WARNING_CODES.X12_837_ENTITY_SEGMENT_DISCARDED_AFTER_LX,
+    message: WARNING_MESSAGES.X12_837_ENTITY_SEGMENT_DISCARDED_AFTER_LX,
+    position
+  };
+}
 function unknownClaimStatusCategory(position) {
   return {
     code: WARNING_CODES.X12_UNKNOWN_CLAIM_STATUS_CATEGORY,
@@ -2528,7 +2546,7 @@ function renderCallerJson(value) {
 var NONE = Object.freeze([]);
 function describeShape(value) {
   if (typeof value !== "object") {
-    return `a ${typeof value} (${renderCallerValue(value)})`;
+    return `a ${typeof value}`;
   }
   let length;
   try {
@@ -2565,7 +2583,7 @@ function describeCallerDecimal(value) {
   const type = typeof value;
   if (type === "object") return Array.isArray(value) ? "an array" : "an object";
   if (type === "function") return "a function";
-  return `a ${type} (${renderCallerValue(value)})`;
+  return `a ${type}`;
 }
 function requireCallerDecimal(value, at, refuse) {
   if (value instanceof X12Decimal) return value;
@@ -2575,19 +2593,20 @@ function requireCallerDecimal(value, at, refuse) {
 }
 
 // src/builder/caller-segment.ts
+var SEGMENT_ID_RE2 = /^[A-Z][A-Z0-9]{1,2}$/u;
 function describeSegmentValue(value) {
   if (value === null) return "null";
   if (value === void 0) return "undefined";
   const type = typeof value;
   if (type === "object") return Array.isArray(value) ? "an array" : "an object";
   if (type === "function") return "a function";
-  return `a ${type} (${renderCallerValue(value)})`;
+  return `a ${type}`;
 }
 function locateSlot(parts, index) {
   const id = parts[0];
   const position = String(index).padStart(2, "0");
-  if (typeof id !== "string" || id.length === 0) return `element ${String(index)}`;
-  return `${renderCallerValue(id)}-${position}`;
+  if (typeof id !== "string" || !SEGMENT_ID_RE2.test(id)) return `element ${String(index)}`;
+  return `"${id}"-${position}`;
 }
 function requireCallerSegment(parts, at, refuse) {
   let index = 0;
@@ -2608,7 +2627,7 @@ function describeCallerValue(value) {
   const type = typeof value;
   if (type === "object") return Array.isArray(value) ? "an array" : "an object";
   if (type === "function") return "a function";
-  return `a ${type} (${renderCallerValue(value)})`;
+  return `a ${type}`;
 }
 function requireCallerString(value, at, refuse) {
   if (typeof value === "string") return value;
@@ -3269,7 +3288,7 @@ function get837Claims(delimiters, tx, opts) {
   }
   const variant = explicitType ?? variantFromIcr ?? variantFromSegment ?? "unknown";
   if (variant === "unknown") {
-    warnings.push(unknown837Variant({ segmentIndex: 1, transactionIndex: 0 }));
+    warnings.push(unknown837Variant({ segmentIndex: 0, transactionIndex: 0 }));
   }
   const hierarchies = [];
   const hlIndex = /* @__PURE__ */ new Map();
@@ -3292,7 +3311,9 @@ function get837Claims(delimiters, tx, opts) {
   let currentOtherSubscriber;
   let currentAdjudication;
   let context = { kind: "header" };
+  let droppedLineReported = false;
   let activeEntity;
+  let entityLoopClosedByStrayLx = false;
   const flushAdjudication = () => {
     if (currentAdjudication !== void 0 && currentServiceLine !== void 0) {
       currentServiceLine.adjudications.push(freezeAdjudication(currentAdjudication));
@@ -3308,6 +3329,15 @@ function get837Claims(delimiters, tx, opts) {
       currentClaim.serviceLines.push(freezeServiceLine2(currentServiceLine));
     }
     currentServiceLine = void 0;
+    droppedLineReported = false;
+  };
+  const reportOrphanServiceSegment = (position) => {
+    if (droppedLineReported) return;
+    warnings.push(serviceSegmentWithoutLx(position));
+  };
+  const reportDiscardedEntitySegment = (position) => {
+    if (!entityLoopClosedByStrayLx) return;
+    warnings.push(entitySegmentDiscardedAfterLx(position));
   };
   const flushOtherSubscriber = () => {
     if (currentOtherSubscriber !== void 0 && currentClaim !== void 0) {
@@ -3411,6 +3441,7 @@ function get837Claims(delimiters, tx, opts) {
           context = { kind: "header" };
         }
         activeEntity = void 0;
+        entityLoopClosedByStrayLx = false;
         break;
       }
       case "SBR": {
@@ -3427,6 +3458,7 @@ function get837Claims(delimiters, tx, opts) {
             otherPayer: void 0
           };
           activeEntity = { kind: "otherSubscriber" };
+          entityLoopClosedByStrayLx = false;
         }
         break;
       }
@@ -3442,6 +3474,7 @@ function get837Claims(delimiters, tx, opts) {
       case "NM1": {
         const qualifier = elementValue(seg, 1, delimiters);
         const entity = decodeNm12(seg, delimiters);
+        entityLoopClosedByStrayLx = false;
         if (qualifier === NM1_QUALIFIERS.SUBMITTER) {
           submitter = entity;
           activeEntity = { kind: "submitter" };
@@ -3486,16 +3519,19 @@ function get837Claims(delimiters, tx, opts) {
       case "N3": {
         const lines = collectElementValues(seg, 1, 2, delimiters);
         attachAddressLines(lines, activeEntity, entityMutators);
+        reportDiscardedEntitySegment(position);
         break;
       }
       case "N4": {
         const partial = decodeN42(seg, delimiters);
         attachAddressFields(partial, activeEntity, entityMutators);
+        reportDiscardedEntitySegment(position);
         break;
       }
       case "PER": {
         const contact = decodePer2(seg, delimiters);
         attachContact(contact, activeEntity, entityMutators);
+        reportDiscardedEntitySegment(position);
         break;
       }
       case "REF": {
@@ -3507,6 +3543,7 @@ function get837Claims(delimiters, tx, opts) {
           currentClaim.references.push(ref);
         } else {
           attachReference(ref, activeEntity, entityMutators);
+          reportDiscardedEntitySegment(position);
         }
         break;
       }
@@ -3542,6 +3579,7 @@ function get837Claims(delimiters, tx, opts) {
           sink
         );
         activeEntity = void 0;
+        entityLoopClosedByStrayLx = false;
         context = { kind: "loop2300" };
         break;
       }
@@ -3590,24 +3628,53 @@ function get837Claims(delimiters, tx, opts) {
         flushServiceLine();
         if (currentClaim === void 0) {
           warnings.push(serviceLineDropped(position));
+          droppedLineReported = true;
+          entityLoopClosedByStrayLx ||= activeEntity !== void 0;
+          activeEntity = void 0;
           break;
         }
         currentServiceLine = openServiceLine2(seg, delimiters, currentClaim.variant, position);
-        if (currentServiceLine === void 0) warnings.push(serviceLineDropped(position));
+        if (currentServiceLine === void 0) {
+          warnings.push(serviceLineDropped(position));
+          droppedLineReported = true;
+        }
         activeEntity = void 0;
+        entityLoopClosedByStrayLx = false;
         context = { kind: "loop2400" };
         break;
       }
+      // A service segment with no line open to decode into is a loss the
+      // walker used to take in silence. Two ways to reach it, and only one
+      // was ever reported: an LX that opened nothing already warned at the
+      // LX (`droppedLineReported`), while a segment with no Loop 2400 open
+      // at all had no anchor to warn at and so reported on no channel - a
+      // charge, a quantity, a procedure code and its modifiers off the wire
+      // and onto nothing. `reportOrphanServiceSegment` closes only the
+      // second: it anchors at the service segment itself, because that is
+      // the only segment the case has. Note the condition is "no line open",
+      // NOT "no LX in the file": an LX in an earlier claim is still an LX.
+      //
+      // It does NOT decode the segment. The charge is SV1-02 / SV2-03 and
+      // the units SV1-04 / SV2-05 / SV3-06, so reading a service segment
+      // into a line the walker never opened is how a mis-read charge gets
+      // minted. Refusing to read is the safe half; doing it silently was the
+      // defect. This says nothing about VARIANT resolution, which happens
+      // before the walk and scans every SVx in the body: an orphan segment
+      // is eligible for that fallback like any other, which is pre-existing
+      // and disclosed in KNOWN-LIMITATIONS.md rather than changed here.
       case "SV1": {
         if (currentServiceLine !== void 0) decodeSv1(currentServiceLine, seg, delimiters, sink);
+        else reportOrphanServiceSegment(position);
         break;
       }
       case "SV2": {
         if (currentServiceLine !== void 0) decodeSv2(currentServiceLine, seg, delimiters, sink);
+        else reportOrphanServiceSegment(position);
         break;
       }
       case "SV3": {
         if (currentServiceLine !== void 0) decodeSv3(currentServiceLine, seg, delimiters, sink);
+        else reportOrphanServiceSegment(position);
         break;
       }
       case "TOO": {
@@ -8401,6 +8468,7 @@ var HL_LEVEL4 = {
   DEPENDENT: "23"
 };
 var DEFAULT_REVIEW_LEVEL = "EV";
+var REVIEW_LEVEL_CODES = Object.freeze(["EV", "SS"]);
 function build278Request(spec) {
   return buildServicesReview("005010X217", "request", spec);
 }
@@ -8539,6 +8607,13 @@ function enforceStructuralSpec7(spec, direction) {
   }
 }
 function enforceReview(review, locator, direction) {
+  const resolvedLevel = review.levelCode ?? DEFAULT_REVIEW_LEVEL;
+  if (!REVIEW_LEVEL_CODES.includes(resolvedLevel)) {
+    throw new ServicesReview278BuildError(
+      AUTH_278_BUILD_ERROR_CODES.X12_278_BUILD_INVALID_SPEC,
+      `build278: review at ${locator} has HL-03 level code ${renderCallerValue(resolvedLevel)}; a review level must be "EV" (patient event) or "SS" (service). A level outside those two emits a well-formed document whose review loop no reader opens, so the review and its HCR-01 certification decision would not decode.`
+    );
+  }
   if (review.requestCategoryCode === "") {
     throw new ServicesReview278BuildError(
       AUTH_278_BUILD_ERROR_CODES.X12_278_BUILD_INVALID_SPEC,
@@ -10117,7 +10192,7 @@ var profiles = Object.freeze({
 });
 
 // src/index.ts
-var VERSION = "0.0.10";
+var VERSION = "0.0.11";
 
 exports.ACK_BUILD_ERROR_CODES = ACK_BUILD_ERROR_CODES;
 exports.ALL_WARNING_MESSAGES = ALL_WARNING_MESSAGES;
@@ -10254,6 +10329,7 @@ exports.elementDecimal = elementDecimal;
 exports.elementDecimalOrZero = elementDecimalOrZero;
 exports.elementOptional = elementOptional;
 exports.elementValue = elementValue;
+exports.entitySegmentDiscardedAfterLx = entitySegmentDiscardedAfterLx;
 exports.escapeRelease = escapeRelease;
 exports.get271Eligibility = get271Eligibility;
 exports.get277CADisposition = get277CADisposition;
@@ -10300,6 +10376,7 @@ exports.segmentCountMismatch = segmentCountMismatch;
 exports.serializeX12 = serializeX12;
 exports.serviceLineDropped = serviceLineDropped;
 exports.serviceLineNotDecoded = serviceLineNotDecoded;
+exports.serviceSegmentWithoutLx = serviceSegmentWithoutLx;
 exports.setDefaultProfile = setDefaultProfile;
 exports.trailingGarbage = trailingGarbage;
 exports.transactionCountMismatch = transactionCountMismatch;