Skip to content

S0070-transform-tf-8: nothing a message carries is dropped in silence - #40

Merged
NSchatz merged 2 commits into
mainfrom
sdd/S0070-transform-tf-8
Aug 22, 2026
Merged

S0070-transform-tf-8: nothing a message carries is dropped in silence#40
NSchatz merged 2 commits into
mainfrom
sdd/S0070-transform-tf-8

Conversation

@NSchatz

Copy link
Copy Markdown
Contributor

Spec: work/specs/S0070-transform-tf-8/spec.md in the umbrella repo.

What this changes

An issues list that said nothing about an AL1, a DG1 or an IN1 meant one of two very different things: the bundle carried it, or nobody looked. Two new stable issue codes tell them apart, raised once per segment occurrence that contributed nothing to a resource the returned bundle contains:

CodeMeaning
TRANSFORM_SEGMENT_NOT_EMITTEDThe IG publishes a segment map for this name and nothing in the bundle carries it: a gap in this library.
TRANSFORM_SEGMENT_NO_IG_MAPThe IG publishes no segment map for this name, or the name could not be classified at all.

No segment is newly transformed. A flagged segment tells a consumer what is missing, not what it said.

The four rules that carry the safety of it

  • Contribution, never inspection. An occurrence is marked as reached only where the resource it fed has just cleared the emit gate and joined the bundle. So the RXE this library counts and refuses, the orphan OBX, and a resource the gate withheld are all reported: those are the omissions a consumer most needs told.
  • The name part is guarded by a shape test this library applies itself (/^[A-Z][A-Za-z0-9]{2}$/ against the value the parser published), not by excluding the parser's own marker constant. That constant is not on @cosyte/hl7's public surface, the peer range here admits any version of it, and an exclusion test fails OPEN the moment the literal moves. The shape test fails closed and selects the same set today. A test greps the shipped source to keep the literal out.
  • A position carrying neither a name nor any field content raises nothing, wherever it sits, and still counts toward later ordinals so [#n] names the line the sender wrote. A line that kept its field separator carries content and IS reported.
  • One issue per occurrence, numbered among all occurrences of its name. Two NK1 of which only the second is reported gives NK1[2].

Locations

NAME[k], 1-based among that name's occurrences, or [#n], the segment's position in the message, with no part of an unrecognized name reproduced. Both shapes are asserted across the whole corpus. The core-concepts doc states that these are 1-based while the per-occurrence locations the library already emitted are 0-based and have not moved, and that a damaged identifier (AL11) reads as a standard gap rather than an IG claim.

Evidence that nothing else moved

The Bundle and the full pre-existing issues list for all 23 recorded inputs were captured from this tree before a line of the diagnostic existed (commit 13750f18, first commit on this branch) and are asserted against those baselines: the Bundle byte for byte, and every pre-existing issue first, in its recorded order, with the new ones appended. That measures "no resource changed" and "no issue was reordered" against the old tree rather than against the new code.

phi-scan-overrides.md and package.json are byte-identical to their pinned content. The change is additive throughout: 0 deletions.

Gates

pnpm test 578 passed (32 files, was 524/31) - pnpm lint - pnpm typecheck - pnpm format:check - pnpm test:coverage (all directory gates green; the new module is 100/100/100/100) - pnpm phi-scan - pnpm check:no-emdash - pnpm check:no-internal-refs - pnpm check:agent-notes.

…teness fixtures
The message-level completeness diagnostic has to prove two things about every
input it changes the issues list for: the Bundle comes back byte for byte, and
every issue the library already raised is still there, first, in the order it
was raised. Neither can be measured from a tree that already carries the
diagnostic, so the corpus and its baselines land first, captured from HEAD
before a line of the diagnostic exists.
scripts/capture-completeness-goldens.ts records the commit it captured at and
says in its own banner why re-running it against a changed tree turns both
assertions into tautologies.
…e bundle
An issues list that said nothing about an AL1, a DG1 or an IN1 meant one of two
very different things: the bundle carried it, or nobody looked. Two new codes
tell them apart, raised once per segment occurrence that contributed nothing to
a resource the returned bundle contains. TRANSFORM_SEGMENT_NOT_EMITTED is a gap
in this library (the IG publishes a map for the name); TRANSFORM_SEGMENT_NO_IG_MAP
is a gap in the standard, or a name that could not be classified at all.
Reaching is contribution, never inspection. An occurrence is marked only where
the resource it fed has just cleared the emit gate and joined the bundle, so the
RXE this library counts and refuses, the orphan OBX, and a resource the gate
withheld are all reported: those are exactly the omissions a consumer most needs
told, and a "the walker touched it" reading would have silenced them.
The name part of a location is guarded by the segment-identifier shape applied
by this library to the value the parser published, as a positive test. Not by
excluding the parser's marker constant: that constant is not on the package's
public surface, the peer range here admits any parser version, and an exclusion
test fails OPEN the moment the literal moves, promoting an unvouched value into
a rendering. The shape test fails closed and selects the same set today.
A position carrying neither a name nor any field content is the parser's ordinal
placeholder for a blank line. It raises nothing wherever it sits, and still
counts toward later ordinals so [#n] keeps naming the line the sender wrote. A
line that kept its field separator carries content and IS reported: the
exclusion is for the absence of a segment, never the absence of a name.
Nothing else moved, and it is asserted rather than claimed. Both codes are
informational, neither is fatal, and the new issues are appended after every
issue the assembly already raised. The Bundle and the full pre-existing issues
list for all twenty-three inputs are compared against baselines captured from
this tree before the diagnostic existed, so "no resource changed" and "no issue
was reordered" are measured against the old tree, not against the new code.
phi-scan-overrides.md and package.json are byte-identical to their pinned
content; the change is additive throughout.
@NSchatz
NSchatz merged commit 673890c into mainAug 22, 2026
9 checks passed
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@NSchatz