@cosyte/dicom 0.0.6 → 0.0.8

package/dist/index.d.cts

@@ -415,6 +415,9 @@ declare const WARNING_CODES: {
     readonly DICOM_CHARSET_AMBIGUOUS_SEPARATOR: "DICOM_CHARSET_AMBIGUOUS_SEPARATOR";
     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_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";
 };
 /**
@@ -2348,6 +2351,178 @@ interface DeidentifiedAttribute {
      */
     readonly repeatingGroup?: string;
 }
+/**
+ * One value that was emptied because a Data Element was found **inside** it.
+ *
+ * PS3.5 defines Value Length as the length of that element's own Value Field. A
+ * sender that over-declares it produces a file whose reading is self-consistent
+ * and whose next element has been absorbed into the previous one's value - and
+ * Table E.1-1 is keyed by tag, so an absorbed `(0010,0020)` is not an attribute
+ * any longer and no action fires on it. `deidentify` therefore refuses to keep a
+ * value whose tail decodes as whole Data Elements it would have acted on
+ * (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.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom } from "@cosyte/dicom";
+ * const { report } = deidentify(parseDicom(buf));
+ * for (const e of report.embeddedAttributes) {
+ *   console.warn(`${e.tag} hid ${e.hidden.join(", ")} in its value`);
+ * }
+ * ```
+ */
+interface EmbeddedAttributeFinding {
+    /** The carrier - the element whose over-declared value held the others. */
+    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. */
+    readonly hidden: readonly Tag[];
+    /** Tag/index chain when the carrier is inside a sequence item; omitted at the root. */
+    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.
+ *
+ * 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
+ * value is never opaque bytes - it is Data Elements this run is obliged to
+ * reach. PS3.15 2026c §E.1.1 "De-identifier" states that obligation directly:
+ * an implementation claiming the Basic Application Level Confidentiality
+ * Profile "shall protect or retain all instances of the Attributes listed in
+ * [Table E.1-1], whether contained in the top level Data Set or embedded in an
+ * Item of a Sequence of Items". When the item stream cannot be enumerated the
+ * obligation cannot be discharged element by element, so it falls on the
+ * enclosing attribute - the escalation §E.1.1 itself uses for a SOP Instance
+ * UID inside a Sequence, where "the enclosing Attribute in the top-level Data
+ * Set must be encrypted in its entirety". (That sentence is written about the
+ * encrypt-and-replace mechanism for SOP Instance UIDs, not about Table E.1-1
+ * generally; it is cited here as the standard's own precedent for escalating to
+ * 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
+ * `Dataset.warnings`: `DICOM_SQ_NOT_DESCENDED` for a defined-length Implicit VR
+ * LE value whose dictionary-resolved `SQ` was not a valid item stream.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom } from "@cosyte/dicom";
+ * const { report } = deidentify(parseDicom(buf));
+ * for (const s of report.unauditableSequences) {
+ *   console.warn(`${s.tag}: ${String(s.byteLength)} bytes dropped, item stream unreadable`);
+ * }
+ * ```
+ */
+interface UnauditableSequenceFinding {
+    /** The `SQ` element that was emptied. */
+    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. */
+    readonly contextPath?: readonly string[];
+}
+/**
+ * One element that was emptied because its **on-wire VR is not one of the 34
+ * PS3.5 section 6.2 defines**, so nothing this library did to its bytes counts
+ * as decoding a Value Field.
+ *
+ * ## Why such an element exists at all
+ *
+ * Under an Explicit VR Transfer Syntax the VR is two bytes the sender wrote, and
+ * this parser trusts them (Postel's Law on the read path). The routine way two
+ * arbitrary bytes end up in a VR field is an **under**-declared Value Length
+ * upstream: the reader finishes the short value, and the leftover bytes of the
+ * value that was actually encoded are read as the next Data Element header. Tag,
+ * VR and length are then all fragments of somebody's value, and the element that
+ * genuinely followed is consumed as this fabricated element's "value".
+ *
+ * Measured on `scripts/measure-sq-bound-grid.ts`: a carrier under-declaring by 6
+ * produces `(4156,554C)` with the VR bytes `"E "`, whose value holds the source
+ * `(0010,0020)` Patient ID in full. It reaches **string** carriers exactly as it
+ * reaches binary ones, because the carrier's own VR is not what decides it.
+ *
+ * ## Why emptying, and why it is not a guess
+ *
+ * PS3.5 2026c section 6.2 requires every VR not yet defined to use the long-form
+ * Data Element Structure - "with reserved bytes after the VR and a 32-bit
+ * unsigned integer VL" - so an unrecognized VR read short-form, which is what
+ * this parser does, is by the standard's own structure rule not a reading of a
+ * Value Field. There is nothing to prove about the content: the test is a
+ * membership check against the closed 34-VR set on a field the parser already
+ * recorded, so there is no scan, no per-offset loop, and no cost that follows an
+ * attacker-chosen value length.
+ *
+ * PS3.15 2026c section E.1.1 obliges an implementation claiming the Basic
+ * Application Level Confidentiality Profile to "protect or retain all instances
+ * of the Attributes listed in [Table E.1-1]". Those instances cannot be reached
+ * inside bytes that were never a value, so the obligation falls on the carrier.
+ *
+ * **`UN` is not this.** `UN` is one of the 34, so an ordinary unknown-VR element
+ * - the Implicit VR fallback for a tag this build's dictionary does not publish,
+ * and the CP-246 shape - never reaches here. That is the line the sibling
+ * `SQ`-with-no-items rule could not draw.
+ *
+ * ## Why this finding names no tag, when every sibling finding does
+ *
+ * Because the tag **may be content**, and nothing here can tell. The paragraph
+ * above is the whole argument: when an under-declare desynchronized the reader,
+ * the four tag bytes and the two VR bytes were read out of the middle of some
+ * element's Value Field, so reporting the "tag" would republish four bytes of
+ * the document. An unrecognized VR written honestly, at a correct length, raises
+ * this same code and has an ordinary tag - **and the two are indistinguishable
+ * here**, so the tag is withheld on both routes rather than on a guess. Measured on a synthetic `ST` carrier holding
+ * `"MR BRAIN SMITHSON"`, the fabricated tag is `48544F53` - four bytes of the
+ * surname. {@link EmbeddedAttributeFinding} and
+ * {@link UnauditableSequenceFinding} may carry a tag because theirs came from a
+ * header the sender really wrote; this one may not, and the asymmetry is the
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom } from "@cosyte/dicom";
+ * const { report } = deidentify(parseDicom(buf));
+ * for (const u of report.undefinedVrElements) {
+ *   console.warn(`offset ${String(u.byteOffset)}: ${String(u.byteLength)} bytes dropped`);
+ * }
+ * ```
+ */
+interface UndefinedVrFinding {
+    /**
+     * Byte offset of the emptied element's header. **This is how the element is
+     * identified, and there is deliberately no `tag` field** - see the note above:
+     * a fabricated header's tag bytes are part of some element's value.
+     */
+    readonly byteOffset: number;
+    /**
+     * Byte length of the value field that was dropped.
+     *
+     * **An input-derived count, and on this finding specifically that is not a
+     * formality.** For the sibling findings the length came from a header the
+     * sender wrote; here the two length bytes can themselves be value bytes, like
+     * the tag bytes. What is published is the *number* they decode to, never the
+     * bytes - the same footing as every `{n}` in the warning registry, which is
+     * documented there as "an input-derived count". A number is not a rendering,
+     * and the reach is at most a character or so, but do not describe this field
+     * 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. */
+    readonly contextPath?: readonly string[];
+}
 /**
  * The audit trail returned alongside the de-identified dataset.
  *
@@ -2372,6 +2547,69 @@ interface DeidentifyReport {
     readonly attributes: readonly DeidentifiedAttribute[];
     /** Private tags removed under the Basic Profile (kept ones are omitted). */
     readonly removedPrivateTags: readonly Tag[];
+    /**
+     * Values emptied because whole Data Elements were encoded inside them by an
+     * over-declared Value Length. Empty on a well-formed file; a non-empty array
+     * means the *source* was malformed in a way that hid attributes from the
+     * action table, so treat it as a data-quality alarm on the sender as well as
+     * an audit line. See {@link EmbeddedAttributeFinding}.
+     */
+    readonly embeddedAttributes: readonly EmbeddedAttributeFinding[];
+    /**
+     * `SQ` elements emptied because the parser did not materialize their items, so
+     * the run had no Data Sets to walk and could not discharge PS3.15 §E.1.1's
+     * obligation inside them. Empty on a well-formed file; a non-empty array means
+     * content was dropped from the de-identified output, and the matching
+     * `DICOM_SQ_NOT_DESCENDED` entry on `Dataset.warnings` says why the parse
+     * refused. See {@link UnauditableSequenceFinding}.
+     *
+     * **Capped, and the cap is on the record only.** A crafted input can carry
+     * tens of thousands of un-auditable elements, so this array (and its matching
+     * warnings) stops at `MAX_UNAUDITABLE_SEQUENCE_FINDINGS`. Every un-auditable
+     * 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.
+     */
+    readonly unauditableSequences: readonly UnauditableSequenceFinding[];
+    /**
+     * Elements emptied because their on-wire VR is not one of the 34 PS3.5 §6.2
+     * defines, so their bytes are not a Value Field this library decoded and
+     * PS3.15 §E.1.1's obligation over what is inside them could not be discharged.
+     * Empty on a file conformant to **PS3.5 2026c**: a sender that writes one of
+     * the 34 VRs that edition defines never produces one, and an Implicit VR LE
+     * file **cannot** - there the VR comes from the dictionary. The edition is not
+     * pedantry: §6.2 exists precisely to say how a *future* VR will be encoded, so
+     * a file conformant to a later edition using a newly defined VR is the
+     * population that sentence exists for. (What such a file does on this
+     * library's parse path is not summarized here - it was measured and the
+     * shapes disagree.) A non-empty array
+     * means the source desynchronized the reader, usually by under-declaring a
+     * Value Length somewhere earlier. See {@link UndefinedVrFinding}.
+     *
+     * **Capped, and the cap is on the record only**, exactly as
+     * {@link DeidentifyReport.unauditableSequences} is: a crafted 1 MiB input can
+     * carry over a hundred thousand such elements, so this array and its matching
+     * warnings stop at `MAX_UNDEFINED_VR_FINDINGS`. Every one of them is still
+     * emptied; an array exactly that long means "at least this many".
+     *
+     * **A finding here names a byte offset, not a tag** - uniquely among the
+     * report's findings, and for a reason worth reading in
+     * {@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.
+     */
+    readonly undefinedVrElements: readonly UndefinedVrFinding[];
     /**
      * Source UID → replacement UID, for cross-file consistency. The **keys are
      * document values**, not composed identifiers: this is the one field of the
@@ -2529,15 +2767,43 @@ declare class DeidentifyError extends Error {
  * - 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 sequence whose `items` the parser did not materialize is kept verbatim
- *   rather than recursed, so any nested listed attributes are not de-identified.
- *   That is now a **narrow and announced** set: an undefined-length `UN` value the
- *   CP-246 descent could not read as a sequence, and a defined-length Implicit VR
- *   LE value whose resolved `SQ` turned out not to be an item stream - the latter
- *   carrying `DICOM_SQ_NOT_DESCENDED` on `ds.warnings`. It used to include
- *   **every** defined-length sequence under Implicit VR LE, silently
- *   (`DICOM-IMPLICIT-SQ-NOT-DESCENDED`, fixed after `0.0.5`). Check
- *   `ds.warnings` before treating a report as complete.
+ * - A **standard** (non-private) `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
+ *   fail-safe answer is to drop the carrier and say so
+ *   (`DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE` + `report.unauditableSequences`).
+ *   That costs content, and the trade is deliberate: it used to be *kept
+ *   verbatim*, which wrote the sender's own un-audited Data Elements - measured,
+ *   `(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.
+ * - 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
+ *   Value Length upstream produces: the reader desynchronizes, reads leftover
+ *   value bytes as a Data Element header, and the element that genuinely
+ *   followed becomes its "value" - measured carrying a `(0010,0020)` Patient ID
+ *   in full. §6.2 requires every undefined VR to be long-form, and this parser
+ *   reads it short-form, so those bytes are not a Value Field this library
+ *   decoded under any VR. See {@link hasUndefinedVr}. **Unlike the `SQ` rule
+ *   above this one has no carve-out** - it sits in `keepOrEmpty`, the only path
+ *   that keeps a value verbatim, so `RetainSafePrivate` does not exempt it.
+ * - **Still leaking, measured, and its own decision:** the over-declare swallow
+ *   into a **binary** carrier (`OB`/`OW`/`US`/`UN`), 11 grid cells at
+ *   `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`.
  *
  * @module
  */
@@ -2628,4 +2894,4 @@ interface UidRemapper {
  */
 declare function makeUidRemapper(root?: string, cache?: Map<string, string>): UidRemapper;
 
-export { type AppliedAction, CODING_SCHEME_OIDS, type CodedConcept, DEFAULT_UID_ROOT, DEIDENTIFY_ERROR_CODES, DEIDENTIFY_OPTIONS, Dataset, type DefineProfileOptions, type DeidentifiedAttribute, DeidentifyError, type DeidentifyErrorCode, type DeidentifyOption, type DeidentifyOptions, type DeidentifyReport, type DeidentifyResult, type DicomDate, type DicomDateTime, DicomParseError, type DicomParseWarning, type DicomPosition, DicomSerializeError, type DicomTime, type DicomValue, DicomValueError, index as Dictionary, Element, FATAL_CODES, type FatalCode, type FileMeta, type FileMetaRawElement, type FrameFunctionalGroups, type ImageView, Item, type OnWarningCallback, type OtherPatientId, type ParseOptions, type PatientView, type PersonName, type PersonNameGroup, type PrivateTagDefinition, type Profile, ProfileDefinitionError, type ProfilePrivateTags, type RealWorldValueMap, SERIALIZE_ERROR_CODES, Sequence, type SerializeErrorCode, type SeriesView, type StudyView, type UidRemapper, VALUE_ERROR_CODES, VERSION, type ValueErrorCode, WARNING_CODES, type WarningCode, codingSchemeOid, decodeElementValue, decodeText, defineProfile, deidentify, isKnownCharsetTerm, makeUidRemapper, parseDate, parseDateTime, parseDicom, parsePersonName, parseSpecificCharacterSet, parseTime, profiles, readCode, resolveDecoderLabel, serializeDicom };
+export { type AppliedAction, CODING_SCHEME_OIDS, type CodedConcept, DEFAULT_UID_ROOT, DEIDENTIFY_ERROR_CODES, DEIDENTIFY_OPTIONS, Dataset, type DefineProfileOptions, type DeidentifiedAttribute, DeidentifyError, type DeidentifyErrorCode, type DeidentifyOption, type DeidentifyOptions, type DeidentifyReport, type DeidentifyResult, type DicomDate, type DicomDateTime, DicomParseError, type DicomParseWarning, type DicomPosition, DicomSerializeError, type DicomTime, type DicomValue, DicomValueError, index as Dictionary, Element, type EmbeddedAttributeFinding, FATAL_CODES, type FatalCode, type FileMeta, type FileMetaRawElement, type FrameFunctionalGroups, type ImageView, Item, type OnWarningCallback, type OtherPatientId, type ParseOptions, type PatientView, type PersonName, type PersonNameGroup, type PrivateTagDefinition, type Profile, ProfileDefinitionError, type ProfilePrivateTags, type RealWorldValueMap, SERIALIZE_ERROR_CODES, Sequence, type SerializeErrorCode, type SeriesView, type StudyView, type UidRemapper, type UnauditableSequenceFinding, type UndefinedVrFinding, VALUE_ERROR_CODES, VERSION, type ValueErrorCode, WARNING_CODES, type WarningCode, codingSchemeOid, decodeElementValue, decodeText, defineProfile, deidentify, isKnownCharsetTerm, makeUidRemapper, parseDate, parseDateTime, parseDicom, parsePersonName, parseSpecificCharacterSet, parseTime, profiles, readCode, resolveDecoderLabel, serializeDicom };

package/dist/index.d.ts

@@ -415,6 +415,9 @@ declare const WARNING_CODES: {
     readonly DICOM_CHARSET_AMBIGUOUS_SEPARATOR: "DICOM_CHARSET_AMBIGUOUS_SEPARATOR";
     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_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";
 };
 /**
@@ -2348,6 +2351,178 @@ interface DeidentifiedAttribute {
      */
     readonly repeatingGroup?: string;
 }
+/**
+ * One value that was emptied because a Data Element was found **inside** it.
+ *
+ * PS3.5 defines Value Length as the length of that element's own Value Field. A
+ * sender that over-declares it produces a file whose reading is self-consistent
+ * and whose next element has been absorbed into the previous one's value - and
+ * Table E.1-1 is keyed by tag, so an absorbed `(0010,0020)` is not an attribute
+ * any longer and no action fires on it. `deidentify` therefore refuses to keep a
+ * value whose tail decodes as whole Data Elements it would have acted on
+ * (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.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom } from "@cosyte/dicom";
+ * const { report } = deidentify(parseDicom(buf));
+ * for (const e of report.embeddedAttributes) {
+ *   console.warn(`${e.tag} hid ${e.hidden.join(", ")} in its value`);
+ * }
+ * ```
+ */
+interface EmbeddedAttributeFinding {
+    /** The carrier - the element whose over-declared value held the others. */
+    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. */
+    readonly hidden: readonly Tag[];
+    /** Tag/index chain when the carrier is inside a sequence item; omitted at the root. */
+    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.
+ *
+ * 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
+ * value is never opaque bytes - it is Data Elements this run is obliged to
+ * reach. PS3.15 2026c §E.1.1 "De-identifier" states that obligation directly:
+ * an implementation claiming the Basic Application Level Confidentiality
+ * Profile "shall protect or retain all instances of the Attributes listed in
+ * [Table E.1-1], whether contained in the top level Data Set or embedded in an
+ * Item of a Sequence of Items". When the item stream cannot be enumerated the
+ * obligation cannot be discharged element by element, so it falls on the
+ * enclosing attribute - the escalation §E.1.1 itself uses for a SOP Instance
+ * UID inside a Sequence, where "the enclosing Attribute in the top-level Data
+ * Set must be encrypted in its entirety". (That sentence is written about the
+ * encrypt-and-replace mechanism for SOP Instance UIDs, not about Table E.1-1
+ * generally; it is cited here as the standard's own precedent for escalating to
+ * 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
+ * `Dataset.warnings`: `DICOM_SQ_NOT_DESCENDED` for a defined-length Implicit VR
+ * LE value whose dictionary-resolved `SQ` was not a valid item stream.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom } from "@cosyte/dicom";
+ * const { report } = deidentify(parseDicom(buf));
+ * for (const s of report.unauditableSequences) {
+ *   console.warn(`${s.tag}: ${String(s.byteLength)} bytes dropped, item stream unreadable`);
+ * }
+ * ```
+ */
+interface UnauditableSequenceFinding {
+    /** The `SQ` element that was emptied. */
+    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. */
+    readonly contextPath?: readonly string[];
+}
+/**
+ * One element that was emptied because its **on-wire VR is not one of the 34
+ * PS3.5 section 6.2 defines**, so nothing this library did to its bytes counts
+ * as decoding a Value Field.
+ *
+ * ## Why such an element exists at all
+ *
+ * Under an Explicit VR Transfer Syntax the VR is two bytes the sender wrote, and
+ * this parser trusts them (Postel's Law on the read path). The routine way two
+ * arbitrary bytes end up in a VR field is an **under**-declared Value Length
+ * upstream: the reader finishes the short value, and the leftover bytes of the
+ * value that was actually encoded are read as the next Data Element header. Tag,
+ * VR and length are then all fragments of somebody's value, and the element that
+ * genuinely followed is consumed as this fabricated element's "value".
+ *
+ * Measured on `scripts/measure-sq-bound-grid.ts`: a carrier under-declaring by 6
+ * produces `(4156,554C)` with the VR bytes `"E "`, whose value holds the source
+ * `(0010,0020)` Patient ID in full. It reaches **string** carriers exactly as it
+ * reaches binary ones, because the carrier's own VR is not what decides it.
+ *
+ * ## Why emptying, and why it is not a guess
+ *
+ * PS3.5 2026c section 6.2 requires every VR not yet defined to use the long-form
+ * Data Element Structure - "with reserved bytes after the VR and a 32-bit
+ * unsigned integer VL" - so an unrecognized VR read short-form, which is what
+ * this parser does, is by the standard's own structure rule not a reading of a
+ * Value Field. There is nothing to prove about the content: the test is a
+ * membership check against the closed 34-VR set on a field the parser already
+ * recorded, so there is no scan, no per-offset loop, and no cost that follows an
+ * attacker-chosen value length.
+ *
+ * PS3.15 2026c section E.1.1 obliges an implementation claiming the Basic
+ * Application Level Confidentiality Profile to "protect or retain all instances
+ * of the Attributes listed in [Table E.1-1]". Those instances cannot be reached
+ * inside bytes that were never a value, so the obligation falls on the carrier.
+ *
+ * **`UN` is not this.** `UN` is one of the 34, so an ordinary unknown-VR element
+ * - the Implicit VR fallback for a tag this build's dictionary does not publish,
+ * and the CP-246 shape - never reaches here. That is the line the sibling
+ * `SQ`-with-no-items rule could not draw.
+ *
+ * ## Why this finding names no tag, when every sibling finding does
+ *
+ * Because the tag **may be content**, and nothing here can tell. The paragraph
+ * above is the whole argument: when an under-declare desynchronized the reader,
+ * the four tag bytes and the two VR bytes were read out of the middle of some
+ * element's Value Field, so reporting the "tag" would republish four bytes of
+ * the document. An unrecognized VR written honestly, at a correct length, raises
+ * this same code and has an ordinary tag - **and the two are indistinguishable
+ * here**, so the tag is withheld on both routes rather than on a guess. Measured on a synthetic `ST` carrier holding
+ * `"MR BRAIN SMITHSON"`, the fabricated tag is `48544F53` - four bytes of the
+ * surname. {@link EmbeddedAttributeFinding} and
+ * {@link UnauditableSequenceFinding} may carry a tag because theirs came from a
+ * header the sender really wrote; this one may not, and the asymmetry is the
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom } from "@cosyte/dicom";
+ * const { report } = deidentify(parseDicom(buf));
+ * for (const u of report.undefinedVrElements) {
+ *   console.warn(`offset ${String(u.byteOffset)}: ${String(u.byteLength)} bytes dropped`);
+ * }
+ * ```
+ */
+interface UndefinedVrFinding {
+    /**
+     * Byte offset of the emptied element's header. **This is how the element is
+     * identified, and there is deliberately no `tag` field** - see the note above:
+     * a fabricated header's tag bytes are part of some element's value.
+     */
+    readonly byteOffset: number;
+    /**
+     * Byte length of the value field that was dropped.
+     *
+     * **An input-derived count, and on this finding specifically that is not a
+     * formality.** For the sibling findings the length came from a header the
+     * sender wrote; here the two length bytes can themselves be value bytes, like
+     * the tag bytes. What is published is the *number* they decode to, never the
+     * bytes - the same footing as every `{n}` in the warning registry, which is
+     * documented there as "an input-derived count". A number is not a rendering,
+     * and the reach is at most a character or so, but do not describe this field
+     * 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. */
+    readonly contextPath?: readonly string[];
+}
 /**
  * The audit trail returned alongside the de-identified dataset.
  *
@@ -2372,6 +2547,69 @@ interface DeidentifyReport {
     readonly attributes: readonly DeidentifiedAttribute[];
     /** Private tags removed under the Basic Profile (kept ones are omitted). */
     readonly removedPrivateTags: readonly Tag[];
+    /**
+     * Values emptied because whole Data Elements were encoded inside them by an
+     * over-declared Value Length. Empty on a well-formed file; a non-empty array
+     * means the *source* was malformed in a way that hid attributes from the
+     * action table, so treat it as a data-quality alarm on the sender as well as
+     * an audit line. See {@link EmbeddedAttributeFinding}.
+     */
+    readonly embeddedAttributes: readonly EmbeddedAttributeFinding[];
+    /**
+     * `SQ` elements emptied because the parser did not materialize their items, so
+     * the run had no Data Sets to walk and could not discharge PS3.15 §E.1.1's
+     * obligation inside them. Empty on a well-formed file; a non-empty array means
+     * content was dropped from the de-identified output, and the matching
+     * `DICOM_SQ_NOT_DESCENDED` entry on `Dataset.warnings` says why the parse
+     * refused. See {@link UnauditableSequenceFinding}.
+     *
+     * **Capped, and the cap is on the record only.** A crafted input can carry
+     * tens of thousands of un-auditable elements, so this array (and its matching
+     * warnings) stops at `MAX_UNAUDITABLE_SEQUENCE_FINDINGS`. Every un-auditable
+     * 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.
+     */
+    readonly unauditableSequences: readonly UnauditableSequenceFinding[];
+    /**
+     * Elements emptied because their on-wire VR is not one of the 34 PS3.5 §6.2
+     * defines, so their bytes are not a Value Field this library decoded and
+     * PS3.15 §E.1.1's obligation over what is inside them could not be discharged.
+     * Empty on a file conformant to **PS3.5 2026c**: a sender that writes one of
+     * the 34 VRs that edition defines never produces one, and an Implicit VR LE
+     * file **cannot** - there the VR comes from the dictionary. The edition is not
+     * pedantry: §6.2 exists precisely to say how a *future* VR will be encoded, so
+     * a file conformant to a later edition using a newly defined VR is the
+     * population that sentence exists for. (What such a file does on this
+     * library's parse path is not summarized here - it was measured and the
+     * shapes disagree.) A non-empty array
+     * means the source desynchronized the reader, usually by under-declaring a
+     * Value Length somewhere earlier. See {@link UndefinedVrFinding}.
+     *
+     * **Capped, and the cap is on the record only**, exactly as
+     * {@link DeidentifyReport.unauditableSequences} is: a crafted 1 MiB input can
+     * carry over a hundred thousand such elements, so this array and its matching
+     * warnings stop at `MAX_UNDEFINED_VR_FINDINGS`. Every one of them is still
+     * emptied; an array exactly that long means "at least this many".
+     *
+     * **A finding here names a byte offset, not a tag** - uniquely among the
+     * report's findings, and for a reason worth reading in
+     * {@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.
+     */
+    readonly undefinedVrElements: readonly UndefinedVrFinding[];
     /**
      * Source UID → replacement UID, for cross-file consistency. The **keys are
      * document values**, not composed identifiers: this is the one field of the
@@ -2529,15 +2767,43 @@ declare class DeidentifyError extends Error {
  * - 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 sequence whose `items` the parser did not materialize is kept verbatim
- *   rather than recursed, so any nested listed attributes are not de-identified.
- *   That is now a **narrow and announced** set: an undefined-length `UN` value the
- *   CP-246 descent could not read as a sequence, and a defined-length Implicit VR
- *   LE value whose resolved `SQ` turned out not to be an item stream - the latter
- *   carrying `DICOM_SQ_NOT_DESCENDED` on `ds.warnings`. It used to include
- *   **every** defined-length sequence under Implicit VR LE, silently
- *   (`DICOM-IMPLICIT-SQ-NOT-DESCENDED`, fixed after `0.0.5`). Check
- *   `ds.warnings` before treating a report as complete.
+ * - A **standard** (non-private) `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
+ *   fail-safe answer is to drop the carrier and say so
+ *   (`DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE` + `report.unauditableSequences`).
+ *   That costs content, and the trade is deliberate: it used to be *kept
+ *   verbatim*, which wrote the sender's own un-audited Data Elements - measured,
+ *   `(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.
+ * - 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
+ *   Value Length upstream produces: the reader desynchronizes, reads leftover
+ *   value bytes as a Data Element header, and the element that genuinely
+ *   followed becomes its "value" - measured carrying a `(0010,0020)` Patient ID
+ *   in full. §6.2 requires every undefined VR to be long-form, and this parser
+ *   reads it short-form, so those bytes are not a Value Field this library
+ *   decoded under any VR. See {@link hasUndefinedVr}. **Unlike the `SQ` rule
+ *   above this one has no carve-out** - it sits in `keepOrEmpty`, the only path
+ *   that keeps a value verbatim, so `RetainSafePrivate` does not exempt it.
+ * - **Still leaking, measured, and its own decision:** the over-declare swallow
+ *   into a **binary** carrier (`OB`/`OW`/`US`/`UN`), 11 grid cells at
+ *   `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`.
  *
  * @module
  */
@@ -2628,4 +2894,4 @@ interface UidRemapper {
  */
 declare function makeUidRemapper(root?: string, cache?: Map<string, string>): UidRemapper;
 
-export { type AppliedAction, CODING_SCHEME_OIDS, type CodedConcept, DEFAULT_UID_ROOT, DEIDENTIFY_ERROR_CODES, DEIDENTIFY_OPTIONS, Dataset, type DefineProfileOptions, type DeidentifiedAttribute, DeidentifyError, type DeidentifyErrorCode, type DeidentifyOption, type DeidentifyOptions, type DeidentifyReport, type DeidentifyResult, type DicomDate, type DicomDateTime, DicomParseError, type DicomParseWarning, type DicomPosition, DicomSerializeError, type DicomTime, type DicomValue, DicomValueError, index as Dictionary, Element, FATAL_CODES, type FatalCode, type FileMeta, type FileMetaRawElement, type FrameFunctionalGroups, type ImageView, Item, type OnWarningCallback, type OtherPatientId, type ParseOptions, type PatientView, type PersonName, type PersonNameGroup, type PrivateTagDefinition, type Profile, ProfileDefinitionError, type ProfilePrivateTags, type RealWorldValueMap, SERIALIZE_ERROR_CODES, Sequence, type SerializeErrorCode, type SeriesView, type StudyView, type UidRemapper, VALUE_ERROR_CODES, VERSION, type ValueErrorCode, WARNING_CODES, type WarningCode, codingSchemeOid, decodeElementValue, decodeText, defineProfile, deidentify, isKnownCharsetTerm, makeUidRemapper, parseDate, parseDateTime, parseDicom, parsePersonName, parseSpecificCharacterSet, parseTime, profiles, readCode, resolveDecoderLabel, serializeDicom };
+export { type AppliedAction, CODING_SCHEME_OIDS, type CodedConcept, DEFAULT_UID_ROOT, DEIDENTIFY_ERROR_CODES, DEIDENTIFY_OPTIONS, Dataset, type DefineProfileOptions, type DeidentifiedAttribute, DeidentifyError, type DeidentifyErrorCode, type DeidentifyOption, type DeidentifyOptions, type DeidentifyReport, type DeidentifyResult, type DicomDate, type DicomDateTime, DicomParseError, type DicomParseWarning, type DicomPosition, DicomSerializeError, type DicomTime, type DicomValue, DicomValueError, index as Dictionary, Element, type EmbeddedAttributeFinding, FATAL_CODES, type FatalCode, type FileMeta, type FileMetaRawElement, type FrameFunctionalGroups, type ImageView, Item, type OnWarningCallback, type OtherPatientId, type ParseOptions, type PatientView, type PersonName, type PersonNameGroup, type PrivateTagDefinition, type Profile, ProfileDefinitionError, type ProfilePrivateTags, type RealWorldValueMap, SERIALIZE_ERROR_CODES, Sequence, type SerializeErrorCode, type SeriesView, type StudyView, type UidRemapper, type UnauditableSequenceFinding, type UndefinedVrFinding, VALUE_ERROR_CODES, VERSION, type ValueErrorCode, WARNING_CODES, type WarningCode, codingSchemeOid, decodeElementValue, decodeText, defineProfile, deidentify, isKnownCharsetTerm, makeUidRemapper, parseDate, parseDateTime, parseDicom, parsePersonName, parseSpecificCharacterSet, parseTime, profiles, readCode, resolveDecoderLabel, serializeDicom };