@cosyte/dicom 0.0.8 → 0.0.11

package/dist/index.d.cts

@@ -391,11 +391,14 @@ interface ParseOptions {
  * ```
  */
 declare const WARNING_CODES: {
+    readonly DICOM_DUPLICATE_FILE_META_ELEMENT: "DICOM_DUPLICATE_FILE_META_ELEMENT";
+    readonly DICOM_DUPLICATE_TAG_IN_DATA_SET: "DICOM_DUPLICATE_TAG_IN_DATA_SET";
     readonly DICOM_EMPTY_ITEM_IN_SEQUENCE: "DICOM_EMPTY_ITEM_IN_SEQUENCE";
     readonly DICOM_FILE_META_GROUP_LENGTH_MISMATCH: "DICOM_FILE_META_GROUP_LENGTH_MISMATCH";
     readonly DICOM_FILE_META_GROUP_LENGTH_MISSING: "DICOM_FILE_META_GROUP_LENGTH_MISSING";
     readonly DICOM_GROUP_LENGTH_IN_DATASET: "DICOM_GROUP_LENGTH_IN_DATASET";
     readonly DICOM_IMPLICIT_VR_FOR_PRIVATE_TAG_WITHOUT_VR: "DICOM_IMPLICIT_VR_FOR_PRIVATE_TAG_WITHOUT_VR";
+    readonly DICOM_ITEM_CROSSES_SEQUENCE_END: "DICOM_ITEM_CROSSES_SEQUENCE_END";
     readonly DICOM_MISSING_PREAMBLE: "DICOM_MISSING_PREAMBLE";
     readonly DICOM_NONZERO_RESERVED_BYTES: "DICOM_NONZERO_RESERVED_BYTES";
     readonly DICOM_ODD_LENGTH_VALUE_PADDED: "DICOM_ODD_LENGTH_VALUE_PADDED";
@@ -416,6 +419,8 @@ declare const WARNING_CODES: {
     readonly DICOM_UNSUPPORTED_CHARSET: "DICOM_UNSUPPORTED_CHARSET";
     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_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";
     readonly DICOM_PRIVATE_CREATOR_UNKNOWN: "DICOM_PRIVATE_CREATOR_UNKNOWN";
@@ -2526,13 +2531,21 @@ interface UndefinedVrFinding {
 /**
  * The audit trail returned alongside the de-identified dataset.
  *
- * Every field except one is composed from static tables: tags, Part 6 keywords,
- * Annex E action codes, structural `TAG[index]` sequence paths, and registry
- * warning messages. **`uidMap` is the exception, and it is not value-free.** 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 `uidMap` as PHI: the rest of the
- * report is safe to log, and that field is not.
+ * 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.
+ *
+ * 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.
  *
  * @example
  * ```ts
@@ -2545,7 +2558,24 @@ interface UndefinedVrFinding {
 interface DeidentifyReport {
     /** Per-attribute outcomes for every attribute Annex E acted on. */
     readonly attributes: readonly DeidentifiedAttribute[];
-    /** Private tags removed under the Basic Profile (kept ones are omitted). */
+    /**
+     * Private tags removed under the Basic Profile (kept ones are omitted).
+     *
+     * **This is the second field that is not value-free, and the qualification is
+     * measured.** A tag here is composed from four bytes of the source, and on a
+     * file whose Value Lengths disagree with its bytes those four bytes can be
+     * document content rather than a tag the sender wrote: an `OB` carrier holding
+     * `"SECRET-NOTE-"` followed by a well-formed odd-group header reports
+     * `["41534342"]`, whose wire-order bytes read `"SABC"`. That reproduces
+     * identically on every release that has shipped this field.
+     *
+     * It is reported anyway, because *which* private tags were removed is the
+     * whole audit value of the field and withholding them would destroy it on
+     * every well-formed file to bound a malformed one. Narrowing it - to blocks a
+     * creator in the same Data Set actually reserved, say - is a product decision
+     * about audit value versus a four-byte echo, not a defect fix, and it has not
+     * been made. Treat this array as PHI when the source is untrusted.
+     */
     readonly removedPrivateTags: readonly Tag[];
     /**
      * Values emptied because whole Data Elements were encoded inside them by an
@@ -2618,7 +2648,15 @@ interface DeidentifyReport {
     readonly uidMap: ReadonlyMap<string, string>;
     /** Safety warnings - notably burned-in-pixel annotation that cannot be cleaned. */
     readonly warnings: readonly DicomParseWarning[];
-    /** The Retain/Clean options that were active for this run. */
+    /**
+     * The Retain/Clean options that were active for this run.
+     *
+     * **Not a list of what survived.** Attributes Table E.1-1 does not list are
+     * kept without appearing anywhere in this field - `(0012,0063)`
+     * De-identification Method is the one whose retention is disclosed, and it is
+     * disclosed as `DICOM_DEIDENT_METHOD_PRIOR_RETAINED` on
+     * {@link DeidentifyReport.warnings}, because it is not an option set.
+     */
     readonly retained: readonly DeidentifyOption[];
 }
 /**
@@ -2651,8 +2689,44 @@ interface DeidentifyOptions {
      */
     readonly profile?: Profile;
     /**
-     * Text written to `(0012,0063)` De-identification Method. Default names the
+     * Text **added to** `(0012,0063)` De-identification Method. Default names the
      * Basic Profile and the active options.
+     *
+     * 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
+     * provenance chain, not a replacement.
+     *
+     * **This string is itself a `1-n` value**: it is split on `\` and only the
+     * values not already recorded are added.
+     *
+     * **Trailing SPACE and NUL are padding, not content** (PS3.5 Table 6.2-1's `LO`
+     * row, which describes a **Value** - and `LO` is `1-n`). They are ignored when
+     * a value here is matched against one already recorded, **per value, on both
+     * sides**, and they are trimmed from the value written. That makes repeated
+     * de-identification a fixed point **from the first pass**, for every string:
+     * with or without a delimiter, and with a pad byte on any value, last or not.
+     * A string that is padding only records nothing. Leading spaces are yours and
+     * are written through untouched.
+     *
+     * One bound, and it is over the value that would be **written**, not over the
+     * join: when that value would exceed the largest Value Length an `LO` can
+     * encode, the prior value is **replaced** rather than added to - an element the
+     * serializer cannot encode would take the whole de-identified object down - and
+     * `report.warnings` carries `DICOM_DEIDENT_METHOD_NOT_ADDED`. That includes a
+     * prior value already at the ceiling which records this method already, where
+     * there is no join to exceed anything. A string longer than that ceiling on its
+     * own is not bounded here and will fail to serialize, exactly as it did before
+     * this option grew a join.
+     *
+     * `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.
+     *
+     * When the prior value **is** kept, `report.warnings` carries
+     * `DICOM_DEIDENT_METHOD_PRIOR_RETAINED`: `(0012,0063)` is not in Table E.1-1, so
+     * nothing in the run inspected or redacted those bytes, and a name a sender
+     * wrote there is in output stamped `(0012,0062) = YES`.
      */
     readonly deidentificationMethod?: string;
 }
@@ -2728,8 +2802,8 @@ 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} that is value-free except for
- * `uidMap`, whose keys are the file's own source UIDs.
+ * is returned alongside a {@link DeidentifyReport} whose two non-value-free
+ * fields are named on that type: `uidMap` and `removedPrivateTags`.
  *
  * **What it does**
  * - Resolves each attribute's action (basic profile, overridden by an active
@@ -2750,8 +2824,10 @@ declare class DeidentifyError extends Error {
  *   {@link Profile}, keeps the private data elements the profile's overlay names
  *   as safe (and the private-creator elements the profile recognizes).
  * - Remaps `(0002,0003)` Media Storage SOP Instance UID consistently (unless
- *   `RetainUIDs`), writes `(0012,0062)` Patient Identity Removed = `YES` and
- *   `(0012,0063)` De-identification Method, and warns
+ *   `RetainUIDs`), writes `(0012,0062)` Patient Identity Removed = `YES`, **adds**
+ *   its method text to `(0012,0063)` De-identification Method rather than
+ *   replacing what the file already recorded there (PS3.15 E.1.1 - see
+ *   `addDeidentificationMethod`), and warns
  *   (`DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED`) when Pixel Data is present and not
  *   marked free of burned-in annotation - this metadata-only pass cannot clean
  *   pixels (deferred to `@cosyte/dicom-pixel`).
@@ -2804,6 +2880,43 @@ declare class DeidentifyError extends Error {
  *   `35adc2d`. No content test can decide it - arbitrary bytes are what those
  *   VRs are for - and the one candidate remedy empties conformant binary values.
  *   See `./embedded.ts`.
+ * - `RetainSafePrivate` **retains nothing inside a Sequence Item whose Data Set
+ *   boundary the file contradicts** - an item stream that ran past its
+ *   sequence's own declared Value Length. Which elements are in the Item is then
+ *   not determined by the file, and PS3.5 §7.8.1 scopes a private block
+ *   reservation to exactly that boundary, so PS3.15 §E.3.10's "known ... to be
+ *   safe" cannot be established and its "all other Private Attributes shall be
+ *   removed **or processed in the element-specific manner recommended by
+ *   Deidentification Action (0008,0307), if present within Private Data Element
+ *   Characteristics Sequence (0008,0300)**" applies - a two-branch clause, of
+ *   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
+ *   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 =
+ *   YES` with `removedPrivateTags: []` (`DICOM-PRIVATE-CREATOR-RESERVATION-LEAK`,
+ *   measured on the published `0.0.8` tarball and fixed on `0.0.10`; there is no `0.0.9` on
+ *   the registry). See {@link itemStreamOverrunsSequence}.
+ * - `RetainSafePrivate` **retains nothing that a Data Set holds after a sequence
+ *   whose own contents contradict the extent it declared** - the mirror
+ *   direction, where an Item that *under*-declares **ejects** its trailing
+ *   elements out and a Private Creator landing in the enclosing Data Set reserves
+ *   a block for elements the sender never put beside it. The same false
+ *   attestation, and it applies **in every Data Set, not just the root**: an
+ *   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}.
  *
  * @module
  */

package/dist/index.d.ts

@@ -391,11 +391,14 @@ interface ParseOptions {
  * ```
  */
 declare const WARNING_CODES: {
+    readonly DICOM_DUPLICATE_FILE_META_ELEMENT: "DICOM_DUPLICATE_FILE_META_ELEMENT";
+    readonly DICOM_DUPLICATE_TAG_IN_DATA_SET: "DICOM_DUPLICATE_TAG_IN_DATA_SET";
     readonly DICOM_EMPTY_ITEM_IN_SEQUENCE: "DICOM_EMPTY_ITEM_IN_SEQUENCE";
     readonly DICOM_FILE_META_GROUP_LENGTH_MISMATCH: "DICOM_FILE_META_GROUP_LENGTH_MISMATCH";
     readonly DICOM_FILE_META_GROUP_LENGTH_MISSING: "DICOM_FILE_META_GROUP_LENGTH_MISSING";
     readonly DICOM_GROUP_LENGTH_IN_DATASET: "DICOM_GROUP_LENGTH_IN_DATASET";
     readonly DICOM_IMPLICIT_VR_FOR_PRIVATE_TAG_WITHOUT_VR: "DICOM_IMPLICIT_VR_FOR_PRIVATE_TAG_WITHOUT_VR";
+    readonly DICOM_ITEM_CROSSES_SEQUENCE_END: "DICOM_ITEM_CROSSES_SEQUENCE_END";
     readonly DICOM_MISSING_PREAMBLE: "DICOM_MISSING_PREAMBLE";
     readonly DICOM_NONZERO_RESERVED_BYTES: "DICOM_NONZERO_RESERVED_BYTES";
     readonly DICOM_ODD_LENGTH_VALUE_PADDED: "DICOM_ODD_LENGTH_VALUE_PADDED";
@@ -416,6 +419,8 @@ declare const WARNING_CODES: {
     readonly DICOM_UNSUPPORTED_CHARSET: "DICOM_UNSUPPORTED_CHARSET";
     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_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";
     readonly DICOM_PRIVATE_CREATOR_UNKNOWN: "DICOM_PRIVATE_CREATOR_UNKNOWN";
@@ -2526,13 +2531,21 @@ interface UndefinedVrFinding {
 /**
  * The audit trail returned alongside the de-identified dataset.
  *
- * Every field except one is composed from static tables: tags, Part 6 keywords,
- * Annex E action codes, structural `TAG[index]` sequence paths, and registry
- * warning messages. **`uidMap` is the exception, and it is not value-free.** 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 `uidMap` as PHI: the rest of the
- * report is safe to log, and that field is not.
+ * 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.
+ *
+ * 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.
  *
  * @example
  * ```ts
@@ -2545,7 +2558,24 @@ interface UndefinedVrFinding {
 interface DeidentifyReport {
     /** Per-attribute outcomes for every attribute Annex E acted on. */
     readonly attributes: readonly DeidentifiedAttribute[];
-    /** Private tags removed under the Basic Profile (kept ones are omitted). */
+    /**
+     * Private tags removed under the Basic Profile (kept ones are omitted).
+     *
+     * **This is the second field that is not value-free, and the qualification is
+     * measured.** A tag here is composed from four bytes of the source, and on a
+     * file whose Value Lengths disagree with its bytes those four bytes can be
+     * document content rather than a tag the sender wrote: an `OB` carrier holding
+     * `"SECRET-NOTE-"` followed by a well-formed odd-group header reports
+     * `["41534342"]`, whose wire-order bytes read `"SABC"`. That reproduces
+     * identically on every release that has shipped this field.
+     *
+     * It is reported anyway, because *which* private tags were removed is the
+     * whole audit value of the field and withholding them would destroy it on
+     * every well-formed file to bound a malformed one. Narrowing it - to blocks a
+     * creator in the same Data Set actually reserved, say - is a product decision
+     * about audit value versus a four-byte echo, not a defect fix, and it has not
+     * been made. Treat this array as PHI when the source is untrusted.
+     */
     readonly removedPrivateTags: readonly Tag[];
     /**
      * Values emptied because whole Data Elements were encoded inside them by an
@@ -2618,7 +2648,15 @@ interface DeidentifyReport {
     readonly uidMap: ReadonlyMap<string, string>;
     /** Safety warnings - notably burned-in-pixel annotation that cannot be cleaned. */
     readonly warnings: readonly DicomParseWarning[];
-    /** The Retain/Clean options that were active for this run. */
+    /**
+     * The Retain/Clean options that were active for this run.
+     *
+     * **Not a list of what survived.** Attributes Table E.1-1 does not list are
+     * kept without appearing anywhere in this field - `(0012,0063)`
+     * De-identification Method is the one whose retention is disclosed, and it is
+     * disclosed as `DICOM_DEIDENT_METHOD_PRIOR_RETAINED` on
+     * {@link DeidentifyReport.warnings}, because it is not an option set.
+     */
     readonly retained: readonly DeidentifyOption[];
 }
 /**
@@ -2651,8 +2689,44 @@ interface DeidentifyOptions {
      */
     readonly profile?: Profile;
     /**
-     * Text written to `(0012,0063)` De-identification Method. Default names the
+     * Text **added to** `(0012,0063)` De-identification Method. Default names the
      * Basic Profile and the active options.
+     *
+     * 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
+     * provenance chain, not a replacement.
+     *
+     * **This string is itself a `1-n` value**: it is split on `\` and only the
+     * values not already recorded are added.
+     *
+     * **Trailing SPACE and NUL are padding, not content** (PS3.5 Table 6.2-1's `LO`
+     * row, which describes a **Value** - and `LO` is `1-n`). They are ignored when
+     * a value here is matched against one already recorded, **per value, on both
+     * sides**, and they are trimmed from the value written. That makes repeated
+     * de-identification a fixed point **from the first pass**, for every string:
+     * with or without a delimiter, and with a pad byte on any value, last or not.
+     * A string that is padding only records nothing. Leading spaces are yours and
+     * are written through untouched.
+     *
+     * One bound, and it is over the value that would be **written**, not over the
+     * join: when that value would exceed the largest Value Length an `LO` can
+     * encode, the prior value is **replaced** rather than added to - an element the
+     * serializer cannot encode would take the whole de-identified object down - and
+     * `report.warnings` carries `DICOM_DEIDENT_METHOD_NOT_ADDED`. That includes a
+     * prior value already at the ceiling which records this method already, where
+     * there is no join to exceed anything. A string longer than that ceiling on its
+     * own is not bounded here and will fail to serialize, exactly as it did before
+     * this option grew a join.
+     *
+     * `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.
+     *
+     * When the prior value **is** kept, `report.warnings` carries
+     * `DICOM_DEIDENT_METHOD_PRIOR_RETAINED`: `(0012,0063)` is not in Table E.1-1, so
+     * nothing in the run inspected or redacted those bytes, and a name a sender
+     * wrote there is in output stamped `(0012,0062) = YES`.
      */
     readonly deidentificationMethod?: string;
 }
@@ -2728,8 +2802,8 @@ 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} that is value-free except for
- * `uidMap`, whose keys are the file's own source UIDs.
+ * is returned alongside a {@link DeidentifyReport} whose two non-value-free
+ * fields are named on that type: `uidMap` and `removedPrivateTags`.
  *
  * **What it does**
  * - Resolves each attribute's action (basic profile, overridden by an active
@@ -2750,8 +2824,10 @@ declare class DeidentifyError extends Error {
  *   {@link Profile}, keeps the private data elements the profile's overlay names
  *   as safe (and the private-creator elements the profile recognizes).
  * - Remaps `(0002,0003)` Media Storage SOP Instance UID consistently (unless
- *   `RetainUIDs`), writes `(0012,0062)` Patient Identity Removed = `YES` and
- *   `(0012,0063)` De-identification Method, and warns
+ *   `RetainUIDs`), writes `(0012,0062)` Patient Identity Removed = `YES`, **adds**
+ *   its method text to `(0012,0063)` De-identification Method rather than
+ *   replacing what the file already recorded there (PS3.15 E.1.1 - see
+ *   `addDeidentificationMethod`), and warns
  *   (`DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED`) when Pixel Data is present and not
  *   marked free of burned-in annotation - this metadata-only pass cannot clean
  *   pixels (deferred to `@cosyte/dicom-pixel`).
@@ -2804,6 +2880,43 @@ declare class DeidentifyError extends Error {
  *   `35adc2d`. No content test can decide it - arbitrary bytes are what those
  *   VRs are for - and the one candidate remedy empties conformant binary values.
  *   See `./embedded.ts`.
+ * - `RetainSafePrivate` **retains nothing inside a Sequence Item whose Data Set
+ *   boundary the file contradicts** - an item stream that ran past its
+ *   sequence's own declared Value Length. Which elements are in the Item is then
+ *   not determined by the file, and PS3.5 §7.8.1 scopes a private block
+ *   reservation to exactly that boundary, so PS3.15 §E.3.10's "known ... to be
+ *   safe" cannot be established and its "all other Private Attributes shall be
+ *   removed **or processed in the element-specific manner recommended by
+ *   Deidentification Action (0008,0307), if present within Private Data Element
+ *   Characteristics Sequence (0008,0300)**" applies - a two-branch clause, of
+ *   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
+ *   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 =
+ *   YES` with `removedPrivateTags: []` (`DICOM-PRIVATE-CREATOR-RESERVATION-LEAK`,
+ *   measured on the published `0.0.8` tarball and fixed on `0.0.10`; there is no `0.0.9` on
+ *   the registry). See {@link itemStreamOverrunsSequence}.
+ * - `RetainSafePrivate` **retains nothing that a Data Set holds after a sequence
+ *   whose own contents contradict the extent it declared** - the mirror
+ *   direction, where an Item that *under*-declares **ejects** its trailing
+ *   elements out and a Private Creator landing in the enclosing Data Set reserves
+ *   a block for elements the sender never put beside it. The same false
+ *   attestation, and it applies **in every Data Set, not just the root**: an
+ *   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}.
  *
  * @module
  */