@cosyte/hl7 0.0.10 → 0.1.1

package/README.md

@@ -1,7 +1,7 @@
 <a href="https://cosyte.com">
   <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">
+    <img alt="The Cosyte logo on its own white ground: the icon beside the word Cosyte." src="https://cosyte.com/tile/cosyte-lockup-tile-on-light-1200x300.png">
   </picture>
 </a>
 
@@ -18,25 +18,112 @@ A developer-focused HL7 v2 parser and utility library for Node.js and TypeScript
 
 ---
 
-## Quickstart
+## Contents
+
+- [Why this exists](#why-this-exists)
+- [Status](#status)
+- [Install](#install)
+- [Usage](#usage)
+- [PHI and safety](#phi-and-safety)
+- [Features](#features)
+- [HL7 in 90 seconds](#hl7-in-90-seconds)
+- [Access patterns](#access-patterns)
+- [Cookbook](#cookbook)
+- [Profiles](#profiles)
+- [Real-World Tolerance](#real-world-tolerance)
+- [Error Handling](#error-handling)
+- [Roadmap](#roadmap)
+- [Contributing](#contributing)
+- [Trademarks](#trademarks)
+- [License](#license)
 
-Three lines of useful output after install + parse. No HL7 spec knowledge required.
+---
+
+## Why this exists
+
+HL7 v2 is the format hospital systems actually speak, and reading one field out of it usually costs you a detour through a 2,000-page specification to learn that the patient's medical record number is `PID-3.1` and the message time is `MSH-7`. This library is for the application developer who has to consume that traffic and would rather not become an HL7 expert first: `msg.patient?.mrn` and `msg.meta.timestamp` are the whole learning curve. The nearest alternative is splitting on `|` and `^` yourself, or reaching for a parser that hands back a positional tree and still expects you to know the segment and field numbers. Those give you structure; this gives you the fields, keeps the positional tree underneath for when you need it, and treats vendor-quirky real-world input as the normal case rather than an error.
+
+---
+
+## Status
+
+`0.1.0`. The public API is settled and safe to depend on: the exported functions, the message and helper surfaces, and the 20 stable warning codes are what the version claims, and renaming a warning code counts as a breaking change here.
+
+Nothing is queued as forthcoming: [Roadmap](#roadmap) below names no future work, only what is permanently out of scope. `parseStream` parses multi-GB batch files incrementally and yields the messages as an async iterable, and `emitMessageSchema` produces JSON Schema and Zod descriptions of what `toJSON()` returns. Both are exported, so both are covered by the stability claim above.
+
+The opt-in structural validator ships too: `validateMessageStructure(msg)` enforces segment ordering and cardinality against HL7's published message structures. See [Check a message against HL7's published shape](#check-a-message-against-hl7s-published-shape-validatemessagestructure).
+
+Typed message overlays ship and are covered by the stability claim: `msg.is("ADT^A01")` answers from the message type the parser extracted and narrows the message for the compiler, so the accessors after the check are scoped to the segments that message type's published structure requires. See [Narrow a message to its type](#narrow-a-message-to-its-type).
+
+---
+
+## Install
 
 ```bash
 # pnpm (recommended). Also works with: npm install @cosyte/hl7  |  yarn add @cosyte/hl7
 pnpm add @cosyte/hl7
 ```
 
+Requires Node `>=22`. The package ships dual ESM and CommonJS builds with type declarations for both, so `import` and `require` both work and neither needs a compatibility shim. There are zero runtime dependencies: the Node standard library is all it loads.
+
+---
+
+## Usage
+
+Parse a message, read fields off it. No HL7 spec knowledge required.
+
 ```ts
 import { parseHL7 } from "@cosyte/hl7";
 
-const msg = parseHL7(rawHL7);
-console.log(msg.patient?.fullName); // "John Q. Doe"
-console.log(msg.patient?.mrn); // "MRN12345"
-console.log(msg.meta.timestamp?.raw); // "20260419101500" (fidelity TS: precision + zone preserved)
+// A synthetic ADT^A01 admit. HL7 v2 ends every segment with a carriage return.
+const raw =
+  "MSH|^~\\&|EPIC|MAIN|LIS|REF|20260419101500||ADT^A01^ADT_A01|MSG00001|P|2.5\r" +
+  "EVN|A01|20260419101500\r" +
+  "PID|1||MRN12345^^^HOSP^MR||Doe^John^Q||19800115|M|||123 Main St^^Boston^MA^02101||^PRN^PH^^^617^5551212\r" +
+  "PV1|1|I|ICU^101^A^HOSP|||||ATTEND^Smith^Jane^^^^MD|||||||||||VISIT001\r";
+
+const msg = parseHL7(raw);
+
+console.log("Patient record number:", msg.patient?.mrn);
+console.log("Full name:", msg.patient?.fullName);
+console.log("Date of birth:", msg.patient?.dateOfBirth?.raw);
+console.log("Precision:", msg.patient?.dateOfBirth?.precision);
+console.log("Message type:", msg.meta.type);
+console.log("Sent at:", msg.meta.timestamp?.raw);
+console.log("Ward:", msg.visit?.location?.pointOfCare);
 ```
 
-That's the whole pitch: no config, no schema upload, no spec lookup. The parser accepts vendor-quirky input by default, strips MLLP framing if it's there, normalises casing, and tolerates the dozen-or-so deviations real HL7 traffic routinely carries. You reach for strict mode, dot-paths, or profiles when you want them, not before.
+```text
+Patient record number: MRN12345
+Full name: John Q Doe
+Date of birth: 19800115
+Precision: day
+Message type: ADT^A01^ADT_A01
+Sent at: 20260419101500
+Ward: ICU
+```
+
+The test suite reads that block out of this README, runs it against the package, and fails if the output above ever stops matching what the code prints. The message is a copy of a synthetic fixture from the repository's test corpus.
+
+Note `precision`: a birth date is a day, not an instant, and every datetime is a fidelity `TS` that keeps the precision and timezone it arrived with rather than guessing a `Date`.
+
+That is the whole pitch: no config, no schema upload, no spec lookup. The parser accepts vendor-quirky input by default, strips MLLP framing if it's there, normalises casing, and tolerates the dozen-or-so deviations real HL7 traffic routinely carries. You reach for strict mode, dot-paths, or profiles when you want them, not before.
+
+---
+
+## PHI and safety
+
+HL7 v2 messages carry patient data, so what this library does with the bytes you hand it is part of its contract.
+
+**It does not log.** There is no logger, no debug channel and no `console` call anywhere in the library: diagnostics are returned to you, never printed. Tolerated deviations come back as `Hl7ParseWarning` values carrying a stable code, a bounded message and a position (`segmentIndex`, `fieldIndex`), never the field value that triggered them, so a warning is safe to log as-is.
+
+**One field is an exception, and it is deliberate.** `Hl7ParseError.snippet` carries up to 40 characters of your input verbatim and unredacted so a fatal parse failure is actionable. It is the only field that echoes input without filtering, the library does not redact it, and it is the first thing to strip if your compliance posture requires it. `Hl7ParseError.message` is bounded rather than absolutely content-free: it echoes a token only where the token matches a shape the spec defines (a three-character segment identifier, a message type, a version, a known charset label) and withholds anything else.
+
+**It retains nothing you do not hold.** Parsing returns an `Hl7Message` and the message content lives on that object and nowhere else. There is no cache, no pool and no module-level store of message data, so the content is released when you drop your reference to it. The one piece of process-wide state the library keeps is an optional registered default profile, which holds parsing configuration, not patient data.
+
+**It writes nothing and sends nothing.** No file is opened, no directory is written and no network connection is made: the library imports only `node:buffer` and `node:crypto` from the standard library and has zero runtime dependencies. `parseStream` reads a stream you supply and opens nothing itself. `toString()`, `toJSON()` and `prettyPrint()` hand the message content back to you by design; where it goes next is your call, and `prettyPrint()` in particular is a debug view of real patient data, not a redacted one.
+
+**What stays yours.** Transport security, storage, retention and audit, redaction before anything reaches a log or an error tracker, and access control are all the consuming application's. A parser cannot make a system HIPAA-compliant, and this one does not claim to.
 
 ---
 
@@ -44,6 +131,8 @@ 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.
+- **Typed message overlays**: `msg.is("ADT^A01")` answers at run time and narrows at compile time, so the message code and trigger event become literal types and `part` / `parts` are scoped to the segments that message type's published structure requires. No cast, no per-message-type import.
+- **Opt-in published-structure validation**: `validateMessageStructure(msg)` checks segment order, occurrence counts and unnamed segments against HL7's own published message structures, derived offline from a vendored snapshot. Read-only, no new warning code, and nothing changes for a caller who does not ask.
 - **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).
@@ -62,7 +151,7 @@ A typical ADT message looks like this:
 Message
  ├── MSH    (header: sender, receiver, type, timestamp)
  ├── EVN    (event details for ADT)
- ├── PID    (patient identification: name, MRN, DOB)
+ ├── PID    (patient identification: name, record number, DOB)
  ├── PV1    (visit: class, location, attending)
  └── OBX×N  (observations: repeats for labs, vitals)
 
@@ -143,7 +232,7 @@ Runnable recipes for the tasks developers hit most often. Every snippet imports
 
 ### Patient demographics
 
-Reach for the `msg.patient` helper for the name/MRN/DOB trio that covers 95% of demographic extractions.
+Reach for the `msg.patient` helper for the name, record-number and date-of-birth trio that covers 95% of demographic extractions.
 
 ```ts
 import { parseHL7 } from "@cosyte/hl7";
@@ -215,7 +304,7 @@ const outbound = msg.toString(); // spec-clean HL7 wire format
 
 ### Allergies
 
-`msg.allergies()` walks every `AL1` segment and returns a typed list.
+`msg.allergies()` walks every `AL1` and every `IAM` segment and returns a typed list, one entry per segment in document order. An ADT^A60 carries its allergies in `IAM` and no `AL1`, so it is read too. Each entry names the segment it came from in `source`.
 
 ```ts
 import { parseHL7 } from "@cosyte/hl7";
@@ -223,12 +312,26 @@ import { parseHL7 } from "@cosyte/hl7";
 const msg = parseHL7(raw);
 
 for (const al of msg.allergies()) {
-  console.log(al.code?.text, al.severity, al.reaction);
-  // "Penicillin" "SV" "Hives"
+  console.log(al.source, al.code?.text, al.severity, al.reaction);
+  // "IAM" "Penicillin" "SV" "Hives"
+  if (al.deleteRequested === true) {
+    // IAM-6 was "D": the sender asks you to delete the allergy it sent earlier
+    // under al.uniqueIdentifier?.entityIdentifier. Nothing was deleted for you.
+  }
 }
 ```
 
-Fields are parsed into their spec-typed shapes (`code` is a `CWE` composite, `onsetDate` is a fidelity `TS`). The same helper family exists for next-of-kin (`msg.nextOfKin()`), diagnoses (`msg.diagnoses()`), insurance (`msg.insurance()`), medications (`msg.medications()`), and immunizations (`msg.immunizations()`).
+Fields are parsed into their spec-typed shapes (`code` is a `CWE` composite, `onsetDate` is a fidelity `TS`). An `IAM` entry also carries `actionCode` (IAM-6 exactly as sent, absent when IAM-6 is empty rather than assumed to be `A`) and `uniqueIdentifier` (IAM-7 components 1 and 2).
+
+What it does not do:
+
+- It never applies an action. A `D` entry is still returned, marked `deleteRequested: true`; a `U` entry never replaces an earlier one; an `AL1` and an `IAM` for the same allergen are two entries. The library holds no allergy list to apply them to, so that is the receiver's call.
+- It does not read the `IAR` (adverse reaction) or `NTE` segments under an `IAM`, nor IAM-1 or IAM-8 onward, and it reads IAM-2 and IAM-4 as component 1 and IAM-5 as its first repetition. Reach the rest with `msg.segments("IAM")`.
+- A missing IAM-7 is left missing: IAM-3 is never used in its place.
+
+The same helper family exists for next-of-kin (`msg.nextOfKin()`), diagnoses (`msg.diagnoses()`), insurance (`msg.insurance()`), medications (`msg.medications()`), and immunizations (`msg.immunizations()`). Each medication carries `orderControl`, the ORC-1 order control of the `ORC` that opened its order group (`NW`, `DC`, `HD` and so on) exactly as sent, never an interpreted state such as active, held or discontinued, and absent when no `ORC` opens the group or ORC-1 is empty.
+
+Each immunization carries `administrationStatus`, read from that RXA's own RXA-21, RXA-5 and RXA-20: `completed` for a dose given (RXA-20 `CP` or `PA`), `not-done` for a refused or not-administered dose (`RE` or `NA`), `no-vaccine-administered` for a CVX `998` placeholder, `delete-requested` for an RXA-21 `D` asking to delete an administration sent earlier, and `undetermined` for anything not exactly mapped, never `completed`. The raw RXA-20 and RXA-21 codes ride beside it with the field and table that decided. It is reported, never applied: a `D` record is still returned and nothing is removed. See the [immunization status notes](./docs-content/spec-notes-immunization-status.md).
 
 ### Scheduling, documents & charges (SIU · MDM · DFT)
 
@@ -283,7 +386,9 @@ The repeat pattern (Table 0335) is surfaced **verbatim**: hl7 never normalizes a
 
 ### Patient merges and identity events
 
-`msg.identityEvents()` recognizes the ADT identity-management trigger events: merges (A18/A34/A35/A36/A39/A40/A41/A42), moves (A43/A44), link/unlink (A24/A37), and person add/update (A28/A31). It surfaces every party **labelled by role**. On a merge, the MRG segment carries the _prior_ (non-surviving) identifiers and the PID carries the _surviving_ ones; the direction is the spec constant `MRG_TO_PID` and is never inferred from content.
+`msg.identityEvents()` recognizes the ADT identity-management trigger events: merges (A18/A34/A35/A36/A39/A40/A41/A42), moves (A43/A44/A45), identifier changes (A47/A49/A50/A51), link/unlink (A24/A37), and person add/update (A28/A31). It surfaces every party **labelled by role**. On a merge, move or change, the MRG segment carries the _prior_ (non-surviving) identifiers and the PID carries the _surviving_ ones; the direction is the spec constant `MRG_TO_PID` and is never inferred from content.
+
+The recognized set is floored by the published message structures: every ADT trigger event whose structure requires an MRG segment is recognized, so the read side cannot fall behind the structures the parser validates against. `kind` stays meaningful across that floor: an identifier change (`"change"`) replaces one identifier on one record and is never reported as a `"merge"`, so a consumer that acts only on `kind === "merge"` never starts conflating records on an event it did not expect.
 
 ```ts
 import { parseHL7 } from "@cosyte/hl7";
@@ -300,7 +405,7 @@ for (const ev of msg.identityEvents()) {
 }
 ```
 
-A mis-applied merge conflates two patients or orphans data under a retired MRN, so the helper is deliberately conservative: an incomplete pair (no MRG, an orphaned MRG, or a PID with no surviving identifier) surfaces whatever _is_ present plus a `MERGE_MISSING_PRIOR_OR_SURVIVOR` warning on the event: the MRG is never dropped, and the direction is never guessed. The MRG field map is version-scoped: the backward-compat single-ID fields (PID-2 / MRG-4, withdrawn as of HL7 v2.7) are not read when MSH-12 declares v2.7+. Note that `@cosyte/hl7` _surfaces_ the merge. Actually re-pointing stored data to the survivor is your integration engine's job.
+A mis-applied merge conflates two patients or orphans data under a retired record number, so the helper is deliberately conservative: an incomplete pair (no MRG, an orphaned MRG, or a PID with no surviving identifier) surfaces whatever _is_ present plus a `MERGE_MISSING_PRIOR_OR_SURVIVOR` warning on the event: the MRG is never dropped, and the direction is never guessed. The MRG field map is version-scoped: the backward-compat single-ID fields (PID-2 / MRG-4, withdrawn as of HL7 v2.7) are not read when MSH-12 declares v2.7+. Note that `@cosyte/hl7` _surfaces_ the merge. Actually re-pointing stored data to the survivor is your integration engine's job.
 
 ### Write your first profile in 10 minutes
 
@@ -427,11 +532,167 @@ hl7 preserves precision + timezone **fidelity**; it does **not** localize, conve
 timestamps. A consumer needing an absolute instant applies the sender's zone via `assumeOffsetMinutes`.
 Use `parseDtm` / `formatDtm` / `dtmToDate` directly on a raw string when you're outside the message model.
 
+#### Converting a datetime: `toObject`, `toISO`, `toDate`
+
+Three conversion helpers sit on top of the fidelity `TS`. Every `@cosyte` parser exposes these same
+three names with the same semantics, so you learn the conversion story once and it holds across the
+suite.
+
+| function                  | returns                            | gives you                                              |
+| ------------------------- | ---------------------------------- | ------------------------------------------------------ |
+| `toObject(value)`         | frozen `DateParts`, or `undefined` | the stated calendar components as a plain object       |
+| `toISO(value)`            | `string`, or `undefined`           | ISO-8601, truncated to the stated precision            |
+| `toDate(value, options?)` | `Date`, or `undefined`             | an absolute instant, only when the zone is determinate |
+
+```ts
+import { parseDtm, toObject, toISO } from "@cosyte/hl7";
+
+toObject(parseDtm("19880705"));
+// { year: 1988, month: 7, day: 5 }: exactly the stated components, nothing zero-filled
+
+toISO(parseDtm("19880705")); // "1988-07-05": truncated to the stated precision, no fabricated Z
+toISO(parseDtm("20250102153045.5-0500")); // "2025-01-02T15:30:45.5-05:00": digits verbatim
+```
+
+`toObject` carries only the components the value stated, so `Object.keys()` recovers its precision and
+nothing is invented: no `raw`, no `valid`, no `precision`. `month` is spec-native 1 to 12, which is
+exactly what `Temporal.PlainDateTime.from({...})` and luxon's `DateTime.fromObject({...})` accept:
+delete `offsetMinutes` and hand the rest over with no key rename and no value adjustment. Neither
+library is a dependency here, and neither needs to be. `millisecond` is the first three fractional
+digits taken verbatim and right-padded, so `.5` is 500 ms and `.0500` is 50 ms, never a float
+multiplication that loses the last digit. `offsetMinutes` appears if and only if the value carried an
+explicit offset, and is never synthesised from the host machine's zone.
+
+**`toDate` never guesses a zone.** An offset-less value returns `undefined` unless you say which zone
+it was written in:
+
+```ts
+import { parseDtm, toDate } from "@cosyte/hl7";
+
+toDate(parseDtm("20250102")); // undefined: no offset stated, and none assumed
+toDate(parseDtm("20250102"), { assumeOffsetMinutes: 0 }); // 2025-01-02T00:00:00.000Z: you chose UTC
+toDate(parseDtm("20250102"), { assumeOffsetMinutes: -300 }); // 2025-01-02T05:00:00.000Z
+
+// A stated offset always wins, and assumeOffsetMinutes is ignored rather than blended:
+toDate(parseDtm("20250102153045-0500")); // 2025-01-02T20:30:45.000Z
+toDate(parseDtm("20250102153045-0500"), { assumeOffsetMinutes: 600 }); // the same instant
+```
+
+The host machine's timezone is never read and UTC is never assumed, so the answer does not depend on
+where your code ran. Components below the stated precision fill to their lowest legal value for the
+instant only, leaving the value's own precision untouched, and a four-digit year below 100 stays that
+year (`00500101` is year 50, never 1950).
+
+**An offset that is not a finite number is no offset at all.** `assumeOffsetMinutes` is signed
+minutes east of UTC, and anything else names no zone, so `toDate` answers `undefined` rather than
+coercing it into one. That matters from JavaScript, where the type is not checked for you:
+
+```ts
+import { parseDtm, toDate } from "@cosyte/hl7";
+
+const dob = parseDtm("20240229"); // day precision, no offset stated
+
+toDate(dob, null); // undefined: no options bag is not a zone, and this does not throw
+toDate(dob, {}); // undefined: same answer as passing nothing
+toDate(dob, { assumeOffsetMinutes: "0" }); // undefined: a string is not a number of minutes
+toDate(dob, { assumeOffsetMinutes: Number.NaN }); // undefined: neither is NaN
+
+toDate(dob, { assumeOffsetMinutes: 0 }); // 2024-02-29T00:00:00.000Z: a real choice, honoured
+```
+
+`"0"`, `true` and `[]` all multiply to `0` in JavaScript, so a converter that simply did the
+arithmetic would hand back a UTC instant nobody asked for, which is the guess this surface exists to
+refuse. An offset large enough to leave the range a `Date` represents is refused the same way, so no
+answer is ever an `Invalid Date`. A value that states its own offset is unaffected: its offset wins
+outright, so an unusable assumption beside one is ignored rather than fatal.
+
+**`toISO` renders, `formatDtm` round-trips.** A stated zero offset renders as `Z`, including HL7's
+`-0000` form, so the two answers differ by design and `formatDtm` remains the byte-exact route back to
+the wire:
+
+```ts
+import { formatDtm, parseDtm, toISO } from "@cosyte/hl7";
+
+const ts = parseDtm("20250102153045-0000");
+toISO(ts); // "2025-01-02T15:30:45Z"
+formatDtm(ts); // "20250102153045-0000": byte-exact, sign preserved
+```
+
+All three return `undefined` rather than throwing for a value the parser marked invalid, for
+`undefined` and for `null`.
+
+**An impossible date converts to nothing, never to the day after it.** A value stating a day its
+month does not have is refused by all three, whole, rather than rolled over into the following
+month. February really has 28 days, or 29 in a leap year under the full 4/100/400 rule:
+
+```ts
+import { parseDtm, toDate, toISO, toObject } from "@cosyte/hl7";
+
+toObject(parseDtm("20240230")); // undefined: February has no 30th
+toISO(parseDtm("20230229")); // undefined: 2023 is not a leap year
+toDate(parseDtm("21000229"), { assumeOffsetMinutes: 0 }); // undefined: 2100 is not one either
+
+toISO(parseDtm("20240229")); // "2024-02-29": 2024 is, so this one converts
+```
+
+`month` is bounded 1 to 12, `day` by the month it is in, `hour` 0 to 23, and `minute` and `second`
+0 to 59. The parser itself is unchanged and stays deliberately liberal, so `parseDtm("20240230")`
+is still `valid: true` and `formatDtm` still round-trips those bytes: the refusal is in the
+conversion, which is where a wrong answer would otherwise look right. Rendering it would be worse
+than throwing, because `new Date("2024-02-30")` is 1 March in every JavaScript runtime, so a
+consumer reading the string gets a silent one-day shift instead of an error.
+
+**The offset a value states is bounded on the same terms.** When a value claims an explicit offset,
+that offset has to be a whole number of minutes within 23 hours 59 minutes of UTC, which is exactly
+what `+HH:MM` can state and what an ISO-8601 reader accepts. Anything else names no zone, so the
+value converts to `undefined` rather than being reported as an offset, rendered into a string no
+reader can read back, or turned into an instant:
+
+```ts
+import { parseHL7, toDate, toISO } from "@cosyte/hl7";
+
+// A timestamp on the wire, read by the lenient fallback, stating +99:99:
+const ts = parseHL7("MSH|^~\\&|SEND|FAC|RECV|FAC|2024-02-29T12:00:00+99:99||ADT^A01|MSG1|P|2.5\r")
+  .meta.timestamp;
+
+toISO(ts); // undefined: 6039 minutes east of UTC is no zone, and "+100:39" is unreadable
+toDate(ts); // undefined: an offset that names no zone yields no instant
+```
+
+The same bound catches an `offsetMinutes` a JavaScript caller puts on a value by hand, where a
+`"0"`, a `true` or an `[]` would otherwise multiply to `0` and answer a confident UTC instant, and
+it catches `NaN`, which would otherwise render as `+NaN:NaN`. Every real zone on Earth is far inside
+it (the widest in use is 14 hours east), a stated offset still wins outright over any
+`assumeOffsetMinutes` beside it, and `parseDtm`, `formatDtm` and `dtmToDate` are unchanged.
+
+**Using two `@cosyte` parsers in one file.** The three names are identical in `@cosyte/hl7`,
+`@cosyte/x12`, `@cosyte/dicom`, `@cosyte/ncpdp`, `@cosyte/astm` and `@cosyte/ccda`, so importing two
+of them into one file collides. Alias on import:
+
+```ts
+import { parseDtm, toISO as hl7ToISO } from "@cosyte/hl7";
+import { toISO as x12ToISO } from "@cosyte/x12";
+
+hl7ToISO(parseDtm("19880705")); // "1988-07-05"
+// x12ToISO does the same for an X12 date value: same three names, same semantics.
+```
+
+...or namespace-import, which keeps the package of origin visible at every call site:
+
+```ts
+import * as hl7 from "@cosyte/hl7";
+import * as x12 from "@cosyte/x12";
+
+hl7.toISO(hl7.parseDtm("19880705")); // "1988-07-05"
+// x12.toISO(...) is the same call, against an X12 date value.
+```
+
 #### Non-standard timestamp formats
 
-HL7's canonical `YYYYMMDDHHmmss` parses with zero warnings. Everything else (vendor-quirky
-`MM/DD/YYYY`, ISO `YYYY-MM-DD`, legacy `YYYYMMDD HHmm`) parses via the `dateFormats` option, which
-tries each format in order and populates the same fidelity `TS`.
+HL7's canonical `YYYYMMDDHHmmss` parses with zero warnings. For everything else (vendor-quirky
+`MM/DD/YYYY`, ISO `YYYY-MM-DD`, legacy `YYYYMMDD HHmm`), tell the parser what your sender writes
+using the `dateFormats` option. Each format is tried in order, the first match wins, and it
+populates the same fidelity `TS`.
 
 ```ts
 import { parseHL7 } from "@cosyte/hl7";
@@ -440,10 +701,72 @@ const msg = parseHL7(raw, {
   dateFormats: ["MM/DD/YYYY HH:mm:ss", "MM/DD/YYYY", "YYYY-MM-DD"],
 });
 
-console.log(msg.meta.timestamp?.matchedFormat); // e.g. "MM/DD/YYYY" (which fallback won)
+console.log(msg.meta.timestamp?.matchedFormat); // e.g. "MM/DD/YYYY": which declared format won
+console.log(msg.patient?.dateOfBirth?.matchedFormat); // the same list reaches PID-7
+```
+
+**The formats you declare reach every datetime the library returns**, not just the message header
+timestamp: `patient.dateOfBirth`, `visit.admitDateTime` / `dischargeDateTime`, each
+`observations()` entry's `observedDateTime` and its `TS`/`DT` typed value, `allergies()`
+onset dates, `diagnoses()` date/times, `insurance()` effective and expiration dates,
+`immunizations()` administered and expiration dates, `charges()` transaction dates,
+`documents()` activity date/times, order and medication `timings` (a `TQ1` segment and the legacy
+embedded `TQ` alike), and `appointments()` start and end times.
+
+`matchedFormat` is how you tell which answer you got: it names the declared format that matched,
+and is absent when the value was canonical HL7 and parsed strictly. There is no parse warning for
+either case.
+
+**Only the formats you declare are tried on those fields.** A date the parser was not told about
+stays `valid: false` with its `raw` text intact, rather than being guessed at: guessing is how a
+day-first `05/07/1988` becomes a confident May 7 on a date of birth, and a plausible wrong date is
+worse than a missing one. `BUILTIN_DATE_FALLBACKS` (ISO-8601 and the US-order slash forms) is a
+last resort for `msg.meta.timestamp` alone and never runs on a typed datetime field.
+
+A format is written from a fixed token vocabulary (`SUPPORTED_DATE_TOKENS`) that covers month names (`05-JUL-1988`), a 12-hour clock with AM/PM (`7/5/1988 2:30 PM`), single-digit tolerance (`M`, `D`, `H`) and escaped literals (`YYYY-MM-DD[T]HH:mm:ss`). It carries no two-digit-year token, because resolving one needs a century window and a wrong window moves a date of birth by a hundred years without failing. `defineProfile()` refuses a format the vocabulary cannot honour, at definition time, rather than accepting it and never matching. The whole grammar, with every token, rule and exclusion, is the `Date token grammar` page in the documentation.
+
+Built-in vendor profiles (`profiles.epic`, `profiles.genericLab`, etc.) already carry the date formats common to that vendor, and an option format is tried ahead of a profile's. Reach for a profile instead of hand-listing formats when one fits.
+
+#### Day-first vs month-first: the parser refuses to guess
+
+`05/07/1988` is 5 July to a day-first sender and May 7 to a month-first one. Both are real calendar
+dates, and nothing in the message says which was meant. When no format has been declared, the
+parser resolves **neither**: `msg.meta.timestamp` comes back `valid: false` carrying an `ambiguity`
+report that names the raw value and both readings, so a wrong date never reaches your code silently.
+
+```ts
+import { parseHL7, AMBIGUOUS_DATE_ORDER } from "@cosyte/hl7";
+
+const ts = parseHL7(raw).meta.timestamp; // MSH-7 was "05/07/1988"
+
+if (ts?.ambiguity?.code === AMBIGUOUS_DATE_ORDER) {
+  console.log(ts.ambiguity.raw); // "05/07/1988"
+  console.log(ts.ambiguity.candidates[0]); // { format: "MM/DD/YYYY", month: 5, day: 7, isoDate: "1988-05-07" }
+  console.log(ts.ambiguity.candidates[1]); // { format: "DD/MM/YYYY", month: 7, day: 5, isoDate: "1988-07-05" }
+}
+```
+
+Declaring the sender's order is the fix, and it is one line. A declared format is tried ahead of the
+built-ins, so the value resolves and no ambiguity is reported:
+
+```ts
+const dayFirst = parseHL7(raw, { dateFormats: ["DD/MM/YYYY"] });
+console.log(dayFirst.meta.timestamp?.month); // 7: 5 July 1988
+
+const monthFirst = parseHL7(raw, { dateFormats: ["MM/DD/YYYY"] });
+console.log(monthFirst.meta.timestamp?.month); // 5: May 7 1988
 ```
 
-When a fallback format wins, the parser emits a `TIMESTAMP_FALLBACK_FORMAT` warning with the matched format on `msg.warnings`. Built-in vendor profiles (`profiles.epic`, `profiles.genericLab`, etc.) already carry the date formats common to that vendor. Reach for a profile instead of hand-listing formats when one fits.
+Only genuinely two-way values are refused. `07/25/1988` has one reading (there is no month 25) and
+still resolves as July 25. `05/05/1988` has two readings that agree and still resolves. Strict HL7
+timestamps, ISO-8601 values and `YYYY-MM-DD` values are untouched. Ambiguity is also a different fact
+from malformed input: a value that is illegal under both readings reports no timestamp and no
+ambiguity.
+
+The report belongs to `msg.meta.timestamp`, because it is the built-in list that produces the second
+reading and that list runs there and nowhere else. On a typed datetime field, an undeclared
+`05/07/1988` is simply `valid: false` with its `raw` intact and no `ambiguity`: nothing tried to read
+it, so there was no guess to refuse. Declaring the order resolves it on every field at once.
 
 ### Stripping MLLP framing
 
@@ -532,9 +855,38 @@ if (msg.meta.messageCode === "ORU") {
 
 Matching on `messageCode` + `triggerEvent` is more robust than string-equals on `type`, because some senders populate MSH-9.3 (`type` includes it) and some don't.
 
+### Narrow a message to its type
+
+`msg.is("ADT^A01")` does the same comparison and tells the **compiler** the answer. Inside the guard the message code and trigger event are literal types rather than `string | undefined`, and `part` / `parts` accept only the segment names that message type's published structure marks required. No cast, and no type to import per message type.
+
+```ts
+import { parseHL7 } from "@cosyte/hl7";
+
+const msg = parseHL7(raw);
+
+if (msg.is("ADT^A01")) {
+  const code: "ADT" = msg.meta.messageCode; // literal, and no longer optional
+  const event: "A01" = msg.meta.triggerEvent;
+  console.log(code, event);
+
+  const pid = msg.part("PID"); // Segment | undefined: first PID, or none
+  const evn = msg.parts("EVN"); // readonly Segment[]: every EVN, possibly empty
+  console.log(pid?.field(3).value, evn.length);
+
+  // msg.part("OBX");                    // does not compile: ADT^A01 does not require OBX
+  console.log(msg.segments("OBX").length); // the base accessor still takes any name
+}
+```
+
+A key is `"<MSH-9.1>^<MSH-9.2>"` (`"ADT^A01"`), or `"<MSH-9.1>"` alone for a message type the published structure registry matches on message code alone (`"ACK"`, whose MSH-9.2 carries the acknowledged message's trigger event). `SUPPORTED_OVERLAY_MESSAGES` enumerates every key with the segments its structure requires, derived from that registry rather than written down.
+
+The check is on the (MSH-9.1, MSH-9.2) pair the parser extracted, so a message whose MSH-9 carries the three-component `ADT^A01^ADT_A01` still answers `true` to `is("ADT^A01")`. **Any string that is not a key returns `false` and never throws**: an unrecognized type, the three-component form as a string, an empty string, or a value computed at run time (which cannot narrow anything, so it returns a plain `boolean`). For a raw comparison, `msg.meta.type` is the string MSH-9 carried.
+
+Narrowing does not promise presence. The parser is lenient by design, and an `ADT^A01` that arrives without its `PID` still answers `true` here, still warns, and still reports the absence on `msg.structure`: `part` returns `undefined` and `parts` an empty list, exactly as `segments` does.
+
 ### Spot a truncated or misrouted message
 
-For the common message types, `msg.structure` reports whether the core segment groups the HL7 spec marks **Required** for that trigger event are actually present. It's a **misroute / truncation safety net**, not a conformance validator: an `ORU^R01` that arrives with no `OBR`/`OBX` result group is almost always truncated or sent to the wrong feed.
+For the message types it covers, `msg.structure` reports whether the segments HL7's own published message-structure definitions give a **minimum of one** for that trigger event are actually present. It's a **misroute / truncation safety net**, not a conformance validator: an `ORU^R01` that arrives with no `OBR` is almost always truncated or sent to the wrong feed.
 
 ```ts
 import { parseHL7, WARNING_CODES } from "@cosyte/hl7";
@@ -542,16 +894,43 @@ import { parseHL7, WARNING_CODES } from "@cosyte/hl7";
 const msg = parseHL7(raw); // ORU^R01 with only MSH + PID
 
 console.log(msg.structure.recognized); // true
-console.log(msg.structure.missingGroups); // ["result"]  (no OBR/OBX)
+console.log(msg.structure.missingSegments); // ["OBR"]
+console.log(msg.structure.structureIds); // ["ORU_R01-A", "ORU_R01-B", ...]
 
 // The same finding also surfaces as an additive Tier-2 warning, so a
 // channel can route on it without inspecting `structure`:
 if (msg.warnings.some((w) => w.code === WARNING_CODES.MISSING_EXPECTED_GROUP)) {
-  // quarantine / alert: the message is missing an expected segment group
+  // quarantine / alert: the message is missing an expected segment
 }
 ```
 
-The check is **conservative by construction**: it only models groups that are genuinely Required (so a conformant-but-sparse message never warns), it keys on the **trigger event** (not the message family), and a type it doesn't recognize yields `recognized: false` and emits nothing. It never throws and never rewrites the message. `strict` mode may promote the warning to an error per the usual model. Recognized types: ADT (A01/A02/A03/A04/A05/A08/A11/A13), ORU^R01, ORM^O01, OML^O21, OMG^O19, OMP^O09, OMI^O23, SIU (S12–S26), MDM (T02/T06), DFT^P03, VXU^V04, and ACK. See [`docs-content/spec-notes-structure.md`](docs-content/spec-notes-structure.md) for the per-type Required-segment sourcing.
+Expectations are **derived, not hand-picked**: the package vendors a byte-for-byte snapshot of the published structures and derives the registry from it offline, with no network call at build time or run time. `STRUCTURE_REGISTRY_PROVENANCE` carries the publication, its commit, the sha256 of every vendored file and the structure behind every recognized pair, so a warning can be audited without leaving the package.
+
+It stays conservative where the publication is: a segment inside an optional group is not expected (so a conformant `OBX`-free `ORU^R01` never warns), a segment is expected only when every published variant of the structure requires it, and a type it doesn't recognize yields `recognized: false` and emits nothing. It never throws and never rewrites the message. `strict` mode may promote the warning to an error per the usual model. Recognized message codes: ADT, ORU, ORM, OML, OMG, OMP, OMI, SIU, MDM, DFT, VXU and ACK, across 94 trigger-event pairs. See [`docs-content/spec-notes-structure.md`](docs-content/spec-notes-structure.md) for the full table, the derivation rules, and what changed for consumers.
+
+### Check a message against HL7's published shape (`validateMessageStructure`)
+
+`msg.structure` asks only whether a required segment is **present**. When the question is "does this feed follow the shape the standard publishes for this trigger event?", ask for `validateMessageStructure(msg)`: an **opt-in, read-only** check over the same vendored publication, at segment granularity. Nothing calls it for you and it changes nothing: no new warning code, no change to a parse, and the message is byte-identical afterwards.
+
+```ts
+import { parseHL7, validateMessageStructure } from "@cosyte/hl7";
+
+const result = validateMessageStructure(parseHL7(raw)); // ADT^A01 with PV1 before PID
+
+console.log(result.validated); // true
+console.log(result.structureId); // "ADT_A01-A": the variant the findings are against
+console.log(result.structureIds); // the whole variant family that was considered
+for (const f of result.findings) console.log(f.severity, f.code, f.locus.segment, f.message);
+// e.g. 'error STRUCTURE_SEGMENT_OUT_OF_ORDER PID  Segment "PID" (occurrence 0) appears where published structure ADT_A01-A does not allow it.'
+```
+
+It reports three things: `STRUCTURE_SEGMENT_OUT_OF_ORDER` (the sequence stops being a beginning the published order allows), `STRUCTURE_SEGMENT_CARDINALITY` (fewer occurrences than the published minimum along the path from the structure root, or more than the published maximum), and `STRUCTURE_SEGMENT_UNEXPECTED` (a segment the publication does not name, a `Z` segment included, at `warning` severity). Every finding carries a **PHI-free locus**: a segment name, a 0-indexed occurrence and a published structure id, never a field value.
+
+The order check reads the publication's bounds as written, at every locus: a group it lets repeat may repeat, which is what lets a conformant `ORU^R01` carry `OBR OBX OBR OBX`, a group bounded at one occurrence may not be re-entered, so a `VXU^V04` whose `PV2` arrives before its `PV1` is reported, and no occurrence of a group may begin without the child the publication requires first, so an `ADT^A01` whose `IN2` arrives before its `IN1` is reported as well. The three questions are still kept apart so one defect is reported once: the one bound dropped for a segment name is the one the cardinality check has already reported for it, so a missing or over-repeated segment does not also read as everything after it being out of place. Where two segments arrive in an order the publication does not allow, the finding names **the one that arrived late**: the segment the publication puts first and the message delivered second, which is not always where the reading stopped, because the publication is often free to skip past a segment the message delayed. The pair is found by exchanging adjacent segments and asking whether the publication derives the result, and every adjacent pair is asked rather than a shortlist near the stop: in a message that repeats a group the pair can sit well in front of it, as in an `OML^O21` carrying three orders whose first order's note is delivered after the second order's `ORC`. Where more than one pair would do, the earliest is named.
+
+**Read `validated` before `findings`.** A message type the registry does not model, the one retained transcription (`ORM^O01`), a structure with no ordered expectation and a message with no readable type each come back `validated: false` with a `reason` and no findings: "the publication cannot answer" is a different answer from "nothing was wrong". Where the publication splits a structure into variants, conforming to **one** variant conforms to the family, so findings appear only when every variant is violated and they are exactly one named variant's.
+
+> **Zero findings is not an attestation.** It means this message did not break the published structure in the three ways above. Field content, datatypes, value sets and HL7 tables are unchecked, coverage is twelve message codes, and the publication is vendored at a fixed commit. See [`docs-content/spec-notes-structure.md`](docs-content/spec-notes-structure.md).
 
 ### Validate against your own conformance profile (`validateAgainstProfile`)
 
@@ -581,7 +960,20 @@ for (const f of findings) console.log(f.severity, f.code, f.message);
 // e.g. "error PROFILE_VALUE_NOT_IN_SET  PID-8 component 1 value is not in the profile value set (3 permitted codes)."
 ```
 
-The engine holds four invariants: it **never throws** (a malformed profile yields `PROFILE_MALFORMED` findings, not an exception: use `defineConformanceProfile` for a fail-fast authoring gate that _does_ throw); a **valid message yields zero findings**; **no finding carries PHI**: each names the structural locus (segment / field / component / repetition) and the rule, never the offending value; and validation is **read-only**. Usage codes are the HL7 six (`R`/`RE`/`C`/`CE`/`O`/`X`); `C`/`CE` presence is not evaluated (no predicate language, a documented boundary). Distinct from the parse-profile system (`defineProfile`/`profiles`), which shapes _how a message is parsed_.
+The engine holds four invariants: it **never throws** (a malformed profile yields `PROFILE_MALFORMED` findings, not an exception: use `defineConformanceProfile` for a fail-fast authoring gate that _does_ throw); a **valid message yields zero findings**; **no finding carries PHI**: each names the structural locus (segment / field / component / repetition) and the rule, never the offending value; and validation is **read-only**. Distinct from the parse-profile system (`defineProfile`/`profiles`), which shapes _how a message is parsed_.
+
+A rule's usage is one of `R`/`RE`/`C`/`CE`/`O`/`X`/`B`, or a declared conditional written `C(t/f)`. A conditionally-used rule can carry a **condition predicate** that the engine evaluates against the message to decide which outcome applies: a location in the same message, a verb from the closed set (`is`, `is not`, `contains`, `does not contain`, `matches`, `does not match`) or a presence statement (`is valued`, `is not valued`), a value list _you_ supply, and `AND`/`OR`/`XOR` connectors.
+
+```ts
+// "PID-8 is Required when a date of birth was sent, Not-permitted when it was not."
+{
+  field: 8,
+  usage: "C(R/X)",
+  condition: { location: { segment: "PID", field: 7 }, presence: "is valued" },
+}
+```
+
+Still no network call and still no code set: a predicate reads the message in front of it and compares against values you wrote down. A predicate the message cannot decide (a comparison against an element that is not there) yields a `PROFILE_CONDITION_UNEVALUATABLE` finding and the element's presence is **not** assessed, rather than being guessed either way. A rule that declares no predicate can still take its outcome from a caller-supplied resolution, and declaring both at one locus is refused.
 
 > **"No findings" is not an attestation.** An empty result means _nothing this profile checked was violated_: never "this message is conformant." The profile only covers what you declared, and hl7 makes no conformance certification. See [`docs-content/spec-notes-conformance.md`](docs-content/spec-notes-conformance.md).
 
@@ -614,7 +1006,7 @@ Profiles are the growth loop. Built-ins cover the common vendor patterns; real i
 
 ### Authoring a profile
 
-`defineProfile({ name, customSegments, dateFormats, onWarning, description })` returns a frozen `Profile` object. `customSegments` is a record mapping segment name -> `{ fields: { aliasName: 1-indexedPosition } }`.
+`defineProfile({ name, customSegments, segmentOverrides, dateFormats, onWarning, description })` returns a frozen `Profile` object. `customSegments` is a record mapping Z-segment name -> `{ fields: { aliasName: 1-indexedPosition } }`; `segmentOverrides` is the same shape for STANDARD segment names (see [Naming fields on standard segments](#naming-fields-on-standard-segments)).
 
 ```ts
 import { defineProfile, type CustomSegmentDefinition } from "@cosyte/hl7";
@@ -633,6 +1025,71 @@ const myhospital = defineProfile({
 
 Invalid input (missing name, malformed Z-segment name, unsupported date tokens, unknown option keys) throws `ProfileDefinitionError` with an actionable message. See [Error Handling](#error-handling).
 
+### Naming fields on standard segments
+
+`customSegments` names fields on your Z-segments. `segmentOverrides` does the same job for the STANDARD segments, for the case every real integration eventually hits: a site that stuffs its own value into a standard field. A second MRN in PID-19, a local severity code in AL1-4, a site dose qualifier in RXA-6. Give it a name once in the profile and read it by that name everywhere, instead of scattering a hand-typed position through your code.
+
+```ts
+import { defineProfile, parseHL7 } from "@cosyte/hl7";
+
+const site = defineProfile({
+  name: "myhospital-adt",
+  segmentOverrides: {
+    PID: { fields: { siteMrn: 19 } },
+    AL1: { fields: { localSeverityCode: 4 } },
+    RXA: { fields: { doseQualifier: 6 } },
+  },
+});
+
+const msg = parseHL7(raw, site);
+msg.part("PID")?.get("siteMrn")?.value; // the value at PID-19
+msg.part("AL1")?.get("localSeverityCode")?.value; // the value at AL1-4
+```
+
+**Positions are 1-indexed HL7 positions**, identical in meaning to the argument of `seg.field(n)`, including the MSH numbering convention: a binding at `1` is MSH-1 (the field separator) and a binding at `3` is MSH-3 (the sending application). `get(name)` and `field(position)` always agree.
+
+**A name that is not declared, and a declared position the message did not carry, both read `undefined`**, never an empty string. A typo surfaces instead of quietly reading blank. The HL7 explicit null (`""`) is a value the sender chose to send, so it still comes back as a `Field`.
+
+**Inheritance follows the same rule as `customSegments`.** Layer profiles with `extends` and, per segment type, the child's binding wins at any POSITION both declare while the parent's bindings at other positions survive:
+
+```ts
+const parent = defineProfile({
+  name: "parent",
+  segmentOverrides: { PID: { fields: { parentAlias: 19, countyCode: 12 } } },
+});
+
+const child = defineProfile({
+  name: "child",
+  extends: parent,
+  segmentOverrides: { PID: { fields: { childAlias: 19 } } },
+});
+
+// child.segmentOverrides.PID.fields === { childAlias: 19, countyCode: 12 }
+```
+
+**What `defineProfile()` refuses, at definition time**, throwing `ProfileDefinitionError` and returning no profile:
+
+| Declaration                                                         | Why it is refused                                                                                                                                                        |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| a Z-segment key (`ZPI`)                                             | that is a custom segment: the error points you at the `customSegments` option                                                                                            |
+| a name that is not a standard HL7 v2 segment (`QQQ`, `pid`, `PIDX`) | keys are matched against `KNOWN_SEGMENTS` in their canonical uppercase spelling, so a key that would never resolve is rejected rather than silently defining a dead name |
+| a position that is not a positive integer (`0`, `-1`, `2.5`, `"3"`) | the error names the profile, the segment and the field                                                                                                                   |
+| a misspelled option key (`segmentOverride`)                         | reported with `segmentOverrides` as the suggestion                                                                                                                       |
+
+An empty map (`segmentOverrides: {}`), or a declared segment with an empty field map, is accepted and behaves exactly like declaring nothing.
+
+#### Limitations
+
+**Overrides add named reads. They change nothing that already reads.** This is the whole design, and it is deliberate: HL7 v2 traffic is PHI, and an alias that re-pointed an existing accessor would hand a downstream consumer a different clinical value with no warning and nothing to notice. Specifically, a `segmentOverrides` declaration does NOT:
+
+- **re-point the typed clinical accessors.** `msg.patient`, `msg.visit`, `msg.allergies()`, `msg.medications()`, `msg.observations()` and every other typed helper keep reading the positions the HL7 standard assigns. Declaring `siteMrn: 19` does not make `msg.patient?.mrn` read PID-19; it still reads PID-3.
+- **add a dot-path.** Dot-paths stay positional: `msg.get("PID.19")` works, `msg.get("PID.siteMrn")` is a syntax error. The named accessor is the one route to a declared name.
+- **change serialization.** `toString()` is byte-for-byte what it was, `toJSON()` is unchanged, and the message still round-trips verbatim.
+- **change the warning list.** An undeclared Z-segment still emits `UNKNOWN_SEGMENT`, and naming a standard segment in the override map does not suppress or add any warning.
+- **touch the write path.** `setField`, `setComposite`, `buildMessage` and the typed builders take positions, not names.
+
+Parse one message with the overrides and again without them and every one of those observables is equal. Only the new names differ.
+
 ### Extending profiles
 
 Use `extends` to layer profiles. Single parent or array of parents, both supported.
@@ -663,6 +1120,7 @@ When `extends` resolves parents, fields are merged per-key with the following ru
 - **Scalars** (`description`): later layers overwrite earlier ones.
 - **Arrays** (`dateFormats`, `lineage`): concatenate + dedupe, preserving first-seen order.
 - **`customSegments` map**: deep-merge per key; same-segment-name in two parents reconciles positional fields.
+- **`segmentOverrides` map**: the same reducer, on the standard-segment declarations. See [Naming fields on standard segments](#naming-fields-on-standard-segments).
 - **`onWarning` handlers**: compose into a chain, invoked in lineage order (parents before children). Errors thrown by one handler do not stop subsequent handlers.
 - **`name`**: never inherited, always the profile's own.
 
@@ -701,7 +1159,7 @@ Eight profiles ship in the box, reachable via the `profiles` namespace:
 - `profiles.athena`: athenahealth. Ambulatory-oriented, ISO-leaning date formats.
 - `profiles.genericLab`: Generic reference-lab (LabCorp / Quest-style). Adds `YYYYMMDD HHmm` (ASTM-era) and `YYYY-MM-DD` (ISO date-only); declares `ZLB` (lab overrides) and `ZNT` (lab note) Z-segments.
 - `profiles.visage`: Visage 7 imaging/PACS RIS feeds. Declares the `ZDS` Z-segment that carries the DICOM **Study Instance UID** (field 1) so an HL7 order correlates to its DICOM study, the IHE Radiology RIS/PACS bridge segment. Grounded in the public [Visage 7 HL7 Interface Specification](https://www.visageimaging.com/downloads/Visage7/Visage7_HL7InterfaceSpecification.pdf) (V23.00, Jun 2026). Dates are HL7-native, so it adds no date formats.
-- `profiles.philips`: Philips Vue PACS ("IS Link") imaging feeds. Declares six Vue PACS Z-segments, one per filler role: `ZDS` (DICOM Study Instance UID), `ZLK` (linked studies/orders), `ZAO` (order additional details: modality, body part, transfer/acquisition status, technician + radiologist), `ZEB` (encrypted patient info), `ZAP` (patient additional details), and `ZAV` (visit additional details). Grounded in the public [Vue PACS 12.2.8 HL7 Interface Specifications](https://www.documents.philips.com/assets/Conformance%20Statements/20240409/8941f89d89aa4983aab7b14d00db578c.pdf) (Philips, doc HA1669 Rev A, §§5.11–5.16). Dates are HL7-native, so it adds no date formats.
+- `profiles.philips`: Philips Vue PACS ("IS Link") imaging feeds. Declares six Vue PACS Z-segments, one per filler role: `ZDS` (DICOM Study Instance UID), `ZLK` (linked studies/orders), `ZAO` (order additional details: modality, body part, transfer/acquisition status, technician + radiologist), `ZEB` (encrypted patient info), `ZAP` (patient additional details), and `ZAV` (visit additional details). Grounded in the public [Vue PACS 12.2.8 HL7 Interface Specifications](https://www.documents.philips.com/assets/Conformance%20Statements/20240409/8941f89d89aa4983aab7b14d00db578c.pdf) (Philips, doc HA1669 Rev A, §§5.11-5.16). Dates are HL7-native, so it adds no date formats.
 - `profiles.va`: U.S. Department of Veterans Affairs VistA Radiology/Nuclear Medicine feeds (HL7 v2.4). Declares the `ZDS` Z-segment that carries the DICOM **Study Instance UID** (field 1): the same IHE Radiology RIS↔PACS bridge as `visage`/`philips`, grounded here in a distinct **federal** spec and documented on **both ORM and ORU** (result) messages. Grounded in the public [Radiology/Nuclear Medicine 5.0 HL7 Interface Specification](https://www.va.gov/vdl/documents/clinical/radiology_nuclear_med/ra5_0hl7is.pdf) (Version 3.6, Patch RA\*5.0\*203, June 2024). Dates are HL7-native, so it adds no date formats.
 
 Use a built-in directly (`parseHL7(raw, profiles.epic)`) or as a base for your own (`defineProfile({ extends: profiles.epic, ... })`).
@@ -732,7 +1190,7 @@ for (const w of msg.warnings) {
 }
 ```
 
-The full list of Tier-2 codes (16 entries: `MLLP_FRAMING_STRIPPED`, `FIELD_WHITESPACE_TRIMMED`, `UNKNOWN_ESCAPE_SEQUENCE`, `TIMESTAMP_FALLBACK_FORMAT`, `SEGMENT_CASE`, `EXTRA_FIELDS`, `UNKNOWN_SEGMENT`, `DUPLICATE_REQUIRED_SEGMENT`, `ENCODING_MISMATCH`, `MISSING_REQUIRED_FIELD`, `MISSING_EXPECTED_GROUP`, `OUT_OF_ORDER_SEGMENT`, `VERSION_MISMATCH`, `UNKNOWN_CHARSET`, `ACK_NO_CORRELATION_ID`, `MERGE_MISSING_PRIOR_OR_SURVIVOR`) lives in [`src/parser/warnings.ts`](./src/parser/warnings.ts). Narrow on `w.code === WARNING_CODES.UNKNOWN_SEGMENT` (and friends) for typo-free comparisons.
+The full list of Tier-2 codes lives in [`src/parser/warnings.ts`](./src/parser/warnings.ts). Narrow on `w.code === WARNING_CODES.UNKNOWN_SEGMENT` (and friends) for typo-free comparisons.
 
 Need zero tolerance instead? `parseHL7(raw, { strict: true })` escalates every Tier-2 deviation to a thrown `Hl7ParseError`. Use strict in CI validators; leave it off for production ingestion.
 
@@ -832,19 +1290,15 @@ All three error types (and the `FATAL_CODES` / `WARNING_CODES` registries, and t
 
 ## Roadmap
 
-Not in v1, but on the roadmap for v2:
+Nothing is queued for a future release. Three capabilities a reader might expect to find named here are available today. Batch files too large to buffer are parsed incrementally by [`parseStream`](#streaming-large-files-parsestream), which yields the messages as an async iterable. JSON Schema and Zod descriptions of what `toJSON()` returns come from `emitMessageSchema`; Zod arrives as TypeScript source text to paste into your own project, so this package still has zero runtime dependencies (see the [schema emission notes](./docs-content/schema-emission.md)). A profile's declared field names are carried into the type system, so `seg.get("departmentCode")` on a declared segment is checked against that profile's names instead of widening to `string | undefined`. All three are exported, and all three are covered by the stability claim in [Status](#status).
 
-- **Typed message overlays** (`msg.is("ADT^A01")` narrows to `AdtA01Message`): message-type-aware getter narrowing.
-- **Schema-aware structure validation**: opt-in structural validator that enforces segment ordering + cardinality against the HL7 spec.
-- **Streaming parser for large batch files**: `createHL7Stream()` returning an iterable of messages, for multi-GB batch processing.
-- **JSON Schema / Zod emission for `toJSON()` output**: autogenerated schemas from the internal typed model.
-- **Type-safe custom-segment field names via conditional types**: `seg.get("departmentCode")` narrows to the profile's declared field alias, not `string | undefined`.
+What lands next starts as a quirk sighting or a real-world edge case on the [issue tracker](https://github.com/cosyte/hl7/issues).
 
 ### Out of scope (permanently)
 
-- **MLLP framing / network transport**: a future `@cosyte/hl7-mllp` package will cover network IO; this library is parser-only.
+- **Network transport**: sending and receiving over MLLP is [`@cosyte/mllp`](https://github.com/cosyte/mllp)'s job; this library is parser-only and only strips MLLP framing on read.
 - **HL7 v3 and CDA**: different spec family entirely; not in our plans.
-- **FHIR conversion**: a future companion package could bridge, but the conversion is non-trivial and deserves its own repo.
+- **FHIR conversion**: [`@cosyte/transform`](https://github.com/cosyte/transform) converts a parsed message to FHIR R4; this library does not.
 - **Exhaustive coded-value validation**: we validate structure, not every HL7 table. Integrate a domain validator (e.g. your LIS's internal code registry) for that.
 
 ---
@@ -853,18 +1307,20 @@ Not in v1, but on the roadmap for v2:
 
 Vendor-quirk fixtures, profile improvements, and standalone profile packages are all welcome. The more real-world edge cases the test suite covers, the more robust the parser gets. Every published profile package is a signal of adoption and a contribution back.
 
+Ask on the issue tracker, [github.com/cosyte/hl7/issues](https://github.com/cosyte/hl7/issues): questions, bug reports and quirk sightings all start there, and so does any refactor large enough to want discussion before a PR.
+
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for dev setup, how to file an issue, and how to submit a PR.
 
 ---
 
 ## Trademarks
 
-Epic, Cerner, MEDITECH, athenahealth, LabCorp, Quest Diagnostics, Visage (Visage Imaging), and Philips (Vue PACS) are trademarks of their respective owners. cosyte is not affiliated with, endorsed by, or
+Epic, Cerner, MEDITECH, athenahealth, LabCorp, Quest Diagnostics, Visage (Visage Imaging), and Philips (Vue PACS) are trademarks of their respective owners. Cosyte is not affiliated with, endorsed by, or
 sponsored by any of them: the names identify the systems whose real-world message quirks the built-in profiles accommodate. See [TRADEMARKS.md](./TRADEMARKS.md).
 
 ## License
 
-MIT: see [LICENSE](./LICENSE).
+MIT, copyright Cosyte. See [LICENSE](./LICENSE).
 
 ---