@cosyte/x12 0.0.14 → 0.0.15

package/dist/index.d.cts

@@ -2483,9 +2483,10 @@ declare function unescapeRelease(input: string, delimiters: Delimiters, emit: (w
  * the untyped-refusal defect this package has fixed elsewhere. This is a pure
  * text utility with no spec, no element and no caller context to name, so
  * `TypeError` is the accurate answer for a wrong-typed argument. **Nothing
- * inside this library can reach it**: all nine builders route every element
+ * inside this library can reach it**: every builder routes its elements
  * through `src/builder/caller-string.ts`, which refuses first with the calling
- * builder's own typed, code-tagged error. This throw is the backstop for a
+ * builder's own typed, code-tagged error. (No count: it is asserted by
+ * `test/builder-string-type.test.ts` and was stale here.) This throw is the backstop for a
  * consumer calling the export directly, where the alternative was silent data
  * loss.
  *
@@ -5720,22 +5721,23 @@ declare function get837Claims(delimiters: Delimiters, tx: X12TransactionSet, opt
 
 /**
  * Interchange + group + transaction identity for the built 837. The builder
- * fixes GS-01 to `"HC"` and the ST-03 / GS-08 version to the variant's TR3
- * (`005010X222A2` / `X223A3` / `X224A2`) so the caller never hand-codes them.
- *
- * **🩺 Known limitation, disclosed rather than changed: those three are
- * published errata guides, but they are neither the identifiers HIPAA
- * adopts at 45 CFR 162.1102 nor the ones payer companion guides commonly
- * require in ST-03 / GS-08** (CMS and several state Medicaid guides state
- * `005010X222A1` for Professional, `005010X223A2` for Institutional and
- * `005010X224A2` for Dental). **A partner that requires one of those will
- * reject a Professional or Institutional 837 this builder emits, and there
- * is currently no way for a caller to override the value.** Nothing here
- * was re-stamped on that evidence: which published guide identifier a
- * trading partner accepts is a partner fact, not a spec fact, and silently
- * changing bytes this library already emitted would break the partners it
- * works with today. `KNOWN-LIMITATIONS.md` carries this as an open
- * residual. The READ side is unaffected - `get837Claims` recognises all of
+ * fixes GS-01 to `"HC"`, and defaults the ST-03 / GS-08 reference to the
+ * variant's TR3 (`005010X222A2` / `X223A3` / `X224A2`) so the caller never
+ * has to hand-code it.
+ *
+ * **🩺 That default is not what every trading partner accepts, so
+ * {@link Build837EnvelopeSpec.implementationConventionReference} overrides
+ * it.** The three defaults are published errata guides, but they are
+ * neither the identifiers HIPAA adopts at 45 CFR 162.1102 nor the ones
+ * payer companion guides commonly require in ST-03 / GS-08 (CMS and several
+ * state Medicaid guides state `005010X222A1` for Professional and
+ * `005010X223A2` for Institutional). **A partner that requires one of those
+ * will reject a Professional or Institutional 837 built on the default**,
+ * and the override is how you send what your partner asked for. The default
+ * itself was deliberately NOT re-stamped: which published guide identifier
+ * a partner accepts is a partner fact rather than a spec fact, and changing
+ * bytes this library already emitted would break the partners it works with
+ * today. The READ side is unaffected - `get837Claims` recognises all of
  * these references.
  *
  * @example
@@ -5764,6 +5766,44 @@ interface Build837EnvelopeSpec {
     readonly groupControlNumber: string;
     /** ST-02 / SE-02 - transaction set control number. */
     readonly transactionSetControlNumber: string;
+    /**
+     * 🩺 ST-03 **and** GS-08 - the implementation convention reference this
+     * 837 declares. Default: the variant's TR3 (`005010X222A2` Professional,
+     * `005010X223A3` Institutional, `005010X224A2` Dental).
+     *
+     * **Set it to whatever your trading partner's companion guide requires**,
+     * for example `005010X222A1` on a professional claim to a payer that asks
+     * for it. Which published identifier a partner accepts is a partner fact,
+     * so this library will not choose for you: it defaults to a real published
+     * guide and gets out of the way. **One value is written to both elements**,
+     * because this builder has always written the same reference to ST-03 and
+     * GS-08 and nothing grounds a caller making them differ. That is a statement
+     * about the bytes this field emits, not about what each element may legally
+     * hold: GS-08 is data element 480 (`AN 1/12`) and ST-03 is element 1705
+     * (`AN 1/35`), and nothing here bounds the length.
+     *
+     * Refused, all `X12_837_BUILD_INVALID_SPEC`. An **empty** string, because a
+     * trailing empty element is dropped on emit, so it would delete ST-03 and
+     * GS-08 rather than send them empty. One carrying an **active delimiter or
+     * the release character**, because these two elements cannot carry it even
+     * escaped: the ST and GS segments are read by a splitter that is not
+     * release-aware, so the declaration would silently become two elements. And
+     * one **this library's own reader resolves to a different variant**
+     * (`005010X223A2` handed to `build837P`): the file would declare one variant
+     * and carry another's service segments, and `get837Claims` would then decode
+     * none of its service lines. Those are what this field adds, on top of the
+     * element-type guard every string slot already has, which refuses a
+     * non-string with the same code - no total is published. **Anything else is
+     * emitted as given** - the set of published errata is not provably
+     * exhaustive, so an identifier this library does not carry is the caller's
+     * call, not an error.
+     *
+     * 🩺 A guard on this element cannot make the element trustworthy. An active
+     * delimiter in a DIFFERENT envelope field splits its own segment and shifts
+     * every element after it, so ST-03 / GS-08 are then read out of a
+     * neighbour's slot. `KNOWN-LIMITATIONS.md` carries the measurement.
+     */
+    readonly implementationConventionReference?: string;
     /** ISA-05 - interchange sender qualifier. Default `"ZZ"`. */
     readonly senderQualifier?: string;
     /** ISA-07 - interchange receiver qualifier. Default `"ZZ"`. */
@@ -6475,8 +6515,9 @@ interface Build837Spec {
 
 /**
  * `build837P` / `build837I` / `build837D` - pure-function builders for a
- * 005010 837 Healthcare Claim (Professional `X222A2`, Institutional
- * `X223A3`, Dental `X224A2`). NEVER auto-sends, NEVER opens a socket, NEVER
+ * 005010 837 Healthcare Claim (Professional, Institutional, Dental; the
+ * ST-03 / GS-08 guide reference defaults to `X222A2` / `X223A3` / `X224A2`
+ * and the caller may state another). NEVER auto-sends, NEVER opens a socket, NEVER
  * touches the filesystem. The library mechanically emits the claim it is
  * told; a spec whose billing-provider → subscriber → (claims | patient)
  * tree cannot form a valid HL hierarchy is REFUSED via {@link
@@ -6505,7 +6546,9 @@ interface Build837Spec {
  */
 
 /**
- * `build837P` - assemble a 005010X222A2 Professional 837 around the spec.
+ * `build837P` - assemble a Professional 837 around the spec, declaring
+ * `005010X222A2` unless `envelope.implementationConventionReference` states
+ * the guide your trading partner requires.
  *
  * @example
  * ```ts
@@ -6537,8 +6580,10 @@ interface Build837Spec {
  */
 declare function build837P(spec: Build837Spec): X12Interchange;
 /**
- * `build837I` - assemble a 005010X223A3 Institutional 837 around the spec.
- * Service lines must be `variant: "I"` (SV2).
+ * `build837I` - assemble an Institutional 837 around the spec, declaring
+ * `005010X223A3` unless `envelope.implementationConventionReference` states
+ * the guide your trading partner requires. Service lines must be
+ * `variant: "I"` (SV2).
  *
  * @example
  * ```ts
@@ -6549,8 +6594,10 @@ declare function build837P(spec: Build837Spec): X12Interchange;
  */
 declare function build837I(spec: Build837Spec): X12Interchange;
 /**
- * `build837D` - assemble a 005010X224A2 Dental 837 around the spec. Service
- * lines must be `variant: "D"` (SV3); per-line tooth detail rides on TOO.
+ * `build837D` - assemble a Dental 837 around the spec, declaring
+ * `005010X224A2` unless `envelope.implementationConventionReference` states
+ * the guide your trading partner requires. Service lines must be
+ * `variant: "D"` (SV3); per-line tooth detail rides on TOO.
  *
  * @example
  * ```ts
@@ -12862,6 +12909,82 @@ declare function build999(spec: Build999Spec): X12Interchange;
  * library does NOT silently invent envelope bytes around it - the caller's
  * application boundary owns whether the TA1 is embedded in an outbound
  * interchange or sent as a standalone TA1-only interchange.
+ *
+ * ## 🩺 Why every element is released, and what that changed
+ *
+ * `raw` used to be `[...five caller values].join(elementSeparator)` with
+ * nothing in between, so a caller value carrying an active delimiter took
+ * a slot of its own and shifted every element after it down one. TA1-04 is
+ * the disposition and TA1-05 the note, so the shift landed the read on the
+ * wrong pair, and `parseTA1` narrows an out-of-enum TA1-04 to `R`:
+ * **an Accept this library emitted read back as a Reject**, with the TA1-01
+ * reassociation key merged into TA1-02 and `warnings: []` on every channel.
+ * The inverse is the less safe one and also existed: a `noteCode` of
+ * literally `"A"` (a value the type forbids and nothing checks at run time)
+ * shifted onto TA1-04 and made a **Reject read back as an Accept**, which a
+ * sender never resubmits against.
+ *
+ * The grounding is inside the package, not in a spec clause, which is the
+ * same tiebreak `X12-ENVELOPE-SPLITTER-NOT-RELEASE-AWARE` recorded: one
+ * function disagreed with itself. This module emitted bytes that this
+ * package's own reader decoded into a different disposition than the one
+ * the caller asked for, and every other builder already released the same
+ * class of element through the same helper.
+ *
+ * **It changes bytes, and that is the cost that kept it open for a slice.**
+ * A value containing none of the four delimiters or the release character
+ * is emitted byte-for-byte as before, which is every conformant TA1. A
+ * value containing one is now released, so its bytes differ from the ones
+ * `0.0.14` and earlier put on the wire. What that costs is stated outright
+ * below rather than argued away, and **without a total**: two drafts of this
+ * account published a closed one and both were refuted.
+ *
+ * - **The consumer predicate moves in BOTH directions.** Read the property
+ *   rather than a direction list: `parseTA1` of a `buildTA1` output now
+ *   reports the disposition and note the CALLER passed, where before it
+ *   reported whatever element the shift left in TA1-04. So
+ *   `ackCode === "R"` stops firing where an Accept had been shifted onto
+ *   it, and starts firing where a Reject had been shifted off it -
+ *   `interchangeTime: "12*A"` with `ackCode: "R"` read `"A"` before and
+ *   reads `"R"` here, every field a valid member of its union. What is
+ *   one-directional is the safety, which is a different statement.
+ * - **Only three values in the escaped set ever shifted the segment's own
+ *   element framing**: the element separator, the segment terminator, and
+ *   a `?` immediately before the separator. **`^` and `:` moved the
+ *   dot-path reader instead, and releasing them is a GAIN there.**
+ *   `getSegmentValue(ta1, "01")` answered `"0000"` before for a control
+ *   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.
+ * - **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
+ *   disposition stay correct, and this one regresses on BOTH kinds of
+ *   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 the release is scoped to the delimiter set the caller states through
+ * {@link BuildTA1Options} - see that interface for why guessing one is a
+ * value corruption rather than a safe default.
  */
 
 /**
@@ -12876,7 +12999,18 @@ declare function build999(spec: Build999Spec): X12Interchange;
  * - `ackCode === "A"` paired with `noteCode !== "000"` →
  *   {@link "./errors.js".ACK_BUILD_ERROR_CODES.X12_TA1_ACCEPT_WITH_NOTE}.
  *   Accept must mean accept. Use `E` (accept with errors) when the
- *   inbound had structural defects you elected to ignore.
+ *   inbound had structural defects you elected to ignore. This one runs
+ *   FIRST and its precedence is unchanged.
+ * - Any of the five element values that is not a `string` →
+ *   {@link "./errors.js".ACK_BUILD_ERROR_CODES.X12_ACK_INVALID_SPEC}. This
+ *   is not a bonus guard: releasing a value means routing it through
+ *   {@link "../../builder/caller-string.js".makeCallerEscaper}, and the
+ *   bare `escapeRelease` underneath it returns its empty accumulator for a
+ *   `number`, so escaping without the type check would have replaced the
+ *   shifted-element defect with a silently VANISHED TA1-01. **A number or
+ *   an `undefined` control number used to emit as `TA1*12345*…` (the
+ *   number surviving onto `elements`, in a `readonly string[]`) or
+ *   `TA1**250101*…`; both now refuse.**
  *
  * @param spec - The TA1 fields. `interchangeControlNumber` echoes the
  *               inbound ISA-13; `interchangeDate` / `interchangeTime` echo
@@ -12914,13 +13048,28 @@ declare function build999(spec: Build999Spec): X12Interchange;
  */
 declare function buildTA1(spec: BuildTA1Spec, options?: BuildTA1Options): Ta1Segment;
 /**
- * Options accepted by {@link buildTA1}. Both fields are optional - pass
- * none for the cosyte default envelope (`*` element separator). Override
- * only when the TA1 is being embedded in an outer envelope whose declared
- * delimiters differ from the cosyte default.
+ * Options accepted by {@link buildTA1}: the delimiter set the returned
+ * segment will be read against. Every field is optional and defaults to the
+ * cosyte parser archetype (`*` element, `^` repetition, `:` component, `~`
+ * segment), which is the same four `build999` takes on
+ * {@link "./types.js".Build999EnvelopeSpec}.
+ *
+ * **The three non-element fields exist for ESCAPING and nothing else.**
+ * `buildTA1` still emits no segment terminator, no repetition and no
+ * composite. It has to know them because a caller value carrying one of
+ * them has to be released, and because escaping a byte that is NOT a
+ * delimiter where the segment lands corrupts the value: `unescapeRelease`
+ * preserves `?X` verbatim for any `X` outside the declared set, so a value
+ * released against a guessed delimiter comes back carrying a stray `?`.
+ * **If you embed a TA1 in an envelope whose delimiters are not the
+ * archetype, state them here** - the defaults are an assumption this
+ * function cannot verify, exactly as they were before it escaped anything.
  */
 interface BuildTA1Options {
     readonly elementSeparator?: string;
+    readonly repetitionSeparator?: string;
+    readonly componentSeparator?: string;
+    readonly segmentTerminator?: string;
 }
 
 /**

package/dist/index.d.ts

@@ -2483,9 +2483,10 @@ declare function unescapeRelease(input: string, delimiters: Delimiters, emit: (w
  * the untyped-refusal defect this package has fixed elsewhere. This is a pure
  * text utility with no spec, no element and no caller context to name, so
  * `TypeError` is the accurate answer for a wrong-typed argument. **Nothing
- * inside this library can reach it**: all nine builders route every element
+ * inside this library can reach it**: every builder routes its elements
  * through `src/builder/caller-string.ts`, which refuses first with the calling
- * builder's own typed, code-tagged error. This throw is the backstop for a
+ * builder's own typed, code-tagged error. (No count: it is asserted by
+ * `test/builder-string-type.test.ts` and was stale here.) This throw is the backstop for a
  * consumer calling the export directly, where the alternative was silent data
  * loss.
  *
@@ -5720,22 +5721,23 @@ declare function get837Claims(delimiters: Delimiters, tx: X12TransactionSet, opt
 
 /**
  * Interchange + group + transaction identity for the built 837. The builder
- * fixes GS-01 to `"HC"` and the ST-03 / GS-08 version to the variant's TR3
- * (`005010X222A2` / `X223A3` / `X224A2`) so the caller never hand-codes them.
- *
- * **🩺 Known limitation, disclosed rather than changed: those three are
- * published errata guides, but they are neither the identifiers HIPAA
- * adopts at 45 CFR 162.1102 nor the ones payer companion guides commonly
- * require in ST-03 / GS-08** (CMS and several state Medicaid guides state
- * `005010X222A1` for Professional, `005010X223A2` for Institutional and
- * `005010X224A2` for Dental). **A partner that requires one of those will
- * reject a Professional or Institutional 837 this builder emits, and there
- * is currently no way for a caller to override the value.** Nothing here
- * was re-stamped on that evidence: which published guide identifier a
- * trading partner accepts is a partner fact, not a spec fact, and silently
- * changing bytes this library already emitted would break the partners it
- * works with today. `KNOWN-LIMITATIONS.md` carries this as an open
- * residual. The READ side is unaffected - `get837Claims` recognises all of
+ * fixes GS-01 to `"HC"`, and defaults the ST-03 / GS-08 reference to the
+ * variant's TR3 (`005010X222A2` / `X223A3` / `X224A2`) so the caller never
+ * has to hand-code it.
+ *
+ * **🩺 That default is not what every trading partner accepts, so
+ * {@link Build837EnvelopeSpec.implementationConventionReference} overrides
+ * it.** The three defaults are published errata guides, but they are
+ * neither the identifiers HIPAA adopts at 45 CFR 162.1102 nor the ones
+ * payer companion guides commonly require in ST-03 / GS-08 (CMS and several
+ * state Medicaid guides state `005010X222A1` for Professional and
+ * `005010X223A2` for Institutional). **A partner that requires one of those
+ * will reject a Professional or Institutional 837 built on the default**,
+ * and the override is how you send what your partner asked for. The default
+ * itself was deliberately NOT re-stamped: which published guide identifier
+ * a partner accepts is a partner fact rather than a spec fact, and changing
+ * bytes this library already emitted would break the partners it works with
+ * today. The READ side is unaffected - `get837Claims` recognises all of
  * these references.
  *
  * @example
@@ -5764,6 +5766,44 @@ interface Build837EnvelopeSpec {
     readonly groupControlNumber: string;
     /** ST-02 / SE-02 - transaction set control number. */
     readonly transactionSetControlNumber: string;
+    /**
+     * 🩺 ST-03 **and** GS-08 - the implementation convention reference this
+     * 837 declares. Default: the variant's TR3 (`005010X222A2` Professional,
+     * `005010X223A3` Institutional, `005010X224A2` Dental).
+     *
+     * **Set it to whatever your trading partner's companion guide requires**,
+     * for example `005010X222A1` on a professional claim to a payer that asks
+     * for it. Which published identifier a partner accepts is a partner fact,
+     * so this library will not choose for you: it defaults to a real published
+     * guide and gets out of the way. **One value is written to both elements**,
+     * because this builder has always written the same reference to ST-03 and
+     * GS-08 and nothing grounds a caller making them differ. That is a statement
+     * about the bytes this field emits, not about what each element may legally
+     * hold: GS-08 is data element 480 (`AN 1/12`) and ST-03 is element 1705
+     * (`AN 1/35`), and nothing here bounds the length.
+     *
+     * Refused, all `X12_837_BUILD_INVALID_SPEC`. An **empty** string, because a
+     * trailing empty element is dropped on emit, so it would delete ST-03 and
+     * GS-08 rather than send them empty. One carrying an **active delimiter or
+     * the release character**, because these two elements cannot carry it even
+     * escaped: the ST and GS segments are read by a splitter that is not
+     * release-aware, so the declaration would silently become two elements. And
+     * one **this library's own reader resolves to a different variant**
+     * (`005010X223A2` handed to `build837P`): the file would declare one variant
+     * and carry another's service segments, and `get837Claims` would then decode
+     * none of its service lines. Those are what this field adds, on top of the
+     * element-type guard every string slot already has, which refuses a
+     * non-string with the same code - no total is published. **Anything else is
+     * emitted as given** - the set of published errata is not provably
+     * exhaustive, so an identifier this library does not carry is the caller's
+     * call, not an error.
+     *
+     * 🩺 A guard on this element cannot make the element trustworthy. An active
+     * delimiter in a DIFFERENT envelope field splits its own segment and shifts
+     * every element after it, so ST-03 / GS-08 are then read out of a
+     * neighbour's slot. `KNOWN-LIMITATIONS.md` carries the measurement.
+     */
+    readonly implementationConventionReference?: string;
     /** ISA-05 - interchange sender qualifier. Default `"ZZ"`. */
     readonly senderQualifier?: string;
     /** ISA-07 - interchange receiver qualifier. Default `"ZZ"`. */
@@ -6475,8 +6515,9 @@ interface Build837Spec {
 
 /**
  * `build837P` / `build837I` / `build837D` - pure-function builders for a
- * 005010 837 Healthcare Claim (Professional `X222A2`, Institutional
- * `X223A3`, Dental `X224A2`). NEVER auto-sends, NEVER opens a socket, NEVER
+ * 005010 837 Healthcare Claim (Professional, Institutional, Dental; the
+ * ST-03 / GS-08 guide reference defaults to `X222A2` / `X223A3` / `X224A2`
+ * and the caller may state another). NEVER auto-sends, NEVER opens a socket, NEVER
  * touches the filesystem. The library mechanically emits the claim it is
  * told; a spec whose billing-provider → subscriber → (claims | patient)
  * tree cannot form a valid HL hierarchy is REFUSED via {@link
@@ -6505,7 +6546,9 @@ interface Build837Spec {
  */
 
 /**
- * `build837P` - assemble a 005010X222A2 Professional 837 around the spec.
+ * `build837P` - assemble a Professional 837 around the spec, declaring
+ * `005010X222A2` unless `envelope.implementationConventionReference` states
+ * the guide your trading partner requires.
  *
  * @example
  * ```ts
@@ -6537,8 +6580,10 @@ interface Build837Spec {
  */
 declare function build837P(spec: Build837Spec): X12Interchange;
 /**
- * `build837I` - assemble a 005010X223A3 Institutional 837 around the spec.
- * Service lines must be `variant: "I"` (SV2).
+ * `build837I` - assemble an Institutional 837 around the spec, declaring
+ * `005010X223A3` unless `envelope.implementationConventionReference` states
+ * the guide your trading partner requires. Service lines must be
+ * `variant: "I"` (SV2).
  *
  * @example
  * ```ts
@@ -6549,8 +6594,10 @@ declare function build837P(spec: Build837Spec): X12Interchange;
  */
 declare function build837I(spec: Build837Spec): X12Interchange;
 /**
- * `build837D` - assemble a 005010X224A2 Dental 837 around the spec. Service
- * lines must be `variant: "D"` (SV3); per-line tooth detail rides on TOO.
+ * `build837D` - assemble a Dental 837 around the spec, declaring
+ * `005010X224A2` unless `envelope.implementationConventionReference` states
+ * the guide your trading partner requires. Service lines must be
+ * `variant: "D"` (SV3); per-line tooth detail rides on TOO.
  *
  * @example
  * ```ts
@@ -12862,6 +12909,82 @@ declare function build999(spec: Build999Spec): X12Interchange;
  * library does NOT silently invent envelope bytes around it - the caller's
  * application boundary owns whether the TA1 is embedded in an outbound
  * interchange or sent as a standalone TA1-only interchange.
+ *
+ * ## 🩺 Why every element is released, and what that changed
+ *
+ * `raw` used to be `[...five caller values].join(elementSeparator)` with
+ * nothing in between, so a caller value carrying an active delimiter took
+ * a slot of its own and shifted every element after it down one. TA1-04 is
+ * the disposition and TA1-05 the note, so the shift landed the read on the
+ * wrong pair, and `parseTA1` narrows an out-of-enum TA1-04 to `R`:
+ * **an Accept this library emitted read back as a Reject**, with the TA1-01
+ * reassociation key merged into TA1-02 and `warnings: []` on every channel.
+ * The inverse is the less safe one and also existed: a `noteCode` of
+ * literally `"A"` (a value the type forbids and nothing checks at run time)
+ * shifted onto TA1-04 and made a **Reject read back as an Accept**, which a
+ * sender never resubmits against.
+ *
+ * The grounding is inside the package, not in a spec clause, which is the
+ * same tiebreak `X12-ENVELOPE-SPLITTER-NOT-RELEASE-AWARE` recorded: one
+ * function disagreed with itself. This module emitted bytes that this
+ * package's own reader decoded into a different disposition than the one
+ * the caller asked for, and every other builder already released the same
+ * class of element through the same helper.
+ *
+ * **It changes bytes, and that is the cost that kept it open for a slice.**
+ * A value containing none of the four delimiters or the release character
+ * is emitted byte-for-byte as before, which is every conformant TA1. A
+ * value containing one is now released, so its bytes differ from the ones
+ * `0.0.14` and earlier put on the wire. What that costs is stated outright
+ * below rather than argued away, and **without a total**: two drafts of this
+ * account published a closed one and both were refuted.
+ *
+ * - **The consumer predicate moves in BOTH directions.** Read the property
+ *   rather than a direction list: `parseTA1` of a `buildTA1` output now
+ *   reports the disposition and note the CALLER passed, where before it
+ *   reported whatever element the shift left in TA1-04. So
+ *   `ackCode === "R"` stops firing where an Accept had been shifted onto
+ *   it, and starts firing where a Reject had been shifted off it -
+ *   `interchangeTime: "12*A"` with `ackCode: "R"` read `"A"` before and
+ *   reads `"R"` here, every field a valid member of its union. What is
+ *   one-directional is the safety, which is a different statement.
+ * - **Only three values in the escaped set ever shifted the segment's own
+ *   element framing**: the element separator, the segment terminator, and
+ *   a `?` immediately before the separator. **`^` and `:` moved the
+ *   dot-path reader instead, and releasing them is a GAIN there.**
+ *   `getSegmentValue(ta1, "01")` answered `"0000"` before for a control
+ *   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.
+ * - **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
+ *   disposition stay correct, and this one regresses on BOTH kinds of
+ *   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 the release is scoped to the delimiter set the caller states through
+ * {@link BuildTA1Options} - see that interface for why guessing one is a
+ * value corruption rather than a safe default.
  */
 
 /**
@@ -12876,7 +12999,18 @@ declare function build999(spec: Build999Spec): X12Interchange;
  * - `ackCode === "A"` paired with `noteCode !== "000"` →
  *   {@link "./errors.js".ACK_BUILD_ERROR_CODES.X12_TA1_ACCEPT_WITH_NOTE}.
  *   Accept must mean accept. Use `E` (accept with errors) when the
- *   inbound had structural defects you elected to ignore.
+ *   inbound had structural defects you elected to ignore. This one runs
+ *   FIRST and its precedence is unchanged.
+ * - Any of the five element values that is not a `string` →
+ *   {@link "./errors.js".ACK_BUILD_ERROR_CODES.X12_ACK_INVALID_SPEC}. This
+ *   is not a bonus guard: releasing a value means routing it through
+ *   {@link "../../builder/caller-string.js".makeCallerEscaper}, and the
+ *   bare `escapeRelease` underneath it returns its empty accumulator for a
+ *   `number`, so escaping without the type check would have replaced the
+ *   shifted-element defect with a silently VANISHED TA1-01. **A number or
+ *   an `undefined` control number used to emit as `TA1*12345*…` (the
+ *   number surviving onto `elements`, in a `readonly string[]`) or
+ *   `TA1**250101*…`; both now refuse.**
  *
  * @param spec - The TA1 fields. `interchangeControlNumber` echoes the
  *               inbound ISA-13; `interchangeDate` / `interchangeTime` echo
@@ -12914,13 +13048,28 @@ declare function build999(spec: Build999Spec): X12Interchange;
  */
 declare function buildTA1(spec: BuildTA1Spec, options?: BuildTA1Options): Ta1Segment;
 /**
- * Options accepted by {@link buildTA1}. Both fields are optional - pass
- * none for the cosyte default envelope (`*` element separator). Override
- * only when the TA1 is being embedded in an outer envelope whose declared
- * delimiters differ from the cosyte default.
+ * Options accepted by {@link buildTA1}: the delimiter set the returned
+ * segment will be read against. Every field is optional and defaults to the
+ * cosyte parser archetype (`*` element, `^` repetition, `:` component, `~`
+ * segment), which is the same four `build999` takes on
+ * {@link "./types.js".Build999EnvelopeSpec}.
+ *
+ * **The three non-element fields exist for ESCAPING and nothing else.**
+ * `buildTA1` still emits no segment terminator, no repetition and no
+ * composite. It has to know them because a caller value carrying one of
+ * them has to be released, and because escaping a byte that is NOT a
+ * delimiter where the segment lands corrupts the value: `unescapeRelease`
+ * preserves `?X` verbatim for any `X` outside the declared set, so a value
+ * released against a guessed delimiter comes back carrying a stray `?`.
+ * **If you embed a TA1 in an envelope whose delimiters are not the
+ * archetype, state them here** - the defaults are an assumption this
+ * function cannot verify, exactly as they were before it escaped anything.
  */
 interface BuildTA1Options {
     readonly elementSeparator?: string;
+    readonly repetitionSeparator?: string;
+    readonly componentSeparator?: string;
+    readonly segmentTerminator?: string;
 }
 
 /**