@cosyte/dicom 0.0.10 → 0.0.12

package/dist/index.d.cts

@@ -307,6 +307,26 @@ 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`.
+     * **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
+     * `err.snippet` as PHI.
+     *
      * Omit (do not pass `undefined`) to use the default.
      */
     readonly strict?: boolean;
@@ -391,11 +411,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 +439,9 @@ 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_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";
     readonly DICOM_PRIVATE_CREATOR_UNKNOWN: "DICOM_PRIVATE_CREATOR_UNKNOWN";
@@ -2643,7 +2669,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[];
 }
 /**
@@ -2676,8 +2710,60 @@ 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.
+     *
+     * **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
+     * 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 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
+     * 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;
 }
@@ -2775,8 +2861,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`).
@@ -2851,7 +2939,21 @@ declare class DeidentifyError extends Error {
  *   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`,
- *   live through `0.0.9`). See {@link itemStreamOverrunsSequence}.
+ *   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

@@ -307,6 +307,26 @@ 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`.
+     * **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
+     * `err.snippet` as PHI.
+     *
      * Omit (do not pass `undefined`) to use the default.
      */
     readonly strict?: boolean;
@@ -391,11 +411,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 +439,9 @@ 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_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";
     readonly DICOM_PRIVATE_CREATOR_UNKNOWN: "DICOM_PRIVATE_CREATOR_UNKNOWN";
@@ -2643,7 +2669,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[];
 }
 /**
@@ -2676,8 +2710,60 @@ 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.
+     *
+     * **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
+     * 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 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
+     * 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;
 }
@@ -2775,8 +2861,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`).
@@ -2851,7 +2939,21 @@ declare class DeidentifyError extends Error {
  *   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`,
- *   live through `0.0.9`). See {@link itemStreamOverrunsSequence}.
+ *   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
  */