@cosyte/synth 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -460,6 +460,56 @@ its public history at `0.0.x`, per the cosyte version ladder (`0.0.x` until firs
 
 ### Changed
 
+- **Fatal messages come from a frozen registry, and `SynthError` takes no value parameter.** Every
+  message is a fixed entry in the newly exported `SYNTH_FATAL_MESSAGES` table, keyed by code, and the
+  constructor is `SynthError(code)`: there is no longer a position through which a caller-supplied
+  string can reach `message`, `stack`, or any field on the thrown object.
+
+  **The severity, stated honestly.** This is not a leak of patient data and describing it as one
+  would be its own dishonesty. `@cosyte/synth` generates synthetic fixtures, so the values a refusal
+  used to quote were quirk names, format labels, code-system URIs and money strings. What was wrong
+  was the _shape_: every fatal took a value parameter, and the only thing keeping PHI out of a
+  diagnostic was that callers happened to be passing harmless values. The audit of the thirteen
+  cosyte repos found that the single property separating the packages that leak from the ones that
+  are genuinely prevented is exactly this: whether the message factory takes a value parameter at
+  all. It now does not.
+
+  The prose mattered as much as the code here. The claim that warning messages are PHI-free by
+  construction spread through this ecosystem as a _sentence_, not as shared runtime code, and this
+  package had inherited the sentence and used it as a reason not to bound anything. Every surface
+  carrying it has been corrected in the same change rather than restated in fresher words:
+  `src/codes.ts` (whose `@param message` read "never contains PHI, there is none"),
+  `docs-content/troubleshooting.md`, `docs-content/concepts-archetype.md`,
+  `docs-content/limitations.md`, `docs-content/guides-quirks.md` and `README.md`.
+
+- **Every caller-supplied selector is resolved against its closed set, not trusted.** `resolveKind`
+  and `resolveMix` (new, exported, `src/select.ts`) sit at the entry point of every option that names
+  a member of a union: a message kind, an `ADT` trigger, a document type, a corpus mix entry, an `837`
+  variant, a Bundle type, a `Patient` profile, a quirk kind. An unrecognised one is a fatal
+  `SYNTH_UNSUPPORTED_KIND`.
+
+  **This is the same defect as the message one, not a separate tidy-up**, and it was found by the
+  refuter after the message fix had been called done. A selector union does not exist at run time, and
+  an unresolved selector did three things at once. It travelled into an optional peer builder, which is
+  entitled to quote it back in its own `TypeError` and does, so a caller-supplied string reached an
+  `err.message` and an `err.stack` through a `@cosyte/synth` entry point (`generateCcda`,
+  `generateCcdaQuirk`, `ccdaCorpus`, `ccdaQuirkCorpus`). It became an `Artifact.kind` and a
+  `manifest.counts` key, which is the structural-identifier position the whole model half of this work
+  is about (`x12Corpus({ mix })`). And it fell out of an exhaustive `switch` as `undefined`, which
+  neither reads as an error nor is one.
+
+- **`assertIntendedWarnings` loses its leading `quirk` parameter**, and is now
+  `assertIntendedWarnings(intendedWarnings, bareWarnings)`. It existed only to be interpolated into
+  the refusal. A parameter whose sole job is to reach a message is the shape being removed, so it was
+  deleted rather than left in place and ignored.
+
+- **`resolveQuirk` refuses a descriptor found under a different format's registry**, on the same
+  `SYNTH_UNSUPPORTED_QUIRK` code. The `format` argument used to be read only to build the message
+  text; it is now compared, never rendered.
+
+- **`defineSynthProfile` raises `SynthError` with `SYNTH_INVALID_PROFILE`** for a missing or blank
+  `name`, where it previously raised a `TypeError`.
+
 - Replaced the parser-archetype scaffold stubs (`parseSynth`, `WARNING_CODES`, `FATAL_CODES`) with the
   generator surface — `@cosyte/synth` is a synthetic-fixture **generator**, not a parser.
 - **Docs:** refreshed the `README.md` status block to describe the **feature-complete** generator surface
@@ -497,6 +547,234 @@ its public history at `0.0.x`, per the cosyte version ladder (`0.0.x` until firs
 
 ### Fixed
 
+- **A file that appeared and disappeared while the PHI gate was running made it refuse the whole
+  sweep.** A full scan lists every file under `src/`, `test/` and `scripts/` and then reads them one
+  by one. Anything created and deleted between those two steps was read after it was gone, and the
+  scanner stopped with an error rather than a verdict. That is reachable in this repository rather
+  than theoretical: the gate's own test suite writes short-lived files into two of the three
+  directories it scans, and sweeping the working tree while that suite ran stopped 8 of 165 sweeps.
+  A sibling package hit the same shape from its build tool and it blocked a release.
+
+  **The refusal was right; the file list was wrong, so the list is what changed.** Exactly one case
+  is now tolerated: a file the scan listed itself, that is not committed, and that is missing when
+  the scan reaches it. It is reported on stderr as skipped, never dropped in silence, and the
+  "files scanned" figure counts what was actually read, so a skip lowers it instead of padding it.
+
+  **Everything else still stops the scan.** A committed file that cannot be read, a read that fails
+  for any other reason (unreadable is not the same as absent), a skipped file that is back on disk
+  when the scan finishes, and a repository that cannot report what it tracks. A full scan that ends
+  up having read nothing at all is refused outright, so tolerating a missing file can never turn
+  into a clean report of a tree nothing was read from. Pre-commit scans read committed content
+  directly and never depended on any of this.
+
+  Each of those bounds is pinned by a test that reds when the bound is widened, verified by widening
+  each one in turn. **One is not pinned and is named here rather than implied:** the check that a
+  skipped file has not come back. Reaching it needs a timing-dependent test, which is the failure
+  this defect teaches, so it is left uncovered deliberately; losing it would cost that re-check, not
+  the tolerance's limits. **One residual is disclosed rather than closed:** the re-check matches on
+  the file's path, not its contents, so an uncommitted file _renamed_ mid-scan goes unread under a
+  clean report. Committing it makes it tracked and no longer tolerable, and pre-commit reads
+  committed content either way. Closing it in general needs a content-addressed scan; re-listing the
+  scanned directories afterwards would close the in-directory half more cheaply, at the cost of a
+  second walk and a new way to refuse. Both are a design trade for a later change rather than
+  something impossible.
+
+  **Two smaller limits are recorded rather than closed, and both fail in the refusing direction.**
+  When the repository cannot report what it tracks the scan still stops, but the message names the
+  file it could not read rather than that reason. And the tracked-file list is read through a 1 MiB
+  buffer, so a repository large enough to exceed it would quietly stop applying the tolerance —
+  measured here at 6,556 bytes, three orders of magnitude of headroom.
+
+- **The test suite could fail on a busy machine while the code under test was correct.** The
+  per-test timeout is a wall-clock budget, so it measures the machine as much as the code. These
+  suites are CPU-bound, in that their running time is set by how much processor they actually get
+  rather than by the work the code does, so the two heaviest C-CDA sweeps ran within about 2x of the 10 s limit
+  with a core to themselves, and crossed it when sharing one, reporting a failure that reproduced
+  nowhere else. A failure that means "the machine was busy" costs more than it saves, because the
+  next real one is read as noise too.
+
+  Two fixes, chosen so that a genuine hang still fails fast. The C-CDA quirk sweeps, the heaviest
+  cases in the package and the ones that build a document and parse it twice, now carry their own explicit
+  generous ceilings, matching the sibling C-CDA suites that already had them. And the PHI-gate suite,
+  which runs the scanner in a real subprocess ~65 times, now starts those subprocesses with `node`
+  rather than the on-the-fly TypeScript runner: measured on one box, 0.6 s against 2.1 s per start,
+  taking the file from ~145 s to ~75 s. Nothing about the scanner changed, and one test still runs it
+  the original way so the two invocations are held to the same verdict.
+
+  **The global timeout is deliberately unchanged.** Raising it would have been the shorter fix and
+  would have traded a false failure for a false pass, letting a genuinely stuck test sit for a minute
+  before anyone heard about it.
+
+- **Three of the PHI gate's seven structured detectors decided what to inspect from the file's NAME,
+  so byte-identical content was refused as `probe.xml` and passed as `probe.ts`.** `scanCcda` and
+  `scanNcpdpScript` returned early unless the path ended `.xml`; `scanFhir` unless it ended `.json`.
+  That mattered in this repo specifically, because it builds documents as inline string literals in
+  TypeScript tests — the scan enumerated those files and then structurally read nothing in them.
+
+  **Every arm now keys off the bytes.** Each of the three admits a target by its extension **or** what
+  the bytes say — a CDA root/namespace, a SCRIPT `<Message>` envelope, FHIR's `resourceType` for its
+  textual route. **Admission is additive**: no target admitted before is refused admission now.
+  Extensions are matched case-insensitively, so `.XML` is an XML file too. `scanFhir` gained a second
+  route for the hard half: a resource in a TypeScript object literal is not valid JSON, so a `.json`
+  gate plus `JSON.parse` could never have reached it however the extension check was widened. Its
+  **structural** route is not marker-gated — it runs whenever `JSON.parse` succeeds, with no
+  `resourceType` check, exactly as it did for `.json` before.
+
+  **The marker is the false-positive defence for the CONTENT routes**, which is narrower than "nothing
+  is examined without a marker" — an `.xml` path still reaches the C-CDA arm with no marker at all, and
+  FHIR's structural route still reads any parseable JSON. A gate that flagged every `family:` in every
+  source file would be turned off, which is worse than the gap it closes.
+
+  **NOTHING SUBTRACTS. No detector was taught to skip anything**, and getting to that took three
+  review passes. Widening the arms made this scanner's own test suite one of its targets, and that
+  suite necessarily writes name elements. The first three attempts answered it by teaching the
+  **scanner** to skip template placeholders — and on a PHI detector a skip rule has to be exactly
+  right, which it twice was not. It silenced `Anderson ...` (a containment test), then `${"Anderson"}`
+  (any interpolation body elided, left open on a claim that closing it would break an existing idiom
+  when `git show main` shows the same branch had just introduced that idiom), then `{{Anderson ${s}}`
+  (one regex pass matching straight across two constructs the source never nested). Each remedy bought
+  one more evasion shape, which is the signature of a rule that does not belong in a PHI gate.
+
+  The rule is **gone**. The suite assembles its fixture elements at run time instead, so the detector
+  stays maximally literal and there is no subtraction to audit. Measured across sixteen shapes —
+  including every one a refuter used to break the earlier drafts — `main` and this branch return the
+  **identical** verdict; the only differences anywhere are files the widened arms now reach that
+  `main` never read.
+
+  **The measurement that justified the deleted predicate is corrected here too**, because the wrong
+  version had been written down as the evidence: the first run over 170 files returned four hits across
+  two files — **two real names** the widening had just made visible (now declared in the allow-list) and
+  two name elements in this scanner's own fixtures. Not "four placeholders, none a name".
+
+  Two things the change surfaced, both fixed here. The C-CDA name/telecom sweep was always
+  **document-wide** but labelled every hit `recordTarget/…`; a name in `<author>` came back labelled
+  with a location it was not in. The sweep is kept (an informant's name in a committed fixture is as
+  real as a patient's) and only the false claim about _where_ is withdrawn. And two hand-written
+  tokens in a de-identifier test became visible for the first time; they are **declared in the
+  allow-list**, with what that costs written next to them, rather than edited out of a test whose
+  point requires exactly those shapes.
+
+  The characterization test that pinned the old behaviour asserted the **opposite** of what is true
+  now. It was rewritten in place, not deleted — the same probe bytes, the same two paths, the opposite
+  expectation — alongside new pins for the limits this did **not** close: admission is file-scoped
+  rather than object-scoped, the C-CDA name loci remain
+  namespace-prefix-naive, and the textual FHIR route misses a phone whose `system` and `value` are
+  separated by another key (the structural route catches it — the two are not at parity, and the
+  routes are mutually exclusive).
+
+- **The two scan modes disagreed about a git-ignored file and neither direction was tested.** All-mode
+  drops git-ignored files; `--staged` does not. Both directions are now exercised. **Neither is
+  changed**: all-mode walks the working tree, where an ignored path is build output; `--staged`
+  enumerates the index, which a file reaches only via `git add -f` and which a commit will therefore
+  carry. Refusing to read that one is the shipping direction.
+
+- **The PHI commit gate could be argued into scanning nothing and still print `OK`.**
+  `scripts/phi-scan.ts` treated an `--allow-fixture <path>` as both a subtraction _and_ a scan
+  target, so `pnpm phi-scan --allow-fixture X` with no other argument built the target set `[X]`,
+  subtracted `X`, scanned zero files and exited 0 with the same `OK — no hits` line a real pass
+  prints. `--allow-fixture` is now purely subtractive and never seeds the target set; the mode is
+  decided by `--staged` and positional paths alone. Three invariants (`enforceObservation`) are
+  checked before any hit counting: an override that subtracts no enumerated target is an error
+  rather than an inert entry that reads as a live bypass, a target set emptied by overrides is
+  refused, and an enumeration that finds nothing is refused in every mode but `--staged` (where
+  "nothing staged" is legitimate). Both **summary** lines now carry the **denominator** — the count
+  of files scanned — so an `OK` is never read without the number it is an `OK` over. Ported from the
+  same defect closed in `ncpdp`.
+
+- **The staged enumerator dropped whole classes of staged file, because its filter was the wrong
+  polarity.** `git diff --cached --diff-filter=AM` is an **allow-list of git status letters**: every
+  letter it does not name is skipped by default and silently. That is how it missed `R` — a fixture
+  `git mv`'d and edited to add PHI in one commit stages as a single rename entry — and `T`, a
+  tracked symlink replaced by a regular file carrying PHI. Each was found by a separate refuter pass
+  in `ncpdp`, which is the argument for the general fix rather than the two patches: the enumerator
+  now asks for `--diff-filter=d` (everything **except** deletions, which have no blob to read), so an
+  unknown or future status letter costs a wasted scan instead of a missed file. It also passes
+  `--no-renames`, which decomposes a rename into `D` + `A` so the **destination** path — the one
+  carrying the new content — is the path that gets read. Both directions are measured in the suite:
+  the tests assert the new flags catch the `R` and `T` cases **and** that the superseded `AM`
+  allow-list did not list the violator's path for either. That second assertion is also what keeps
+  the first honest — had git degraded the fixture to a plain `A`/`M`, `AM` would have listed it and
+  the test would red rather than pass for the wrong reason.
+
+- **The scan stopped at `test/fixtures/`, leaving most of the repository unswept.** `SCAN_ROOTS` is
+  now `src/`, `test/` and `scripts/`, walked whole and shared by both all-mode and `--staged` through
+  a single `isScannable` predicate, so the **roots** narrow in one place. The gap mattered here
+  specifically: this repo builds messages as inline string literals in tests **outside** `fixtures/`,
+  and `scripts/` is hand-written tracked text that can carry a real address as easily as a fixture
+  can. Measured on the widening: **114 in-scope files became 170**. Markdown stays out of scope in
+  every mode, because documentation — including this scanner's own override log and allow-list —
+  legitimately quotes violator values.
+
+  **What the widening does NOT buy, stated because the obvious reading is wrong.** Over a `.ts` file
+  it delivers the format-agnostic floor and the content-gated arms (HL7 v2, X12, ASTM, NCPDP
+  Telecom), which sniff their own framing. It delivers nothing from the three **extension-gated**
+  arms: `scanCcda` and `scanNcpdpScript` return early unless the path ends `.xml`, and `scanFhir`
+  unless it ends `.json`. A byte-identical payload is caught as `probe.xml` and missed as `probe.ts`.
+  That gating predates this change and is deliberately left alone — content-sniffing XML and JSON out
+  of arbitrary TypeScript is a much larger job with its own false-positive surface, and doing it as a
+  side effect of a root change would grow the gate's teeth without review. It is recorded as a known
+  gap in the scanner's header rather than implied away, and the roots list no longer claims otherwise.
+
+  **SUPERSEDED — see "Three of the PHI gate's seven structured detectors…" under Fixed below.** The
+  paragraph above described the state of the gate when the roots were widened, and is kept as that
+  record. The three extension gates were subsequently removed as the separate job this paragraph said
+  they needed, so its present tense no longer holds.
+
+- **The widened scan surfaced one real finding, and it is declared rather than suppressed.** The ten
+  vendored US Core 6.1.0 StructureDefinitions under `test/us-core-profiles/` each carry their
+  publisher's work-group contact address in `contact.telecom`. It is a real address, so it is a real
+  hit; it is not PHI, because it denotes a standards-body mailing list rather than a person receiving
+  care. It is cleared with a new, narrower allow-list tag — `EMAIL <address>`, one exact address —
+  rather than an `EMAILDOMAIN` entry that would clear every address at a live organizational domain,
+  and rather than an `--allow-fixture` bypass that would silence every other check on those ten files.
+
+- **A missing allow-list exited 1, which reads as "hits found".** `loadAllowList` now runs inside the
+  invocation-error boundary, so an absent `scripts/phi-allow-list.txt` exits **2** like every other
+  invocation error.
+
+- **The override log was parsed file-wide, so its own format template was a bypass.**
+  `phi-scan-overrides.md` documents itself with a literal `### <path>` heading above the entries
+  section; only `### <path>` subsections **under `## Entries`** are read as approvals now.
+
+- **A false assertion in the scanner's test suite, deleted rather than reworded.** Its docblock said
+  the suite "deliberately does NOT test structured, field-level PHI detection". That was untrue when
+  written and stayed untrue for six formats — the HL7, FHIR, X12, NCPDP, ASTM and quirk suites had
+  been exercising exactly that. The dangerous half of a wrong assertion is not the code around it but
+  the next reader trusting it, so the sentence is gone. Two more went with it: the `STARTER` banner —
+  carried in `scripts/phi-scan.ts`, `phi-scan-overrides.md` and `.github/workflows/ci.yml`, all three
+  still describing a scanner that detects "SSN and email only" after every structured arm had landed —
+  and a claim in `docs-content/limitations.md` that this project's own fixtures carry a
+  `# synthetic: true` header. **No fixture does**; two shipped value-pool sources do.
+
+- **A corpus could report a transaction it did not contain.** `x12Corpus({ seed: 9, mix: ["270"] })`
+  returned a corpus whose manifest said `{"270": 1}` and whose bytes were an `837` professional claim,
+  byte-identical to `mix: ["837P"]` at the same seed, because the kind dispatcher ended in an
+  unguarded fallback. Every corpus dispatcher is now an exhaustive `switch` behind a resolved
+  selector, so an unrecognised kind is a fatal `SYNTH_UNSUPPORTED_KIND` and can no longer be silently
+  relabelled. A golden file that lies about what it holds is the failure the intended-warning contract
+  exists to prevent, in the one format that had no equivalent check.
+
+- **Five exhaustive `switch`es over run-time-erased unions returned `undefined` typed as a value.**
+  `generateHl7`, `generateHl7Quirk`'s base-message dispatcher, `fhirCorpus`, `ncpdpCorpus` and
+  `astmCorpus` each took no branch for a kind outside its union and handed the result on, surfacing
+  later as a `TypeError` from the runtime with no code to branch on. All five are now guarded by a
+  resolved selector.
+
+  **Three more of the same shape are known and deliberately left**, in `src/deid/`:
+  `x12DeidLoop({ variant })` and `ncpdpTelecomDeidLoop({ transaction })` fall through to an uncoded
+  `TypeError`, and `ccdaDeidLoop({ documentType })` silently generates a Referral Note for anything but
+  `"ccd"`. None echoes a caller value into a message, so none is a diagnostic leak. They are named here
+  rather than swept in, because two review passes had each found one more position after this change
+  described its own coverage as general, and widening the change a third time is the wrong response to
+  that.
+
+- **`injectCcdaQuirk` returned `undefined` for an unrecognised quirk name, as though it were a
+  document.** `CcdaQuirkName` is a union that does not exist at run time, so a JavaScript caller (or
+  a cast) reaching the function with any other string fell out of the transform's switch with no
+  branch taken and no error. The name is now resolved against `CCDA_QUIRKS` first and an unknown one
+  is a fatal `SYNTH_UNSUPPORTED_QUIRK`. Found by the diagnostic-surface slot table below, which
+  recorded it as the one slot that produced neither a value nor a diagnostic.
+
 - **`README.md` said the package was not published to npm. It is.** The summary blockquote opened
   with "pre-alpha (`0.0.x`), not yet published to npm", so the npm package page asserted that the
   package did not exist on npm, directly under the version npm renders in its own header. A reader
@@ -541,4 +819,61 @@ its public history at `0.0.x`, per the cosyte version ladder (`0.0.x` until firs
 
 ### Security
 
+- **A per-slot diagnostic-surface gate, run red before it was run green.**
+  `test/phi/diagnostic-surface.test.ts` drives `assertNoDiagnosticPhiLeak` from `@cosyte/test-utils`
+  over a table of **44** consumer-controlled positions: the quirk name, format label and registry key
+  on `resolveQuirk`; the quirk selector on all three `generate*Quirk`, all three `*QuirkRoundTrip` and
+  all three `*QuirkCorpus` entry points, by explicit list and through a `defineSynthProfile` profile;
+  both code lists on `assertIntendedWarnings`; both parameters of `injectCcdaQuirk`; the code-system
+  URI on `toBuildCode`; the money string on `dec`; **eighteen selector positions** across the six
+  formats (message kind, `ADT` trigger, document type, corpus mix, `837` variant, Bundle type,
+  `Patient` profile, quirk kind); and the artifact `content` each quirk round-trip harness hands to a
+  sibling parser. Each slot plants an eight-byte marker and a 32 KiB one, names the code it must
+  reach, and fails if any four-byte run of the marker turns up in a thrown value, a `message`, a
+  `stack`, or a structural identifier on a returned model.
+
+  **Measured against the unfixed source first, because a suite never seen red is indistinguishable
+  from one that cannot go red.** Of the 44 slots, **3 were clean and 41 failed**. The failure
+  categories **overlap** — a slot can both echo the marker and throw an uncoded error, and 6 do — so
+  they are counted per slot per category and do not sum to 41: **20** echoed the planted value
+  verbatim into an error message or stack, **4** put it on a model identifier, **16** threw an error
+  carrying no code to branch on, and **7** accepted it with neither an error nor a usable value. The
+  method: check out the base tree's `src/`, add the new codes and the frozen table as a purely
+  additive patch with an _optional_ message parameter so no base call site changes, then invoke each
+  slot's plant directly with both probe sizes.
+
+  **The model half of that sweep is vacuous, and the file says so rather than letting a reader infer
+  coverage.** Every slot throws, because every position fails closed before a model exists, so
+  `getModelIdentifiers` is never reached during the sweep. That is the result of the fix, not a gap in
+  the table, and it is carried instead by a separate assertion that runs the three identifier helpers
+  over real corpora and real quirk round-trips and checks that every identifier they yield comes from
+  a set this package controls. Between them: the slots prove no caller value survives to a model, and
+  the closed-set test proves the identifiers that exist were derived rather than passed through.
+
+  It also asserts the structural half: no `throw new` under `src/` names anything but `SynthError`,
+  and no construction of one carries an interpolation. The scanner is positive-controlled against a
+  constructed string containing the thing it hunts, not against a file that happens to be nearby, and
+  **its title says what a regex can see while its docblock says what it cannot** — it cannot see a
+  `TypeError` the runtime raises on its own, which is exactly the route the selector chokepoint
+  closes.
+
+  What the gate does not prove is in the runner's own documentation and is not restated more
+  favourably here: it does not catch a re-encoded echo, an echo under four bytes, a leak carried only
+  as a number, or a leak through a position nobody declared. The slot table is the deliverable. It was
+  derived by enumerating the exported types with the TypeScript checker rather than by sweeping the
+  source from memory. **Even so it was refuted twice, on the same class both times.** The first
+  version covered only `throw` sites and missed eighteen selector positions. The second called the
+  selectors "generalised, not patched" and missed the tail of a quirk list a `count` never reaches,
+  which lands on `manifest.quirks` unresolved. Enumerating the types was necessary and not sufficient:
+  both misses were judgements about which positions "reach a diagnostic", made before it was
+  established that an unresolved selector reaches a peer builder's diagnostic and a derived manifest
+  key.
+
+  **So the table is no longer described as exhaustive, on any surface.** A third claim of completeness
+  would be worth exactly what the first two were. What holds generally is the mechanism — the error
+  type has no value parameter, and a selector is read in one place — and the table is an enumeration
+  of the positions that have been checked. That wording is now in the test file's own header, in
+  `docs-content/limitations.md` and in `CLAUDE.md`, so the next person to add a position adds a slot
+  rather than trusting a count.
+
 [Unreleased]: https://github.com/cosyte/synth/commits/main

package/README.md

@@ -255,8 +255,12 @@ astmQuirkRoundTrip(generateAstmQuirk({ seed: 1, quirk: "unknown-escape" })).inte
 ```
 
 A quirk a format's profile system does not support fails closed with a stable `SYNTH_UNSUPPORTED_QUIRK`
-diagnostic — never a silently-wrong fixture. Every quirk is grounded in a **publicly-documented**
-deviation or a parser's **public** profile, never a private vendor corpus.
+diagnostic — never a silently-wrong fixture — and so do the other selectors: a message kind, a
+document type, a corpus mix entry, an `837` variant, a Bundle type. Each is checked against its own set
+before anything is generated, so an unrecognised one is a fatal `SYNTH_UNSUPPORTED_KIND` rather than a
+mislabelled corpus. Every refusal carries a code and a fixed message from a frozen table, and quotes
+nothing you passed. Every quirk is grounded in a **publicly-documented** deviation or a parser's
+**public** profile, never a private vendor corpus.
 
 **Deferred:** quirk recipes for **FHIR, X12, and NCPDP**, and any quirk that would need a **private,
 vendor-attributed corpus** to ground.

package/dist/astm/index.cjs

@@ -31,6 +31,63 @@ function sfc32Next(s) {
   return t >>> 0;
 }
 
+// src/codes.ts
+var SYNTH_FATAL_CODES = {
+  /**
+   * 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.
+   */
+  SYNTH_UNSUPPORTED_QUIRK: "SYNTH_UNSUPPORTED_QUIRK",
+  /**
+   * A quirk transform found no structural anchor to mutate, so the fixture would not carry the
+   * deviation it is labelled with. Fatal — a golden file that lies about its parser verdict is worse
+   * than no golden file.
+   */
+  SYNTH_QUIRK_ANCHOR_ABSENT: "SYNTH_QUIRK_ANCHOR_ABSENT",
+  /**
+   * A bare parse of a freshly-generated quirk artifact did not produce exactly the declared intended
+   * warning code(s). Fatal — never emit a mislabeled fixture.
+   */
+  SYNTH_INTENDED_WARNING_MISMATCH: "SYNTH_INTENDED_WARNING_MISMATCH",
+  /** An integer range was requested with its maximum below its minimum. Fatal. */
+  SYNTH_INVALID_RANGE: "SYNTH_INVALID_RANGE",
+  /** A value was drawn from an empty pool. Fatal — never a fabricated substitute. */
+  SYNTH_EMPTY_POOL: "SYNTH_EMPTY_POOL",
+  /** A `defineSynthProfile` spec was not usable (a missing or blank `name`). Fatal. */
+  SYNTH_INVALID_PROFILE: "SYNTH_INVALID_PROFILE",
+  /**
+   * A caller-supplied selector (a message kind, a document type, a corpus mix entry, a claim
+   * variant, a Bundle type, a resource profile) is not in the closed set that governs it. Fatal —
+   * see `resolveKind`: a selector union is erased at run time, and a selector that falls through
+   * either mislabels the fixture or hands the value to a peer builder that quotes it back.
+   */
+  SYNTH_UNSUPPORTED_KIND: "SYNTH_UNSUPPORTED_KIND"
+};
+var SYNTH_FATAL_MESSAGES = Object.freeze({
+  SYNTH_UNSUPPORTED_FORMAT: "The requested format is not generable by this build. A generator has no byte fallback: it builds through a parser's own serializer or it refuses.",
+  SYNTH_UNSUPPORTED_QUIRK: "The requested vendor quirk is not in the target format's quirk registry. Compare the request against that format's exported registry (HL7_QUIRKS, CCDA_QUIRKS, ASTM_QUIRKS).",
+  SYNTH_QUIRK_ANCHOR_ABSENT: "The quirk transform found no structural anchor to mutate, so the fixture would not carry the deviation it is labelled with. Refusing to emit a mislabeled fixture.",
+  SYNTH_INTENDED_WARNING_MISMATCH: "A bare parse of the generated quirk artifact did not produce exactly the declared intended warning code(s). Refusing to emit a mislabeled fixture.",
+  SYNTH_UNMAPPED_CODE_SYSTEM: "The concept's code-system URI has no OID mapping in the C-CDA example-code table.",
+  SYNTH_INVALID_DECIMAL: "The value could not be read as an X12 decimal.",
+  SYNTH_INVALID_RANGE: "An integer range was requested with its maximum below its minimum.",
+  SYNTH_EMPTY_POOL: "A value was drawn from an empty pool.",
+  SYNTH_INVALID_PROFILE: "defineSynthProfile requires a non-empty string name.",
+  SYNTH_UNSUPPORTED_KIND: "The requested kind, document type, corpus mix entry, variant or profile is not one this generator supports. The supported set is the exported union for that option."
+});
+var SynthError = class extends Error {
+  /** The stable fatal code. */
+  code;
+  /**
+   * @param code - The stable {@link SynthFatalCode}. The message comes from the frozen registry.
+   */
+  constructor(code) {
+    super(SYNTH_FATAL_MESSAGES[code]);
+    this.name = "SynthError";
+    this.code = code;
+  }
+};
+
 // src/rng/rng.ts
 var Sfc32Rng = class {
   seed;
@@ -48,7 +105,7 @@ var Sfc32Rng = class {
     return this.nextUint32() / 4294967296;
   }
   int(min, max) {
-    if (max < min) throw new RangeError(`Rng.int: max (${String(max)}) < min (${String(min)})`);
+    if (max < min) throw new SynthError(SYNTH_FATAL_CODES.SYNTH_INVALID_RANGE);
     const span = max - min + 1;
     return min + Math.floor(this.float() * span);
   }
@@ -56,7 +113,7 @@ var Sfc32Rng = class {
     return this.float() < p;
   }
   pick(items) {
-    if (items.length === 0) throw new RangeError("Rng.pick: empty array");
+    if (items.length === 0) throw new SynthError(SYNTH_FATAL_CODES.SYNTH_EMPTY_POOL);
     return items[this.int(0, items.length - 1)];
   }
   digits(n) {
@@ -584,10 +641,21 @@ function latin1(bytes) {
   return out;
 }
 
+// src/select.ts
+function resolveKind(allowed, requested) {
+  const match = allowed.find((value) => value === requested);
+  if (match === void 0) throw new SynthError(SYNTH_FATAL_CODES.SYNTH_UNSUPPORTED_KIND);
+  return match;
+}
+function resolveMix(allowed, requested, fallback) {
+  if (requested === void 0) return fallback;
+  return requested.map((entry) => resolveKind(allowed, entry));
+}
+
 // src/profile.ts
 function defineSynthProfile(spec) {
   if (typeof spec.name !== "string" || spec.name.trim().length === 0) {
-    throw new TypeError("defineSynthProfile: `name` is required and must be a non-empty string.");
+    throw new SynthError(SYNTH_FATAL_CODES.SYNTH_INVALID_PROFILE);
   }
   return Object.freeze({
     name: spec.name,
@@ -597,28 +665,6 @@ function defineSynthProfile(spec) {
   });
 }
 
-// src/codes.ts
-var SYNTH_FATAL_CODES = {
-  /**
-   * 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.
-   */
-  SYNTH_UNSUPPORTED_QUIRK: "SYNTH_UNSUPPORTED_QUIRK"
-};
-var SynthError = class extends Error {
-  /** The stable fatal code. */
-  code;
-  /**
-   * @param code - The stable {@link SynthFatalCode}.
-   * @param message - A human-readable detail (never contains PHI — there is none).
-   */
-  constructor(code, message) {
-    super(message);
-    this.name = "SynthError";
-    this.code = code;
-  }
-};
-
 // src/quirk.ts
 var PROFILE_QUIRK_APPLIED = "PROFILE_QUIRK_APPLIED";
 function sameCodeSet(a, b) {
@@ -635,12 +681,8 @@ function sameCodeSet(a, b) {
 }
 function resolveQuirk(registry, format, name2) {
   const descriptor = registry[name2];
-  if (descriptor === void 0) {
-    const supported = Object.keys(registry).sort().join(", ");
-    throw new SynthError(
-      SYNTH_FATAL_CODES.SYNTH_UNSUPPORTED_QUIRK,
-      `${format}: unsupported quirk "${name2}". The ${format} profile system supports: ${supported}.`
-    );
+  if (descriptor === void 0 || descriptor.format !== format) {
+    throw new SynthError(SYNTH_FATAL_CODES.SYNTH_UNSUPPORTED_QUIRK);
   }
   return descriptor;
 }
@@ -655,11 +697,9 @@ function profileTolerated(disposition, intendedWarnings, warningsUnderProfile) {
       return false;
   }
 }
-function assertIntendedWarnings(quirk, intendedWarnings, bareWarnings) {
+function assertIntendedWarnings(intendedWarnings, bareWarnings) {
   if (!sameCodeSet(bareWarnings, intendedWarnings)) {
-    throw new Error(
-      `quirk "${quirk}": the intended-warning contract does not hold \u2014 expected exactly [${intendedWarnings.join(", ")}] but a bare parse produced [${bareWarnings.join(", ")}]. Refusing to emit a mislabeled fixture.`
-    );
+    throw new SynthError(SYNTH_FATAL_CODES.SYNTH_INTENDED_WARNING_MISMATCH);
   }
 }
 function validateProfileQuirks(profile, registry, format) {
@@ -668,6 +708,7 @@ function validateProfileQuirks(profile, registry, format) {
 }
 
 // src/astm/quirk.ts
+var ALL_QUIRK_KINDS = Object.freeze(["Result"]);
 var ASTM_QUIRKS = Object.freeze({
   "unknown-escape": Object.freeze({
     name: "unknown-escape",
@@ -721,17 +762,14 @@ function applyQuirk(quirk, records) {
 }
 function generateAstmQuirk(options) {
   const seed = options.seed ?? 0;
-  const kind = "Result";
+  const kind = resolveKind(ALL_QUIRK_KINDS, options.kind ?? "Result");
   const descriptor = resolveQuirk(ASTM_QUIRKS, "astm", options.quirk);
   const clean = generateAstmResult({ seed });
   const content = applyQuirk(options.quirk, clean);
   if (content === clean) {
-    throw new Error(
-      `generateAstmQuirk: quirk "${options.quirk}" found no structural anchor in a ${kind} report at seed ${seed} \u2014 refusing to emit a fixture that does not carry the intended deviation.`
-    );
+    throw new SynthError(SYNTH_FATAL_CODES.SYNTH_QUIRK_ANCHOR_ABSENT);
   }
   assertIntendedWarnings(
-    descriptor.name,
     descriptor.intendedWarnings,
     astm.parseAstmRecords(content).warnings.map((w) => String(w.code))
   );
@@ -777,6 +815,7 @@ var ALL_ASTM_QUIRKS = Object.freeze(
 function astmQuirkCorpus(options) {
   const quirks = options.profile ? validateProfileQuirks(options.profile, ASTM_QUIRKS, "astm") : options.quirks ?? ALL_ASTM_QUIRKS;
   const names = quirks.length > 0 ? quirks : ALL_ASTM_QUIRKS;
+  for (const name2 of names) resolveQuirk(ASTM_QUIRKS, "astm", name2);
   const count = options.count ?? names.length;
   const seedStream = createRng(options.seed);
   const artifacts = Array.from({ length: count }, (_unused, i) => {
@@ -798,7 +837,8 @@ var astmQuirkProfile = defineSynthProfile({
 });
 
 // src/astm/index.ts
-var DEFAULT_MIX = Object.freeze(["Result", "Order"]);
+var ALL_KINDS = Object.freeze(["Result", "Order"]);
+var DEFAULT_MIX = ALL_KINDS;
 function generateKind(kind, seed) {
   switch (kind) {
     case "Result":
@@ -808,7 +848,8 @@ function generateKind(kind, seed) {
   }
 }
 function astmCorpus(options) {
-  const { seed, mix = DEFAULT_MIX } = options;
+  const { seed } = options;
+  const mix = resolveMix(ALL_KINDS, options.mix, DEFAULT_MIX);
   const count = options.count ?? mix.length;
   const seedStream = createRng(seed);
   const artifacts = Array.from({ length: count }, (_unused, i) => {