@cosyte/dicom 0.0.13 → 0.0.15

package/dist/index.d.cts

@@ -114,6 +114,18 @@ interface UidEntry {
  * throw `TypeError` in strict mode (which all of `@cosyte/dicom`'s emitted code
  * runs under, given `"use strict"` is implicit for ES modules).
  *
+ * @example
+ * ```ts
+ * import { Dictionary } from "@cosyte/dicom";
+ *
+ * // Tag or keyword, either way round, and `undefined` rather than a throw on a miss.
+ * Dictionary.lookup("00100020")?.name; // "Patient ID"
+ * Dictionary.byKeyword("Modality")?.tag; // "00080060"
+ *
+ * // UIDs resolve to their registered name, so nobody hard-codes a SOP Class table.
+ * Dictionary.uid("1.2.840.10008.5.1.4.1.1.2")?.name; // "CT Image Storage"
+ * ```
+ *
  * @module
  */
 
@@ -317,8 +329,31 @@ interface ParseOptions {
      *
      * 🛑 **THE ESCALATED DIAGNOSTIC CARRIES SOURCE BYTES THAT THE WARNING DOES
      * NOT.** A `DicomParseWarning.message` is a frozen registry string with only
-     * structural tokens filled in, so it is safe to log whole; the
-     * `DicomParseError` this option raises in its place also carries `snippet`,
+     * structural tokens filled in: `{tag}` renders only a tag PS3.6's element
+     * registry carries a literal row for, `{vr}` only one of the 34 VRs PS3.5
+     * section 6.2 defines, and a raw length or byte value a header carries is
+     * bound out of the factory signature rather than rendered. That now holds on
+     * the `deidentify()` codes too:
+     * `DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE` and
+     * `DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE` rendered `Element.rawBytes.length`
+     * through `0.0.14`, which equals the declared Value Length and was reachable
+     * from a fabricated header, and both slots are gone. So is
+     * `DICOM_ITEM_CROSSES_SEQUENCE_END`'s remaining-bytes count, because **a raw
+     * number shifted by a constant the reader can compute is that raw number**: it
+     * was the enclosing sequence's declared Value Length less the bytes of that
+     * sequence already consumed. **The exceptions are named in one place that is
+     * not a record of a past change, and are deliberately not restated here** -
+     * the `WARNING_MESSAGES` docblock in `./warnings.ts`, which this JSDoc used to
+     * carry a copy of.
+     * **This is a statement about `w.message` and about nothing else**: the two
+     * byte counts still exist on `report.undefinedVrElements[].byteLength` and
+     * `report.unauditableSequences[].byteLength`, model fields on a type whose own
+     * docs say it is not a value-free surface. **No
+     * safe-to-log verdict is stated here** - that sentence was corrected twice and
+     * is deleted rather than tried a third time; the mechanism is above and the
+     * 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`.
      * A message-only PHI review of the lenient path therefore does not transfer to
      * the strict one. Log `err.code`, `err.byteOffset` and `err.message`; treat
@@ -921,6 +956,21 @@ declare class Element {
  * `(0002,0102)` Private Information - is captured here as raw bytes (the
  * 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.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom } from "@cosyte/dicom";
+ * const ds = parseDicom(buf);
+ * // Anything the typed FileMeta fields do not model, in ascending tag order.
+ * for (const raw of ds.fileMeta?.extraElements ?? []) {
+ *   raw.tag; // e.g. "00020017" Sending Application Entity Title
+ *   raw.vr; // the VR the source wrote (File Meta is always Explicit VR LE)
+ *   raw.value.length; // even, per PS3.5 2026c section 7.1.1
+ * }
+ * ```
+ *
+ * `(0002,0016)` Source Application Entity Title is deliberately NOT the example: it is one of the
+ * typed fields, so it never reaches this array.
  */
 interface FileMetaRawElement {
     /** 8-char uppercase hex tag, e.g. `"00020100"`. */
@@ -2448,15 +2498,29 @@ interface DeidentifiedAttribute {
  * (PS3.15 §E.1 "all instances"; §E.3.5 is the standard's own precedent for
  * removing identifying information embedded inside a string attribute).
  *
- * `tag` and `vr` are the carrier's own and are structural. **`hidden` is not,
- * and calling this finding "safe to log" was wrong.** Each entry is composed
- * from four bytes that were sitting *inside* the carrier's value - that is the
- * whole reason the field exists - so on any file that populates it those bytes
- * are document content. Measured: a `CS` carrier over-declaring over the bytes
- * `"SABC"` reports `hidden: ["41534342"]`, which is `"SABC"` in wire order.
- * `PRE-EXISTING` and identical on every release that has shipped the field.
- * Treat `hidden` at the sensitivity of the file, and see
- * {@link DeidentifyReport} for the other fields in this class.
+ * `tag` and `vr` are the carrier's own and are structural. **`hidden` was not,
+ * and it is bound now.** Every tag in an embedded run is composed from four
+ * bytes that were sitting *inside* the carrier's value - that is the whole
+ * reason this type exists - and a run needs only ONE actionable attribute to be
+ * reported, so through `0.0.13` the rest of the run was listed beside it.
+ * Measured: a `CS` carrier over-declaring across a fabricated `"SMIT"` header
+ * 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
+ * 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
+ * document byte, the same trade rendering a VR makes with the 34. **A
+ * repeating-group mask hit is NOT in that set and is excluded**: `(50xx,xxxx)`
+ * Curve Data leaves the whole 16-bit element number free, so a mask match proves
+ * a rule exists without making the membership finite. A graded pass caught a
+ * draft of this filter that admitted it.
+ *
+ * **🛑 THAT IS NOT AN ALL-CLEAR OVER THIS TYPE.** `contextPath` below is
+ * unbound and unchanged, `hidden` is uncapped, and
+ * {@link DeidentifyReport} names the report's other value-bearing fields. A
+ * `DeidentifyReport` is still not safe to log whole.
  *
  * @example
  * ```ts
@@ -2472,7 +2536,18 @@ interface EmbeddedAttributeFinding {
     readonly tag: Tag;
     /** The carrier's VR. Always one of the string VRs; binary VRs are not scanned. */
     readonly vr: VR;
-    /** The tags of the Data Elements found inside the carrier's value, in wire order. */
+    /**
+     * The tags found inside the carrier's value **that this run acts on and that a
+     * published table names**, in wire order. **Not every tag in the run** - see
+     * this type's own remarks.
+     *
+     * **🩺 IT MAY BE EMPTY, AND EMPTY DOES NOT MEAN "NOTHING WAS HIDDEN HERE".**
+     * A run whose only actionable members are private attributes, Curve Data or
+     * Overlay elements reports a finding with no tags: the carrier was still
+     * emptied, and the accompanying `DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED`
+     * warning still counts the whole run. The presence of the finding is the fact;
+     * this list is the part of it that can be named.
+     */
     readonly hidden: readonly Tag[];
     /**
      * Tag/index chain when the carrier is inside a sequence item; omitted at the
@@ -2649,12 +2724,21 @@ interface UndefinedVrFinding {
      *
      * **An input-derived count, and on this finding specifically that is not a
      * formality.** For the sibling findings the length came from a header the
-     * sender wrote; here the two length bytes can themselves be value bytes, like
-     * the tag bytes. What is published is the *number* they decode to, never the
-     * bytes - the same footing as every `{n}` in the warning registry, which is
-     * documented there as "an input-derived count". A number is not a rendering,
-     * and the reach is at most a character or so, but do not describe this field
-     * as "structural, never a value" the way its siblings are described.
+     * sender wrote; here the four length bytes can themselves be value bytes, like
+     * the tag bytes. What is published is the *number* they decode to, and one
+     * `readUInt32LE` puts the bytes back: a fabricated header reading `"SO\0\0"`
+     * publishes `20307`, two letters of a surname. Do not describe this field as
+     * "structural, never a value" the way its siblings are described.
+     *
+     * **🩺 IT IS NO LONGER "the same footing as every `{n}` in the warning
+     * registry", AND THAT SENTENCE WAS THE ONE THIS FIELD SHIPPED WITH.**
+     * `DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE` rendered exactly this number and
+     * does not any more - it is bound out of `undefinedVrNotAuditable`'s
+     * signature. So this field is now a **model field**, on the same standing
+     * exception as `removedPrivateTags`, `unauditableSequences[].tag`, `uidMap`
+     * and `contextPath`: narrowing it is a product call, because a bound empties
+     * it on every well-formed file, where it is exactly the audit number the field
+     * exists to carry. Deliberately unchanged; see this type's own summary.
      */
     readonly byteLength: number;
     /**
@@ -2697,13 +2781,18 @@ interface UndefinedVrFinding {
  *   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.
- * - **`embeddedAttributes[].hidden`** - see {@link EmbeddedAttributeFinding}.
- *   Each entry is a tag composed from four bytes that were sitting **inside**
- *   a value, which is the position this type exists to distrust, so on a file
- *   that populates the field at all they are document content by
- *   construction. `PRE-EXISTING` and identical on every release that has
- *   shipped the field; it is disclosed here and its remedy is its own slice,
- *   alongside the cap that field is also missing.
+ * - **`undefinedVrElements[].byteLength` and
+ *   `unauditableSequences[].byteLength`** - the declared Value Length read off
+ *   the element header, so on a fabricated header it is four document bytes
+ *   wearing a decimal: `"SO\0\0"` publishes `20307`, two letters of a surname,
+ *   put back with one `readUInt32LE`. **They JOINED this list rather than
+ *   always having been on it.** Through `0.0.14` the two
+ *   `DICOM_DEIDENT_*_NOT_AUDITABLE` **messages** rendered the same number;
+ *   binding it out of those factory signatures left these model fields as its
+ *   only publisher, which is a smaller surface and not a closed one. Narrowing
+ *   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
  *   {@link DeidentifiedAttribute.contextPath}, which holds the measurement. The
  *   segment tags come off the wire with no table behind them, so a fabricated
@@ -2714,8 +2803,18 @@ interface UndefinedVrFinding {
  *   same file the de-identified object itself re-emits the fabricated header, so
  *   redacting this field does not make the object safe.**
  *
+ * `embeddedAttributes[].hidden` **left that list** in
+ * `DICOM-DIAGNOSTIC-PHI-RESIDUALS` - an entry is now a literal PS3.15 Table
+ * E.1-1 row, so it is not value-bearing. Its own disclosure had been reworded
+ * twice by then, and this repo deletes a disclosure at that point rather than
+ * writing a third; what is true of the field is stated once, on
+ * {@link EmbeddedAttributeFinding}. The field is **still uncapped**.
+ *
  * So "the report is safe to log apart from `uidMap`" is **not** an accurate
  * description of this type, and was corrected rather than kept convenient.
+ * **This is the only copy of that list.** Two others lived in module docstrings,
+ * still naming `hidden` after it left and never naming `contextPath` at all; a
+ * graded pass found them and they were deleted rather than resynced.
  *
  * @example
  * ```ts
@@ -2994,9 +3093,8 @@ declare class DeidentifyError extends Error {
  * action map ({@link annexE}). It is a **pure** function: the input {@link Dataset}
  * is never mutated; a fresh `Dataset` (with a rebuilt element map and File Meta)
  * is returned alongside a {@link DeidentifyReport} whose non-value-free fields
- * are named on that type: `uidMap`, `removedPrivateTags`,
- * `unauditableSequences[].tag` and `embeddedAttributes[].hidden`. Read the list
- * there, never a count quoted elsewhere.
+ * are named on that type. **The list is deliberately not copied here** - see
+ * `./index.ts` for what a third copy of it cost.
  *
  * **What it does**
  * - Resolves each attribute's action (basic profile, overridden by an active

package/dist/index.d.ts

@@ -114,6 +114,18 @@ interface UidEntry {
  * throw `TypeError` in strict mode (which all of `@cosyte/dicom`'s emitted code
  * runs under, given `"use strict"` is implicit for ES modules).
  *
+ * @example
+ * ```ts
+ * import { Dictionary } from "@cosyte/dicom";
+ *
+ * // Tag or keyword, either way round, and `undefined` rather than a throw on a miss.
+ * Dictionary.lookup("00100020")?.name; // "Patient ID"
+ * Dictionary.byKeyword("Modality")?.tag; // "00080060"
+ *
+ * // UIDs resolve to their registered name, so nobody hard-codes a SOP Class table.
+ * Dictionary.uid("1.2.840.10008.5.1.4.1.1.2")?.name; // "CT Image Storage"
+ * ```
+ *
  * @module
  */
 
@@ -317,8 +329,31 @@ interface ParseOptions {
      *
      * 🛑 **THE ESCALATED DIAGNOSTIC CARRIES SOURCE BYTES THAT THE WARNING DOES
      * NOT.** A `DicomParseWarning.message` is a frozen registry string with only
-     * structural tokens filled in, so it is safe to log whole; the
-     * `DicomParseError` this option raises in its place also carries `snippet`,
+     * structural tokens filled in: `{tag}` renders only a tag PS3.6's element
+     * registry carries a literal row for, `{vr}` only one of the 34 VRs PS3.5
+     * section 6.2 defines, and a raw length or byte value a header carries is
+     * bound out of the factory signature rather than rendered. That now holds on
+     * the `deidentify()` codes too:
+     * `DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE` and
+     * `DICOM_DEIDENT_SEQUENCE_NOT_AUDITABLE` rendered `Element.rawBytes.length`
+     * through `0.0.14`, which equals the declared Value Length and was reachable
+     * from a fabricated header, and both slots are gone. So is
+     * `DICOM_ITEM_CROSSES_SEQUENCE_END`'s remaining-bytes count, because **a raw
+     * number shifted by a constant the reader can compute is that raw number**: it
+     * was the enclosing sequence's declared Value Length less the bytes of that
+     * sequence already consumed. **The exceptions are named in one place that is
+     * not a record of a past change, and are deliberately not restated here** -
+     * the `WARNING_MESSAGES` docblock in `./warnings.ts`, which this JSDoc used to
+     * carry a copy of.
+     * **This is a statement about `w.message` and about nothing else**: the two
+     * byte counts still exist on `report.undefinedVrElements[].byteLength` and
+     * `report.unauditableSequences[].byteLength`, model fields on a type whose own
+     * docs say it is not a value-free surface. **No
+     * safe-to-log verdict is stated here** - that sentence was corrected twice and
+     * is deleted rather than tried a third time; the mechanism is above and the
+     * 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`.
      * A message-only PHI review of the lenient path therefore does not transfer to
      * the strict one. Log `err.code`, `err.byteOffset` and `err.message`; treat
@@ -921,6 +956,21 @@ declare class Element {
  * `(0002,0102)` Private Information - is captured here as raw bytes (the
  * 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.
+ *
+ * @example
+ * ```ts
+ * import { parseDicom } from "@cosyte/dicom";
+ * const ds = parseDicom(buf);
+ * // Anything the typed FileMeta fields do not model, in ascending tag order.
+ * for (const raw of ds.fileMeta?.extraElements ?? []) {
+ *   raw.tag; // e.g. "00020017" Sending Application Entity Title
+ *   raw.vr; // the VR the source wrote (File Meta is always Explicit VR LE)
+ *   raw.value.length; // even, per PS3.5 2026c section 7.1.1
+ * }
+ * ```
+ *
+ * `(0002,0016)` Source Application Entity Title is deliberately NOT the example: it is one of the
+ * typed fields, so it never reaches this array.
  */
 interface FileMetaRawElement {
     /** 8-char uppercase hex tag, e.g. `"00020100"`. */
@@ -2448,15 +2498,29 @@ interface DeidentifiedAttribute {
  * (PS3.15 §E.1 "all instances"; §E.3.5 is the standard's own precedent for
  * removing identifying information embedded inside a string attribute).
  *
- * `tag` and `vr` are the carrier's own and are structural. **`hidden` is not,
- * and calling this finding "safe to log" was wrong.** Each entry is composed
- * from four bytes that were sitting *inside* the carrier's value - that is the
- * whole reason the field exists - so on any file that populates it those bytes
- * are document content. Measured: a `CS` carrier over-declaring over the bytes
- * `"SABC"` reports `hidden: ["41534342"]`, which is `"SABC"` in wire order.
- * `PRE-EXISTING` and identical on every release that has shipped the field.
- * Treat `hidden` at the sensitivity of the file, and see
- * {@link DeidentifyReport} for the other fields in this class.
+ * `tag` and `vr` are the carrier's own and are structural. **`hidden` was not,
+ * and it is bound now.** Every tag in an embedded run is composed from four
+ * bytes that were sitting *inside* the carrier's value - that is the whole
+ * reason this type exists - and a run needs only ONE actionable attribute to be
+ * reported, so through `0.0.13` the rest of the run was listed beside it.
+ * Measured: a `CS` carrier over-declaring across a fabricated `"SMIT"` header
+ * 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
+ * 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
+ * document byte, the same trade rendering a VR makes with the 34. **A
+ * repeating-group mask hit is NOT in that set and is excluded**: `(50xx,xxxx)`
+ * Curve Data leaves the whole 16-bit element number free, so a mask match proves
+ * a rule exists without making the membership finite. A graded pass caught a
+ * draft of this filter that admitted it.
+ *
+ * **🛑 THAT IS NOT AN ALL-CLEAR OVER THIS TYPE.** `contextPath` below is
+ * unbound and unchanged, `hidden` is uncapped, and
+ * {@link DeidentifyReport} names the report's other value-bearing fields. A
+ * `DeidentifyReport` is still not safe to log whole.
  *
  * @example
  * ```ts
@@ -2472,7 +2536,18 @@ interface EmbeddedAttributeFinding {
     readonly tag: Tag;
     /** The carrier's VR. Always one of the string VRs; binary VRs are not scanned. */
     readonly vr: VR;
-    /** The tags of the Data Elements found inside the carrier's value, in wire order. */
+    /**
+     * The tags found inside the carrier's value **that this run acts on and that a
+     * published table names**, in wire order. **Not every tag in the run** - see
+     * this type's own remarks.
+     *
+     * **🩺 IT MAY BE EMPTY, AND EMPTY DOES NOT MEAN "NOTHING WAS HIDDEN HERE".**
+     * A run whose only actionable members are private attributes, Curve Data or
+     * Overlay elements reports a finding with no tags: the carrier was still
+     * emptied, and the accompanying `DICOM_DEIDENT_EMBEDDED_ATTRIBUTE_REMOVED`
+     * warning still counts the whole run. The presence of the finding is the fact;
+     * this list is the part of it that can be named.
+     */
     readonly hidden: readonly Tag[];
     /**
      * Tag/index chain when the carrier is inside a sequence item; omitted at the
@@ -2649,12 +2724,21 @@ interface UndefinedVrFinding {
      *
      * **An input-derived count, and on this finding specifically that is not a
      * formality.** For the sibling findings the length came from a header the
-     * sender wrote; here the two length bytes can themselves be value bytes, like
-     * the tag bytes. What is published is the *number* they decode to, never the
-     * bytes - the same footing as every `{n}` in the warning registry, which is
-     * documented there as "an input-derived count". A number is not a rendering,
-     * and the reach is at most a character or so, but do not describe this field
-     * as "structural, never a value" the way its siblings are described.
+     * sender wrote; here the four length bytes can themselves be value bytes, like
+     * the tag bytes. What is published is the *number* they decode to, and one
+     * `readUInt32LE` puts the bytes back: a fabricated header reading `"SO\0\0"`
+     * publishes `20307`, two letters of a surname. Do not describe this field as
+     * "structural, never a value" the way its siblings are described.
+     *
+     * **🩺 IT IS NO LONGER "the same footing as every `{n}` in the warning
+     * registry", AND THAT SENTENCE WAS THE ONE THIS FIELD SHIPPED WITH.**
+     * `DICOM_DEIDENT_UNDEFINED_VR_NOT_AUDITABLE` rendered exactly this number and
+     * does not any more - it is bound out of `undefinedVrNotAuditable`'s
+     * signature. So this field is now a **model field**, on the same standing
+     * exception as `removedPrivateTags`, `unauditableSequences[].tag`, `uidMap`
+     * and `contextPath`: narrowing it is a product call, because a bound empties
+     * it on every well-formed file, where it is exactly the audit number the field
+     * exists to carry. Deliberately unchanged; see this type's own summary.
      */
     readonly byteLength: number;
     /**
@@ -2697,13 +2781,18 @@ interface UndefinedVrFinding {
  *   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.
- * - **`embeddedAttributes[].hidden`** - see {@link EmbeddedAttributeFinding}.
- *   Each entry is a tag composed from four bytes that were sitting **inside**
- *   a value, which is the position this type exists to distrust, so on a file
- *   that populates the field at all they are document content by
- *   construction. `PRE-EXISTING` and identical on every release that has
- *   shipped the field; it is disclosed here and its remedy is its own slice,
- *   alongside the cap that field is also missing.
+ * - **`undefinedVrElements[].byteLength` and
+ *   `unauditableSequences[].byteLength`** - the declared Value Length read off
+ *   the element header, so on a fabricated header it is four document bytes
+ *   wearing a decimal: `"SO\0\0"` publishes `20307`, two letters of a surname,
+ *   put back with one `readUInt32LE`. **They JOINED this list rather than
+ *   always having been on it.** Through `0.0.14` the two
+ *   `DICOM_DEIDENT_*_NOT_AUDITABLE` **messages** rendered the same number;
+ *   binding it out of those factory signatures left these model fields as its
+ *   only publisher, which is a smaller surface and not a closed one. Narrowing
+ *   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
  *   {@link DeidentifiedAttribute.contextPath}, which holds the measurement. The
  *   segment tags come off the wire with no table behind them, so a fabricated
@@ -2714,8 +2803,18 @@ interface UndefinedVrFinding {
  *   same file the de-identified object itself re-emits the fabricated header, so
  *   redacting this field does not make the object safe.**
  *
+ * `embeddedAttributes[].hidden` **left that list** in
+ * `DICOM-DIAGNOSTIC-PHI-RESIDUALS` - an entry is now a literal PS3.15 Table
+ * E.1-1 row, so it is not value-bearing. Its own disclosure had been reworded
+ * twice by then, and this repo deletes a disclosure at that point rather than
+ * writing a third; what is true of the field is stated once, on
+ * {@link EmbeddedAttributeFinding}. The field is **still uncapped**.
+ *
  * So "the report is safe to log apart from `uidMap`" is **not** an accurate
  * description of this type, and was corrected rather than kept convenient.
+ * **This is the only copy of that list.** Two others lived in module docstrings,
+ * still naming `hidden` after it left and never naming `contextPath` at all; a
+ * graded pass found them and they were deleted rather than resynced.
  *
  * @example
  * ```ts
@@ -2994,9 +3093,8 @@ declare class DeidentifyError extends Error {
  * action map ({@link annexE}). It is a **pure** function: the input {@link Dataset}
  * is never mutated; a fresh `Dataset` (with a rebuilt element map and File Meta)
  * is returned alongside a {@link DeidentifyReport} whose non-value-free fields
- * are named on that type: `uidMap`, `removedPrivateTags`,
- * `unauditableSequences[].tag` and `embeddedAttributes[].hidden`. Read the list
- * there, never a count quoted elsewhere.
+ * are named on that type. **The list is deliberately not copied here** - see
+ * `./index.ts` for what a third copy of it cost.
  *
  * **What it does**
  * - Resolves each attribute's action (basic profile, overridden by an active