fix(hl7): make policy safe-harbor actually Safe Harbor for the encounter loci

[NSchatz]

The defect, reproduced by probe

Under policy: "safe-harbor", seven identifying loci survived byte-identical with no manifest entry at all, because RETAIN_SEGMENTS retains a segment whole and nothing carved its identifying fields back out:

PV1-19 visit number, PV1-44 admit, PV1-45 discharge, OBR-7 observation date, DG1-5 diagnosis date, and the placer/filler order numbers (OBR-2/3, ORC-2/3).

The manifest read only PID-3[0]:transformed PID-5:removed PID-7:transformed. Reproduced on f8b7f56 before any change, and again as a red test.

HIPAA Safe Harbor 45 CFR 164.514(b)(2)(i)(C) requires removal of all elements of dates except year that are directly related to an individual, and names admission and discharge dates in the regulation text itself; a visit or order number is a unique identifying code the (R) catch-all reaches. A policy named safe-harbor that returns them is a compliance trap for anyone who trusts the name. Founder decision, 2026-08-11; breaking on purpose while the package is pre-alpha, since 0.1.0 would freeze the guarantee.

What changes

• SAFE_HARBOR_PROFILE retains nothing. The four dates generalize to their year; the five identifier loci are removed as category (R).
• LIMITED_DATA_SET_PROFILE keeps all seven, grounded in 164.514(e)(2), whose limited-data-set exclusion list enumerates sixteen direct identifiers, contains no date, and has no catch-all. Encoded as data (LIMITED_DATA_SET_DIRECT_IDENTIFIERS, isRetainableCategory()) so the citation is enforced rather than restated: exactly two of the eighteen categories are retainable.
• Retention takes three independent keys, and a missing one always means the transform runs: the adapter proposes a class, the configured options must list that class, and the resolved category must be retainable. So an adapter cannot retain anything by itself, and an options bag that omits retainedLoci keeps nothing.
• PV1-19 is routed by its CX-5 identifier-type code, exactly as PID-3 is. This is load bearing, not cosmetic: a visit-number field routinely carries a medical record or account number, both named by 164.514(e)(2). An MR-typed value now gets the same keyed surrogate as the matching PID-3 entry instead of being republished in the clear beside it.
• A safe-harbor-labelled policy may not retain at all, whatever the options bag says: fatal DEID_POLICY_INVALID, the retention analogue of the existing date-shift label guard.
• Anything still retained is recorded: disposition retained, transform retain, code DEID_RESIDUAL_RETAINED, so it reaches the Expert-Determination support report's residual inventory instead of being invisible in both artifacts. Each inventory row now carries its transform, so a kept year is distinguishable from a kept full-precision timestamp.
• defineDeidProfile()'s widen-never-narrow contract now covers retention, and it reads the opposite way round from a transform override: dropping a retained class removes more (allowed); adding one keeps more (fatal). A subset test, not a rank comparison.

The leak corpus was structurally blind to this class, which is the deeper defect

No HL7 fixture carried PV1-19/44/45 at all, so the headline gate could not have caught a regression: a sweep only reports on sentinels a fixture actually seeds. test/fixtures/hl7/adt-a03.hl7 seeds all seven plus the usual demographics and is wired into test/corpus/leak-corpus.test.ts.

Proven red on the pre-fix source. The new fixture and tests run against f8b7f56's src/ fail 8 tests, including the headline leak gate reporting all seven encounter sentinels surviving. The refuter independently reproduced this.

Positive control in both directions, because a detector that reports zero can be a gap rather than a clearance: safe-harbor removes all seven; limited-data-set still carries all seven byte-identical, composites and assigning authorities intact, while still removing the patient identifiers 164.514(e)(2) does name.

Corrected claims

docs-content/limitations.md is the honesty page, and its "loci absent from the parser models fail closed" row read as the opposite of the truth for a retained segment. That claim is deleted, not caveated. In its place the page states the true class: every field of a retained segment the carve-out does not name is still passed through and recorded nowhere, still including full-precision timestamps in EVN, PV2, PR1, RXA, RXD, FT1, TXA and SPM and the provider names in PV1-7/8 and OBR-16. The carve-out narrows that class; it does not close it.

Gate

scripts/verify.sh deid green: 621 tests, typecheck, lint, format:check, check, phi-scan, check-no-internal-refs, coverage, build, attw, smoke.

conformance-refuter pass 1 returned REFUTED with three INTRODUCED findings inside the bar, all addressed in a1851a1:

• F2 (blocker) the 164.514(e)(2) ground was asserted rather than checked, so an MR-typed PV1-19 was retained under limited-data-set, republishing in the clear the MRN pseudonymized at PID-3 in the same message.
• F3 the engine retained on the locus marker alone and never read options.retainedLoci, making the documented fail-closed default false at the layer it was declared on.
• F1 the corrected honesty page had replaced a true broad limitation with a false narrow enumeration, which is precisely what the acceptance criteria test for.

Two findings were tagged PRE-EXISTING and are deliberately not fixed here; they are going out as their own backlog lines.

Note on history

Two commits in this branch's history are titled park: UNVERIFIED, UNGRADED .... They were written by a coordinator to preserve work in progress after the worker fleet died mid-slice on an auth error. Everything in them has since been re-measured from scratch, verified and graded. Squash-merging collapses them.