Clinical profiles and external validation

OPRP 0.1.0-dev.11 adds six versioned FHIR R4 StructureDefinitions, a local FHIR conformance package, an independent HL7 validator runner and optional trusted Host admission helpers. Dev10 adds complete dependency locking, finite local terminology and durable validation jobs. These artifacts let implementers reproduce structural/profile validation outside the handwritten reference validator. They do not freeze a production specification or certify a Host, clinical workflow or US Core server.

Base profiles and US targets

The profile catalogue maps Condition, AllergyIntolerance, MedicationStatement, Encounter, Procedure and Immunization to draft OPRP canonicals. Each profile derives from its R4 resource, requires relative Patient ownership, prohibits top-level contained resources/modifier extensions and declares the selected mandatory clinical fields. MedicationStatement selects medicationCodeableConcept. The definitions are differentials; the HL7 engine builds snapshots while loading them. They retain base FHIR constraints rather than copying the base definitions. FHIR R4 profiling.

The canonical namespace https://www.convey.care/fhir is proposed publication metadata. It is not currently deployed or a required runtime directory. Hosts load versioned packages from independently configured copies. The package can be distributed independently of Convey; OPRP original profiles use Apache 2.0; identifier publication remains a release decision.

Base OPRP profiles remain international. The additional oprp-us-core target validates against both OPRP and US Core 9.0.0, pinned as a deliberate test baseline. Its selection does not establish which version a particular US deployment or certification program must implement. Current US Core has two Condition profiles and uses different medication resource types; this increment selects the problems/health-concerns Condition profile and does not invent a MedicationStatement mapping. US Core 9 profile catalogue.

The OPRP profiles supplement existing bounded admission. They do not encode every nested-content restriction, exact patient binding, field-size bound, authorization decision or label policy. An externally valid resource still must pass the Host's own checks. Conversely, existing prototype resources may pass handwritten admission and fail the stronger external target. Existing data is not silently rewritten.

Pinned tooling and local operation

The toolchain lock pins official HL7 validator 6.10.4 and the official US Core 9.0.0 package by SHA-256. Java 21.0.11 is the tested runtime. The JAR is approximately 192 MiB; a fully locked dependency cache must be supplied before validation. Validator release.

npm run setup:validator
npm run package:profiles
npm run clinical:conformance

setup:validator explicitly downloads the two locked artifacts and verifies their hashes. Existing mismatched files fail instead of being trusted or replaced. It additionally verifies/installs a supplied complete dependency-cache copy. It does not install Java or change global SDK configuration. OPRP_VALIDATOR_JAR and OPRP_US_CORE_PACKAGE select already downloaded, hash-matching copies for the demonstration.

The runner invokes Java with argument arrays, a workspace-local home/cache, a private temporary directory, bounded input/output and a process deadline. It checks the JAR and selected package hashes and detects changes to loaded profile sources before validating. Input resources are cloned before asynchronous work so caller mutation cannot change what an approval binds. Every result must be an OperationOutcome, mapped unambiguously to its input file. Missing/malformed reports, process failures, timeouts and excessive output never grant admission.

The runner uses -tx n/a and disables the default resource fetcher. Terminology is disabled when no local catalogue is configured. Local structural/invariant validation can pass while code/value-set checks remain warning-only or incomplete. The runner returns warnings and marks only reports without error/fatal issues accepted. A report with warnings must not be described as comprehensive terminology or clinical validation.

The runner prohibits HTTP using the pinned engine's -no-http-access flag and verifies the full cache lock before/after each run. Missing dependencies fail rather than triggering runtime acquisition. Configure terminology to add the finite local checker; see installation and coverage.

Trusted Host admission

The public protocol continues to request permissions and tokens from the Host. This integration adds no mandatory patient login, requester-supplied certificate of clinical correctness, or new Convey service. It is a trusted Host-owned preflight workflow, not a new public wire endpoint.

import { ExternalFhirValidator, ValidatedClinicalAdmission } from '@convey/oprp-sdk';
const validator = new ExternalFhirValidator({
  jar: '/host/tools/validator_cli.jar',
  workspace: '/host/private/validation',
  profiles: '/host/profiles',
  usCorePackage: '/host/tools/us-core-9.0.0.tgz',
});
const admission = new ValidatedClinicalAdmission(validator, 'oprp', 300);
host.clinical.admission = admission;

// A trusted intake worker authenticates and authorizes its workflow first.
const reports = await admission.assess([proposedResource], patient, now);
if (!reports[0].accepted) {
  // Preserve diagnostics for authorized operator review; do not silently fix data.
}
// The ordinary authorized create/update reaches the Host after successful preflight.

The preflight cache admits only exact successful content for a configured target. Its digest includes resource ID, patient ownership, clinical fields, security labels, profiles and other content. Only meta.versionId and meta.lastUpdated, which the Host generates for writes, are excluded. The Host rechecks normal authorization, classification, optimistic versions and the current digest inside the mutation transaction. A new or changed write without a fresh preflight fails external_validation_required before committing resources, history, receipts or events.

The lightweight ValidatedClinicalAdmission helper remains an in-memory option. Its approvals default to five minutes, may be configured from one second through one hour, and are bounded to 256 in-memory entries. They are not durable. Restart or expiry requires another preflight; callers must use the same Host clock. A committed same-operation receipt remains retryable after preflight expiry because it accepts no new content. Deletes use normal permission/visibility/version checks without a new clinical representation. Uncertain queued writes stay pending until the operator supplies validation; this does not bypass their ordering or create clinical corrections automatically.

The gate also checks authoritative clinical resources and every retained clinical version before archive restore, before issuing a migration ready proof and again before migration materialization, and checks trusted classification changes. Preflight these versions at the destination under its policy. A failed import rolls back the whole transaction. Migration operators must finish destination preflight before source release, and refresh it as needed; the durable helper now schedules missing destination versions and persists approvals; the in-memory helper still requires manual preflight. Source validation evidence is not transferred as destination admission authority.

capabilities advertises external_validation only while a gate is installed, including engine, target, package version, optional US Core version, terminology mode and lifetime. The existing validation_profile: oprp-r4-clinical-2 remains the mandatory bounded validator. Omitting the optional gate does not claim external validation. Only the Node Host helper is implemented; Python/.NET requesters can use the Host as usual but have no native external-validator adapter in this release.

Evidence and compatibility

The recorded synthetic evidence includes accepted/rejected case counts, warning counts, profile-catalogue hash and observed dependency-cache versions/full tree hashes. It records the current synthetic run. Immutable dependencies are separately specified by the full cache lock.

Clinical conformance uses the real pinned engine to accept six OPRP examples, reject forbidden contained content for each, validate five selected US Core examples and reject the unmapped MedicationStatement target. It also rejects a completed Procedure without performed time under US Core, even though the base OPRP example passes. This difference demonstrates why the external check is useful. The workflow additionally exercises encrypted Host rejection/preflight/retry, six locally coded examples, three local terminology rejections, durable intake restart and destination migration-worker restart through activated custody.

The unit integration tests separately test manifest consistency, digest binding, expiry, mutation rollback, retry behavior, report structure, process failure/deadline and archive/classification gates. Their stub validator tests plumbing only; the standalone clinical-conformance command provides independent validation evidence. The synthetic examples are intentionally minimal and may generate warnings, including missing narrative and absent coded terminology. No real clinical data or external vendor is involved.

The local FHIR package and profile checksums are publication inputs, not a public release. The package includes six StructureDefinitions, an ImplementationGuide and package index. OPRP original profile materials use Apache 2.0, with the license and notices included in the package. Clients and operators should read diagnostics and reconcile existing data explicitly before enabling stronger admission.

Next: deployable Host operations, replaceable storage/persistence interfaces, and a reproducible two-Host installation with health/recovery tooling. Broader licensed terminology and independent security review remain release gates.