@cosyte/dicom 0.0.18 → 0.1.0

package/dist/index.d.cts

@@ -15,11 +15,10 @@ import { Buffer } from 'node:buffer';
 declare const VERSION: string;
 
 /**
- * Type definitions for the Phase 1 public Dictionary namespace.
+ * Type definitions for the public Dictionary namespace.
  *
- * Frozen surface. Phase 2 (parser), Phase 3 (dataset/VR), and Phase 7
- * (validate) all depend on this
- * shape - schema-breaking changes here cascade through the codebase.
+ * Frozen surface. The parser, the VR decoders and `validate()` all depend on
+ * this shape - schema-breaking changes here cascade through the codebase.
  *
  * @module
  */
@@ -98,19 +97,17 @@ interface UidEntry {
 }
 
 /**
- * Public Dictionary namespace for `@cosyte/dicom` - Phase 1 deliverable.
- *
- * D-10:
+ * Public Dictionary namespace for `@cosyte/dicom`.
  *
  *  - {@link lookup} - accepts either an 8-char hex tag (`"00100010"`) or a
  *    keyword (`"PatientName"`) and returns the typed {@link DictionaryEntry}
  *    or `undefined`.
  *  - {@link byKeyword} - keyword-only lookup; for cases where the caller has
  *    already validated the input shape and wants a narrower call.
- *  - {@link uid} - UID lookup (DICT-06).
+ *  - {@link uid} - UID lookup.
  *
- * No function throws on miss (D-10: "Returns the typed entry or `undefined`.
- * No throws on miss."). Returned entries are deeply frozen - mutation attempts
+ * No function throws on miss: each returns the typed entry or `undefined`.
+ * Returned entries are deeply frozen - mutation attempts
  * throw `TypeError` in strict mode (which all of `@cosyte/dicom`'s emitted code
  * runs under, given `"use strict"` is implicit for ES modules).
  *
@@ -140,8 +137,8 @@ interface UidEntry {
  * @example
  *   import { Dictionary } from "@cosyte/dicom";
  *   const a = Dictionary.lookup("00100010");        // by tag
- *   const b = Dictionary.lookup("PatientName");     // by keyword (DICT-04)
- *   const c = Dictionary.lookup("not-real");        // undefined (D-10 no-throw)
+ *   const b = Dictionary.lookup("PatientName");     // by keyword
+ *   const c = Dictionary.lookup("not-real");        // undefined, never a throw
  */
 declare function lookup(tagOrKeyword: string): DictionaryEntry | undefined;
 /**
@@ -162,8 +159,8 @@ declare function byKeyword(keyword: string): DictionaryEntry | undefined;
  * Covers PS3.6 Annex A whole: transfer syntaxes, SOP and Meta SOP Classes,
  * well-known SOP Instances and Frames of Reference, coding schemes and the
  * rest, current and retired alike. Returns `undefined` for unknown UIDs or
- * malformed input. Used by `parseDicom()` (Phase 2) to render human-readable
- * Transfer Syntax names (DICT-06).
+ * malformed input. Used by `parseDicom()` to render human-readable
+ * Transfer Syntax names.
  *
  * @example
  *   import { Dictionary } from "@cosyte/dicom";
@@ -187,10 +184,10 @@ declare namespace index {
 /**
  * Fatal error taxonomy for the `@cosyte/dicom` parser pipeline.
  *
- * Phase 2 core-parser context:
- *   - D-09 - `FATAL_CODES` is a frozen `as const` registry with EXACTLY
- *     four codes; anything less severe MUST be a Tier-2 warning.
- *   - D-10 - `DicomParseError` carries `code`, `byteOffset`, `offsetFrame`,
+ * Two rules hold the taxonomy in place:
+ *   - `FATAL_CODES` is a frozen `as const` registry with EXACTLY four codes;
+ *     anything less severe MUST be a Tier-2 warning.
+ *   - `DicomParseError` carries `code`, `byteOffset`, `offsetFrame`,
  *     `snippet` (up to 16 source bytes, space-separated lowercase hex), and
  *     an optional `contextPath`. The thrown `Error.message` is formatted
  *     `[CODE] msg (offset=N frame=F)` with `… in path/segments` appended when
@@ -260,8 +257,7 @@ type FatalCode = (typeof FATAL_CODES)[keyof typeof FATAL_CODES];
  * RESIDUALS` closed it, nothing on the thrown error said which. A consumer
  * cutting `input.subarray(err.byteOffset, err.byteOffset + 16)` to see what
  * upset the parser was, inside a Sequence Item, cutting an unrelated element -
- * the exact defect the `{ strict: true }` snippet itself was fixed for in
- * `#80`.
+ * the exact defect the `{ strict: true }` snippet itself was once fixed for.
  *
  * **A frame NAME is published; a frame ORIGIN is not, and that asymmetry is
  * deliberate.** The name is drawn from the closed set below, which the parser
@@ -331,7 +327,7 @@ type OffsetFrame = (typeof OFFSET_FRAMES)[keyof typeof OFFSET_FRAMES];
  * Thrown by `parseDicom` when the input violates one of the four
  * unrecoverable Tier-3 structural rules - or, under `{ strict: true }`,
  * when any Tier-2 warning is escalated through the single `emit`
- * chokepoint (D-35). Carries byte-offset positional context plus a short
+ * chokepoint. Carries byte-offset positional context plus a short
  * source snippet so consumers can log actionable errors.
  *
  * Message format: `[CODE] msg (offset=N frame=F)`, with `… in a/b/c`
@@ -353,13 +349,14 @@ type OffsetFrame = (typeof OFFSET_FRAMES)[keyof typeof OFFSET_FRAMES];
  * **`snippet` is cut in the frame `offsetFrame` names, on every fatal but one.**
  * The exception is `UNSUPPORTED_TRANSFER_SYNTAX`, whose snippet slot carries
  * PS3.6's own NAME for the unsupported UID when the registry publishes one
- * (`"RLE Lossless"`), and 16 raw bytes only when it does not. That is
+ * (`"SMPTE ST 2110-20 Uncompressed Progressive Active Video"`), and 16 raw
+ * bytes only when it does not. That is
  * deliberate and predates the frame; it is named here because a universal about
- * `snippet` written without it is false on the code a compressed object reaches
- * first. Everywhere else the two agree, so a consumer that only wants the bytes
- * at the offset already has them. **The frame is what a consumer needs before
- * indexing anything of its OWN by `byteOffset`**, which is the case no field on
- * this class used to cover.
+ * `snippet` written without it is false on the code an object under a refused
+ * Transfer Syntax reaches first. Everywhere else the two agree, so a consumer
+ * that only wants the bytes at the offset already has them. **The frame is what
+ * a consumer needs before indexing anything of its OWN by `byteOffset`**, which
+ * is the case no field on this class used to cover.
  *
  * @example
  * ```ts
@@ -388,7 +385,7 @@ declare class DicomParseError extends Error {
     readonly contextPath: readonly string[] | undefined;
     /**
      * Construct a new `DicomParseError`. All fields except `contextPath` are
-     * required so every thrower populates positional context per `TOL-02` - and
+     * required so every thrower populates positional context - and
      * `offsetFrame` is required for the same reason `byteOffset` is, because an
      * offset whose frame is optional is an offset whose frame is usually
      * missing.
@@ -401,11 +398,14 @@ declare class DicomParseError extends Error {
 /**
  * Shared parser-pipeline types for `@cosyte/dicom`.
  *
- * Phase 2 core-parser context:
- *   - D-02 - `ParseOptions` shape (Phase 2 only; no `profile` field).
- *   - D-03 - `OnWarningCallback` ordering contract (invoked AFTER push to `ctx.warnings`).
- *   - D-07 - `DicomPosition` shape (`byteOffset`, optional `fileMeta` / `deflated` / `contextPath`).
- *   - D-45 - `ParseContext.profile?: unknown` is reserved for Phase 6; Phase 2 never sets it.
+ * The contracts that live here:
+ *   - `ParseOptions`, the shape a caller passes to `parseDicom`.
+ *   - `OnWarningCallback`, whose ordering contract is that it is invoked
+ *     AFTER the push to `ctx.warnings`.
+ *   - `DicomPosition` (`byteOffset`, optional `fileMeta` / `deflated` /
+ *     `contextPath`).
+ *   - `ParseContext`, the parser's internal state, including the active
+ *     source/vendor `Profile`.
  *
  * Public types (exported via `src/index.ts`): `DicomPosition`, `ParseOptions`, `OnWarningCallback`.
  * Internal type (NOT exported from `src/index.ts`): `ParseContext`.
@@ -435,7 +435,7 @@ interface PrivateTagDefinition {
     readonly name: string;
 }
 /**
- * A source/vendor tolerance preset (Phase 6). A `Profile` bundles three
+ * A source/vendor tolerance preset. A `Profile` bundles three
  * things that only ever **tighten or annotate** a parse - never loosen it
  * past the Postel's-Law default:
  *
@@ -478,7 +478,7 @@ interface Profile {
  * Positional context for a `DicomParseWarning` or `DicomParseError`.
  *
  * **🛑 `byteOffset` IS NOT ALWAYS RELATIVE TO THE SOURCE BUFFER, AND THIS
- * JSDOC SAID IT WAS.** For the Deflated Explicit VR LE transfer syntax (D-27),
+ * JSDOC SAID IT WAS.** For the Deflated Explicit VR LE transfer syntax,
  * `deflated: true` says the offset indexes the inflated dataset buffer rather
  * than the on-disk source. That flag is the only frame this type carries, and
  * it is not the only frame this parser has: a defined-length Sequence Item is
@@ -514,7 +514,7 @@ interface DicomPosition {
 /**
  * Synchronous callback invoked once per Tier-2 warning emitted during parse.
  *
- * Per `02-CONTEXT.md` D-03, the callback fires AFTER the warning has been
+ * The callback fires AFTER the warning has been
  * pushed to `ctx.warnings`; if the callback throws, the parser silently
  * swallows the exception and continues (mirrors `@cosyte/hl7` sibling).
  *
@@ -532,8 +532,7 @@ type OnWarningCallback = (warning: DicomParseWarning) => void;
 /**
  * Options accepted by `parseDicom`.
  *
- * Per `02-CONTEXT.md` D-02 - Phase 2 form only. No `profile` field; Phase 6
- * adds it. With `exactOptionalPropertyTypes: true`, callers omit unset keys
+ * With `exactOptionalPropertyTypes: true`, callers omit unset keys
  * rather than passing `undefined` for any field below.
  *
  * @example
@@ -579,7 +578,7 @@ interface ParseOptions {
      * treatment is in the package's troubleshooting docs. The `DicomParseError`
      * this option raises in its place is a different and larger surface: it also
      * carries `snippet`,
-     * **16 raw bytes, unredacted** (D-10), read at the warning's own `byteOffset`.
+     * **16 raw bytes, unredacted**, read at the warning's own `byteOffset`.
      * A message-only PHI review of the lenient path therefore does not transfer to
      * the strict one. Log `err.code`, `err.byteOffset`, `err.offsetFrame` and
      * `err.message`; treat `err.snippet` as PHI.
@@ -623,7 +622,7 @@ interface ParseOptions {
     /**
      * Synchronous callback invoked once per Tier-2 warning, after the warning
      * has been pushed to `Dataset.warnings`. Throwing handlers are silently
-     * swallowed (parser-state safety per D-03).
+     * swallowed, for parser-state safety.
      *
      * Omit to skip the callback entirely.
      */
@@ -634,11 +633,11 @@ interface ParseOptions {
      * default), `Element.rawBytes` is `Buffer.subarray(slice)` - a zero-copy
      * view that pins the source ArrayBuffer until every Element is GC'd.
      *
-     * Per D-16 / MODEL-03. Omit to use the default.
+     * Omit to use the default.
      */
     readonly copyValues?: boolean;
     /**
-     * Source/vendor tolerance preset (Phase 6, D-45). Applies the profile's
+     * Source/vendor tolerance preset. Applies the profile's
      * `escalations` / `suppressions` to warning emission and its
      * `privateDictionary` to Implicit-VR resolution of private data elements.
      * A profile only tightens or annotates - it never makes the default
@@ -655,13 +654,12 @@ interface ParseOptions {
  * Tier-2 warning registry and factories for the `@cosyte/dicom` parser
  * pipeline.
  *
- * Phase 2 core-parser context:
- *   - D-08 - `WARNING_CODES` is a frozen `as const` registry with every code
- *     in the TOL-03 catalog (≥25 entries). Phase 2 actively emits 13;
- *     7 VR-decode-time codes are reserved for Phase 3; 2 charset codes are
- *     reserved for Phase 4; 2 codes are reserved for Phase 6 / Phase 7.
- *   - D-12 - Exactly one named factory per actively-emitted code; each
- *     factory carries its own JSDoc + `@example` and returns a typed
+ * Two rules govern it:
+ *   - `WARNING_CODES` is a frozen `as const` registry carrying every code
+ *     this package defines, including the ones no stage emits yet, so the
+ *     schema is stable for consumers.
+ *   - Exactly one named factory per actively-emitted code; each factory
+ *     carries its own JSDoc + `@example` and returns a typed
  *     `DicomParseWarning`.
  *
  * Consumers compare `warning.code === WARNING_CODES.<CODE>` to narrow and
@@ -677,9 +675,8 @@ interface ParseOptions {
  * The registry is frozen via `as const` so TypeScript infers the exact
  * string-literal union for `WarningCode` - there is zero runtime cost and
  * no magic-string comparisons for consumers. Reserved-but-not-emitted
- * codes carry inline comments documenting which phase activates them
- * (Phase 2 declares the union so the schema is stable for downstream
- * phases per D-08, D-42, D-43).
+ * codes carry inline comments documenting which stage activates them; the
+ * union is declared whole so the schema is stable for consumers.
  *
  * @example
  * ```ts
@@ -691,6 +688,10 @@ interface ParseOptions {
  * ```
  */
 declare const WARNING_CODES: {
+    readonly DICOM_DIRECTORY_OFFSET_DEFLATED: "DICOM_DIRECTORY_OFFSET_DEFLATED";
+    readonly DICOM_DIRECTORY_OFFSET_MALFORMED: "DICOM_DIRECTORY_OFFSET_MALFORMED";
+    readonly DICOM_DIRECTORY_OFFSET_UNRESOLVED: "DICOM_DIRECTORY_OFFSET_UNRESOLVED";
+    readonly DICOM_DIRECTORY_RECORD_REVISITED: "DICOM_DIRECTORY_RECORD_REVISITED";
     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";
@@ -702,6 +703,7 @@ declare const WARNING_CODES: {
     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";
+    readonly DICOM_PIXEL_DATA_FRAGMENTS_NOT_DELIMITED: "DICOM_PIXEL_DATA_FRAGMENTS_NOT_DELIMITED";
     readonly DICOM_PIXEL_DATA_LENGTH_MISMATCH: "DICOM_PIXEL_DATA_LENGTH_MISMATCH";
     readonly DICOM_PRIVATE_TAG_NO_CREATOR: "DICOM_PRIVATE_TAG_NO_CREATOR";
     readonly DICOM_SQ_NOT_DESCENDED: "DICOM_SQ_NOT_DESCENDED";
@@ -716,15 +718,27 @@ declare const WARNING_CODES: {
     readonly DICOM_TRAILING_NULL_IN_TEXT_VR: "DICOM_TRAILING_NULL_IN_TEXT_VR";
     readonly DICOM_UI_TRAILING_SPACE: "DICOM_UI_TRAILING_SPACE";
     readonly DICOM_CHARSET_AMBIGUOUS_SEPARATOR: "DICOM_CHARSET_AMBIGUOUS_SEPARATOR";
+    readonly DICOM_CHARSET_BYTES_UNDECODABLE: "DICOM_CHARSET_BYTES_UNDECODABLE";
+    readonly DICOM_CHARSET_ESCAPE_UNDECLARED: "DICOM_CHARSET_ESCAPE_UNDECLARED";
+    readonly DICOM_CHARSET_EXTENSION_NOT_RESET: "DICOM_CHARSET_EXTENSION_NOT_RESET";
     readonly DICOM_UNSUPPORTED_CHARSET: "DICOM_UNSUPPORTED_CHARSET";
     readonly DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED: "DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED";
+    readonly DICOM_DEIDENT_DATES_NOT_TRANSFORMED: "DICOM_DEIDENT_DATES_NOT_TRANSFORMED";
+    readonly DICOM_DEIDENT_DICOMDIR_FILE_SET_NOT_DISCHARGED: "DICOM_DEIDENT_DICOMDIR_FILE_SET_NOT_DISCHARGED";
     readonly DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED: "DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED";
+    readonly DICOM_DEIDENT_FILE_META_REPLACED: "DICOM_DEIDENT_FILE_META_REPLACED";
+    readonly DICOM_DEIDENT_GROUP_0004_REMOVED: "DICOM_DEIDENT_GROUP_0004_REMOVED";
+    readonly DICOM_DEIDENT_METHOD_CODES_PRIOR_REPLACED: "DICOM_DEIDENT_METHOD_CODES_PRIOR_REPLACED";
+    readonly DICOM_DEIDENT_METHOD_CODES_PRIOR_RETAINED: "DICOM_DEIDENT_METHOD_CODES_PRIOR_RETAINED";
     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_METHOD_VALUE_OVER_LENGTH: "DICOM_DEIDENT_METHOD_VALUE_OVER_LENGTH";
+    readonly DICOM_DEIDENT_PRIVATE_CARRIER_NOT_AUDITABLE: "DICOM_DEIDENT_PRIVATE_CARRIER_NOT_AUDITABLE";
+    readonly DICOM_DEIDENT_PRIVATE_DECLARATION_NOT_RESOLVED: "DICOM_DEIDENT_PRIVATE_DECLARATION_NOT_RESOLVED";
     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_DEIDENT_UNREGISTERED_ELEMENT_REMOVED: "DICOM_DEIDENT_UNREGISTERED_ELEMENT_REMOVED";
     readonly DICOM_PRIVATE_CREATOR_UNKNOWN: "DICOM_PRIVATE_CREATOR_UNKNOWN";
 };
 /**
@@ -750,7 +764,7 @@ type WarningCode = (typeof WARNING_CODES)[keyof typeof WARNING_CODES];
  * subclass) so they can be safely accumulated into `Dataset.warnings` and
  * passed to `onWarning` callbacks.
  *
- * Per D-07 there is intentionally NO `snippet` field on warnings:
+ * There is intentionally NO `snippet` field on warnings:
  * real-world files routinely produce 50+ warnings and a per-warning
  * snippet would balloon retained memory. Snippets appear only on
  * `DicomParseError` (the strict-mode escalation path).
@@ -772,43 +786,66 @@ interface DicomParseWarning {
 }
 
 /**
- * Phase 2 structural `Item` - a single `(FFFE,E000)`-delimited Item
+ * The structural `Item` - a single `(FFFE,E000)`-delimited Item
  * inside a Sequence, carrying a nested `Dataset`.
  *
- * Per `02-CONTEXT.md` D-04: structural surface only; navigation methods
- * land in Phase 3 (via `Dataset` extension per D-42).
+ * Structural surface only; navigation comes from the `Dataset` superclass.
  *
  * @module
  */
 
 /**
  * Initialiser shape for an `Item` - extends `DatasetInit` with `index`,
- * the 0-based position of the item inside its parent `Sequence`.
+ * the 0-based position of the item inside its parent `Sequence`, and the
+ * optional `fileOffset` the parser records (see {@link Item.fileOffset}).
  *
  * @internal
  */
 interface ItemInit extends DatasetInit {
     readonly index: number;
+    readonly fileOffset?: number;
 }
 /**
  * One sequence item. Inherits `fileMeta` (always `undefined` for nested
  * items), `warnings`, and the protected element map from `Dataset`.
  *
- * Phase 3 surfaces `Item.get(...)` / `Item.has(...)` / etc. via the
- * `Dataset` superclass extension per D-42.
+ * `Item.get(...)` / `Item.has(...)` and the rest come from the `Dataset`
+ * superclass.
  *
  * @example
  * ```ts
  * import { Item } from "@cosyte/dicom";
- * // Producers (parser plan 02-04) construct items as follows:
+ * // The parser constructs items as follows:
  * // const item = new Item({ index: 0, warnings: [], elements: new Map() });
  * ```
  */
 declare class Item extends Dataset {
     readonly index: number;
+    /**
+     * Byte offset of this Item's `(FFFE,E000)` Item tag in the Part 10 file it
+     * was read from, counted from the first byte of the File Preamble, which is
+     * how PS3.3 2026d Table F.3-3 counts a DICOMDIR's offsets. For a file read
+     * without a preamble, the 132 bytes of File Preamble and `DICM` prefix it
+     * lacks are still counted, so the File Meta group's first byte is offset 132.
+     *
+     * `undefined` for an Item with no position in a file: one inside a Deflated
+     * Data Set (a byte of a deflated stream is not a byte of the file), and one
+     * built by hand. `deidentify()` carries it from each source Item to the Item
+     * it rebuilds, as that Item's identity: it is how `serializeDicom` ties a
+     * DICOMDIR offset to the Directory Record it named.
+     *
+     * @example
+     * ```ts
+     * import { parseDicom } from "@cosyte/dicom";
+     * const ds = parseDicom(buf);
+     * const first = ds.get("00041220")?.items?.[0];
+     * first?.fileOffset; // where that Directory Record Item starts in the file
+     * ```
+     */
+    readonly fileOffset: number | undefined;
     /**
      * Construct a new structural `Item`. Producers are the SQ / FFFE
-     * marker parsers in plan 02-04.
+     * marker parsers.
      *
      * @internal
      */
@@ -816,7 +853,7 @@ declare class Item extends Dataset {
 }
 
 /**
- * Decoded-value model for Phase 3 - the typed result of `Element.value`.
+ * Decoded-value model - the typed result of `Element.value`.
  *
  * `DicomValue` is a discriminated union keyed on `kind`; each variant maps
  * to a family of VRs that share a decode shape (per PS3.5 §6.2 Table 6.2-1):
@@ -1021,18 +1058,14 @@ type DicomValue = {
 };
 
 /**
- * Phase 2 structural `Element` - leaf wrapper over an on-wire DICOM
+ * The structural `Element` - leaf wrapper over an on-wire DICOM
  * Data Element.
  *
- * Per `02-CONTEXT.md` D-04 + D-42: structural fields ONLY. No `.value`
- * getter, no decoders, no `.items` navigation - those land in Phase 3,
- * which extends this class.
- *
- * Per D-16: `rawBytes` is a `Buffer.subarray()` view over the source
- * buffer by default (zero-copy), pinning the source ArrayBuffer until
- * every Element is GC'd. The `parseDicom` `{ copyValues: true }` option
- * flips production to `Buffer.from(slice)` so the source can be
- * released; producers (parser plans 02-04 onward) honour it.
+ * `rawBytes` is a `Buffer.subarray()` view over the source buffer by default
+ * (zero-copy), pinning the source ArrayBuffer until every Element is GC'd.
+ * The `parseDicom` `{ copyValues: true }` option flips production to
+ * `Buffer.from(slice)` so the source can be released; every producer in the
+ * parser honours it.
  *
  * @module
  */
@@ -1042,7 +1075,7 @@ type DicomValue = {
  *
  * `privateCreator` is omitted (not `undefined`) for standard tags;
  * present only when the parser resolved a `(gggg,EEFF)` private element
- * to its registered Private Creator string per D-33 / D-34.
+ * to its registered Private Creator string.
  *
  * @internal
  */
@@ -1055,10 +1088,10 @@ interface ElementInit {
     readonly byteOffset: number;
     readonly privateCreator?: string;
     /**
-     * Phase 2 hint set by the parser when an `Element` was promoted from
-     * `VR=UN` with undefined length to `VR=SQ` via the CP-246 fallback (D-30).
-     * Phase 3 reads this to choose the inner SQ decoder (Implicit VR LE) on
-     * first lazy access. Never set on standard SQ elements.
+     * Hint set by the parser when an `Element` was promoted from
+     * `VR=UN` with undefined length to `VR=SQ` via the CP-246 fallback.
+     * The lazy value decoder reads this to choose the inner SQ decoder
+     * (Implicit VR LE) on first access. Never set on standard SQ elements.
      *
      * @internal
      */
@@ -1066,14 +1099,14 @@ interface ElementInit {
     /**
      * Byte order of the value bytes, set by the parser per transfer syntax
      * (`true` for Implicit/Explicit VR LE + Deflated; `false` for Explicit VR
-     * BE). Phase 3 numeric decoders read this - signedness comes from the VR,
+     * BE). The numeric decoders read this - signedness comes from the VR,
      * endianness from here.
      */
     readonly littleEndian: boolean;
     /**
      * The dataset's resolved `(0008,0005)` Specific Character Set terms in
      * effect for this element (parent dataset's, or the item's own override).
-     * Omitted when the Default Repertoire (ISO_IR 6) applies. Phase 3
+     * Omitted when the Default Repertoire (ISO_IR 6) applies. The
      * charset-dependent text decoders (`LO SH UC LT ST UT PN`) read this.
      */
     readonly specificCharacterSet?: readonly string[];
@@ -1085,13 +1118,11 @@ interface ElementInit {
     readonly items?: readonly Item[];
 }
 /**
- * One DICOM Data Element as parsed by Phase 2.
+ * One DICOM Data Element as parsed.
  *
- * Phase 2 surface (this plan): `tag`, `vr`, `vm`, `length`, `rawBytes`,
- * `byteOffset`, `privateCreator`. NO `.value` getter, NO decoders, NO
- * navigation methods. Phase 3 (per D-42) extends this class with a lazy,
- * memoized `.value` getter and the VR-aware decoders under
- * `src/dataset/vr/`.
+ * Structural surface: `tag`, `vr`, `vm`, `length`, `rawBytes`,
+ * `byteOffset`, `privateCreator`. On top of it sits a lazy, memoized
+ * `.value` getter backed by the VR-aware decoders under `src/dataset/vr/`.
  *
  * `rawBytes` retention behaviour: zero-copy `Buffer.subarray` view by
  * default (pins source ArrayBuffer); pass `{ copyValues: true }` to
@@ -1124,10 +1155,10 @@ declare class Element {
     readonly byteOffset: number;
     readonly privateCreator: string | undefined;
     /**
-     * Phase 2 hint for Phase 3's lazy SQ decoder per D-30. `true` when this
-     * Element was promoted from `VR=UN` with undefined length to `VR=SQ` via
-     * the CP-246 fallback. Phase 3 uses this to choose the Implicit VR LE
-     * inner decoder. Always `undefined` on standard SQ elements.
+     * Hint for the lazy SQ decoder. `true` when this Element was promoted
+     * from `VR=UN` with undefined length to `VR=SQ` via the CP-246 fallback,
+     * which is what selects the Implicit VR LE inner decoder. Always
+     * `undefined` on standard SQ elements.
      *
      * @internal
      */
@@ -1141,9 +1172,9 @@ declare class Element {
     /** Lazily-decoded, memoized {@link DicomValue}. */
     private _valueCache;
     /**
-     * Construct a new structural `Element`. Producers (parser plans 02-03
-     * onward) build these directly from on-wire bytes; consumers receive
-     * them via `Dataset` after `parseDicom`.
+     * Construct a new structural `Element`. The parser builds these directly
+     * from on-wire bytes; consumers receive them via `Dataset` after
+     * `parseDicom`.
      *
      * @internal
      */
@@ -1167,13 +1198,12 @@ declare class Element {
 }
 
 /**
- * Phase 2 structural `FileMeta` view-object shape.
+ * The structural `FileMeta` view-object shape.
  *
- * Per `02-CONTEXT.md` D-04 + D-17 + FM-02: a plain interface (not a class)
- * since Phase 2 has no methods. Only `transferSyntaxUID` is required;
- * the rest are populated by `parseFileMeta` (plan 02-02) when present
- * but never enforced (Phase 7's `validate()` enforces FM Type-1 fields
- * per D-19). Phase 3 may promote to a class if helpers are added.
+ * A plain interface rather than a class, because it carries no methods.
+ * Only `transferSyntaxUID` is required; the rest are populated by
+ * `parseFileMeta` when present but never enforced (`validate()` is what
+ * enforces File Meta Type-1 fields).
  *
  * @module
  */
@@ -1189,6 +1219,11 @@ declare class Element {
  * on-wire value, even-length per PS3.5 §6.2) rather than dropped. `value` is a
  * defensive copy, so the view never aliases the parsed input buffer.
  *
+ * 🛑 **THE ROUND TRIP IS PARSE-THEN-SERIALIZE ONLY. `deidentify()` DROPS EVERY
+ * ELEMENT THIS TYPE DESCRIBES**, and the exact examples above are why: a Sending
+ * AE Title and a Private Information pair are the identity information PS3.15
+ * §E.1.1 names. See {@link FileMeta.extraElements} for the whole carve-out.
+ *
  * @example
  * ```ts
  * import { parseDicom } from "@cosyte/dicom";
@@ -1217,9 +1252,9 @@ interface FileMetaRawElement {
  * over `(0002,xxxx)` elements parsed during the File Meta pre-pass.
  *
  * Only `transferSyntaxUID` is required because it is the dispatch input
- * for the four v1 transfer-syntax parsers; everything else is optional
+ * for the transfer-syntax parsers; everything else is optional
  * because real-world clinical files routinely omit one or more
- * Type-1 elements. Phase 7's `validate()` adds opinion-bearing checks
+ * Type-1 elements. `validate()` adds opinion-bearing checks
  * for those missing elements.
  *
  * @example
@@ -1243,15 +1278,139 @@ interface FileMeta {
      * Any `(0002,xxxx)` elements the source carried that the typed fields above
      * do not model, preserved in tag order so a round-trip re-emits the File Meta
      * group byte-for-byte. Omitted when the group held only modeled elements.
+     *
+     * ## 🛑 The byte-for-byte round trip does NOT hold for `deidentify()` output
+     *
+     * That promise is about **parse then serialize**, and it is scoped to it
+     * deliberately rather than by omission. `deidentify()` rebuilds this group to
+     * describe the de-identifying application instead of the source (PS3.15
+     * §E.1.1: the File Meta Information "shall be replaced with a description of
+     * the de-identifying application", because otherwise "identity information may
+     * leak through unmodified File Meta Information ... includ[ing] information
+     * regarding Application Entity Titles, Presentation Addresses, implementation
+     * information, and private information"). So on the de-identify path this
+     * array is **dropped in full** - not filtered, not sampled - and
+     * `sourceApplicationEntityTitle` goes with it, while
+     * `implementationClassUID` and `implementationVersionName` are replaced with
+     * this library's own.
+     *
+     * The elements that survive are the ones that identify the **object** rather
+     * than its sender: `fileMetaInformationVersion`, `mediaStorageSOPClassUID`,
+     * `transferSyntaxUID`, and `mediaStorageSOPInstanceUID` (remapped unless
+     * `RetainUIDs` is active). What was dropped is counted on the report
+     * `deidentify()` returns, so a caller learns the fidelity loss from the run
+     * rather than by diffing the bytes.
+     *
+     * A caller that needs the source group verbatim must read it off the
+     * **parsed** dataset; it is not recoverable from de-identified output, and it
+     * is not meant to be.
      */
     readonly extraElements?: readonly FileMetaRawElement[];
 }
 
 /**
- * Typed view model for the Phase 4 safety-critical domain helpers
+ * The DICOMDIR Directory Record model: which records a DICOMDIR's offsets name,
+ * and the tree they form.
+ *
+ * A DICOMDIR is a Dataset whose File Meta Media Storage SOP Class UID
+ * `(0002,0002)` is `1.2.840.10008.1.3.10` (Media Storage Directory Storage). Its
+ * Directory Record Sequence `(0004,1220)` holds one Item per record, and four
+ * `UL` attributes link them by byte offset: `(0004,1200)` and `(0004,1202)` name
+ * the first and last record of the root directory entity, and each record's
+ * `(0004,1400)` names its next sibling and `(0004,1420)` the first record of its
+ * lower-level entity. PS3.3 2026d Table F.3-3 counts each offset as "a number of
+ * bytes starting with the first byte of the File Meta Information" and says it
+ * "includes the File Preamble and the DICM Prefix"; zero means no record.
+ *
+ * **An offset resolves to a record only when it is exactly the file offset of
+ * that record's `(FFFE,E000)` Item tag**, which the parser records on each Item
+ * as {@link Item.fileOffset}. Nothing here scans the bytes for an Item tag: an
+ * offset that lands on an Item of a Sequence nested inside a record, inside a
+ * record's Data Set, on the Sequence's own header, or past the end of the file
+ * names no record, and the parser warns (`DICOM_DIRECTORY_OFFSET_UNRESOLVED`).
+ *
+ * The analysis is one pure function of a Dataset, {@link analyzeDirectory}, read
+ * three ways: `parseDicom` turns its findings into warnings, `Dataset.directory`
+ * exposes its tree, and `serializeDicom` ties each offset it writes to a record
+ * through the same {@link Item.fileOffset} identity.
+ *
+ * @module
+ */
+
+/**
+ * One Directory Record of a DICOMDIR: an Item of the Directory Record Sequence
+ * `(0004,1220)`, with the records its offsets name.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom } from "@cosyte/dicom";
+ * const dir = parseDicom(buf).directory;
+ * for (const patient of dir?.root ?? []) {
+ *   patient.type; // "PATIENT"
+ *   for (const study of patient.lowerLevel) study.item.get("0020000D"); // Study Instance UID
+ * }
+ * ```
+ */
+interface DirectoryRecord {
+    /** The record's 0-based index in the Directory Record Sequence. */
+    readonly index: number;
+    /**
+     * The Directory Record Type `(0004,1430)` value (`"PATIENT"`, `"STUDY"`,
+     * `"SERIES"`, `"IMAGE"` and the rest PS3.3 F.5 defines), or `undefined` when
+     * the record carries none.
+     */
+    readonly type: string | undefined;
+    /**
+     * The Referenced File ID `(0004,1500)`: its components in order (a path
+     * relative to the File-set root, one component per value), as the file wrote
+     * them less only the padding PS3.5 makes insignificant in `CS` (the trailing
+     * pad, and each value's leading and trailing spaces). Kept verbatim: never
+     * de-identified, rewritten or joined, and the element's own bytes on `item`
+     * are untouched. `undefined` when the record carries none.
+     */
+    readonly referencedFileId: readonly string[] | undefined;
+    /**
+     * The records of this record's lower-level directory entity: the one its
+     * `(0004,1420)` names, then each `(0004,1400)` successor in order. Empty when
+     * the offset is zero or names no record.
+     */
+    readonly lowerLevel: readonly DirectoryRecord[];
+    /** The record's own Data Set, for its record keys. */
+    readonly item: Item;
+}
+/**
+ * The Directory Record tree of a DICOMDIR, read from its offsets.
+ *
+ * `records` is every Item of the Directory Record Sequence, in order, whether
+ * or not an offset reaches it. `root` is the root directory entity: the record
+ * `(0004,1200)` names, then each `(0004,1400)` successor in order. A record is
+ * reached at most once: an offset that would reach one again is not followed.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom, type DirectoryRecord } from "@cosyte/dicom";
+ * const dir = parseDicom(buf).directory; // undefined unless the object is a DICOMDIR
+ * const walk = (records: readonly DirectoryRecord[], depth = 0): void => {
+ *   for (const r of records) {
+ *     console.log(" ".repeat(depth), r.type, r.referencedFileId?.join("/"));
+ *     walk(r.lowerLevel, depth + 1);
+ *   }
+ * };
+ * if (dir !== undefined) walk(dir.root);
+ * ```
+ */
+interface DicomDirectory {
+    /** Every Directory Record, in Directory Record Sequence order. */
+    readonly records: readonly DirectoryRecord[];
+    /** The root directory entity, in `(0004,1400)` order. */
+    readonly root: readonly DirectoryRecord[];
+}
+
+/**
+ * Typed view model for the safety-critical domain helpers
  * (`Dataset.patient` / `study` / `series` / `image`).
  *
- * Every field here obeys the §4 fail-safe contract from the dicom roadmap:
+ * Every field here obeys the same fail-safe contract:
  * a missing value is **typed-absent** (`undefined`), never a substituted
  * default; a malformed numeric component stays `null` inside its array
  * rather than being coerced; raw bytes are always still reachable via the
@@ -1285,7 +1444,7 @@ interface OtherPatientId {
     readonly typeCode?: string;
 }
 /**
- * Patient & study identity (§4.1 - the wrong-patient failure class).
+ * Patient & study identity (the wrong-patient failure class).
  *
  * `id` is **not globally unique**; correct cross-system matching needs the
  * `{id, issuerOfId, issuerQualifiers}` tuple plus `otherIds`. `name` keeps
@@ -1310,7 +1469,7 @@ interface PatientView {
     readonly sex?: string;
 }
 /**
- * Study-level identity (§4.1). `instanceUid` is the cross-system study key;
+ * Study-level identity. `instanceUid` is the cross-system study key;
  * `accessionNumber` ties the study to the order.
  *
  * @example
@@ -1330,7 +1489,7 @@ interface StudyView {
     readonly description?: string;
 }
 /**
- * Series-level identity & co-registration (§4.1, §4.3). Images sharing a
+ * Series-level identity & co-registration. Images sharing a
  * `frameOfReferenceUid` are spatially co-registered.
  *
  * @example
@@ -1373,7 +1532,7 @@ interface CodedConcept {
     readonly schemeUid?: string;
 }
 /**
- * A Real World Value Mapping (§4.5) - slope/intercept bound atomically to
+ * A Real World Value Mapping - slope/intercept bound atomically to
  * its UCUM measurement-units code, so a number is never detached from its
  * units. From Real World Value Mapping Sequence `(0040,9096)`.
  *
@@ -1390,7 +1549,7 @@ interface RealWorldValueMap {
 }
 /**
  * The five Enhanced multi-frame functional-group macros, resolved for a
- * single frame Per-Frame-else-Shared (§4.4, PS3.3 §C.7.6.16). Each macro is
+ * single frame Per-Frame-else-Shared (PS3.3 §C.7.6.16). Each macro is
  * typed-absent when present in neither the per-frame nor the shared group
  * (the three *geometry* macros are treated as required for an enhanced
  * object - see {@link ImageView.frame}).
@@ -1427,7 +1586,7 @@ interface FrameFunctionalGroups {
     };
 }
 /**
- * Pixel-interpretation + geometry metadata (§4.2 / §4.3 / §4.4 / §4.5) - the
+ * Pixel-interpretation + geometry metadata - the
  * "wrong pixels look fine" and "looks fine, measures wrong" classes. v1 does
  * not decode pixels; this view surfaces exactly what a renderer needs so it
  * does not have to guess.
@@ -1492,14 +1651,13 @@ interface ImageView {
 }
 
 /**
- * Phase 2 structural `Dataset` - top-level container produced by
+ * The structural `Dataset` - top-level container produced by
  * `parseDicom`.
  *
- * Per `02-CONTEXT.md` D-04 + D-42: only `fileMeta` and `warnings` are
- * public; the element map is held internally and Phase 3 extends this
- * class with the `get` / `has` / `elements` / `getAll` / `setElement` /
- * `addElement` / `removeElement` / `addItem` / `removeItem` navigation
- * surface.
+ * Only `fileMeta` and `warnings` are public data; the element map is held
+ * internally and reached through the `get` / `has` / `elements` / `getAll` /
+ * `setElement` / `addElement` / `removeElement` / `addItem` / `removeItem`
+ * navigation surface.
  *
  * The `warnings` array is frozen at the constructor boundary (mirrors
  * `@cosyte/hl7` sibling `model/message.ts`) so consumers receive
@@ -1523,12 +1681,11 @@ interface DatasetInit {
     readonly elements: ReadonlyMap<Tag, Element>;
 }
 /**
- * One parsed DICOM dataset - the structural shell shipped by Phase 2.
+ * One parsed DICOM dataset - the structural shell.
  *
- * Phase 2 public surface: `fileMeta`, `warnings`. The internal element
- * map is stored on `_elements` (protected) and Phase 3 promotes it to
- * the public `get` / `has` / `elements` / `getAll` navigation API per
- * D-42.
+ * Public data: `fileMeta`, `warnings`. The internal element map is stored
+ * on `_elements` (protected) and reached through the public
+ * `get` / `has` / `elements` / `getAll` navigation API.
  *
  * @example
  * ```ts
@@ -1544,21 +1701,23 @@ declare class Dataset {
     readonly fileMeta: FileMeta | undefined;
     readonly warnings: readonly DicomParseWarning[];
     /**
-     * Element map, keyed by uppercase 8-hex tag. Phase 3 promotes to
-     * public navigation surface; Phase 2 keeps it `protected` so only
-     * subclasses (`Item`, future Phase-3 extensions) can introspect.
+     * Element map, keyed by uppercase 8-hex tag. Reached publicly through the
+     * navigation surface; kept `protected` here so only subclasses (`Item`, and
+     * any later extension) can introspect it directly.
      *
      * @internal
      */
     protected readonly _elements: ReadonlyMap<Tag, Element>;
-    /** Memoised Phase 4 domain views (built once, on first access). */
+    /** Memoised domain views (built once, on first access). */
     private _patient?;
     private _study?;
     private _series?;
     private _image?;
+    /** Boxed so a memoised "not a DICOMDIR" is told apart from "not read yet". */
+    private _directory?;
     /**
-     * Construct a new structural `Dataset`. Phase 2 freezes the warnings
-     * array at the model boundary (sibling `message.ts` lines 117–118).
+     * Construct a new structural `Dataset`. The warnings array is frozen at
+     * the model boundary.
      *
      * @internal
      */
@@ -1614,7 +1773,7 @@ declare class Dataset {
      */
     getAll(tag: Tag): readonly Element[];
     /**
-     * Patient-identity view (§4.1). Fail-safe typed-absent fields; `id` is
+     * Patient-identity view. Fail-safe typed-absent fields; `id` is
      * **not** globally unique - match on the `{id, issuerOfId, ...}` tuple
      * plus `otherIds`, never on a bare `(0010,0020)`. Memoised on first read.
      *
@@ -1627,7 +1786,7 @@ declare class Dataset {
      */
     get patient(): PatientView;
     /**
-     * Study-identity view (§4.1). `instanceUid` is the cross-system study
+     * Study-identity view. `instanceUid` is the cross-system study
      * key; `accessionNumber` ties it to the order. Memoised on first read.
      *
      * @example
@@ -1639,7 +1798,7 @@ declare class Dataset {
      */
     get study(): StudyView;
     /**
-     * Series-identity & co-registration view (§4.1, §4.3). A shared
+     * Series-identity & co-registration view. A shared
      * `frameOfReferenceUid` means images are spatially co-registered.
      * Memoised on first read.
      *
@@ -1652,7 +1811,7 @@ declare class Dataset {
      */
     get series(): SeriesView;
     /**
-     * Pixel-interpretation + geometry view (§4.2–§4.5). Surfaces exactly
+     * Pixel-interpretation + geometry view. Surfaces exactly
      * what a renderer needs without guessing: `rescaleSlope`/`signed`/
      * `photometricInterpretation` stay absent rather than defaulted, and the
      * three pixel-spacing tags are distinct. Memoised on first read.
@@ -1665,26 +1824,59 @@ declare class Dataset {
      * ```
      */
     get image(): ImageView;
+    /**
+     * The DICOMDIR Directory Record tree, or `undefined` when this Dataset is not
+     * a DICOMDIR (its File Meta Media Storage SOP Class UID is not
+     * `1.2.840.10008.1.3.10`). Read from the four offset attributes (PS3.3 2026d
+     * Table F.3-3): `root` is the record `(0004,1200)` names and each
+     * `(0004,1400)` successor, and each record's `lowerLevel` is the record its
+     * `(0004,1420)` names and each successor. An offset resolves only when it is
+     * exactly the file offset of an Item of the Directory Record Sequence
+     * `(0004,1220)`; one that is not names no record, and `parseDicom` warns
+     * (`DICOM_DIRECTORY_OFFSET_UNRESOLVED`, `DICOM_DIRECTORY_OFFSET_MALFORMED`,
+     * `DICOM_DIRECTORY_RECORD_REVISITED`, `DICOM_DIRECTORY_OFFSET_DEFLATED`).
+     * Memoised on first read.
+     *
+     * Limits: record keys are not checked against PS3.3 F.5, the File-set
+     * Consistency Flag and `(0004,1202)`'s agreement with the end of the root
+     * chain are not checked, and under Deflated Explicit VR LE no offset resolves,
+     * so every record is listed in `records` and none is linked.
+     *
+     * @example
+     * ```ts
+     * import { parseDicom } from "@cosyte/dicom";
+     * const dir = parseDicom(buf).directory;
+     * for (const patient of dir?.root ?? []) {
+     *   for (const study of patient.lowerLevel) {
+     *     for (const series of study.lowerLevel) {
+     *       for (const image of series.lowerLevel) console.log(image.referencedFileId);
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    get directory(): DicomDirectory | undefined;
 }
 
 /**
  * Public parser entry - `parseDicom`.
  *
- * Pipeline (Phase 2 plan 02-02):
- *   1. Dual EMPTY_INPUT check (raw input + post-normalize) per CONTEXT D-13.
+ * Pipeline:
+ *   1. Dual EMPTY_INPUT check (raw input + post-normalize).
  *   2. {@link normalizeInput} converts `Buffer | Uint8Array | ArrayBuffer`
- *      to a zero-copy `Buffer` view per PARSE-04.
- *   3. {@link parsePart10Header} resolves preamble + DICM framing per D-14.
+ *      to a zero-copy `Buffer` view.
+ *   3. {@link parsePart10Header} resolves preamble + DICM framing.
  *   4. {@link parseFileMeta} parses the (always Explicit VR LE) File Meta
- *      group per FM-01 / D-17.
- *   5. {@link TRANSFER_SYNTAX_PARSERS} dispatches on TS UID per D-20;
+ *      group.
+ *   5. {@link TRANSFER_SYNTAX_PARSERS} dispatches on TS UID;
  *      unsupported UIDs throw `UNSUPPORTED_TRANSFER_SYNTAX` carrying the
  *      `Dictionary.uid(uid)?.name` in `err.snippet`.
- *   6. The chosen strategy returns a `ReadonlyMap<Tag, Element>` (Phase 2
- *      stubs - real bodies arrive in plans 02-03 / 02-04 / 02-05).
- *   7. The result is assembled into a structural {@link Dataset}.
+ *   6. The chosen strategy returns a `ReadonlyMap<Tag, Element>`.
+ *   7. For a DICOMDIR, every Directory Record offset is resolved against the
+ *      Items' file offsets and each one that names no record is warned.
+ *   8. The result is assembled into a structural {@link Dataset}.
  *
- * Phase 6 (D-45) wires a source/vendor `Profile` via `ParseOptions.profile`:
+ * A source/vendor `Profile` is wired in through `ParseOptions.profile`:
  * its `escalations` / `suppressions` reshape Tier-2 emission at the
  * {@link makeEmitter} chokepoint, and its private-dictionary overlay resolves
  * the Implicit VR of vendor private data elements.
@@ -1705,8 +1897,28 @@ declare class Dataset {
  *     a recognizable `(0002,0000)` File Meta Group Length at offset 0.
  *   - `INVALID_FILE_META` - File Meta is truncated or `(0002,0010)`
  *     Transfer Syntax UID is missing.
- *   - `UNSUPPORTED_TRANSFER_SYNTAX` - Transfer Syntax UID is not one of the
- *     four v1 UIDs (`1.2.840.10008.1.2`, `…1.2.1`, `…1.2.2`, `…1.2.1.99`).
+ *   - `UNSUPPORTED_TRANSFER_SYNTAX` - Transfer Syntax UID is none of the
+ *     supported ones: the four native syntaxes (`1.2.840.10008.1.2`,
+ *     `…1.2.1`, `…1.2.2`, `…1.2.1.99`), every encapsulated Pixel Data
+ *     syntax PS3.5 2026c section A.4 names (JPEG, JPEG-LS, JPEG 2000, HTJ2K,
+ *     RLE, MPEG, HEVC, JPEG XL, Deflated Image Frame, Encapsulated
+ *     Uncompressed), and the four JPIP Referenced syntaxes of sections A.6,
+ *     A.7, A.11 and A.12. The SMPTE ST 2110 syntaxes and every retired UID
+ *     stay refused.
+ *
+ * An object under a section A.4 syntax is read under Explicit VR Little Endian
+ * rules, as A.4 requires: its metadata is fully readable, and its Pixel Data
+ * fragments are handed back as opaque, undecoded bytes by
+ * {@link readPixelDataFragments}. **No pixel is ever decoded.**
+ *
+ * An object under a JPIP Referenced syntax is read the same way for metadata:
+ * sections A.6 and A.11 make the Data Set Explicit VR Little Endian, and
+ * sections A.7 and A.12 deflate that Data Set per RFC 1951, so it is inflated
+ * first under the Deflated reader's decompression cap. Its Pixel Data Provider
+ * URL (0028,7FE0) is returned as the `UR` element the file carries and is
+ * **never fetched, resolved or validated**. The object is read-only here:
+ * `serializeDicom` refuses to write the four JPIP syntaxes, and `deidentify`
+ * refuses to de-identify an object under one of them.
  *
  * Pass `{ strict: true }` to escalate every Tier-2 warning to a thrown
  * `DicomParseError` carrying the warning code.
@@ -1716,7 +1928,7 @@ declare class Dataset {
  * import { parseDicom, WARNING_CODES, DicomParseError } from "@cosyte/dicom";
  * import { readFileSync } from "node:fs";
  *
- * // Three input shapes (PARSE-04): Buffer, Uint8Array, ArrayBuffer.
+ * // Three input shapes: Buffer, Uint8Array, ArrayBuffer.
  * const bytes = readFileSync("study.dcm");
  * const ds1 = parseDicom(bytes);
  * const ds2 = parseDicom(new Uint8Array(bytes));
@@ -1747,11 +1959,11 @@ declare function parseDicom(input: Buffer | Uint8Array | ArrayBuffer): Dataset;
 declare function parseDicom(input: Buffer | Uint8Array | ArrayBuffer, options: ParseOptions): Dataset;
 
 /**
- * Phase 2 structural `Sequence` - wrapper around an SQ element's items.
+ * The structural `Sequence` - wrapper around an SQ element's items.
  *
- * Per `02-CONTEXT.md` D-04: structural surface only - `items` and
- * `length`. No navigation methods. Phase 3 adds `Sequence.items[N].get(...)`
- * via `Item`'s `Dataset`-superclass extension per D-42.
+ * Structural surface only: `items` and `length`. No navigation methods of
+ * its own; `Sequence.items[N].get(...)` comes from `Item`'s `Dataset`
+ * superclass.
  *
  * @module
  */
@@ -1760,12 +1972,12 @@ declare function parseDicom(input: Buffer | Uint8Array | ArrayBuffer, options: P
  * One SQ (Sequence) element's structural body.
  *
  * `length` is the on-wire length: a real byte count for defined-length
- * SQ, or `0xFFFFFFFF` (4_294_967_295) when undefined-length per D-29.
+ * SQ, or `0xFFFFFFFF` (4_294_967_295) when undefined-length.
  *
  * @example
  * ```ts
  * import { Sequence } from "@cosyte/dicom";
- * // Producers (parser plan 02-04) construct sequences as follows:
+ * // The parser constructs sequences as follows:
  * // const sq = new Sequence([item0, item1], 0xFFFFFFFF);
  * ```
  */
@@ -1781,6 +1993,99 @@ declare class Sequence {
     constructor(items: readonly Item[], length: number);
 }
 
+/**
+ * Encapsulated Pixel Data, handed back as raw bytes: the Basic Offset Table and
+ * every fragment, exactly as the file carries them.
+ *
+ * An object under a PS3.5 2026c section A.4 Transfer Syntax (JPEG, JPEG-LS,
+ * JPEG 2000, HTJ2K, RLE and the rest) carries its Pixel Data `(7FE0,0010)` as an
+ * Item stream: a Basic Offset Table Item, then one Item per fragment of the
+ * encoded pixel stream, then a Sequence Delimitation Item. The parser reads that
+ * structure and never reads a fragment's content. This module is how a caller
+ * gets the content: as opaque, **undecoded** bytes. No pixel is decompressed, no
+ * frame is assembled from fragments, and the Basic Offset Table's offsets are
+ * not interpreted, because each of those is a codec's or a viewer's decision and
+ * this package decodes no pixels.
+ *
+ * @module
+ */
+
+/**
+ * The Basic Offset Table and the fragments of one encapsulated Pixel Data
+ * element, each as the raw bytes of its Item Value.
+ *
+ * Every `Buffer` here is a view over the element's own `Element.rawBytes`, with
+ * no Item header and no Sequence Delimitation Item in it, so it follows that
+ * element's retention: a zero-copy view over your input by default, and a copy
+ * that outlives it under `parseDicom(bytes, { copyValues: true })`.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom, readPixelDataFragments } from "@cosyte/dicom";
+ * const pixels = readPixelDataFragments(parseDicom(buf));
+ * if (pixels !== undefined) {
+ *   pixels.basicOffsetTable?.length; // 0 when the table is empty
+ *   pixels.fragments.length; // how many fragment Items the file carries
+ * }
+ * ```
+ */
+interface PixelDataFragments {
+    /**
+     * The Basic Offset Table's Item Value, uninterpreted. **Zero bytes when the
+     * table is empty**, which PS3.5 2026c section A.4 permits and decoders must
+     * accept. `undefined` only when the Item stream holds no Item at all, which
+     * A.4 does not permit; nothing is invented in its place.
+     */
+    readonly basicOffsetTable: Buffer | undefined;
+    /**
+     * The Item Value of every Item after the Basic Offset Table, in file order.
+     * Each is returned whole: its content is never read, so bytes inside a
+     * fragment that happen to look like a delimiter are fragment bytes (A.4: a
+     * decoder "may not scan for a Sequence Delimitation Item").
+     */
+    readonly fragments: readonly Buffer[];
+}
+/**
+ * Read the Basic Offset Table and every fragment of a Data Set's encapsulated
+ * Pixel Data `(7FE0,0010)` as raw bytes, without decoding anything.
+ *
+ * Pass the root {@link Dataset} `parseDicom` returned: its Pixel Data is the
+ * top-level element PS3.5 2026c section A.4 encapsulates. An `Item` is a
+ * `Dataset` too, and is read the same way over its own elements.
+ *
+ * **`undefined` means this Data Set has no encapsulated fragments**: Pixel Data
+ * is absent, or it is present in native format with an explicit Value Length.
+ * That is never an empty list and never a Basic Offset Table, so it cannot be
+ * mistaken for an encapsulated result.
+ *
+ * **The list can be short, and the parse says so.** A stream that ends with the
+ * input before its Sequence Delimitation Item still parses, and
+ * `DICOM_PIXEL_DATA_FRAGMENTS_NOT_DELIMITED` on `ds.warnings` says that the
+ * fragments read may not be all the sender wrote. Read the warnings before
+ * treating the list as complete.
+ *
+ * @throws `DicomParseError` with code `INVALID_FILE_META` when the element's
+ *   bytes are not an Item stream (an Item header cut short, an Item reaching past
+ *   the bytes, or a tag other than `(FFFE,E000)` / `(FFFE,E0DD)`). `parseDicom`
+ *   refuses such bytes itself, so only a hand-built `Element` reaches this; the
+ *   error carries no fragment byte and no length outside its 16-byte `snippet`.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom, readPixelDataFragments } from "@cosyte/dicom";
+ * const ds = parseDicom(buf); // e.g. a JPEG 2000 object
+ * const pixels = readPixelDataFragments(ds);
+ * if (pixels === undefined) {
+ *   // no encapsulated Pixel Data: absent, or native
+ * } else {
+ *   for (const fragment of pixels.fragments) {
+ *     // hand `fragment` to a codec of your choice; it is the bytes as written
+ *   }
+ * }
+ * ```
+ */
+declare function readPixelDataFragments(ds: Dataset): PixelDataFragments | undefined;
+
 /**
  * VR-aware value dispatch - the body behind `Element.value`.
  *
@@ -1795,6 +2100,11 @@ declare class Sequence {
  *   - **Charset**: `LO SH UC LT ST UT PN` decode through `(0008,0005)`;
  *     the remaining string VRs are the Default Repertoire (ASCII, decoded
  *     Latin-1-lenient with `DICOM_NON_ASCII_IN_ASCII_VR` on stray bytes).
+ *     A multi-valued `(0008,0005)` decodes with ISO 2022 code extensions
+ *     (`./iso2022`), resetting to Value 1 at the VR's own delimiters, and
+ *     flags `DICOM_CHARSET_ESCAPE_UNDECLARED`,
+ *     `DICOM_CHARSET_BYTES_UNDECODABLE` and
+ *     `DICOM_CHARSET_EXTENSION_NOT_RESET` at most once each per value.
  *   - **Numeric strings** `DS`/`IS` → `number | null` (never `NaN`→0).
  *   - **Temporal** `DA`/`TM`/`DT` → tolerant typed values (warn + preserve).
  *   - **Bulk** `OB OD OF OL OV OW UN` → raw `binary` (not interpreted in v1).
@@ -1825,11 +2135,12 @@ declare function decodeElementValue(element: Element): DicomValue;
 
 /**
  * Specific Character Set `(0008,0005)` resolution + text decoding for the
- * Phase 3 value decoders.
+ * VR value decoders.
  *
  * Zero runtime deps: decoding rides on Node 22's full-ICU `TextDecoder`
  * (the `@cosyte/dicom` ≤3-dep ceiling keeps `iconv-lite` in reserve only if
- * a future multi-extension CJK case forces it).
+ * a future CJK case forces it). A multi-valued set's ISO 2022 code
+ * extensions are decoded by `./iso2022`, set by set, on the same labels.
  *
  * Term-list corrections verified against PS3.3 §C.12.1.1.2 for this build
  * (the easy-to-get-wrong ones):
@@ -1885,6 +2196,10 @@ declare function isKnownCharsetTerm(term: string): boolean;
  * the term list mixes single-byte and code-extension sets; falls back to
  * the default repertoire (Latin-1, lenient) when no term resolves.
  *
+ * {@link decodeText} decodes under this label when the list has one term, or
+ * when Value 1 is `ISO_IR 192`, `GB18030` or `GBK`. Any other multi-term list
+ * decodes with ISO 2022 code extensions instead, whatever label this returns.
+ *
  * @example
  * ```ts
  * import { resolveDecoderLabel } from "@cosyte/dicom";
@@ -1894,14 +2209,26 @@ declare function isKnownCharsetTerm(term: string): boolean;
  */
 declare function resolveDecoderLabel(terms: readonly string[] | undefined): string;
 /**
- * Decode bytes to a string under the resolved Specific Character Set,
- * never throwing: an unsupported decoder label falls back to UTF-8, then to
- * Latin-1 (1:1, cannot fail).
+ * Decode bytes to a string under the Specific Character Set terms, never
+ * throwing.
+ *
+ * With more than one term, and a Value 1 other than `ISO_IR 192`, `GB18030` or
+ * `GBK`, the bytes decode with ISO 2022 code extensions (PS3.5 section
+ * 6.1.2.5): every PS3.3 Table C.12-3 and C.12-4 escape sequence switches G0 or
+ * G1, no escape byte reaches the string, and the Value 1 designations come back
+ * after each CR, LF or FF, which are the reset points of a text VR. Bytes no
+ * designated set decodes read as U+FFFD. Only the string is returned here;
+ * `Element.value` carries the warnings for an element's value.
+ *
+ * Every other term list decodes under {@link resolveDecoderLabel}'s label: an
+ * unsupported label falls back to UTF-8, then to Latin-1 (1:1, cannot fail).
  *
  * @example
  * ```ts
  * import { decodeText } from "@cosyte/dicom";
  * const s = decodeText(buf, ["ISO_IR 192"]); // UTF-8
+ * // ESC $ B, the JIS X 0208 bytes of one character, ESC ( B
+ * decodeText(Buffer.from([0x1b, 0x24, 0x42, 0x3b, 0x33, 0x1b, 0x28, 0x42]), ["", "ISO 2022 IR 87"]);
  * ```
  */
 declare function decodeText(bytes: Buffer, terms: readonly string[] | undefined): string;
@@ -1992,7 +2319,209 @@ declare function parseDateTime(raw: string): {
 };
 
 /**
- * Coded-terminology surfacing (§4.6, PS3.16 §8 Table 8-1).
+ * Calendar-component conversion for the decoded `DA` / `TM` / `DT` values.
+ *
+ * `parseDate`, `parseTime` and `parseDateTime` decode three separate wire
+ * syntaxes into three separate shapes. These three functions project all of
+ * them onto one: `toObject` for the calendar components, `toISO` for a string,
+ * `toDate` for an absolute instant. The same three names, with the same
+ * meanings, are exported by every `@cosyte/*` parser that decodes a date, so a
+ * caller that learns them once can read a timestamp out of any of them.
+ *
+ * Three properties are the whole point of the surface and are asserted rather
+ * than assumed in `test/conversion-surface.test.ts`:
+ *
+ * - **A component the value did not state is ABSENT.** Nothing is zero-filled,
+ *   so `Object.keys()` of the result is exactly the precision the sender wrote.
+ * - **`millisecond` comes from the digits in `raw`, never from
+ *   `fractionalSeconds`.** `DicomTime.fractionalSeconds` is a binary float, and
+ *   the standard puts no bound on how many digits a `TM` may carry, so the
+ *   digits are read as written and the float is not consulted at all. `toISO`
+ *   renders the same digits verbatim, neither padded to three nor rounded.
+ * - **`toDate` never guesses a zone.** A value with no `&ZZXX` offset and no
+ *   `assumeOffsetMinutes` is not an instant, so it answers `undefined` rather
+ *   than reading the host machine's zone.
+ * - **A component outside its calendar range is REFUSED, never rolled over.**
+ *   The decoders bound the day at 1 to 31 without consulting the month, so
+ *   `parseDate("20240230")` is `valid: true`. Projecting that yields
+ *   `"2024-02-30"`, which every ISO-8601 reader silently moves to 1 March, and
+ *   an instant a day after the one the sender wrote. PatientBirthDate
+ *   (0010,0030) is a `DA`, so the harm is a date of birth shifted by a day with
+ *   nothing thrown. All three functions answer `undefined` instead.
+ *
+ * None of the three throws, for any input.
+ *
+ * The refusal lives HERE and not in `parseDate` / `parseTime` / `parseDateTime`:
+ * those keep the behaviour they were pinned at, so a caller that wants the
+ * sender's bytes still reads them off the decoded value and off `raw`. What is
+ * refused is the PROJECTION of a value onto a calendar that has no such day.
+ *
+ * @module
+ */
+
+/**
+ * The decoded temporal values this surface accepts: a `DA`, a `TM` or a `DT`.
+ *
+ * Deliberately not exported. The three members are exported types a caller can
+ * already name, and the Contract these functions implement introduces no new
+ * value type in any package that adopts it.
+ */
+type DicomTemporal = DicomDate | DicomTime | DicomDateTime;
+/**
+ * The calendar components a temporal value actually stated, and nothing else.
+ *
+ * Every value is a number, `month` is 1 to 12 (never the JS `Date` 0 to 11),
+ * and a component the value did not state is ABSENT rather than present and
+ * `undefined`: there is no `precision` key because the key set is the
+ * precision. No `raw`, no `valid` and no parse bookkeeping reaches it.
+ *
+ * The shape is the one `Temporal.PlainDateTime.from` and luxon's
+ * `DateTime.fromObject` accept, which is why the names are singular where
+ * {@link DicomTime} and {@link DicomDateTime} spell them plurally. Delete
+ * `offsetMinutes` and either constructor takes the rest with no key rename and
+ * no value adjustment. That is a documented property rather than a tested one:
+ * proving it would mean taking a dependency, and this package takes none for it.
+ *
+ * @example
+ * ```ts
+ * import { parseDateTime, toObject } from "@cosyte/dicom";
+ * import type { DateParts } from "@cosyte/dicom";
+ *
+ * const parts: DateParts | undefined = toObject(parseDateTime("202401151330").value);
+ * Object.keys(parts ?? {}); // ["year", "month", "day", "hour", "minute"]
+ * ```
+ */
+interface DateParts {
+    /** Calendar year as written, so `0050` is the year 50 and never 1950. */
+    readonly year?: number;
+    /** Calendar month, 1 to 12. */
+    readonly month?: number;
+    /** Day of month, 1 to 31. */
+    readonly day?: number;
+    /** Hour of day, 0 to 23. */
+    readonly hour?: number;
+    /** Minute, 0 to 59. */
+    readonly minute?: number;
+    /**
+     * Second, 0 to 59.
+     *
+     * `TM` and `DT` permit `60` for a leap second and the decoders keep it, but a
+     * value stating it is not projected: there is no ISO rendering of it a reader
+     * does not move, and no instant to build. See the module doc block.
+     */
+    readonly second?: number;
+    /** The first three digits of the stated fraction, right-padded with zeroes. */
+    readonly millisecond?: number;
+    /** Signed minutes east of UTC, present only when the value carried an offset. */
+    readonly offsetMinutes?: number;
+}
+/**
+ * The one option {@link toDate} takes, and the only key it carries.
+ *
+ * `assumeOffsetMinutes` is the caller's declaration of the zone a value that
+ * carries none was written in. An explicit `0` means "read this naive value as
+ * UTC", which is a decision this library will not make on a caller's behalf.
+ *
+ * @example
+ * ```ts
+ * import { parseDate, toDate } from "@cosyte/dicom";
+ * import type { ToDateOptions } from "@cosyte/dicom";
+ *
+ * const options: ToDateOptions = { assumeOffsetMinutes: -300 };
+ * toDate(parseDate("20240115").value, options)?.toISOString(); // "2024-01-15T05:00:00.000Z"
+ * ```
+ */
+interface ToDateOptions {
+    /** Minutes east of UTC to read a value that states no offset in. */
+    readonly assumeOffsetMinutes?: number;
+}
+/**
+ * The calendar components a `DA`, `TM` or `DT` value stated, as a frozen object.
+ *
+ * Returns `undefined` for a value the decoders marked `valid: false`, for
+ * `null` / `undefined`, for a value that stated no component at all, and for
+ * one whose components name no real calendar point (30 February, 29 February
+ * outside a leap year, 31 April, second 60). It never throws.
+ * `hours` / `minutes` / `seconds` are renamed to the singular
+ * `hour` / `minute` / `second`; `raw`, `valid` and the `legacy` and
+ * `nonstandardOffset` flags the decoders report beside the value never appear.
+ *
+ * @example
+ * ```ts
+ * import { parseDate, parseDateTime, parseTime, toObject } from "@cosyte/dicom";
+ *
+ * toObject(parseDateTime("20240115133015").value);
+ * // { year: 2024, month: 1, day: 15, hour: 13, minute: 30, second: 15 }
+ *
+ * toObject(parseTime("133015.123456").value).millisecond; // 123, from the digits
+ * toObject(parseDate("18700230").value); // undefined: February has no 30th
+ * ```
+ */
+declare function toObject(value: DicomTemporal | null | undefined): DateParts | undefined;
+/**
+ * The value as an ISO-8601 string, TRUNCATED to the precision it stated.
+ *
+ * Nothing is padded out: a `DA` renders `2024-01-15`, a `DT` that stated only
+ * an hour renders `2024-01-15T13`, and a `TM` renders the bare time. Fractional
+ * digits are rendered exactly as written. A stated offset is appended, `Z` when
+ * it is zero; a value that stated NO offset gets nothing appended, because a
+ * fabricated `Z` would claim UTC the sender never wrote.
+ *
+ * Returns `undefined` for an invalid value, for `null` / `undefined`, for a
+ * value that stated no component at all, and for one naming no real calendar
+ * point: a string such as `"2024-02-30"` is worse than no answer, because every
+ * ISO-8601 reader moves it silently to 1 March. It never throws. This is not a
+ * byte round-trip of the wire value and is not meant to be: `serializeDicom`
+ * remains the route that reproduces the original bytes.
+ *
+ * @example
+ * ```ts
+ * import { parseDate, parseDateTime, parseTime, toISO } from "@cosyte/dicom";
+ *
+ * toISO(parseDateTime("20240115133015-0500").value); // "2024-01-15T13:30:15-05:00"
+ * toISO(parseTime("133015").value); // "13:30:15"
+ * toISO(parseDate("18700431").value); // undefined: April has no 31st
+ * ```
+ */
+declare function toISO(value: DicomTemporal | null | undefined): string | undefined;
+/**
+ * The value as an absolute instant, ONLY where the zone is determinate.
+ *
+ * A stated `&ZZXX` offset wins and `options.assumeOffsetMinutes` is ignored.
+ * With no stated offset the caller's `assumeOffsetMinutes` is applied, an
+ * explicit `0` meaning "treat this naive value as UTC". With neither, the
+ * answer is `undefined`: the host machine's zone is never read and UTC is never
+ * assumed. A value with no year is never an instant, so a `TM` always answers
+ * `undefined` however the call is made. A non-finite `assumeOffsetMinutes`
+ * (`NaN`, `Infinity`, `-Infinity`) names no zone either, so it answers
+ * `undefined` rather than an `Invalid Date` whose `getTime()` is `NaN`, and so
+ * does a finite offset so large that applying it leaves the range a `Date` can
+ * represent. A value naming no real calendar point is refused before any of
+ * that, so an impossible day is never rolled into the next month.
+ *
+ * Components below the stated precision fill to their lowest legal value for
+ * the instant alone; the value's own precision is untouched, and a later
+ * {@link toObject} or {@link toISO} on it returns what it returned before. A
+ * four-digit year below 100 stays that year, so `0050` is the year 50 and the
+ * two-digit remapping of `Date.UTC` never reaches the result.
+ *
+ * @example
+ * ```ts
+ * import { parseDate, parseDateTime, toDate } from "@cosyte/dicom";
+ *
+ * toDate(parseDate("20240115").value); // undefined: no zone was stated
+ * toDate(parseDate("20240115").value, { assumeOffsetMinutes: 0 })?.toISOString();
+ * // "2024-01-15T00:00:00.000Z"
+ * toDate(parseDateTime("20240115133015+0100").value)?.toISOString();
+ * // "2024-01-15T12:30:15.000Z"
+ * toDate(parseDate("18700230").value, { assumeOffsetMinutes: 0 });
+ * // undefined: never 1 March for a value the sender wrote as February
+ * ```
+ */
+declare function toDate(value: DicomTemporal | null | undefined, options?: ToDateOptions): Date | undefined;
+
+/**
+ * Coded-terminology surfacing (PS3.16 §8 Table 8-1).
  *
  * A coded concept is the triplet `Code Value (0008,0100)` /
  * `Coding Scheme Designator (0008,0102)` / `Code Meaning (0008,0104)`. This
@@ -2051,11 +2580,11 @@ declare function codingSchemeOid(designator: string | undefined): string | undef
 declare function readCode(item: Dataset): CodedConcept;
 
 /**
- * Value-layer error taxonomy for the Phase 4 domain helpers.
+ * Value-layer error taxonomy for the domain helpers.
  *
  * This is **separate** from the parser's four-code `FATAL_CODES` /
  * `DicomParseError` (locked to unrecoverable Part 10 structural corruption
- * - see `../../parser/errors.ts`). The §4 helpers are otherwise fail-safe:
+ * - see `../../parser/errors.ts`). The domain helpers are otherwise fail-safe:
  * a missing *value* is typed-absent (`undefined`), never an exception. The
  * helper layer throws only for a **structural contract violation** the
  * caller asked it to resolve and that cannot be answered safely:
@@ -2071,7 +2600,7 @@ declare function readCode(item: Dataset): CodedConcept;
  * @module
  */
 /**
- * Stable string codes the Phase 4 helpers may throw. Narrow on
+ * Stable string codes the domain helpers may throw. Narrow on
  * {@link DicomValueError.code} to react to a specific contract violation.
  *
  * @example
@@ -2103,7 +2632,7 @@ declare const VALUE_ERROR_CODES: {
  */
 type ValueErrorCode = (typeof VALUE_ERROR_CODES)[keyof typeof VALUE_ERROR_CODES];
 /**
- * Thrown by the Phase 4 helpers for a structural contract violation that
+ * Thrown by the domain helpers for a structural contract violation that
  * cannot be answered safely (see module doc). Never carries a decoded
  * value, so it is safe to log without leaking PHI: the `message` is built
  * only from the code and structural facts (indices, tag/macro names).
@@ -2134,7 +2663,7 @@ declare class DicomValueError extends Error {
 }
 
 /**
- * `serializeDicom` - the Phase 5 Part 10 writer (the conservative half of
+ * `serializeDicom` - the Part 10 writer (the conservative half of
  * Postel's Law).
  *
  * Takes a {@link Dataset} (from `parseDicom`, or hand-built) and emits a
@@ -2144,15 +2673,40 @@ declare class DicomValueError extends Error {
  *   2. File Meta group `0002`, always Explicit VR LE, with a correct
  *      `(0002,0000)` group length - see {@link encodeFileMeta}.
  *   3. The dataset body, in the dataset's own transfer syntax (**no
- *      transcode**): Implicit VR LE, Explicit VR LE/BE, or - for the Deflated
- *      syntax - an Explicit VR LE body run through RFC 1951 raw deflate
- *      (`zlib.deflateRawSync`), symmetric to the parser's `inflateRawSync`.
+ *      transcode**): Implicit VR LE; Explicit VR LE/BE; for the Deflated
+ *      syntax, an Explicit VR LE body run through RFC 1951 raw deflate
+ *      (`zlib.deflateRawSync`), symmetric to the parser's `inflateRawSync`; and
+ *      for every Transfer Syntax PS3.5 2026c section A.4 names (the generated
+ *      list the parser dispatches), an Explicit VR LE body whose top-level
+ *      Pixel Data is an encapsulated fragment stream (see `./encapsulated.ts`).
  *
  * Conservative behaviour (PS3.5): scalar values are padded to even length on
  * write (§6.2); retired `(gggg,0000)` group-length elements are omitted from
- * the dataset (§7.2); short/long-form headers are chosen by VR (§7.1.2);
- * sequence and encapsulated-pixel-data spans pass through byte-for-byte
- * (§7.5 / §A.4).
+ * the dataset (§7.2); short/long-form headers are chosen by VR (§7.1.2); the
+ * Data Elements of the root Data Set, and of every Sequence Item the writer can
+ * walk, are emitted in ascending tag order (PS3.5 2026c §7.1 / §7.5.1, see
+ * `./order.ts`), with Items kept in their order and no value byte changed;
+ * encapsulated-pixel-data fragments pass through byte-for-byte (§A.4), and
+ * under a section A.4 syntax a top-level Pixel Data that is not a fragment
+ * stream section A.4 allows is refused, never repaired. A DICOMDIR's Directory
+ * Record offsets are recomputed against the bytes written, and one that cannot
+ * be tied to a record is refused (see `./directory.ts`).
+ *
+ * The ordering has limits, stated with it. A tag repeated inside an Item is
+ * kept (both copies, in source order), so such output still breaks PS3.5 2026c
+ * §7.1's "at most once". A Sequence that cannot be walked, one nested past
+ * `NESTING_DEPTH_LIMIT`, one whose parsed `items` do not match its bytes, and
+ * any `UN`-carried Sequence (under Implicit VR LE that includes a private
+ * Sequence inside an Item, even one a `Profile` resolved to `SQ`, since a
+ * default read resolves its tag to `UN`) are emitted as read, unordered. An
+ * element whose own bytes do not show where a reader ends it (an
+ * undefined-length `UN` the parser could not read as a Sequence, a value
+ * missing its Sequence Delimitation Item) is written after the ascending rest of
+ * its Data Set, since a reader would take whatever followed it into its value.
+ * So is a Sequence nested past the bound, other than a defined-length one under
+ * Implicit VR LE, since seeing where a reader ends it would take the walk past
+ * the bound. An element the parser relocated because a length lied is ordered
+ * where it was placed.
  *
  * @module
  */
@@ -2161,9 +2715,59 @@ declare class DicomValueError extends Error {
  * Serialize a {@link Dataset} to a spec-clean DICOM Part 10 `Buffer`.
  *
  * The dataset's transfer syntax is preserved (no transcoding): pixel-data
- * fragments and nested sequences are written back byte-for-byte, while scalar
- * values are re-emitted with correct even-length padding and File Meta group
- * length. Pure function - the input `Dataset` is never mutated.
+ * fragments are written back byte-for-byte, nested sequences carry the same
+ * bytes with each Item's Data Elements in ascending tag order, and scalar values
+ * are re-emitted with correct even-length padding and File Meta group length.
+ * Pure function - the input `Dataset` is never mutated.
+ *
+ * **Element order.** Every Data Set is written in ascending tag order (PS3.5
+ * 2026c §7.1, §7.5.1): the root, and the Data Set of every Item in every
+ * Sequence the writer can walk on the wire, at every depth up to
+ * `NESTING_DEPTH_LIMIT`. Items stay in their order (PS3.5 2026c §7.5) and no
+ * value changes; only whole element spans move, and only where the parsed
+ * `items` match the bytes, so the output reads back as the source did. Limits:
+ * a tag repeated inside an Item is kept twice, in source order, so that output
+ * still breaks PS3.5 2026c §7.1's "at most once"; a Sequence whose Item stream
+ * cannot be walked to exactly its end, one nested past the bound, one whose
+ * `items` do not match its bytes (a Sequence the parser did not descend, for
+ * one), and any `UN`-carried Sequence (under Implicit VR LE that includes a
+ * private Sequence inside an Item, even one a `Profile` resolved to `SQ`, since
+ * a default read resolves its tag to `UN`) are written as read, unordered; an
+ * element whose own bytes do not show where a reader ends it (an
+ * undefined-length `UN` the parser could not read as a Sequence, or a value
+ * missing its Sequence Delimitation Item) is written after the ascending rest
+ * of its Data Set, because a reader takes what follows it into its value, and
+ * so is a Sequence nested past the bound (other than a defined-length one under
+ * Implicit VR LE), whose end the writer would have to walk past the bound to
+ * see; and an element the parser relocated because a length lied is ordered
+ * where it was placed, since ordering cannot recover an order the source
+ * destroyed.
+ *
+ * **Encapsulated objects.** Under every Transfer Syntax PS3.5 2026c section A.4
+ * names (JPEG, JPEG-LS, JPEG 2000, HTJ2K, RLE and the rest: the list `parseDicom`
+ * reads), the File Meta Transfer Syntax UID is kept, the Data Set is written as
+ * Explicit VR Little Endian, and the top-level Pixel Data `(7FE0,0010)` is
+ * written as `OB` of undefined length: the input's Basic Offset Table Item and
+ * fragment Items byte for byte and in order, then a zero-length Sequence
+ * Delimitation Item. Nothing is decoded, transcoded or re-framed, and no offset
+ * table is interpreted or rebuilt. The limit sits with it: a top-level Data Set
+ * that section A.4 does not allow is refused with
+ * `INVALID_ENCAPSULATED_PIXEL_DATA` rather than repaired, which includes a
+ * fragment stream `parseDicom` read with `DICOM_PIXEL_DATA_FRAGMENTS_NOT_DELIMITED`,
+ * an odd Item Length, an empty fragment, native or absent top-level Pixel Data,
+ * and Float or Double Float Pixel Data. Pixel Data nested in a Sequence Item is
+ * written as read.
+ *
+ * **DICOMDIR offsets.** For a `Dataset` whose File Meta Media Storage SOP Class
+ * UID is `1.2.840.10008.1.3.10`, `(0004,1200)`, `(0004,1202)` and each Directory
+ * Record's `(0004,1400)` and `(0004,1420)` are written as the byte offset, from
+ * the first preamble byte of the output, of the Directory Record each named when
+ * the file was read (PS3.3 2026d Table F.3-3), whatever moved it: the rebuilt
+ * File Meta group, the ascending order above, or `deidentify()`. A record is the
+ * Item of the Directory Record Sequence `(0004,1220)` whose `Item.fileOffset`
+ * the offset equals; nothing is found by scanning for an Item tag. A zero offset
+ * is written as zero. Limits: the retired MRDR offset `(0004,1504)` is written as
+ * read, and nothing checks record keys or `(0004,1202)` against the root chain.
  *
  * **Input contract.** The writer is designed for a {@link Dataset} produced by
  * `parseDicom`: it relies on the parser's `Element.rawBytes` representation
@@ -2178,12 +2782,19 @@ declare class DicomValueError extends Error {
  * elements preserved on `extraElements`), not a byte-exact copy of the original
  * file: the 128-byte preamble is normalized to zeros, the File Meta group is
  * rebuilt in ascending tag order (modeled fields + `extraElements` - see
- * {@link encodeFileMeta}), odd-length values are padded even, and retired
- * `(gggg,0000)` group lengths are dropped.
+ * {@link encodeFileMeta}), the Data Sets are ordered as above, odd-length values
+ * are padded even, and retired `(gggg,0000)` group lengths are dropped.
  *
  * @throws {@link DicomSerializeError} with code `MISSING_TRANSFER_SYNTAX` when
- *   the dataset has no File Meta Transfer Syntax UID, or
- *   `UNSUPPORTED_TRANSFER_SYNTAX` when that UID is outside the v1 set.
+ *   the dataset has no File Meta Transfer Syntax UID,
+ *   `UNSUPPORTED_TRANSFER_SYNTAX` when that UID is neither one of the four
+ *   native syntaxes nor a section A.4 one, `INVALID_ENCAPSULATED_PIXEL_DATA`
+ *   when it is a section A.4 one and the top-level Pixel Data is not a fragment
+ *   stream section A.4 allows, `DIRECTORY_OFFSET_UNRESOLVED` when a DICOMDIR
+ *   carries an offset that is not zero and names no Directory Record the
+ *   `Dataset` holds, or is not one 32-bit unsigned integer (never written stale
+ *   or as zero), or `DIRECTORY_OFFSET_DEFLATED` when a DICOMDIR under Deflated
+ *   Explicit VR LE carries a non-zero offset. Nothing is returned on a throw.
  *
  * @example
  * ```ts
@@ -2196,9 +2807,9 @@ declare class DicomValueError extends Error {
 declare function serializeDicom(ds: Dataset): Buffer;
 
 /**
- * Serializer error taxonomy for the Phase 5 Part 10 writer.
+ * Serializer error taxonomy for the Part 10 writer.
  *
- * Like the Phase 4 {@link "../dataset/helpers/errors".DicomValueError}, this
+ * Like {@link "../dataset/helpers/errors".DicomValueError}, this
  * is **separate** from the parser's four-code `FATAL_CODES` /
  * `DicomParseError` (which are locked to *read*-side Part 10 structural
  * corruption - see `../parser/errors.ts`). The serializer throws only when
@@ -2208,17 +2819,45 @@ declare function serializeDicom(ds: Dataset): Buffer;
  *     `fileMeta.transferSyntaxUID` is empty. The Transfer Syntax UID is the
  *     dispatch input that decides every byte of the encoding, so there is no
  *     safe default to fall back to.
- *   - `UNSUPPORTED_TRANSFER_SYNTAX` - the Transfer Syntax UID is not one of
- *     the four v1 syntaxes the writer (and parser) support. The writer never
- *     transcodes, so it cannot emit a syntax it does not understand.
- *
- * The message is built only from the Transfer Syntax UID and structural
- * facts (never a decoded attribute value), so it is always safe to log.
+ *   - `UNSUPPORTED_TRANSFER_SYNTAX` - the Transfer Syntax UID is neither one of
+ *     the four native syntaxes nor one PS3.5 2026c section A.4 names for
+ *     encapsulated Pixel Data (the JPIP Referenced and SMPTE ST 2110 syntaxes
+ *     and every retired UID stay here). The writer never transcodes, so it
+ *     cannot emit a syntax it does not understand.
+ *   - `INVALID_ENCAPSULATED_PIXEL_DATA` - the Transfer Syntax UID is a section
+ *     A.4 one, but the top-level Data Set is not one that syntax may carry: no
+ *     top-level Pixel Data `(7FE0,0010)`, Float or Double Float Pixel Data
+ *     `(7FE0,0008)` / `(7FE0,0009)` present, Pixel Data with a defined Value
+ *     Length (Native Format), or a fragment stream that is not a Basic Offset
+ *     Table Item and one or more fragment Items of even, defined, non-zero
+ *     Item Length, ended by a Sequence Delimitation Item. The writer refuses
+ *     such a stream rather than repairing it: appending a delimiter to a stream
+ *     the reader flagged as possibly short would write a well-formed file that
+ *     may be missing frames.
+ *   - `DIRECTORY_OFFSET_UNRESOLVED` - the `Dataset` is a DICOMDIR (File Meta
+ *     Media Storage SOP Class UID `1.2.840.10008.1.3.10`) and one of its offset
+ *     attributes, `(0004,1200)`, `(0004,1202)`, or a Directory Record's
+ *     `(0004,1400)` or `(0004,1420)`, cannot be tied to a Directory Record the
+ *     `Dataset` holds: a non-zero value that is not the `Item.fileOffset` of an
+ *     Item of its Directory Record Sequence `(0004,1220)`, or a value that is
+ *     not one 32-bit unsigned integer. The writer recomputes every offset it
+ *     can tie; one it cannot is refused, never written stale (it would name the
+ *     wrong bytes) and never written as zero (zero means "no record" and would
+ *     silently prune the tree).
+ *   - `DIRECTORY_OFFSET_DEFLATED` - the DICOMDIR is to be written in Deflated
+ *     Explicit VR Little Endian and carries a non-zero offset (or one that is
+ *     not one 32-bit unsigned integer). A position inside a deflated stream
+ *     names no Item a reader can seek to, so no offset can be written for it.
+ *     A Deflated DICOMDIR whose offsets are all zero is written.
+ *
+ * The message is built only from structural constants (never a decoded
+ * attribute value, a Transfer Syntax UID, or a length or byte read from the
+ * input), so it is always safe to log.
  *
  * @module
  */
 /**
- * Stable string codes the Phase 5 serializer may throw. Narrow on
+ * Stable string codes the serializer may throw. Narrow on
  * {@link DicomSerializeError.code} to react to a specific failure.
  *
  * @example
@@ -2230,6 +2869,9 @@ declare function serializeDicom(ds: Dataset): Buffer;
 declare const SERIALIZE_ERROR_CODES: {
     readonly MISSING_TRANSFER_SYNTAX: "MISSING_TRANSFER_SYNTAX";
     readonly UNSUPPORTED_TRANSFER_SYNTAX: "UNSUPPORTED_TRANSFER_SYNTAX";
+    readonly INVALID_ENCAPSULATED_PIXEL_DATA: "INVALID_ENCAPSULATED_PIXEL_DATA";
+    readonly DIRECTORY_OFFSET_UNRESOLVED: "DIRECTORY_OFFSET_UNRESOLVED";
+    readonly DIRECTORY_OFFSET_DEFLATED: "DIRECTORY_OFFSET_DEFLATED";
 };
 /**
  * Discriminant for {@link DicomSerializeError.code}, enabling exhaustive
@@ -2243,7 +2885,13 @@ declare const SERIALIZE_ERROR_CODES: {
  *     case "MISSING_TRANSFER_SYNTAX":
  *       return "dataset has no Transfer Syntax UID to serialize under";
  *     case "UNSUPPORTED_TRANSFER_SYNTAX":
- *       return "Transfer Syntax UID is outside the v1 set";
+ *       return "Transfer Syntax UID is neither native nor a section A.4 one";
+ *     case "INVALID_ENCAPSULATED_PIXEL_DATA":
+ *       return "top-level Pixel Data is not a section A.4 fragment stream";
+ *     case "DIRECTORY_OFFSET_UNRESOLVED":
+ *       return "a DICOMDIR offset names no Directory Record the dataset holds";
+ *     case "DIRECTORY_OFFSET_DEFLATED":
+ *       return "a Deflated DICOMDIR carries a non-zero Directory Record offset";
  *   }
  * }
  * ```
@@ -2253,7 +2901,8 @@ type SerializeErrorCode = (typeof SERIALIZE_ERROR_CODES)[keyof typeof SERIALIZE_
  * Thrown by `serializeDicom` when a `Dataset`
  * cannot be emitted as spec-clean Part 10. Never carries a decoded value, so
  * it is safe to log without leaking PHI: the `message` is built only from the
- * code and the offending Transfer Syntax UID.
+ * code and structural constants, never from the Transfer Syntax UID, a length
+ * or a byte the `Dataset` holds.
  *
  * @example
  * ```ts
@@ -2265,6 +2914,12 @@ type SerializeErrorCode = (typeof SERIALIZE_ERROR_CODES)[keyof typeof SERIALIZE_
  *   if (err instanceof DicomSerializeError && err.code === "MISSING_TRANSFER_SYNTAX") {
  *     // dataset is missing the File Meta Transfer Syntax UID
  *   }
+ *   if (err instanceof DicomSerializeError && err.code === "INVALID_ENCAPSULATED_PIXEL_DATA") {
+ *     // a section A.4 object whose top-level Pixel Data is not a fragment stream
+ *   }
+ *   if (err instanceof DicomSerializeError && err.code === "DIRECTORY_OFFSET_UNRESOLVED") {
+ *     // a DICOMDIR offset the writer cannot tie to a Directory Record
+ *   }
  * }
  * ```
  */
@@ -2282,7 +2937,7 @@ declare class DicomSerializeError extends Error {
 
 /**
  * `defineProfile()` - the public factory for building immutable {@link Profile}
- * objects (Phase 6). Mirrors the `@cosyte/hl7` sibling's profile factory: a
+ * objects. Mirrors the `@cosyte/hl7` sibling's profile factory: a
  * validated options object in, a frozen `Profile` with a `describe()` method
  * out. Invalid input throws {@link ProfileDefinitionError} with an actionable
  * message rather than producing a half-built profile.
@@ -2425,22 +3080,24 @@ declare const profiles: Readonly<{
 
 /**
  * PS3.15 Annex E attribute-action table - DICOM Basic Application Confidentiality
- * Profile + 11 retention/clean option sets.
- *
- * Phase 1 deliverable (D-08 / D-09 / D-14). Consumed by Phase 7 `anonymize()`
- * (ANON-01..ANON-10).
- *
- * NOTE: This module is NOT re-exported from the package's `src/index.ts` (per D-10 +
- * D-27 - Phase 1's external surface is `Dictionary.{lookup,byKeyword,uid}` + `VERSION`
- * only). Phase 7 imports `annexE` via the `@cosyte/dicom/dictionary/annex-e` internal
- * path, which the `package.json` `exports` map will admit when Phase 7 lands its plans.
- *
- * The 9 *metadata-affecting* PS3.15 Annex E option-set columns (E.3.3–E.3.11 plus the
- * collapsed E.3.6 "RetainLongitudinalTemporal") populate `AnnexEAction.optionSet`
- * keys per attribute. The two *pixel-level* options - E.3.1 `CleanPixelData` and
- * E.3.2 `CleanRecognizableVisual` - are not represented per-attribute (PS3.15 Table
- * E.1-1 has no column for them); Phase 7 enforces them at the pixel-decode layer.
- * Both names remain in `AnnexEOption` for completeness and for Phase 7's API.
+ * Profile plus its retention/clean option sets.
+ *
+ * Consumed by the de-identifier.
+ *
+ * NOTE: This module is NOT re-exported from the package's `src/index.ts`. The
+ * `Dictionary` namespace's external surface is `Dictionary.{lookup,byKeyword,uid}`
+ * plus `VERSION`; `annexE` is reached internally through
+ * `@cosyte/dicom/dictionary/annex-e`.
+ *
+ * The 10 *metadata-affecting* option columns of Table E.1-1 populate
+ * `AnnexEAction.optionSet` keys per attribute. Ten rather than nine because
+ * E.3.6 is two mutually exclusive Options with a column each, and both are
+ * carried: `RetainLongitudinalTemporal` for full dates and
+ * `RetainLongitudinalTemporalModifiedDates` for modified dates. The two
+ * *pixel-level* options - E.3.1 `CleanPixelData` and E.3.2
+ * `CleanRecognizableVisual` - are not represented per-attribute (PS3.15 Table
+ * E.1-1 has no column for them); they are enforced at the pixel-decode layer.
+ * Both names remain in `AnnexEOption` for completeness and for that API.
  */
 
 /**
@@ -2454,7 +3111,7 @@ declare const profiles: Readonly<{
  * - `U` = replace UID with a consistent new UID per session
  *
  * Compound codes (`Z/D`, `X/Z/D`, `X/Z/U*`, `C/X`) are preserved verbatim from the
- * Annex E source; Phase 7 interprets them per the table's per-attribute semantics
+ * Annex E source; the de-identifier interprets them per the table's per-attribute semantics
  * (e.g. `Z/D` = `Z` if absent, `D` if present).
  *
  * @example
@@ -2462,52 +3119,68 @@ declare const profiles: Readonly<{
  */
 type AnnexEActionCode = "D" | "Z" | "X" | "K" | "C" | "U" | "Z/D" | "X/Z" | "X/D" | "X/Z/D" | "X/Z/U*" | "C/X";
 /**
- * One of the 11 PS3.15 Annex E option sets (E.3.1–E.3.11).
+ * One name per PS3.15 Annex E option column (E.3.1 to E.3.11), plus the second
+ * of the two Options E.3.6 defines.
  *
- * Names match REQUIREMENTS.md ANON-02 verbatim. `CleanPixelData` (E.3.1) and
- * `CleanRecognizableVisual` (E.3.2) act on pixel data, not metadata, and never
- * appear as `optionSet` keys in the generated `ANNEX_E` map; they remain in the
- * union for Phase 7's pixel-decode API.
+ * `CleanPixelData` (E.3.1) and `CleanRecognizableVisual` (E.3.2) act on pixel
+ * data, not metadata, and never appear as `optionSet` keys in the generated
+ * `ANNEX_E` map; they remain in the union for the pixel-decode API.
+ *
+ * **E.3.6 is two mutually exclusive Options and Table E.1-1 gives them separate
+ * columns**, so it takes two names here: `RetainLongitudinalTemporal` carries
+ * `Rtn. Long. Full Dates Opt.` (keep the real dates) and
+ * `RetainLongitudinalTemporalModifiedDates` carries `Rtn. Long. Modif. Dates
+ * Opt.` (keep them only as modified values), which is the more protective of
+ * the two on every row where they differ.
  *
  * @example
- *   const opt: AnnexEOption = "RetainLongitudinalTemporal";
+ *   const opt: AnnexEOption = "RetainLongitudinalTemporalModifiedDates";
  */
-type AnnexEOption = "CleanPixelData" | "CleanRecognizableVisual" | "CleanGraphics" | "CleanStructuredContent" | "CleanDescriptors" | "RetainLongitudinalTemporal" | "RetainPatientCharacteristics" | "RetainDeviceIdentity" | "RetainUIDs" | "RetainSafePrivate" | "RetainInstitutionIdentity";
+type AnnexEOption = "CleanPixelData" | "CleanRecognizableVisual" | "CleanGraphics" | "CleanStructuredContent" | "CleanDescriptors" | "RetainLongitudinalTemporal" | "RetainLongitudinalTemporalModifiedDates" | "RetainPatientCharacteristics" | "RetainDeviceIdentity" | "RetainUIDs" | "RetainSafePrivate" | "RetainInstitutionIdentity";
 
 /**
- * Public types + error taxonomy for Phase 7 metadata de-identification
+ * Public types + error taxonomy for metadata de-identification
  * (PS3.15 Annex E).
  *
  * @module
  */
 
 /**
- * The PS3.15 Annex E option sets `deidentify` honours - the nine
+ * The PS3.15 Annex E option sets `deidentify` honours - the
  * *metadata-affecting* columns of Table E.1-1. The two pixel-level options
  * (`CleanPixelData` §E.3.1, `CleanRecognizableVisual` §E.3.2) are deliberately
  * excluded: this is a metadata-only de-identifier and cannot inspect pixels
  * (deferred to `@cosyte/dicom-pixel`). When pixel data is present it always
  * warns rather than claiming the image is clean.
  *
- * **`RetainLongitudinalTemporal` gives you the full-dates branch.** PS3.15
- * §E.3.6 is *two* options, and Table E.1-1 gives them separate columns:
- * `Rtn. Long. Full Dates` (keep dates and times as they are) and
- * `Rtn. Long. Modif. Dates` (keep them only as modified/shifted values). One
- * name here covers both, and it carries the **full-dates** column - the *less*
- * protective branch. That is not a rounding difference: the two columns disagree
- * on **169** rows, and on every one of them full-dates says `K` (keep the real
- * value) where modified-dates says `C` (clean it). Activate it only when real
- * dates are genuinely required; leave it off and the Basic Profile action
- * applies, which removes or empties them. Date *shifting* is not implemented at
- * this layer - a caller who needs the modified-dates behaviour shifts the values
- * themselves after the call.
+ * **§E.3.6 is two Options, and each has its own name here.** Table E.1-1 gives
+ * them separate columns: `Rtn. Long. Full Dates` (keep dates and times as they
+ * are) and `Rtn. Long. Modif. Dates` (keep them only as modified values).
+ *
+ * - `RetainLongitudinalTemporal` carries the **full-dates** column, the *less*
+ *   protective branch: where the two columns differ, it says `K` (keep the real
+ *   value). Activate it only when real dates are genuinely required.
+ * - `RetainLongitudinalTemporalModifiedDates` carries the **modified-dates**
+ *   column, which says `C` (clean it) on every row where the two differ, and
+ *   makes the run write `(0028,0303) = MODIFIED`.
+ *
+ * The two are **mutually exclusive**: §E.3.6 defines them as alternatives, and a
+ * call naming both is rejected with {@link DeidentifyError}. Leave both off and
+ * the Basic Profile action applies, which removes or empties dates.
+ *
+ * 🩺 **Date *modification* is the caller's, on both branches.** This library
+ * applies the column and writes the declaration; it shifts, aggregates and
+ * transforms nothing, so a `MODIFIED` it writes is true only if you performed
+ * the transformation §E.3.6 describes. `report.warnings` carries
+ * `DICOM_DEIDENT_DATES_NOT_TRANSFORMED` on every run that activates the
+ * modified-dates Option, saying exactly that.
  *
  * @example
  *   const retain: DeidentifyOption[] = ["RetainLongitudinalTemporal", "RetainSafePrivate"];
  */
 type DeidentifyOption = Exclude<AnnexEOption, "CleanPixelData" | "CleanRecognizableVisual">;
 /**
- * The nine metadata option-set names, frozen for runtime validation.
+ * The metadata option-set names, frozen for runtime validation.
  *
  * @example
  * ```ts
@@ -2594,8 +3267,16 @@ interface DeidentifiedAttribute {
      * `(0012,0062) Patient Identity Removed = YES`. That re-emission belongs to
      * the disclosed under-declare carrier class, not to this field, and neither is
      * a bound on the other: **redacting `contextPath` from a log does not make the
-     * object safe to share.** Pinned in
-     * `test/integration/phi-diagnostic-surface.test.ts`.
+     * object safe to share.**
+     *
+     * **That fixture no longer reproduces either half.** `(5348,4E4F)` has no row
+     * in this build's PS3.6 registry and none in Table E.1-1, so `deidentify()` now
+     * removes the fabricated Sequence whole before it reads the VR, and neither
+     * this field nor the object carries `"HSON"` (see
+     * {@link UnregisteredElementRemoval}); that is what
+     * `test/integration/phi-diagnostic-surface.test.ts` pins now. It is a fact
+     * about that shape and **not a bound on this field**: a Sequence the run does
+     * descend still contributes whatever tag the wire gave it.
      *
      * It is published anyway, on the same footing as
      * {@link DeidentifyReport.removedPrivateTags}: **where** an attribute sat is
@@ -2633,7 +3314,7 @@ interface DeidentifiedAttribute {
  * beside a genuine `(0010,0020)` reported `hidden: ["4D535449", "00100020"]`,
  * and `4D535449` is `"SMIT"` in wire order.
  *
- * **An entry is now one of the 652 literal rows of PS3.15 Table E.1-1 that this
+ * **An entry is now one of the 653 literal rows of PS3.15 Table E.1-1 that this
  * run's options left actionable.** That is a **membership** bound rather than a
  * shape one - the posture this package already takes for a VR and for a Private
  * Creator - so what survives names a published table entry rather than a
@@ -2686,11 +3367,12 @@ interface EmbeddedAttributeFinding {
     readonly contextPath?: readonly string[];
 }
 /**
- * One Sequence-of-Items carrier that was emptied because this run had no item
- * stream to walk, so the de-identifier had no Data Sets to reach.
+ * One carrier this run could not reach the Data Sets inside, and **emptied** for
+ * it. {@link UnauditableSequenceFinding.applied} names that outcome and is the
+ * field to read first; it is the only outcome this finding has.
  *
- * **Two producers, and the second is not a parsed `SQ`.** The ordinary one is an
- * `SQ` element whose `items` the parser never materialized. The other is a
+ * **Two producers, and neither ships bytes.** The ordinary one is an
+ * `SQ` element whose `items` the parser never materialized. The second is a
  * private data element retained under `RetainSafePrivate` whose `Profile` entry
  * declares it `SQ` while the parse tree says otherwise - `UN` under Implicit VR
  * LE when the profile was passed to `deidentify()` but not to `parseDicom`, or
@@ -2701,6 +3383,19 @@ interface EmbeddedAttributeFinding {
  * parsed VR in the output and is emptied rather than re-typed to `SQ`
  * (`DICOM-PRIVATE-SQ-PARSE-VR`).
  *
+ * **🛑 THERE WAS A THIRD PRODUCER AND IT IS RETIRED: `applied: "kept"` IS GONE
+ * FROM THIS TYPE AND FROM EVERY RUN.** Through `0.0.19` a private data element
+ * the profile vouched for whose value this run never enumerated was **retained
+ * verbatim** and named here with `applied: "kept"` - the package reporting that
+ * it had shipped a value it did not read. Such an instance is now **removed**
+ * instead, and its record moved to
+ * {@link DeidentifyReport.unenumerablePrivateRemovals}, which is a different
+ * surface with a different guarantee: uncapped, complete, and stating a reason.
+ * This array never carries a retained private value again, so an entry here
+ * always means content is **not** in your output. That is an audit-contract
+ * change for anyone who switched on `applied`; see
+ * {@link UnenumerablePrivateRemoval}.
+ *
  * 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
@@ -2749,9 +3444,26 @@ interface EmbeddedAttributeFinding {
  * ```
  */
 interface UnauditableSequenceFinding {
-    /** The `SQ` element that was emptied. */
+    /** The carrier element. */
     readonly tag: Tag;
-    /** Byte length of the value field that was dropped. Structural, never a value. */
+    /**
+     * What happened to that carrier's value: `"emptied"`, always. The value is not
+     * in the de-identified output.
+     *
+     * **🛑 `"kept"` WAS A MEMBER OF THIS UNION AND IS NOT ANY MORE.** It meant "the
+     * value IS in the output, byte for byte, unexamined", and a report field that
+     * can say so is exactly what this package no longer does: that instance is
+     * removed now and recorded on
+     * {@link DeidentifyReport.unenumerablePrivateRemovals}. The field itself is
+     * kept, so `applied === "emptied"` keeps compiling and keeps meaning what it
+     * always meant; a comparison against `"kept"` does not compile any more, which
+     * is the intended way to find out.
+     */
+    readonly applied: "emptied";
+    /**
+     * Byte length of the carrier's value field that was **dropped**. Structural,
+     * never a decoded value.
+     */
     readonly byteLength: number;
     /**
      * Tag/index chain when the carrier is inside a sequence item; omitted at the
@@ -2763,6 +3475,128 @@ interface UnauditableSequenceFinding {
      */
     readonly contextPath?: readonly string[];
 }
+/**
+ * One private attribute **removed** because this run did not enumerate its
+ * value - the record that discharges the audit half of the fail-safe, and the
+ * one report surface that is complete at any input size.
+ *
+ * ## What "enumerated" means here, and what it deliberately does not
+ *
+ * A run has enumerated a private value when it **walked it as DICOM Data
+ * Elements** and put each of them through the Annex E action table (a private
+ * `SQ` the parser materialized items for), when the whole value **was matched
+ * as a member of a closed table the caller supplied** (a Private Creator
+ * `(gggg,00EE)` whose decoded value is in the profile's private dictionary), or
+ * when the value is **zero-length** and so encodes no Data Set. Nothing else.
+ *
+ * **🛑 DECODING A VALUE UNDER THE VR THE PROFILE RESOLVED FOR IT IS NOT
+ * ENUMERATION, AND NEITHER IS THE EMBEDDED-ATTRIBUTE SCANNER'S SILENCE.** A
+ * decoded `LO`, `ST`, `OB`, `OW` or `UN` value is a byte run that can carry a
+ * Data Set written in a transfer syntax this run never tested for; two cells of
+ * the matrix in `test/integration/deident-private-reservation.test.ts` are
+ * perfectly scannable Implicit VR LE string carriers whose values the scanner
+ * DID read and found nothing in, and which carried a nested `(0010,0010)`
+ * anyway, because the nested tiles are Explicit VR and the file is Implicit. So
+ * the predicate is **what the run did with the value**, never the VR and never
+ * the scanner's reach.
+ *
+ * ## The cost, stated at its real size
+ *
+ * With `RetainSafePrivate` plus a `Profile`, three classes of private value
+ * reach the output on something this run enumerated: an instance the run walked
+ * as Data Elements, a Private Creator the profile's dictionary vouches for, and
+ * a zero-length value. **An ordinary vendor scalar under an ordinary string VR
+ * that the file's own declaration does not name safe is removed**, because
+ * this package enumerates nothing inside a retained private value that is not
+ * one of those three. That is over-redaction traded for a closed identity leak:
+ * PS3.15 2026c §E.3.10 retains Private Attributes "known by the de-identifier to
+ * be safe from identity leakage" and sends "all other Private Attributes" to
+ * removal or to the `(0008,0307)` element-specific action, which this library
+ * does not implement - and a value nothing enumerated is not known to be safe
+ * however ordinary it looks. Through `0.0.19` such a value was **kept** and
+ * disclosed instead; the disclosure said outright that it was not a fix.
+ *
+ * ## 🩺 The fourth class, which this record never names
+ *
+ * A private value reaches the output on one more route, and it is the one that
+ * rests on no enumeration at all: the **file's own** Private Data Element
+ * Characteristics Sequence (0008,0300), which §E.3.10 names first among the ways
+ * an Attribute is known safe and which needs no `Profile`. A value in a block
+ * whose Block Identifying Information Status (0008,0303) reads `SAFE`, or listed
+ * in a `MIXED` block's Nonidentifying Private Elements (0008,0304), is retained
+ * unexamined on the **sender's** written assertion, so it is never removed and
+ * never appears here. That is the opposite trade from the one above, made in the
+ * open: the caller who does not trust the sender leaves `RetainSafePrivate` off,
+ * which is the one mitigation §E.3.10 offers.
+ *
+ * ## Per INSTANCE, never per tag
+ *
+ * An entry names one **occurrence**: a tag together with the Data Set it lived
+ * in, which `contextPath` identifies (absent means the root Data Set). Private
+ * blocks are reserved per Data Set (PS3.5 §7.8.1), so the same private tag can
+ * occur several times in one object with different enumerability, and removing
+ * one occurrence never removes a sibling one.
+ *
+ * ## Uncapped, and that is a decision rather than an oversight
+ *
+ * Every consumer-controlled **diagnostic** in this package is capped, because a
+ * finding emitted per element is amplified by an element count the input
+ * chooses. This is not a diagnostic: it is the record of an **action**, on the
+ * same footing as {@link DeidentifyReport.removedPrivateTags}, which is uncapped
+ * for the same reason. A caller's whole guarantee is that they can separate the
+ * unenumerable removals from the Annex E ones for **every** removal, so a cap
+ * here would silently take the guarantee away exactly on the files that need it
+ * most. The matching warnings stay bounded; this array does not.
+ *
+ * ## What it carries, and what that is worth logging
+ *
+ * `tag` is composed from four bytes of the source. On a well-formed file it is
+ * the sender's own private tag number and carries nothing, but on a file whose
+ * Value Lengths disagree with its bytes those four bytes can be document
+ * content - the standing exception {@link DeidentifyReport.removedPrivateTags}
+ * and {@link UnauditableSequenceFinding} already carry, by the same route, and
+ * `contextPath` is unbound in the same way. It is published anyway, because
+ * *which* attribute was removed and *where* is the whole audit value of the
+ * record. Treat this array as PHI when the source is untrusted.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom, type UnenumerablePrivateRemoval } from "@cosyte/dicom";
+ * const { report } = deidentify(parseDicom(buf), { retain: ["RetainSafePrivate"], profile });
+ * report.unenumerablePrivateRemovals.forEach((r: UnenumerablePrivateRemoval) => {
+ *   console.warn(`${r.tag} ${r.applied} (${r.reason})`, r.contextPath ?? "root");
+ * });
+ * ```
+ */
+interface UnenumerablePrivateRemoval {
+    /** The removed instance's tag. */
+    readonly tag: Tag;
+    /**
+     * The outcome, always `"removed"`: the Data Set that held this instance
+     * carries no element bearing that tag, in the returned dataset and in the
+     * serialized bytes. Distinct from **emptied**, where an element with that tag
+     * is present carrying a zero-length value.
+     */
+    readonly applied: "removed";
+    /**
+     * Why, always `"unenumerable"`: this run did not enumerate the value, so
+     * PS3.15 §E.3.10's "known ... to be safe" was never established for it. This
+     * is what separates an entry here from an attribute the Annex E action table
+     * removed (`report.attributes`, `applied: "removed"`) and from one whose value
+     * was emptied.
+     */
+    readonly reason: "unenumerable";
+    /**
+     * Tag/index chain naming the Data Set this instance lived in; **omitted at the
+     * root**, which is what identifies the removal as per-instance rather than
+     * per-tag. **Built by the same descent as
+     * {@link DeidentifiedAttribute.contextPath} and carrying the same caveat:
+     * each segment's tag is read off the wire, bound by nothing, so on a
+     * desynchronized read it can be four bytes of a value.** Read that field's
+     * note before logging this one.
+     */
+    readonly contextPath?: readonly string[];
+}
 /**
  * One 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
@@ -2877,6 +3711,214 @@ interface UndefinedVrFinding {
      */
     readonly contextPath?: readonly string[];
 }
+/**
+ * One non-modeled `(0002,xxxx)` File Meta element `deidentify()` **dropped**
+ * rather than re-emitting into de-identified output.
+ *
+ * ## Why the drop is unconditional
+ *
+ * PS3.15 2026c §E.1.1 requires the File Meta Information of a de-identified
+ * DICOM File to "be replaced with a description of the de-identifying
+ * application", because otherwise "identity information may leak through
+ * unmodified File Meta Information ... [t]his includes information regarding
+ * Application Entity Titles, Presentation Addresses, implementation
+ * information, and private information". A non-modeled `(0002,xxxx)` element is
+ * by definition one this library cannot describe: `(0002,0017)` Sending AE
+ * Title, `(0002,0018)` Receiving AE Title, `(0002,0100)` Private Information
+ * Creator UID and `(0002,0102)` Private Information are all in that class, and
+ * so is anything a vendor invented. The fail-safe direction is to drop what
+ * cannot be described, so no Annex E Option and no parse quality changes the
+ * outcome.
+ *
+ * ## Capped record, complete count
+ *
+ * The array is bounded per run (`MAX_FILE_META_DROP_FINDINGS`) because the
+ * number of elements a crafted File Meta group can carry is chosen by the input.
+ * The **action** is not bounded: every such element is dropped whether or not it
+ * is listed, and {@link DeidentifyReport.fileMetaElementsDroppedCount} is the
+ * complete total at any input size. An array exactly the cap's length means "at
+ * least this many"; read the count, not the length.
+ *
+ * ## What it carries
+ *
+ * `tag` and `vr` come off the wire. The File Meta pre-pass stops at the first
+ * element whose group is not `0002`, so a tag reaching this record always has
+ * `0002` as its group, but its element number is two bytes the file supplied and
+ * a File Meta element that over-declared its length can desynchronize the
+ * pre-pass onto two bytes of somebody's value. Same standing exception as
+ * {@link DeidentifyReport.removedPrivateTags}, by a narrower route and with two
+ * bytes rather than four. `byteLength` is the length of the value that was
+ * dropped, read off that same header. It is published because *what* was dropped
+ * is the whole audit value of a record of a deliberate fidelity loss.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom, type FileMetaDroppedElement } from "@cosyte/dicom";
+ * const { report } = deidentify(parseDicom(buf));
+ * report.fileMetaElementsDropped.forEach((d: FileMetaDroppedElement) => {
+ *   console.warn(`${d.tag} ${d.vr}: ${String(d.byteLength)} bytes not re-emitted`);
+ * });
+ * ```
+ */
+interface FileMetaDroppedElement {
+    /** The dropped element's `(0002,xxxx)` tag. */
+    readonly tag: Tag;
+    /** The VR the source file wrote for it (the File Meta group is Explicit VR LE). */
+    readonly vr: VR;
+    /** Byte length of the value that is not in the de-identified output. */
+    readonly byteLength: number;
+}
+/**
+ * One Data Element whose Group Number is `0004`, **removed** from de-identified
+ * output.
+ *
+ * ## The rule, and the one object it does not apply to
+ *
+ * PS3.15 2026c §E.1.1: "All Data Elements with a Group Number of 0004 shall be
+ * removed from any SOP Instance or DICOM File other than a DICOMDIR File." The
+ * rule is unconditional over the Annex E Options - it sits in the list §E.1.1
+ * imposes on any de-identifier claim and no Option qualifies it - so no
+ * `retain` argument brings a `(0004,xxxx)` element back.
+ *
+ * The DICOMDIR carve-out is decided once per run from the source File Meta's
+ * `(0002,0002)` Media Storage SOP Class UID, and only the value
+ * `1.2.840.10008.1.3.10` (Media Storage Directory Storage) selects it. An object
+ * that declares no Media Storage SOP Class UID at all is therefore **not** a
+ * DICOMDIR and the removal applies to it. When the carve-out does fire, this
+ * array is empty and `DICOM_DEIDENT_DICOMDIR_FILE_SET_NOT_DISCHARGED` says what
+ * else the run did not do.
+ *
+ * ## Every depth, and the removal decides nothing below it
+ *
+ * The test runs on each element of each Data Set the run reaches, root and
+ * Sequence Item alike, so a `(0004,xxxx)` planted inside an item is removed
+ * there too. It is a test on **one element's tag**: it never stands in for a
+ * decision about the Data Sets nested inside some other element, which is the
+ * shape `DICOM-PRIVATE-SQ-CARVE-OUT` was opened for. Removing a `(0004,xxxx)`
+ * that is itself a Sequence removes its items with it, exactly as a Table E.1-1
+ * `X` action does.
+ *
+ * ## Capped record, complete count
+ *
+ * Bounded per run at `MAX_GROUP_0004_FINDINGS`, on its own counter so a flood of
+ * one diagnostic class cannot spend another's budget. The removal itself is not
+ * bounded, and {@link DeidentifyReport.group0004RemovalCount} is complete at any
+ * input size.
+ *
+ * ## What it carries
+ *
+ * `tag` is composed from four bytes of the source and `contextPath` from four
+ * more per segment - the standing exception
+ * {@link DeidentifyReport.removedPrivateTags} and
+ * {@link UnauditableSequenceFinding} already carry, by the same route. On a
+ * well-formed file these are the DICOMDIR directory-structuring tags PS3.6
+ * registers and carry nothing.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom, type Group0004Removal } from "@cosyte/dicom";
+ * const { report } = deidentify(parseDicom(buf));
+ * report.group0004Removals.forEach((r: Group0004Removal) => {
+ *   console.warn(`${r.tag} removed`, r.contextPath ?? "root");
+ * });
+ * ```
+ */
+interface Group0004Removal {
+    /** The removed element's tag. Its group is always `0004`. */
+    readonly tag: Tag;
+    /**
+     * The outcome, always `"removed"`: no element bearing that tag is in the Data
+     * Set that held it, in the returned dataset or in the serialized bytes.
+     */
+    readonly applied: "removed";
+    /**
+     * Tag/index chain when the element was inside a sequence item; omitted at the
+     * root. **Built by the same descent as
+     * {@link DeidentifiedAttribute.contextPath} and carrying the same caveat:
+     * each segment's tag is read off the wire, bound by nothing, so on a
+     * desynchronized read it can be four bytes of a value.** Read that field's
+     * note before logging this one.
+     */
+    readonly contextPath?: readonly string[];
+}
+/**
+ * One non-private Data Element **removed** because this build's PS3.6 2026d
+ * registry does not carry its tag and PS3.15 2026d Table E.1-1 does not list it.
+ *
+ * ## The rule
+ *
+ * A Table E.1-1 miss used to mean "keep": an attribute the table does not list
+ * went into de-identified output verbatim with a report that said nothing about
+ * it. That is right for an attribute PS3.6 registers, which the Profile has
+ * judged, and wrong for one it does not: the notes to PS3.15 2026d Table E.1-1
+ * name "new Standard Attributes" among the places identifying information may
+ * be, and say removing only the known risks "may fail when the Standard is
+ * extended, or when a vendor adds unanticipated Standard Attributes". So an
+ * even-group tag with **no registry row and no Table E.1-1 row** is removed, at
+ * every depth `deidentify()` walks, whatever its VR (`UN`, an on-wire VR outside
+ * the 34 PS3.5 section 6.2 defines, and `SQ` included; a Sequence goes whole and
+ * nothing inside it is walked or recorded).
+ *
+ * "Registered" means a literal PS3.6 row, or a masked row the tag matches, with
+ * the `50xx` / `60xx` groups bounded by PS3.5 2026c section 7.6 (even groups
+ * `5000`-`501E` and `6000`-`601E`). Private tags, group `0004`, group `0002`,
+ * group lengths `(gggg,0000)` and every tag Table E.1-1 lists are not decided by
+ * this rule.
+ *
+ * ## What it costs
+ *
+ * **A conformant attribute from a PS3.6 edition newer than this build's pin is
+ * removed too**, because nothing separates it from an invented one. That is
+ * over-redaction and it is deliberate; a caller who needs such an attribute back
+ * has no switch for it in this release.
+ *
+ * ## What it carries, and what it deliberately does not
+ *
+ * **No tag and no VR.** The trigger is "no registry row carries this tag", and
+ * four bytes an under-declared length upstream made the reader take as a header
+ * satisfy it by construction: the fixture in
+ * `test/integration/deident-undefined-vr.test.ts` fabricates `(4854,4F53)`,
+ * `"THSO"` in wire order, four letters of a surname. Publishing the tag would
+ * republish them, so the element is identified by `byteOffset`, a position this
+ * parser counted, exactly as {@link UndefinedVrFinding} does.
+ *
+ * `contextPath` names the Sequences this run **descended** to reach the
+ * element, never the removed element itself, and carries the caveat every
+ * finding's `contextPath` carries: see {@link DeidentifiedAttribute.contextPath}.
+ *
+ * ## Capped record, complete count
+ *
+ * Bounded per run at `MAX_UNREGISTERED_ELEMENT_FINDINGS`, on its own counter so
+ * a flood of one diagnostic class cannot spend another's budget. The removal
+ * itself is not bounded, and
+ * {@link DeidentifyReport.unregisteredElementRemovalCount} is complete at any
+ * input size.
+ *
+ * @example
+ * ```ts
+ * import { deidentify, parseDicom, type UnregisteredElementRemoval } from "@cosyte/dicom";
+ * const { report } = deidentify(parseDicom(buf));
+ * report.unregisteredElementRemovals.forEach((r: UnregisteredElementRemoval) => {
+ *   console.warn(`removed at offset ${String(r.byteOffset)}`, r.contextPath ?? "root");
+ * });
+ * ```
+ */
+interface UnregisteredElementRemoval {
+    /**
+     * Byte offset of the removed element's header, as the parser recorded it on
+     * `Element.byteOffset`. **This is how the element is identified, and there is
+     * deliberately no `tag` field**: see the note above.
+     */
+    readonly byteOffset: number;
+    /**
+     * Tag/index chain when the element was inside a sequence item; omitted at the
+     * root. **Built by the same descent as
+     * {@link DeidentifiedAttribute.contextPath} and carrying the same caveat:
+     * each segment's tag is read off the wire.** Read that field's note before
+     * logging this one.
+     */
+    readonly contextPath?: readonly string[];
+}
 /**
  * The audit trail returned alongside the de-identified dataset.
  *
@@ -2900,13 +3942,18 @@ interface UndefinedVrFinding {
  *   theoretical.
  * - **`unauditableSequences[].tag`** - see
  *   {@link UnauditableSequenceFinding}. Same shape as `removedPrivateTags` by a
- *   narrower route: a private carrier a {@link Profile} declares `SQ` is named
- *   there, and an under-declared length upstream can resynchronize the reader
- *   onto four bytes that spell such a block. The package's usual answer to a
+ *   narrower route: a private carrier a {@link Profile} vouched for and this run
+ *   emptied is named there, and an under-declared length upstream can
+ *   resynchronize the reader onto four bytes that spell such a block. The
+ *   package's usual answer to a
  *   fabricated header, `undefinedVrElements`, carries a byte offset and no tag,
  *   and still answers it whenever the fabricated VR is outside the 34 PS3.5
  *   §6.2 defines. It cannot when the fabricated VR is one of them, because those
  *   two files are byte-identical.
+ * - **`unenumerablePrivateRemovals[].tag`** - see
+ *   {@link UnenumerablePrivateRemoval}. The same four bytes by the same route,
+ *   on the record of the removal rather than of an emptying, and this one is
+ *   **uncapped** because it is the record of an action rather than a diagnostic.
  * - **`undefinedVrElements[].byteLength` and
  *   `unauditableSequences[].byteLength`** - the declared Value Length read off
  *   the element header, so on a fabricated header it is four document bytes
@@ -2919,7 +3966,17 @@ interface UndefinedVrFinding {
  *   them is a product call rather than a defect fix: a bound empties the field
  *   on every well-formed file, where the number is exactly the audit
  *   information it exists to carry.
- * - **`contextPath`, on all four findings that carry one** - see
+ * - **`group0004Removals[].tag`** - see {@link Group0004Removal}. The same four
+ *   bytes by the same route as `removedPrivateTags`, on the record of a removal
+ *   PS3.15 §E.1.1 requires. On a well-formed file these are PS3.6's registered
+ *   DICOMDIR directory-structuring tags and carry nothing.
+ * - **`fileMetaElementsDropped[].tag` and `.vr`** - see
+ *   {@link FileMetaDroppedElement}. Two bytes rather than four: the File Meta
+ *   pre-pass stops at the first non-`0002` group, so the group half of the tag
+ *   is fixed and only the element number is free, and the VR is two more bytes
+ *   the same desynchronized read would supply. `.byteLength` joins
+ *   `undefinedVrElements[].byteLength` in the entry above by the same route.
+ * - **`contextPath`, on every finding that carries one** - see
  *   {@link DeidentifiedAttribute.contextPath}, which holds the measurement. The
  *   segment tags come off the wire with no table behind them, so a fabricated
  *   `SQ` header the reader descended is named there, `PRE-EXISTING`, with **no
@@ -2954,7 +4011,14 @@ interface DeidentifyReport {
     /** Per-attribute outcomes for every attribute Annex E acted on. */
     readonly attributes: readonly DeidentifiedAttribute[];
     /**
-     * Private tags removed under the Basic Profile (kept ones are omitted).
+     * Private tags removed (kept ones are omitted) - **every one of them,
+     * whichever rule removed it**: the Basic Profile's default removal, a
+     * reservation the file did not settle, and, since the unenumerable class
+     * became a removal, a private attribute this run did not enumerate. Its
+     * meaning is unchanged and it is still uncapped; what it does not carry is a
+     * **reason**, which is why the unenumerable removals are also recorded on
+     * {@link DeidentifyReport.unenumerablePrivateRemovals}, where they can be told
+     * apart from the rest.
      *
      * **This is the second field that is not value-free, and the qualification is
      * measured.** A tag here is composed from four bytes of the source, and on a
@@ -2981,18 +4045,33 @@ interface DeidentifyReport {
      */
     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}.
+     * Carriers whose nested Data Sets this run could not reach and **emptied** for
+     * it: an `SQ` whose items the parser did not materialize, so the run had no
+     * Data Sets to walk and could not discharge PS3.15 §E.1.1's obligation inside
+     * them, and a private carrier a {@link Profile} declares `SQ` that the parse
+     * tree resolved otherwise. Content was dropped from the de-identified output,
+     * and for the first producer the matching `DICOM_SQ_NOT_DESCENDED` entry on
+     * `Dataset.warnings` says why the parse refused.
+     *
+     * 🛑 **THIS ARRAY NO LONGER PRODUCES `applied: "kept"`, AND THAT IS AN
+     * AUDIT-CONTRACT CHANGE.** A private attribute retained under
+     * `RetainSafePrivate` whose value this run never enumerated used to be listed
+     * here, kept verbatim, with the array saying so. That instance is **removed**
+     * now and recorded on
+     * {@link DeidentifyReport.unenumerablePrivateRemovals}. An entry here has one
+     * meaning again: this content is **not** in your output.
+     *
+     * **Empty on a well-formed file**, including one whose private attributes a
+     * profile vouches for. It stopped being populated by ordinary conformant files
+     * when the retained class left it.
      *
      * **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.
+     * carrier is still emptied whether or not it is listed; an array exactly that
+     * long means "at least this many", so read it as truncated rather than as a
+     * total. The unenumerable **removals** are budgeted apart from it and their
+     * record is not capped at all.
      *
      * **It covers private sequences too, since `DICOM-PRIVATE-SQ-CARVE-OUT`.** A
      * private `SQ` a {@link Profile} vouches for under `RetainSafePrivate` used to
@@ -3001,6 +4080,34 @@ interface DeidentifyReport {
      * is over a private attribute and not over an item stream nothing could read.
      */
     readonly unauditableSequences: readonly UnauditableSequenceFinding[];
+    /**
+     * Private attributes **removed because this run did not enumerate their
+     * value** - one entry per instance, naming the tag, the outcome (`"removed"`),
+     * the reason (`"unenumerable"`) and the Data Set it lived in.
+     *
+     * **This is the surface the fail-safe's audit half is built on, and it is the
+     * one array on this report that is never capped or truncated.** A caller can
+     * separate, from this record alone and for every such removal at any input
+     * size, the attributes removed for being unenumerable from the attributes
+     * removed by the Annex E action table (`report.attributes`) and from the ones
+     * whose value was emptied. The matching warnings ARE bounded, so past their
+     * cap this record is the only complete account and the diagnostics are the
+     * bounded one.
+     *
+     * **Empty unless `RetainSafePrivate` plus a `Profile` is active**, because
+     * without both nothing private is retained far enough to be judged: the Basic
+     * Profile removes every private attribute and names it in
+     * {@link DeidentifyReport.removedPrivateTags} instead. A profile lookup that
+     * **misses** is that case too, and never appears here. **The file's own
+     * (0008,0300) declaration does not populate it either**, and that is not an
+     * omission: a value that declaration covers is one §E.3.10 says the run knows
+     * about, so it is retained rather than reaching this rule at all.
+     *
+     * See {@link UnenumerablePrivateRemoval} for what counts as enumeration, for
+     * the over-redaction this costs, and for why it names an instance rather than
+     * a tag.
+     */
+    readonly unenumerablePrivateRemovals: readonly UnenumerablePrivateRemoval[];
     /**
      * 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
@@ -3040,6 +4147,82 @@ interface DeidentifyReport {
      * because a vouched-for private `SQ` is routed into the ordinary `SQ` branches.
      */
     readonly undefinedVrElements: readonly UndefinedVrFinding[];
+    /**
+     * Non-modeled `(0002,xxxx)` File Meta elements this run **dropped** instead of
+     * re-emitting, because the de-identified File Meta group describes this
+     * de-identifying application rather than the source (PS3.15 §E.1.1). Empty
+     * when the source group held only modeled elements, and empty when the source
+     * parsed with no File Meta group at all.
+     *
+     * **This is the record of a deliberate fidelity loss, not of a defect.** The
+     * byte-for-byte File Meta round trip `FileMeta.extraElements` documents is
+     * scoped to parse-then-serialize and does not hold here.
+     *
+     * **Capped; the count beside it is not.** See {@link FileMetaDroppedElement}
+     * and {@link DeidentifyReport.fileMetaElementsDroppedCount}.
+     */
+    readonly fileMetaElementsDropped: readonly FileMetaDroppedElement[];
+    /**
+     * How many non-modeled `(0002,xxxx)` elements this run dropped, **complete at
+     * any input size**.
+     *
+     * The field exists because its sibling array is capped: a caller that needs to
+     * *count* the fidelity loss cannot get the number from an array whose length
+     * saturates, and re-parsing the output does not give it either - the elements
+     * are gone from the output by design. One number cannot be inflated by an
+     * attacker-chosen element count, so bounding it would buy nothing.
+     */
+    readonly fileMetaElementsDroppedCount: number;
+    /**
+     * Data Elements whose Group Number is `0004`, **removed** at every depth this
+     * run reached, as PS3.15 §E.1.1 requires "from any SOP Instance or DICOM File
+     * other than a DICOMDIR File".
+     *
+     * Empty when the object carried none, and empty when it declared Media Storage
+     * SOP Class UID `1.2.840.10008.1.3.10` - the carve-out, which is disclosed on
+     * {@link DeidentifyReport.warnings} as
+     * `DICOM_DEIDENT_DICOMDIR_FILE_SET_NOT_DISCHARGED` rather than left to be
+     * inferred from an empty array.
+     *
+     * **Capped; the count beside it is not.** See {@link Group0004Removal} and
+     * {@link DeidentifyReport.group0004RemovalCount}.
+     */
+    readonly group0004Removals: readonly Group0004Removal[];
+    /**
+     * How many `(0004,xxxx)` elements this run removed, **complete at any input
+     * size**, for the reason
+     * {@link DeidentifyReport.fileMetaElementsDroppedCount} states.
+     *
+     * It is also the field that tells the two §E.1.1 rules apart at a glance: this
+     * one counts group-0004 removals, the other counts File Meta drops, and
+     * neither can be read off the other.
+     */
+    readonly group0004RemovalCount: number;
+    /**
+     * Non-private Data Elements **removed** at every depth this run reached
+     * because this build's PS3.6 2026d registry does not carry their tag and Table
+     * E.1-1 does not list it. See {@link UnregisteredElementRemoval} for the rule,
+     * for what it costs on a newer-edition file, and for why an entry names a byte
+     * offset and no tag.
+     *
+     * Empty on a run that removed none. A separate record from
+     * {@link DeidentifyReport.attributes}, {@link DeidentifyReport.removedPrivateTags},
+     * {@link DeidentifyReport.group0004Removals} and
+     * {@link DeidentifyReport.undefinedVrElements}: an element removed here is on
+     * none of those.
+     *
+     * **Capped; the count beside it is not.** See
+     * {@link DeidentifyReport.unregisteredElementRemovalCount}.
+     */
+    readonly unregisteredElementRemovals: readonly UnregisteredElementRemoval[];
+    /**
+     * How many elements this run removed under the rule
+     * {@link DeidentifyReport.unregisteredElementRemovals} records, **complete at
+     * any input size**, for the reason
+     * {@link DeidentifyReport.fileMetaElementsDroppedCount} states. `0` on a run
+     * that removed none.
+     */
+    readonly unregisteredElementRemovalCount: number;
     /**
      * Source UID → replacement UID, for cross-file consistency. The **keys are
      * document values**, not composed identifiers: this is the one field of the
@@ -3051,11 +4234,13 @@ interface DeidentifyReport {
     /**
      * 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.
+     * **Not a list of what survived.** Registered attributes Table E.1-1 does not
+     * list are kept without appearing anywhere in this field - `(0012,0063)`
+     * De-identification Method and the prior Items of `(0012,0064)`
+     * De-identification Method Code Sequence are the ones whose retention is
+     * disclosed, as `DICOM_DEIDENT_METHOD_PRIOR_RETAINED` and
+     * `DICOM_DEIDENT_METHOD_CODES_PRIOR_RETAINED` on
+     * {@link DeidentifyReport.warnings}, because neither is an option set.
      */
     readonly retained: readonly DeidentifyOption[];
 }
@@ -3083,22 +4268,47 @@ interface DeidentifyOptions {
      */
     readonly uidMap?: Map<string, string>;
     /**
-     * A Phase 6 {@link Profile} whose private-dictionary overlay names the
+     * A {@link Profile} whose private-dictionary overlay names the
      * known-safe private attributes to keep when `RetainSafePrivate` is active.
-     * Without it, `RetainSafePrivate` keeps nothing (fail-safe).
+     *
+     * **Not the only way an attribute is known safe, and no longer required for
+     * `RetainSafePrivate` to keep anything.** PS3.15 2026c §E.3.10 lists four ways
+     * that knowledge may be established and a profile is two of them
+     * (Conformance Statement documentation, and "some other means"); the first is
+     * the **file's own** Private Data Element Characteristics Sequence
+     * (0008,0300), which `deidentify()` reads when this Option is active whether
+     * or not a profile is passed. So a file from a vendor you hold no profile for
+     * keeps the private attributes **that file declares** non-identifying, and
+     * passing a profile only ever adds to that: a profile retention survives a
+     * block the declaration calls `UNSAFE` or says nothing about.
+     *
+     * 🩺 **What the declaration route retains rests on the SENDER's assertion.**
+     * The system that wrote the file said those blocks carry no identifying
+     * information; nothing here re-derives it, and an opaque value in a block
+     * declared `SAFE` reaches de-identified output unexamined. If you do not trust
+     * the sender, leave `RetainSafePrivate` off - §E.3.10's own alternative, and
+     * the only mitigation the standard offers.
+     *
+     * With neither this nor a declaration in the file, `RetainSafePrivate` keeps
+     * nothing (fail-safe).
      */
     readonly profile?: Profile;
     /**
      * Text **added to** `(0012,0063)` De-identification Method. Default names the
      * Basic Profile and the active options.
      *
+     * **It never changes `(0012,0064)`.** The CID 7050 codes the run writes there
+     * follow the options that ran, and free text cannot alter what ran; see
+     * `DEIDENTIFICATION_METHOD_CODES`.
+     *
      * **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.
+     * every option name published at that time, 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, but it is no longer silent.** A value of
      * your own longer than 64 characters is written through as given - it is
@@ -3175,14 +4385,27 @@ interface DeidentifyResult<TDataset> {
 /**
  * Stable codes for {@link DeidentifyError}.
  *
+ * - `INVALID_OPTIONS`: an author-time misconfiguration of the call itself (an
+ *   unknown Retain option, both PS3.15 §E.3.6 temporal Options at once, a
+ *   malformed `uidRoot`).
+ * - `UNSUPPORTED_TRANSFER_SYNTAX`: the Dataset's File Meta Transfer Syntax UID
+ *   is one this de-identifier refuses to act on, whatever the options. Today
+ *   that is exactly the four JPIP Referenced syntaxes of PS3.5 2026c sections
+ *   A.6, A.7, A.11 and A.12: such an object references its pixels through
+ *   Pixel Data Provider URL `(0028,7FE0)`, which has no PS3.15 Table E.1-1 row,
+ *   so a de-identified copy would keep the URL by omission. Nothing is
+ *   de-identified and no dataset or report is returned.
+ *
  * @example
  * ```ts
  * import { DEIDENTIFY_ERROR_CODES } from "@cosyte/dicom";
  * DEIDENTIFY_ERROR_CODES.INVALID_OPTIONS; // "INVALID_OPTIONS"
+ * DEIDENTIFY_ERROR_CODES.UNSUPPORTED_TRANSFER_SYNTAX; // "UNSUPPORTED_TRANSFER_SYNTAX"
  * ```
  */
 declare const DEIDENTIFY_ERROR_CODES: Readonly<{
     readonly INVALID_OPTIONS: "INVALID_OPTIONS";
+    readonly UNSUPPORTED_TRANSFER_SYNTAX: "UNSUPPORTED_TRANSFER_SYNTAX";
 }>;
 /**
  * One of the {@link DEIDENTIFY_ERROR_CODES} values.
@@ -3196,11 +4419,16 @@ declare const DEIDENTIFY_ERROR_CODES: Readonly<{
  */
 type DeidentifyErrorCode = (typeof DEIDENTIFY_ERROR_CODES)[keyof typeof DEIDENTIFY_ERROR_CODES];
 /**
- * Thrown for an author-time misconfiguration of {@link deidentify} (an unknown
- * Retain option, a malformed UID root). Distinct from the parser's fatal codes,
- * the value layer's `DicomValueError`, and the serializer's `DicomSerializeError`.
- * The message carries only structural facts (option names, the UID root) - never
- * a decoded value.
+ * Thrown by {@link deidentify} when it will not de-identify, for one of two
+ * reasons a caller tells apart by `code` (see {@link DEIDENTIFY_ERROR_CODES}):
+ * an author-time misconfiguration of the call (`INVALID_OPTIONS`: an unknown
+ * Retain option, a malformed UID root), or a Dataset under a Transfer Syntax this
+ * de-identifier refuses (`UNSUPPORTED_TRANSFER_SYNTAX`: the four JPIP Referenced
+ * syntaxes). Distinct from the parser's fatal codes, the value layer's
+ * `DicomValueError`, and the serializer's `DicomSerializeError`. The message
+ * carries only structural facts (option names, the UID root) or a fixed string -
+ * never a decoded value, and for `UNSUPPORTED_TRANSFER_SYNTAX` nothing read from
+ * the Dataset at all.
  *
  * @example
  * ```ts
@@ -3245,17 +4473,41 @@ declare class DeidentifyError extends Error {
  *   exact-tag miss. A match is removed *and* reported, with
  *   `DeidentifiedAttribute.repeatingGroup` naming the mask.
  * - Recurses into kept sequences and **re-encodes** them so nested PHI is removed
- *   in the *serialized* bytes too - not just the object model (the Phase 5 writer
+ *   in the *serialized* bytes too - not just the object model (the writer
  *   blits `SQ` spans verbatim, so a rebuilt `items` array alone would not survive
  *   serialization). Rebuilt sequences are normalized to defined length.
- * - Removes all private attributes by default; with `RetainSafePrivate` + a
- *   {@link Profile}, keeps the private data elements the profile's overlay names
- *   as safe (and the private-creator elements the profile recognizes).
+ * - Removes every non-private attribute Table E.1-1 does not list **and this
+ *   build's PS3.6 2026d registry does not carry** - a Standard Attribute from a
+ *   later edition, or one the sender invented - at every depth and whatever its
+ *   VR, recording it on `report.unregisteredElementRemovals` by byte offset and
+ *   never by tag. A registered attribute Table E.1-1 does not list is kept as it
+ *   always was. See {@link isUnregisteredStandardTag}.
+ * - Removes all private attributes by default. With `RetainSafePrivate` it keeps
+ *   the ones PS3.15 §E.3.10 lets it know are safe, by two routes that only ever
+ *   add to each other: the private data elements a caller {@link Profile}'s
+ *   overlay names as safe (and the private-creator elements it recognizes), and
+ *   the blocks the **file itself** declares non-identifying in Private Data
+ *   Element Characteristics Sequence `(0008,0300)`, which needs no profile. The
+ *   second one is the sender's assertion rather than this run's finding; see
+ *   {@link declaredSafe}.
+ * - Writes `(0028,0303)` Longitudinal Temporal Information Modified with the
+ *   state this run's option set put the object in: `UNMODIFIED` under
+ *   `RetainLongitudinalTemporal`, `MODIFIED` under
+ *   `RetainLongitudinalTemporalModifiedDates`, `REMOVED` under neither (PS3.15
+ *   §E.3.6 and §E.2). The two temporal Options are mutually exclusive and a call
+ *   naming both is rejected. **Replaced, not joined** - it is `VM 1`, so a prior
+ *   sender's declaration is discarded rather than appended to. `MODIFIED` says
+ *   the modified-dates column was resolved and **not** that this library
+ *   transformed a date, which it never does; see {@link TEMPORAL_STATE}.
  * - Remaps `(0002,0003)` Media Storage SOP Instance UID consistently (unless
  *   `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
+ *   `addDeidentificationMethod`), **adds** the PS3.16 CID 7050 codes for the
+ *   Profile and each active Option to `(0012,0064)` De-identification Method Code
+ *   Sequence, after any Items the file already carried there and without
+ *   repeating one it already records (see `addDeidentificationMethodCodes`), 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`).
@@ -3266,6 +4518,16 @@ declare class DeidentifyError extends Error {
  *   dummy is instead removed/emptied.
  * - `C` (clean) is a conservative blank, not a meaning-preserving structured
  *   replacement (which needs domain context the metadata layer lacks).
+ * - **A conformant attribute from a PS3.6 edition newer than this build's pin is
+ *   removed**, because it has no registry row here and nothing separates it from
+ *   an invented one. Over-redaction, deliberate, with no caller switch in this
+ *   release (`DICOM-DEIDENT-OVER-REDACTION`).
+ * - The temporal declaration is written at the **top level only**, which is where
+ *   §E.2 and §E.3.6 put it and where a recipient reads it. `(0028,0303)` has no
+ *   row in Table E.1-1, so a copy the sender nested inside a Sequence Item is
+ *   retained by omission like any other unlisted attribute and still says
+ *   whatever that sender wrote. Read the Data Set's own `(0028,0303)`, never a
+ *   nested one.
  * - Pixel-level options (`CleanPixelData`, `CleanRecognizableVisual`) are out of
  *   scope; burned-in text is warned, never cleaned.
  * - A private data element kept under `RetainSafePrivate` is kept *verbatim*
@@ -3283,6 +4545,22 @@ declare class DeidentifyError extends Error {
  *   wins). A carrier the profile declares `SQ` and the tree did not resolve is
  *   emptied rather than kept, keeping its parsed VR
  *   (`DICOM-PRIVATE-SQ-PARSE-VR`). See {@link keepRetainedPrivate}.
+ * - **A retained private value this run did not ENUMERATE is REMOVED**, named in
+ *   `report.removedPrivateTags` and recorded per instance in
+ *   `report.unenumerablePrivateRemovals` with its reason, under the existing
+ *   `DICOM_DEIDENT_PRIVATE_CARRIER_NOT_AUDITABLE` warning. Through `0.0.19` it
+ *   was kept verbatim and merely disclosed, which shipped a Data Set the sender
+ *   nested inside it into output stamped `(0012,0062) = YES` on a **fully
+ *   conformant** file. 🛑 **The cost is priced at its real size and is not a
+ *   corner of the option:** this package enumerates nothing inside a retained
+ *   private value beyond the classes named on
+ *   {@link removeUnenumerablePrivate}, so an ordinary vendor scalar under an
+ *   ordinary string VR that the file's own `(0008,0300)` declaration does not
+ *   name safe is removed too. Getting such a value back needs either a
+ *   declaration in the file - the sender's assertion, not an enumeration this
+ *   run performed - or the content test that separates a nested Data Set from a
+ *   legitimate binary blob, which is an open product question
+ *   (`DICOM-DEIDENT-OVER-REDACTION`).
  * - A `SQ` whose `items` the parser did not
  *   materialize is **emptied**, not kept:
  *   its value is by PS3.5 §7.5.1 a stream of Data Sets, and a run that cannot
@@ -3334,7 +4612,7 @@ declare class DeidentifyError extends Error {
  *   which removal is the branch available here (`(0008,0307)` is not
  *   implemented). Every private element the recursion **reaches** in such an
  *   Item, at any depth below it, is removed and named in
- *   `report.removedPrivateTags`. **The carve-out `#54` was refused for asserting
+ *   `report.removedPrivateTags`. **The carve-out an earlier review refused for asserting
  *   away is CLOSED** (`DICOM-PRIVATE-SQ-CARVE-OUT`): `keepsPrivate` still decides
  *   before the descent, but a **private `SQ`** it vouches for now routes through
  *   {@link keepRetainedPrivate} into the ordinary `SQ` branches instead of being
@@ -3374,8 +4652,33 @@ declare class DeidentifyError extends Error {
  * map. Everything in it is composed from static tables except `uidMap`, whose
  * keys are the source UIDs the file carried: treat that field as PHI.
  *
- * @throws {@link DeidentifyError} (`INVALID_OPTIONS`) for an unknown Retain option
- *   or a malformed `uidRoot`.
+ * The returned Data Set says what this run did to its **dates** as well as to its
+ * identity: `(0028,0303) Longitudinal Temporal Information Modified` carries
+ * `UNMODIFIED` when `RetainLongitudinalTemporal` was active, `MODIFIED` when
+ * `RetainLongitudinalTemporalModifiedDates` was, and `REMOVED` under neither,
+ * replacing any value the source carried at that tag. It is **not** on
+ * {@link DeidentifyReport} - like `(0012,0062)`, it is a statement the object
+ * makes about itself, and the report's shape is unchanged by it. 🩺 A
+ * `MODIFIED` means the modified-dates column was resolved; **you** perform the
+ * date transformation §E.3.6 describes, and `report.warnings` carries
+ * `DICOM_DEIDENT_DATES_NOT_TRANSFORMED` saying so.
+ *
+ * **A JPIP Referenced object is refused, not de-identified.** When
+ * `ds.fileMeta.transferSyntaxUID` is one of the four JPIP Referenced syntaxes
+ * (PS3.5 2026c sections A.6, A.7, A.11 and A.12), the call throws before it
+ * reads the options or the Data Set, because that object's Pixel Data Provider
+ * URL `(0028,7FE0)` has no PS3.15 Table E.1-1 action and would otherwise be kept
+ * by omission. The refusal keys on the File Meta alone: a non-JPIP object that
+ * carries `(0028,7FE0)` is de-identified like any other, and keeps it.
+ *
+ * @throws {@link DeidentifyError} (`UNSUPPORTED_TRANSFER_SYNTAX`) for a `Dataset`
+ *   whose File Meta Transfer Syntax UID is one of the four JPIP Referenced
+ *   syntaxes, whatever the options; its message is a fixed string. Checked
+ *   first, so it is the code such a call gets even when its options are
+ *   invalid too.
+ * @throws {@link DeidentifyError} (`INVALID_OPTIONS`) for an unknown Retain option,
+ *   for both PS3.15 §E.3.6 temporal Options in one call, or for a malformed
+ *   `uidRoot`.
  *
  * @example
  * ```ts
@@ -3451,4 +4754,90 @@ 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, type EmbeddedAttributeFinding, FATAL_CODES, type FatalCode, type FileMeta, type FileMetaRawElement, type FrameFunctionalGroups, type ImageView, Item, OFFSET_FRAMES, type OffsetFrame, 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 };
+/**
+ * PS3.16 2026d CID 7050 "De-identification Method", carried as pinned data, and
+ * the map from what a `deidentify()` run activated to the code it records.
+ *
+ * PS3.15 2026c §E.1.1: "one or more codes from CID 7050 "De-identification
+ * Method" corresponding to the Profile and Options used shall be added to
+ * De-identification Method Code Sequence (0012,0064), and/or a text string
+ * describing the method used shall be inserted in or added to De-identification
+ * Method (0012,0063)." This package writes both halves: the text on
+ * `(0012,0063)` and these codes on `(0012,0064)`.
+ *
+ * **A cited constant, not a vendored PS3.16 plus a generator.** The context group
+ * is thirteen rows and its version, `20170914`, is unchanged between the PS3.15
+ * 2026d edition this package vendors and the PS3.16 2026d page these rows are
+ * quoted from (Type Extensible, UID `1.2.840.10008.6.1.925`, every row
+ * designator `DCM`). The "Option" suffix is part of each Code Meaning.
+ *
+ * Two rows are carried and **never written**: `113101` Clean Pixel Data Option and
+ * `113102` Clean Recognizable Visual Features Option. This is a metadata-only
+ * de-identifier and cannot inspect pixels, which is why neither is a
+ * {@link DeidentifyOption}.
+ *
+ * @module
+ */
+
+/**
+ * One row of PS3.16 CID 7050 "De-identification Method": the three Basic Coded
+ * Entry Attributes (PS3.3 2026d Table 8.8-1a) of one code, exactly as the context
+ * group spells them.
+ *
+ * `deidentify()` writes each code it records as one Item of
+ * `(0012,0064)` De-identification Method Code Sequence carrying Code Value
+ * `(0008,0100)`, Coding Scheme Designator `(0008,0102)` and Code Meaning
+ * `(0008,0104)`, and nothing else. Coding Scheme Version is omitted because PS3.3
+ * requires it only where the designator is not sufficient to identify the code,
+ * and `DCM` is.
+ *
+ * @example
+ * ```ts
+ * import { DEIDENTIFICATION_METHOD_CODES, type DeidentificationMethodCode } from "@cosyte/dicom";
+ * const profile: DeidentificationMethodCode = DEIDENTIFICATION_METHOD_CODES.profile;
+ * profile.codeValue; // "113100"
+ * ```
+ */
+interface DeidentificationMethodCode {
+    /** Code Value `(0008,0100)`, a VR `SH` value. */
+    readonly codeValue: string;
+    /** Coding Scheme Designator `(0008,0102)`. Every CID 7050 row is `DCM`. */
+    readonly codingSchemeDesignator: "DCM";
+    /** Code Meaning `(0008,0104)`, a VR `LO` value, spelled as CID 7050 spells it. */
+    readonly codeMeaning: string;
+}
+/**
+ * PS3.16 2026d CID 7050 "De-identification Method" (context group version
+ * `20170914`, UID `1.2.840.10008.6.1.925`), with the code `deidentify()` records
+ * for the Profile and for each {@link DeidentifyOption}.
+ *
+ * - `rows` - all thirteen rows, in the context group's own order.
+ * - `profile` - `113100` Basic Application Confidentiality Profile, written by
+ *   every run.
+ * - `options` - the code written when that Option was active for the run. An
+ *   Option "ran" when it was active: the Annex E column it selects is resolved
+ *   off the option set, whether or not the object carried an attribute it acts
+ *   on. `113107` therefore says the modified-dates column was resolved, **not**
+ *   that any date was shifted; this library transforms no date, and every such
+ *   run carries `DICOM_DEIDENT_DATES_NOT_TRANSFORMED` on `report.warnings`.
+ *
+ * `113101` and `113102` are in `rows` and are never written: they name the two
+ * pixel-level Options, which this metadata-only layer does not perform.
+ *
+ * @example
+ * ```ts
+ * import { DEIDENTIFICATION_METHOD_CODES } from "@cosyte/dicom";
+ * DEIDENTIFICATION_METHOD_CODES.contextGroupUid; // "1.2.840.10008.6.1.925"
+ * DEIDENTIFICATION_METHOD_CODES.options.RetainUIDs.codeValue; // "113110"
+ * DEIDENTIFICATION_METHOD_CODES.rows.length; // 13
+ * ```
+ */
+declare const DEIDENTIFICATION_METHOD_CODES: {
+    readonly contextGroupUid: "1.2.840.10008.6.1.925";
+    readonly contextGroupVersion: "20170914";
+    readonly rows: readonly DeidentificationMethodCode[];
+    readonly profile: DeidentificationMethodCode;
+    readonly options: Readonly<Record<DeidentifyOption, DeidentificationMethodCode>>;
+};
+
+export { type AppliedAction, CODING_SCHEME_OIDS, type CodedConcept, DEFAULT_UID_ROOT, DEIDENTIFICATION_METHOD_CODES, DEIDENTIFY_ERROR_CODES, DEIDENTIFY_OPTIONS, Dataset, type DateParts, type DefineProfileOptions, type DeidentificationMethodCode, type DeidentifiedAttribute, DeidentifyError, type DeidentifyErrorCode, type DeidentifyOption, type DeidentifyOptions, type DeidentifyReport, type DeidentifyResult, type DicomDate, type DicomDateTime, type DicomDirectory, DicomParseError, type DicomParseWarning, type DicomPosition, DicomSerializeError, type DicomTime, type DicomValue, DicomValueError, index as Dictionary, type DirectoryRecord, Element, type EmbeddedAttributeFinding, FATAL_CODES, type FatalCode, type FileMeta, type FileMetaDroppedElement, type FileMetaRawElement, type FrameFunctionalGroups, type Group0004Removal, type ImageView, Item, OFFSET_FRAMES, type OffsetFrame, type OnWarningCallback, type OtherPatientId, type ParseOptions, type PatientView, type PersonName, type PersonNameGroup, type PixelDataFragments, type PrivateTagDefinition, type Profile, ProfileDefinitionError, type ProfilePrivateTags, type RealWorldValueMap, SERIALIZE_ERROR_CODES, Sequence, type SerializeErrorCode, type SeriesView, type StudyView, type ToDateOptions, type UidRemapper, type UnauditableSequenceFinding, type UndefinedVrFinding, type UnenumerablePrivateRemoval, type UnregisteredElementRemoval, 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, readPixelDataFragments, resolveDecoderLabel, serializeDicom, toDate, toISO, toObject };