Aller au contenu principal

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.

Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.