@cosyte/hl7 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -15,6 +15,146 @@ 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.
+
+- **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
+  `npm i @cosyte/hl7` receives them, so what a consumer's editor renders on hover is public
+  surface and the founder directive of 2026-07-27 applies to it. Re-measured with the shipped
+  rules before the change: **293 distinct lines** across tracked `src/*.ts` (253 phase-rule, 39
+  identifier-rule, 5 ADR, 1 jargon, 1 traceability marker), of which a local build carried
+  **164 distinct lines into `dist/index.d.ts`** (137 phase-rule, 22 identifier-rule, 5 ADR,
+  1 jargon, 1 traceability). After: **0 on every rule, in `src/` doc comments and in both built
+  declaration files.** A consumer hovering `parseHL7`, `defineProfile`, `Medication` or
+  `buildMessage` no longer reads which internal phase built it. Every `Plan N` build-order
+  reference was swept in the same pass, by hand, and **the built declaration file now carries
+  none**: no rule catches them, and they contradicted the `CLAUDE.md` sentence this change adds.
+  For scale, the base commit's build carried 28 such lines, from 61 doc-comment lines in `src/`.
+
+  **Identifiers were translated, never deleted, and no public export lost its documentation.**
+  That is measured, not asserted: the built `dist/index.d.ts` carries **691 doc-comment blocks,
+  633 documented declarations and 237 `@example` blocks before and after, and the sorted list of
+  documented declaration names is byte-identical.** Heads left behind by a front-of-line strip
+  were repaired: nine composite parsers wrapped `HL7-VALUE-REDECODE)` onto a continuation line,
+  where a naive strip leaves `). Absent / empty components are OMITTED`.
+
+  **Stripping the framing exposed a false claim on a published API, which is the argument for
+  doing this at all.** `defineProfile`'s doc block in `dist/index.d.ts` told consumers that
+  `opts.extends` was "ACCEPTED but IGNORED, resulting in `lineage === [opts.name]` regardless".
+  The implementation merges parents (lineage, `dateFormats`, `customSegments`, `description`,
+  composed `onWarning`) and re-validates the merged result. The text now describes what the
+  function does. Four sibling claims of the same kind were also stale and are gone: `emitMessage`,
+  `emitPrettyPrint`, `emitJson` and `buildMessage` were each documented as an unimplemented stub
+  ("Stub throws", "Implementation lives in..."), and all four have been implemented for some time.
+  Internal framing is where stale claims hide, which is why this is a correctness change and not
+  a tidying one.
+
+  **The gate now has a third pass** with its own rule array, its own extractor and its own
+  positive/negative self-tests written in the language of source rather than markdown. It scans
+  `/** */` text only, line by line and again over the block reflowed the way a hover tooltip
+  reflows it, because multi-token rules are blind to a violation that straddles a wrap and this
+  package wraps its doc comments. `//` and `/* */` comments are deliberately **not** covered and
+  keep their identifiers: they do not reach `dist` (checked both directions), and the convention
+  names source comments as a place identifiers belong. 61 such lines remain in `src/` by choice.
+
+  Every claim above was checked RED against a seeded violation rather than assumed: a single-line
+  violation in an exported function's JSDoc; a violation split across a wrap that a line-only
+  grep scores 0 on; the same bookkeeping in a `//` comment staying green; widening the source
+  identifier rule to the `WORD-N` shape failing its own negative self-test naming `MSH-2`; an
+  extractor that strips the comment leader before testing the terminator reporting 66 false hits
+  on a clean tree; and an extractor that yields nothing refusing to report green.
+
+  **The ceiling is stated rather than implied shut, and "0 on all six rules" is a statement about
+  these rules, not about the founder's rule.** Measured on the built `dist/index.d.ts`, what still
+  ships is **144 lines carrying `D-NN` internal decision numbers** and **51 lines carrying item
+  identifiers from nine prefixes the list does not hold** (`HELPERS` 14, `BIP` 15, `PROF` 8,
+  `SER` 6, `MODEL` 4, `PARSE`, `WR`, `TOL`, `TYPES` 1 each). `D-NN` is the deliberate
+  non-catch it has always been, because legacy SNOMED RT codes are axis-prefixed in exactly that
+  shape (`D-13000`, `T-32000`, `M-80003`). The item identifiers need new prefixes added to the
+  list, which is a **rule** change needing its own negative self-tests (`SER`, `WR`, `TOL` and
+  `BIP` are exactly the short generic tokens that made `PKG` unsafe), so it is not smuggled in on
+  the back of a prose sweep. Separately, `dist/` is untracked build output, so no checked-in gate
+  can read it: this gates dist's _source_, which holds only because the dts build copies doc text
+  verbatim, and the `164` figure is a hand-taken snapshot. Two "the per-X slice of Y" false
+  positives, where `slice` means portion, were fixed by rewording rather than by narrowing the
+  rule.
+
+  Documentation, tooling and CI only. No change to the published package surface, parser
+  behavior, or warning codes.
+
+- **Public-surface hygiene gate in CI (`scripts/check-no-internal-refs.sh`,
+  `pnpm check:no-internal-refs`, `.github/workflows/no-internal-refs.yml`;
+  `PUBLIC-SURFACE-HYGIENE`).** Founder directive of 2026-07-27: no internal project bookkeeping on
+  any surface a consumer reads. The remediation half of that directive was a sweep of 149 references
+  across 11 repos, and a sweep regresses the first time someone writes `(CCDA-P8)` into a README, so
+  the deliverable here is the gate; the sweep rides along. **50 violating lines across 15
+  `docs-content/` pages were cleared** (re-measured with the shipped rules against the previous tree;
+  the backlog's count of 44 was markdown-only and predates two of the rules): phase identifiers in
+  page titles and headings, `HL7-N` / `HL7-J` / `HL7-ESC` / `HL7-R` / `VERIFY-AT-BUILD` item
+  identifiers, a citation of `operations/roadmaps/hl7.md`, bracketed spec-trace tags (`[S-NTE]`,
+  `[S-DTM-IMPL]`), an "Open-question #12", and review-process commentary ("All confirmed 3-0
+  (pass 5)", "all verified 3-0 in the research pass", "Assumption logged"). One more, in `README.md`,
+  was fixed by hand and is caught by no rule: a pointer to "the roadmap's known-limitations", a file
+  the reader does not have. Identifiers were translated at the boundary, not merely deleted, and
+  every head left behind by a front-of-line strip was repaired: a heading cut to `: datetime
+precision` reads worse than the text it replaced. The datetime page needed more than a strip: with
+  its phase framing gone it read as documentation of shipped behaviour while still describing, in the
+  present tense, a `parseHl7TsDtm` zero-fill defect that no longer exists in the library (the API it
+  planned has shipped). It is now written as what the package does, its unexecuted plan and test
+  bookkeeping are gone, and a provenance claim that survived the strip in a stronger form than the
+  original ("all verified against primary Ch. 2A") is removed rather than reworded. The detection
+  rules are lifted
+  from `cosyte/.github` `scripts/release-notes.mjs`, which is already tested byte-for-byte against
+  the 14 published release bodies, and they are **keyed on known project prefixes, never on the
+  `WORD-N` shape**: `MSH-2`, `PID-3`, `OBX-5`, `TQ1-7`, `NM1-03`, `PKG-4`, `ICD-10-CM`, `HL7-V2`,
+  `FHIR-R4`, `DICOM-SR`, `NCPDP-SCRIPT`, `FHIR-bridge`, `HL7-defined` and the four `CSP`
+  Clinical Study **Phase** field names are the reference material an HL7 parser's docs exist to
+  provide, and a shape rule deletes them. That is asserted, not assumed: the script carries a
+  **negative** self-test per rule, built from that material, alongside the positive one, so widening
+  a rule into the `WORD-N` shape reds the gate instead of silently corrupting a segment reference on
+  the next sweep. Where a rule could not be guarded it was **cut** instead: `phase` after a
+  determiner ("the non-goals of this phase") is not detected at all, because catching it also caught
+  "the phase of the clinical study" and "the phase of illness", and when the collision is
+  with clinical reference material the reference material wins. The scan harness is the em-dash gate's,
+  in mllp's variant: scan list built and `./`-prefixed in one loop so the scan stays a single command
+  with stderr bound to all of it, no `sed -z`, no `-d skip`, no `-I`, `-e`/`--`, `-0 -r`, and a
+  refusal to print OK from an empty list, an unreadable input, a non-regular-file entry, or any
+  scanner stderr. Every one of those routes was checked RED against a seeded violation rather than
+  inherited. **Every rule is also applied a second time to paragraph-joined text**, because the rules
+  are multi-token and this repo hard-wraps markdown: a violation straddling a wrap was invisible to a
+  line scan and one was live (`A future phase` / `may add opt-in decode`, with the gate printing OK).
+  The join squeezes whitespace the way markdown does, which is load-bearing rather than cosmetic: a
+  verbatim join leaves the continuation line's indentation in place, and about 600 lines of
+  `docs-content/` start indented, so the pass would have missed the dominant wrap shape while
+  reporting that it ran.
+  It scans the public surface only (`README.md`, `TRADEMARKS.md`, `LICENSE`, `docs-content/`, and the
+  npm `description` and `keywords`) because the same identifier is required on the inside:
+  `CHANGELOG.md`, `.changeset/`, commits and PRs are where it belongs. A tripwire refuses the run if
+  `package.json`'s `files` starts shipping anything the gate does not cover. **Three holes are measured and disclosed rather than implied
+  shut:** `dist/` ships the compiled JSDoc, and the tracked `src/*.ts` files carry 253 phase-rule and
+  39 identifier-rule lines, of which a local build puts 137 and 22 into `dist/index.d.ts` for every
+  consumer's editor to render, unswept and ungated here because remediating ~290 source doc comments
+  is its own reviewable change (**that change is the entry above, which swept them and added the
+  third pass**; `dist/` is untracked, so no checked-in gate can re-derive that figure without
+  building first, and that part is still true); determiner-plus-`phase` is not detected, by choice;
+  and the rules catch identifiers, not English sentences about our process. Documentation and CI only: no change to the
+  published package surface, parser behavior, or warning codes.
 - **Em-dash brand gate in CI (`scripts/check-no-emdash.sh`, `pnpm check:no-emdash`,
   `.github/workflows/no-emdash.yml`; `EMDASH-CONFORMANCE` part 1).** The founder directive of
   2026-07-24 (`knowledgebase/06-brand/voice-and-tone.md`) bans `U+2014` outright across every cosyte
@@ -310,6 +450,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,5 @@
+![@cosyte/hl7: parse real-world, vendor-quirky HL7 v2 messages and extract the fields you need in one line](https://cosyte.com/social/cosyte-banner-hl7-1200x300.png)
+
 # @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 +7,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 +39,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.
 
 ---
@@ -251,7 +253,7 @@ for (const charge of parseHL7(raw).charges()) {
 }
 ```
 
-These are **breadth** helpers: they surface the common trigger events' core fields, not a scheduling-workflow state machine, signature verification, or a claims/pricing engine (see the roadmap's known-limitations).
+These are **breadth** helpers: they surface the common trigger events' core fields, not a scheduling-workflow state machine, signature verification, or a claims/pricing engine (see the known limitations in the docs).
 
 ### Order & medication timing
 
@@ -739,7 +741,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 +762,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`