@cosyte/synth 0.1.8 → 0.1.10

package/dist/hl7/index.d.ts

@@ -1,27 +1,224 @@
 import { Hl7Message, RawField } from '@cosyte/hl7';
-import { SyntheticName, SyntheticIdentifier, SyntheticAddress, Rng, Corpus } from '../index.js';
+import { SyntheticIdentifier, SyntheticName, SyntheticAddress, Rng, Corpus } from '../index.js';
+import { AnimalCode } from '../index.js';
 import { QuirkDescriptor, SynthProfile, QuirkArtifact, QuirkRoundTripResult } from '../index.js';
 
+/**
+ * Shared HL7 v2 building blocks for every message family `@cosyte/synth` generates: the MSH scaffold,
+ * the seeded timestamp, and the patient-identity bundle + its `PID` segment. Factored out so `ADT`,
+ * `ORU`, `ORM`, `SIU`, and `VXU` all mint identity from the **same** synthetic-safety providers in the
+ * **same** draw order, and all emit through `@cosyte/hl7`'s conservative serializer. Nothing here draws a
+ * value that is not sourced from `../safe`: the synthetic-by-construction
+ * invariant holds by construction for every family.
+ *
+ * @module
+ */
+
+/**
+ * A seeded HL7 `YYYYMMDDHHMMSS` timestamp (message/event time; recent-year range). Strict HL7 DTM, so
+ * `@cosyte/hl7` parses it back with no `TIMESTAMP_FALLBACK_FORMAT` warning.
+ *
+ * @param rng - The seeded generator.
+ * @returns A 14-digit `YYYYMMDDHHMMSS` timestamp string.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * // "20230714…"
+ * ```
+ */
+declare function seededTimestamp(rng: Rng): string;
+/** The MSH scaffold shared by every generated message: the built message plus its seeded MSH values. */
+interface MessageScaffold {
+    /** The `Hl7Message` with a complete MSH: chain `.addSegment(...)` to append the payload. */
+    readonly message: Hl7Message;
+    /** The seeded `YYYYMMDDHHMMSS` message timestamp (MSH-7), reused for event/observation times. */
+    readonly timestamp: string;
+    /** The seeded message control id (MSH-10). */
+    readonly controlId: string;
+}
+/**
+ * Build the MSH scaffold for a message of the given `MSH-9` type through `@cosyte/hl7`'s `buildMessage`,
+ * so the delimiters, control id, and header layout are the parser's own conservative emit. Draws the
+ * timestamp then the control id from `rng` (a fixed order: the reproducibility contract).
+ *
+ * @param rng - The seeded generator.
+ * @param type - The `MSH-9` message type, e.g. `"ORU^R01"`.
+ * @returns The {@link MessageScaffold}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * // mshScaffold(createRng(1), "ORU^R01").message.addSegment("PID", […]);
+ * ```
+ */
+declare function mshScaffold(rng: Rng, type: string): MessageScaffold;
+/** A complete synthetic patient identity: every field drawn from `../safe`. */
+interface PatientIdentity {
+    /** Name from the shipped fake-name pool. */
+    readonly person: SyntheticName;
+    /** Medical-record identifier scoped to the synthetic assigning authority. */
+    readonly mrn: SyntheticIdentifier;
+    /** Date of birth (`YYYYMMDD`) from the seeded generator. */
+    readonly dob: string;
+    /** Administrative sex. */
+    readonly sex: "M" | "F";
+    /** Synthetic postal address (reserved non-real ZIP). */
+    readonly address: SyntheticAddress;
+    /** Reserved `555-01xx` phone number. */
+    readonly phone: string;
+    /** Never-issued SSN as 9 digits (no dashes), for `PID-19`. */
+    readonly ssnDigits: string;
+}
+/**
+ * Mint a complete synthetic {@link PatientIdentity}. Every value comes from a synthetic-safety provider,
+ * so no code path here can return a real or plausibly-real identifier. The draw order is
+ * fixed (name → MRN → DOB → sex → address → phone → SSN) so the same seed yields the same identity.
+ *
+ * @param rng - The seeded generator.
+ * @returns A synthetic {@link PatientIdentity}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * // const id = patientIdentity(createRng(1)); // id.person, id.mrn, …
+ * ```
+ */
+declare function patientIdentity(rng: Rng): PatientIdentity;
+/**
+ * Lay out a fully-populated `PID` segment from a {@link PatientIdentity} as `addSegment` fields: the
+ * PHI-dense segment shared by every family. Components go through {@link componentsField} so the parser
+ * lays out the `^` separators (building *through* the parser).
+ *
+ * @param id - The synthetic identity to render.
+ * @returns The `PID` field list for `Hl7Message.addSegment("PID", …)`.
+ * @example
+ * ```ts
+ * // msg.addSegment("PID", pidSegment(patientIdentity(createRng(1))));
+ * ```
+ */
+declare function pidSegment(id: PatientIdentity): readonly (string | RawField)[];
+/**
+ * Who a message is about. `"person"`, the default, is the human patient every generator has always
+ * written. `"animal"` writes a veterinary patient instead: see {@link AnimalIdentity}.
+ */
+type Hl7Subject = "person" | "animal";
+/** An animal's owner: every value drawn from `../safe`. */
+interface AnimalOwner {
+    /** The owner's name, from the shipped fake-name pool. */
+    readonly person: SyntheticName;
+    /** The owner's synthetic postal address (reserved non-real ZIP), which is also the animal's. */
+    readonly address: SyntheticAddress;
+    /** The owner's reserved `555-01xx` phone number. */
+    readonly phone: string;
+}
+/** A complete synthetic animal patient: every value drawn from `../safe`. */
+interface AnimalIdentity {
+    /** The pet's name, from the shipped fake pet-name pool. */
+    readonly petName: string;
+    /** The record number, scoped to the synthetic assigning authority. */
+    readonly record: SyntheticIdentifier;
+    /** A 15-digit microchip that begins `999`. */
+    readonly microchip: string;
+    /** The species, from our own short list. */
+    readonly species: AnimalCode;
+    /** The breed, one of the species' breeds. */
+    readonly breed: AnimalCode;
+    /** Birth date (`YYYYMMDD`), 0 to 20 years before the message date. */
+    readonly dob: string;
+    /** Administrative sex. */
+    readonly sex: "M" | "F";
+    /** The owner. */
+    readonly owner: AnimalOwner;
+}
+/**
+ * The identifier type the animal subject writes for a microchip in PID-3 (CX.5): `MCN`, which we
+ * use for microchip number. We have not verified it against HL7 table 0203 (identifier type) in any
+ * version. Not verified.
+ */
+declare const MICROCHIP_IDENTIFIER_TYPE = "MCN";
+/**
+ * The owner relationship the animal subject writes in NK1-3: `OWN^Owner^HL70063`. We have not
+ * verified that `OWN` is a value of HL7 table 0063 (relationship). Not verified.
+ */
+declare const OWNER_RELATIONSHIP: Readonly<{
+    code: "OWN";
+    text: "Owner";
+    system: "HL70063";
+}>;
+/**
+ * Mint a complete synthetic {@link AnimalIdentity}. The draw order is fixed (owner name, pet name,
+ * record number, microchip, species and breed, birth date, sex, address, phone) so the same seed and
+ * date yield the same animal.
+ *
+ * @param rng - The seeded generator.
+ * @param onDate - The message date, `YYYYMMDD` or a longer timestamp: the birth date falls from 0
+ *   to 20 years before it.
+ * @returns A synthetic {@link AnimalIdentity}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { animalIdentity } from "@cosyte/synth/hl7";
+ * const pet = animalIdentity(createRng(1), "20250101");
+ * pet.species.text; // e.g. "Dog"
+ * ```
+ */
+declare function animalIdentity(rng: Rng, onDate: string): AnimalIdentity;
+/**
+ * Lay out the `PID` segment of an {@link AnimalIdentity}: the record number and the microchip as two
+ * PID-3 repetitions, the owner's family name and the pet's name in PID-5, the owner's address and
+ * phone, and the species in PID-35 and breed in PID-36. PID-19 (SSN) stays empty.
+ *
+ * @param id - The synthetic animal to render.
+ * @returns The `PID` field list for `Hl7Message.addSegment("PID", …)`.
+ * @example
+ * ```ts
+ * // msg.addSegment("PID", animalPidSegment(animalIdentity(createRng(1), "20250101")));
+ * ```
+ */
+declare function animalPidSegment(id: AnimalIdentity): readonly (string | RawField)[];
+/**
+ * Lay out the owner's `NK1` segment: the owner's name, relationship {@link OWNER_RELATIONSHIP}
+ * (`OWN`, not verified against HL7 table 0063), address and phone.
+ *
+ * @param id - The synthetic animal whose owner to render.
+ * @returns The `NK1` field list for `Hl7Message.addSegment("NK1", …)`.
+ * @example
+ * ```ts
+ * // msg.addSegment("NK1", ownerNk1Segment(animalIdentity(createRng(1), "20250101")));
+ * ```
+ */
+declare function ownerNk1Segment(id: AnimalIdentity): readonly (string | RawField)[];
+
 /**
  * Spec-clean HL7 v2 `ADT` generation, built **through `@cosyte/hl7`'s `buildMessage`** so MSH
  * delimiters, segment layout, and escaping are the parser's own conservative emit: spec-clean *by
  * construction*. Every PHI-bearing field (name, DOB, SSN, MRN,
  * address, phone) is drawn from the synthetic-safety providers (`../safe`), so no value can be real.
  *
- * `ADT^A01/A04/A08` all require the `PID` (patient) + `PV1` (visit) groups the parser's structure net
- * checks for, so a generated message round-trips through `@cosyte/hl7` with **zero warnings**.
+ * Every trigger here requires the `EVN`, `PID` (patient) and `PV1` (visit) segments the parser's
+ * structure net checks for, so a generated message round-trips through `@cosyte/hl7` with **zero
+ * warnings**. The triggers and the structures they share (HL7 v2 chapter 3):
+ *
+ * - `A01` admit, `A04` register, `A08` update patient information, `A13` cancel discharge: `ADT_A01`.
+ * - `A02` transfer a patient: `ADT_A02`. `A03` discharge or end visit: `ADT_A03`.
+ * - `A11` cancel admit or visit notification: `ADT_A09`.
+ * - `A28` add person or patient information, `A31` update person information: `ADT_A05`.
  *
  * @module
  */
 
-/** The ADT trigger events this generator produces (all require the PID + PV1 groups). */
-type AdtTrigger = "A01" | "A04" | "A08";
+/** The ADT trigger events this generator produces (all require the EVN, PID and PV1 segments). */
+type AdtTrigger = "A01" | "A04" | "A08" | "A02" | "A03" | "A11" | "A13" | "A28" | "A31";
 /** Options for {@link generateAdt}. */
 interface GenerateAdtOptions {
     /** The seed: the same seed yields a byte-identical message. Defaults to `0`. */
     readonly seed?: number;
     /** The ADT trigger event. Defaults to `"A01"`. */
     readonly trigger?: AdtTrigger;
+    /**
+     * Who the message is about. Defaults to `"person"`, whose bytes for a seed are what they always
+     * were. `"animal"` writes a veterinary patient: the pet's name in PID-5, a microchip in PID-3, the
+     * species in PID-35 and breed in PID-36, and the owner in an `NK1` after the `PID`.
+     */
+    readonly subject?: Hl7Subject;
 }
 /**
  * Generate a spec-clean `ADT` {@link Hl7Message} through `@cosyte/hl7`. Deterministic in `seed`.
@@ -29,8 +226,12 @@ interface GenerateAdtOptions {
  * The message carries a complete MSH (seeded control id + timestamp, so the bytes are reproducible),
  * `EVN`, a fully-populated `PID` (identity from the synthetic providers), and `PV1` (the visit group),
  * so it parses back through `@cosyte/hl7` with **zero warnings** (proven by {@link ./round-trip}).
+ * A trigger added after `A01`, `A04` and `A08` also names its published structure in MSH-9.3 and
+ * fills the `PV1` fields its event is about (a transfer's prior location, a discharge's times).
  *
- * @param options - Seed + trigger. See {@link GenerateAdtOptions}.
+ * With `subject: "animal"` the patient is an animal and its owner follows the `PID` in an `NK1`.
+ *
+ * @param options - Seed, trigger and subject. See {@link GenerateAdtOptions}.
  * @returns A spec-clean `ADT` `Hl7Message`.
  * @example
  * ```ts
@@ -56,6 +257,12 @@ declare function generateAdt(options?: GenerateAdtOptions): Hl7Message;
 interface GenerateOruOptions {
     /** The seed: the same seed yields a byte-identical message. Defaults to `0`. */
     readonly seed?: number;
+    /**
+     * Who the result is about. Defaults to `"person"`, whose bytes for a seed are what they always
+     * were. `"animal"` writes a veterinary patient: the pet's name in PID-5, a microchip in PID-3, the
+     * species in PID-35 and breed in PID-36, and the owner in an `NK1` after the `PID`.
+     */
+    readonly subject?: Hl7Subject;
 }
 /**
  * Generate a spec-clean `ORU^R01` {@link Hl7Message} through `@cosyte/hl7`. Deterministic in `seed`.
@@ -64,7 +271,9 @@ interface GenerateOruOptions {
  * rows. The `OBR`/`OBX` result group satisfies the parser's `ORU^R01` structure net, so the message
  * re-parses with **zero warnings** (proven by {@link ./round-trip}).
  *
- * @param options - Seed. See {@link GenerateOruOptions}.
+ * With `subject: "animal"` the patient is an animal and its owner follows the `PID` in an `NK1`.
+ *
+ * @param options - Seed and subject. See {@link GenerateOruOptions}.
  * @returns A spec-clean `ORU^R01` `Hl7Message`.
  * @example
  * ```ts
@@ -173,6 +382,160 @@ interface GenerateVxuOptions {
  */
 declare function generateVxu(options?: GenerateVxuOptions): Hl7Message;
 
+/**
+ * Spec-clean HL7 v2 `MDM^T02` (original document notification and content) generation, built
+ * **through `@cosyte/hl7`'s `buildMessage`**. The published `MDM_T02` structure requires `EVN`, `PID`,
+ * `PV1`, `TXA` (the document header) and at least one `OBX` (the document body); this generator emits
+ * each of them, so the message round-trips with **zero warnings**. Identity comes from `../safe`; the
+ * document body is a fixed set of sentences that say they are synthetic.
+ *
+ * @module
+ */
+
+/** Options for {@link generateMdm}. */
+interface GenerateMdmOptions {
+    /** The seed: the same seed yields a byte-identical message. Defaults to `0`. */
+    readonly seed?: number;
+}
+/**
+ * Generate a spec-clean `MDM^T02` {@link Hl7Message} through `@cosyte/hl7`. Deterministic in `seed`.
+ *
+ * Layout: MSH (`MDM^T02^MDM_T02`), `EVN`, `PID` (synthetic identity), `PV1`, `TXA` (document type
+ * from HL7 table 0270, content presentation `TX`, a `SYNTHDOC` unique document number, completion
+ * status `DO`, documented) and one to three `OBX` lines of `TX` text, each final (`F`).
+ *
+ * @param options - Seed. See {@link GenerateMdmOptions}.
+ * @returns A spec-clean `MDM^T02` `Hl7Message`.
+ * @example
+ * ```ts
+ * import { generateMdm } from "@cosyte/synth/hl7";
+ * const msg = generateMdm({ seed: 12345 });
+ * console.log(msg.toString());
+ * ```
+ */
+declare function generateMdm(options?: GenerateMdmOptions): Hl7Message;
+
+/**
+ * Spec-clean HL7 v2 `DFT^P03` (post detail financial transactions) generation, built **through
+ * `@cosyte/hl7`'s `buildMessage`**. The published `DFT_P03` structure requires `EVN`, `PID` and at
+ * least one `FT1` (the financial transaction); this generator emits them and a `PV1`, so the message
+ * round-trips with **zero warnings**. Identity comes from `../safe`; the charge code is a local code
+ * that says it is synthetic, never a real chargemaster or procedure code.
+ *
+ * @module
+ */
+
+/** Options for {@link generateDft}. */
+interface GenerateDftOptions {
+    /** The seed: the same seed yields a byte-identical message. Defaults to `0`. */
+    readonly seed?: number;
+}
+/**
+ * Generate a spec-clean `DFT^P03` {@link Hl7Message} through `@cosyte/hl7`. Deterministic in `seed`.
+ *
+ * Layout: MSH (`DFT^P03^DFT_P03`), `EVN`, `PID` (synthetic identity), `PV1`, and one `FT1`: a
+ * `SYNTHTXN` transaction id, the transaction date, type `CG` (charge, HL7 table 0017), a local
+ * `SYNTHCHG` charge code and a quantity of one to three.
+ *
+ * @param options - Seed. See {@link GenerateDftOptions}.
+ * @returns A spec-clean `DFT^P03` `Hl7Message`.
+ * @example
+ * ```ts
+ * import { generateDft } from "@cosyte/synth/hl7";
+ * const msg = generateDft({ seed: 12345 });
+ * console.log(msg.toString());
+ * ```
+ */
+declare function generateDft(options?: GenerateDftOptions): Hl7Message;
+
+/**
+ * Spec-clean HL7 v2 `OML^O21` (laboratory order) generation, built **through `@cosyte/hl7`'s
+ * `buildMessage`**. The published `OML_O21` structure requires the common order (`ORC`); this
+ * generator emits `PID`, `ORC` and a matching `OBR`, so the message round-trips with **zero
+ * warnings**. Identity comes from `../safe`; the ordered service comes from the license-clean example
+ * pool, never bundled terminology.
+ *
+ * @module
+ */
+
+/** Options for {@link generateOml}. */
+interface GenerateOmlOptions {
+    /** The seed: the same seed yields a byte-identical message. Defaults to `0`. */
+    readonly seed?: number;
+}
+/**
+ * Generate a spec-clean `OML^O21` {@link Hl7Message} through `@cosyte/hl7`. Deterministic in `seed`.
+ *
+ * Layout: MSH (`OML^O21^OML_O21`), `PID` (synthetic identity), `ORC` (order control `NW`, a new
+ * order) and an `OBR` carrying the same placer and filler numbers and a laboratory service.
+ *
+ * @param options - Seed. See {@link GenerateOmlOptions}.
+ * @returns A spec-clean `OML^O21` `Hl7Message`.
+ * @example
+ * ```ts
+ * import { generateOml } from "@cosyte/synth/hl7";
+ * const msg = generateOml({ seed: 12345 });
+ * console.log(msg.toString());
+ * ```
+ */
+declare function generateOml(options?: GenerateOmlOptions): Hl7Message;
+
+/**
+ * Spec-clean HL7 v2 `ACK` (general acknowledgment) generation, for any message: built **through
+ * `@cosyte/hl7`'s `buildMessage`** like every other kind. The published `ACK` structure requires
+ * `MSH` and `MSA`; an error acknowledgment adds one `ERR`. The message round-trips with **zero
+ * warnings**.
+ *
+ * `@cosyte/hl7`'s own `buildAck` stamps the current time and a fresh control id, which is right for a
+ * live interface and wrong for a fixture. This generator draws both from the seed instead, so the
+ * same seed and the same inbound message give the same bytes.
+ *
+ * @module
+ */
+
+/**
+ * An original-mode acknowledgment code (HL7 table 0008, MSA-1): `AA` application accept, `AE`
+ * application error, `AR` application reject.
+ */
+type Hl7AckCode = "AA" | "AE" | "AR";
+/** Options for {@link generateAck}. */
+interface GenerateAckOptions {
+    /** The seed: the same seed and inbound message yield a byte-identical ACK. Defaults to `0`. */
+    readonly seed?: number;
+    /**
+     * The message being acknowledged. Defaults to the `ADT^A01` {@link generateAdt} makes from the same
+     * seed. It must carry an MSH-10 message control id.
+     */
+    readonly inbound?: Hl7Message;
+    /** The acknowledgment code in MSA-1. Defaults to `"AA"`. */
+    readonly code?: Hl7AckCode;
+}
+/**
+ * Generate a spec-clean `ACK` {@link Hl7Message} answering `inbound`. Deterministic in `seed` and
+ * `inbound`.
+ *
+ * - **MSH**: the inbound receiver (MSH-5, MSH-6) becomes the sender (MSH-3, MSH-4) and the inbound
+ *   sender the receiver. MSH-7 is one to fifty-nine seconds after the inbound MSH-7, or a seeded time
+ *   when that is not a full `YYYYMMDDHHMMSS`. MSH-9 is `ACK^<inbound trigger>^ACK`, or `ACK` when
+ *   the inbound names no trigger. MSH-10 is a seeded `SYNTHACK` control id. MSH-11 is always `T`, test
+ *   data, whatever the inbound says. MSH-12 echoes the inbound version, `2.5` when it names none.
+ * - **MSA**: MSA-1 is `code`, MSA-2 the inbound MSH-10.
+ * - **ERR**, for `AE` and `AR` only: ERR-3 is condition `207`, application internal error (HL7 table
+ *   0357), and ERR-4 severity `E`, error.
+ *
+ * @param options - Seed, inbound message and code. See {@link GenerateAckOptions}.
+ * @returns A spec-clean `ACK` `Hl7Message`.
+ * @throws SynthError `SYNTH_ACK_UNCORRELATED` when the inbound message has no MSH-10, and
+ * `SYNTH_UNSUPPORTED_KIND` when `code` is not `AA`, `AE` or `AR`.
+ * @example
+ * ```ts
+ * import { generateAck, generateOru } from "@cosyte/synth/hl7";
+ * const ack = generateAck({ seed: 7, inbound: generateOru({ seed: 7 }) });
+ * console.log(ack.toString()); // MSH|...|ACK^R01^ACK|SYNTHACK...|T|2.5 then MSA|AA|SYNTH...
+ * ```
+ */
+declare function generateAck(options?: GenerateAckOptions): Hl7Message;
+
 /**
  * The **round-trip-through-the-parser harness**: the headline gate for the synthetic-fixture
  * generator. A generated artifact is "spec-clean" only if `@cosyte/hl7`, not
@@ -236,99 +599,6 @@ declare function roundTrip(message: Hl7Message): RoundTripResult;
  */
 declare function componentsField(components: readonly string[]): RawField;
 
-/**
- * Shared HL7 v2 building blocks for every message family `@cosyte/synth` generates: the MSH scaffold,
- * the seeded timestamp, and the patient-identity bundle + its `PID` segment. Factored out so `ADT`,
- * `ORU`, `ORM`, `SIU`, and `VXU` all mint identity from the **same** synthetic-safety providers in the
- * **same** draw order, and all emit through `@cosyte/hl7`'s conservative serializer. Nothing here draws a
- * value that is not sourced from `../safe`: the synthetic-by-construction
- * invariant holds by construction for every family.
- *
- * @module
- */
-
-/**
- * A seeded HL7 `YYYYMMDDHHMMSS` timestamp (message/event time; recent-year range). Strict HL7 DTM, so
- * `@cosyte/hl7` parses it back with no `TIMESTAMP_FALLBACK_FORMAT` warning.
- *
- * @param rng - The seeded generator.
- * @returns A 14-digit `YYYYMMDDHHMMSS` timestamp string.
- * @example
- * ```ts
- * import { createRng } from "@cosyte/synth";
- * // "20230714…"
- * ```
- */
-declare function seededTimestamp(rng: Rng): string;
-/** The MSH scaffold shared by every generated message: the built message plus its seeded MSH values. */
-interface MessageScaffold {
-    /** The `Hl7Message` with a complete MSH: chain `.addSegment(...)` to append the payload. */
-    readonly message: Hl7Message;
-    /** The seeded `YYYYMMDDHHMMSS` message timestamp (MSH-7), reused for event/observation times. */
-    readonly timestamp: string;
-    /** The seeded message control id (MSH-10). */
-    readonly controlId: string;
-}
-/**
- * Build the MSH scaffold for a message of the given `MSH-9` type through `@cosyte/hl7`'s `buildMessage`,
- * so the delimiters, control id, and header layout are the parser's own conservative emit. Draws the
- * timestamp then the control id from `rng` (a fixed order: the reproducibility contract).
- *
- * @param rng - The seeded generator.
- * @param type - The `MSH-9` message type, e.g. `"ORU^R01"`.
- * @returns The {@link MessageScaffold}.
- * @example
- * ```ts
- * import { createRng } from "@cosyte/synth";
- * // mshScaffold(createRng(1), "ORU^R01").message.addSegment("PID", […]);
- * ```
- */
-declare function mshScaffold(rng: Rng, type: string): MessageScaffold;
-/** A complete synthetic patient identity: every field drawn from `../safe`. */
-interface PatientIdentity {
-    /** Name from the shipped fake-name pool. */
-    readonly person: SyntheticName;
-    /** Medical-record identifier scoped to the synthetic assigning authority. */
-    readonly mrn: SyntheticIdentifier;
-    /** Date of birth (`YYYYMMDD`) from the seeded generator. */
-    readonly dob: string;
-    /** Administrative sex. */
-    readonly sex: "M" | "F";
-    /** Synthetic postal address (reserved non-real ZIP). */
-    readonly address: SyntheticAddress;
-    /** Reserved `555-01xx` phone number. */
-    readonly phone: string;
-    /** Never-issued SSN as 9 digits (no dashes), for `PID-19`. */
-    readonly ssnDigits: string;
-}
-/**
- * Mint a complete synthetic {@link PatientIdentity}. Every value comes from a synthetic-safety provider,
- * so no code path here can return a real or plausibly-real identifier. The draw order is
- * fixed (name → MRN → DOB → sex → address → phone → SSN) so the same seed yields the same identity.
- *
- * @param rng - The seeded generator.
- * @returns A synthetic {@link PatientIdentity}.
- * @example
- * ```ts
- * import { createRng } from "@cosyte/synth";
- * // const id = patientIdentity(createRng(1)); // id.person, id.mrn, …
- * ```
- */
-declare function patientIdentity(rng: Rng): PatientIdentity;
-/**
- * Lay out a fully-populated `PID` segment from a {@link PatientIdentity} as `addSegment` fields: the
- * PHI-dense segment shared by every family. Components go through {@link componentsField} so the parser
- * lays out the `^` separators (building *through* the parser).
- *
- * @param id - The synthetic identity to render.
- * @returns The `PID` field list for `Hl7Message.addSegment("PID", …)`.
- * @example
- * ```ts
- * // msg.addSegment("PID", pidSegment(patientIdentity(createRng(1))));
- * ```
- */
-declare function pidSegment(id: PatientIdentity): readonly (string | RawField)[];
-
 /**
  * A tiny, curated, **license-clean** pool of example codes used to fill coded fields in generated HL7
  * messages (`OBR`/`OBX` observations, `ORC`/`OBR` orders, `RXA` vaccines). These are **public code
@@ -445,9 +715,15 @@ interface Hl7QuirkCorpusOptions {
     readonly seed: number;
     /** How many quirk artifacts to generate. Defaults to the number of quirks. */
     readonly count?: number;
-    /** The quirk names to cycle through. Defaults to every HL7 quirk. Validated; unsupported ⇒ fatal. */
+    /**
+     * The quirk names to cycle through. Defaults to every HL7 quirk. Validated; unsupported ⇒ fatal.
+     * An empty list, or a `profile` whose `quirks` is an empty list, throws `SYNTH_EMPTY_POOL`.
+     */
     readonly quirks?: readonly Hl7QuirkName[];
-    /** A {@link SynthProfile} whose `quirks` drive the corpus (validated). Takes precedence over `quirks`. */
+    /**
+     * A {@link SynthProfile} whose `quirks` drive the corpus (validated). Its `quirks`, when set, take
+     * precedence over `quirks`; a profile that leaves `quirks` out leaves the selection to `quirks`.
+     */
     readonly profile?: SynthProfile;
     /** The base message family each quirk is injected into. Defaults to `"ORU^R01"`. */
     readonly kind?: Hl7QuirkKind;
@@ -486,17 +762,30 @@ declare const hl7QuirkProfile: SynthProfile;
  * never loads a parser.
  * `@cosyte/hl7` is an **optional peer dependency**, present only for this subpath.
  *
- * The HL7 v2 message set is complete: `ADT` (A01/A04/A08), `ORU^R01`, `ORM^O01`, `SIU^S12`, and
- * `VXU^V04`, each built through `@cosyte/hl7`'s `buildMessage` and round-tripping with zero warnings.
+ * The HL7 v2 message set: `ADT` (A01, A02, A03, A04, A08, A11, A13, A28, A31), `ORU^R01`, `ORM^O01`,
+ * `SIU^S12`, `VXU^V04`, `MDM^T02`, `DFT^P03`, `OML^O21`, and an `ACK` for any of them, each built
+ * through `@cosyte/hl7`'s `buildMessage`, stamped HL7 v2.5, and round-tripping with zero warnings.
  *
  * @module
  */
 
 /**
  * Every HL7 v2 message kind this subpath generates: the `MSH-9` label used as the corpus `kind`. `ADT`
- * carries its trigger; the other families have a single generated trigger each.
+ * carries its trigger; the other families have a single generated trigger each. `ACK` acknowledges
+ * an `ADT^A01` generated from the same seed (see {@link generateAck} to acknowledge any message).
+ */
+type Hl7MessageKind = "ADT^A01" | "ADT^A04" | "ADT^A08" | "ORU^R01" | "ORM^O01" | "SIU^S12" | "VXU^V04" | "ACK" | "ADT^A02" | "ADT^A03" | "ADT^A11" | "ADT^A13" | "ADT^A28" | "ADT^A31" | "MDM^T02" | "DFT^P03" | "OML^O21";
+/**
+ * Every kind {@link generateHl7} and {@link hl7Corpus} accept, in a fixed order: the first seven
+ * kinds, then each kind added since. Pass it as a corpus `mix` to cycle through all of them.
+ *
+ * @example
+ * ```ts
+ * import { HL7_MESSAGE_KINDS, hl7Corpus } from "@cosyte/synth/hl7";
+ * hl7Corpus({ seed: 1, count: HL7_MESSAGE_KINDS.length, mix: HL7_MESSAGE_KINDS });
+ * ```
  */
-type Hl7MessageKind = "ADT^A01" | "ADT^A04" | "ADT^A08" | "ORU^R01" | "ORM^O01" | "SIU^S12" | "VXU^V04";
+declare const HL7_MESSAGE_KINDS: readonly Hl7MessageKind[];
 /**
  * Generate one message of the given {@link Hl7MessageKind} from a seed, dispatching to the right
  * family generator. Every kind builds through `@cosyte/hl7` and is deterministic in `seed`.
@@ -518,13 +807,15 @@ interface Hl7CorpusOptions {
     /** How many messages to generate. Defaults to `1`. */
     readonly count?: number;
     /**
-     * The message kinds to cycle through. Defaults to one of every family
-     * (`ADT^A01/A04/A08`, `ORU^R01`, `ORM^O01`, `SIU^S12`, `VXU^V04`).
+     * The message kinds to cycle through, any of {@link HL7_MESSAGE_KINDS}. Defaults to one each of
+     * the first seven kinds (`ADT^A01/A04/A08`, `ORU^R01`, `ORM^O01`, `SIU^S12`, `VXU^V04`), so a seed's
+     * default corpus is unchanged as kinds are added. An empty list throws `SYNTH_EMPTY_POOL`.
      */
     readonly mix?: readonly Hl7MessageKind[];
     /**
      * ADT-only convenience: the triggers to cycle through, kept for back-compat. When
-     * supplied it takes precedence over `mix` and restricts the corpus to `ADT` messages.
+     * supplied it takes precedence over `mix` and restricts the corpus to `ADT` messages. An empty
+     * list throws `SYNTH_EMPTY_POOL`.
      */
     readonly triggers?: readonly AdtTrigger[];
     /**
@@ -551,5 +842,5 @@ interface Hl7CorpusOptions {
  */
 declare function hl7Corpus(options: Hl7CorpusOptions): Corpus;
 
-export { EXAMPLE_LAB_OBSERVATIONS, EXAMPLE_ORDER_SERVICES, EXAMPLE_VACCINES, HL7_QUIRKS, componentsField, generateAdt, generateHl7, generateHl7Quirk, generateOrm, generateOru, generateSiu, generateVxu, hl7Corpus, hl7QuirkCorpus, hl7QuirkProfile, hl7QuirkRoundTrip, mshScaffold, patientIdentity, pidSegment, roundTrip, seededTimestamp };
-export type { AdtTrigger, ExampleCode, GenerateAdtOptions, GenerateHl7QuirkOptions, GenerateOrmOptions, GenerateOruOptions, GenerateSiuOptions, GenerateVxuOptions, Hl7CorpusOptions, Hl7MessageKind, Hl7QuirkCorpusOptions, Hl7QuirkKind, Hl7QuirkName, MessageScaffold, PatientIdentity, RoundTripResult };
+export { EXAMPLE_LAB_OBSERVATIONS, EXAMPLE_ORDER_SERVICES, EXAMPLE_VACCINES, HL7_MESSAGE_KINDS, HL7_QUIRKS, MICROCHIP_IDENTIFIER_TYPE, OWNER_RELATIONSHIP, animalIdentity, animalPidSegment, componentsField, generateAck, generateAdt, generateDft, generateHl7, generateHl7Quirk, generateMdm, generateOml, generateOrm, generateOru, generateSiu, generateVxu, hl7Corpus, hl7QuirkCorpus, hl7QuirkProfile, hl7QuirkRoundTrip, mshScaffold, ownerNk1Segment, patientIdentity, pidSegment, roundTrip, seededTimestamp };
+export type { AdtTrigger, AnimalIdentity, AnimalOwner, ExampleCode, GenerateAckOptions, GenerateAdtOptions, GenerateDftOptions, GenerateHl7QuirkOptions, GenerateMdmOptions, GenerateOmlOptions, GenerateOrmOptions, GenerateOruOptions, GenerateSiuOptions, GenerateVxuOptions, Hl7AckCode, Hl7CorpusOptions, Hl7MessageKind, Hl7QuirkCorpusOptions, Hl7QuirkKind, Hl7QuirkName, Hl7Subject, MessageScaffold, PatientIdentity, RoundTripResult };