@cosyte/x12 0.0.14 → 0.0.16

package/dist/index.cjs

@@ -47,6 +47,12 @@ var DELIMITER_POSITIONS = {
   component: 104,
   segment: 105
 };
+function isVisibleDelimiterChar(c) {
+  const code = c.charCodeAt(0);
+  if (code < 32 || code === 127) return false;
+  if (/\s/u.test(c)) return false;
+  return true;
+}
 function detectDelimiters(raw) {
   const fatalPosition = { segmentIndex: 0, interchangeIndex: 0 };
   const snip = snippet(raw);
@@ -70,19 +76,13 @@ function detectDelimiters(raw) {
   const repetition = raw.charAt(DELIMITER_POSITIONS.repetition);
   const component = raw.charAt(DELIMITER_POSITIONS.component);
   const segment = raw.charAt(DELIMITER_POSITIONS.segment);
-  const isValidDelimiterChar = (c) => {
-    const code = c.charCodeAt(0);
-    if (code < 32 || code === 127) return false;
-    if (/\s/u.test(c)) return false;
-    return true;
-  };
   for (const [name, ch] of [
     ["element", element],
     ["repetition", repetition],
     ["component", component],
     ["segment", segment]
   ]) {
-    if (!isValidDelimiterChar(ch)) {
+    if (!isVisibleDelimiterChar(ch)) {
       throw new X12ParseError(
         FATAL_CODES.X12_INVALID_DELIMITERS,
         `Delimiter "${name}" at ISA byte ${String(DELIMITER_POSITIONS[name] + 1)} is whitespace, control, or empty.`,
@@ -224,7 +224,7 @@ var WARNING_MESSAGES = {
   X12_MISSING_REQUIRED_LOOP_2000B: 'Missing required loop "2000B" (Subscriber HL): no Subscriber HL precedes the CLM.',
   X12_MISSING_REQUIRED_LOOP_2010BA: 'Missing required loop "2010BA" (Subscriber Name): no Subscriber Name follows the Subscriber HL.',
   X12_MISSING_REQUIRED_LOOP_2010BB: 'Missing required loop "2010BB" (Payer Name): no Payer Name follows the Subscriber HL.',
-  X12_837_UNKNOWN_VARIANT: "837 variant could not be resolved: ST-03's implementation convention reference is absent, empty, or not an 837 Technical Report Type 3 identifier this reader recognises, and no SVx service-line segment was present to fall back on. The set of references it recognises covers the professional, institutional and dental 837 guides HIPAA adopts at 45 CFR 162.1102 together with their published errata; it is NOT claimed to be exhaustive, and this message deliberately does not enumerate it, because a list here goes stale the moment a guide is added. A reference outside that set is not asserted to be invalid - all this code reports is that this reader could not turn it into a variant and had nothing to fall back on. The verbatim reference is preserved on the model; read it there rather than inferring what the sender meant.",
+  X12_837_UNKNOWN_VARIANT: "837 variant could not be resolved: ST-03's implementation convention reference is absent, empty, or not an 837 Technical Report Type 3 identifier this reader recognises, and no SVx service-line segment was present to fall back on. The set of references it recognises covers the professional, institutional and dental 837 guides HIPAA adopts at 45 CFR 162.1102 together with their published errata; it is NOT claimed to be exhaustive, and this message deliberately does not enumerate it, because a list here goes stale the moment a guide is added. A reference outside that set is not asserted to be invalid - all this code reports is that this reader could not turn it into a variant and had nothing to fall back on.",
   X12_837_AMBIGUOUS_VARIANT: "837 variant resolved from a service segment while the transaction body carries service segments of more than one variant: no caller `type` option was supplied and ST-03's implementation convention reference is absent, empty, or not an 837 Technical Report Type 3 identifier this reader recognises, so this reader fell back to the FIRST SV1 / SV2 / SV3 in the body, and a later one names a different variant. `submission.variant` is therefore a guess between contradictory evidence, and every claim and service line in the submission was read against it. Which service segment is the stray one is NOT decided here and is not derivable from the TR3s: this reader cannot tell a stray service segment from a conformant one, and the fallback takes the first regardless of whether any Loop 2400 was open at it, so an orphan segment decides the variant like any other. Read the bound literally, as a property of the RESOLUTION rather than of the document: this reports the fallback's own ambiguity, so a caller-supplied `type`, or an ST-03 this reader does turn into a variant, means no guess was made and this code is NOT raised however mixed the body is. Whatever else this reader raised on a document that reaches this code, it still raises, at the same position, and this one is added beside them. It is NOT a list of what else you will see, and it does not promise that any particular loss on such a document is reported at all. Re-read with the `type` option to decode the document against a variant you trust. The verbatim segments are preserved on the transaction set; read them there before acting on the submission's type.",
   X12_UNKNOWN_CLAIM_STATUS_CATEGORY: "Unknown claim status category (CSCC): the STC composite's first component is outside the bundled snapshot. The verbatim code is preserved on the status; only its description is unavailable.",
   X12_UNKNOWN_CLAIM_STATUS: "Unknown claim status code (CSC): the STC composite's second component is outside the bundled snapshot. The verbatim code is preserved on the status; only its description is unavailable.",
@@ -868,8 +868,11 @@ function boundSegmentId(first) {
   return SEGMENT_ID_SHAPE_RE.test(first) ? first : NON_SPEC_SEGMENT_ID;
 }
 function decodeSegment(raw, delimiters, emit, position) {
-  const elements = Object.freeze(splitWithRelease(raw, delimiters.element));
-  if (raw.length > 0 && raw.endsWith(RELEASE_CHAR)) {
+  const degenerate = delimiters.element === RELEASE_CHAR;
+  const elements = Object.freeze(
+    degenerate ? raw.split(delimiters.element) : splitWithRelease(raw, delimiters.element)
+  );
+  if (!degenerate && raw.length > 0 && raw.endsWith(RELEASE_CHAR)) {
     let trailingRun = 0;
     for (let j = raw.length - 1; j >= 0 && raw.charAt(j) === RELEASE_CHAR; j -= 1) trailingRun += 1;
     if (trailingRun % 2 === 1) {
@@ -1097,7 +1100,10 @@ function splitSegments(text, start, delimiters) {
   return { segments, endIndex: lastEnd };
 }
 function splitElements(segment, delimiters) {
-  return Object.freeze(segment.split(delimiters.element));
+  if (delimiters.element === RELEASE_CHAR) {
+    return Object.freeze(segment.split(delimiters.element));
+  }
+  return Object.freeze(splitWithRelease(segment, delimiters.element));
 }
 function el(elements, index) {
   return elements[index] ?? "";
@@ -2703,10 +2709,70 @@ function requireCallerString(value, at, refuse) {
     `${at}: every element value must be a string, but received ${describeCallerValue(value)}. Values are never coerced - a JavaScript number cannot carry a leading-zero identifier, so converting here could emit a different value than the caller sent. Convert at the call site.`
   );
 }
+var DELIMITER_ROLES = [
+  ["element", "element separator"],
+  ["repetition", "repetition separator"],
+  ["component", "component separator"],
+  ["segment", "segment terminator"]
+];
+function requireEscapableDelimiters(delimiters, at, refuse) {
+  const degenerate = DELIMITER_ROLES.filter(([role]) => delimiters[role] === RELEASE_CHAR).map(
+    ([, name]) => name
+  );
+  if (degenerate.length === 0) return;
+  const roles = degenerate.length === 1 ? `the ${degenerate[0] ?? ""}` : `the ${degenerate.slice(0, -1).join(", the ")} and the ${degenerate[degenerate.length - 1] ?? ""}`;
+  refuse(
+    `${at}: "${RELEASE_CHAR}" is the X12 release character and cannot also be ${roles}. An escape is written by prefixing "${RELEASE_CHAR}" to the byte it protects, so on this set the protection is emitted as structure; and a composite or a repetition joined with "${RELEASE_CHAR}" is emitted as an escape. Neither reads back, and no element value avoids it. Declare a delimiter set in which no role is "${RELEASE_CHAR}".`
+  );
+}
+function requireWellShapedDelimiters(delimiters, at, refuse) {
+  const REMEDY = `A delimiter occupies ONE fixed position of the ISA (ISA-11, ISA-16 and the position after it), so this set cannot be transmitted and this library's own parser would reject a document declaring it. Declare four distinct, visible, single-character delimiters.`;
+  for (const [role, name] of DELIMITER_ROLES) {
+    const value = delimiters[role];
+    if (typeof value !== "string") {
+      refuse(
+        `${at}: the ${name} must be a string, but received ${describeCallerValue(value)}. Values are never coerced - a coerced delimiter frames the document while the release escape still compares against what you passed, so no element value is protected from it. ${REMEDY}`
+      );
+    }
+    if (value.length !== 1) {
+      refuse(
+        `${at}: the ${name} must be exactly one character, but the declared value is ${value.length === 0 ? "empty" : `${String(value.length)} characters long`}. ${REMEDY}`
+      );
+    }
+    if (!isVisibleDelimiterChar(value)) {
+      refuse(
+        `${at}: the ${name} must be a visible character, but the declared value is whitespace or a control character. ${REMEDY}`
+      );
+    }
+  }
+  for (const [i, [role, name]] of DELIMITER_ROLES.entries()) {
+    const earlier = DELIMITER_ROLES.slice(0, i).find(([r]) => delimiters[r] === delimiters[role]);
+    if (earlier !== void 0) {
+      refuse(
+        `${at}: the ${name} and the ${earlier[1]} are the same character. A reader cannot tell which role a character is playing. ${REMEDY}`
+      );
+    }
+  }
+}
 function makeCallerEscaper(delimiters, at, refuse) {
+  requireEscapableDelimiters(delimiters, at, refuse);
+  requireWellShapedDelimiters(delimiters, at, refuse);
   return (value) => escapeRelease(requireCallerString(value, at, refuse), delimiters);
 }
 
+// src/builder/caller-control-number.ts
+function requireControlNumber(value, slot, field, at, refuse) {
+  if (typeof value !== "string") {
+    refuse(
+      `${at}: ${field} must be a string, but received ${describeCallerValue(value)}. ${slot} is a required control number and this builder never coerces one, so nothing is emitted. Convert ${field} at the call site.`
+    );
+  }
+  if (value !== "") return value;
+  refuse(
+    `${at}: ${field} is empty. ${slot} is a required control number and this builder never invents one, so nothing is emitted. Supply ${field}.`
+  );
+}
+
 // src/transactions/remit/build-835.ts
 function refuseSpec(message) {
   throw new Remit835BuildError(REMIT_835_BUILD_ERROR_CODES.X12_835_BUILD_INVALID_SPEC, message);
@@ -2751,6 +2817,27 @@ function build835(spec) {
   const senderQualifier = envelope.senderQualifier ?? "ZZ";
   const receiverQualifier = envelope.receiverQualifier ?? "ZZ";
   const usageIndicator = envelope.usageIndicator ?? "P";
+  requireControlNumber(
+    envelope.interchangeControlNumber,
+    "ISA-13 / IEA-02",
+    "interchangeControlNumber",
+    "build835",
+    refuseSpec
+  );
+  requireControlNumber(
+    envelope.groupControlNumber,
+    "GS-06 / GE-02",
+    "groupControlNumber",
+    "build835",
+    refuseSpec
+  );
+  requireControlNumber(
+    envelope.transactionSetControlNumber,
+    "ST-02 / SE-02",
+    "transactionSetControlNumber",
+    "build835",
+    refuseSpec
+  );
   const interchangeControlNumber = padControl(envelope.interchangeControlNumber, 9);
   const isa = [
     "ISA",
@@ -3328,6 +3415,14 @@ function wireLookup(entries) {
   return Object.freeze(table);
 }
 
+// src/transactions/shared/st03.ts
+var noopWarningSink = (_w) => {
+};
+function decodeSt03(raw, delimiters, position) {
+  if (raw === void 0) return void 0;
+  return unescapeRelease(raw, delimiters, noopWarningSink, position);
+}
+
 // src/transactions/claim/address-segments.ts
 function emitsStreetLines(address) {
   return address.lines.length > 0;
@@ -3386,9 +3481,14 @@ function get837Claims(delimiters, tx, opts) {
   if (tx.st.elements[1] !== "837") return void 0;
   const warnings = [];
   const body = tx.se === void 0 ? tx.segments.slice(1) : tx.segments.slice(1, -1);
-  const implementationConventionReference = tx.st.elements[3];
+  const implementationConventionReferenceRaw = tx.st.elements[3];
+  const implementationConventionReference = decodeSt03(
+    implementationConventionReferenceRaw,
+    delimiters,
+    { segmentIndex: 0, transactionIndex: 0 }
+  );
   const explicitType = opts?.type;
-  const variantFromIcr = implementationConventionReference !== void 0 && implementationConventionReference !== "" ? VARIANT_BY_ICR[implementationConventionReference] : void 0;
+  const variantFromIcr = implementationConventionReferenceRaw !== void 0 && implementationConventionReferenceRaw !== "" ? VARIANT_BY_ICR[implementationConventionReferenceRaw] : void 0;
   let variantFromSegment;
   let serviceSegmentVariantsConflict = false;
   if (explicitType === void 0 && variantFromIcr === void 0) {
@@ -4569,6 +4669,29 @@ var VERSION_BY_VARIANT = {
   I: "005010X223A3",
   D: "005010X224A2"
 };
+function resolveVersionRelease(variant, reference, esc) {
+  if (reference === void 0) return VERSION_BY_VARIANT[variant];
+  if (reference === "") {
+    throw new Claim837BuildError(
+      CLAIM_837_BUILD_ERROR_CODES.X12_837_BUILD_INVALID_SPEC,
+      "build837: envelope.implementationConventionReference is empty. ST-03 and GS-08 are required elements and a trailing empty element is not emitted, so an empty reference would remove them rather than send them empty. Omit the field to take the builder's default."
+    );
+  }
+  if (esc(reference) !== reference) {
+    throw new Claim837BuildError(
+      CLAIM_837_BUILD_ERROR_CODES.X12_837_BUILD_INVALID_SPEC,
+      "build837: envelope.implementationConventionReference carries an active delimiter or the release character. Escaping does not make it safe here: the ST and GS segments are read by a splitter that is not release-aware, so a released delimiter still splits the segment and the declaration silently becomes two elements. State a reference that carries neither, or choose different delimiters."
+    );
+  }
+  const named = Object.hasOwn(VARIANT_BY_ICR, reference) ? VARIANT_BY_ICR[reference] : void 0;
+  if (named !== void 0 && named !== variant) {
+    throw new Claim837BuildError(
+      CLAIM_837_BUILD_ERROR_CODES.X12_837_BUILD_INVALID_SPEC,
+      `build837: envelope.implementationConventionReference names an implementation guide this library reads as a DIFFERENT 837 variant, but this is build837${variant}. The emitted file would declare one variant and carry another's service segments, and this library's own reader would then decode none of its service lines. State a reference for the ${variant} 837, or build with the entry point that matches the reference.`
+    );
+  }
+  return reference;
+}
 var X12_837_FUNCTIONAL_ID = "HC";
 var X12_AGENCY_CODE2 = "X";
 var HL_LEVEL = { BILLING: "20", SUBSCRIBER: "22", PATIENT: "23" };
@@ -4583,7 +4706,6 @@ function build837D(spec) {
 }
 function buildClaim837(variant, spec) {
   const { envelope } = spec;
-  const versionRelease = VERSION_BY_VARIANT[variant];
   enforceStructuralSpec2(variant, spec);
   const elementSeparator = envelope.elementSeparator ?? "*";
   const repetitionSeparator = envelope.repetitionSeparator ?? "^";
@@ -4609,9 +4731,35 @@ function buildClaim837(variant, spec) {
     return escaped.slice(0, end).join(componentSeparator);
   };
   const ctx = { seg, esc, comp };
+  const versionRelease = resolveVersionRelease(
+    variant,
+    envelope.implementationConventionReference,
+    esc
+  );
   const senderQualifier = envelope.senderQualifier ?? "ZZ";
   const receiverQualifier = envelope.receiverQualifier ?? "ZZ";
   const usageIndicator = envelope.usageIndicator ?? "P";
+  requireControlNumber(
+    envelope.interchangeControlNumber,
+    "ISA-13 / IEA-02",
+    "interchangeControlNumber",
+    "build837",
+    refuseSpec2
+  );
+  requireControlNumber(
+    envelope.groupControlNumber,
+    "GS-06 / GE-02",
+    "groupControlNumber",
+    "build837",
+    refuseSpec2
+  );
+  requireControlNumber(
+    envelope.transactionSetControlNumber,
+    "ST-02 / SE-02",
+    "transactionSetControlNumber",
+    "build837",
+    refuseSpec2
+  );
   const interchangeControlNumber = padControl2(envelope.interchangeControlNumber, 9);
   const isa = [
     "ISA",
@@ -5783,6 +5931,27 @@ function build271(spec) {
   const senderQualifier = envelope.senderQualifier ?? "ZZ";
   const receiverQualifier = envelope.receiverQualifier ?? "ZZ";
   const usageIndicator = envelope.usageIndicator ?? "P";
+  requireControlNumber(
+    envelope.interchangeControlNumber,
+    "ISA-13 / IEA-02",
+    "interchangeControlNumber",
+    "build271",
+    refuseSpec3
+  );
+  requireControlNumber(
+    envelope.groupControlNumber,
+    "GS-06 / GE-02",
+    "groupControlNumber",
+    "build271",
+    refuseSpec3
+  );
+  requireControlNumber(
+    envelope.transactionSetControlNumber,
+    "ST-02 / SE-02",
+    "transactionSetControlNumber",
+    "build271",
+    refuseSpec3
+  );
   const interchangeControlNumber = padControl3(envelope.interchangeControlNumber, 9);
   const isa = [
     "ISA",
@@ -6153,8 +6322,13 @@ function get277CADisposition(delimiters, tx) {
 function walk277(delimiters, tx) {
   const warnings = [];
   const body = tx.se === void 0 ? tx.segments.slice(1) : tx.segments.slice(1, -1);
-  const implementationConventionReference = tx.st.elements[3];
-  const transactionType = implementationConventionReference === ICR_277CA ? "claim-acknowledgment" : "claim-status";
+  const implementationConventionReferenceRaw = tx.st.elements[3];
+  const implementationConventionReference = decodeSt03(
+    implementationConventionReferenceRaw,
+    delimiters,
+    { segmentIndex: 0, transactionIndex: 0 }
+  );
+  const transactionType = implementationConventionReferenceRaw === ICR_277CA ? "claim-acknowledgment" : "claim-status";
   const hierarchies = [];
   const hlIndex = /* @__PURE__ */ new Map();
   const claims = [];
@@ -6509,6 +6683,27 @@ function buildClaimStatus(version, spec) {
   const senderQualifier = envelope.senderQualifier ?? "ZZ";
   const receiverQualifier = envelope.receiverQualifier ?? "ZZ";
   const usageIndicator = envelope.usageIndicator ?? "P";
+  requireControlNumber(
+    envelope.interchangeControlNumber,
+    "ISA-13 / IEA-02",
+    "interchangeControlNumber",
+    "build277",
+    refuseSpec4
+  );
+  requireControlNumber(
+    envelope.groupControlNumber,
+    "GS-06 / GE-02",
+    "groupControlNumber",
+    "build277",
+    refuseSpec4
+  );
+  requireControlNumber(
+    envelope.transactionSetControlNumber,
+    "ST-02 / SE-02",
+    "transactionSetControlNumber",
+    "build277",
+    refuseSpec4
+  );
   const interchangeControlNumber = padControl4(envelope.interchangeControlNumber, 9);
   const isa = [
     "ISA",
@@ -7300,6 +7495,27 @@ function build820(spec) {
   const senderQualifier = envelope.senderQualifier ?? "ZZ";
   const receiverQualifier = envelope.receiverQualifier ?? "ZZ";
   const usageIndicator = envelope.usageIndicator ?? "P";
+  requireControlNumber(
+    envelope.interchangeControlNumber,
+    "ISA-13 / IEA-02",
+    "interchangeControlNumber",
+    "build820",
+    refuseSpec5
+  );
+  requireControlNumber(
+    envelope.groupControlNumber,
+    "GS-06 / GE-02",
+    "groupControlNumber",
+    "build820",
+    refuseSpec5
+  );
+  requireControlNumber(
+    envelope.transactionSetControlNumber,
+    "ST-02 / SE-02",
+    "transactionSetControlNumber",
+    "build820",
+    refuseSpec5
+  );
   const interchangeControlNumber = padControl5(envelope.interchangeControlNumber, 9);
   const isa = [
     "ISA",
@@ -8007,6 +8223,27 @@ function build834(spec) {
   const senderQualifier = envelope.senderQualifier ?? "ZZ";
   const receiverQualifier = envelope.receiverQualifier ?? "ZZ";
   const usageIndicator = envelope.usageIndicator ?? "P";
+  requireControlNumber(
+    envelope.interchangeControlNumber,
+    "ISA-13 / IEA-02",
+    "interchangeControlNumber",
+    "build834",
+    refuseSpec6
+  );
+  requireControlNumber(
+    envelope.groupControlNumber,
+    "GS-06 / GE-02",
+    "groupControlNumber",
+    "build834",
+    refuseSpec6
+  );
+  requireControlNumber(
+    envelope.transactionSetControlNumber,
+    "ST-02 / SE-02",
+    "transactionSetControlNumber",
+    "build834",
+    refuseSpec6
+  );
   const interchangeControlNumber = padControl6(envelope.interchangeControlNumber, 9);
   const isa = [
     "ISA",
@@ -8459,7 +8696,10 @@ function walk278(delimiters, tx, direction) {
     }
   }
   flushReview();
-  const icr = tx.st.elements[3];
+  const icr = decodeSt03(tx.st.elements[3], delimiters, {
+    segmentIndex: 0,
+    transactionIndex: 0
+  });
   return Object.freeze({
     direction,
     implementationConventionReference: icr === void 0 || icr === "" ? void 0 : icr,
@@ -8683,6 +8923,27 @@ function buildServicesReview(version, direction, spec) {
   const senderQualifier = envelope.senderQualifier ?? "ZZ";
   const receiverQualifier = envelope.receiverQualifier ?? "ZZ";
   const usageIndicator = envelope.usageIndicator ?? "P";
+  requireControlNumber(
+    envelope.interchangeControlNumber,
+    "ISA-13 / IEA-02",
+    "interchangeControlNumber",
+    "build278",
+    refuseSpec7
+  );
+  requireControlNumber(
+    envelope.groupControlNumber,
+    "GS-06 / GE-02",
+    "groupControlNumber",
+    "build278",
+    refuseSpec7
+  );
+  requireControlNumber(
+    envelope.transactionSetControlNumber,
+    "ST-02 / SE-02",
+    "transactionSetControlNumber",
+    "build278",
+    refuseSpec7
+  );
   const interchangeControlNumber = padControl7(envelope.interchangeControlNumber, 9);
   const isa = [
     "ISA",
@@ -9390,11 +9651,12 @@ function parseTA1(interchange) {
   const ta1 = interchange.ta1Segments[0];
   if (ta1 === void 0) return void 0;
   const elements = ta1.elements;
-  const interchangeControlNumber = elements[1] ?? "";
-  const interchangeDate = elements[2] ?? "";
-  const interchangeTime = elements[3] ?? "";
-  const ackCodeRaw = elements[4] ?? "";
-  const noteCodeRaw = elements[5] ?? "";
+  const value = (index) => unescapeRelease(elements[index] ?? "", interchange.delimiters, noop3, { segmentIndex: 0 });
+  const interchangeControlNumber = value(1);
+  const interchangeDate = value(2);
+  const interchangeTime = value(3);
+  const ackCodeRaw = value(4);
+  const noteCodeRaw = value(5);
   const ackCode = narrowAckCode(ackCodeRaw) ?? TA1_ACK_CODES.R;
   const noteCode = narrowNoteCode(noteCodeRaw);
   return Object.freeze({
@@ -9407,6 +9669,8 @@ function parseTA1(interchange) {
     raw: ta1
   });
 }
+var noop3 = (_w) => {
+};
 function narrowAckCode(value) {
   switch (value) {
     case "A":
@@ -9448,6 +9712,27 @@ function build999(spec) {
   const senderQualifier = envelope.senderQualifier ?? "ZZ";
   const receiverQualifier = envelope.receiverQualifier ?? "ZZ";
   const usageIndicator = envelope.usageIndicator ?? "P";
+  requireControlNumber(
+    envelope.interchangeControlNumber,
+    "ISA-13 / IEA-02",
+    "interchangeControlNumber",
+    "build999",
+    refuseSpec8
+  );
+  requireControlNumber(
+    envelope.groupControlNumber,
+    "GS-06 / GE-02",
+    "groupControlNumber",
+    "build999",
+    refuseSpec8
+  );
+  requireControlNumber(
+    envelope.transactionSetControlNumber,
+    "ST-02 / SE-02",
+    "transactionSetControlNumber",
+    "build999",
+    refuseSpec8
+  );
   const interchangeControlNumber = padControl8(envelope.interchangeControlNumber, 9);
   const isa = [
     "ISA",
@@ -9516,6 +9801,13 @@ function build999(spec) {
     elementSeparator,
     segmentTerminator
   );
+  requireControlNumber(
+    functionalGroup.groupControlNumber,
+    "AK1-02",
+    "functionalGroup.groupControlNumber",
+    "build999",
+    refuseSpec8
+  );
   const ak1 = joinSeg(
     [
       "AK1",
@@ -9622,6 +9914,13 @@ function responseHasAnyError(response) {
   return false;
 }
 function buildAk2(response, esc, elementSeparator, segmentTerminator) {
+  requireControlNumber(
+    response.transactionSetControlNumber,
+    "AK2-02",
+    "transactionResponses[].transactionSetControlNumber",
+    "build999",
+    refuseSpec8
+  );
   const parts = [
     "AK2",
     esc(response.transactionSetIdCode),
@@ -9733,18 +10032,49 @@ function expandYY8(yymmdd) {
 // src/transactions/ack/build-ta1.ts
 function buildTA1(spec, options = {}) {
   enforceAcceptIsClean2(spec);
-  const elementSeparator = options.elementSeparator ?? "*";
+  const delimiters = {
+    element: options.elementSeparator ?? "*",
+    repetition: options.repetitionSeparator ?? "^",
+    component: options.componentSeparator ?? ":",
+    segment: options.segmentTerminator ?? "~"
+  };
+  const esc = makeCallerEscaper(delimiters, "buildTA1", refuseSpec9);
+  requireControlNumber(
+    spec.interchangeControlNumber,
+    "TA1-01",
+    "interchangeControlNumber",
+    "buildTA1",
+    refuseSpec9
+  );
+  const interchangeControlNumber = esc(spec.interchangeControlNumber);
+  const interchangeDate = esc(spec.interchangeDate);
+  const interchangeTime = esc(spec.interchangeTime);
+  const ackCode = esc(spec.ackCode);
+  const noteCode = esc(spec.noteCode);
+  requireTa1Element(interchangeDate, "TA1-02", "interchangeDate");
+  requireTa1Element(interchangeTime, "TA1-03", "interchangeTime");
+  requireTa1Element(ackCode, "TA1-04", "ackCode");
+  requireTa1Element(noteCode, "TA1-05", "noteCode");
   const elements = Object.freeze([
     "TA1",
-    spec.interchangeControlNumber,
-    spec.interchangeDate,
-    spec.interchangeTime,
-    spec.ackCode,
-    spec.noteCode
+    interchangeControlNumber,
+    interchangeDate,
+    interchangeTime,
+    ackCode,
+    noteCode
   ]);
-  const raw = elements.join(elementSeparator);
+  const raw = elements.join(delimiters.element);
   return Object.freeze({ raw, elements });
 }
+function refuseSpec9(message) {
+  throw new AckBuildError(ACK_BUILD_ERROR_CODES.X12_ACK_INVALID_SPEC, message);
+}
+function requireTa1Element(emitted, slot, field) {
+  if (emitted !== "") return;
+  refuseSpec9(
+    `buildTA1: ${field} is empty. ${slot} is a required element and this builder never invents one, so nothing is emitted. Supply ${field}.`
+  );
+}
 function enforceAcceptIsClean2(spec) {
   if (spec.ackCode === TA1_ACK_CODES.A && spec.noteCode !== "000") {
     throw new AckBuildError(
@@ -9933,7 +10263,7 @@ var X12BuildError = class extends Error {
 };
 
 // src/builder/build-interchange.ts
-function refuseSpec9(message) {
+function refuseSpec10(message) {
   throw new X12BuildError(X12_BUILD_ERROR_CODES.X12_BUILD_INVALID_SPEC, message);
 }
 function buildInterchange(spec) {
@@ -9947,11 +10277,18 @@ function buildInterchange(spec) {
     component: componentSeparator,
     segment: segmentTerminator
   };
-  const esc = makeCallerEscaper(delimiters, "buildInterchange", refuseSpec9);
+  const esc = makeCallerEscaper(delimiters, "buildInterchange", refuseSpec10);
   const senderQualifier = spec.senderQualifier ?? "ZZ";
   const receiverQualifier = spec.receiverQualifier ?? "ZZ";
   const usageIndicator = spec.usageIndicator ?? "P";
   const version = spec.version ?? "00501";
+  requireControlNumber(
+    spec.interchangeControlNumber,
+    "ISA-13 / IEA-02",
+    "interchangeControlNumber",
+    "buildInterchange",
+    refuseSpec10
+  );
   const interchangeControlNumber = padControl9(spec.interchangeControlNumber, 9);
   const isa = [
     "ISA",
@@ -10001,23 +10338,32 @@ function buildInterchange(spec) {
   return parseX12(raw);
 }
 function buildGroup(group, spec, esc, elementSeparator, segmentTerminator) {
+  requireControlNumber(
+    group.groupControlNumber,
+    "GS-06 / GE-02",
+    "groupControlNumber",
+    "buildInterchange",
+    refuseSpec10
+  );
   const applicationSenderCode = group.applicationSenderCode ?? spec.senderId;
   const applicationReceiverCode = group.applicationReceiverCode ?? spec.receiverId;
   const groupDate = group.groupDate ?? expandYY9(spec.interchangeDate);
   const groupTime = group.groupTime ?? spec.interchangeTime;
   const responsibleAgencyCode = group.responsibleAgencyCode ?? "X";
+  const gsParts = [
+    "GS",
+    group.functionalIdCode,
+    applicationSenderCode,
+    applicationReceiverCode,
+    groupDate,
+    groupTime,
+    group.groupControlNumber,
+    responsibleAgencyCode,
+    group.versionRelease
+  ];
+  requireCallerSegment(gsParts, "buildInterchange", refuseSpec10);
   const gs = joinSeg2(
-    [
-      "GS",
-      esc(group.functionalIdCode),
-      esc(applicationSenderCode),
-      esc(applicationReceiverCode),
-      groupDate,
-      groupTime,
-      esc(group.groupControlNumber),
-      responsibleAgencyCode,
-      esc(group.versionRelease)
-    ],
+    gsParts.map((value, index) => index === 0 ? value : esc(value)),
     elementSeparator,
     segmentTerminator
   );
@@ -10033,6 +10379,13 @@ function buildGroup(group, spec, esc, elementSeparator, segmentTerminator) {
   return gs + transactions + ge;
 }
 function buildTransaction(tx, esc, elementSeparator, segmentTerminator) {
+  requireControlNumber(
+    tx.transactionSetControlNumber,
+    "ST-02 / SE-02",
+    "transactionSetControlNumber",
+    "buildInterchange",
+    refuseSpec10
+  );
   const stParts = ["ST", esc(tx.transactionSetIdCode), esc(tx.transactionSetControlNumber)];
   if (tx.implementationConventionReference !== void 0) {
     stParts.push(esc(tx.implementationConventionReference));
@@ -10061,7 +10414,7 @@ function buildTransaction(tx, esc, elementSeparator, segmentTerminator) {
   return st + bodySegments + se;
 }
 function joinSeg2(parts, elementSeparator, segmentTerminator) {
-  requireCallerSegment(parts, "buildInterchange", refuseSpec9);
+  requireCallerSegment(parts, "buildInterchange", refuseSpec10);
   return parts.join(elementSeparator) + segmentTerminator;
 }
 function pad9(value, width) {
@@ -10370,7 +10723,7 @@ var profiles = Object.freeze({
 });
 
 // src/index.ts
-var VERSION = "0.0.14";
+var VERSION = "0.0.16";
 
 exports.ACK_BUILD_ERROR_CODES = ACK_BUILD_ERROR_CODES;
 exports.ALL_WARNING_MESSAGES = ALL_WARNING_MESSAGES;