@cosyte/synth 0.0.1

package/dist/ccda/index.d.ts

@@ -0,0 +1,380 @@
+import { S as SyntheticName, a as SyntheticIdentifier, R as Rng, C as Corpus } from '../providers-OLz3zAc-.js';
+import { CcdaDocument, BuildCcdaPatient, BuildCode, BuildQuantity } from '@cosyte/ccda';
+import { C as CodeConcept, Q as QuantConcept } from '../example-codes-DeXcnCSK.js';
+import { Q as QuirkDescriptor, S as SynthProfile, a as QuirkArtifact, b as QuirkRoundTripResult } from '../quirk-JLyO1Ncj.js';
+
+/**
+ * Synthetic **C-CDA document generation** — a spec-clean Continuity of Care Document
+ * (CCD) or Referral Note built **through `@cosyte/ccda`'s `buildCcda`**, so template IDs, LOINC section
+ * codes, and structured/narrative agreement are the builder's own (spec-clean *by construction*), and
+ * every `recordTarget` / clinical identifier is drawn from the synthetic-safety providers.
+ *
+ * The document round-trips through `parseCcda` with **zero warnings** — the builder's round-trip-by-
+ * construction guarantee, re-verified independently by {@link ./round-trip.roundTrip}. Coverage tracks
+ * `buildCcda`'s section/doc-type maturity: the CCD SHALL sections (Problems,
+ * Allergies, Medications, Results, Vital Signs) plus Immunizations, Procedures, and Social History
+ * (Smoking Status). Clinical *content* is drawn from the reused, license-clean example-code pools; a
+ * `synth` document exercises the parser, it is **not** a clinically-coherent record.
+ *
+ * @module
+ */
+
+/** The C-CDA document type a generator emits — the two `buildCcda` supports. */
+type CcdaDocumentType = "ccd" | "referralNote";
+/** Options common to every C-CDA generator. */
+interface GenerateCcdaOptions {
+    /** The seed (deterministic — same seed yields a byte-identical document). Defaults to `0`. */
+    readonly seed?: number;
+    /** The document type to emit. Defaults to `"ccd"`. */
+    readonly documentType?: CcdaDocumentType;
+}
+/**
+ * Generate a spec-clean synthetic C-CDA document (CCD by default, or Referral Note), built through
+ * `@cosyte/ccda`'s `buildCcda`. The returned {@link CcdaDocument} round-trips through `parseCcda` with
+ * zero warnings, and the same seed yields a byte-identical document.
+ *
+ * @param options - Seed and document type. See {@link GenerateCcdaOptions}.
+ * @returns The `@cosyte/ccda` `CcdaDocument` (serialize via `serializeCcda(doc)` or `doc.toString()`).
+ * @example
+ * ```ts
+ * import { generateCcda } from "@cosyte/synth/ccda";
+ * import { serializeCcda } from "@cosyte/ccda";
+ * const xml = serializeCcda(generateCcda({ seed: 42 }));
+ * ```
+ */
+declare function generateCcda(options?: GenerateCcdaOptions): CcdaDocument;
+/**
+ * Generate a spec-clean synthetic **Continuity of Care Document (CCD)**.
+ *
+ * @param options - Seed (deterministic). See {@link GenerateCcdaOptions}.
+ * @returns The `CcdaDocument`.
+ * @example
+ * ```ts
+ * import { generateCcd, roundTrip } from "@cosyte/synth/ccda";
+ * roundTrip(generateCcd({ seed: 1 })).specClean; // true
+ * ```
+ */
+declare function generateCcd(options?: Omit<GenerateCcdaOptions, "documentType">): CcdaDocument;
+/**
+ * Generate a spec-clean synthetic **Referral Note** — the second document type `buildCcda` supports,
+ * with its own US Realm Header specialization and Reason-for-Referral / Assessment narrative sections.
+ *
+ * @param options - Seed (deterministic). See {@link GenerateCcdaOptions}.
+ * @returns The `CcdaDocument`.
+ * @example
+ * ```ts
+ * import { generateReferralNote } from "@cosyte/synth/ccda";
+ * generateReferralNote({ seed: 1 }).documentType; // "referralNote"
+ * ```
+ */
+declare function generateReferralNote(options?: Omit<GenerateCcdaOptions, "documentType">): CcdaDocument;
+
+/**
+ * The **round-trip-through-the-parser harness** for C-CDA — the headline gate for the synthetic-fixture
+ * generator. A generated document is "spec-clean" only if `@cosyte/ccda` — not
+ * `@cosyte/synth`'s own opinion — reads it back cleanly. This harness serializes a generated document,
+ * parses it straight back through `parseCcda`, and reports what the parser found, so a false
+ * "spec-clean" claim cannot hide.
+ *
+ * `@cosyte/ccda`'s `buildCcda` is round-trip-by-construction (it emits through the same DOM the parser
+ * reads), so a clean build carries zero warnings — but this harness re-verifies that *independently*,
+ * against the parser, because the parser is the judge.
+ *
+ * @module
+ */
+
+/** The verdict of one round-trip through `@cosyte/ccda`. */
+interface RoundTripResult {
+    /** The serialized C-CDA XML (the builder/serializer's own conservative emit). */
+    readonly content: string;
+    /** The warning codes the parser emitted on re-parse. Empty ⇒ spec-clean. */
+    readonly warnings: readonly string[];
+    /** Whether re-serializing the re-parsed document is byte-identical to `content`. */
+    readonly byteStable: boolean;
+    /** `true` iff the artifact is spec-clean: zero warnings **and** byte-stable. */
+    readonly specClean: boolean;
+}
+/**
+ * Round-trip a generated `@cosyte/ccda` `CcdaDocument` through serialize → parse → serialize and report
+ * the verdict. A spec-clean document re-parses with **zero warnings** and re-serializes byte-identically.
+ *
+ * @param doc - The document to check (typically from {@link ./ccd.generateCcd}).
+ * @returns The {@link RoundTripResult}.
+ * @example
+ * ```ts
+ * import { generateCcd, roundTrip } from "@cosyte/synth/ccda";
+ * const { specClean, warnings } = roundTrip(generateCcd({ seed: 1 }));
+ * // specClean === true, warnings.length === 0
+ * ```
+ */
+declare function roundTrip(doc: CcdaDocument): RoundTripResult;
+
+/**
+ * Synthetic C-CDA patient identity — the `recordTarget` demographics for a generated document, every
+ * field minted from the synthetic-safety providers in `../safe`. No value a generated
+ * C-CDA carries at a PHI locus can be real or plausibly-real: the name is from the shipped fake-name
+ * pool, the MRN lives under the synthetic assigning-authority OID (never a real facility namespace),
+ * and the birth date comes from the seeded generator (never wall-clock).
+ *
+ * The draw order is **fixed** (name → MRN → DOB → gender) so the same seed yields the same identity —
+ * the reproducibility contract.
+ *
+ * @module
+ */
+
+/** A synthetic C-CDA patient identity — the values threaded into a document's `recordTarget`. */
+interface CcdaPatientIdentity {
+    /** The `BuildCcdaPatient` `@cosyte/ccda` consumes for the single `recordTarget`. */
+    readonly patient: BuildCcdaPatient;
+    /** The name from the shipped fake-name pool (also used to compose synthetic narrative/email). */
+    readonly person: SyntheticName;
+    /** The medical-record identifier, scoped to the synthetic assigning authority. */
+    readonly mrn: SyntheticIdentifier;
+}
+/**
+ * Mint a complete synthetic {@link CcdaPatientIdentity}. Every value comes from a synthetic-safety
+ * provider — no code path here can return a real identifier. The MRN is scoped to the
+ * synthetic assigning-authority OID (`mrnRoot`), so it is non-colliding by *namespace*, not by value.
+ *
+ * @param rng - The seeded generator.
+ * @returns A synthetic {@link CcdaPatientIdentity}.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { ccdaPatientIdentity } from "@cosyte/synth/ccda";
+ * // const { patient } = ccdaPatientIdentity(createRng(1));
+ * ```
+ */
+declare function ccdaPatientIdentity(rng: Rng): CcdaPatientIdentity;
+
+/**
+ * The C-CDA example-code pool — a thin adapter that **reuses** the same license-clean, public
+ * code facts the FHIR generators ship (`../fhir/example-codes.ts`), reshaped into `@cosyte/ccda`'s
+ * `BuildCode` tuple (an OID `codeSystem` instead of a FHIR `system` URI). Reusing one source of truth
+ * keeps the LOINC / RxNorm / SNOMED / CVX pools consistent across the FHIR and C-CDA surfaces;
+ * `@cosyte/synth` still bundles
+ * **no** terminology content — these are public spec-example codes, not copyrighted tables.
+ *
+ * Nothing here is PHI: codes and their display text are not patient identifiers. The synthetic-safety
+ * invariant governs identity fields (name / DOB / MRN / telecom), which come from `../safe`.
+ *
+ * @module
+ */
+
+/**
+ * Adapt a FHIR {@link CodeConcept} to a `@cosyte/ccda` {@link BuildCode}, resolving its `system` URI to
+ * the matching OID. The `codeSystem` is always set explicitly (never left to a per-slot default), so a
+ * SNOMED allergen or a LOINC panel carries the right OID regardless of which builder slot consumes it.
+ *
+ * @param concept - The FHIR-shaped `{ system, code, display }` concept.
+ * @returns The `@cosyte/ccda` `BuildCode`.
+ * @throws {Error} When the concept's `system` URI has no known OID mapping.
+ * @example
+ * ```ts
+ * import { toBuildCode } from "@cosyte/synth/ccda";
+ * // toBuildCode({ system: "http://snomed.info/sct", code: "59621000", display: "Essential hypertension" });
+ * ```
+ */
+declare function toBuildCode(concept: CodeConcept): BuildCode;
+/**
+ * Draw a synthetic-but-structurally-sane {@link BuildQuantity} for a quantitative concept — a value in
+ * the concept's plausible band (from the seeded generator, so reproducible) rendered to the concept's
+ * decimal precision, with its UCUM unit. The value implies **no** real measurement.
+ *
+ * @param rng - The seeded generator.
+ * @param concept - The quantitative concept (LOINC code + UCUM unit + value band).
+ * @returns A `BuildQuantity` (`{ value, unit }`) for the C-CDA builder.
+ * @example
+ * ```ts
+ * import { createRng } from "@cosyte/synth";
+ * import { quantityFor, LAB_RESULTS } from "@cosyte/synth/ccda";
+ * // quantityFor(createRng(1), LAB_RESULTS[0]);
+ * ```
+ */
+declare function quantityFor(rng: Rng, concept: QuantConcept): BuildQuantity;
+/** SNOMED CT problem/condition example codes (Problems / Past Medical History). */
+declare const PROBLEMS: readonly CodeConcept[];
+/** RxNorm / SNOMED CT allergen example codes (Allergies). */
+declare const ALLERGENS: readonly CodeConcept[];
+/** SNOMED CT allergy-reaction manifestation example codes. */
+declare const ALLERGY_REACTIONS: readonly CodeConcept[];
+/** RxNorm medication example codes (Medications). */
+declare const MEDICATIONS: readonly CodeConcept[];
+/** LOINC laboratory-result example codes with UCUM units + value bands (Results members). */
+declare const LAB_RESULTS: readonly QuantConcept[];
+/** LOINC panel example codes (the Result Organizer `code`). */
+declare const RESULT_PANELS: readonly CodeConcept[];
+/** LOINC vital-sign example codes with UCUM units + value bands (Vital Signs members). */
+declare const VITAL_SIGNS: readonly QuantConcept[];
+/** CVX vaccine example codes (Immunizations). */
+declare const VACCINES: readonly CodeConcept[];
+/** SNOMED CT procedure example codes (Procedures). */
+declare const PROCEDURES: readonly CodeConcept[];
+/**
+ * SNOMED CT Current Smoking Status value-set example codes (Social History). Public SNOMED CT
+ * identifiers used as structural fillers; `@cosyte/synth` bundles no SNOMED content.
+ */
+declare const SMOKING_STATUSES: readonly BuildCode[];
+/**
+ * NCI Thesaurus administration-route example codes (Medications / Immunizations `route`). Public NCI
+ * concept ids used as structural fillers.
+ */
+declare const ROUTES: readonly BuildCode[];
+
+/**
+ * C-CDA **vendor-quirk generation**. A quirk deviates the
+ * *structure* of an otherwise spec-clean document (built through `@cosyte/ccda`'s `buildCcda`) so it
+ * round-trips through `parseCcda` to **exactly** one intended, stable warning code — the tolerance a
+ * `defineCcdaProfile` profile encodes. With the matching built-in profile active, that warning is
+ * **re-badged** to the value-free `PROFILE_QUIRK_APPLIED` marker (`expected: true`, `toleratedCode` = the
+ * original), exactly as the parser's `profileQuirkApplied` does.
+ *
+ * The deviation is applied **post-serialize**. Three quirks ship, each
+ * publicly grounded and re-badged by a built-in public profile:
+ *
+ * - **`template-extension-absent`** → `TEMPLATE_EXTENSION_ABSENT` (profile `legacyR11`). The R2.1
+ *   `@extension="2015-08-01"` version stamp is dropped from the document-type templateId — a legacy
+ *   R1.1-era document shape.
+ * - **`deprecated-loinc`** → `DEPRECATED_LOINC` (profile `smartScorecard`). A result/vital observation
+ *   LOINC code is swapped to a known-deprecated LOINC (`41909-3`).
+ * - **`deprecated-code-system`** → `DEPRECATED_CODE_SYSTEM` (profile `smartScorecard`). A problem
+ *   observation's value is swapped to a deprecated code system (ICD-9-CM `2.16.840.1.113883.6.103`).
+ *
+ * A quirk **never** introduces a real-looking value — it changes a template stamp or a code, never a PHI
+ * locus, so the synthetic-safety gate still runs and stays zero.
+ *
+ * @module
+ */
+
+/** Every C-CDA quirk this package ships. */
+type CcdaQuirkName = "template-extension-absent" | "deprecated-loinc" | "deprecated-code-system";
+/** The C-CDA quirk registry — each recipe bound to the exact `@cosyte/ccda` warning code it targets. */
+declare const CCDA_QUIRKS: Readonly<Record<CcdaQuirkName, QuirkDescriptor>>;
+/**
+ * Apply a C-CDA quirk transform to a spec-clean document, or **fail closed**. Refuses to return a
+ * document that does not carry the intended deviation (a quirk whose structural anchor is absent) —
+ * a fixture that silently lost its quirk would test the wrong thing.
+ *
+ * @param quirk - The quirk to inject.
+ * @param cleanXml - The spec-clean C-CDA XML.
+ * @returns The quirked XML.
+ * @throws Error when the quirk found no structural anchor to mutate.
+ * @example
+ * ```ts
+ * import { injectCcdaQuirk } from "@cosyte/synth/ccda";
+ * injectCcdaQuirk("template-extension-absent", cleanXml);
+ * ```
+ */
+declare function injectCcdaQuirk(quirk: CcdaQuirkName, cleanXml: string): string;
+/** Options for {@link generateCcdaQuirk}. */
+interface GenerateCcdaQuirkOptions {
+    /** The seed — the same seed + quirk yields a byte-identical document. Defaults to `0`. */
+    readonly seed?: number;
+    /** The quirk to inject. Required. */
+    readonly quirk: CcdaQuirkName;
+    /** The spec-clean base document type. Defaults to `"ccd"`. */
+    readonly documentType?: CcdaDocumentType;
+}
+/**
+ * Generate one C-CDA **quirk** artifact: a spec-clean document (built through `@cosyte/ccda`'s
+ * `buildCcda`) with the requested vendor deviation injected post-serialize. Deterministic in `seed` +
+ * `quirk` + `documentType`.
+ *
+ * @param options - Seed, quirk, and base document type. See {@link GenerateCcdaQuirkOptions}.
+ * @returns The {@link QuirkArtifact} — its `content` round-trips to `intendedWarnings` exactly.
+ * @throws SynthError `SYNTH_UNSUPPORTED_QUIRK` if `quirk` is not a supported C-CDA quirk.
+ * @throws Error if the base document does not contain the structural anchor the quirk targets.
+ * @example
+ * ```ts
+ * import { generateCcdaQuirk, ccdaQuirkRoundTrip } from "@cosyte/synth/ccda";
+ * const rt = ccdaQuirkRoundTrip(generateCcdaQuirk({ seed: 1, quirk: "deprecated-loinc" }));
+ * rt.withProfile?.tolerated; // true — `smartScorecard` re-badges DEPRECATED_LOINC
+ * ```
+ */
+declare function generateCcdaQuirk(options: GenerateCcdaQuirkOptions): QuirkArtifact;
+/**
+ * Round-trip a C-CDA quirk artifact through `@cosyte/ccda` and report the intended-warning verdict: a bare
+ * parse must produce **exactly** the intended code, and the matching public profile
+ * must re-badge it to `PROFILE_QUIRK_APPLIED`.
+ *
+ * @param artifact - The quirk artifact (from {@link generateCcdaQuirk}).
+ * @returns The {@link QuirkRoundTripResult}.
+ * @example
+ * ```ts
+ * import { generateCcdaQuirk, ccdaQuirkRoundTrip } from "@cosyte/synth/ccda";
+ * ccdaQuirkRoundTrip(generateCcdaQuirk({ seed: 1, quirk: "deprecated-loinc" })).intendedWarningHeld;
+ * ```
+ */
+declare function ccdaQuirkRoundTrip(artifact: QuirkArtifact): QuirkRoundTripResult;
+/** Options for {@link ccdaQuirkCorpus}. */
+interface CcdaQuirkCorpusOptions {
+    /** 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 C-CDA quirk. Validated; unsupported ⇒ fatal. */
+    readonly quirks?: readonly CcdaQuirkName[];
+    /** A {@link SynthProfile} whose `quirks` drive the corpus (validated). Takes precedence over `quirks`. */
+    readonly profile?: SynthProfile;
+    /** The base document type each quirk is injected into. Defaults to `"ccd"`. */
+    readonly documentType?: CcdaDocumentType;
+}
+/**
+ * Build a reproducible {@link Corpus} of C-CDA 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 CcdaQuirkCorpusOptions}.
+ * @returns A deep-frozen {@link Corpus}.
+ * @example
+ * ```ts
+ * import { ccdaQuirkCorpus } from "@cosyte/synth/ccda";
+ * ccdaQuirkCorpus({ seed: 42 }).manifest.quirks; // the applied quirk names
+ * ```
+ */
+declare function ccdaQuirkCorpus(options: CcdaQuirkCorpusOptions): Corpus;
+/** A ready-made {@link SynthProfile} requesting every built-in C-CDA quirk. */
+declare const ccdaQuirkProfile: SynthProfile;
+
+/**
+ * `@cosyte/synth/ccda` — the C-CDA generation surface, exposed as its own subpath so importing the
+ * package root does **not** pull `@cosyte/ccda`. This is the **lazy, per-format** boundary: a consumer
+ * who only needs C-CDA fixtures imports `@cosyte/synth/ccda`; one who needs only the core primitives
+ * never loads a parser.
+ * `@cosyte/ccda` is an **optional peer dependency** — present only for this subpath.
+ *
+ * This subpath ships spec-clean C-CDA document generation via `@cosyte/ccda`'s
+ * `buildCcda`: a **CCD** (`generateCcd`) and a **Referral Note** (`generateReferralNote`), each built
+ * through the parser's own emitter so it round-trips through `parseCcda` with zero warnings, and each
+ * drawing every identity value from the synthetic-safety providers.
+ *
+ * @module
+ */
+
+/** Every C-CDA document kind {@link ccdaCorpus} generates — the `documentType` used as the corpus `kind`. */
+type CcdaCorpusKind = CcdaDocumentType;
+/** Options for {@link ccdaCorpus}. */
+interface CcdaCorpusOptions {
+    /** The seed for the whole corpus (deterministic). */
+    readonly seed: number;
+    /** How many documents to generate. Defaults to `1`. */
+    readonly count?: number;
+    /** The document types to cycle through. Defaults to one CCD + one Referral Note. */
+    readonly mix?: readonly CcdaCorpusKind[];
+}
+/**
+ * Build a reproducible {@link Corpus} of spec-clean C-CDA documents. Each document is generated from a
+ * distinct sub-seed derived from the corpus seed (so the set is deterministic) and round-tripped through
+ * `@cosyte/ccda`; the per-artifact `warnings` record the parser's verdict (empty ⇒ spec-clean).
+ *
+ * @param options - Seed, count, and the document mix. See {@link CcdaCorpusOptions}.
+ * @returns A deep-frozen {@link Corpus}.
+ * @example
+ * ```ts
+ * import { ccdaCorpus } from "@cosyte/synth/ccda";
+ * const corpus = ccdaCorpus({ seed: 42, count: 4 });
+ * corpus.artifacts.every((a) => a.warnings.length === 0); // true — spec-clean
+ * ```
+ */
+declare function ccdaCorpus(options: CcdaCorpusOptions): Corpus;
+
+export { ALLERGENS, ALLERGY_REACTIONS, CCDA_QUIRKS, type CcdaCorpusKind, type CcdaCorpusOptions, type CcdaDocumentType, type CcdaPatientIdentity, type CcdaQuirkCorpusOptions, type CcdaQuirkName, type GenerateCcdaOptions, type GenerateCcdaQuirkOptions, LAB_RESULTS, MEDICATIONS, PROBLEMS, PROCEDURES, RESULT_PANELS, ROUTES, type RoundTripResult, SMOKING_STATUSES, VACCINES, VITAL_SIGNS, ccdaCorpus, ccdaPatientIdentity, ccdaQuirkCorpus, ccdaQuirkProfile, ccdaQuirkRoundTrip, generateCcd, generateCcda, generateCcdaQuirk, generateReferralNote, injectCcdaQuirk, quantityFor, roundTrip, toBuildCode };