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.
Something unclear? Send documentation feedback by email.