@cosyte/synth 0.0.1

package/dist/astm/index.d.cts

@@ -0,0 +1,418 @@
+import { S as SyntheticName, R as Rng, C as Corpus } from '../providers-OLz3zAc-.cjs';
+import { Q as QuirkDescriptor, S as SynthProfile, a as QuirkArtifact, b as QuirkRoundTripResult } from '../quirk-DmkgoZdh.cjs';
+
+/**
+ * Spec-clean ASTM (E1394 / CLSI LIS02) message generation — the `H`/`P`/`O`/`R`/`C`/`L` record report —
+ * built through `@cosyte/astm`'s `buildAstmMessage` so the delimiter declaration (`H|\^&`), the record
+ * type letters, the per-type sequence counters, the `L` terminator, and every escape are the parser's
+ * own conservative emit. Nothing clinical is defaulted: a
+ * result's status/flag/units/value are supplied from the example pool, never invented by the builder.
+ *
+ * A framed **E1381 / CLSI LIS01** variant is also offered ({@link generateAstmResultFramed}) via
+ * `composeAstmFrames`, which frames each record into `<STX> FN text <ETB|ETX> CS <CR><LF>` with the
+ * **modulo-256 checksum and the `0`–`7` frame number computed by the parser** — never faked. Both round
+ * trip through `@cosyte/astm` cleanly (`parseAstmRecords` / `parseFramedAstm` — see `./round-trip`).
+ *
+ * Every value at a PHI-bearing locus (the `P` record's name / DOB / practice+lab IDs) is
+ * drawn from the synthetic-safety providers via `./identity`, so no output can be real or plausibly-real
+ * PHI. `synth` is a **format/conformance generator, not a clinical simulator**: a generated
+ * result pairs a code and a value with no claim of clinical coherence.
+ *
+ * @module
+ */
+/** Options for the ASTM message generators. */
+interface GenerateAstmOptions {
+    /** The seed (deterministic — same seed yields a byte-identical message). */
+    readonly seed: number;
+    /** How many `R` (result) records to emit. Defaults to a seeded 1–4. */
+    readonly resultCount?: number;
+    /** Whether to append a `C` (comment) record after the results. Defaults to `true`. */
+    readonly comment?: boolean;
+}
+/**
+ * Generate a spec-clean ASTM **result message** — an `H`/`P`/`O`/`R`…/`C`/`L` record stream — built
+ * through `@cosyte/astm`'s `buildAstmMessage`. Every identity value is synthetic-by-construction; the message
+ * round-trips through `parseAstmRecords` with zero warnings and re-serializes
+ * byte-identically (see `./round-trip`).
+ *
+ * @param options - The seed, optional result count, and whether to append a comment.
+ * @returns The `CR`-terminated ASTM record stream.
+ * @example
+ * ```ts
+ * import { generateAstmResult } from "@cosyte/synth/astm";
+ * const raw = generateAstmResult({ seed: 42 });
+ * ```
+ */
+declare function generateAstmResult(options: GenerateAstmOptions): string;
+/**
+ * Generate a spec-clean ASTM **order message** — an `H`/`P`/`O`/`L` record stream with no results, for
+ * the order side of the flow. Built through `buildAstmMessage`; synthetic-by-construction; round-trips
+ * clean.
+ *
+ * @param options - The seed.
+ * @returns The `CR`-terminated ASTM record stream.
+ * @example
+ * ```ts
+ * import { generateAstmOrder } from "@cosyte/synth/astm";
+ * const raw = generateAstmOrder({ seed: 7 });
+ * ```
+ */
+declare function generateAstmOrder(options: GenerateAstmOptions): string;
+/**
+ * Generate a spec-clean **framed** ASTM result message — the same `H`/`P`/`O`/`R`…/`C`/`L` records,
+ * wrapped in the **E1381 / CLSI LIS01** frame envelope (`<STX> FN text <ETB|ETX> CS <CR><LF>`) via
+ * `@cosyte/astm`'s `composeAstmFrames`. The **modulo-256 checksum and the `0`–`7` frame number are
+ * computed by the parser** (never hand-written), and a record over 240 bytes is split across frames —
+ * so the bytes round-trip through `parseFramedAstm` with zero frame **and** record warnings (see
+ * `./round-trip`). Each record is framed independently (one `ETX`-closed run per record), mirroring what
+ * `decodeAstmFrames` reassembles.
+ *
+ * @param options - The seed, optional result count, and whether to append a comment.
+ * @returns The framed byte stream.
+ * @example
+ * ```ts
+ * import { generateAstmResultFramed } from "@cosyte/synth/astm";
+ * const bytes = generateAstmResultFramed({ seed: 42 }); // Uint8Array — E1381 framed
+ * ```
+ */
+declare function generateAstmResultFramed(options: GenerateAstmOptions): Uint8Array;
+
+/**
+ * The **round-trip-through-the-parser harness** for ASTM — the headline gate for the synthetic-fixture
+ * generator. A generated ASTM record stream (or framed byte stream) is "spec-clean" only
+ * if `@cosyte/astm` — not `@cosyte/synth`'s own opinion — reads it back cleanly. Each harness parses the
+ * generated wire straight back through the parser and reports what it found, so a false "spec-clean"
+ * claim cannot hide.
+ *
+ * The **record** layer (E1394) and the **frame** layer (E1381) are separate concerns, so each gets its
+ * own harness; both report the same {@link AstmRoundTripResult} shape (the framed one additionally folds
+ * the frame-layer warnings — bad checksum, sequence gap, unterminated, oversize — into `warnings`, so a
+ * framing defect is caught by the same gate).
+ *
+ * @module
+ */
+/** The verdict of one round-trip through `@cosyte/astm`. */
+interface AstmRoundTripResult {
+    /** The serialized ASTM wire text (records: the `CR`-terminated stream; framed: the raw bytes as latin1). */
+    readonly content: string;
+    /** The warning codes the parser emitted on re-parse (record + frame layers). Empty ⇒ spec-clean. */
+    readonly warnings: readonly string[];
+    /** Whether re-serializing the re-parsed message is byte-identical to the input. */
+    readonly byteStable: boolean;
+    /** `true` iff the artifact is spec-clean: zero warnings **and** byte-stable. */
+    readonly specClean: boolean;
+}
+/**
+ * Round-trip a generated ASTM **record** stream through parse → serialize and report the verdict. A
+ * spec-clean message re-parses with **zero warnings** and re-serializes byte-identically.
+ *
+ * @param raw - The ASTM record stream (typically from `generateAstmResult` / `generateAstmOrder`).
+ * @returns The {@link AstmRoundTripResult}.
+ * @example
+ * ```ts
+ * import { generateAstmResult, astmRoundTrip } from "@cosyte/synth/astm";
+ * const { specClean } = astmRoundTrip(generateAstmResult({ seed: 1 })); // specClean === true
+ * ```
+ */
+declare function astmRoundTrip(raw: string): AstmRoundTripResult;
+/**
+ * Round-trip a generated **framed** ASTM byte stream (E1381) through decode+parse → re-frame and report
+ * the verdict. A spec-clean framed message re-parses with **zero record and zero frame warnings** (every
+ * modulo-256 checksum verifies, no sequence gap, no unterminated/oversize frame) and re-frames
+ * byte-identically.
+ *
+ * @param bytes - The framed byte stream (typically from `generateAstmResultFramed`).
+ * @returns The {@link AstmRoundTripResult} — `content` holds the framed bytes decoded as latin1.
+ * @example
+ * ```ts
+ * import { generateAstmResultFramed, astmFramedRoundTrip } from "@cosyte/synth/astm";
+ * const { specClean } = astmFramedRoundTrip(generateAstmResultFramed({ seed: 1 })); // true
+ * ```
+ */
+declare function astmFramedRoundTrip(bytes: Uint8Array): AstmRoundTripResult;
+
+/**
+ * Synthetic identity for ASTM (E1394 / CLSI LIS02) messages — every value `synth` puts into a `P`
+ * (patient) record, an `O` (order) accession, or the `H` header is minted here, and **only** from the
+ * synthetic-safety providers. ASTM's PHI-dense locus is the **`P` record**: it carries the
+ * patient **name** (`Last^First^Middle`), **birthdate**, **sex**, and the **practice-assigned** and
+ * **laboratory-assigned** patient IDs, which must stay
+ * **distinct** (the parser keeps them distinct; a generator that let one default from the other would
+ * defeat that). Every identifier is scoped to the synthetic assigning authority: there is no reserved
+ * patient-ID range for ASTM (as for MRNs generally), so the **namespace** is the
+ * guarantee. The IDs carry a clearly-synthetic prefix (`PRA` / `LAB` / `ACC`) so the `phi-scan` ASTM
+ * arm can recognize them as synthetic-AA-scoped and a real bare numeric MRN can never masquerade as one.
+ *
+ * @module
+ */
+
+/** A synthetic ASTM patient — every field drawn from `../safe`. */
+interface AstmPatient {
+    /** Name from the shipped fake-name pool, plus a fictional middle initial. */
+    readonly person: SyntheticName;
+    /** Middle initial (clearly synthetic). */
+    readonly middle: string;
+    /** Birthdate `YYYYMMDD`, from the seeded generator (no real event implied). */
+    readonly birthDate: string;
+    /** Sex code, emitted verbatim (`M` / `F` — structural, never defaulted by the builder). */
+    readonly sex: "M" | "F";
+    /** Practice-assigned patient ID — synthetic-AA scoped (`PRA`-prefixed). Distinct from the lab ID. */
+    readonly practiceAssignedId: string;
+    /** Laboratory-assigned patient ID — synthetic-AA scoped (`LAB`-prefixed). Distinct from the practice ID. */
+    readonly laboratoryAssignedId: string;
+}
+/** A synthetic ASTM order identity — the specimen / accession id and priority. */
+interface AstmOrder {
+    /** Specimen / accession id — synthetic-AA scoped (`ACC`-prefixed). */
+    readonly specimenId: string;
+    /** Priority code, emitted verbatim (`R` routine, `S` stat). */
+    readonly priority: "R" | "S";
+}
+/** A synthetic ASTM header identity — the sender and analyzer strings for the `H` record. */
+interface AstmHeaderIdentity {
+    /** The sending system id (clearly synthetic). */
+    readonly sender: string;
+    /** The analyzer / instrument string (clearly synthetic). */
+    readonly analyzer: string;
+}
+/**
+ * Mint a synthetic patient for a `P` record. Fixed draw order (name → middle → DOB → sex → practice id
+ * → lab id) so the same seed yields the same patient. The two patient IDs are minted from
+ * **independent** synthetic-identifier draws, so they are distinct by construction.
+ *
+ * @param rng - The seeded generator.
+ * @returns A synthetic {@link AstmPatient}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { astmPatient } from "@cosyte/synth/astm";
+ * const { person, practiceAssignedId, laboratoryAssignedId } = astmPatient(createRng(1));
+ * ```
+ */
+declare function astmPatient(rng: Rng): AstmPatient;
+/**
+ * Mint a synthetic order identity for an `O` record — a synthetic-AA-scoped accession id and a priority.
+ *
+ * @param rng - The seeded generator.
+ * @returns A synthetic {@link AstmOrder}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { astmOrder } from "@cosyte/synth/astm";
+ * const { specimenId } = astmOrder(createRng(1));
+ * ```
+ */
+declare function astmOrder(rng: Rng): AstmOrder;
+/**
+ * Mint a synthetic header identity for the `H` record — a clearly-synthetic sender and analyzer.
+ *
+ * @param rng - The seeded generator.
+ * @returns A synthetic {@link AstmHeaderIdentity}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { astmHeaderIdentity } from "@cosyte/synth/astm";
+ * const { sender } = astmHeaderIdentity(createRng(1));
+ * ```
+ */
+declare function astmHeaderIdentity(rng: Rng): AstmHeaderIdentity;
+
+/**
+ * A small, **license-clean** pool of example ASTM laboratory tests — the analyte codes, units, and
+ * plausible value ranges `synth` draws on when populating `O` (order) and `R` (result) records. The
+ * codes are **facts** (a LOINC number is a public identifier, and the local analyzer codes here are
+ * invented), never a bundled terminology table. Nothing clinical is asserted — a `synth` result pairs a value
+ * and a code with no claim of clinical coherence: the pool exists only to make a *structurally* realistic
+ * result record.
+ *
+ * @module
+ */
+/** One example laboratory analyte — its codes, units, reference range, and a seeded value window. */
+interface AstmExampleTest {
+    /** A local analyzer test code (invented — never a real vendor assay id). */
+    readonly localCode: string;
+    /** The public LOINC identifier for the analyte (a fact, not bundled terminology prose). */
+    readonly loinc: string;
+    /** The human-readable test name, emitted in the Universal Test ID name component. */
+    readonly name: string;
+    /** The units string, emitted verbatim in `R`-field 5 (never converted or guessed). */
+    readonly units: string;
+    /** The reference range text, emitted verbatim in `R`-field 6. */
+    readonly referenceRange: string;
+    /** Inclusive integer low bound of the seeded synthetic value (structural, not clinical). */
+    readonly valueLow: number;
+    /** Inclusive integer high bound of the seeded synthetic value. */
+    readonly valueHigh: number;
+    /** Number of decimal places to render the synthetic value with. */
+    readonly decimals: number;
+}
+/**
+ * The example test pool. A handful of common chemistry/hematology analytes, each with a public LOINC
+ * code, invented local code, units, and a value window the seeded generator samples. Frozen — the pool
+ * is shared, immutable data.
+ *
+ * @example
+ * ```ts
+ * import { EXAMPLE_ASTM_TESTS } from "@cosyte/synth/astm";
+ * EXAMPLE_ASTM_TESTS[0]?.name; // "Glucose"
+ * ```
+ */
+declare const EXAMPLE_ASTM_TESTS: readonly AstmExampleTest[];
+/** HL7 Table 0078 abnormal-flag codes `synth` draws from (emitted verbatim; never defaulted). */
+declare const ASTM_ABNORMAL_FLAGS: readonly string[];
+/** Result-status codes `synth` draws from (`F` final, `P` preliminary, `C` correction). */
+declare const ASTM_RESULT_STATUSES: readonly string[];
+/** Free-text result comments — clearly synthetic, carry no PHI. */
+declare const ASTM_COMMENT_TEXT: readonly string[];
+
+/**
+ * ASTM E1394 **vendor-quirk generation**. A quirk deviates the
+ * *structure* of an otherwise spec-clean record report (built through `@cosyte/astm`'s
+ * `buildAstmMessage`) so it round-trips through `parseAstmRecords` to **exactly** one intended, stable
+ * warning code — a code in the parser's `defineAstmProfile` tolerable set. Where a built-in public
+ * profile tolerates the quirk, the warning is **re-badged** to the value-free `PROFILE_QUIRK_APPLIED`
+ * marker (`expected: true`), exactly as the parser's `profileQuirkApplied` does.
+ *
+ * The deviation is applied **post-serialize** on the record stream. Two quirks ship:
+ *
+ * - **`unknown-escape`** → `ASTM_UNKNOWN_ESCAPE_SEQUENCE` (profile `referenceCorpus`). A non-standard
+ *   `&Z&` escape body is injected into a result's units field. Grounded on `@cosyte/astm`'s public
+ *   `referenceCorpus` profile (the redistributable kxepal/python-astm + senaite OSS corpus), which
+ *   re-badges it.
+ * - **`unknown-record-type`** → `ASTM_RECORD_UNKNOWN_TYPE`. A record's leading type letter is changed to
+ *   a site-defined `Z` — a real ASTM tolerance (the parser's tolerable set includes this code), but no
+ *   built-in profile tolerates it, so it is a `"bare"` quirk (a consumer authors a `defineAstmProfile`
+ *   to re-badge it).
+ *
+ * A quirk **never** introduces a real-looking value — it changes an escape body or a record type letter,
+ * never a P-record identity locus, so the synthetic-safety gate still runs and stays zero.
+ *
+ * @module
+ */
+
+/** Every ASTM quirk this package ships. */
+type AstmQuirkName = "unknown-escape" | "unknown-record-type";
+/**
+ * Both shipped ASTM quirks are **result-report** deviations — `unknown-escape` targets an `R` record's
+ * units field and `unknown-record-type` a `C` (comment) record, neither of which an *order* report
+ * carries. So the quirk base is always a result report (`generateAstmResult`).
+ */
+type AstmQuirkKind = "Result";
+/** The ASTM quirk registry — each recipe bound to the exact `@cosyte/astm` warning code it targets. */
+declare const ASTM_QUIRKS: Readonly<Record<AstmQuirkName, QuirkDescriptor>>;
+/** Options for {@link generateAstmQuirk}. */
+interface GenerateAstmQuirkOptions {
+    /** The seed — the same seed + quirk yields a byte-identical record stream. Defaults to `0`. */
+    readonly seed?: number;
+    /** The quirk to inject. Required. */
+    readonly quirk: AstmQuirkName;
+    /** The spec-clean base report kind. Always `"Result"` (see {@link AstmQuirkKind}). */
+    readonly kind?: AstmQuirkKind;
+}
+/**
+ * Generate one ASTM **quirk** artifact: a spec-clean record report (built through `@cosyte/astm`) with
+ * the requested vendor deviation injected post-serialize. Deterministic in `seed` + `quirk` + `kind`.
+ *
+ * @param options - Seed, quirk, and base kind. See {@link GenerateAstmQuirkOptions}.
+ * @returns The {@link QuirkArtifact} — its `content` round-trips to `intendedWarnings` exactly.
+ * @throws SynthError `SYNTH_UNSUPPORTED_QUIRK` if `quirk` is not a supported ASTM quirk.
+ * @throws Error if the base report does not contain the structural anchor the quirk targets.
+ * @example
+ * ```ts
+ * import { generateAstmQuirk, astmQuirkRoundTrip } from "@cosyte/synth/astm";
+ * const rt = astmQuirkRoundTrip(generateAstmQuirk({ seed: 1, quirk: "unknown-escape" }));
+ * rt.withProfile?.tolerated; // true — `referenceCorpus` re-badges ASTM_UNKNOWN_ESCAPE_SEQUENCE
+ * ```
+ */
+declare function generateAstmQuirk(options: GenerateAstmQuirkOptions): QuirkArtifact;
+/**
+ * Round-trip an ASTM quirk artifact through `@cosyte/astm` and report the intended-warning verdict: a bare
+ * parse must produce **exactly** the intended code, and — when a built-in public
+ * profile tolerates the quirk — the profiled parse must re-badge it to `PROFILE_QUIRK_APPLIED`.
+ *
+ * @param artifact - The quirk artifact (from {@link generateAstmQuirk}).
+ * @returns The {@link QuirkRoundTripResult}.
+ * @example
+ * ```ts
+ * import { generateAstmQuirk, astmQuirkRoundTrip } from "@cosyte/synth/astm";
+ * astmQuirkRoundTrip(generateAstmQuirk({ seed: 1, quirk: "unknown-escape" })).intendedWarningHeld;
+ * ```
+ */
+declare function astmQuirkRoundTrip(artifact: QuirkArtifact): QuirkRoundTripResult;
+/** Options for {@link astmQuirkCorpus}. */
+interface AstmQuirkCorpusOptions {
+    /** The seed for the whole corpus (deterministic). */
+    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 ASTM quirk. Validated; unsupported ⇒ fatal. */
+    readonly quirks?: readonly AstmQuirkName[];
+    /** A {@link SynthProfile} whose `quirks` drive the corpus (validated). Takes precedence over `quirks`. */
+    readonly profile?: SynthProfile;
+}
+/**
+ * Build a reproducible {@link Corpus} of ASTM quirk artifacts. Each artifact's `warnings` record the
+ * intended code for its quirk; the manifest lists the applied quirk names.
+ *
+ * @param options - Seed, count, and the quirk selection. See {@link AstmQuirkCorpusOptions}.
+ * @returns A deep-frozen {@link Corpus}.
+ * @example
+ * ```ts
+ * import { astmQuirkCorpus } from "@cosyte/synth/astm";
+ * astmQuirkCorpus({ seed: 42 }).manifest.quirks; // the applied quirk names
+ * ```
+ */
+declare function astmQuirkCorpus(options: AstmQuirkCorpusOptions): Corpus;
+/** A ready-made {@link SynthProfile} requesting every built-in ASTM quirk. */
+declare const astmQuirkProfile: SynthProfile;
+
+/**
+ * `@cosyte/synth/astm` — the ASTM generation surface, exposed as its own subpath so importing the
+ * package root does **not** pull `@cosyte/astm`. This is the **lazy, per-format** boundary: a consumer
+ * who only needs ASTM fixtures imports `@cosyte/synth/astm`; one who needs only the core primitives
+ * never loads a parser.
+ * `@cosyte/astm` is an **optional peer dependency** — present only for this subpath.
+ *
+ * This subpath ships spec-clean generation of the E1394 record report and its E1381 framed twin, each
+ * built through `@cosyte/astm`'s own emit surface:
+ *
+ * - **Records (E1394):** `generateAstmResult` (`H`/`P`/`O`/`R`…/`C`/`L`) and `generateAstmOrder`
+ *   (`H`/`P`/`O`/`L`) via `buildAstmMessage` — each round-tripping through `parseAstmRecords` with zero
+ *   warnings and byte-stable, and carrying a `P` record whose name / DOB / practice+lab IDs are all
+ *   synthetic-by-construction. The practice- and laboratory-assigned patient IDs are
+ *   minted independently, so they stay **distinct**.
+ * - **Framing (E1381):** `generateAstmResultFramed` via `composeAstmFrames` — the modulo-256 checksum
+ *   and the `0`–`7` frame number are **computed by the parser, never faked**, and the bytes round-trip
+ *   through `parseFramedAstm` with zero frame **and** record warnings.
+ *
+ * @module
+ */
+
+/** Every ASTM message kind {@link astmCorpus} generates — the label used as the corpus `kind`. */
+type AstmCorpusKind = "Result" | "Order";
+/** Options for {@link astmCorpus}. */
+interface AstmCorpusOptions {
+    /** The seed for the whole corpus (deterministic). */
+    readonly seed: number;
+    /** How many messages to generate. Defaults to the length of the mix. */
+    readonly count?: number;
+    /** The message kinds to cycle through. Defaults to one of each. */
+    readonly mix?: readonly AstmCorpusKind[];
+}
+/**
+ * Build a reproducible {@link Corpus} of spec-clean ASTM messages. Each message is generated from a
+ * distinct sub-seed derived from the corpus seed (so the set is deterministic) and round-tripped through
+ * `@cosyte/astm`; the per-artifact `warnings` record the parser's verdict (empty ⇒ spec-clean).
+ *
+ * @param options - Seed, count, and the message mix. See {@link AstmCorpusOptions}.
+ * @returns A deep-frozen {@link Corpus}.
+ * @example
+ * ```ts
+ * import { astmCorpus } from "@cosyte/synth/astm";
+ * const corpus = astmCorpus({ seed: 42 });
+ * corpus.artifacts.every((a) => a.warnings.length === 0); // true — spec-clean
+ * ```
+ */
+declare function astmCorpus(options: AstmCorpusOptions): Corpus;
+
+export { ASTM_ABNORMAL_FLAGS, ASTM_COMMENT_TEXT, ASTM_QUIRKS, ASTM_RESULT_STATUSES, type AstmCorpusKind, type AstmCorpusOptions, type AstmExampleTest, type AstmHeaderIdentity, type AstmOrder, type AstmPatient, type AstmQuirkCorpusOptions, type AstmQuirkKind, type AstmQuirkName, type AstmRoundTripResult, EXAMPLE_ASTM_TESTS, type GenerateAstmOptions, type GenerateAstmQuirkOptions, astmCorpus, astmFramedRoundTrip, astmHeaderIdentity, astmOrder, astmPatient, astmQuirkCorpus, astmQuirkProfile, astmQuirkRoundTrip, astmRoundTrip, generateAstmOrder, generateAstmQuirk, generateAstmResult, generateAstmResultFramed };