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
| Name | Type | Required | Description |
|---|---|---|---|
bundle | fhir-bundle | No | Single mode: the hospital FHIR Bundle for the consult scope. |
documents | json | No | Single mode, optional: document texts from the hospital text store. |
consult_ref | text | No | Single mode: the consult reference (tokenised as CON). |
patient_id | text | No | Single mode: the hospital Patient logical id (post-EMPI golden record). |
encounter_id | text | No | Single mode, optional: the consult's Encounter id; defaults to the only Encounter in the bundle. |
scope | json | No | Optional evidence scope; only mode (encounter|patient|documents|libraries) and a whole-number window_days are carried, anything else is dropped. |
evidence | json | No | Batch mode: an array of {consult_ref, patient_id, bundle, documents} as emitted by consult-evidence-load. |
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
package | json | No | Single mode: the sealed Evidence Package (tietai.seam.evidence-package/v1). Absent when the package failed. |
packages | json | No | Batch mode: released Evidence Packages only; failed consults are absent. The only port HG-22's hop guard admits. |
summary | json | No | PHI-free outcome per consult (object in single mode, array in batch mode). Never wired across a seam. |
success | boolean | No | True when at least one package was released. |
Settings
Basic
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Language | language | enum | No | es | es, ca | Language of the document text and of the NER model (es validated for the pilot). |
| Model size | model_size | enum | No | large | small, large | Size of the Spanish NER model of the first pass (es/<size> under HYDRA_PHI_MODELS_DIR). |
| Residual model size | residual_model_size | enum | No | large | small, large | Model of the second (residual) detection pass that fails the package closed. |
Advanced
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Window tokens | window_tokens | number | No | 400 | Maximum model tokens per NER window; long notes are windowed so nothing is truncated. | |
| Stride tokens | stride_tokens | number | No | 64 | Overlap between consecutive windows, so an entity on a boundary is detected once. | |
| Detect threshold | detect_threshold | number | No | 0.5 | Minimum confidence of a first-pass detection. Low on purpose: over-detection is reversible. | |
| Residual block confidence | residual_block_confidence | number | No | 0.8 | A residual PERSON/ID/contact detection at or above this confidence fails the package. Bounded to [0.50, 0.95]. | |
| Residual max rate | residual_max_rate | number | No | 0.005 | Residual detections (≥ 0.50) allowed per replacement before the package fails. Bounded to (0, 0.05]. | |
| Max concurrency | max_concurrency | number | No | 4 | Documents pseudonymised in parallel within one package. | |
| Extension allowlist | extension_allowlist | array | No | FHIR extension URLs kept (and still walked). Every other extension is dropped. Pilot: empty. | ||
| Drop non-text attachments | drop_nontext_attachments | boolean | No | true | Fixed true: a non-text attachment never crosses the seam; false is rejected. |
Errors
| Code | Description |
|---|---|
SEAM_NOT_DATA_HOLDER | Not on the data-holder site, or the seam dependencies are not wired (canonical name; emitted today as its alias SEAM_NOT_HOSPITAL) |
SEAM_NOT_HOSPITAL | Deprecated alias of SEAM_NOT_DATA_HOLDER; the code currently emitted |
NER_MODEL_UNAVAILABLE | The Spanish NER model could not be loaded or a window inference failed |
KEY_MISMATCH | A stored date offset differs from the recomputed one (wrong k_site after a restore) |
SEAM_INPUT | Neither 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
summaryacross 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
summarywith 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..