@cosyte/x12 0.0.7 → 0.0.9

package/CHANGELOG.md

@@ -9,6 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- **`requireCallerString` / `makeCallerEscaper`** (internal), the single route a caller-supplied
+  element value takes **through a builder's `esc` helper**. Read that scope literally: it is not
+  every route into an emitted segment, and the `### Fixed` entry below says which positions bypass
+  it. All nine builders now build their `esc` helper through
+  `makeCallerEscaper`, which type-checks the value before escaping and refuses through the calling
+  module's own `refuse` callback, so a wrong-typed element draws that builder's existing typed error
+  and code rather than a new shared one. `buildInterchange`, `build999`, `build271` and `build278`
+  each gained the one-line `refuseSpec` thrower they needed for it.
+
 - **`renderCallerJson`** (internal), the type-preserving half of the caller-value bound, held to the
   same `BUILD_REFUSAL_VALUE_MAX_RENDERED` ceiling as `renderCallerValue`. It exists because
   `defineProfile()` reports a bad `name` / `id` / `effect` / `fixture` with `JSON.stringify`, and that
@@ -42,6 +51,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   a warning `message` is a frozen-registry lookup with positional metadata only, but an orphan is
   document content, verbatim, exactly like `tx.rawSegments`. Log `context` and `segmentIndex`.
 
+### Changed
+
+- **`escapeRelease` now throws `TypeError` on a non-string instead of returning `""`.** Previously it
+  gave three different wrong answers depending on what arrived: a number, a boolean or a plain object
+  returned the empty string silently; `null` and `undefined` threw on the property read; an array or
+  an array-like threw on `charAt`. All three now terminate the same way. A `TypeError` rather than a
+  code-tagged library error is deliberate: it is a pure text utility with no spec, element or caller
+  context to name. Nothing inside the library can reach it, because all nine builders refuse
+  first with their own typed, code-tagged error.
+
 ### Security
 
 - **The PHI scanner refuses an in-scope entry that is not a regular file, on both of its enumerating
@@ -111,6 +130,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- **A number passed where a builder's types say `string` no longer emits an EMPTY element. It is now
+  REFUSED, and it is deliberately not coerced.** `escapeRelease` opened with
+  `if (value.length === 0) return value;` and then looped to `value.length`. On a number `.length` is
+  `undefined`, so the early return did not fire, `i < undefined` was false, the loop body never ran,
+  and the function returned its empty accumulator. **The value vanished with no warning and no
+  error.** The types say `string`, so a TypeScript caller could not reach it; a JavaScript or
+  JSON-driven caller could, and `@cosyte/cli` is such a caller.
+
+  Measured at `0.0.8` on an otherwise valid `build835` spec with only `patientControlNumber` changed:
+  `CLP**1*500.00*450.00*50.00*MB*ICN-9001*11::1`, `ix.warnings.length === 0`, and a frozen interchange
+  that looks successful. CLP-01 is required by TR3 005010X221A1 Loop 2100 and is the key that
+  reassociates the remittance back to the 837's CLM-01. The builder's own
+  `patientControlNumber === ""` guard did not catch it, because the value was not yet a string when it
+  was checked.
+
+  **The same one line reached every escaped slot in all nine builders**, including the 837's own
+  CLM-01, the other end of that reassociation link. Measured at base by driving the shipped table
+  against a `143a6ea` worktree, one element each: `BPR*A1*450.00` became `BPR**450.00`,
+  `AK2*837*A1*005010X222A2` became `AK2*837**005010X222A2`, `NM1*IL*1*DOE*JANE****34*A1` became
+  `NM1*IL*1*DOE*JANE****34`, `ENT**2J*34*A1` became `ENT**2J*34`, `NM1*1P*2*A1` became `NM1*1P*2`,
+  `UM*HS*I*A1` became `UM*HS*I`, and `CLM*A1*150.00***11:B:1*Y*A*Y*Y` became
+  `CLM**150.00***11:B:1*Y*A*Y*Y`. Where the dropped element was trailing, the trailing-empty trim
+  removed it outright, so it is not even positionally recoverable.
+
+  **It refuses rather than coercing, and that choice is the substance of the fix.** Coercion would
+  mint a _different_ identifier: a JSON payload that carried `"0012345"` as a number has already lost
+  the leading zeros, so `String(12345)` emits a well-formed identifier that is not the one the caller
+  sent, and a remittance that reassociates to the wrong claim is worse than one that fails to
+  reassociate at all. `String(1e21)` is `"1e+21"`, `String(NaN)` is `"NaN"` and `String(0.1 + 0.2)` is
+  `"0.30000000000000004"`, none valid in an `AN`, `ID` or `Nn` element, and `X12Decimal` is already
+  the sanctioned route for numeric content. No working caller is broken, because the numeric path did
+  not work; it silently lost the field. The refusal message says why, so a caller is not nudged
+  straight into `String(value)` at the wrong boundary.
+
+  This is deliberately the OPPOSITE answer to `renderCallerValue`, which coerces for the same caller
+  mistake. A refusal message that throws replaces a typed, code-tagged error with an uncaught
+  `TypeError`, so its duty is to survive anything; an emitted document's duty is to invent nothing.
+
+  **The guard is on values routed through the escape helper, and not every element position goes
+  through it.** All of what follows is pre-existing, measured, unchanged here and disclosed in
+  `KNOWN-LIMITATIONS.md`. **36 `esc` slots read `.toString()` off what the types say is an
+  `X12Decimal`**, so a raw number arrives already a string and is passed through: a
+  `patientResponsibilityAmount` of `0.1 + 0.2` still emits `…*0.30000000000000004*…`, `1e21` still
+  emits `…*1e+21*…` and `NaN` still emits `…*NaN*…`, each with zero warnings, which are the exact
+  three renderings this entry names as disqualifying, and an 837 service-line `units` reaches SV1-04
+  the same way. **That is a set of examples too, not a count** - a draft of this entry said the class
+  was exactly 36 slots and closed, and adversarial review measured it open. **Some string-typed
+  positions never call the escape helper at all** and emit a
+  number, or an unescaped delimiter, verbatim: the 999's `groupControlNumber` (GS-06 / GE-02),
+  `transactionSetControlNumber` (ST-02 / SE-02) and `disposition` (AK9-01 and IK5-01), the 278's
+  `levelCode` (HL-03), `groupDate` / `groupTime` (GS-04 / GS-05), and the 837's `lineNumber`
+  (LX-01). **Those are examples and not a census, deliberately:** two drafts of this
+  entry published an exhaustive count and adversarial review measured both incomplete, so the claim
+  is cut back rather than grown a third time. AK9-01 is an `ID` element bound to X12 code source 715,
+  and `build999`'s own accept-with-errors guard compares it against `"A"`, so a number walks past it
+  the same way it walked past `patientControlNumber === ""`. **The fixed-width ISA slots** go through
+  `pad` / `padControl`, so a number throws an untyped `TypeError` and a numeric
+  `interchangeControlNumber` throws a typed refusal whose text misleadingly says "exceeds the 9-char
+  spec limit"; `buildTA1` has no escape helper at all.
+
+  **The "no working caller is broken" claim holds with one measured exception:** a boxed
+  `new String("PT-ACCT-001")` built cleanly at `0.0.8` and is refused now, because `typeof` it is
+  `"object"`.
+
 - **The `attw` publish gate no longer passes a tarball that carries no type declarations.** The
   `attw` script was the bare CLI, and `@arethetypeswrong/cli` returns 0 whenever its analysis found
   no types at all, before it reads the problem list. For a package that ships types, "This package
@@ -365,6 +448,66 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Tests
 
+- **`test/builder-string-type.test.ts`**, the emit gate for the fix above and the third member of the
+  builder-gate family (`builder-refusal-bounds` guards what a refusal says, `builder-array-bounds`
+  guards whether a refusal happens, this one guards whether the caller's value reaches the document).
+  The source scan is the exhaustive half: it requires every builder module's `esc` to be built by
+  `makeCallerEscaper` and requires no builder module to call `escapeRelease` itself, so a tenth
+  builder writing the old one-liner reds it without anyone adding a case. Negative-controlled by
+  putting the defect back: reverting one module's `esc` reds the scan by file and line **and** reds
+  the behavioural half, which is a cleaner control than the array gate gets, since there is no loop
+  here to wedge the runner.
+
+- **The PHI-scanner suite stopped paying 30 of its 32 `tsx` start-ups, and the global `testTimeout`
+  now says what it does and does not cover.** No library code, no public surface and no timeout value
+  changed; `scripts/phi-scan.ts` and `scripts/attw.mjs` are untouched.
+
+  Nearly every case in `test/scripts/phi-scan.test.ts` spawns the scanner. Counted at runtime on
+  both trees with a `spawnSync` shim: **32 spawns across 32 cases, all under `tsx`**, becoming
+  **36 spawns across 33 cases, 34 under `node` and 2 under `tsx`**. So 30 `tsx` start-ups were
+  removed and 2 were kept deliberately, in the equivalence case below. The scanner is type-annotated
+  Node that needs erasing and nothing more, and Node 22.18 or newer strips types itself, so the
+  spawns now use `process.execPath`. Measured on a 12-CPU cgroup quota with
+  `availableParallelism()` 12 and other workers running (load average 8.9 to 11.3, a realistic
+  condition rather than a quiet one): one scanner start is a 441 ms median under `tsx` against
+  149 ms under `node`, seven runs each. Interleaved BASE/HEAD under `pnpm test:coverage`, two rounds
+  each so the arms share a load condition, that file went 17.2 s / 17.5 s to 8.6 s / 8.6 s, and
+  15.7 s to 6.6 s run on its own. Total CPU across all workers went 58.9 s / 58.4 s to
+  50.5 s / 49.5 s. Those medians predict 8.2 s off this file (32 starts converted, less the 2 `node`
+  and 2 `tsx` starts the new case adds) against 9.1 s measured, so the model is the right shape and
+  about 11% light, not a match.
+
+  **The substitution is pinned as an equivalence rather than assumed.** The gate consumers actually
+  run (`pnpm phi-scan`, the pre-commit hook, CI) still invokes `tsx`, so one new case drives both
+  runners over the same violator and the same clean file and requires the same exit code, stdout and
+  stderr. It is the only place `tsx` is still spawned, and a simulated divergence reds it. **Scope it
+  honestly:** that case drives `paths` mode on one hit and one clean file, so it pins the exit-0 and
+  exit-1 verdicts and not the exit-2 refusals, nor all-mode, nor `--staged`. It is aimed at the only
+  divergence these two runners plausibly have, which is at module load, and a load-time divergence
+  cannot be confined to the routes it does not drive.
+
+  **What this did not buy, stated because the two figures diverge:** it removed about 8.6 s of CPU
+  but barely moved the suite's critical path (17.2 s / 17.5 s to 16.3 s / 16.7 s), which is now
+  `test/scripts/attw-gate.test.ts`. That file is deliberately left alone: measured, one `attw --pack`
+  on a trivial two-file package is 1,596 ms median, of which the real `npm pack` is 462 ms and the
+  rest is attw's own analysis. There is no runner to substitute there, pinning the real binary is the
+  point of that gate, and each of its cases already carries its own 60 s ceiling.
+
+  **`vitest.config.ts` now documents the scope of `testTimeout: 10_000`, which is narrower than it
+  looks in both directions.** It is a floor for ordinary tests, not where slow work gets its room:
+  the three slowest suites already take per-test ceilings, and the 10 MB+ 834 stream measured
+  8.9 s / 10.0 s / 9.3 s / 9.1 s across the four interleaved runs, so it sits AT the 10 s global on a
+  merely-loaded box (a 10.0 s reading is not evidence of which side of the bar it fell), and measured
+  24.1 s under heavier load on the same box. It is green only on its own 120 s ceiling. Raising the
+  global to
+  fit it would hand the same leash to all 1,100-odd tests and turn a genuinely hung test from broken
+  into merely slow. It is also **not a liveness net**: measured on this tree with vitest 4.1.4, an
+  async overrun reds at the ceiling, a finite synchronous overrun reds only after the work returns,
+  and an infinite synchronous loop produces no verdict at all, wedging the worker until it is killed
+  from outside (45 s, exit 143, no pass/fail line). That is the failure mode
+  `X12-CALLER-VALUE-RESIDUALS` hit for real, and the defence against it is the source scan in
+  `test/builder-array-bounds.test.ts`, not any timeout value.
+
 - **The default emit mode's guarantees are locked against the whole committed corpus, not just the 13
   goldens.** The goldens are already in the serializer's image, so they could only ever demonstrate
   the easy half of the round trip. `test/serialize.test.ts` now discovers every `.edi` fixture from

package/dist/index.cjs

@@ -426,6 +426,9 @@ function unescapeRelease(input, delimiters, emit, position) {
   return out;
 }
 function escapeRelease(value, delimiters) {
+  if (typeof value !== "string") {
+    throw new TypeError(`escapeRelease: value must be a string, received ${typeof value}.`);
+  }
   if (value.length === 0) return value;
   let out = "";
   for (let i = 0; i < value.length; i++) {
@@ -2508,6 +2511,25 @@ function isRealArray(value) {
   return Array.isArray(value);
 }
 
+// src/builder/caller-string.ts
+function describeCallerValue(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)})`;
+}
+function requireCallerString(value, at, refuse) {
+  if (typeof value === "string") return value;
+  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.`
+  );
+}
+function makeCallerEscaper(delimiters, at, refuse) {
+  return (value) => escapeRelease(requireCallerString(value, at, refuse), delimiters);
+}
+
 // src/transactions/remit/build-835.ts
 function refuseSpec(message) {
   throw new Remit835BuildError(REMIT_835_BUILD_ERROR_CODES.X12_835_BUILD_INVALID_SPEC, message);
@@ -2533,7 +2555,7 @@ function build835(spec) {
     component: componentSeparator,
     segment: segmentTerminator
   };
-  const esc = (value) => escapeRelease(value, delimiters);
+  const esc = makeCallerEscaper(delimiters, "build835", refuseSpec);
   const seg = (parts) => {
     let end = parts.length;
     while (end > 1 && parts[end - 1] === "") end -= 1;
@@ -4210,7 +4232,7 @@ function buildClaim837(variant, spec) {
     component: componentSeparator,
     segment: segmentTerminator
   };
-  const esc = (value) => escapeRelease(value, delimiters);
+  const esc = makeCallerEscaper(delimiters, "build837", refuseSpec2);
   const seg = (parts) => {
     let end = parts.length;
     while (end > 1 && parts[end - 1] === "") end -= 1;
@@ -5351,6 +5373,12 @@ function refuseHierarchy2(message) {
     message
   );
 }
+function refuseSpec3(message) {
+  throw new Eligibility271BuildError(
+    ELIGIBILITY_271_BUILD_ERROR_CODES.X12_271_BUILD_INVALID_SPEC,
+    message
+  );
+}
 var X279A1_VERSION_RELEASE = "005010X279A1";
 var X12_271_FUNCTIONAL_ID = "HB";
 var X12_AGENCY_CODE3 = "X";
@@ -5368,7 +5396,7 @@ function build271(spec) {
     component: componentSeparator,
     segment: segmentTerminator
   };
-  const esc = (value) => escapeRelease(value, delimiters);
+  const esc = makeCallerEscaper(delimiters, "build271", refuseSpec3);
   const seg = (parts) => {
     let end = parts.length;
     while (end > 1 && parts[end - 1] === "") end -= 1;
@@ -6043,7 +6071,7 @@ function refuseHierarchy3(message) {
     message
   );
 }
-function refuseSpec3(message) {
+function refuseSpec4(message) {
   throw new ClaimStatus277BuildError(
     CLAIM_STATUS_277_BUILD_ERROR_CODES.X12_277_BUILD_INVALID_SPEC,
     message
@@ -6077,7 +6105,7 @@ function buildClaimStatus(version, spec) {
     component: componentSeparator,
     segment: segmentTerminator
   };
-  const esc = (value) => escapeRelease(value, delimiters);
+  const esc = makeCallerEscaper(delimiters, "build277", refuseSpec4);
   const seg = (parts) => {
     let end = parts.length;
     while (end > 1 && parts[end - 1] === "") end -= 1;
@@ -6252,12 +6280,12 @@ function enforceClaim2(claim, locator, isFirst) {
   const statuses = requireCallerArray(
     claim.statuses,
     `build277: claim at ${locator}: statuses`,
-    refuseSpec3
+    refuseSpec4
   );
   const serviceLines = requireCallerArray(
     claim.serviceLines,
     `build277: claim at ${locator}: serviceLines`,
-    refuseSpec3
+    refuseSpec4
   );
   if (claim.trace === void 0 && statuses.length === 0 && serviceLines.length === 0) {
     throw new ClaimStatus277BuildError(
@@ -6280,7 +6308,7 @@ function enforceClaim2(claim, locator, isFirst) {
     const lineStatuses = requireCallerArray(
       line.statuses,
       `build277: claim at ${locator}.line[${String(l)}]: statuses`,
-      refuseSpec3
+      refuseSpec4
     );
     for (let i = 0; i < lineStatuses.length; i += 1) {
       enforceStatus(lineStatuses[i], `${locator}.line[${String(l)}].status[${String(i)}]`);
@@ -6831,7 +6859,7 @@ var Premium820BuildError = class extends Error {
 };
 
 // src/transactions/premium/build-820.ts
-function refuseSpec4(message) {
+function refuseSpec5(message) {
   throw new Premium820BuildError(PREMIUM_820_BUILD_ERROR_CODES.X12_820_BUILD_INVALID_SPEC, message);
 }
 var X218_VERSION_RELEASE = "005010X218";
@@ -6850,7 +6878,7 @@ function build820(spec) {
     component: componentSeparator,
     segment: segmentTerminator
   };
-  const esc = (value) => escapeRelease(value, delimiters);
+  const esc = makeCallerEscaper(delimiters, "build820", refuseSpec5);
   const seg = (parts) => {
     let end = parts.length;
     while (end > 1 && parts[end - 1] === "") end -= 1;
@@ -6977,7 +7005,7 @@ function build820(spec) {
   return parseX12(raw);
 }
 function enforceStructuralSpec5(spec) {
-  const traces = requireCallerArray(spec.traces, "build820: spec.traces", refuseSpec4);
+  const traces = requireCallerArray(spec.traces, "build820: spec.traces", refuseSpec5);
   if (traces.length === 0) {
     throw new Premium820BuildError(
       PREMIUM_820_BUILD_ERROR_CODES.X12_820_BUILD_INVALID_SPEC,
@@ -6987,7 +7015,7 @@ function enforceStructuralSpec5(spec) {
   const remittances = requireCallerArray(
     spec.remittances,
     "build820: spec.remittances",
-    refuseSpec4
+    refuseSpec5
   );
   if (remittances.length === 0) {
     throw new Premium820BuildError(
@@ -7007,7 +7035,7 @@ function enforceStructuralSpec5(spec) {
     const openItems = requireCallerArray(
       remittance.openItems,
       `build820: spec.remittances[${String(r)}].openItems`,
-      refuseSpec4
+      refuseSpec5
     );
     if (openItems.length === 0) {
       throw new Premium820BuildError(
@@ -7527,7 +7555,7 @@ var Enrollment834BuildError = class extends Error {
 };
 
 // src/transactions/enrollment/build-834.ts
-function refuseSpec5(message) {
+function refuseSpec6(message) {
   throw new Enrollment834BuildError(
     ENROLLMENT_834_BUILD_ERROR_CODES.X12_834_BUILD_INVALID_SPEC,
     message
@@ -7551,7 +7579,7 @@ function build834(spec) {
     component: componentSeparator,
     segment: segmentTerminator
   };
-  const esc = (value) => escapeRelease(value, delimiters);
+  const esc = makeCallerEscaper(delimiters, "build834", refuseSpec6);
   const seg = (parts) => {
     let end = parts.length;
     while (end > 1 && parts[end - 1] === "") end -= 1;
@@ -7632,7 +7660,7 @@ function build834(spec) {
   return parseX12(raw);
 }
 function enforceStructuralSpec6(spec) {
-  const members = requireCallerArray(spec.members, "build834: spec.members", refuseSpec5);
+  const members = requireCallerArray(spec.members, "build834: spec.members", refuseSpec6);
   if (members.length === 0) {
     throw new Enrollment834BuildError(
       ENROLLMENT_834_BUILD_ERROR_CODES.X12_834_BUILD_INVALID_SPEC,
@@ -7657,7 +7685,7 @@ function enforceStructuralSpec6(spec) {
     const coverages = requireCallerArray(
       member.healthCoverages,
       `build834: spec.members[${String(m)}].healthCoverages`,
-      refuseSpec5
+      refuseSpec6
     );
     for (let c = 0; c < coverages.length; c += 1) {
       const coverage = coverages[c];
@@ -8184,6 +8212,12 @@ function refuseHierarchy4(message) {
     message
   );
 }
+function refuseSpec7(message) {
+  throw new ServicesReview278BuildError(
+    AUTH_278_BUILD_ERROR_CODES.X12_278_BUILD_INVALID_SPEC,
+    message
+  );
+}
 var X12_278_FUNCTIONAL_ID = "HI";
 var X12_AGENCY_CODE7 = "X";
 var HL_LEVEL4 = {
@@ -8212,7 +8246,7 @@ function buildServicesReview(version, direction, spec) {
     component: componentSeparator,
     segment: segmentTerminator
   };
-  const esc = (value) => escapeRelease(value, delimiters);
+  const esc = makeCallerEscaper(delimiters, "build278", refuseSpec7);
   const seg = (parts) => {
     let end = parts.length;
     while (end > 1 && parts[end - 1] === "") end -= 1;
@@ -8963,6 +8997,9 @@ function narrowNoteCode(value) {
 }
 
 // src/transactions/ack/build-999.ts
+function refuseSpec8(message) {
+  throw new AckBuildError(ACK_BUILD_ERROR_CODES.X12_ACK_INVALID_SPEC, message);
+}
 var X231A1_VERSION_RELEASE = "005010X231A1";
 var X12_AGENCY_CODE8 = "X";
 function build999(spec) {
@@ -8979,7 +9016,7 @@ function build999(spec) {
     component: componentSeparator,
     segment: segmentTerminator
   };
-  const esc = (value) => escapeRelease(value, delimiters);
+  const esc = makeCallerEscaper(delimiters, "build999", refuseSpec8);
   const senderQualifier = envelope.senderQualifier ?? "ZZ";
   const receiverQualifier = envelope.receiverQualifier ?? "ZZ";
   const usageIndicator = envelope.usageIndicator ?? "P";
@@ -9459,6 +9496,9 @@ var X12BuildError = class extends Error {
 };
 
 // src/builder/build-interchange.ts
+function refuseSpec9(message) {
+  throw new X12BuildError(X12_BUILD_ERROR_CODES.X12_BUILD_INVALID_SPEC, message);
+}
 function buildInterchange(spec) {
   const elementSeparator = spec.elementSeparator ?? "*";
   const repetitionSeparator = spec.repetitionSeparator ?? "^";
@@ -9470,7 +9510,7 @@ function buildInterchange(spec) {
     component: componentSeparator,
     segment: segmentTerminator
   };
-  const esc = (value) => escapeRelease(value, delimiters);
+  const esc = makeCallerEscaper(delimiters, "buildInterchange", refuseSpec9);
   const senderQualifier = spec.senderQualifier ?? "ZZ";
   const receiverQualifier = spec.receiverQualifier ?? "ZZ";
   const usageIndicator = spec.usageIndicator ?? "P";
@@ -9892,7 +9932,7 @@ var profiles = Object.freeze({
 });
 
 // src/index.ts
-var VERSION = "0.0.7";
+var VERSION = "0.0.9";
 
 exports.ACK_BUILD_ERROR_CODES = ACK_BUILD_ERROR_CODES;
 exports.ALL_WARNING_MESSAGES = ALL_WARNING_MESSAGES;