@cosyte/dicom 0.0.12 → 0.0.14

package/dist/index.d.ts

@@ -74,7 +74,13 @@ interface DictionaryEntry {
     readonly repeatingGroup?: boolean;
 }
 /**
- * One DICOM UID as published in PS3.6 / PS3.4 (UID registry).
+ * One DICOM UID as published in PS3.6 Annex A (Tables A-1 and A-2).
+ *
+ * `name` is the normative UID Name, with two deliberate conveniences. Retirement is carried in
+ * `retired` rather than as the trailing `(Retired)` every retired Annex A row carries in its UID
+ * Name, and four transfer syntaxes carry the short form every DICOM toolkit prints rather than
+ * PS3.6's longer `...: Default Transfer Syntax for ...` form. Every other name is the normative
+ * text.
  *
  * @example
  *   import { Dictionary } from "@cosyte/dicom";
@@ -108,6 +114,18 @@ interface UidEntry {
  * throw `TypeError` in strict mode (which all of `@cosyte/dicom`'s emitted code
  * runs under, given `"use strict"` is implicit for ES modules).
  *
+ * @example
+ * ```ts
+ * import { Dictionary } from "@cosyte/dicom";
+ *
+ * // Tag or keyword, either way round, and `undefined` rather than a throw on a miss.
+ * Dictionary.lookup("00100020")?.name; // "Patient ID"
+ * Dictionary.byKeyword("Modality")?.tag; // "00080060"
+ *
+ * // UIDs resolve to their registered name, so nobody hard-codes a SOP Class table.
+ * Dictionary.uid("1.2.840.10008.5.1.4.1.1.2")?.name; // "CT Image Storage"
+ * ```
+ *
  * @module
  */
 
@@ -141,9 +159,11 @@ declare function byKeyword(keyword: string): DictionaryEntry | undefined;
 /**
  * Look up a DICOM UID by its dotted-decimal value.
  *
- * Returns `undefined` for unknown UIDs or malformed input. Used by
- * `parseDicom()` (Phase 2) to render human-readable Transfer Syntax names
- * (DICT-06).
+ * Covers PS3.6 Annex A whole: transfer syntaxes, SOP and Meta SOP Classes,
+ * well-known SOP Instances and Frames of Reference, coding schemes and the
+ * rest, current and retired alike. Returns `undefined` for unknown UIDs or
+ * malformed input. Used by `parseDicom()` (Phase 2) to render human-readable
+ * Transfer Syntax names (DICT-06).
  *
  * @example
  *   import { Dictionary } from "@cosyte/dicom";
@@ -309,24 +329,35 @@ interface ParseOptions {
      *
      * 🛑 **THE ESCALATED DIAGNOSTIC CARRIES SOURCE BYTES THAT THE WARNING DOES
      * NOT.** A `DicomParseWarning.message` is a frozen registry string with only
-     * structural tokens filled in, so it is safe to log whole; the
-     * `DicomParseError` this option raises in its place also carries `snippet`,
+     * structural tokens filled in, so it is safe to log whole **on a well-formed
+     * file, and it is not unconditionally safe**: the `{tag}` slot is filled by a
+     * shape check, which cannot refuse a tag a lying Value Length composed out of
+     * somebody's value (measured, `PRE-EXISTING`, disclosed rather than guarded
+     * because withholding the tag would take it off every private element in every
+     * conformant file). The `DicomParseError` this option raises in its place is a
+     * different and larger surface: it also carries `snippet`,
      * **16 raw bytes, unredacted** (D-10), read at the warning's own `byteOffset`.
-     * **Which element those bytes belong to is not contracted**: that offset's
-     * frame follows where the element was read - file-absolute at the root,
-     * relative to the enclosing slice inside a defined-length Sequence or Item,
-     * and into the inflated stream under Deflated Explicit VR LE - while the
-     * snippet is cut from whichever buffer the parse is holding, so the two can
-     * disagree and the bytes can be an unrelated element's value. Do not reason
-     * from a code's message to what its snippet holds - **measure it, and treat
-     * every one of them as document content.**
-     *
-     * That is the documented design of `snippet` rather than a defect in any one
-     * code, and turning this option on does not change what any of them means -
-     * but a message-only PHI review of the lenient path does not transfer to the
-     * strict one. Log `err.code`, `err.byteOffset` and `err.message`; treat
+     * A message-only PHI review of the lenient path therefore does not transfer to
+     * the strict one. Log `err.code`, `err.byteOffset` and `err.message`; treat
      * `err.snippet` as PHI.
      *
+     * **The snippet is cut in the SAME FRAME the `byteOffset` is counted in**, so
+     * it is the bytes at the offset the diagnostic names: file-absolute at the
+     * root, relative to the enclosing slice inside a defined-length Sequence or
+     * Item, and into the inflated stream under Deflated Explicit VR LE. It was not
+     * always: until `DICOM-FATAL-MESSAGE-REGISTRY` the offset moved with the frame
+     * while the cut was always taken from the whole file, so inside a
+     * defined-length Item the 16 bytes were **an unrelated element's** - a
+     * diagnostic disclosing data from a part of the document the reader was never
+     * asked about. That is closed. **What is NOT closed, and never was a defect:
+     * the bytes are still raw source bytes.** Reading them as safe because the
+     * message beside them is registry-bound is the mistake this whole paragraph
+     * exists to prevent.
+     *
+     * **`byteOffset` still carries no frame-of-reference contract**, and closing
+     * the mismatch did not give it one: a nested offset is still not a key you can
+     * look up against the root. Measure it rather than reasoning about it.
+     *
      * Omit (do not pass `undefined`) to use the default.
      */
     readonly strict?: boolean;
@@ -907,6 +938,21 @@ declare class Element {
  * `(0002,0102)` Private Information - is captured here as raw bytes (the
  * on-wire value, even-length per PS3.5 §6.2) rather than dropped. `value` is a
  * defensive copy, so the view never aliases the parsed input buffer.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom } from "@cosyte/dicom";
+ * const ds = parseDicom(buf);
+ * // Anything the typed FileMeta fields do not model, in ascending tag order.
+ * for (const raw of ds.fileMeta?.extraElements ?? []) {
+ *   raw.tag; // e.g. "00020017" Sending Application Entity Title
+ *   raw.vr; // the VR the source wrote (File Meta is always Explicit VR LE)
+ *   raw.value.length; // even, per PS3.5 2026c section 7.1.1
+ * }
+ * ```
+ *
+ * `(0002,0016)` Source Application Entity Title is deliberately NOT the example: it is one of the
+ * typed fields, so it never reaches this array.
  */
 interface FileMetaRawElement {
     /** 8-char uppercase hex tag, e.g. `"00020100"`. */
@@ -2348,16 +2394,23 @@ declare const DEIDENTIFY_OPTIONS: readonly DeidentifyOption[];
  */
 type AppliedAction = "removed" | "emptied" | "dummied" | "uid-remapped" | "cleaned" | "kept";
 /**
- * One audited attribute outcome. Carries only structural facts - tag, keyword,
- * the resolved Annex E action code, and the SQ context path - **never** a
- * decoded value, so a report is always safe to log.
+ * One audited attribute outcome. `tag`, `keyword`, `action`, `applied` and
+ * `repeatingGroup` carry **never** a decoded value: `keyword`, `action` and
+ * `repeatingGroup` come from the Part 6 and Annex E tables, and `tag` is bound to
+ * a tag those tables carry a row for, which is membership in a closed table
+ * rather than a shape test.
+ *
+ * **🩺 `contextPath` is NOT in that class and this docstring used to say it was.**
+ * It is a chain of tags read off the wire, bound by nothing - see
+ * {@link DeidentifiedAttribute.contextPath} and the note on
+ * {@link DeidentifyReport}.
  *
  * @example
  * ```ts
  * import { deidentify, parseDicom, type DeidentifiedAttribute } from "@cosyte/dicom";
  * const { report } = deidentify(parseDicom(buf));
  * report.attributes.forEach((a: DeidentifiedAttribute) => {
- *   console.log(a.keyword, a.action, a.applied); // structural facts only - safe to log
+ *   console.log(a.keyword, a.action, a.applied); // composed from tables - safe to log
  * });
  * ```
  */
@@ -2367,7 +2420,45 @@ interface DeidentifiedAttribute {
     /** The resolved single action after collapsing any conditional code. */
     readonly action: Exclude<AnnexEActionCode, `${string}/${string}`>;
     readonly applied: AppliedAction;
-    /** Tag/index chain for an attribute inside a sequence; omitted at the root. */
+    /**
+     * Tag/index chain for an attribute inside a sequence; omitted at the root.
+     *
+     * **🩺 Each segment is `TAG[index]`, and the `TAG` half is read off the wire
+     * with no table behind it.** It is whatever tag the descent walked, so it is
+     * bound by neither a shape test nor membership in a closed one - which is what
+     * separates it from `tag`, `keyword`, `action` and `repeatingGroup`. On a file
+     * where an under-declared Value Length desynchronized the reader onto four
+     * bytes sitting **inside** somebody's value, those four bytes become a segment
+     * here. It is not the only identifier on this report read off the wire -
+     * {@link DeidentifyReport.removedPrivateTags} and
+     * {@link UnauditableSequenceFinding.tag} are too - but those two are disclosed
+     * as such, and this one was documented as structural.
+     *
+     * Measured on a synthetic `LO` carrier holding `"MRS BRAIN SMITHSON"` that
+     * under-declares by four: the reader resynchronizes onto a fabricated `SQ`
+     * header, descends it, and the report reads `contextPath: ["53484E4F[0]"]` -
+     * `"HSON"` in wire order, recovered by writing the two halves back with
+     * `writeUInt16LE`. **No warning is raised and every finding array on the
+     * report is empty.** Change the surname and the published segment changes with
+     * it. `PRE-EXISTING`, on every release that has shipped the field.
+     *
+     * **🛑 IT IS NOT THE ONLY PLACE THOSE BYTES SURFACE, AND AN EARLIER DRAFT OF
+     * THIS NOTE SAID IT WAS. A GRADED PASS REFUTED THAT AND IT MUST NOT COME
+     * BACK.** On the same file the de-identified `Dataset` still carries the
+     * fabricated `(5348,4E4F)`, so `serializeDicom` writes its header back out in
+     * full - `"HSON"` included - inside an object stamped
+     * `(0012,0062) Patient Identity Removed = YES`. That re-emission belongs to
+     * the disclosed under-declare carrier class, not to this field, and neither is
+     * a bound on the other: **redacting `contextPath` from a log does not make the
+     * object safe to share.** Pinned in
+     * `test/integration/phi-diagnostic-surface.test.ts`.
+     *
+     * It is published anyway, on the same footing as
+     * {@link DeidentifyReport.removedPrivateTags}: **where** an attribute sat is
+     * the whole audit value of the field, and withholding it would destroy that on
+     * every well-formed file in order to bound a malformed one. **Treat it as PHI
+     * when the source is untrusted.**
+     */
     readonly contextPath?: readonly string[];
     /**
      * Present when the action came from a Table E.1-1 row that names a
@@ -2389,9 +2480,29 @@ interface DeidentifiedAttribute {
  * (PS3.15 §E.1 "all instances"; §E.3.5 is the standard's own precedent for
  * removing identifying information embedded inside a string attribute).
  *
- * Every field is structural: `tag` and `vr` are the carrier's, and `hidden`
- * holds tags composed from four bytes each. No decoded value appears here, so
- * this is safe to log.
+ * `tag` and `vr` are the carrier's own and are structural. **`hidden` was not,
+ * and it is bound now.** Every tag in an embedded run is composed from four
+ * bytes that were sitting *inside* the carrier's value - that is the whole
+ * reason this type exists - and a run needs only ONE actionable attribute to be
+ * reported, so through `0.0.13` the rest of the run was listed beside it.
+ * Measured: a `CS` carrier over-declaring across a fabricated `"SMIT"` header
+ * beside a genuine `(0010,0020)` reported `hidden: ["4D535449", "00100020"]`,
+ * and `4D535449` is `"SMIT"` in wire order.
+ *
+ * **An entry is now one of the 652 literal rows of PS3.15 Table E.1-1 that this
+ * run's options left actionable.** That is a **membership** bound rather than a
+ * shape one - the posture this package already takes for a VR and for a Private
+ * Creator - so what survives names a published table entry rather than a
+ * document byte, the same trade rendering a VR makes with the 34. **A
+ * repeating-group mask hit is NOT in that set and is excluded**: `(50xx,xxxx)`
+ * Curve Data leaves the whole 16-bit element number free, so a mask match proves
+ * a rule exists without making the membership finite. A graded pass caught a
+ * draft of this filter that admitted it.
+ *
+ * **🛑 THAT IS NOT AN ALL-CLEAR OVER THIS TYPE.** `contextPath` below is
+ * unbound and unchanged, `hidden` is uncapped, and
+ * {@link DeidentifyReport} names the report's other value-bearing fields. A
+ * `DeidentifyReport` is still not safe to log whole.
  *
  * @example
  * ```ts
@@ -2407,14 +2518,44 @@ interface EmbeddedAttributeFinding {
     readonly tag: Tag;
     /** The carrier's VR. Always one of the string VRs; binary VRs are not scanned. */
     readonly vr: VR;
-    /** The tags of the Data Elements found inside the carrier's value, in wire order. */
+    /**
+     * The tags found inside the carrier's value **that this run acts on and that a
+     * published table names**, in wire order. **Not every tag in the run** - see
+     * this type's own remarks.
+     *
+     * **🩺 IT MAY BE EMPTY, AND EMPTY DOES NOT MEAN "NOTHING WAS HIDDEN HERE".**
+     * A run whose only actionable members are private attributes, Curve Data or
+     * Overlay elements reports a finding with no tags: the carrier was still
+     * emptied, and the accompanying `DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED`
+     * warning still counts the whole run. The presence of the finding is the fact;
+     * this list is the part of it that can be named.
+     */
     readonly hidden: readonly Tag[];
-    /** Tag/index chain when the carrier is inside a sequence item; omitted at the root. */
+    /**
+     * Tag/index chain when the carrier is inside a sequence item; omitted at the
+     * root. **Built by the same descent as
+     * {@link DeidentifiedAttribute.contextPath} and carrying the same caveat:
+     * each segment's tag is read off the wire, bound by nothing, so on a
+     * desynchronized read it can be four bytes of a value.** Read that field's
+     * note before logging this one.
+     */
     readonly contextPath?: readonly string[];
 }
 /**
- * One `SQ` element that was emptied because the parser never materialized its
- * items, so the de-identifier had no Data Sets to walk.
+ * One Sequence-of-Items carrier that was emptied because this run had no item
+ * stream to walk, so the de-identifier had no Data Sets to reach.
+ *
+ * **Two producers, and the second is not a parsed `SQ`.** The ordinary one is an
+ * `SQ` element whose `items` the parser never materialized. The other is a
+ * private data element retained under `RetainSafePrivate` whose `Profile` entry
+ * declares it `SQ` while the parse tree says otherwise - `UN` under Implicit VR
+ * LE when the profile was passed to `deidentify()` but not to `parseDicom`, or
+ * whatever binary VR the sender wrote under Explicit VR, which wins in the
+ * parser. The profile is the authority that retained the element, and it has
+ * said the value is a Sequence of Items; with no items on the tree, the §E.1.1
+ * obligation below falls on the carrier just the same. Such an element keeps its
+ * parsed VR in the output and is emptied rather than re-typed to `SQ`
+ * (`DICOM-PRIVATE-SQ-PARSE-VR`).
  *
  * PS3.5 2026c §7.5.1 "Item Encoding Rules" states that "Each Item Value shall
  * contain a DICOM Data Set composed of Data Elements", so an `SQ` element's
@@ -2433,12 +2574,26 @@ interface EmbeddedAttributeFinding {
  * the carrier, not as a rule about this case.)
  *
  * Both fields are structural: `tag` is the carrier's and `byteLength` is the
- * declared size of the value that was dropped. No decoded value appears here,
- * so this is safe to log.
- *
- * The parser always announces the underlying refusal first, on
+ * recorded span of the value that was dropped. **No _decoded_ value appears
+ * here, and that is not the same as "safe to log".** On the second producer
+ * `tag` can be four bytes of another element's value: a length under-declared
+ * upstream resynchronizes the reader mid-value, and if the bytes it lands on
+ * spell a private block this caller's profile declares `SQ`, followed by a VR
+ * that is one of the 34, the fabricated header is what you get here. The
+ * package's answer to that class is normally `report.undefinedVrElements`,
+ * which names a byte offset and **no tag**, and it still answers the case where
+ * the fabricated VR is outside the 34 - but it cannot answer this one, because
+ * a fabricated `OB` header and a genuine one are byte-identical. So this shares
+ * the standing exception `report.removedPrivateTags` and `uidMap` already have:
+ * a `DeidentifyReport` is **not** a value-free surface. Treat it as document
+ * content, at the sensitivity of the file it came from.
+ *
+ * For the first producer the parser announces the underlying refusal on
  * `Dataset.warnings`: `DICOM_SQ_NOT_DESCENDED` for a defined-length Implicit VR
- * LE value whose dictionary-resolved `SQ` was not a valid item stream.
+ * LE value whose dictionary-resolved `SQ` was not a valid item stream. **Do not
+ * generalise that to the second.** There the file may be entirely conformant -
+ * an honest defined-length `OB` carrier raises nothing at all - so this report
+ * field, not `Dataset.warnings`, is where that drop is visible.
  *
  * @example
  * ```ts
@@ -2454,7 +2609,14 @@ interface UnauditableSequenceFinding {
     readonly tag: Tag;
     /** Byte length of the value field that was dropped. Structural, never a value. */
     readonly byteLength: number;
-    /** Tag/index chain when the carrier is inside a sequence item; omitted at the root. */
+    /**
+     * Tag/index chain when the carrier is inside a sequence item; omitted at the
+     * root. **Built by the same descent as
+     * {@link DeidentifiedAttribute.contextPath} and carrying the same caveat:
+     * each segment's tag is read off the wire, bound by nothing, so on a
+     * desynchronized read it can be four bytes of a value.** Read that field's
+     * note before logging this one.
+     */
     readonly contextPath?: readonly string[];
 }
 /**
@@ -2514,8 +2676,14 @@ interface UnauditableSequenceFinding {
  * finding rather than an inconsistency.
  *
  * `byteOffset` locates the element instead - a position this parser counted.
- * Nothing here renders a document byte: an offset the parser counted, a decoded
- * length, and the structural `contextPath`. Safe to log.
+ *
+ * **🩺 THAT WITHHOLDING IS NOT WHOLE, AND THIS PARAGRAPH USED TO CLAIM IT WAS.**
+ * It said "nothing here renders a document byte ... and the structural
+ * `contextPath`. Safe to log." `contextPath` is not structural: its segments are
+ * tags read off the wire by the same descent, so the header this type refuses to
+ * name by `tag` can be named by the `contextPath` of a finding one level down.
+ * See {@link DeidentifiedAttribute.contextPath} for the measurement. `byteOffset`
+ * and `byteLength` are unaffected and the reasoning above them still stands.
  *
  * @example
  * ```ts
@@ -2546,27 +2714,68 @@ interface UndefinedVrFinding {
      * as "structural, never a value" the way its siblings are described.
      */
     readonly byteLength: number;
-    /** Tag/index chain when the carrier is inside a sequence item; omitted at the root. */
+    /**
+     * Tag/index chain when the carrier is inside a sequence item; omitted at the
+     * root. **Built by the same descent as
+     * {@link DeidentifiedAttribute.contextPath} and carrying the same caveat:
+     * each segment's tag is read off the wire, bound by nothing, so on a
+     * desynchronized read it can be four bytes of a value.** Read that field's
+     * note before logging this one.
+     */
     readonly contextPath?: readonly string[];
 }
 /**
  * The audit trail returned alongside the de-identified dataset.
  *
  * Most fields are composed from static tables: Part 6 keywords, Annex E action
- * codes, structural `TAG[index]` sequence paths, and registry warning messages.
- * **Two are not, and both are named here rather than in a footnote.**
- *
- * 1. **`uidMap`** - its keys are the source UIDs read out of the file, kept so a
- *    caller can make UID replacement consistent across a study or an archive. A
- *    Study or SOP Instance UID is a unique identifying number, so treat it as
- *    PHI.
- * 2. **`removedPrivateTags`** - see the field's own note. On a *well-formed*
- *    file these are the sender's own private tag numbers and carry nothing; on a
- *    malformed one a tag can be four bytes of a value, and it is measured, not
- *    theoretical.
+ * codes, the active option names.
+ * **Several fields are not, and they are named here rather than in a footnote.**
+ * 🛑 **Do not quote a COUNT of them, here or anywhere else.** The count read
+ * "one" and then "two" and then "three", and was wrong every time it was read,
+ * because each correction bumped the numeral without re-deriving the list.
+ * **The list below carried its own numerals until one had to be added, which is
+ * the same disease one step removed, so they are gone.** Treat it as the current
+ * reading of a surface that has grown, not as a proof of exhaustiveness.
+ *
+ * - **`uidMap`** - its keys are the source UIDs read out of the file, kept so a
+ *   caller can make UID replacement consistent across a study or an archive. A
+ *   Study or SOP Instance UID is a unique identifying number, so treat it as
+ *   PHI.
+ * - **`removedPrivateTags`** - see the field's own note. On a *well-formed*
+ *   file these are the sender's own private tag numbers and carry nothing; on a
+ *   malformed one a tag can be four bytes of a value, and it is measured, not
+ *   theoretical.
+ * - **`unauditableSequences[].tag`** - see
+ *   {@link UnauditableSequenceFinding}. Same shape as `removedPrivateTags` by a
+ *   narrower route: a private carrier a {@link Profile} declares `SQ` is named
+ *   there, and an under-declared length upstream can resynchronize the reader
+ *   onto four bytes that spell such a block. The package's usual answer to a
+ *   fabricated header, `undefinedVrElements`, carries a byte offset and no tag,
+ *   and still answers it whenever the fabricated VR is outside the 34 PS3.5
+ *   §6.2 defines. It cannot when the fabricated VR is one of them, because those
+ *   two files are byte-identical.
+ * - **`contextPath`, on all four findings that carry one** - see
+ *   {@link DeidentifiedAttribute.contextPath}, which holds the measurement. The
+ *   segment tags come off the wire with no table behind them, so a fabricated
+ *   `SQ` header the reader descended is named there, `PRE-EXISTING`, with **no
+ *   warning and no finding array to correlate it with**. This is the field the
+ *   rest of this docstring, the tolerance table and the troubleshooting guide
+ *   all called structural. **It is a logging hazard and nothing more: on that
+ *   same file the de-identified object itself re-emits the fabricated header, so
+ *   redacting this field does not make the object safe.**
+ *
+ * `embeddedAttributes[].hidden` **left that list** in
+ * `DICOM-DIAGNOSTIC-PHI-RESIDUALS` - an entry is now a literal PS3.15 Table
+ * E.1-1 row, so it is not value-bearing. Its own disclosure had been reworded
+ * twice by then, and this repo deletes a disclosure at that point rather than
+ * writing a third; what is true of the field is stated once, on
+ * {@link EmbeddedAttributeFinding}. The field is **still uncapped**.
  *
  * So "the report is safe to log apart from `uidMap`" is **not** an accurate
  * description of this type, and was corrected rather than kept convenient.
+ * **This is the only copy of that list.** Two others lived in module docstrings,
+ * still naming `hidden` after it left and never naming `contextPath` at all; a
+ * graded pass found them and they were deleted rather than resynced.
  *
  * @example
  * ```ts
@@ -2620,9 +2829,11 @@ interface DeidentifyReport {
      * sequence is still emptied; an array exactly that long means "at least this
      * many", so read it as truncated rather than as a total.
      *
-     * **It is not a complete list of what went un-audited, either**: a private
-     * `SQ` a {@link Profile} vouches for under `RetainSafePrivate` is kept
-     * verbatim and never appears here.
+     * **It covers private sequences too, since `DICOM-PRIVATE-SQ-CARVE-OUT`.** A
+     * private `SQ` a {@link Profile} vouches for under `RetainSafePrivate` used to
+     * be kept verbatim and never appear here; it is now emptied and listed on the
+     * same terms as any other, because the profile's licence under PS3.15 §E.3.10
+     * is over a private attribute and not over an item stream nothing could read.
      */
     readonly unauditableSequences: readonly UnauditableSequenceFinding[];
     /**
@@ -2651,14 +2862,17 @@ interface DeidentifyReport {
      * {@link UndefinedVrFinding}: the tag of a fabricated header is itself part of
      * some element's value.
      *
-     * Unlike its sibling this list has **no carve-out**, and the reason is
-     * structural rather than a promise: `keepOrEmpty` is the **only** path that
-     * writes a source value into de-identified output unchanged, and the test sits
-     * at the top of it. Every other outcome - `X` remove, `Z`/`C` empty, `D` dummy,
-     * `U` remap, and a private tag the Basic Profile drops - already replaces the
-     * value. So a `RetainSafePrivate` element a {@link Profile} vouches for still
-     * reaches this test and is still emptied, which is where the sibling
-     * `SQ`-with-no-items rule has a real carve-out and this one does not.
+     * This list has **no carve-out**, and the reason is structural rather than a
+     * promise: `keepOrEmpty` is the **only** path that writes a source value into
+     * de-identified output unchanged, and the test sits at the top of it. Every
+     * other outcome - `X` remove, `Z`/`C` empty, `D` dummy, `U` remap, and a
+     * private tag the Basic Profile drops - already replaces the value. So a
+     * `RetainSafePrivate` element a {@link Profile} vouches for still reaches this
+     * test and is still emptied. Its sibling
+     * {@link DeidentifyReport.unauditableSequences} had a real one until
+     * `DICOM-PRIVATE-SQ-CARVE-OUT`; neither has one now, and they arrive at that by
+     * different routes - this one because nothing bypasses `keepOrEmpty`, that one
+     * because a vouched-for private `SQ` is routed into the ordinary `SQ` branches.
      */
     readonly undefinedVrElements: readonly UndefinedVrFinding[];
     /**
@@ -2839,8 +3053,9 @@ declare class DeidentifyError extends Error {
  * nine *metadata-affecting* Annex E Options, driven by the generated Table E.1-1
  * action map ({@link annexE}). It is a **pure** function: the input {@link Dataset}
  * is never mutated; a fresh `Dataset` (with a rebuilt element map and File Meta)
- * is returned alongside a {@link DeidentifyReport} whose two non-value-free
- * fields are named on that type: `uidMap` and `removedPrivateTags`.
+ * is returned alongside a {@link DeidentifyReport} whose non-value-free fields
+ * are named on that type. **The list is deliberately not copied here** - see
+ * `./index.ts` for what a third copy of it cost.
  *
  * **What it does**
  * - Resolves each attribute's action (basic profile, overridden by an active
@@ -2877,10 +3092,22 @@ declare class DeidentifyError extends Error {
  *   replacement (which needs domain context the metadata layer lacks).
  * - Pixel-level options (`CleanPixelData`, `CleanRecognizableVisual`) are out of
  *   scope; burned-in text is warned, never cleaned.
- * - A private data element kept under `RetainSafePrivate` is kept *verbatim* - if
- *   it is itself a sequence carrying standard PHI attributes, that nested content
- *   is not recursed. The profile vouches the element is safe; nest accordingly.
- * - A **standard** (non-private) `SQ` whose `items` the parser did not
+ * - A private data element kept under `RetainSafePrivate` is kept *verbatim*
+ *   **unless it carries a Sequence of Items**. A private `SQ` the profile
+ *   vouches for is retained as an element but its items are **walked**, so
+ *   standard PHI attributes nested inside it are de-identified like any others
+ *   (`DICOM-PRIVATE-SQ-CARVE-OUT`; it was kept whole and unexamined through
+ *   `0.0.10`). The profile vouches that the *private attribute* is safe, which
+ *   PS3.15 §E.3.10 is about; it cannot vouch for a Data Set nested in its value,
+ *   which §E.1.1 covers "whether contained in the top level Data Set or embedded
+ *   in an Item of a Sequence of Items". **"Carries a Sequence" is decided by the
+ *   profile as well as by the parse tree**, because the two disagree about the
+ *   same bytes whenever the profile did not reach `parseDicom` (Implicit VR LE
+ *   writes no VR) or the sender wrote a binary VR (Explicit VR, where the wire
+ *   wins). A carrier the profile declares `SQ` and the tree did not resolve is
+ *   emptied rather than kept, keeping its parsed VR
+ *   (`DICOM-PRIVATE-SQ-PARSE-VR`). See {@link keepRetainedPrivate}.
+ * - A `SQ` whose `items` the parser did not
  *   materialize is **emptied**, not kept:
  *   its value is by PS3.5 §7.5.1 a stream of Data Sets, and a run that cannot
  *   enumerate them cannot discharge §E.1.1's obligation inside them, so the
@@ -2891,16 +3118,18 @@ declare class DeidentifyError extends Error {
  *   `(0010,0020)` Patient IDs among them - into output stamped
  *   `(0012,0062) PatientIdentityRemoved = YES`
  *   (`DICOM-DEIDENT-RAWBYTES-PASSTHROUGH`, live through `0.0.6`).
- * - Two things are still kept verbatim, deliberately. A **private** `SQ`
- *   retained under `RetainSafePrivate` + a {@link Profile}, where the profile has
- *   vouched for the element by creator and tag - the pre-existing "kept
- *   verbatim" limitation above, unchanged. And an undefined-length **`UN`** whose
- *   CP-246 descent was refused: it keeps `vr === "UN"`, and since every ordinary
- *   `UN` element also has no items, the test above cannot be applied there
- *   without emptying every unknown-VR element in every file. That one is
- *   measured and **still leaks** (`PRE-EXISTING`); the reliable consumer-side
- *   test remains `el.items === undefined` on a `UN` element you are trusting a
- *   report about.
+ * - One thing is still kept verbatim, and it is **not** the private `SQ`: an
+ *   undefined-length **`UN`** whose CP-246 descent was refused. It keeps
+ *   `vr === "UN"`, and since every ordinary `UN` element also has no items, the
+ *   test above cannot be applied there without emptying every unknown-VR element
+ *   in every file. That one is measured and **still leaks** (`PRE-EXISTING`);
+ *   the reliable consumer-side test remains `el.items === undefined` on a `UN`
+ *   element you are trusting a report about. `RetainSafePrivate` no longer
+ *   exempts anything from the rule above it - a vouched-for private `SQ` with no
+ *   materialized items is emptied on the same terms as any other. The one place
+ *   a `UN` **is** answered is the retained-private route, and only because a
+ *   profile named it: a private `UN` whose profile entry declares `SQ` is
+ *   emptied there. That is a statement about that route and not about `UN`.
  * - An element whose **on-wire VR is not one of the 34** PS3.5 §6.2 defines is
  *   **emptied**, not kept (`DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE` +
  *   `report.undefinedVrElements`). Such an element is what an *under*-declared
@@ -2929,12 +3158,14 @@ declare class DeidentifyError extends Error {
  *   which removal is the branch available here (`(0008,0307)` is not
  *   implemented). Every private element the recursion **reaches** in such an
  *   Item, at any depth below it, is removed and named in
- *   `report.removedPrivateTags`. **There is one carve-out, and it is the same one
- *   `#54` was refused for asserting away**: `keepsPrivate` decides *before* the
- *   descent, so a **private `SQ`** the profile vouches for is kept **verbatim**,
- *   its items are never walked, and this rule is never consulted inside it -
- *   measured, and it still leaks a private value absorbed from the root
- *   (`PRE-EXISTING`, identical on `164eb39`, its own item). That costs content
+ *   `report.removedPrivateTags`. **The carve-out `#54` was refused for asserting
+ *   away is CLOSED** (`DICOM-PRIVATE-SQ-CARVE-OUT`): `keepsPrivate` still decides
+ *   before the descent, but a **private `SQ`** it vouches for now routes through
+ *   {@link keepRetainedPrivate} into the ordinary `SQ` branches instead of being
+ *   kept verbatim, so its items **are** walked and this rule **is** consulted
+ *   inside them. Read that as "the retention decision no longer decides the fate
+ *   of the Data Sets below it", never as "the class is closed" - the residual
+ *   list in `CLAUDE.md` is the census. That costs content
  *   on a malformed file and nothing at all on a conformant one; without it a
  *   private value the sender wrote **outside** the sequence was retained on the
  *   Item's reservation and written into output stamped `PatientIdentityRemoved =
@@ -2950,10 +3181,10 @@ declare class DeidentifyError extends Error {
  *   inner sequence ejecting a creator into the still-usable Item that encloses it
  *   is measured and pinned. The cut is positional, so a reservation the sender
  *   wrote **ahead of** the offending sequence is untouched. Every private element
- *   after that point is removed and named in `report.removedPrivateTags`, and the
- *   **private-`SQ` carve-out above still applies**: a private `SQ` inside the
- *   settled run that the profile vouches for is kept verbatim and never walked.
- *   See {@link settledBound}.
+ *   after that point is removed and named in `report.removedPrivateTags`. A
+ *   private `SQ` inside the settled run that the profile vouches for is retained
+ *   and **walked**, so the rule reaches its items too - it no longer stops at the
+ *   carrier. See {@link settledBound} and {@link keepRetainedPrivate}.
  *
  * @module
  */