@cosyte/hl7 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -15,6 +15,45 @@ per the cosyte version ladder (`0.0.x` until first alpha).
 
 ### Added
 
+- **The cosyte brand banner heads `README.md` (`ASSETS-P8`, the consuming half).** A plain markdown
+  image on the first line of the file, above the H1, pointing at the absolute HTTPS URL published
+  for `hl7` in the `assets` repo's `published-urls.json` contract
+  (`https://cosyte.com/social/cosyte-banner-hl7-1200x300.png`, `status: live` on
+  `website#59 01f988b`). Re-verified `200 image/png`, 18316 bytes, immediately before the push.
+
+  **The shape is deliberate, and `hl7` sets it for the other thirteen consuming READMEs.** It is a
+  markdown image, **not `<img>` and not `<picture>`**: whether npm's markdown sanitizer preserves a
+  `<picture>` element is unverified, which is precisely why the banner artwork is self-grounded
+  (opaque ground, correct against a light or dark page) and depends on no such element. A markdown
+  image with an absolute HTTPS URL is the construct we are willing to assert renders on both npm and
+  GitHub, so it carries no width or height attributes either. **PNG only** is a bounded policy (the
+  format we assert renders on every README surface), not a demonstrated impossibility for others.
+  The **alt text is content, not decoration**: it names the package and its one-line purpose,
+  because it is what a screen reader on the npm page reads out, so "banner", "logo", or the file
+  name would all be a wasted line.
+
+  **SUPERSEDED on 2026-07-31 by `1aee04b`, which replaced this banner with the shared Cosyte lockup
+  in a `<picture>` block.** The two paragraphs above are left exactly as they shipped rather than
+  corrected, because they were true of the tree and right on the evidence available when they were
+  written, and they record a real state the package passed through. This note says what changed
+  under them. It shipped verbatim inside the `@cosyte/hl7@0.0.4` tarball, so it is text a consumer
+  already has on disk.
+
+  **The claim the new evidence overturns is the second one: "whether npm's markdown sanitizer
+  preserves a `<picture>` element is unverified".** That is measured now. The first claim, that the
+  banner is a markdown image and "not `<img>` and not `<picture>`", was a consequence of the second
+  rather than an independent choice, so it went when its premise did; it is no longer true of the
+  tree either way, since `README.md` now opens with a `<picture>`. What was measured: **GitHub
+  honours the `prefers-color-scheme` switch**, verified on `@cosyte/astm` in dark mode, where the
+  rendered image's `currentSrc` resolves to the on-dark tile and its parent element is `PICTURE`.
+  **On the npm package page the `<img>` is hoisted out of its `<picture>` by the anchor wrapper**,
+  so the inner fallback renders rather than the element being stripped or broken; and **npmjs.com
+  has no dark mode** (founder-confirmed), so the light cut is the correct image there regardless.
+  The GitHub and npm measurements above were taken on `astm` and reported into this repo rather
+  than re-taken here; what was re-checked directly for `hl7` was that both tile URLs return
+  `200 image/png`. **PNG only** and **alt text is content, not decoration** are both unchanged and
+  still hold; only the element choice and its stated premise moved.
+
 - **The published JSDoc is swept, and `src/` doc comments are gated
   (`pnpm check:no-internal-refs` third pass; `PUBLIC-SURFACE-HYGIENE`).** Doc comments compile
   into `dist/index.d.ts` and `dist/index.d.cts`, `dist` is the first entry in `files`, and every
@@ -397,6 +436,29 @@ kind, value)`** sets one at a field or `field[rep]` dot-path. Component values a
 
 ### Changed
 
+- **`README.md` now opens with the shared Cosyte lockup in a `<picture>` block, replacing the
+  per-package banner (`1aee04b`).** The dark-ground org tile sits behind a
+  `prefers-color-scheme: dark` media query with the light-ground tile as the inner `<img>`, so on a
+  renderer that honours the switch the mark sits on a ground matching the page it is read on. One
+  markdown image line out, four lines in: the `# @cosyte/hl7` H1, the blockquote tagline, the badge
+  row and everything below are untouched.
+
+  **Why the per-package banner goes.** It baked the package name and the one-line tagline into
+  pixels, and the two lines directly beneath it repeated both. The shared lockup reads "Cosyte"
+  while the H1 reads `@cosyte/hl7`, so the strings differ, the duplication goes away, and the
+  heading stays.
+
+  **The failure mode is safe**: a renderer that strips `<source>` renders the inner `<img>`, so the
+  worst case is a light-ground mark on a dark page, never a missing or broken image. The block was
+  copied out of `astm/README.md` rather than retyped and the two URLs then diffed byte for byte
+  against that file, because a transcription error in one of them is a broken image on a public
+  package page. Both were re-verified `200 image/png` (10513 and 10455 bytes) immediately before
+  the push: the `live` flag in the `assets` manifest is a declaration made on evidence from another
+  repo, not a fact checked here. The alt text describes the mark rather than the package, since it
+  is what a screen reader on the npm page reads out and what a reader gets when the image fails.
+  This supersedes the `ASSETS-P8` banner entry under **Added** above, which is annotated in place
+  rather than rewritten. Documentation only: no runtime, API or packaging change.
+
 - **Corrected stale "not yet published to npm / unpublished" language in the docs site
   (README-ORG-SWEEP).** `@cosyte/hl7` is now published on npm at `0.0.1` and public, so the
   `docs-content/installation.md` Status blockquote ("not yet published… the shape it will take at
@@ -433,6 +495,153 @@ kind, value)`** sets one at a field or `field[rep]` dot-path. Component values a
 
 ### Fixed
 
+- **A warning or error message could carry clinical text into a log line (`HL7-WARN-MSG-PHI`).**
+  No options were required to reach it: plain `parseHL7(raw)` on lenient defaults.
+
+  **The mechanism.** `normalize()` rewrites every `\r\n` and `\n` in the input to `\r` before
+  segment splitting, unconditionally and with no field awareness. HL7 v2 Ch. 2 fixes the segment
+  terminator as `<CR>` and provides `\.br\` (§2.7.6) precisely because a literal line break cannot
+  appear inside a field, but real senders emit raw breaks inside narrative fields (`OBX-5`, notes,
+  embedded documents), which is exactly the class of sender violation this parser exists to
+  tolerate. When one occurs, the remainder of that field becomes a forged segment, and `tokenize()`
+  takes the whole line as its segment identifier because a line with no field separator offers no
+  other candidate. `UNKNOWN_SEGMENT` then interpolated that "identifier" uncapped, putting synthetic
+  name, date of birth and medical record number into `Hl7ParseWarning.message`. Under
+  `{ strict: true }` the same text reached the thrown `Hl7ParseError.message`, and therefore
+  `.stack`.
+
+  **The disclosure was inverted, which is what made it consequential.** Guidance said to redact
+  `Hl7ParseError.snippet`. On the strict path `snippet` holds the head of the message (usually the
+  MSH header) while `message` held the payload, so a consumer following the documented mitigation
+  exactly still logged the data. `message` is also the field a logger prints by default and the one
+  `stack` embeds.
+
+  **The fix: bound at the factory, not at the call site.** A token taken from input is echoed only
+  when it matches the form the spec defines for it, and becomes `<withheld>` otherwise. A length cap
+  was rejected because truncating still emits the first N characters of a patient name. Segment
+  identifiers are held to exactly three alphanumerics (HL7 v2 Ch. 2 §2.5), with equivalent forms for
+  MSH-9 types and MSH-12 versions. Conforming tokens render byte-identically, so `PID`, `ZZZ` and
+  every legitimate Z-segment name are unchanged and well-formed input sees no behaviour change:
+  1653 existing tests pass untouched. Placing the check in the factories rather than at the one live
+  call site also covers the six factories currently exported but unreached, and consumers who
+  construct warnings themselves.
+
+  **Charset labels are bounded by registry membership, not by spelling, and that distinction was
+  earned the hard way.** The first version of this fix used a shape test for them too, and a refuter
+  broke it: the shape admitted all five of the PHI-shaped markers this repo's own property suite
+  defines, including an 18-character patient name. Table 0211 is a **closed** table and
+  `UNKNOWN_CHARSET` fires precisely when a label is absent from it, so at the moment of the warning
+  there is no spec-defined spelling left to test against, and `UNICODE UTF-8` and a patient name are
+  shape-siblings. No regex can separate them. A label is now echoed only when `resolveCharset`
+  recognises it.
+
+  **What is bounded, stated without overclaiming.** `snippet` is the only field carrying input
+  verbatim and unbounded, so it is the one to redact first. A message cannot carry a field's value,
+  but it can carry a residue of up to three characters when a malformed line happens to look like a
+  segment identifier. No absolute "never carries field content" claim is made anywhere in this
+  package, because the code cannot honour one.
+
+  **Two adjacent surfaces bounded in the same pass.** `UNKNOWN_CHARSET` and `ENCODING_MISMATCH`
+  interpolate a value read as MSH-18, which on a message carrying no segment terminators is not
+  MSH-18 at all but the 18th `|`-token of the flattened input, commonly a data field. That path is
+  Buffer-only, and `parseStream` and `splitBatch` re-encode each split message to a Buffer, which is
+  the ordinary MLLP and file ingestion shape, so it is not an exotic corner.
+  `MISSING_EXPECTED_GROUP` and `MERGE_MISSING_PRIOR_OR_SURVIVOR` interpolate MSH-9.
+
+  **The test gap is the real finding.** The PHI property suite could not reach this position: every
+  generated marker sat after a `|`, so it was always a field value to the tokenizer, while the only
+  position that leaks is a line's **leading** token. A green suite over an unreachable case is
+  indistinguishable from a correct one. New generators emit the real trigger (a field-internal `\n`
+  and `\r\n`) across the lenient and strict arms, asserting on `.stack` separately from `.message`
+  because most error reporters ship the stack off-box, and pinning the escalated code on both
+  strict properties so neither can pass vacuously if some other warning escalates first. A second
+  set covers the Buffer/MSH-18 path, which every string-input generator in the suite structurally
+  misses, and a third asserts the invariant on the parsed **model**. All ten new tests fail on the
+  code they were written against and pass on this one.
+
+  **The same lesson applied to this fix's own first draft, which is why it now bounds the model
+  too.** Bounding the warning message protected this package's diagnostics and nothing else.
+  `Segment.type` still carried the entire forged line, so a consumer that reads the model and builds
+  its own report from that "identifier" wrote clinical narrative into it, on lenient defaults, with
+  no options set. **A diagnostic-surface fix does not protect a downstream package that reads your
+  model and builds its own diagnostics from it. Bounding at the model protects both.**
+  `Segment.type`, `Hl7Message.version` and the unrecognized branch of `MessageStructure` now carry
+  bounded identifiers, and the shared primitive moved to `src/parser/tokens.ts` so the parser and the
+  model use one bound rather than two.
+
+  **One bound deliberately not taken, named rather than left implicit.** On the _recognized_ branch
+  of `MessageStructure`, `triggerEvent` is echoed verbatim, and a definition matching on message code
+  alone (`ACK`) accepts an arbitrary MSH-9.2. Left unbounded on purpose: no real sender putting
+  narrative in MSH-9.2 is grounded in a de-identified document, and widening the guard there is a
+  separate change, not a silent extension of this one. An earlier comment in that file asserted the
+  branch returned registry values and could not carry input, which was false; the claim is corrected
+  rather than the guard grown.
+
+  **What stays unbounded, deliberately, because bounding it would be a mis-parse.** The model
+  separates **identifiers** from **values**. `Meta.*` is the documented value view of the MSH header;
+  `Segment.fields`, `Segment.raw` and `Hl7Message.rawSegments` are the raw tokenization the
+  byte-verbatim round-trip serializes from; `toString()` / `toJSON()` / `prettyPrint()` are the
+  message itself. Those are content surfaces and say so. `meta.version` in particular keeps MSH-12
+  exactly as it arrived and is what the v2.7 MRG field-scoping reads, so bounding
+  `Hl7Message.version` changes no clinical field selection.
+
+  **Docs corrected in both directions.** `docs-content/troubleshooting.md` asserted that warning
+  messages never echo a field's value, an overclaim; it and the equivalent assurances in
+  `normalize.ts` and `warnings.ts` now state the check that makes it true. The `Hl7ParseError`
+  disclosure now says `snippet` is the field to redact first, rather than claiming a message is
+  clean. `README.md` called the snippet an excerpt of "the offending input" when it is always
+  taken from the start of the message; the wording is corrected rather than the behaviour, because
+  re-pointing the snippet at the deviation's own segment would move more clinical content into the
+  single unredacted field.
+
+  **Not a mis-parse.** Parsed values were always correct; this was a diagnostic-surface leak.
+  Consumers on any published version up to and including `0.0.3` should treat
+  `Hl7ParseWarning.message` and `Hl7ParseError.message` as potentially carrying field content for
+  feeds they do not control until they upgrade.
+
+- **Stale counts in `docs-content/`, found while correcting the PHI wording.** The warning-code
+  count was given as 19 in three places (it is 20), and two pages quoted a published npm version
+  that was two releases stale. Both now point at the registry rather than restating it, which is the
+  only way a doc page stops drifting from it.
+
+- **Four false claims in the README's feature list, each re-derived from source rather than from
+  memory (`README-CLAIM-DRIFT`).** Every number and version below was measured against the thing it
+  describes, in the order a consumer would have to trust it:
+  1. **Node 18+ to Node 22+**, in the badge (`node-%3E%3D18`) and in the prose. `engines.node` is
+     `>=22.0.0` in `package.json` and in the registry (`npm view @cosyte/hl7 engines`), and CI runs
+     the 22 + 24 matrix. This was the one with a consumer-visible consequence: `npm i @cosyte/hl7`
+     on Node 18 warns on engines while the package page says 18 is supported.
+  2. **ES2022 to ES2023.** `@cosyte/tsconfig/base.json` sets `"target": "ES2023"` and
+     `"lib": ["ES2023"]`, and this repo's `tsconfig.json` extends it without override.
+  3. **18 to 20 stable warning codes.** `WARNING_CODES` in `src/parser/warnings.ts` has 20 keys, and
+     `test/warning-codes.snapshot.test.ts` already asserted `toHaveLength(20)`. A green test suite
+     and a wrong package page coexisted. **No other surface says 18, but that is not the same as the
+     count now being consistent**: further down `README.md`, an inline prose list of 16 code names is
+     still introduced as "the full list of Tier-2 codes", and `docs-content/` says 19 in three
+     places. Those are pre-existing, outside this feature list, and left for their own change rather
+     than folded in here.
+  4. **"Every public export has JSDoc + `@example`" to "every public function and class."** Measured
+     over the 213 names in the built `dist/index.d.ts` export list: all **79 functions** and all
+     **5 classes** carry both, but of 17 value constants one (`ERR_CONDITION_CODE_SYSTEM`) has JSDoc
+     with no `@example`, and while all **109 type-only exports carry JSDoc, only 73 carry an
+     `@example`**. The three aliased namespace exports (`HL7`, `conformance`, `text`) fail the old
+     wording outright: two carry no JSDoc at all and the third has no `@example`. The narrowed
+     sentence is exactly true; the old one was not.
+
+  **The rest of the feature list was checked the same way and is correct**, so it is unchanged:
+  4 fatal codes (`FATAL_CODES` has exactly 4 keys), 8 built-in vendor profiles (the frozen `profiles`
+  namespace has 8, and the eight vendor names match), zero runtime dependencies (`dependencies` is
+  present and empty, and there is no `peerDependencies`), `noUncheckedIndexedAccess` (true in the
+  inherited base config), dual ESM + CJS (the `exports` map resolves `import` to `.mjs`/`.d.ts` and
+  `require` to `.cjs`/`.d.cts`, and `attw` passes node10, node16-CJS, node16-ESM and bundler), and
+  the two linked paths (`examples/profile-starter-kit/`, `docs-content/spec-notes-escapes.md`) both
+  resolve.
+
+  **`CLAUDE.md` already said Node >= 22 and Target ES2023, so the repo contradicted itself and
+  nothing caught it.** The two files drifted in opposite directions because only one of them is read
+  by a consumer, and it is the one that drifted. No gate compares a README claim to the config it
+  describes, which is why these were found by hand.
+
 - **`scripts/sync-version.mjs` hardened against two latent defects, and gated in CI
   (SYNC-VERSION-HARDENING).** Follow-up hardening on the VERSION-SYNC script; ported byte-identically
   across `hl7`, `x12`, and `mllp`. (1) The version was spliced into `src/index.ts` via

package/README.md

@@ -1,3 +1,8 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://cosyte.com/tile/cosyte-lockup-tile-on-dark-1200x300.png">
+  <img alt="Cosyte: a plus mark set in two overlapping rounded squares, one solid and one outlined, beside the Cosyte wordmark" src="https://cosyte.com/tile/cosyte-lockup-tile-on-light-1200x300.png">
+</picture>
+
 # @cosyte/hl7
 
 > Parse real-world, vendor-quirky HL7 v2 messages and extract the fields you need in one line, without reading the spec.
@@ -5,7 +10,7 @@
 [![npm version](https://img.shields.io/npm/v/@cosyte/hl7.svg)](https://www.npmjs.com/package/@cosyte/hl7)
 [![CI](https://img.shields.io/github/actions/workflow/status/cosyte/hl7/ci.yml?branch=main&label=CI)](https://github.com/cosyte/hl7/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org)
 
 A developer-focused HL7 v2 parser and utility library for Node.js and TypeScript. Optimised for the 10% of HL7 you actually use, with the other 90% still one accessor away when you need it.
 
@@ -37,10 +42,10 @@ That's the whole pitch: no config, no schema upload, no spec lookup. The parser
 
 - **One-line extraction**: `msg.patient.mrn`, `msg.meta.timestamp`, `msg.observations()`, and friends. No segment or field numbers to memorise.
 - **Three access patterns**: named helpers, dot-paths (`msg.get("PID.5.1")`), or structural traversal (`msg.segments("OBX")[0].field(3)`). Pick the level of ceremony you need.
-- **Real-world tolerance, four-tier**: lenient default parses vendor-quirky messages; 18 stable warning codes flag what was tolerated; strict mode escalates every deviation for CI validators; only 4 truly-structural failures are fatal.
+- **Real-world tolerance, four-tier**: lenient default parses vendor-quirky messages; 20 stable warning codes flag what was tolerated; strict mode escalates every deviation for CI validators; only 4 truly-structural failures are fatal.
 - **First-class profile system**: `defineProfile()` API, 8 built-in vendor profiles (Epic, Cerner, Meditech, athenahealth, generic lab, Visage 7 imaging/PACS, Philips Vue PACS, VA VistA Radiology/NucMed), plus a [publishable starter kit](./examples/profile-starter-kit/) you copy-and-ship.
 - **Round-trip safe, byte-verbatim escapes**: `parse -> modify -> toString()` emits spec-clean HL7 regardless of input quirks (Postel's Law: liberal parser, conservative emitter), and a parsed field's escape sequences (`\H\`, `\X41\`, charset/vendor escapes) re-emit **byte-for-byte**. See [Escapes & round-trip](./docs-content/spec-notes-escapes.md).
-- **Strict TypeScript, zero runtime deps**: ES2022, `noUncheckedIndexedAccess`, dual ESM + CJS, Node 18+. Every public export has JSDoc + `@example` that feeds your editor's IntelliSense.
+- **Strict TypeScript, zero runtime deps**: ES2023, `noUncheckedIndexedAccess`, dual ESM + CJS, Node 22+. Every public function and class has JSDoc + `@example` that feeds your editor's IntelliSense.
 - **Warnings carry stable codes + positional context**: react programmatically by `w.code`, with `segmentIndex`/`fieldIndex`/etc. attached.
 
 ---
@@ -739,7 +744,7 @@ The library throws exactly three error types, all exported from the package barr
 
 ### `Hl7ParseError`
 
-Thrown by `parseHL7` when the input hits one of the 4 Tier-3 fatal codes (see above). Carries positional context plus a short snippet of the offending input.
+Thrown by `parseHL7` when the input hits one of the 4 Tier-3 fatal codes (see above). Carries positional context plus a short snippet taken from the start of the input (up to 40 characters, plus an ellipsis when truncated).
 
 ```ts
 import { parseHL7, Hl7ParseError, FATAL_CODES } from "@cosyte/hl7";
@@ -760,7 +765,13 @@ if (err instanceof Hl7ParseError && err.code === FATAL_CODES.NO_MSH_SEGMENT) {
 }
 ```
 
-`Hl7ParseError.snippet` may contain PHI when parsing real clinical messages. The library does NOT redact. Redact at your call site if compliance demands it.
+`Hl7ParseError.snippet` may contain PHI when parsing real clinical messages. The library does NOT redact it. Redact it at your call site if compliance demands it.
+
+**`snippet` is the only field carrying input verbatim and unfiltered** (capped at 40 characters plus an ellipsis, but not shape-checked in any way), so redact it first.
+
+`message` is bounded but not absolutely content-free, which is worth stating because `message` is what a logger prints by default and what `stack` embeds. A token taken from the input is echoed only when it matches the form the spec defines for it: a three-character segment identifier, an MSH-9 type, an MSH-12 version, or a charset label the closed Table 0211 actually contains. Anything else becomes `<withheld>`. So a message cannot carry a field's value, but it can carry a residue of up to three characters when a malformed line happens to look like a segment identifier. The other shapes are narrower in practice than their patterns allow, because the library only ever feeds them registry-matched values; the patterns themselves admit more (a message type up to 26 characters, a version up to 14), which matters only if you construct warnings yourself.
+
+Under `{ strict: true }` an escalated Tier-2 warning is thrown as an `Hl7ParseError` carrying that same bounded message, plus a `snippet` of the first 40 characters of the input rather than of the deviation's own segment.
 
 ### `Hl7ParseWarning`
 

package/dist/index.cjs

@@ -255,7 +255,104 @@ var KNOWN_SEGMENTS = /* @__PURE__ */ new Set([
   "CSS"
 ]);
 
+// src/parser/charset.ts
+function normalizeLabel(raw) {
+  return raw.trim().replace(/\s+/gu, " ").toUpperCase();
+}
+function decodeEntry(canonical, decoder) {
+  return { canonical, treatment: "decode", decoder };
+}
+function verbatimEntry(canonical) {
+  return { canonical, treatment: "verbatim", decoder: "" };
+}
+function buildTable() {
+  const table = /* @__PURE__ */ new Map();
+  const add = (aliases, entry) => {
+    for (const alias of aliases) table.set(normalizeLabel(alias), entry);
+  };
+  add(["ASCII", "US-ASCII", "ISO IR6"], decodeEntry("ASCII", "utf-8"));
+  add(["UTF-8", "UTF8", "UNICODE UTF-8", "UNICODE"], decodeEntry("UTF-8", "utf-8"));
+  add(["8859/1", "ISO-8859-1", "ISO 8859-1", "ISO8859-1"], decodeEntry("8859/1", "latin1"));
+  for (const n of [2, 3, 4, 5, 6, 7, 8, 10, 13, 14, 15, 16]) {
+    add(
+      [`8859/${n}`, `ISO-8859-${n}`, `ISO 8859-${n}`, `ISO8859-${n}`],
+      decodeEntry(`8859/${n}`, `iso-8859-${n}`)
+    );
+  }
+  add(["8859/9", "ISO-8859-9", "ISO 8859-9", "ISO8859-9"], verbatimEntry("8859/9"));
+  add(["8859/11", "ISO-8859-11", "ISO 8859-11", "ISO8859-11"], verbatimEntry("8859/11"));
+  add(["ISO IR14", "JIS X 0201"], verbatimEntry("ISO IR14"));
+  add(["ISO IR87", "JIS X 0208"], verbatimEntry("ISO IR87"));
+  add(["ISO IR159", "JIS X 0212"], verbatimEntry("ISO IR159"));
+  add(["GB 18030-2000", "GB18030", "GB 18030"], verbatimEntry("GB 18030-2000"));
+  add(["KS X 1001", "KSX1001", "KS C 5601"], verbatimEntry("KS X 1001"));
+  add(["CNS 11643-1992", "CNS 11643"], verbatimEntry("CNS 11643-1992"));
+  add(["BIG-5", "BIG5"], verbatimEntry("BIG-5"));
+  add(["UNICODE UTF-16", "UTF-16"], verbatimEntry("UNICODE UTF-16"));
+  add(["UNICODE UTF-32", "UTF-32"], verbatimEntry("UNICODE UTF-32"));
+  return table;
+}
+var CHARSET_TABLE = buildTable();
+var DEFAULT_RESOLUTION = Object.freeze({
+  canonical: "ASCII",
+  treatment: "decode",
+  decoder: "utf-8",
+  recognized: true
+});
+function resolveCharset(raw) {
+  if (raw === void 0) return DEFAULT_RESOLUTION;
+  const key = normalizeLabel(raw);
+  if (key === "") return DEFAULT_RESOLUTION;
+  const entry = CHARSET_TABLE.get(key);
+  if (entry !== void 0) {
+    return {
+      canonical: entry.canonical,
+      treatment: entry.treatment,
+      decoder: entry.decoder,
+      recognized: true
+    };
+  }
+  return { canonical: key, treatment: "verbatim", decoder: "", recognized: false };
+}
+function canonicalCharset(raw) {
+  return resolveCharset(raw).canonical;
+}
+
+// src/parser/tokens.ts
+var DERIVED_TOKEN_SHAPES = {
+  /**
+   * HL7 v2 Ch. 2 §2.5 segment identifier: three characters, the first
+   * alphabetic.
+   *
+   * Two deliberate tightenings, each measured rather than assumed. The first
+   * version allowed four characters as "vendor tolerance", which was invented
+   * rather than grounded: all 91 `KNOWN_SEGMENTS` are exactly three, and
+   * `defineProfile` independently validates custom Z-segments to
+   * `/^Z[A-Z0-9]{2}$/`, so nothing legitimate is longer. The second requires a
+   * leading letter, which every known segment and every legal Z-segment
+   * satisfies, and which excludes a **bare numeric** residue. That matters out
+   * of proportion to its size: a forged line reading `120` is a glucose, a
+   * blood pressure or a dose, which is the most clinical meaning three
+   * characters can carry.
+   */
+  segmentId: /^[A-Za-z][A-Za-z0-9]{2}$/,
+  /** MSH-9 message type / trigger, e.g. `ADT^A01` or `A40`. */
+  messageType: /^[A-Za-z0-9]{1,8}(?:\^[A-Za-z0-9]{1,8}){0,2}$/,
+  /** MSH-12 version ID, e.g. `2.5` or `2.5.1`. */
+  version: /^[0-9]{1,2}(?:\.[0-9]{1,3}){0,3}$/
+};
+function safeDerivedToken(value, kind) {
+  return DERIVED_TOKEN_SHAPES[kind].test(value) ? value : WITHHELD;
+}
+var WITHHELD = "<withheld>";
+function boundedIdentifier(value, kind) {
+  return value === "" ? "" : safeDerivedToken(value, kind);
+}
+
 // src/parser/warnings.ts
+function safeCharsetLabel(value) {
+  return resolveCharset(value).recognized ? value : WITHHELD;
+}
 var WARNING_CODES = {
   MLLP_FRAMING_STRIPPED: "MLLP_FRAMING_STRIPPED",
   FIELD_WHITESPACE_TRIMMED: "FIELD_WHITESPACE_TRIMMED",
@@ -340,28 +437,28 @@ function timestampFallbackFormat(position, matchedFormat) {
 function segmentCase(position, observed) {
   return {
     code: WARNING_CODES.SEGMENT_CASE,
-    message: `Segment identifier "${observed}" is not uppercase; normalized to "${observed.toUpperCase()}".`,
+    message: `Segment identifier "${safeDerivedToken(observed, "segmentId")}" is not uppercase; normalized to "${safeDerivedToken(observed.toUpperCase(), "segmentId")}".`,
     position
   };
 }
 function extraFields(position, segmentName2, extraCount) {
   return {
     code: WARNING_CODES.EXTRA_FIELDS,
-    message: `Segment "${segmentName2}" has ${String(extraCount)} more field(s) than the profile declares.`,
+    message: `Segment "${safeDerivedToken(segmentName2, "segmentId")}" has ${String(extraCount)} more field(s) than the profile declares.`,
     position
   };
 }
 function unknownSegment(position, segmentName2) {
   return {
     code: WARNING_CODES.UNKNOWN_SEGMENT,
-    message: `Unknown segment "${segmentName2}": not in HL7 spec and no profile claim.`,
+    message: `Unknown segment "${safeDerivedToken(segmentName2, "segmentId")}": not in HL7 spec and no profile claim.`,
     position
   };
 }
 function duplicateRequiredSegment(position, segmentName2) {
   return {
     code: WARNING_CODES.DUPLICATE_REQUIRED_SEGMENT,
-    message: `Required singleton segment "${segmentName2}" appears more than once.`,
+    message: `Required singleton segment "${safeDerivedToken(segmentName2, "segmentId")}" appears more than once.`,
     position
   };
 }
@@ -375,42 +472,42 @@ function encodingMismatch(position, detail) {
 function missingRequiredField(position, segmentName2, fieldIndex) {
   return {
     code: WARNING_CODES.MISSING_REQUIRED_FIELD,
-    message: `Required field ${segmentName2}-${String(fieldIndex)} is missing or empty.`,
+    message: `Required field ${safeDerivedToken(segmentName2, "segmentId")}-${String(fieldIndex)} is missing or empty.`,
     position
   };
 }
 function missingExpectedGroup(position, messageType, groupName, anchorSegments) {
   return {
     code: WARNING_CODES.MISSING_EXPECTED_GROUP,
-    message: `Message type "${messageType}" is missing its expected "${groupName}" segment group (no ${anchorSegments.join("/")}); message may be truncated or misrouted.`,
+    message: `Message type "${safeDerivedToken(messageType, "messageType")}" is missing its expected "${groupName}" segment group (no ${anchorSegments.join("/")}); message may be truncated or misrouted.`,
     position
   };
 }
 function outOfOrderSegment(position, segmentName2) {
   return {
     code: WARNING_CODES.OUT_OF_ORDER_SEGMENT,
-    message: `Segment "${segmentName2}" appears out of the order declared by the active profile.`,
+    message: `Segment "${safeDerivedToken(segmentName2, "segmentId")}" appears out of the order declared by the active profile.`,
     position
   };
 }
 function versionMismatch(position, declared, expected) {
   return {
     code: WARNING_CODES.VERSION_MISMATCH,
-    message: `HL7 version mismatch: message declares "${declared}", expected "${expected}".`,
+    message: `HL7 version mismatch: message declares "${safeDerivedToken(declared, "version")}", expected "${expected}".`,
     position
   };
 }
 function unknownCharset(position, requested) {
   return {
     code: WARNING_CODES.UNKNOWN_CHARSET,
-    message: `Unrecognized character set "${requested}"; not decoded, bytes read as latin1.`,
+    message: `Unrecognized character set "${safeCharsetLabel(requested)}"; not decoded, bytes read as latin1.`,
     position
   };
 }
 function unsupportedCharset(position, code) {
   return {
     code: WARNING_CODES.UNSUPPORTED_CHARSET,
-    message: `Character set "${code}" was not decoded; bytes read as latin1.`,
+    message: `Character set "${safeCharsetLabel(code)}" was not decoded; bytes read as latin1.`,
     position
   };
 }
@@ -425,7 +522,7 @@ function mergeMissingPriorOrSurvivor(position, eventType, missing) {
   const detail = missing === "prior" ? "no MRG segment carries a usable prior (non-surviving) identifier" : "no PID segment carries a usable surviving identifier";
   return {
     code: WARNING_CODES.MERGE_MISSING_PRIOR_OR_SURVIVOR,
-    message: `Identity event "${eventType}" is missing its ${missing} role: ${detail}. Surfacing what is present; the MRG->PID merge direction is not guessed.`,
+    message: `Identity event "${safeDerivedToken(eventType, "messageType")}" is missing its ${missing} role: ${detail}. Surfacing what is present; the MRG->PID merge direction is not guessed.`,
     position
   };
 }
@@ -471,69 +568,6 @@ function emitIfFramed(result, emit, position) {
   }
 }
 
-// src/parser/charset.ts
-function normalizeLabel(raw) {
-  return raw.trim().replace(/\s+/gu, " ").toUpperCase();
-}
-function decodeEntry(canonical, decoder) {
-  return { canonical, treatment: "decode", decoder };
-}
-function verbatimEntry(canonical) {
-  return { canonical, treatment: "verbatim", decoder: "" };
-}
-function buildTable() {
-  const table = /* @__PURE__ */ new Map();
-  const add = (aliases, entry) => {
-    for (const alias of aliases) table.set(normalizeLabel(alias), entry);
-  };
-  add(["ASCII", "US-ASCII", "ISO IR6"], decodeEntry("ASCII", "utf-8"));
-  add(["UTF-8", "UTF8", "UNICODE UTF-8", "UNICODE"], decodeEntry("UTF-8", "utf-8"));
-  add(["8859/1", "ISO-8859-1", "ISO 8859-1", "ISO8859-1"], decodeEntry("8859/1", "latin1"));
-  for (const n of [2, 3, 4, 5, 6, 7, 8, 10, 13, 14, 15, 16]) {
-    add(
-      [`8859/${n}`, `ISO-8859-${n}`, `ISO 8859-${n}`, `ISO8859-${n}`],
-      decodeEntry(`8859/${n}`, `iso-8859-${n}`)
-    );
-  }
-  add(["8859/9", "ISO-8859-9", "ISO 8859-9", "ISO8859-9"], verbatimEntry("8859/9"));
-  add(["8859/11", "ISO-8859-11", "ISO 8859-11", "ISO8859-11"], verbatimEntry("8859/11"));
-  add(["ISO IR14", "JIS X 0201"], verbatimEntry("ISO IR14"));
-  add(["ISO IR87", "JIS X 0208"], verbatimEntry("ISO IR87"));
-  add(["ISO IR159", "JIS X 0212"], verbatimEntry("ISO IR159"));
-  add(["GB 18030-2000", "GB18030", "GB 18030"], verbatimEntry("GB 18030-2000"));
-  add(["KS X 1001", "KSX1001", "KS C 5601"], verbatimEntry("KS X 1001"));
-  add(["CNS 11643-1992", "CNS 11643"], verbatimEntry("CNS 11643-1992"));
-  add(["BIG-5", "BIG5"], verbatimEntry("BIG-5"));
-  add(["UNICODE UTF-16", "UTF-16"], verbatimEntry("UNICODE UTF-16"));
-  add(["UNICODE UTF-32", "UTF-32"], verbatimEntry("UNICODE UTF-32"));
-  return table;
-}
-var CHARSET_TABLE = buildTable();
-var DEFAULT_RESOLUTION = Object.freeze({
-  canonical: "ASCII",
-  treatment: "decode",
-  decoder: "utf-8",
-  recognized: true
-});
-function resolveCharset(raw) {
-  if (raw === void 0) return DEFAULT_RESOLUTION;
-  const key = normalizeLabel(raw);
-  if (key === "") return DEFAULT_RESOLUTION;
-  const entry = CHARSET_TABLE.get(key);
-  if (entry !== void 0) {
-    return {
-      canonical: entry.canonical,
-      treatment: entry.treatment,
-      decoder: entry.decoder,
-      recognized: true
-    };
-  }
-  return { canonical: key, treatment: "verbatim", decoder: "", recognized: false };
-}
-function canonicalCharset(raw) {
-  return resolveCharset(raw).canonical;
-}
-
 // src/parser/normalize.ts
 var CHARSET_POSITION = { segmentIndex: 0, fieldIndex: 18 };
 function preserveVerbatim(input) {
@@ -928,8 +962,8 @@ function analyzeMessageStructure(messageCode, triggerEvent, presentSegmentNames)
   if (def === void 0) {
     return Object.freeze({
       recognized: false,
-      messageCode,
-      triggerEvent,
+      messageCode: boundedIdentifier(messageCode, "segmentId"),
+      triggerEvent: boundedIdentifier(triggerEvent, "segmentId"),
       expectedGroups: Object.freeze([]),
       missingGroups: Object.freeze([])
     });
@@ -2161,7 +2195,24 @@ var EMPTY_REP = Object.freeze({
 
 // src/model/segment.ts
 var Segment = class {
-  /** Segment name (3 chars, e.g. `"PID"`, `"OBX"`, `"ZPI"`). */
+  /**
+   * Segment identifier: three characters with a leading letter, e.g. `"PID"`,
+   * `"OBX"`, `"ZPI"`.
+   *
+   * **Bounded, and it is `"<withheld>"` when the raw name is not that shape.**
+   * A line with no field separator has its whole content read as a segment
+   * name, so an unescaped line break inside a narrative field forges a
+   * "segment" whose name is clinical text. This field presents itself as a
+   * structural identifier and consumers interpolate it into labels, loci and
+   * reports, so it never carries that text. `""` still means absent, which is
+   * a different fact from withheld.
+   *
+   * Use {@link Segment.raw}`.name` when you need the verbatim text: it is the
+   * unbounded value, and it is what serialization emits, so the byte-verbatim
+   * round-trip is unaffected. One consequence worth knowing: a segment whose
+   * raw name fails the shape (a 4-character vendor Z-segment, which HL7 v2
+   * Ch. 2 §2.5 does not permit) is not matched by `msg.segments(name)`.
+   */
   type;
   /** Reference to the underlying `RawSegment.fields`: 1-indexed per HL7 convention. */
   fields;
@@ -2194,7 +2245,7 @@ var Segment = class {
    */
   constructor(raw, enc, absoluteIndex, customFields) {
     this.raw = raw;
-    this.type = raw.name;
+    this.type = boundedIdentifier(raw.name, "segmentId");
     this.fields = raw.fields;
     this.enc = enc;
     this.absoluteIndex = absoluteIndex;
@@ -3885,6 +3936,16 @@ var Hl7Message = class {
    */
   rawSegments;
   encodingCharacters;
+  /**
+   * HL7 version the model asserts for this message, from MSH-12.1.1, e.g.
+   * `"2.5"` or `"2.5.1"`.
+   *
+   * **Bounded, and it is `"<withheld>"` when MSH-12 does not hold a version.**
+   * Same reasoning as {@link Segment.type}: it presents as an identifier and
+   * consumers label with it. `meta.version` keeps MSH-12 exactly as it
+   * arrived, and is what version-scoped field selection reads, so this bound
+   * changes no parsing behaviour.
+   */
   version;
   warnings;
   profile;
@@ -3955,7 +4016,7 @@ var Hl7Message = class {
   constructor(init) {
     this.rawSegments = init.segments;
     this.encodingCharacters = init.encodingCharacters;
-    this.version = init.version;
+    this.version = boundedIdentifier(init.version, "version");
     this.warnings = Object.freeze(init.warnings.slice());
     this.profile = init.profile;
     if (init.customSegments !== void 0) this._customSegments = init.customSegments;
@@ -4793,7 +4854,12 @@ function resolveBufferCharset(raw, options, emit) {
       emit(
         encodingMismatch(
           { segmentIndex: 0 },
-          `options.charset="${override}" disagrees with MSH-18="${declared}"`
+          // `declared` is MSH-18 read off the wire. On a message with no
+          // segment terminators it is not MSH-18 at all but the 18th
+          // `|`-token of the flattened message, commonly a data field, so it
+          // is shape-checked before it reaches a log surface. `override` is
+          // the caller's own `options.charset`, not input, and is left alone.
+          `options.charset="${override}" disagrees with MSH-18="${safeCharsetLabel(declared)}"`
         )
       );
     }
@@ -6808,7 +6874,7 @@ async function* parseStream(source, optionsOrProfile) {
 }
 
 // src/index.ts
-var VERSION = "0.0.3";
+var VERSION = "0.0.5";
 
 exports.ACK_CODES = ACK_CODES;
 exports.ACK_CONDITIONS = ACK_CONDITIONS;