All notable changes to this project will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
- Added gRPC enhanced ACK parity for commit ACK codes
CA,CE, andCRalongside the existingAA,AE, andARapplication ACK codes. - Added shared dirty real-world corpus fixture categories and CLI parity coverage for corpus summary, fingerprint, and diff.
- Added REST and gRPC server dirty-corpus parity coverage using the shared dirty real-world fixture categories.
- Added REST profile lint, explain, and inline fixture-test endpoints that emit the shared profile evidence report shapes with opt-in v2 provenance.
- Added local Python wheel dirty-corpus parity coverage using the shared dirty real-world fixture categories.
- Added
xtask check-dirty-corpus-parityto run the shared dirty-corpus acceptance proof across Rust core, CLI, REST, and gRPC surfaces. - Added a CLI dirty real-world validate/redact/bundle/replay workflow to the shared dirty-corpus parity runner.
- Added a REST dirty real-world validate-redacted/bundle/replay workflow to the shared dirty-corpus parity runner.
- Added a gRPC dirty real-world validate-redacted/bundle/replay workflow to the shared dirty-corpus parity runner.
- Added
xtask check-bundle-replay-parityto run the shared bundle/replay acceptance proof across Rust core, CLI, REST, and gRPC surfaces. - Added
xtask check-evidence-parity-acceptanceas the aggregate local Rust/CLI/REST/gRPC parity acceptance suite, with optional local Python wheel smoke. - Added
xtask python-local-wheel-proofto build, install, import, and smoke-test the local Pythonhl7v2wheel without claiming TestPyPI or PyPI availability. - Added
xtask python-public-registry-proofto installhl7v2from TestPyPI or PyPI in a scratch venv and run the same Python smoke/evidence scripts after public registry upload succeeds. - Added
xtask check-deployment-provenanceto reject floating deployment image examples and keep hl7v2 image tags aligned with the workspace version. - Added a checked deployment digest example/template under the deployment provenance rail for future production image receipts.
- Aligned legacy ADR toolchain and package-surface examples with the current Rust 1.95 support boundary and post-demicrocrating product graph.
- Routed TestPyPI/PyPI install-back workflow jobs through
xtask python-public-registry-proofso hosted public-registry proof and local reproduction use the same command boundary. - Added local Python dirty real-world validate/redact/bundle/replay workflow proof using the shared Z-segment fixture.
- Added the dirty real-world Python evidence workflow smoke to the hosted Python Wheels workflow and policy guard.
- Added a shared schema-version parity fixture and manifest guard for representative CLI, REST, gRPC, and local Python evidence proof.
- Added a dirty real-world odd MSH metadata fixture and parity assertions for Rust core, CLI, REST, gRPC, and local Python smoke expectations.
- Added a dirty real-world vendor ORU narrative/null observation fixture and parity assertions for Rust core, CLI, REST, gRPC, and local Python smoke expectations.
- Added
xtask check-first-10-minutes-guideand wired it intocheck-first-use-guidesso the job-first CLI onboarding path is executable from a source checkout. - Added
xtask check-first-use-by-surface-guideto prove the Rust, CLI, and server routes from the first-use routing guide while keeping Python public registry proof separate. - Added
xtask check-vendor-upgrade-diff-guideto prove the before/after corpus drift workflow from the vendor upgrade guide. - Added
xtask check-operator-error-guidance-guideto prove representative REST safe-error fields and CLI validation report guidance from the operator error guide. - Added
xtask check-schema-version-parityto run the shared schema-version acceptance proof across Rust core, CLI, REST, and gRPC surfaces. - Added
xtask check-safe-error-phi-parityto run the shared safe-error and PHI sentinel acceptance proof across Rust core, CLI, REST, and gRPC surfaces. - Added
xtask check-profile-parityto run the shared profile lint/explain/test acceptance proof across Rust core, CLI, REST, and gRPC surfaces. - Added
xtask check-safe-support-bundle-guideto prove the operator support-bundle guide's redact, bundle, replay, artifact, and PHI-sentinel promises. - Added
xtask check-evidence-artifacts-guideto prove the operator artifact interpretation guide's doctor, profile, validation, corpus, redaction, bundle, manifest, environment, field-path, replay, and PHI-sentinel promises. - Added
xtask check-sidecar-guideto start a local HTTP sidecar and prove the deployment guide's readiness, redacted validation, invalid-message quarantine, bundle, replay, ACK policy, metrics, corpus diff, and PHI-sentinel path. - Hardened
xtask check-sidecar-guideto use an ephemeral loopback port for the executable smoke proof while leaving the manual sidecar guide on its fixed local example port. - Added generated
SAFE-SHARING.mdchecklists to CLI, Python/core, and server evidence bundles so support packets carry a reviewed pre-share checklist. - Added gRPC evidence replay parity with configured-root bundle replay, fail-closed missing/unsafe bundle handling, shared replay reports, and opt-in v2 replay provenance.
- Added gRPC quarantine output parity through
ValidateRedactedwith configured-root writes for failed redacted validation and opt-in v2 quarantine provenance. - Added gRPC inline corpus diff parity, including before/after inline corpus deltas and opt-in v2 provenance.
- Added gRPC profile explain parity with shared profile explain reports and opt-in v2 provenance.
- Added gRPC profile fixture-test parity with shared profile test reports, inline fixture inputs, expected-report subset comparisons, and opt-in v2 provenance.
- Added gRPC evidence bundle creation parity with configured-root writes, hashed public output IDs, unsafe bundle ID rejection, and opt-in v2 bundle artifacts.
- Added gRPC profile lint parity with shared profile lint reports and opt-in v2 provenance.
- Derived the Nix package version and Docker image tag from the workspace
version so the flake no longer emits a floating
latestimage tag. - Pinned the Kubernetes deployment image tag and version labels to v1.5.0
instead of the previous floating
latestimage reference. - Removed the remaining Grafana documentation example that defaulted the
administrator password to
admin. - Pinned Python wheel proof workflows to Rust 1.95.0 so public Python package build and install-back evidence uses the declared release toolchain.
- Hardened Python wheel and public-registry proof commands to fail when the
imported
hl7v2module version does not match the expected package version. - Hardened public Python registry install-back proof to install wheel artifacts only with pip caching disabled.
- Aligned the e2e HTTP client test dependency on rustls so all-features
workspace checks do not re-enable native TLS through
reqwestdefaults. - Added CPU and memory bounds to the Docker Compose validation sidecar smoke stack so local operator proof cannot consume unlimited host resources.
- Pinned the API Contracts workflow's OpenAPI, schema, and proto toolchain installs to exact versions for reproducible contract validation.
- Surfaced nightly mutation and security audit failures instead of masking them, while pinning the nightly audit and mutation tools.
- Pinned the Security workflow's
cargo-auditinstall to a specific version for reproducible dependency-audit runs. - Made routed benchmark lane failures visible while bounding the CI benchmark sample to the internal benchmark harness.
- Made the nightly workflow summary fail the workflow when required nightly jobs report failures instead of downgrading them to warnings.
- Fixed the evidence-artifacts guide smoke so corpus diff count assertions use the current dirty real-world fixture directories instead of stale after-counts.
- Added synchronize-only concurrency controls to the API Contracts and Security workflows so stale PR updates can be canceled without canceling push, scheduled, or manual proof runs.
- Rejected non-finite float spellings such as
INF,Infinity, andNaNfrom HL7 numeric validation.
- Clarified the non-Nix developer setup path, including
justinstallation,xtaskfallbacks, optional local quality tools, and OpenSSL/pkg-config troubleshooting boundaries. - Removed stale
cargo-tarpaulincoverage workflow references from CI/testing docs so they match the currentcargo-llvm-covcoverage lane. - Replaced the stale issues and next-steps planning snapshot with a current blocker map for public Python proof, evidence parity, operator workflows, dirty corpus expansion, gRPC hardening, RIPR calibration, and later TypeScript/WASM work.
- Corrected the documentation index so new planning work no longer defaults to
the closed historical
plans/1.4.1/directory. - Added crate-local context for the canonical Rust
hl7v2crate and thehl7v2-pythonbinding backend, preserving the Rust API versus Python backend boundary for future maintenance. - Corrected the ADR index status for ADR-0006 so it matches the proposed OPA policy-enforcement ADR.
- Corrected the v1.5.0 readiness receipt so the public Python
hl7v2TestPyPI blocker points at the still-open Trusted Publisher issue #563 instead of describing it as closed. - Clarified current-state wording for the public Python
hl7v2TestPyPI/PyPI blocker after the registry proof command, workflow routing, parity boundary, and gap audit landed without a new upload attempt. - Clarified the TestPyPI release-proof guide so the latest failed
publishing-mode run is no longer described as current
mainafter later registry proof scaffolding landed. - Refreshed the manifest-linked cross-surface evidence parity gap audit after
guide smokes, dirty-corpus expansion, and Python public-registry proof
boundaries landed on
main. - Recorded a second hosted-traffic calibration audit for the advisory
riprevidence surface after evidence-parity and Python-proof PR traffic, keeping the lane non-blocking. - Recorded executable safe support-bundle guide smoke proof for the operator-facing support packet workflow.
- Recorded executable sidecar guide smoke proof for the HTTP deployment walkthrough, with follow-up hardening so the executable check chooses an ephemeral loopback port instead of depending on the manual example port.
- Recorded the blocked public Python registry install-back proof commands in the machine-readable evidence parity manifest.
- Updated the current-main TestPyPI publishing-mode proof retry after the v1.5.0 refactor cleanup readiness refresh; wheel smoke passed, while upload remains blocked by TestPyPI Trusted Publisher setup.
- Recorded a post-release current-main readiness refresh after the Python wheel dirty evidence smoke, Windows policy guard, server validation-helper refactor, and synthetic value/CLI help cleanup landed through #740/#742/#743/#738.
- Recorded a post-release current-main readiness refresh after REST and gRPC dirty real-world validate-redacted/bundle/replay workflows landed through #734.
- Recorded a current-main TestPyPI publishing-mode proof retry for public
Python package
hl7v2; wheel smoke passed, while upload remains blocked by TestPyPI Trusted Publisher setup. - Recorded a post-release current-main readiness refresh after gRPC enhanced ACK parity landed through #705.
- Recorded a current-main TestPyPI publishing-mode proof attempt for public
Python package
hl7v2; wheel smoke passed, while upload remains blocked by TestPyPI Trusted Publisher setup. - Added a repeatable public crates.io install-back smoke script and receipt for the v1.5.0 Rust library, CLI, and server first-use paths.
- Recorded a post-release current-main readiness refresh after normalization and CLI ACK parity landed through #698.
- Recorded a post-release current-main readiness refresh after shared Rust/CLI/server/Python dirty-corpus parity landed through #695.
- Recorded the shared dirty real-world corpus fixture proof for Rust core and CLI corpus evidence commands.
- Recorded the server dirty real-world corpus parity proof for REST and gRPC corpus evidence commands.
- Recorded the local Python wheel dirty real-world corpus parity proof.
- Recorded a post-release current-main readiness refresh after the focused SRP module split train landed through #691.
- Recorded a fresh hosted non-publishing
Python TestPyPI Proofreceipt on currentmainand confirmed public Pythonhl7v2is still absent from TestPyPI and PyPI. - Recorded a post-release v1.5.0 objective audit showing that the crates.io, tag, GitHub release, and Rust/CLI/server install-back portions are now complete while public Python TestPyPI/PyPI proof remains blocked or undecided.
- Recorded a current hosted non-publishing
Python TestPyPI Proofreceipt for public packagehl7v2while keeping TestPyPI upload/install-back blocked on Trusted Publisher setup. - Aligned the cross-surface evidence parity docs with the already-tested Python ACK local binding proof.
- Aligned the gRPC parity docs with the currently implemented profile, bundle/replay, corpus, ACK, and normalize RPC proof surface.
- Refreshed the v1.5.0 release-readiness receipt after the Python ACK and
gRPC parity documentation syncs landed on
main. - Recorded a pre-release package registry state audit showing that v1.5.0 was
not yet published at that snapshot and that public Python
hl7v2was not on PyPI or TestPyPI. - Recorded a prompt-to-artifact objective completion audit for the active v1.5.0 lane and kept the lane open until publish, Python, and npm receipts exist.
- Recorded the v1.5.0 crates.io publish, tag, GitHub release, registry resolution, and Rust/CLI/server install-back receipt.
- Recorded the final non-publishing v1.5.0 pre-publish proof for the selected crates.io graph before any upload, tag, or GitHub release action.
- Refreshed the v1.5.0 release-readiness receipt after the advisory RIPR
calibration audit and gRPC profile lint parity landed on
main. - Refreshed the v1.5.0 release-readiness receipt after gRPC profile explain
parity landed on
main. - Refreshed the v1.5.0 release-readiness receipt after gRPC quarantine output
parity landed on
main. - Refreshed the v1.5.0 release-readiness receipt after gRPC evidence bundle
creation parity landed on
main. - Confirmed the v1.5.0 release graph decision still selects the primary Rust
graph plus
hl7v2-pythonas binding backend after the latest readiness refresh. - Refreshed the v1.5.0 release-readiness receipt after the gRPC inline corpus
fingerprint and diff parity work landed on
main. - Refreshed the v1.5.0 release-readiness receipt after the nightly property
command repair and finite numeric validation fix landed on
main. - Recorded the first hosted-traffic calibration audit for the advisory
riprevidence surface and kept the lane non-blocking.
- Added gRPC inline corpus fingerprint parity, including optional inline profile validation issue-code counts and opt-in v2 provenance.
- Added an advisory
riprstatic mutation-exposure workflow and suppression policy, keeping runtime mutation as a targeted backstop rather than a default PR tax. - Added targeted mutation lane routing for high-risk parser, MLLP, profile, redaction, bundle/replay, evidence-schema, server, Python, and release surfaces.
- Added a Rust 1.95 / v1.5.0 release-readiness workflow and receipt home for non-publishing proof before crates.io release.
- Raised MSRV from Rust 1.93 to Rust 1.95 and pinned
rust-toolchain.tomlto Rust 1.95.0 for local and CI consistency. - Prepared the Rust package graph as version
1.5.0forhl7v2,hl7v2-server, andhl7v2-cli. - Prepared
hl7v2-pythonas a publishable crates.io binding backend for the public Pythonhl7v2package, selected it for the v1.5.0 binding-backend release graph, and kept it outside the primary Rust product graph. - Tightened the compiler, Clippy, no-panic, and file-policy rails for high-throughput maintenance without increasing default CI weight.
- Retargeted the public Python distribution metadata and proof workflows to
hl7v2while keeping the internalhl7v2-pythonRust crate outside the primary Rust product graph.
- Burned down selected CLI monitor and server metrics Clippy debt with bounded conversions and narrower test assertions.
- Added opt-in v2 provenance contracts and producer paths across validation, profile, corpus, redaction, bundle, replay, quarantine, and doctor evidence artifacts while keeping v1 defaults compatible.
- Added server sidecar hardening after v1.3.0: inline corpus evidence endpoints, server replay, bundle artifact schema opt-in, readiness path-leak protection, redacted structured evidence logs, evidence metrics, and Docker Compose smoke coverage.
- Added Python evidence hardening: validation/corpus/redaction/bundle/replay v2 parity, cross-surface PHI sentinel coverage, a manual TestPyPI proof workflow, and a Python evidence workflow guide.
- Added
cargo run -p xtask -- evidence-schema-checkas the maintained local evidence fixture/schema validation rail.
- Fixed server evidence bundles so replay reproduces messages whose
MSH.9includes a third message-structure component such asADT^A01^ADT_A01.
- Prepared the v1.4.0 package line and publish dry-run receipt for the final
Rust crates.io graph:
hl7v2,hl7v2-server, andhl7v2-cli. - Verified and refreshed the validation sidecar guide with live server replay output and the current inline corpus diff response shape.
- Added current-state and contract-index documentation for the post-v1.3.0 evidence-contract line.
- Released the v1.3.0 Evidence Loop around deterministic HL7 interface evidence: first-run diagnostics, typed validation reports, profile lint/test/explain, corpus summarize/fingerprint/diff, safe-analysis redaction, evidence bundle/replay, and Python binding parity.
- Added schema-backed evidence artifacts and golden fixtures for validation reports, profile reports, corpus reports, redaction receipts, bundle summaries, and replay reports.
- Added CLI automation semantics for evidence commands: stable exit codes,
machine-readable stdout, diagnostic stderr,
--output,--quiet, and--no-colorsupport. - Added server-side edge-guard workflows: sanitized
--print-config, readiness checks, redacted validation, evidence bundle creation, policy-driven ACK/NAK decisions, and quarantine output hooks. - Added Python binding APIs for parse, JSON export, normalize, validation reports, corpus summary/fingerprint/diff, safe-analysis redaction, evidence bundle creation, and replay verification.
- Added workflow guides for first-use evidence, vendor upgrade diffs, safe support bundles, and validation sidecar deployment.
- Evidence bundles now include manifest and README artifacts, and replay verifies manifest hashes before comparing regenerated evidence.
- Current release documentation positions v1.3.0 as the published Evidence Loop release for the final Rust package graph.
- Moved the package line to
1.2.1so the final Rust publish can use a fresh release tag instead of reusing the historicalv1.2.0tag. - Published the final Rust package graph to crates.io:
hl7v2,hl7v2-server, andhl7v2-cli.
- Clarified the post-collapse public package surface:
hl7v2,hl7v2-python,hl7v2-server, andhl7v2-cli. - Marked old implementation crate READMEs as private deprecated compatibility
shims and pointed new Rust users to
hl7v2module paths. - Added the 2026-05-07 workspace-patched publish dry-run receipt for the final four-crate package graph.
- Recorded the direct crates.io dry-run result:
hl7v2passes before publish, while dependent crates correctly wait onhl7v2being present in the crates.io index.
Modernization & Integrity
- Rust 2024 Migration: Entire workspace upgraded to the Rust 2024 edition.
- MSRV 1.93: Set minimum supported Rust version to 1.93 to leverage modern language features (
let chains). - Let Chains Adoption: Extensively refactored nested conditional logic into idiomatic Rust 2024 let chains across all core crates.
- gRPC Service: Fully implemented
Hl7Serviceproviding high-performance RPCs for Parse, Validate, GenerateAck, and Normalize. - Message Lifecycle: New
hl7v2-lifecyclecrate for enterprise message retention, archival state machines, and legal hold management. - Statistical Guard: Enhanced
hl7v2-guardwith statistical baseline anomaly detection and automated warmup learning periods.
CI & Stability
- Deterministic Build: Integrated
protoc-bin-vendoredfor cross-platform gRPC code generation without external dependencies. - Network Stabilization: Refactored E2E tests to use OS-assigned ports and oneshot channel synchronization, eliminating CI flakiness.
- Security Hardening: Corrected TruffleHog scan ranges and refined license regression checks to eliminate false positives in documentation.
- Corrected field indices for MSH metadata extraction in gRPC and Lifecycle components.
- Resolved type inference ambiguities in examples caused by recent model refactoring.
- Fixed numerous Clippy warnings including
collapsible-if,field-reassign-with-default, andio-other-error. - Improved gRPC error reporting for invalid profiles and malformed HL7 messages.
Production Readiness & Security
- HTTP Server: Production-ready REST API built with Axum.
- Observability: Integrated Prometheus metrics (
/metrics) and structured JSON tracing. - Security: API Key authentication (
X-API-Keyheader) and per-IP rate limiting viatower-governor. - Swagger UI: Interactive API documentation served at
/api/docsvia OpenAPI 3.0 spec. - Nix Support: Added
flake.nixand.envrcfor reproducible development environments.
CLI Enhancements
- Streaming Parse: High-performance, memory-efficient parsing for large files via
--streamingflag. - Normalization: Improved
--canonical-delimssupport for standardizing HL7 messages. - Profiling: Real-time performance monitoring and system resource tracking in CLI commands.
Architecture (SRP Microcrate Refactoring)
- New Microcrates: Extracted logic into 28 specialized crates for better maintainability and reduced dependency trees.
- Network: New
hl7v2-networkcrate for MLLP over TCP/TLS. - Stream: New
hl7v2-streamcrate for event-based parsing. - Validation: New
hl7v2-validationcrate for rule-based engine. - Generation: Extracted
hl7v2-ack,hl7v2-faker,hl7v2-template, andhl7v2-template-values.
- Fixed critical infinite loop in streaming parser during partial segment reads.
- Resolved message boundary detection issues in sequential MLLP streams.
- Fixed race conditions in E2E tests caused by TCP port collisions.
- Improved error reporting for HL7 query path out-of-bounds access.
- Corrected numerous clippy lints and formatting issues across the workspace.
- Refactored server authentication to use isolated state for reliable testing.
- Fixed benchmark compatibility with newer Rust versions (criterion deprecations).
- Created comprehensive
docs/API_GUIDE.mdfor the REST server. - Added detailed
README.mdandCLAUDE.mdto every microcrate. - Documented key decisions in ADRs 0011-0014 (Security, Observability, Rules).
- Created
RELEASE_PROCESS.mdfor project maintainers.
Core Parsing (hl7v2-core)
- Event-based streaming parser with delimiter switching
- MLLP frame wrapping/unwrapping
- Complete escape sequence handling (\F, \S, \R, \E, \T)
- JSON serialization to canonical format
- Batch processing (BHS/BTS, FHS/FTS)
- Field path access API with presence semantics
- Performance benchmarks
Profile Validation (hl7v2-prof)
- Profile loading from YAML
- Profile inheritance with parent resolution
- Profile merging with conflict resolution
- Constraint validation (required, length, pattern)
- HL7 table value set validation
- Cross-field validation rules
- Advanced data type validation (ST, ID, CX, PN, TS, DT, TM, NM, SI, FT, TX)
- Temporal rules (date/time comparisons)
- Contextual rules (if/then logic)
- Custom validators (phone, email, SSN, birth date, checksums)
Message Generation (hl7v2-gen)
- Template-based message generation
- Deterministic seeding for reproducibility
- Realistic data generators:
- Names (gender-aware)
- Addresses (US format)
- Phone numbers
- Social Security Numbers
- Medical Record Numbers
- ICD-10 codes
- LOINC codes
- Medications
- Allergens
- Blood types
- Ethnicity/Race
- Value distributions (fixed, lists, ranges, normal)
- Error injection (invalid segments/fields)
- Corpus generation with multi-template support
- Golden hash verification
CLI Interface (hl7v2-cli)
- Parse command (with JSON output, MLLP support)
- Normalize command (message normalization)
- Validate command (profile validation)
- ACK command (ACK generation with AA/AE/AR codes)
- Generate command (template-based generation)
- Interactive REPL mode
- Zero-copy parsing claims overstated (uses Vec internally)
- No backpressure/bounded channels in streaming
- No memory bounds enforcement
- No resume parsing across chunk boundaries
- No highlight escapes (\H...\N)
- No remote profile loading
- No server mode HTTP/gRPC
- No configuration file support
- Network module contains stubs only
See docs/STATUS.md for complete status.
- Created docs/STATUS.md - Transparent feature status
- Created ROADMAP.md - v1.2.0-v2.0.0 roadmap and sprint-level planning
- Created CONTRIBUTING.md - Contributor guide
- Created DEVELOPMENT.md - Developer setup guide
- Created TESTING.md - Testing procedures
- Updated README.md with accurate feature descriptions
- Core HL7 v2 parsing
- Basic MLLP support
- Message normalization
- Simple JSON serialization
- Basic validation rules
- CLI interface (parse, validate, normalize)
- Continue server sidecar hardening, Python distribution proof, profile conformance quality, and compatibility-shim policy cleanup as separate release trains.
For information about contributing changes, see CONTRIBUTING.md.
This project follows Semantic Versioning:
- PATCH (1.0.x): Bug fixes, documentation, internal improvements
- MINOR (1.x.0): New features, backward compatible
- MAJOR (x.0.0): Breaking changes, major redesigns
- MSRV (Minimum Supported Rust Version): 1.95
- Stable: Latest stable Rust recommended
- HL7 v2.3
- HL7 v2.4
- HL7 v2.5
- HL7 v2.5.1
- HL7 v2.7
- HL7 v2.8
- HL7 v2.9
Highlights:
- Complete core parsing implementation
- Comprehensive profile validation
- Realistic message generation
- CLI interface for common operations
Performance:
- Parse: ≥100k messages/minute
- Memory: Proportional to message size
- Latency: Sub-millisecond
Quality:
- 87%+ test coverage
- Zero unsafe code in public APIs
- Comprehensive error handling
See docs/STATUS.md for complete feature list.
This project is licensed under the GNU Affero General Public License, version 3 or later (AGPL-3.0-or-later). See LICENSE.