@cosyte/dicom 0.0.11 → 0.0.13

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";
@@ -141,9 +147,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";
@@ -307,6 +315,32 @@ interface ParseOptions {
      * When `true`, every Tier-2 warning is escalated to a thrown
      * `DicomParseError` carrying the warning code. Default `false`.
      *
+     * 🛑 **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`,
+     * **16 raw bytes, unredacted** (D-10), read at the warning's own `byteOffset`.
+     * 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;
@@ -420,6 +454,7 @@ declare const WARNING_CODES: {
     readonly DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED: "DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED";
     readonly DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED: "DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED";
     readonly DICOM_DEIDENT_METHOD_NOT_ADDED: "DICOM_DEIDENT_METHOD_NOT_ADDED";
+    readonly DICOM_DEIDENT_METHOD_NOT_LO: "DICOM_DEIDENT_METHOD_NOT_LO";
     readonly DICOM_DEIDENT_METHOD_PRIOR_RETAINED: "DICOM_DEIDENT_METHOD_PRIOR_RETAINED";
     readonly DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE: "DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE";
     readonly DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE: "DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE";
@@ -2327,16 +2362,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
  * });
  * ```
  */
@@ -2346,7 +2388,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
@@ -2368,9 +2448,15 @@ 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` is not,
+ * and calling this finding "safe to log" was wrong.** Each entry is composed
+ * from four bytes that were sitting *inside* the carrier's value - that is the
+ * whole reason the field exists - so on any file that populates it those bytes
+ * are document content. Measured: a `CS` carrier over-declaring over the bytes
+ * `"SABC"` reports `hidden: ["41534342"]`, which is `"SABC"` in wire order.
+ * `PRE-EXISTING` and identical on every release that has shipped the field.
+ * Treat `hidden` at the sensitivity of the file, and see
+ * {@link DeidentifyReport} for the other fields in this class.
  *
  * @example
  * ```ts
@@ -2388,12 +2474,31 @@ interface EmbeddedAttributeFinding {
     readonly vr: VR;
     /** The tags of the Data Elements found inside the carrier's value, in wire order. */
     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
@@ -2412,12 +2517,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
@@ -2433,7 +2552,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[];
 }
 /**
@@ -2493,8 +2619,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
@@ -2525,24 +2657,62 @@ 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.
+ * - **`embeddedAttributes[].hidden`** - see {@link EmbeddedAttributeFinding}.
+ *   Each entry is a tag composed from four bytes that were sitting **inside**
+ *   a value, which is the position this type exists to distrust, so on a file
+ *   that populates the field at all they are document content by
+ *   construction. `PRE-EXISTING` and identical on every release that has
+ *   shipped the field; it is disclosed here and its remedy is its own slice,
+ *   alongside the cap that field is also missing.
+ * - **`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.**
  *
  * 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.
@@ -2599,9 +2769,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[];
     /**
@@ -2630,14 +2802,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[];
     /**
@@ -2692,6 +2867,19 @@ interface DeidentifyOptions {
      * Text **added to** `(0012,0063)` De-identification Method. Default names the
      * Basic Profile and the active options.
      *
+     * **The default is multi-valued, one Value per name, and that is a conformance
+     * fix rather than a style choice.** PS3.5 2026c Table 6.2-1 caps an `LO` at
+     * **64 characters per Value**, and `(0012,0063)` is `1-n`; the single-value
+     * default this replaced measured 76 characters with no options and 272 with
+     * all nine, so every run this library ever made wrote a value no `LO` may
+     * legally carry. The Profile name is now one Value of 61 characters and each
+     * active option is its own, so no option subset can exceed the maximum.
+     *
+     * **Your string is not bounded here.** A value of your own longer than 64
+     * characters is written through as given, with no warning: it is yours, and
+     * splitting or truncating it would invent a record you did not write. Split it
+     * on `\` yourself if a strict receiver is in your path.
+     *
      * PS3.15 E.1.1 says this string is "inserted in or added to" the attribute, so
      * a value the incoming Data Set already carried is kept and this one is
      * appended after a `\` as a further value of the `1-n` attribute - the
@@ -2721,7 +2909,10 @@ interface DeidentifyOptions {
      *
      * `DICOM_DEIDENT_METHOD_NOT_ADDED` means "the length ceiling was reached", never
      * "every fallback is disclosed": a `(0012,0063)` a file encoded under a VR other
-     * than `LO` is also replaced, and that one is silent.
+     * than `LO` is also replaced, and that one raises `DICOM_DEIDENT_METHOD_NOT_LO`.
+     * Two codes rather than one because the causes are unrelated - the chain outgrew
+     * the VR, or the bytes were never in that VR at all - and a prior value that is
+     * empty or padding only raises neither, because nothing was lost.
      *
      * When the prior value **is** kept, `report.warnings` carries
      * `DICOM_DEIDENT_METHOD_PRIOR_RETAINED`: `(0012,0063)` is not in Table E.1-1, so
@@ -2802,8 +2993,10 @@ 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: `uidMap`, `removedPrivateTags`,
+ * `unauditableSequences[].tag` and `embeddedAttributes[].hidden`. Read the list
+ * there, never a count quoted elsewhere.
  *
  * **What it does**
  * - Resolves each attribute's action (basic profile, overridden by an active
@@ -2840,10 +3033,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
@@ -2854,16 +3059,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
@@ -2892,12 +3099,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 =
@@ -2913,10 +3122,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
  */