@cosyte/dicom 0.0.6 → 0.0.7

package/CHANGELOG.md

@@ -6,6 +6,182 @@ All notable changes to `@cosyte/dicom` will be documented in this file. The form
 
 ### Security
 
+- **An element whose on-wire VR is not one of the 34 PS3.5 §6.2 defines was kept verbatim by
+  `deidentify()`, carrying a source `(0010,0020)` Patient ID into de-identified output next to the
+  `(0012,0062) PatientIdentityRemoved = YES` this library writes** (`DICOM-CARRIER-LEAF-LEAKS`,
+  mechanism 2; pre-existing, live on the published `0.0.6`, identical on both trees). Re-derived on
+  `scripts/measure-sq-bound-grid.ts` at `35adc2d` before anything changed: **19 leaking cells → 11**.
+  Negative control first - the grid run against `d1031f5`'s `src/` restored **1,174** leaking cells
+  and reproduced `#54`'s published 2,448-cell cost - plus a second control confirming the harness
+  fails outright when pointed at another package.
+
+  **This is the _under_-declare, not the swallow the entry below closed.** An under-declared Value
+  Length desynchronizes the reader: it finishes the short value early, reads the leftover bytes of
+  the value that was actually encoded as the next Data Element header, and consumes the element that
+  genuinely followed as that fabricated element's "value". Measured: a 14-byte carrier
+  under-declaring by 6 yields tag `(4156,554C)` with the VR bytes `"E "`, holding the Patient ID in
+  full, **silently** and with a clean report. It reaches **string** carriers as readily as binary
+  ones, so it is not bounded by the binary-VR story that frames the residual below.
+
+  **The remedy reads a field the parser already recorded, not the bytes.** PS3.5 2026c §6.2: "All
+  new VRs defined in future versions of DICOM shall be of the same Data Element Structure as defined
+  in [§7.1.2] with reserved bytes after the VR and a 32-bit unsigned integer VL". An unrecognized VR
+  is long-form by that rule while this parser reads it short-form (Postel's Law on the read path), so
+  its bytes are not a Value Field this library decoded under any VR and PS3.15 2026c §E.1.1's
+  obligation cannot be discharged inside them. Read from the vendored SHA-pinned documents, pins
+  re-derived, each sentence unique in its document. Such an element is **emptied**,
+  `report.undefinedVrElements` names the **byte offset** and the byte length dropped, and the new
+  `DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE` is raised. **The finding names no tag, uniquely among
+  the report's findings**: the header _may_ have been fabricated out of the middle of some element's
+  value, in which case its four tag bytes are document content - on a synthetic `ST` carrier holding
+  `"MR BRAIN SMITHSON"` the tag renders as `48544F53`, four letters of the surname. An honestly
+  written unrecognized VR raises the same code with an ordinary tag, and the two are
+  indistinguishable here, so the tag is withheld either way.
+  `renderTag` shape-checks a tag and cannot refuse one, so the withholding happens at the call site.
+  An undefined-VR carrier whose bytes happened to tile was reported in `report.embeddedAttributes`
+  before and now reports here instead. The test is a set-membership check on
+  `el.vr`: O(1), **no scan**. The record is **capped at 64 across the run** and the emptying never is
+  - an undefined-VR element costs an attacker only an 8-byte header, so 1 MiB is 131,072 of them.
+
+  **No carve-out, and structurally so:** `keepOrEmpty` is the only path that keeps a source value
+  verbatim and the test sits at its top, so `RetainSafePrivate` does not exempt an element - pinned
+  by a test. **`UN` is untouched**, being one of the 34, and the rule cannot fire under Implicit VR
+  LE at all, where the VR comes from the dictionary; 0 Implicit VR LE cells moved.
+
+  **Cost, published rather than described:** 23 grid cells lose a marker from de-identified output,
+  **15 of which were not leaking**. On a file conformant to PS3.5 2026c the cost is zero.
+
+  **The root cause is a parse behaviour this slice does not touch, and it is disclosed rather than
+  implied fixed.** §6.2's note says informatively that an unrecognized VR may be handled "by applying
+  the rules stated in [§7.1.2]" - i.e. read long-form, value copied unchanged. This parser reads it
+  **short-form**. Emptying at the de-identify boundary is therefore compensation, not conformance.
+  `PRE-EXISTING`, its own slice. No claim is made here about what a §6.2-conformant future-VR file
+  does on either tree.
+
+  **Still leaking, measured, and now priced:** the 11 remaining cells are the over-declare swallow
+  into a **binary** carrier at `delta=18`. The one candidate remedy was built and measured - it
+  takes 11 to 0 and empties **all 5** conformant binary tiling controls, i.e. deletes a legal
+  `OB`/`UN` value because 8 of its bytes read as a zero-length `(0010,0020)`. That is a product
+  decision, not a bug fix, and it has its own item.
+
+- **A sequence the parser could not open was passed through `deidentify()` as raw bytes, so a
+  `(0010,0020)` Patient ID inside it reached de-identified output next to the
+  `(0012,0062) PatientIdentityRemoved = YES` this library writes** (`DICOM-DEIDENT-RAWBYTES-PASSTHROUGH`,
+  pre-existing and live on the published `0.0.6`). It is the larger half of the 2,127 leaking grid
+  cells the previous entry decomposed: **1,155 of the 6,348 cells that parse**, all Implicit VR LE,
+  all carrying exactly `["DICOM_SQ_NOT_DESCENDED"]`. Re-measured before anything was changed, with a
+  negative control (reverting the previous entry's call site restored exactly 2,127) so the harness
+  is known live rather than assumed.
+
+  When an element resolves to `SQ` from PS3.6 under Implicit VR LE and its defined-length value is
+  not a valid `(FFFE,E000)` item stream, the parser refuses the descent and keeps the declared span
+  on `Element.rawBytes` with `Element.items` undefined. That is right for a parser. It was not safe
+  for `deidentify()`, which recurses only into a sequence whose items exist: for a carrier such as
+  `(0008,1115)` with no Table E.1-1 row, the action table resolved "keep" and the span was re-emitted
+  verbatim, with the report naming nothing.
+
+  **The remedy reads the parser's recorded refusal, not the bytes.** PS3.5 2026c §7.5.1 "Item
+  Encoding Rules" states "Each Item Value shall contain a DICOM Data Set composed of Data Elements",
+  so an `SQ` value is never legitimately opaque the way an `OB` value is; PS3.15 2026c §E.1.1
+  "De-identifier" obliges an implementation claiming the Basic Profile to "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". Unable to enumerate the items, the obligation falls on
+  the carrier, which is the escalation §E.1.1 itself makes for a SOP Instance UID inside a Sequence.
+  Both sentences read from the vendored SHA-pinned documents, pins re-derived, each unique in its
+  document. A **standard** `SQ` with no items is therefore **emptied**,
+  `report.unauditableSequences` names the tag and the byte length dropped, and the new
+  `DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE` is raised. That record is **capped at 64 across the run**
+  (element count is attacker-chosen too, and `#48` bound every other consumer-controlled
+  diagnostic); the **emptying is never capped**, so an array exactly 64 long means "at least 64". A
+  listed sequence kept by a Retain Option takes the same branch and its audit line now reads
+  `emptied` rather than `kept` - previously it produced an empty sequence anyway while claiming the
+  attribute was retained.
+
+  **It costs content, and the number is published rather than described:** 2,448 grid cells lose a
+  value from their de-identified output, of which **1,293 were not leaking anything** and pay purely
+  for the guarantee. The accompanying `DICOM_SQ_NOT_DESCENDED` says why the parse refused, which is
+  _usually_ a sender defect - but **not always**: a conformant file nested deeper than this
+  library's own `NESTING_DEPTH_LIMIT` of 64 (ours; PS3.5 sets no nesting bound) is refused the same
+  way and loses that sequence too. Because the trigger is `items === undefined` rather than a
+  content test there is no scan, so no cost follows an attacker-chosen value length; the cost tests
+  use a carrier where **every even offset** is a tiling candidate and assert that property rather
+  than describing it, as a **forward tripwire** - this path never traverses those bytes.
+
+  **New surface:** `UnauditableSequenceFinding`, `DeidentifyReport.unauditableSequences`, and
+  `DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE` (**27 Tier-2 codes, was 26**; snapshot updated
+  deliberately). `DICOM_SQ_NOT_DESCENDED`'s message changed, since it said nested content was
+  invisible to de-identification.
+
+  **Not covered, and one of these is measured here for the first time.** An undefined-length `UN`
+  whose CP-246 descent was refused keeps `vr === "UN"`, and the rule cannot be extended to it because
+  every ordinary `UN` element also has no items - measured on a hand-built file, the identifier still
+  reaches output with no report entry. A **private** `SQ` under `RetainSafePrivate` plus a `Profile`
+  is still kept verbatim, deliberately - `keepsPrivate` decides first, so it never reaches this rule,
+  and measured on a synthetic vendor block the identifier does still reach output. Both carve-outs
+  are pinned by tests. And the **binary-VR carrier** residual the previous entry
+  disclosed but could not measure now has a number: the grid gained an over-declaring **leaf**
+  carrier dimension and finds **19 leaking cells, identical on both trees** - 11 at `delta=18` (the
+  swallow into `OB`/`OW`/`US`/`UN`, silent, with `LO`/`ST` controls on the identical fixture at 0)
+  and 8 at `delta=-6` (an _under_-declare, where leftover bytes are read as a Data Element header and
+  the identifier lands in a manufactured element with an unknown on-wire VR; this one hits string
+  carriers too and was not previously disclosed anywhere).
+
+  **Measured, on the now 76,599-cell grid against `d1031f5`:** sequence-sweep leaks 1,155 → **0**;
+  **0 cells differing in any parse respect**, now a printed count rather than an inference from
+  `changed`, because no parser file is touched; 0 new fatals, 0 lost parse values, 0 reports that
+  lose an attribute, 0 new strict fatals.
+
+- **An element that over-declared its own Value Length swallowed the next element into its value,
+  where the PS3.15 Annex E action table cannot see it, and `deidentify()` wrote the identifier into
+  its output with a clean report** (`DICOM-OVERDECLARE-SWALLOWS-INTO-VALUE`, pre-existing and live
+  on the published `0.0.6`). **No sequence is involved.** PS3.5 2026c defines Value Length as "The
+  length of the Value Field of the Data Element" - that element's own value. A sender that writes a
+  larger number produces a file that is not detectably broken: the reader consumes the declared
+  count, the bytes it over-consumes are the following element header and all, every subsequent
+  offset still lines up, and nothing on the wire says which length field lied. After the swallow
+  there is no `(0010,0020)` in the object for Table E.1-1 to match, only bytes inside some other
+  attribute's value, so de-identification passed over PHI it never recognised as an attribute.
+  Measured on the committed grid at `244a372`: **877 of the 6,348 cells that parse** wrote a source
+  value into de-identified output this way, on Explicit VR LE and Explicit VR BE, **871 of them with
+  no warning on either channel and no throw under `{ strict: true }`**.
+
+  **`parseDicom` is unchanged, deliberately.** The two readings - "the length is right and the value
+  is odd" and "the length lied and the next element was absorbed" - produce identical bytes, so a
+  parser cannot choose between them and this release does not pretend to. `deidentify()` answers a
+  strictly narrower question, and only about values it was about to **keep**: does this value's tail
+  decode, in the file's own transfer syntax, as a complete run of Data Elements ending exactly at the
+  end of the value, at least one of which this run would have acted on, and containing a byte the
+  carrier's VR cannot legally hold (PS3.5 §6.1.3 and Table 6.1-1 permit five C0 control characters in
+  DICOM text; **Table 6.2-1 decides which of the five each VR may hold**, in three tiers)? All three have to hold. If they do, the value is **emptied**
+  rather than kept, a new `DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED` warning appears on
+  `report.warnings`, and the new `report.embeddedAttributes` names the carrier, its VR and the tags
+  that were hiding inside it. PS3.15 §E.1 requires a de-identifier to "protect or retain all
+  instances of the Attributes listed in [Table E.1-1]"; §E.3.5 is the standard's own statement that
+  identifying information embedded **inside a string attribute's value** is in scope for removal.
+  Emptying is the fail-safe direction; keeping is not.
+
+  **What this does not cover, stated rather than implied.** Carriers are **string VRs only**, and the
+  residual is live rather than theoretical: the identical over-declare into an `OB`, `OW`, `UN` or
+  `US` carrier still writes the identifier into de-identified output, with **no warning and no report
+  entry**, exactly as before. Arbitrary bytes are what those VRs are for, so no content test can tell
+  a swallow from a legitimate value there, and scanning them would trade a measured guarantee for a
+  coin-flip that deletes real pixel and lookup-table data. The committed grid never puts a binary VR
+  in the over-declaring role, so this residual is **disclosed but unmeasured** and needs its own
+  item. (It was measured later in this same release cycle, by the entry above: **19 grid cells**,
+  once the grid gained an over-declaring leaf carrier.) A sequence the
+  parser declined to descend and kept as opaque bytes is a **different** defect with a different
+  remedy and is untouched here (1,155 grid cells, all Implicit VR LE, all carrying
+  `DICOM_SQ_NOT_DESCENDED`). And nothing here recovers the correct reading of a malformed file: the
+  carrier's parsed value still holds the absorbed bytes, and `ds.get("00100020")` still returns
+  nothing. This closes the leak, not the mis-read.
+
+  **Measured, on the same 76,293-cell grid, against `244a372`:** 2,127 leaking cells → 1,155; every
+  Explicit VR cell → **0**; and **0 cells whose parse differs in any respect** - reading, both
+  warning channels, `{ strict: true }`, and which values survive anywhere in the object are
+  byte-identical, because no parser file is touched. 0 new fatals, 0 lost values, 0 reports that lose
+  an attribute. `scripts/measure-sq-bound-grid.ts`, previously only on an unmerged branch, is
+  committed so every figure above is one command away.
+
 - **A defined-length sequence under Implicit VR Little Endian was never opened, so PHI nested inside
   one survived `deidentify()` into serialized output while the report said it had been removed**
   (`DICOM-IMPLICIT-SQ-NOT-DESCENDED`, pre-existing and live on the published `0.0.5`). The
@@ -249,6 +425,18 @@ All notable changes to `@cosyte/dicom` will be documented in this file. The form
 
 ### Added
 
+- **`UndefinedVrFinding`, `DeidentifyReport.undefinedVrElements` and
+  `DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE`** (**28 Tier-2 codes, was 27**; the locked
+  `WARNING_CODES` snapshot was updated deliberately). `MAX_UNDEFINED_VR_FINDINGS` (64) caps the
+  record, never the emptying.
+
+- **A conformant-tiling control family in `scripts/measure-sq-bound-grid.ts`**
+  (`LEGIT_TILING_CARRIERS`) plus the `conformant tiling control emptied` counters in `--diff`. It
+  exists to price the remaining binary-carrier leak, which `LEAKING` structurally cannot: a rule that
+  empties every binary value whose tail tiles reads as `11 → 0` there and says nothing about what it
+  destroyed. Restricted to stride-0 VRs, because `buildDicom` byte-swaps `OW`/`US` values under
+  Explicit VR BE - a first draft included them and read 9 emptied rows where the honest number was 6.
+
 - **`DICOM_SQ_NOT_DESCENDED`**, a Tier-2 warning code (25 total, was 24). Public surface: the locked
   `WARNING_CODES` snapshot was updated deliberately, and a profile may `escalate` or `suppress` it
   like any other code.

package/README.md

@@ -207,6 +207,8 @@ const safe = serializeDicom(dataset); // safe to share: input dataset never muta
 
 report.attributes.length; // count of attributes acted on (each carries tag/keyword/action, no values)
 report.warnings; // e.g. DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED
+report.unauditableSequences; // SQ elements emptied because their items could not be walked
+report.undefinedVrElements; // elements emptied because their on-wire VR is not a VR
 ```
 
 UIDs are remapped to deterministic `2.25` replacements that stay consistent across files, so a de-identified study still hangs together. Opt into any of the nine metadata-affecting Annex E Options to keep specific classes of attribute:
@@ -316,7 +318,7 @@ for (const w of ds.warnings) {
 }
 ```
 
-The 25 Tier-2 codes (`DICOM_MISSING_PREAMBLE`, `DICOM_FILE_META_GROUP_LENGTH_MISMATCH`, `DICOM_UN_PARSED_AS_SQ`, `DICOM_ODD_LENGTH_VALUE_PADDED`, `DICOM_PRIVATE_CREATOR_UNKNOWN`, `DICOM_VR_MISMATCH`, `DICOM_DA_LEGACY_FORMAT`, … ) live in [`src/parser/warnings.ts`](./src/parser/warnings.ts). Narrow on `w.code === WARNING_CODES.…` for typo-free comparisons, or pass `{ onWarning }` to `parseDicom` to stream them.
+The 26 Tier-2 codes (`DICOM_MISSING_PREAMBLE`, `DICOM_FILE_META_GROUP_LENGTH_MISMATCH`, `DICOM_UN_PARSED_AS_SQ`, `DICOM_ODD_LENGTH_VALUE_PADDED`, `DICOM_PRIVATE_CREATOR_UNKNOWN`, `DICOM_VR_MISMATCH`, `DICOM_DA_LEGACY_FORMAT`, … ) live in [`src/parser/warnings.ts`](./src/parser/warnings.ts). Narrow on `w.code === WARNING_CODES.…` for typo-free comparisons, or pass `{ onWarning }` to `parseDicom` to stream them.
 
 The 4 Tier-3 fatal codes (`NOT_DICOM_PART_10`, `INVALID_FILE_META`, `UNSUPPORTED_TRANSFER_SYNTAX`, `EMPTY_INPUT`) always throw a `DicomParseError`; they represent input the parser cannot meaningfully recover.
 
@@ -362,7 +364,9 @@ Thrown by `serializeDicom` for `MISSING_TRANSFER_SYNTAX` (the dataset names no t
 
 - **Pixel data.** No decode/decompression, no rendering, no measurements: Pixel Data is exposed as raw bytes. And v1 does not read a **compressed object at all**, not even structurally: a transfer syntax outside the four listed below is the fatal `UNSUPPORTED_TRANSFER_SYNTAX`, so JPEG / JPEG-LS / JPEG2000 / RLE / HTJ2K objects do not parse. → `@cosyte/dicom-pixel`.
 - **Burned-in PHI.** v1 **warns** it cannot remove burned-in annotation; a "de-identified" output is **metadata-de-identified only**.
-- **A sequence the parser could not open.** `deidentify()` recurses only into a sequence whose items the parser materialized, so anything nested inside one it could not read is neither cleaned nor listed in the report. Two shapes reach that state and **only one of them warns**: a defined-length Implicit VR LE value whose dictionary-resolved `SQ` is not an item stream raises `DICOM_SQ_NOT_DESCENDED`, while an undefined-length `UN` value the CP-246 descent could not read as a sequence is **silent** (it keeps `vr === "UN"` and raises nothing). So `ds.warnings` is worth reading but is not sufficient: the reliable test is `el.items === undefined` on an `SQ` or `UN` element you are trusting the report about.
+- **A sequence the parser could not open: content is dropped, not passed through.** `deidentify()` recurses only into a sequence whose items the parser materialized. A **standard** `SQ` element with no items is now **emptied**: its bytes are Data Sets by PS3.5 §7.5.1 and PS3.15 §E.1.1 obliges the de-identifier to reach the listed attributes inside them, so a run that cannot enumerate them must not ship them. `report.unauditableSequences` names the carrier and the byte length dropped (capped at 64 entries; the emptying itself is never capped), and `DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE` is raised. Expect **data loss** on such a file. The parse refusal is usually a sender-side encoding defect, but not always: a **conformant** file nested deeper than this library's own `NESTING_DEPTH_LIMIT` of 64 is refused the same way and loses that sequence too. **Two shapes are exempt and still leak.** A **private** `SQ` kept under `RetainSafePrivate` + a `Profile` is kept verbatim and unaudited, because the profile vouched for it. And an undefined-length **`UN`** the CP-246 descent could not read as a sequence keeps `vr === "UN"`, so the rule does not reach it and cannot be extended there: every ordinary `UN` element also has no items. For either, the reliable test remains `el.items === undefined` on the element itself.
+- **An element whose on-wire VR is not a VR: the value is dropped, not passed through.** Under an Explicit VR syntax the VR is two bytes the sender wrote and this parser trusts them. If those two bytes are not one of the 34 PS3.5 §6.2 defines, `deidentify()` **empties** the element: §6.2 requires every undefined VR to be long-form with a 32-bit VL, this parser reads it short-form, so those bytes are not a Value Field the library decoded and PS3.15 §E.1.1's obligation cannot be discharged inside them. `report.undefinedVrElements` names the **byte offset** and the byte length dropped (capped at 64 entries; the emptying itself is never capped) and `DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE` is raised. It names **no tag**, deliberately and uniquely among the report's findings: this header _may_ have been fabricated out of the middle of some element's value, in which case its tag bytes are document content - and nothing distinguishes that case from an honestly-written unrecognized VR, so the tag is withheld either way. The usual cause is an **under**-declared Value Length earlier in the file, which desynchronizes the reader so that leftover value bytes are read as a Data Element header - and the element that genuinely followed becomes the fabricated element's value, which is how a `(0010,0020)` Patient ID used to reach de-identified output. **A file conformant to PS3.5 2026c never trips this**, and an Implicit VR LE file cannot: there the VR comes from the dictionary. (The edition matters: §6.2 exists precisely to say how a _future_ VR will be encoded.) `UN` is one of the 34 and is not affected. **There is no exemption** - unlike the sequence rule above, `RetainSafePrivate` does not keep such an element.
+- **An over-declared Value Length into a binary carrier still leaks, and it is a known trade.** The mirror case - an _over_-declared length that swallows the following element into an `OB`/`OW`/`US`/`UN` value - is **not** detected, and a `(0010,0020)` inside it reaches de-identified output with no warning and no report entry. Arbitrary bytes are exactly what those VRs are for, so no content test can decide it; the only candidate remedy was measured and empties conformant binary values (a legal LUT or blob deleted because 8 of its bytes read as a zero-length `(0010,0020)`). String carriers **are** covered, because there the same bytes are provably outside the VR's repertoire. If you accept files from a sender you do not control, treat a binary attribute's length as untrusted.
 - **Networking & web.** No DIMSE (C-STORE/FIND/MOVE, MWL, MPPS); no DICOMweb (QIDO/WADO/STOW). → `@cosyte/dicom-net`, `@cosyte/dicomweb`.
 - **Transcoding.** No transfer-syntax conversion. The serializer re-emits in the dataset's source syntax only.
 - **Terminology resolution.** Coded values are surfaced (designator + canonical source) but not validated against SNOMED/LOINC/etc.

package/dist/index.cjs

@@ -11,7 +11,7 @@ var __export = (target, all) => {
 };
 
 // src/version.ts
-var VERSION = "0.0.6";
+var VERSION = "0.0.7";
 
 // src/dictionary/index.ts
 var dictionary_exports = {};
@@ -11735,6 +11735,12 @@ var WARNING_CODES = {
   // === Reserved by later phases (declared, not emitted in Phase 2) ===
   DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED: "DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED",
   // reserved by Phase 7 - not emitted in Phase 2
+  DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED: "DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED",
+  // emitted by deidentify(), never by the parser
+  DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE: "DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE",
+  // emitted by deidentify(), never by the parser
+  DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE: "DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE",
+  // emitted by deidentify(), never by the parser
   DICOM_PRIVATE_CREATOR_UNKNOWN: "DICOM_PRIVATE_CREATOR_UNKNOWN"
   // reserved by Phase 6 - not emitted in Phase 2
 };
@@ -11748,13 +11754,30 @@ var WARNING_MESSAGES = Object.freeze({
   DICOM_PRIVATE_TAG_NO_CREATOR: "Private element ({tag}) has no Private Creator registered for its block; treating as VR=UN.",
   DICOM_GROUP_LENGTH_IN_DATASET: "Retired Group Length element ({tag}) encountered in dataset; preserved as-is.",
   DICOM_NONZERO_RESERVED_BYTES: "Element ({tag}) has non-zero reserved bytes between VR and length (first byte {n}, second byte {n2}); ignoring.",
-  DICOM_SQ_NOT_DESCENDED: "Element ({tag}) resolved to VR=SQ from the dictionary but its defined-length value is not a valid item stream; kept as opaque bytes and NOT descended, so nothing nested inside it is visible to navigation or de-identification.",
+  DICOM_SQ_NOT_DESCENDED: "Element ({tag}) resolved to VR=SQ from the dictionary but its defined-length value is not a valid item stream; kept as opaque bytes and NOT descended, so nothing nested inside it is visible to navigation, and deidentify() cannot audit it. See DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE.",
   DICOM_UN_PARSED_AS_SQ: "Element ({tag}) has VR=UN with undefined length; descended as Implicit VR LE sequence per CP-246.",
   DICOM_EMPTY_ITEM_IN_SEQUENCE: "Sequence ({tag}) contains an empty item (length=0); tolerated.",
   DICOM_PIXEL_DATA_LENGTH_MISMATCH: "(7FE0,0010) PixelData declared length {n} does not match computed {n2} bytes.",
   DICOM_IMPLICIT_VR_FOR_PRIVATE_TAG_WITHOUT_VR: "Private element ({tag}) under Implicit VR LE has no VR override; falling back to UN.",
   DICOM_PRIVATE_CREATOR_UNKNOWN: "Private element ({tag}) has a Private Creator the active profile's private dictionary does not name; falling back to UN. The creator string is not reproduced here - read the (gggg,00EE) element if you need it.",
   DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED: "Pixel Data is present and Burned In Annotation is not 'NO'; this metadata-only de-identifier cannot inspect or clean pixels. Recognizable text may remain burned into the image.",
+  DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED: "Element ({tag}) {vr} was kept by the action table, but its value ends with {n} whole Data Element(s) - an over-declared Value Length swallowed what followed it. Emptied rather than kept, because the action table cannot see an attribute encoded inside a value. Read report.embeddedAttributes for the tags that were hidden there.",
+  // Deliberately short. One of these is raised per un-auditable element, so a
+  // long message is multiplied by an element count the input controls; the
+  // reasoning belongs in the docs, not in a string repeated thousands of times.
+  DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE: "Element ({tag}) is VR=SQ with no parsed items, so its {n} value bytes could not be audited (PS3.15 E.1.1); emptied. See report.unauditableSequences.",
+  // Deliberately short for the same reason as the code above: one per element,
+  // and the element count is chosen by the input.
+  //
+  // NEITHER THE TAG NOR THE VR IS ECHOED, and that is specific to this code
+  // rather than caution. Every other factory's {tag} is composed from a real
+  // Data Element header; the condition that raises THIS one is that the header
+  // was fabricated from bytes inside some element's value, so its four tag bytes
+  // and its two VR bytes are document content. `renderTag` shape-checks a tag
+  // and cannot refuse one, so the withholding has to happen at the call site.
+  // The byte offset locates the element instead, and is a position this parser
+  // counted rather than anything the document said.
+  DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE: "An element at byte offset {n2} carries an on-wire VR that is not one of the 34 PS3.5 6.2 defines, so its {n} value bytes are not a Value Field this library decoded; emptied (PS3.15 E.1.1). Its tag and VR are withheld: an earlier under-declared length can make them fragments of some element's value. See report.undefinedVrElements.",
   DICOM_BOM_IN_TEXT_VR: "Element ({tag}) {vr} value begins with a UTF-8 BOM; stripped on decode.",
   DICOM_TRAILING_NULL_IN_TEXT_VR: "Element ({tag}) {vr} value has a trailing NULL pad where SPACE is expected; trimmed.",
   DICOM_UI_TRAILING_SPACE: "Element ({tag}) UI value is SPACE-padded; UI requires NULL padding (PS3.5 \xA76.2). Trimmed.",
@@ -11832,6 +11855,25 @@ function privateCreatorUnknown(position, tag) {
 function burnedInAnnotationNotRemoved(position) {
   return build(WARNING_CODES.DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED, position);
 }
+function embeddedAttributeRemoved(position, tag, vr, count) {
+  return build(WARNING_CODES.DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED, position, {
+    tag,
+    vr,
+    n: count
+  });
+}
+function sequenceNotAuditable(position, tag, byteLength) {
+  return build(WARNING_CODES.DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE, position, {
+    tag,
+    n: byteLength
+  });
+}
+function undefinedVrNotAuditable(position, byteLength) {
+  return build(WARNING_CODES.DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE, position, {
+    n: byteLength,
+    n2: position.byteOffset
+  });
+}
 function bomInTextVR(position, tag, vr) {
   return build(WARNING_CODES.DICOM_BOM_IN_TEXT_VR, position, { tag, vr });
 }
@@ -14656,6 +14698,132 @@ function uidValueMultiplicity(rawBytes) {
   return raw.split("\\").length;
 }
 
+// src/deident/embedded.ts
+var KNOWN_VRS2 = new Set(Object.keys(BE_VR_STRIDE));
+var UNDEFINED_LENGTH4 = 4294967295;
+var FFFE_GROUP = 65534;
+var SCANNABLE_CARRIER_VRS = /* @__PURE__ */ new Set([
+  "AE",
+  "AS",
+  "CS",
+  "DA",
+  "DS",
+  "DT",
+  "IS",
+  "LO",
+  "LT",
+  "PN",
+  "SH",
+  "ST",
+  "TM",
+  "UC",
+  "UI",
+  "UR",
+  "UT"
+]);
+var ALLOWED_CONTROL_BYTES = /* @__PURE__ */ new Set([
+  9,
+  // TAB
+  10,
+  // LF
+  12,
+  // FF
+  13,
+  // CR
+  27
+  // ESC
+]);
+var CONTROL_TOLERANT_VRS = /* @__PURE__ */ new Set(["LT", "ST", "UT"]);
+var ESC_ONLY_VRS = /* @__PURE__ */ new Set(["LO", "SH", "UC", "PN"]);
+var MAX_SCAN_BYTES = 1 << 20;
+var MIN_HEADER = 8;
+function readU16(buf, off, littleEndian) {
+  return littleEndian ? buf.readUInt16LE(off) : buf.readUInt16BE(off);
+}
+function readU32(buf, off, littleEndian) {
+  return littleEndian ? buf.readUInt32LE(off) : buf.readUInt32BE(off);
+}
+function decodeAt(value, off, encoding) {
+  if (off + MIN_HEADER > value.length) return void 0;
+  const littleEndian = encoding !== "explicitBE";
+  const group = readU16(value, off, littleEndian);
+  const element = readU16(value, off + 2, littleEndian);
+  if (group === FFFE_GROUP) {
+    return { next: off + 8, tag: void 0 };
+  }
+  if (group === 0 && element === 0) return void 0;
+  const tag = joinTag(group, element);
+  if (encoding === "implicit") {
+    const length2 = readU32(value, off + 4, littleEndian);
+    if (length2 === UNDEFINED_LENGTH4 || length2 % 2 !== 0) return void 0;
+    const next2 = off + 8 + length2;
+    return next2 > value.length ? void 0 : { next: next2, tag };
+  }
+  const vr = value.toString("latin1", off + 4, off + 6);
+  if (!KNOWN_VRS2.has(vr)) return void 0;
+  if (LONG_FORM_VRS.has(vr)) {
+    if (off + 12 > value.length) return void 0;
+    if (value[off + 6] !== 0 || value[off + 7] !== 0) return void 0;
+    const length2 = readU32(value, off + 8, littleEndian);
+    if (length2 === UNDEFINED_LENGTH4 || length2 % 2 !== 0) return void 0;
+    const next2 = off + 12 + length2;
+    return next2 > value.length ? void 0 : { next: next2, tag };
+  }
+  const length = readU16(value, off + 6, littleEndian);
+  if (length % 2 !== 0) return void 0;
+  const next = off + 8 + length;
+  return next > value.length ? void 0 : { next, tag };
+}
+function isScannableCarrier(vr) {
+  return SCANNABLE_CARRIER_VRS.has(vr);
+}
+function hasByteOutsideRepertoire(region, carrierVr) {
+  const allFive = CONTROL_TOLERANT_VRS.has(carrierVr);
+  const escOnly = ESC_ONLY_VRS.has(carrierVr);
+  for (const byte of region) {
+    if (byte >= 32 && byte !== 127) continue;
+    if (allFive && ALLOWED_CONTROL_BYTES.has(byte)) continue;
+    if (escOnly && byte === 27) continue;
+    return true;
+  }
+  return false;
+}
+function findEmbeddedAttributes(value, carrierVr, encoding, isActionable) {
+  if (!isScannableCarrier(carrierVr)) return void 0;
+  if (value.length < MIN_HEADER) return void 0;
+  const windowStart = value.length > MAX_SCAN_BYTES ? value.length - MAX_SCAN_BYTES : 0;
+  const window = value.subarray(windowStart);
+  const n = window.length;
+  const half = (n >> 1) + 1;
+  const tiles = new Uint8Array(half);
+  const hit = new Uint8Array(half);
+  for (let off = n - MIN_HEADER & -2; off >= 0; off -= 2) {
+    const decoded = decodeAt(window, off, encoding);
+    if (decoded === void 0) continue;
+    const atEnd = decoded.next === n;
+    const onward = decoded.next < n ? tiles[decoded.next >> 1] === 1 : false;
+    if (!atEnd && !onward) continue;
+    tiles[off >> 1] = 1;
+    const actionable = decoded.tag !== void 0 && isActionable(decoded.tag);
+    const onwardHit = decoded.next < n ? hit[decoded.next >> 1] === 1 : false;
+    if (actionable || onwardHit) hit[off >> 1] = 1;
+  }
+  for (let off = 0; off + MIN_HEADER <= n; off += 2) {
+    if (hit[off >> 1] !== 1) continue;
+    if (!hasByteOutsideRepertoire(window.subarray(off), carrierVr)) return void 0;
+    const tags = [];
+    let pos = off;
+    while (pos < n) {
+      const decoded = decodeAt(window, pos, encoding);
+      if (decoded === void 0) break;
+      if (decoded.tag !== void 0) tags.push(decoded.tag);
+      pos = decoded.next;
+    }
+    return tags;
+  }
+  return void 0;
+}
+
 // src/deident/types.ts
 var DEIDENTIFY_OPTIONS = Object.freeze([
   "CleanGraphics",
@@ -14727,6 +14895,9 @@ var BODY_ENCODING2 = {
   "1.2.840.10008.1.2.2": "explicitBE",
   "1.2.840.10008.1.2.1.99": "explicitLE"
 };
+var MAX_UNAUDITABLE_SEQUENCE_FINDINGS = 64;
+var MAX_UNDEFINED_VR_FINDINGS = 64;
+var KNOWN_VRS3 = new Set(Object.keys(BE_VR_STRIDE));
 function validateRetain(retain) {
   const valid = new Set(DEIDENTIFY_OPTIONS);
   const active = /* @__PURE__ */ new Set();
@@ -14840,6 +15011,64 @@ function isPrivateCreatorElement(tag) {
   const { element } = splitTag(tag);
   return element >= 16 && element <= 255;
 }
+function actsOnTag(tag, ctx) {
+  if (isPrivateTag(tag)) return true;
+  const action = annexE(tag);
+  if (action === void 0) return false;
+  return resolveAction(effectiveCode(action, ctx.active)) !== "K";
+}
+function hasUndefinedVr(el) {
+  return !KNOWN_VRS3.has(el.vr);
+}
+function keepOrEmpty(el, ctx, contextPath, out) {
+  if (hasUndefinedVr(el)) {
+    emptyUndefinedVrElement(el, ctx, contextPath, out);
+    return false;
+  }
+  const hidden = findEmbeddedAttributes(el.rawBytes, el.vr, ctx.encoding, (t) => actsOnTag(t, ctx));
+  if (hidden === void 0) {
+    out.elements.set(el.tag, el);
+    return true;
+  }
+  out.elements.set(el.tag, freshScalar(el, buffer.Buffer.alloc(0), 0));
+  out.embeddedAttributes.push({
+    tag: el.tag,
+    vr: el.vr,
+    hidden,
+    ...contextPath.length > 0 ? { contextPath: [...contextPath] } : {}
+  });
+  out.warnings.push(
+    embeddedAttributeRemoved({ byteOffset: el.byteOffset }, el.tag, el.vr, hidden.length)
+  );
+  return false;
+}
+function emptyUndefinedVrElement(el, ctx, contextPath, out) {
+  out.elements.set(el.tag, freshScalar(el, buffer.Buffer.alloc(0), 0));
+  if (ctx.budget.undefinedVrElements >= MAX_UNDEFINED_VR_FINDINGS) return;
+  ctx.budget.undefinedVrElements += 1;
+  out.undefinedVrElements.push({
+    byteOffset: el.byteOffset,
+    byteLength: el.rawBytes.length,
+    ...contextPath.length > 0 ? { contextPath: [...contextPath] } : {}
+  });
+  out.warnings.push(undefinedVrNotAuditable({ byteOffset: el.byteOffset }, el.rawBytes.length));
+}
+function isUnauditableSequence(el) {
+  return el.vr === "SQ" && el.items === void 0;
+}
+function emptyUnauditableSequence(el, ctx, contextPath, out) {
+  out.elements.set(el.tag, rebuildSequence(el, [], ctx.encoding));
+  if (ctx.budget.unauditableSequences >= MAX_UNAUDITABLE_SEQUENCE_FINDINGS) return;
+  ctx.budget.unauditableSequences += 1;
+  out.unauditableSequences.push({
+    tag: el.tag,
+    byteLength: el.rawBytes.length,
+    ...contextPath.length > 0 ? { contextPath: [...contextPath] } : {}
+  });
+  out.warnings.push(
+    sequenceNotAuditable({ byteOffset: el.byteOffset }, el.tag, el.rawBytes.length)
+  );
+}
 function creatorsInScope(source) {
   const byBlock = /* @__PURE__ */ new Map();
   for (const el of source) {
@@ -14866,21 +15095,26 @@ function processElements(source, ctx, contextPath) {
   const out = {
     elements: /* @__PURE__ */ new Map(),
     attributes: [],
-    removedPrivateTags: []
+    removedPrivateTags: [],
+    embeddedAttributes: [],
+    unauditableSequences: [],
+    undefinedVrElements: [],
+    warnings: []
   };
   const creators = creatorsInScope(source);
   for (const el of source) {
     if (isPrivateTag(el.tag)) {
-      if (keepsPrivate(el, ctx, creators)) out.elements.set(el.tag, el);
+      if (keepsPrivate(el, ctx, creators)) keepOrEmpty(el, ctx, contextPath, out);
       else out.removedPrivateTags.push(el.tag);
       continue;
     }
     const action = annexE(el.tag);
     if (action === void 0) {
-      if (el.vr === "SQ" && el.items !== void 0) {
-        out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
+      if (el.vr === "SQ") {
+        if (isUnauditableSequence(el)) emptyUnauditableSequence(el, ctx, contextPath, out);
+        else out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
       } else {
-        out.elements.set(el.tag, el);
+        keepOrEmpty(el, ctx, contextPath, out);
       }
       continue;
     }
@@ -14892,8 +15126,7 @@ function processElements(source, ctx, contextPath) {
     let applied;
     switch (resolved) {
       case "K":
-        out.elements.set(el.tag, el);
-        applied = "kept";
+        applied = keepOrEmpty(el, ctx, contextPath, out) ? "kept" : "emptied";
         break;
       case "X":
         applied = "removed";
@@ -14935,6 +15168,10 @@ function descendSequence(el, ctx, contextPath, out) {
     const inner = processElements(item.elements(), ctx, childPath);
     out.attributes.push(...inner.attributes);
     out.removedPrivateTags.push(...inner.removedPrivateTags);
+    out.embeddedAttributes.push(...inner.embeddedAttributes);
+    out.unauditableSequences.push(...inner.unauditableSequences);
+    out.undefinedVrElements.push(...inner.undefinedVrElements);
+    out.warnings.push(...inner.warnings);
     newItems.push(new Item({ index, warnings: [], elements: inner.elements }));
   });
   return rebuildSequence(el, newItems, ctx.encoding);
@@ -14951,13 +15188,23 @@ function applySequenceAction(el, resolved, action, ctx, contextPath, out) {
       applied = "emptied";
       break;
     case "C":
-      out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
-      applied = "cleaned";
+      if (isUnauditableSequence(el)) {
+        emptyUnauditableSequence(el, ctx, contextPath, out);
+        applied = "emptied";
+      } else {
+        out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
+        applied = "cleaned";
+      }
       break;
     case "U":
     case "K":
-      out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
-      applied = "kept";
+      if (isUnauditableSequence(el)) {
+        emptyUnauditableSequence(el, ctx, contextPath, out);
+        applied = "emptied";
+      } else {
+        out.elements.set(el.tag, descendSequence(el, ctx, contextPath, out));
+        applied = "kept";
+      }
       break;
   }
   out.attributes.push(auditAttribute(el.tag, action, resolved, applied, contextPath));
@@ -15003,8 +15250,18 @@ function deidentify(ds, options = {}) {
     active,
     remap,
     profile: options.profile,
-    encoding};
-  const { elements, attributes, removedPrivateTags } = processElements(ds.elements(), ctx, []);
+    encoding,
+    budget: { unauditableSequences: 0, undefinedVrElements: 0 }
+  };
+  const processed = processElements(ds.elements(), ctx, []);
+  const {
+    elements,
+    attributes,
+    removedPrivateTags,
+    embeddedAttributes,
+    unauditableSequences,
+    undefinedVrElements
+  } = processed;
   elements.set(
     TAG_PATIENT_IDENTITY_REMOVED,
     insertedScalar(TAG_PATIENT_IDENTITY_REMOVED, "CS", buffer.Buffer.from("YES", "latin1"), littleEndian)
@@ -15014,7 +15271,7 @@ function deidentify(ds, options = {}) {
     TAG_DEIDENTIFICATION_METHOD,
     insertedScalar(TAG_DEIDENTIFICATION_METHOD, "LO", buffer.Buffer.from(method, "latin1"), littleEndian)
   );
-  const warnings = [];
+  const warnings = [...processed.warnings];
   if (hasUncleanedBurnedIn(ds)) {
     const offset = ds.get(TAG_PIXEL_DATA)?.byteOffset ?? 0;
     warnings.push(burnedInAnnotationNotRemoved({ byteOffset: offset, fileMeta: false }));
@@ -15029,6 +15286,9 @@ function deidentify(ds, options = {}) {
   const report = {
     attributes,
     removedPrivateTags,
+    embeddedAttributes,
+    unauditableSequences,
+    undefinedVrElements,
     uidMap: remap.cache,
     warnings,
     retained: [...active]