@cosyte/x12 0.0.15 → 0.0.16

package/dist/index.d.cts

@@ -285,9 +285,7 @@ interface X12ParseWarning {
  * Neither side is echoed, not truncated and not hashed. A control number is
  * free-form trading-partner text on five of the six slots (only ISA-13 is
  * fixed-width), routinely carries a batch or patient-account identifier in
- * the field, and is entirely sender-controlled. Read `isa.elements[13]`,
- * `iea.elements[2]`, `gs.elements[6]`, `ge.elements[2]`, `st.elements[2]`
- * and `se.elements[2]` off the model when you need the values.
+ * the field, and is entirely sender-controlled.
  *
  * @example
  * ```ts
@@ -319,8 +317,7 @@ declare function pre005010(position: X12Position): X12ParseWarning;
  * Build an `X12_GROUP_COUNT_MISMATCH` warning. Emitted when IEA-01 does not
  * equal the actual number of GS..GE groups present in the interchange.
  * Trading partners use this to detect transmission truncation. Both numbers
- * stay on the model (`iea.elements[1]` and `ix.groups.length`) and neither
- * is silently corrected.
+ * stay on the model and neither is silently corrected.
  *
  * @example
  * ```ts
@@ -332,8 +329,7 @@ declare function groupCountMismatch(position: X12Position): X12ParseWarning;
 /**
  * Build an `X12_TRANSACTION_COUNT_MISMATCH` warning. Emitted when GE-01
  * does not equal the actual number of ST..SE transaction sets present in
- * the group. Both numbers stay on the model (`ge.elements[1]` and
- * `group.transactions.length`).
+ * the group. Both numbers stay on the model.
  *
  * @example
  * ```ts
@@ -588,10 +584,15 @@ declare function missingRequiredLoop(position: X12Position, loop: X12RequiredLoo
  * Build an `X12_837_UNKNOWN_VARIANT` warning. Emitted when the 837 helper
  * cannot resolve the variant from ST-03's implementation-convention
  * reference AND no SVx service-line segment is present to fall back on.
- * The parsed submission still ships with `variant: "unknown"` and the
- * verbatim reference on `submission.implementationConventionReference`; the
+ * The parsed submission still ships with `variant: "unknown"`, and the
  * walker does its best on shared structure (envelope, HL, claim header) and
- * skips variant-specific service-line decoding.
+ * skips variant-specific service-line decoding. **This message deliberately
+ * points at no model field.** Recognition reads `ST-03` as FRAMED while
+ * `submission.implementationConventionReference` is decoded of any `?` release
+ * escape, so on a document that escapes a delimiter inside `ST-03` the two
+ * differ and the model field can hold an identifier this code just said was
+ * not recognised (`X12-ST03-READ-NOT-RELEASE-AWARE`). A pointer stood here and
+ * in the message text and is DELETED, not reworded.
  *
  * `get837Claims` anchors this at the **ST**, which is `tx.segments[0]` and
  * carries the ST-03 the resolution reads. Through `0.0.10` it passed
@@ -1454,6 +1455,12 @@ declare const NON_SPEC_SEGMENT_ID = "(non-spec)";
  * decodes to an empty segment (`id: ""`, `elements: [""]`); callers that
  * care can guard.
  *
+ * **A degenerate delimiter set whose ELEMENT SEPARATOR is itself `?` splits
+ * literally**, because one byte cannot both separate and escape. Only that
+ * role is guarded here: a `?` repetition or component separator is a
+ * different call and is deliberately unchanged (see
+ * {@link "./release.js".splitWithRelease}).
+ *
  * @example
  * ```ts
  * import { decodeSegment } from "@cosyte/x12";
@@ -1916,7 +1923,9 @@ interface Ta1Segment {
  *
  * `elements` on the ST and SE segments themselves IS decoded at envelope
  * time so envelope invariants can be checked (ST-02 ↔ SE-02 control-number
- * reconciliation, SE-01 segment count).
+ * reconciliation, SE-01 segment count). **Read "decoded" as element-SPLIT and
+ * nothing more: the strings are PRE-`?`-unescape**, and a reader that publishes
+ * one to a consumer unescapes it first (`X12-ST03-READ-NOT-RELEASE-AWARE`).
  *
  * @example
  * ```ts
@@ -12335,7 +12344,9 @@ type Ta1AckCode = (typeof TA1_ACK_CODES)[keyof typeof TA1_ACK_CODES];
  * TA1-05 interchange note code (ASC X12 code list I18). Codes `000`–`028`
  * are defined by the standard; values past `028` exist in some standard
  * revisions and are accepted on parse (Postel's Law) but not enumerated
- * here - the parsed model carries the raw string for verbatim preservation.
+ * here - the parsed model carries the un-narrowed string on `noteCodeRaw`,
+ * post-`?`-unescape as of `X12-TA1-RESIDUALS`. **A clause here said "verbatim"
+ * and is deleted rather than reworded**; `raw.elements[5]` is the byte surface.
  *
  * `000` is the canonical "no error" note paired with a `TA1-04 == 'A'`
  * acceptance. The build-time safety guard refuses a fabricated `A` paired
@@ -12412,9 +12423,11 @@ declare const TA1_NOTE_CODES: {
 /**
  * String-literal union over {@link TA1_NOTE_CODES} - the standard-issued
  * note codes `000`–`028`. Real-world inbound TA1 may carry a value past
- * `028` (some revisions extend the list); `parseTA1` exposes the raw
- * string in that case so the verbatim value survives even when the union
- * cannot statically type it.
+ * `028` (some revisions extend the list); `parseTA1` exposes the
+ * un-narrowed string on `noteCodeRaw` in that case, so the value survives
+ * even when the union cannot statically type it. **It is post-`?`-unescape
+ * as of `X12-TA1-RESIDUALS`, and a clause here calling it VERBATIM is
+ * deleted rather than reworded** - `raw.elements[5]` is the byte surface.
  */
 type Ta1NoteCode = (typeof TA1_NOTE_CODES)[keyof typeof TA1_NOTE_CODES];
 
@@ -12636,13 +12649,23 @@ interface X12Ack999 {
  * - `interchangeTime` - TA1-03: HHMM (echoes inbound ISA-10).
  * - `ackCode` - TA1-04: {@link Ta1AckCode}.
  * - `noteCode` - TA1-05: typed when the value is a known I18 code
- *   ({@link Ta1NoteCode}); the raw string is preserved verbatim alongside
- *   so unknown extensions round-trip.
- * - `noteCodeRaw` - verbatim TA1-05 string. Equal to `noteCode` when the
- *   value is a known I18 code; equal to the raw inbound text when not.
+ *   ({@link Ta1NoteCode}); `noteCodeRaw` carries the un-narrowed string
+ *   alongside so unknown extensions survive. **A clause here said that
+ *   string is preserved VERBATIM and is deleted, not reworded:**
+ *   `X12-TA1-RESIDUALS` made it post-unescape, and `raw.elements[5]` is
+ *   the verbatim surface.
+ * - `noteCodeRaw` - the un-narrowed TA1-05 string. Equal to `noteCode` when
+ *   the value is a known I18 code; equal to the decoded inbound text when
+ *   not.
  * - `raw` - the underlying envelope-level {@link Ta1Segment}, for
  *   byte-exact round-trip.
  *
+ * **The five decoded fields are POST-`?`-unescape; `raw` is the verbatim
+ * byte surface and is not.** `X12-TA1-RESIDUALS` moved the decoded half:
+ * before it, a released TA1-01 read back carrying its `?` and matched no
+ * ISA-13, while every dot-path read of the same element already unescaped.
+ * Read `raw.elements` when you want the bytes.
+ *
  * @example
  * ```ts
  * import type { X12AckTA1 } from "@cosyte/x12";
@@ -12956,20 +12979,17 @@ declare function build999(spec: Build999Spec): X12Interchange;
  *   number of `"0000^0001"`, truncating the reassociation key to the first
  *   repetition, and answers `"0000^0001"` here; the composite read `"01-1"`
  *   answered `"0000"` for `"0000:0001"`. **The measured pure cost is a
- *   MID-STRING `?`, and only on the surfaces documented as raw**: `raw`,
- *   `elements` and `parseTA1`'s fields read `"0000??0001"` where they read
- *   `"0000?0001"`, while the dot-path read of THAT value unescapes and
- *   answered `"0000?0001"` on both. Read the clause as scoped to the
- *   mid-string `?`, because it is not true of `^` or `:` three sentences
- *   up. **`getSegmentValue` takes an `X12Segment` and `Ta1Segment` carries
- *   no `id`, so add one to read a TA1 through it.** No total is published:
- *   that is what was measured, not a closed account.
- * - **`parseTA1` reads elements RAW, pre-`?`-unescape**, exactly as
- *   `X12Segment.elements` has always documented. So a control number of
- *   `"00000001?"` now reads back as `"00000001??"` rather than as
- *   `"00000001?*260601"`. The disposition is correct where it was
- *   inverted; the key still needs `unescapeRelease` applied by the reader.
- *   That is a property of the read half and is not changed here.
+ *   MID-STRING `?`, and only on the surfaces documented as raw**: `raw` and
+ *   `elements` read `"0000??0001"` where they read `"0000?0001"`, while the
+ *   dot-path read of THAT value unescapes and answered `"0000?0001"` on
+ *   both. Read the clause as scoped to the mid-string `?`, because it is
+ *   not true of `^` or `:` three sentences up. **`getSegmentValue` takes an
+ *   `X12Segment` and `Ta1Segment` carries no `id`, so add one to read a TA1
+ *   through it.** No total is published: that is what was measured, not a
+ *   closed account.
+ *   **🩺 A CLAUSE NAMING `parseTA1`'s FIELDS AS A THIRD SUCH SURFACE STOOD
+ *   HERE AND IS DELETED, NOT REWORDED.** `X12-TA1-RESIDUALS` made those
+ *   fields post-unescape, so it is measured false; do not restate it.
  * - **A caller who was pre-releasing the value themselves** (the remedy
  *   `KNOWN-LIMITATIONS.md` named while this was open) is now escaping
  *   twice: `"00000001??"` in, `"00000001????"` out. The framing and the
@@ -12977,10 +12997,24 @@ declare function build999(spec: Build999Spec): X12Interchange;
  *   surface - the dot-path read answers `"00000001??"` where it answered
  *   `"00000001?"`. Drop the hand-rolled escape.
  *
- * **And an EMPTY control number is still not refused.** `escapeRelease`
- * early-returns on `""` and this module has no required-field guard, so
- * `interchangeControlNumber: ""` emits `TA1**260601*1200*A*000` with no
- * error, here and at every earlier release. Only a NON-string refuses.
+ * **And an EMPTY control number USED to go out unrefused.** `escapeRelease`
+ * early-returns on `""` and this module had no required-field guard, so
+ * `interchangeControlNumber: ""` emitted `TA1**260601*1200*A*000` with no
+ * error, through `0.0.15`. `X12-EMPTY-CONTROL-NUMBER-FABRICATED` closed it:
+ * see {@link "../../builder/caller-control-number.js".requireControlNumber}.
+ * `X12-CONTROL-NUMBER-GUARD-NOT-TYPE-CHECKED` then made the same guard
+ * type-check, so TA1-01 draws a refusal naming TA1-01 rather than the escaper's
+ * one naming only the builder - same class, same code, different words. The
+ * guard is still byte-strict, so a whitespace-only TA1-01 still builds.
+ *
+ * **The other four slots were left open by that slice and `X12-TA1-RESIDUALS`
+ * closes them.** TA1-01's guard was the only required-field guard this module
+ * had, so `interchangeDate`, `interchangeTime`, `ackCode` and `noteCode` each
+ * emitted an absent element on `""` with `warnings: []`. **TA1-05's cell has to
+ * be read against a NON-Accept disposition, or `enforceAcceptIsClean` reaches
+ * it first and the reading measures that guard instead** - see
+ * {@link requireTa1Element}, which carries the grounding and the residual it
+ * deliberately leaves.
  *
  * And the release is scoped to the delimiter set the caller states through
  * {@link BuildTA1Options} - see that interface for why guessing one is a
@@ -13157,9 +13191,7 @@ interface BuildTA1Options {
  * Every warning it emits is built by the same value-free factories the parser
  * uses: `message` is a frozen-registry lookup and `position` locates the
  * control segment, so a declared count or control number can never reach a
- * diagnostic. Read the declared and actual values off the model
- * (`se.elements[1]` against `tx.rawSegments.length`, `ge.elements[1]` against
- * `group.transactions.length`, `iea.elements[1]` against `ix.groups.length`).
+ * diagnostic.
  */
 
 /**

package/dist/index.d.ts

@@ -285,9 +285,7 @@ interface X12ParseWarning {
  * Neither side is echoed, not truncated and not hashed. A control number is
  * free-form trading-partner text on five of the six slots (only ISA-13 is
  * fixed-width), routinely carries a batch or patient-account identifier in
- * the field, and is entirely sender-controlled. Read `isa.elements[13]`,
- * `iea.elements[2]`, `gs.elements[6]`, `ge.elements[2]`, `st.elements[2]`
- * and `se.elements[2]` off the model when you need the values.
+ * the field, and is entirely sender-controlled.
  *
  * @example
  * ```ts
@@ -319,8 +317,7 @@ declare function pre005010(position: X12Position): X12ParseWarning;
  * Build an `X12_GROUP_COUNT_MISMATCH` warning. Emitted when IEA-01 does not
  * equal the actual number of GS..GE groups present in the interchange.
  * Trading partners use this to detect transmission truncation. Both numbers
- * stay on the model (`iea.elements[1]` and `ix.groups.length`) and neither
- * is silently corrected.
+ * stay on the model and neither is silently corrected.
  *
  * @example
  * ```ts
@@ -332,8 +329,7 @@ declare function groupCountMismatch(position: X12Position): X12ParseWarning;
 /**
  * Build an `X12_TRANSACTION_COUNT_MISMATCH` warning. Emitted when GE-01
  * does not equal the actual number of ST..SE transaction sets present in
- * the group. Both numbers stay on the model (`ge.elements[1]` and
- * `group.transactions.length`).
+ * the group. Both numbers stay on the model.
  *
  * @example
  * ```ts
@@ -588,10 +584,15 @@ declare function missingRequiredLoop(position: X12Position, loop: X12RequiredLoo
  * Build an `X12_837_UNKNOWN_VARIANT` warning. Emitted when the 837 helper
  * cannot resolve the variant from ST-03's implementation-convention
  * reference AND no SVx service-line segment is present to fall back on.
- * The parsed submission still ships with `variant: "unknown"` and the
- * verbatim reference on `submission.implementationConventionReference`; the
+ * The parsed submission still ships with `variant: "unknown"`, and the
  * walker does its best on shared structure (envelope, HL, claim header) and
- * skips variant-specific service-line decoding.
+ * skips variant-specific service-line decoding. **This message deliberately
+ * points at no model field.** Recognition reads `ST-03` as FRAMED while
+ * `submission.implementationConventionReference` is decoded of any `?` release
+ * escape, so on a document that escapes a delimiter inside `ST-03` the two
+ * differ and the model field can hold an identifier this code just said was
+ * not recognised (`X12-ST03-READ-NOT-RELEASE-AWARE`). A pointer stood here and
+ * in the message text and is DELETED, not reworded.
  *
  * `get837Claims` anchors this at the **ST**, which is `tx.segments[0]` and
  * carries the ST-03 the resolution reads. Through `0.0.10` it passed
@@ -1454,6 +1455,12 @@ declare const NON_SPEC_SEGMENT_ID = "(non-spec)";
  * decodes to an empty segment (`id: ""`, `elements: [""]`); callers that
  * care can guard.
  *
+ * **A degenerate delimiter set whose ELEMENT SEPARATOR is itself `?` splits
+ * literally**, because one byte cannot both separate and escape. Only that
+ * role is guarded here: a `?` repetition or component separator is a
+ * different call and is deliberately unchanged (see
+ * {@link "./release.js".splitWithRelease}).
+ *
  * @example
  * ```ts
  * import { decodeSegment } from "@cosyte/x12";
@@ -1916,7 +1923,9 @@ interface Ta1Segment {
  *
  * `elements` on the ST and SE segments themselves IS decoded at envelope
  * time so envelope invariants can be checked (ST-02 ↔ SE-02 control-number
- * reconciliation, SE-01 segment count).
+ * reconciliation, SE-01 segment count). **Read "decoded" as element-SPLIT and
+ * nothing more: the strings are PRE-`?`-unescape**, and a reader that publishes
+ * one to a consumer unescapes it first (`X12-ST03-READ-NOT-RELEASE-AWARE`).
  *
  * @example
  * ```ts
@@ -12335,7 +12344,9 @@ type Ta1AckCode = (typeof TA1_ACK_CODES)[keyof typeof TA1_ACK_CODES];
  * TA1-05 interchange note code (ASC X12 code list I18). Codes `000`–`028`
  * are defined by the standard; values past `028` exist in some standard
  * revisions and are accepted on parse (Postel's Law) but not enumerated
- * here - the parsed model carries the raw string for verbatim preservation.
+ * here - the parsed model carries the un-narrowed string on `noteCodeRaw`,
+ * post-`?`-unescape as of `X12-TA1-RESIDUALS`. **A clause here said "verbatim"
+ * and is deleted rather than reworded**; `raw.elements[5]` is the byte surface.
  *
  * `000` is the canonical "no error" note paired with a `TA1-04 == 'A'`
  * acceptance. The build-time safety guard refuses a fabricated `A` paired
@@ -12412,9 +12423,11 @@ declare const TA1_NOTE_CODES: {
 /**
  * String-literal union over {@link TA1_NOTE_CODES} - the standard-issued
  * note codes `000`–`028`. Real-world inbound TA1 may carry a value past
- * `028` (some revisions extend the list); `parseTA1` exposes the raw
- * string in that case so the verbatim value survives even when the union
- * cannot statically type it.
+ * `028` (some revisions extend the list); `parseTA1` exposes the
+ * un-narrowed string on `noteCodeRaw` in that case, so the value survives
+ * even when the union cannot statically type it. **It is post-`?`-unescape
+ * as of `X12-TA1-RESIDUALS`, and a clause here calling it VERBATIM is
+ * deleted rather than reworded** - `raw.elements[5]` is the byte surface.
  */
 type Ta1NoteCode = (typeof TA1_NOTE_CODES)[keyof typeof TA1_NOTE_CODES];
 
@@ -12636,13 +12649,23 @@ interface X12Ack999 {
  * - `interchangeTime` - TA1-03: HHMM (echoes inbound ISA-10).
  * - `ackCode` - TA1-04: {@link Ta1AckCode}.
  * - `noteCode` - TA1-05: typed when the value is a known I18 code
- *   ({@link Ta1NoteCode}); the raw string is preserved verbatim alongside
- *   so unknown extensions round-trip.
- * - `noteCodeRaw` - verbatim TA1-05 string. Equal to `noteCode` when the
- *   value is a known I18 code; equal to the raw inbound text when not.
+ *   ({@link Ta1NoteCode}); `noteCodeRaw` carries the un-narrowed string
+ *   alongside so unknown extensions survive. **A clause here said that
+ *   string is preserved VERBATIM and is deleted, not reworded:**
+ *   `X12-TA1-RESIDUALS` made it post-unescape, and `raw.elements[5]` is
+ *   the verbatim surface.
+ * - `noteCodeRaw` - the un-narrowed TA1-05 string. Equal to `noteCode` when
+ *   the value is a known I18 code; equal to the decoded inbound text when
+ *   not.
  * - `raw` - the underlying envelope-level {@link Ta1Segment}, for
  *   byte-exact round-trip.
  *
+ * **The five decoded fields are POST-`?`-unescape; `raw` is the verbatim
+ * byte surface and is not.** `X12-TA1-RESIDUALS` moved the decoded half:
+ * before it, a released TA1-01 read back carrying its `?` and matched no
+ * ISA-13, while every dot-path read of the same element already unescaped.
+ * Read `raw.elements` when you want the bytes.
+ *
  * @example
  * ```ts
  * import type { X12AckTA1 } from "@cosyte/x12";
@@ -12956,20 +12979,17 @@ declare function build999(spec: Build999Spec): X12Interchange;
  *   number of `"0000^0001"`, truncating the reassociation key to the first
  *   repetition, and answers `"0000^0001"` here; the composite read `"01-1"`
  *   answered `"0000"` for `"0000:0001"`. **The measured pure cost is a
- *   MID-STRING `?`, and only on the surfaces documented as raw**: `raw`,
- *   `elements` and `parseTA1`'s fields read `"0000??0001"` where they read
- *   `"0000?0001"`, while the dot-path read of THAT value unescapes and
- *   answered `"0000?0001"` on both. Read the clause as scoped to the
- *   mid-string `?`, because it is not true of `^` or `:` three sentences
- *   up. **`getSegmentValue` takes an `X12Segment` and `Ta1Segment` carries
- *   no `id`, so add one to read a TA1 through it.** No total is published:
- *   that is what was measured, not a closed account.
- * - **`parseTA1` reads elements RAW, pre-`?`-unescape**, exactly as
- *   `X12Segment.elements` has always documented. So a control number of
- *   `"00000001?"` now reads back as `"00000001??"` rather than as
- *   `"00000001?*260601"`. The disposition is correct where it was
- *   inverted; the key still needs `unescapeRelease` applied by the reader.
- *   That is a property of the read half and is not changed here.
+ *   MID-STRING `?`, and only on the surfaces documented as raw**: `raw` and
+ *   `elements` read `"0000??0001"` where they read `"0000?0001"`, while the
+ *   dot-path read of THAT value unescapes and answered `"0000?0001"` on
+ *   both. Read the clause as scoped to the mid-string `?`, because it is
+ *   not true of `^` or `:` three sentences up. **`getSegmentValue` takes an
+ *   `X12Segment` and `Ta1Segment` carries no `id`, so add one to read a TA1
+ *   through it.** No total is published: that is what was measured, not a
+ *   closed account.
+ *   **🩺 A CLAUSE NAMING `parseTA1`'s FIELDS AS A THIRD SUCH SURFACE STOOD
+ *   HERE AND IS DELETED, NOT REWORDED.** `X12-TA1-RESIDUALS` made those
+ *   fields post-unescape, so it is measured false; do not restate it.
  * - **A caller who was pre-releasing the value themselves** (the remedy
  *   `KNOWN-LIMITATIONS.md` named while this was open) is now escaping
  *   twice: `"00000001??"` in, `"00000001????"` out. The framing and the
@@ -12977,10 +12997,24 @@ declare function build999(spec: Build999Spec): X12Interchange;
  *   surface - the dot-path read answers `"00000001??"` where it answered
  *   `"00000001?"`. Drop the hand-rolled escape.
  *
- * **And an EMPTY control number is still not refused.** `escapeRelease`
- * early-returns on `""` and this module has no required-field guard, so
- * `interchangeControlNumber: ""` emits `TA1**260601*1200*A*000` with no
- * error, here and at every earlier release. Only a NON-string refuses.
+ * **And an EMPTY control number USED to go out unrefused.** `escapeRelease`
+ * early-returns on `""` and this module had no required-field guard, so
+ * `interchangeControlNumber: ""` emitted `TA1**260601*1200*A*000` with no
+ * error, through `0.0.15`. `X12-EMPTY-CONTROL-NUMBER-FABRICATED` closed it:
+ * see {@link "../../builder/caller-control-number.js".requireControlNumber}.
+ * `X12-CONTROL-NUMBER-GUARD-NOT-TYPE-CHECKED` then made the same guard
+ * type-check, so TA1-01 draws a refusal naming TA1-01 rather than the escaper's
+ * one naming only the builder - same class, same code, different words. The
+ * guard is still byte-strict, so a whitespace-only TA1-01 still builds.
+ *
+ * **The other four slots were left open by that slice and `X12-TA1-RESIDUALS`
+ * closes them.** TA1-01's guard was the only required-field guard this module
+ * had, so `interchangeDate`, `interchangeTime`, `ackCode` and `noteCode` each
+ * emitted an absent element on `""` with `warnings: []`. **TA1-05's cell has to
+ * be read against a NON-Accept disposition, or `enforceAcceptIsClean` reaches
+ * it first and the reading measures that guard instead** - see
+ * {@link requireTa1Element}, which carries the grounding and the residual it
+ * deliberately leaves.
  *
  * And the release is scoped to the delimiter set the caller states through
  * {@link BuildTA1Options} - see that interface for why guessing one is a
@@ -13157,9 +13191,7 @@ interface BuildTA1Options {
  * Every warning it emits is built by the same value-free factories the parser
  * uses: `message` is a frozen-registry lookup and `position` locates the
  * control segment, so a declared count or control number can never reach a
- * diagnostic. Read the declared and actual values off the model
- * (`se.elements[1]` against `tx.rawSegments.length`, `ge.elements[1]` against
- * `group.transactions.length`, `iea.elements[1]` against `ix.groups.length`).
+ * diagnostic.
  */
 
 /**