@cosyte/synth 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,407 @@
+import { s as ssn, p as phone, n as name, e as email, i as ipv4, c as ipv6, u as uuid, d as identifier, f as address, g as dateYmd, h as npi, j as dea } from './providers-OLz3zAc-.js';
+export { A as Artifact, C as Corpus, k as CorpusManifest, R as Rng, l as SsnBlock, m as SynthFormat, b as SyntheticAddress, a as SyntheticIdentifier, S as SyntheticName, o as createRng, q as makeCorpus } from './providers-OLz3zAc-.js';
+export { P as PROFILE_QUIRK_APPLIED, a as QuirkArtifact, Q as QuirkDescriptor, c as QuirkProfileDisposition, d as QuirkProfiledVerdict, b as QuirkRoundTripResult, S as SynthProfile, e as SynthProfileSpec, f as assertIntendedWarnings, g as defineSynthProfile, p as profileTolerated, r as resolveQuirk, s as sameCodeSet, v as validateProfileQuirks } from './quirk-JLyO1Ncj.js';
+
+/**
+ * The reserved / never-collide identifier facts that make a `@cosyte/synth` value **provably
+ * synthetic** — the ground truth behind the synthetic-safety invariant.
+ *
+ * These are **facts**, not copyrighted prose: authoritative ranges published by SSA, NANPA, and the
+ * IETF that are guaranteed never to denote a real person or a real routable resource. Every provider
+ * draws only from these; the predicates here are the executable half of the CI synthetic-safety gate —
+ * they let a test assert that no emitted value falls **outside** a reserved source.
+ *
+ * Sources:
+ * - **SSN** — SSA never issues area numbers `000`, `666`, or `900–999`; the `987-65-4320…4329` block
+ *   is SSA's explicitly-reserved advertising range. (ssa.gov)
+ * - **Phone** — NANP reserves `555-0100…555-0199` as the fictional/non-working line range. (nanpa.com)
+ * - **Email/domain** — RFC 2606 / RFC 6761 reserved: `example.com`/`.net`/`.org` and the `.example`,
+ *   `.test`, `.invalid`, `.localhost` TLDs.
+ * - **IP** — RFC 5737 IPv4 TEST-NET-1/2/3 (`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`) and
+ *   RFC 3849 IPv6 documentation prefix `2001:db8::/32`.
+ * - **NPI** — a real National Provider Identifier is a 10-digit number whose last digit is a Luhn
+ *   check digit computed over the `80840` prefix + the 9-digit base (CMS NPI check-digit rule, ISO
+ *   7812). A number whose check digit is **wrong** therefore cannot be a NPPES-issued NPI. `synth`
+ *   emits NPIs with a deliberately-invalid check digit, so no generated NPI can collide with a real
+ *   provider.
+ *
+ * @module
+ */
+/**
+ * The synthetic **assigning authority** `@cosyte/synth` mints MRNs / account / member identifiers
+ * under. There is **no** reserved MRN range (an MRN is unique only within its assigning-authority /
+ * OID namespace), so — a documented design decision — every synthetic identifier
+ * is scoped to a namespace that clearly cannot be a real facility's: a `SYNTH`-labelled authority whose
+ * OID lives under HL7's designated **example** root `2.16.840.1.113883.19`. A value under this AA can
+ * never collide with a real record because the *namespace itself* is synthetic.
+ */
+declare const SYNTHETIC_ASSIGNING_AUTHORITY: Readonly<{
+    /** The human-readable assigning-authority namespace id (HL7 HD.1). */
+    namespaceId: "COSYTE-SYNTH";
+    /** The universal id — an OID under HL7's example arc `2.16.840.1.113883.19` (HD.2). */
+    universalId: "2.16.840.1.113883.19.999";
+    /** The universal id type (HD.3). */
+    universalIdType: "ISO";
+}>;
+/** RFC 2606 / 6761 reserved email domains `@cosyte/synth` draws from. */
+declare const RESERVED_EMAIL_DOMAINS: readonly string[];
+/** RFC 5737 IPv4 documentation (TEST-NET) `/24` network prefixes. */
+declare const TEST_NET_V4_PREFIXES: readonly string[];
+/** RFC 3849 IPv6 documentation prefix. */
+declare const DOC_V6_PREFIX = "2001:db8";
+/**
+ * The `80840` prefix prepended to a 10-digit NPI before the Luhn check (the CMS NPI check-digit
+ * rule — `80840` is the ISO 7812 issuer identifier for the US health-application namespace). A real
+ * NPI satisfies `luhn("80840" + npi) ≡ 0 (mod 10)`.
+ */
+declare const NPI_LUHN_PREFIX = "80840";
+/**
+ * The Luhn sum (mod 10) of a numeric string, doubling every second digit from the right. Used to
+ * verify (or deliberately break) an NPI check digit.
+ *
+ * @param digits - A string of decimal digits.
+ * @returns The Luhn sum modulo 10 (0 ⇒ the string passes the Luhn check).
+ * @internal
+ */
+declare function luhnMod10(digits: string): number;
+/**
+ * The correct NPI check digit for a 9-digit base — the value that makes `80840` + base + check pass
+ * the Luhn check.
+ *
+ * @param base9 - The 9-digit NPI base (positions 1–9).
+ * @returns The check digit (`0`–`9`) a real NPI would carry for this base.
+ * @example
+ * ```ts
+ * import { npiCheckDigit } from "@cosyte/synth";
+ * npiCheckDigit("123456789"); // 3 — so 1234567893 is a Luhn-valid NPI shape
+ * ```
+ */
+declare function npiCheckDigit(base9: string): number;
+/**
+ * The DEA-registration prefix letters `@cosyte/synth` draws a synthetic DEA number's first character
+ * from. A real DEA number is `<registrant-type><last-name-initial>` + 7 digits; the first letter is the
+ * registrant type (A/B/F/G/M/P/R/X are the widely-published values; the second letter is the
+ * registrant's last-name initial). These letters are a **fact** about the number's shape, not
+ * copyrighted prose — they only shape the value; the synthetic guarantee is the deliberately-**invalid
+ * checksum** (see {@link dea} / {@link isSyntheticDea}).
+ */
+declare const DEA_REGISTRANT_TYPES: readonly string[];
+/**
+ * The correct DEA check digit for a 7-digit numeric base. The published DEA checksum is
+ * `(d1 + d3 + d5) + 2·(d2 + d4 + d6)`, whose **units digit** is the 7th (check) digit. A real DEA
+ * number satisfies this; a number whose 7th digit differs cannot be a validly-issued DEA registration.
+ *
+ * @param base6 - The first 6 digits of the DEA number (positions 1–6).
+ * @returns The check digit (`0`–`9`) a real DEA number would carry for this base.
+ * @example
+ * ```ts
+ * import { deaCheckDigit } from "@cosyte/synth";
+ * deaCheckDigit("123456"); // the units digit of (1+3+5) + 2·(2+4+6)
+ * ```
+ */
+declare function deaCheckDigit(base6: string): number;
+/**
+ * Whether a DEA number (`XX` + 7 digits, case-insensitive) is **provably synthetic** — its check digit
+ * (the 7th digit) does **not** match the published DEA checksum, so it cannot be a validly-issued DEA
+ * registration. A checksum-valid DEA number (which *could* denote a real prescriber) returns `false`; a
+ * value that is not the DEA shape returns `false`.
+ *
+ * @param value - The candidate DEA number (with or without incidental separators).
+ * @returns `true` when the DEA number's checksum is wrong (never a real DEA registration).
+ * @example
+ * ```ts
+ * import { isSyntheticDea } from "@cosyte/synth";
+ * isSyntheticDea("AF1234561"); // depends on the base — true when the 7th digit is wrong
+ * ```
+ */
+declare function isSyntheticDea(value: string): boolean;
+/**
+ * Whether a 10-digit NPI is **provably synthetic** — i.e. its check digit is invalid, so it cannot be
+ * a NPPES-issued NPI. A Luhn-valid 10-digit NPI (which *could* denote a real registered provider)
+ * returns `false`; a non-10-digit value returns `false` (not an NPI shape).
+ *
+ * @param value - The candidate NPI (digits only, or with incidental separators).
+ * @returns `true` when the NPI's check digit is wrong (never a real NPI).
+ * @example
+ * ```ts
+ * import { isSyntheticNpi } from "@cosyte/synth";
+ * isSyntheticNpi("1234567894"); // true  — invalid check digit (valid would be 1234567893)
+ * isSyntheticNpi("1234567893"); // false — Luhn-valid, could be a real NPI
+ * ```
+ */
+declare function isSyntheticNpi(value: string): boolean;
+/**
+ * Whether a `ddd-dd-dddd` (or `ddddddddd`) SSN string is drawn from an SSA never-issued / reserved
+ * space — area `000`, `666`, or `900–999`. A real, issuable SSN returns `false`.
+ *
+ * @param value - The candidate SSN (dashes optional).
+ * @returns `true` when the SSN is provably synthetic.
+ * @example
+ * ```ts
+ * import { isSyntheticSsn } from "@cosyte/synth";
+ * isSyntheticSsn("900-12-3456"); // true (never issued)
+ * isSyntheticSsn("123456789");   // false (issuable area 123)
+ * ```
+ */
+declare function isSyntheticSsn(value: string): boolean;
+/**
+ * Whether a phone string contains the NANP `555-0100…555-0199` reserved fictional line range.
+ *
+ * @param value - The candidate phone (any formatting).
+ * @returns `true` when the number is in the reserved fictional block.
+ * @example
+ * ```ts
+ * import { isSyntheticPhone } from "@cosyte/synth";
+ * isSyntheticPhone("(202) 555-0142"); // true
+ * ```
+ */
+declare function isSyntheticPhone(value: string): boolean;
+/**
+ * Whether an email's domain is an RFC 2606 / 6761 reserved / test domain.
+ *
+ * @param value - The candidate email address.
+ * @returns `true` when the domain is reserved (never real).
+ * @example
+ * ```ts
+ * import { isSyntheticEmail } from "@cosyte/synth";
+ * isSyntheticEmail("faux.testerson@example.com"); // true
+ * ```
+ */
+declare function isSyntheticEmail(value: string): boolean;
+/**
+ * Whether an IP string is in an RFC 5737 (IPv4 TEST-NET) or RFC 3849 (IPv6 documentation) reserved
+ * block. A real routable address returns `false`.
+ *
+ * @param value - The candidate IPv4 or IPv6 address.
+ * @returns `true` when the address is a reserved documentation address.
+ * @example
+ * ```ts
+ * import { isSyntheticIp } from "@cosyte/synth";
+ * isSyntheticIp("192.0.2.44");  // true (TEST-NET-1)
+ * isSyntheticIp("8.8.8.8");     // false (real)
+ * ```
+ */
+declare function isSyntheticIp(value: string): boolean;
+
+/**
+ * The shipped **clearly-fake name pool** — `@cosyte/synth`'s own license-clean synthetic data.
+ *
+ * Deliberately **not** a `faker`-style realistic-name corpus (which could match a real person at a real
+ * address — the exact hazard the synthetic-safety invariant forbids). Every token is
+ * an obviously-invented, fixture-flavoured word: a reader can tell at a glance it names no one. The pool
+ * is small on purpose — structural coverage, not demographic realism, is the goal.
+ *
+ * `# synthetic: true`
+ *
+ * @module
+ */
+/** Obviously-synthetic given names. None is a plausible real person's name. */
+declare const SYNTHETIC_GIVEN_NAMES: readonly string[];
+/** Obviously-synthetic family names. None is a plausible real surname at a real address. */
+declare const SYNTHETIC_FAMILY_NAMES: readonly string[];
+/** Obviously-synthetic street names for structured address fields. */
+declare const SYNTHETIC_STREET_NAMES: readonly string[];
+/**
+ * Obviously-synthetic city names. Combined only ever with a synthetic street + a fake name (the
+ * *combination* is what identifies, and the combination is always synthetic).
+ */
+declare const SYNTHETIC_CITY_NAMES: readonly string[];
+
+/**
+ * The `safe` namespace — the single entry point for every synthetic-by-construction value provider.
+ *
+ * Grouped under one object so a consumer reads `safe.ssn(rng)` / `safe.phone(rng)` and it is
+ * self-evident that the value is drawn from a guaranteed-non-colliding synthetic source.
+ * The individual functions and the reserved-range predicates are also exported by name from the
+ * package root for direct import.
+ *
+ * @module
+ */
+
+/**
+ * The synthetic-safety provider namespace. Every function draws only from a reserved range or the
+ * shipped fake-name pool — no value it returns can be real or plausibly-real PHI.
+ *
+ * @example
+ * ```ts
+ * import { createRng, safe } from "@cosyte/synth";
+ * const rng = createRng(42);
+ * safe.ssn(rng);   // never-issued SSN
+ * safe.phone(rng); // reserved 555-01NN number
+ * ```
+ */
+declare const safe: Readonly<{
+    ssn: typeof ssn;
+    phone: typeof phone;
+    name: typeof name;
+    email: typeof email;
+    ipv4: typeof ipv4;
+    ipv6: typeof ipv6;
+    uuid: typeof uuid;
+    identifier: typeof identifier;
+    address: typeof address;
+    dateYmd: typeof dateYmd;
+    npi: typeof npi;
+    dea: typeof dea;
+}>;
+
+/**
+ * `splitmix32` — a tiny, well-studied 32-bit mixing PRNG used **only** to expand a single integer
+ * seed into the four 32-bit state words that seed {@link ../rng/sfc32.sfc32}. It is not the corpus
+ * generator itself (that is `sfc32`); it exists so that a one-number seed deterministically produces a
+ * well-distributed 128-bit `sfc32` state, avoiding the poor low-bit behavior of naive
+ * `state = seed`-style initialization.
+ *
+ * Zero-dependency, `Math.random`-free (lint-enforced): the whole point of the library is that a seed —
+ * and only the seed — determines the output, on any machine, any run.
+ *
+ * @module
+ */
+/**
+ * A stateful `splitmix32` step function. Each call advances the internal 32-bit state and returns the
+ * next unsigned 32-bit integer. Deterministic for a given seed.
+ *
+ * @param seed - The 32-bit seed. Coerced to a 32-bit integer via `| 0`.
+ * @returns A nullary function returning the next `uint32` in the stream.
+ * @example
+ * ```ts
+ * import { splitmix32 } from "@cosyte/synth";
+ * const next = splitmix32(12345);
+ * const a = next(); // deterministic uint32
+ * ```
+ */
+declare function splitmix32(seed: number): () => number;
+
+/**
+ * `sfc32` (Small Fast Counter, 32-bit, 128-bit state) — the deterministic, non-cryptographic PRNG that
+ * drives every value `@cosyte/synth` generates. Chosen over `mulberry32` (whose author flags that it
+ * skips ~1/3 of 32-bit outputs) and over a CSPRNG (`node:crypto`, which is **not seedable** and would
+ * defeat reproducibility). A synthetic-fixture generator has **no secrets** — statistical quality plus
+ * byte-for-byte reproducibility is exactly the right trade.
+ *
+ * The state is four 32-bit words. This module exposes the raw step function; {@link ../rng/rng.Rng}
+ * wraps it with a seed-expansion ({@link ./splitmix32.splitmix32}) and the ergonomic draw helpers.
+ *
+ * @module
+ */
+/**
+ * The mutable four-word `sfc32` state. Threaded explicitly (never global) by {@link ../rng/rng.Rng}.
+ */
+interface Sfc32State {
+    /** State word `a`. */
+    a: number;
+    /** State word `b`. */
+    b: number;
+    /** State word `c`. */
+    c: number;
+    /** Counter word `d`. */
+    d: number;
+}
+/**
+ * Advance an {@link Sfc32State} in place by one step and return the next unsigned 32-bit integer.
+ *
+ * This is the canonical `sfc32` step. The state object is mutated (the counter `d` increments and the
+ * mixing words rotate); callers that need reproducible independence hold their own state and never
+ * share it — {@link ../rng/rng.Rng} creates a fresh state per seed so two runs from the same seed are
+ * identical.
+ *
+ * @param s - The state to advance. Mutated in place.
+ * @returns The next `uint32` in the stream.
+ * @example
+ * ```ts
+ * import { sfc32Next, type Sfc32State } from "@cosyte/synth";
+ * const s: Sfc32State = { a: 1, b: 2, c: 3, d: 4 };
+ * const x = sfc32Next(s); // uint32
+ * ```
+ */
+declare function sfc32Next(s: Sfc32State): number;
+
+/**
+ * Stable diagnostic codes for `@cosyte/synth` and the {@link SynthError} they travel on.
+ *
+ * Unlike a parser (which recovers from bad *input* into Tier-2 warnings), a **generator** has no input
+ * to tolerate — its reflex is *synthetic-by-construction* and *fail-closed on impossibility*. So the
+ * codes here are **fatal**: a caller asked for something the library cannot honor spec-clean, and the
+ * only safe answer is to throw, never to silently fabricate a value or a byte workaround. Codes are `key ===
+ * value` and part of the public contract —
+ * renaming one is a breaking change.
+ *
+ * @module
+ */
+/**
+ * The stable **fatal** code registry. Additions-only thereafter.
+ *
+ * @example
+ * ```ts
+ * import { SYNTH_FATAL_CODES, SynthError } from "@cosyte/synth";
+ * try {
+ *   // ...generate...
+ * } catch (err) {
+ *   if (err instanceof SynthError && err.code === SYNTH_FATAL_CODES.SYNTH_UNSUPPORTED_FORMAT) {
+ *     // handle an unsupported format request
+ *   }
+ * }
+ * ```
+ */
+declare const SYNTH_FATAL_CODES: {
+    /**
+     * A format was requested that this build cannot generate through a real parser builder/serializer
+     * (e.g. ASTM before `@cosyte/astm`'s serializer ships). Fatal — never a hand-written byte fallback.
+     */
+    readonly SYNTH_UNSUPPORTED_FORMAT: "SYNTH_UNSUPPORTED_FORMAT";
+    /**
+     * A vendor quirk was requested that the target format's profile system does not support. Fatal —
+     * never a silent no-op and never a fabricated quirk.
+     */
+    readonly SYNTH_UNSUPPORTED_QUIRK: "SYNTH_UNSUPPORTED_QUIRK";
+};
+/**
+ * A value from {@link SYNTH_FATAL_CODES} — the type carried by a thrown {@link SynthError}.
+ */
+type SynthFatalCode = (typeof SYNTH_FATAL_CODES)[keyof typeof SYNTH_FATAL_CODES];
+/**
+ * The typed error every fatal `@cosyte/synth` condition throws. Carries a stable
+ * {@link SynthFatalCode} so callers branch on `err.code` without matching message text.
+ *
+ * @example
+ * ```ts
+ * import { SynthError, SYNTH_FATAL_CODES } from "@cosyte/synth";
+ * throw new SynthError(SYNTH_FATAL_CODES.SYNTH_UNSUPPORTED_FORMAT, "astm is not yet generable");
+ * ```
+ */
+declare class SynthError extends Error {
+    /** The stable fatal code. */
+    readonly code: SynthFatalCode;
+    /**
+     * @param code - The stable {@link SynthFatalCode}.
+     * @param message - A human-readable detail (never contains PHI — there is none).
+     */
+    constructor(code: SynthFatalCode, message: string);
+}
+
+/**
+ * `@cosyte/synth` — a deterministic, seedable **synthetic-data / test-fixture generator** for the
+ * cosyte healthcare formats. A *consumer* of the parsers, not a parser: it builds artifacts **through
+ * each parser's own builder/serializer** (so output is spec-clean by construction) and draws every
+ * value from a **guaranteed-non-colliding synthetic source** (so no output can be real or
+ * plausibly-real PHI). It is a **format/conformance generator, not a clinical simulator**.
+ *
+ * This root entry point exposes the **format-agnostic core**: the seeded PRNG, the synthetic-safety
+ * providers, the `Corpus` abstraction, the profile skeleton, and the fatal codes. Per-format
+ * generation lives behind its own subpath (`@cosyte/synth/hl7`) so importing the root never pulls a
+ * parser — the lazy per-format boundary.
+ *
+ * @module
+ */
+/**
+ * Library version string, synced with `package.json#version` by downstream release tooling.
+ *
+ * @example
+ * ```ts
+ * import { VERSION } from "@cosyte/synth";
+ * console.log(VERSION);
+ * ```
+ */
+declare const VERSION = "0.0.0";
+
+export { DEA_REGISTRANT_TYPES, DOC_V6_PREFIX, NPI_LUHN_PREFIX, RESERVED_EMAIL_DOMAINS, SYNTHETIC_ASSIGNING_AUTHORITY, SYNTHETIC_CITY_NAMES, SYNTHETIC_FAMILY_NAMES, SYNTHETIC_GIVEN_NAMES, SYNTHETIC_STREET_NAMES, SYNTH_FATAL_CODES, type Sfc32State, SynthError, type SynthFatalCode, TEST_NET_V4_PREFIXES, VERSION, address, dateYmd, dea, deaCheckDigit, email, identifier, ipv4, ipv6, isSyntheticDea, isSyntheticEmail, isSyntheticIp, isSyntheticNpi, isSyntheticPhone, isSyntheticSsn, luhnMod10, name, npi, npiCheckDigit, phone, safe, sfc32Next, splitmix32, ssn, uuid };