Skip to content

docs: say what the round trip checks - #70

Merged
NSchatz merged 1 commit into
mainfrom
docs/round-trip-wording
Oct 7, 2026
Merged

NSchatz merged 1 commit into
mainfrom
docs/round-trip-wording

Conversation

@NSchatz

@NSchatz NSchatz commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Where the README and docs-content called every artifact "spec-clean by construction", they now say what the round-trip harness checks: each artifact is built through its parser's own builder or serializer and re-parses through that parser with zero warnings, byte-stable. The HL7 v2, FHIR R4 and C-CDA sections, and the 837P and NewRx guide headings, keep their wording. The specClean property and every code comment that prints exactly what the API returns are unchanged.

Checked on the published @cosyte/synth 0.1.0 (with the six 0.1.x parsers) from a clean install outside any repository: over seeds 1 to 25, roundTrip / scriptRoundTrip / telecomRoundTrip / astmRoundTrip / astmFramedRoundTrip on the HL7 ADT, FHIR Patient, CCD, 837P, 835, 271, NewRx, B1 and ASTM result (plain and framed) report zero warnings and are byte-stable.

File Before After
README.md (tagline) spec-clean by construction, and never real PHI built through each parser's own builder, and never real PHI
README.md (so the output is spec-clean by the same mechanism the parser proves) (so each artifact re-parses through that parser with zero warnings)
README.md (status) spec-clean generation across all six formats generation across all six formats
README.md (headings) Generate a spec-clean X12 transaction / NCPDP message / ASTM message Generate an X12 transaction / an NCPDP message / an ASTM message
README.md (X12, NCPDP, ASTM corpus lines) // true, all spec-clean // true
README.md (deid loop) it generates a spec-clean artifact it generates an artifact
README.md (design) Spec-clean by the parser's own judgment, ... a spec-clean artifact re-parses with zero warnings. Checked by the parser's own judgment, ... each artifact re-parses with zero warnings.
docs-content/intro.md (spec-clean HL7 v2, FHIR R4 / US Core, ...); (so the output is spec-clean by construction) (HL7 v2, FHIR R4 / US Core, ...); (so each artifact re-parses through that parser with zero warnings)
docs-content/concepts-archetype.md ## Spec-clean, by the parser's own judgment / an artifact is spec-clean by the exact mechanism ...; a request it cannot honor spec-clean ## Checked by the parser's own judgment / an artifact is checkable by feeding it straight back into that parser; a request it cannot honor
docs-content/troubleshooting.md cannot produce spec-clean throws cannot produce throws
docs-content/guides-overview.md the spec-clean generation core; proves spec-cleanliness ... a spec-clean artifact re-parses the generation core; checks an artifact ... it re-parses
docs-content/guides-x12.md, guides-ncpdp.md, guides-astm.md is spec-clean by construction and round-trips ...; proves spec-cleanliness ... a spec-clean interchange / message re-parses round-trips ...; checks an interchange / a message ... it re-parses
docs-content/guides-astm.md (heading) A result report, spec-clean by construction A result report
docs-content/guides-deid.md a spec-clean synthetic artifact; the byte-identical spec-clean artifact a synthetic artifact; the byte-identical artifact
docs-content/guides-quirks.md an otherwise spec-clean message a message that otherwise re-parses with zero warnings
docs-content/limitations.md deterministic, seedable, spec-clean (and, in quirk mode, deliberately off-spec) synthetic fixtures; Spec-clean by construction. ... so it is spec-clean by the same mechanism ...; The spec-clean generation core deterministic, seedable synthetic fixtures (and, in quirk mode, deliberately off-spec ones); Built through the parser. ... and it is checked by feeding the output straight back ...; The generation core
examples/generate-every-format.ts (docblock) Generate one spec-clean artifact in each of the other five formats Generate one artifact in each of the other five formats

No runnable block changes (the README HL7 block that docs-content.test.ts compares with the quickstart is untouched), and the floors section floor-citations.test.ts reads is untouched. No link targets the renamed headings. prettier --check passes on README.md and the example. The package.json description changes only with a release.

https://claude.ai/code/session_011dC8vE9axM3hqC8rNEX3W9

Where the README and docs-content called every artifact "spec-clean by
construction", they now say what the round-trip harness checks: each
artifact is built through its parser's own builder or serializer and
re-parses through that parser with zero warnings. The HL7 v2, FHIR and
C-CDA sections, and the 837P and NewRx guide headings, are unchanged.

- README: tagline, overview, status, the X12, NCPDP and ASTM headings
  and corpus comments, the deid loop, and the design list.
- intro, concepts, troubleshooting, guides overview, the X12, NCPDP,
  ASTM, deid and quirk guides, limitations, and the
  generate-every-format example docblock.

Checked on the published 0.1.0 from a clean install: over seeds 1 to
25, the HL7 ADT, FHIR Patient, CCD, 837P, 835, 271, NewRx, B1 and ASTM
result (plain and framed) round trips report zero warnings and are
byte-stable.

Claude-Session: https://claude.ai/code/session_011dC8vE9axM3hqC8rNEX3W9
@NSchatz
NSchatz merged commit e2907ee into main Oct 7, 2026
20 checks passed
@NSchatz
NSchatz deleted the docs/round-trip-wording branch October 7, 2026 22:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant