Zum Hauptinhalt springen

PHI Pseudonymise (Seam)

Category: Security
Node id: phi-pseudonymise
Maturity: beta
Risk tier: C

Standards: GDPR Art. 4(5), GDPR Art. 9, IEC 62304 Class C

Hospital-side reversible pseudonymisation (GDPR Art. 4(5)) of a consult's FHIR evidence and Spanish document text: keyed PSN tokens, per-patient date shift, persisted correspondence table, fail-closed residual-PHI check. Emits a sealed Evidence Package for the tenant.

What it does​

  • phi
  • database
  • pseudonymisation
  • reidentification-key-writer

Use cases​

  • Pseudonymising a cardiology consult's evidence on the hospital before it crosses the Mesh seam to the EU tenant
  • Batch pseudonymisation of the pilot cohort for the P7/P8 pipelines

Runtime​

  • Performance tier: slow

Input ports​

NameTypeRequiredDescription
bundlefhir-bundleNoSingle mode: the hospital FHIR Bundle for the consult scope.
documentsjsonNoSingle mode, optional: document texts from the hospital text store.
consult_reftextNoSingle mode: the consult reference (tokenised as CON).
patient_idtextNoSingle mode: the hospital Patient logical id (post-EMPI golden record).
encounter_idtextNoSingle mode, optional: the consult's Encounter id; defaults to the only Encounter in the bundle.
scopejsonNoOptional evidence scope; only mode (encounter|patient|documents|libraries) and a whole-number window_days are carried, anything else is dropped.
evidencejsonNoBatch mode: an array of {consult_ref, patient_id, bundle, documents} as emitted by consult-evidence-load.

Output ports​

NameTypeRequiredDescription
packagejsonNoSingle mode: the sealed Evidence Package (tietai.seam.evidence-package/v1). Absent when the package failed.
packagesjsonNoBatch mode: released Evidence Packages only; failed consults are absent. The only port HG-22's hop guard admits.
summaryjsonNoPHI-free outcome per consult (object in single mode, array in batch mode). Never wired across a seam.
successbooleanNoTrue when at least one package was released.

Settings​

Basic​

SettingNameTypeRequiredDefaultAllowed valuesDescription
LanguagelanguageenumNoeses, caLanguage of the document text and of the NER model (es validated for the pilot).
Model sizemodel_sizeenumNolargesmall, largeSize of the Spanish NER model of the first pass (es/<size> under HYDRA_PHI_MODELS_DIR).
Residual model sizeresidual_model_sizeenumNolargesmall, largeModel of the second (residual) detection pass that fails the package closed.

Advanced​

SettingNameTypeRequiredDefaultAllowed valuesDescription
Window tokenswindow_tokensnumberNo400Maximum model tokens per NER window; long notes are windowed so nothing is truncated.
Stride tokensstride_tokensnumberNo64Overlap between consecutive windows, so an entity on a boundary is detected once.
Detect thresholddetect_thresholdnumberNo0.5Minimum confidence of a first-pass detection. Low on purpose: over-detection is reversible.
Residual block confidenceresidual_block_confidencenumberNo0.8A residual PERSON/ID/contact detection at or above this confidence fails the package. Bounded to [0.50, 0.95].
Residual max rateresidual_max_ratenumberNo0.005Residual detections (≥ 0.50) allowed per replacement before the package fails. Bounded to (0, 0.05].
Max concurrencymax_concurrencynumberNo4Documents pseudonymised in parallel within one package.
Extension allowlistextension_allowlistarrayNoFHIR extension URLs kept (and still walked). Every other extension is dropped. Pilot: empty.
Drop non-text attachmentsdrop_nontext_attachmentsbooleanNotrueFixed true: a non-text attachment never crosses the seam; false is rejected.

Errors​

CodeDescription
SEAM_NOT_DATA_HOLDERNot on the data-holder site, or the seam dependencies are not wired (canonical name; emitted today as its alias SEAM_NOT_HOSPITAL)
SEAM_NOT_HOSPITALDeprecated alias of SEAM_NOT_DATA_HOLDER; the code currently emitted
NER_MODEL_UNAVAILABLEThe Spanish NER model could not be loaded or a window inference failed
KEY_MISMATCHA stored date offset differs from the recomputed one (wrong k_site after a restore)
SEAM_INPUTNeither or both of single mode (bundle, consult_ref, patient_id) and batch mode (evidence)

Runtime notes​

  • Requires HYDRA_SITE_RESIDENCY=data-holder (deprecated alias: hospital) and seam keys; refuses to run otherwise.
  • Never wire summary across a seam expecting identifiers — it has none.
  • A residual or data failure (RESIDUAL_PHI, KNOWN_IDENTIFIER_RESIDUAL, CROSS_PATIENT_REFERENCE, UNSHIFTABLE_DATE) returns success=false with the summary and opens a seam_residual_phi review; it is not an error.
  • A missing NER model, a key mismatch, a database or audit failure is an error: nothing of that consult is emitted or committed. In batch mode the other consults still run; the failed one appears in summary with status error (NER_MODEL_UNAVAILABLE or INFRASTRUCTURE_ERROR), and the node returns an error only when no package was released. A consult committed as released is always emitted: a later failure in the batch (including a review that could not be opened) never discards it.
  • The correspondence table is written inside the node, in the same transaction as the audit record; it is never a node output.

See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.

Etwas unklar? Senden Sie Feedback zur Dokumentation per E-Mail..