The boundary artifact

BoundaryArtifact (contracts.py) is the only value that crosses the trust boundary. Every model in the contract is strict (extra="forbid"), so no extra field can ride along, and there is no field that can hold a transcript, a name, a date, or your case identifier.

{
  "schema_version": "1.2",
  "artifact_token": "art_4f9c2a7b1e8d6035a1c2d3e4f5061728",
  "demographics": { "age_band": "30-39", "sex": "female" },
  "beats": [
    {
      "category": "presenting_complaint",
      "label": "Reason for visit",
      "value": "Persistent cough for three weeks",
      "is_past_medical_history": false,
      "disclosure": "volunteered"
    }
  ],
  "distributional_targets": {
    "token_count": 412, "type_count": 198, "zipf_slope": -1.02,
    "heaps_beta": 0.71, "heaps_k": 12.4, "mattr": 0.83, "mattr_window": 50, "yules_k": 96.5
  },
  "audit_log": {
    "boundary_k": 11,
    "entries": [
      { "type": "entity-surrogated", "entity_type": "PERSON", "count": 2 },
      { "type": "gate-decision", "check": "singling-out", "passed": true, "detail": "singling-out passed=True: age band and sex only; clinical combinations are not evaluated here (left to the clinical-rarity check and the judge)" }
    ],
    "provenance": {
      "stage0_backend": "presidio@2.2.x + en_core_web_lg + custom recognizers: ... + gliner:knowledgator/gliner-pii-base-v1.0",
      "extractor_model": "bedrock/us.anthropic.claude-sonnet-4-6",
      "judge_model": "ensemble",
      "endpoint_host": "bedrock-runtime.us-east-1.amazonaws.com"
    }
  },
  "integrity": { "algorithm": "sha256-jcs", "digest": "9f3c...e1" }
}

Fields

Field	Type	Holds
`schema_version`	`"1.2"`	sent on the wire so an upgraded client and the validator cannot silently diverge. 1.2 added `unspecified` to the age bands and changed nothing else; a sealed 1.1 artifact is still accepted. An artifact that omits the field is read as 1.1, for good: the digest covers the field, so what its absence means cannot change
`artifact_token`	`art_` plus 32 hex characters	minted at random per run; you keep the map to your case id locally, because a Medical Record Number is itself Protected Health Information (PHI)
`demographics`	`age_band`, `sex`	bands `0-9` to `70-79`, `80+`, and `unspecified`; sex `female`, `male`, `unspecified`; an exact age has no field to occupy. `unspecified` means the transcript did not say: neither field is ever guessed
`beats[]`	`category`, `label`, `value`, `is_past_medical_history`, `disclosure`	one de-identified clinical beat each, shaped to become a Tacit known-state item; `disclosure` is `volunteered` or `direct_question`
`distributional_targets`	eight numbers	lexical statistics over the beat text, used as regeneration targets; each is an aggregate that carries no identifier
`audit_log`	`boundary_k`, `entries[]`, `provenance`	counts and decisions for your Data Protection Officer (DPO); no verbatim flagged text
`integrity`	`algorithm`, `digest`	SHA-256 over the canonical JSON of every other field

Audit entry types

entries[] is a discriminated union on type:

`type`	Fields	Records
`entity-surrogated`	`entity_type`, `count`	how many entities of one type Stage 0 replaced
`attribute-generalized`	`source`, `target`, `reason`	a value widened to a broader form
`attribute-suppressed`	`attribute`, `reason`	an attribute or beat dropped, with the reason as a label
`gate-decision`	`check`, `passed`, `detail`	one control’s verdict: `named-entity`, `singling-out`, `semantic-judge`, or `clinical-rarity`. The `named-entity` and `clinical-rarity` controls repair (they neutralize a residual or drop a beat) and say how many in `detail`; a record that fails `singling-out` is refused, so an artifact never carries a failed gate
`generalization-loop`	`iteration`, `trigger`	one round of the loop

The provenance block names the Stage-0 backend, the extractor model, the judge model (recorded as ensemble), and the resolved endpoint host, so a DPO can confirm after the fact that the model stayed in-boundary.

The integrity digest

seal_artifact is the only way the SDK builds an artifact. It validates the body, then computes SHA-256 over the RFC 8785 canonical JSON of every field except integrity. Python and TypeScript canonicalize independently and share test fixtures, so a tampered or corrupted artifact is refused on both sides: the SDK refuses to parse it, and Tacit refuses to store it. verify_artifact_integrity(artifact) re-checks one you already hold.

Validating on the receiving side

export_json_schema() returns the JSON Schema of the contract, and the same schema is committed at schema/boundary-artifact.schema.json. Tacit validates incoming artifacts against a mirror of it, so neither side imports the other’s code. tacit-deid schema prints it.

Getting started

How it works

Operating it

Reference

The boundary artifact

The boundary artifact

Fields

Audit entry types

The integrity digest

Validating on the receiving side

​The boundary artifact

​Fields

​Audit entry types

​The integrity digest

​Validating on the receiving side

The boundary artifact

Fields

Audit entry types

The integrity digest

Validating on the receiving side